One document matched: draft-ietf-netconf-4741bis-04.xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt"?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd"[
<!ENTITY rfc2119 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml'>
<!ENTITY rfc2865 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.2865.xml'>
<!ENTITY rfc3470 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3470.xml'>
<!ENTITY rfc3553 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3553.xml'>
<!ENTITY rfc3688 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3688.xml'>
<!ENTITY rfc3986 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.3986.xml'>
<!ENTITY rfc4346 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4346.xml'>
<!ENTITY rfc4741 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4741.xml'>
<!ENTITY rfc4742 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4742.xml'>
<!ENTITY rfc4251 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.4251.xml'>
<!ENTITY rfc5717 PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml/reference.RFC.5717.xml'>
<!ENTITY xml PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xml-20001006'>
<!ENTITY xpath PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xpath-19991116'>
<!ENTITY xslt PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml4/reference.W3C.REC-xslt-19991116'>
<!ENTITY draft-yang PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netmod-yang.xml'>
<!ENTITY draft-yang-types PUBLIC '' 'http://xml.resource.org/public/rfc/bibxml3/reference.I-D.ietf-netmod-yang-types.xml'>
]>
<?rfc toc="yes"?>
<?rfc symrefs="no"?>
<rfc ipr="pre5378Trust200902" category="std" docName="draft-ietf-netconf-4741bis-04">
<front>
<title abbrev="NETCONF Protocol">Network Configuration Protocol (NETCONF)</title>
<author initials="R." surname="Enns" fullname="Rob Enns" role="editor">
<organization>Juniper Networks</organization>
<address>
<postal>
<street>1194 North Mathilda Ave</street>
<city>Sunnyvale</city>
<region>CA</region>
<code>94089</code>
<country>US</country>
</postal>
<email>rpe@juniper.net</email>
</address>
</author>
<author initials="M." surname="Bjorklund" fullname="Martin Bjorklund" role="editor">
<organization>Tail-f Systems</organization>
<address>
<email>mbj@tail-f.com</email>
</address>
</author>
<author initials="J." surname="Schoenwaelder" fullname="Juergen Schoenwaelder" role="editor">
<organization>Jacobs University</organization>
<address>
<email>j.schoenwaelder@jacobs-university.de</email>
</address>
</author>
<author initials="A." surname="Bierman" fullname="Andy Bierman" role="editor">
<organization>Brocade</organization>
<address>
<email>andy.bierman@brocade.com</email>
</address>
</author>
<date/>
<area>Operations</area>
<keyword>XML</keyword>
<keyword>Configuration</keyword>
<keyword>Network Management</keyword>
<keyword>Extensible Markup Language</keyword>
<abstract>
<t>
The Network Configuration Protocol (NETCONF) defined in this document
provides mechanisms to install, manipulate, and delete the
configuration of network devices. It uses an Extensible Markup
Language (XML)-based data encoding for the configuration data as well
as the protocol messages. The NETCONF protocol operations are realized
as Remote Procedure Calls (RPC).
</t>
</abstract>
</front>
<middle>
<section title="Introduction">
<t>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.
</t>
<t>
The NETCONF protocol uses a remote procedure call (RPC) paradigm.
A client encodes an RPC in XML
<xref target="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.
</t>
<t>
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.
</t>
<t>
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 <xref target="capabilities" />.
</t>
<t>
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 <xref target="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.
</t>
<t>
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
<xref target="RFC2119">RFC 2119</xref>.
</t>
<section title="Terminology">
<t>
<list style="symbols">
<t>
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
may support a candidate configuration datastore.
</t>
<t>
capability: A functionality that supplements the base
NETCONF specification.
</t>
<t>
client: A client invokes protocol operations on a
server. In addition, a client may subscribe to receive
notifications from a server.
</t>
<t>
configuration 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.
</t>
<t>
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.
</t>
<t>
configuration datastore: A configuration datastore is
defined as 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.
</t>
<t>
message: A protocol element sent over a session.
Messages are well-formed XML documents.
</t>
<t>
notification: A server initiated message indicating that
a certain event has been recognized by the server.
</t>
<t>
protocol operation: A specific remote procedure call, as
used within the NETCONF protocol.
</t>
<t>
remote procedure call: A remote procedure call (RPC),
realized by exchanging <rpc> and <rpc-reply>
messages.
</t>
<t>
running configuration datastore: A configuration
datastore holding the complete configuration currently
active on the device. The running configuration
datastore always exists.
</t>
<t>
server: A server executes protocol operations invoked by
a client. In addition, a server may send notifications
to a client.
</t>
<t>
session: Client and server exchange messages using a
secure, connection-oriented session.
</t>
<t>
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.
</t>
<t>
state data: State data is the additional data on a
system that is not configuration data such as read-only
status information and collected statistics.
</t>
<t>
user: The authenticated identity of the client. The
authenticated identity of a client is commonly referred
to as the NETCONF username.
</t>
</list>
</t>
</section>
<section title="Protocol Overview">
<t>
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".
</t>
<t>
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.
</t>
<t>
NETCONF can be conceptually partitioned into four layers as
shown in <xref target="layers"/>.
</t>
<figure anchor="layers" title="NETCONF Protocol Layers">
<artwork><![CDATA[
Layer Example
+-------------+ +-----------------+ +----------------+
(4) | Content | | Configuration | | Notification |
| | | data | | data |
+-------------+ +-----------------+ +----------------+
| | |
+-------------+ +-----------------+ |
(3) | Operations | | <edit-config> | |
| | | | |
+-------------+ +-----------------+ |
| | |
+-------------+ +-----------------+ +----------------+
(2) | Messages | | <rpc>, | | <notification> |
| | | <rpc-reply> | | |
+-------------+ +-----------------+ +----------------+
| | |
+-------------+ +-----------------------------------------+
(1) | Secure | | SSH, TLS, BEEP/TLS, SOAP/HTTP/TLS, ... |
| Transports | | |
+-------------+ +-----------------------------------------+
]]></artwork>
</figure>
<t>
<list style="numbers">
<t>
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. <xref target="transportRequirements"/>
discusses these requirements.
</t>
<t>
The Messages layer provides a simple,
transport-independent framing mechanism for encoding
RPCs and notifications. <xref target="rpcModel" />
documents the RPC messages, and <xref target="RFC5717"/>
documents notifications.
</t>
<t>
The Operations layer defines a set of base protocol
operations invoked as RPC methods with XML-encoded
parameters. <xref target="protocolOperations" /> details
the list of base protocol operations.
</t>
<t>
The Content layer is outside the scope of this
document. It is expected that separate efforts to
standardize NETCONF data models will be undertaken.
</t>
</list>
</t>
<t>
The YANG data modeling language
<xref target="I-D.ietf-netmod-yang"/> has been developed for
specifying NETCONF data models and protocol operations,
covering the Operations and the Content layers of
<xref target="layers"/>.
</t>
</section>
<section title="Capabilities">
<t>
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 <xref target="capabilities" />.
</t>
<t>
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.
</t>
<t>
The capability definition may name one or more dependent capabilities.
To support a capability, the server
MUST support any capabilities upon which it depends.
</t>
<t>
<xref target="capabilities" /> defines the capabilities exchange that allows
the client to discover the server's capabilities.
<xref target="capabilities" /> also lists
the set of capabilities defined in this document.
</t>
<t>
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.
</t>
</section>
<section title="Separation of Configuration and State Data" anchor="state">
<t>
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:
<list style="symbols">
<t>Comparisons of configuration data sets would be dominated by irrelevant
entries such as different statistics.</t>
<t>Incoming data could contain nonsensical
requests, such as attempts to write read-only data.</t>
<t>The data sets would be large.</t>
<t>Archived data could contain values for read-only data
items, complicating the processing required to restore
archived data.
</t>
</list>
</t>
<t>
To account for these issues, the NETCONF protocol recognizes the difference
between configuration data and state data and provides
operations for
each. The <get‑config> operation
retrieves configuration data only, while the <get> operation
retrieves configuration and state data.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
</section>
<section title="Transport Protocol Requirements" anchor="transportRequirements">
<t>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.
</t>
<t>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.
</t>
<t>
The transport protocol MUST provide a mechanism to indicate the
session type (client or server) to the NETCONF protocol layer.
</t>
<t>
This section details the characteristics that NETCONF requires
from the underlying transport protocol.
</t>
<section title="Connection-Oriented Operation">
<t>NETCONF is connection-oriented, requiring a persistent
connection between peers. This connection must provide
reliable, sequenced data delivery.
</t>
<t>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.
</t>
<t> 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 <xref target="lock" />.
</t>
</section>
<section title="Authentication, Integrity, and Confidentiality">
<t>
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 may be encrypted in TLS
<xref target="RFC4346" /> or SSH <xref target="RFC4251" />,
depending on the underlying protocol.
</t>
</section>
<section title="Authentication">
<t>
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.
</t>
<t>
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
<xref target="RFC2865" /> should allow the use of RADIUS to
authenticate NETCONF sessions.
</t>
<t>
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 algorithm used to derive the
username is transport protocol specific and in addition
specific to the authentication mechanism used by the
transport protocol. NETCONF transport protocols therefore
MUST explain how a NETCONF username is derived from the
authentication mechanisms supported by the transport
protocol.
</t>
<t>
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 how access
control is configured is outside the scope of this document.
</t>
</section>
<section title="Mandatory Transport Protocol">
<t>
A NETCONF implementation MUST support the SSH transport
protocol mapping <xref target="RFC4742"/>.
</t>
</section>
</section> <!-- Transport Protocol Requirements -->
<section title="XML Considerations" anchor="xmlConsiderations">
<t>
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.
</t>
<t>
All NETCONF messages MUST be well-formed XML, encoded in UTF-8.
</t>
<t>
A NETCONF message MAY begin with an XML declaration (see
section 2.8 of <xref target="W3C.REC-xml-20001006"/>).
</t>
<t>
This section discusses a small number of XML-related considerations
pertaining to NETCONF.
</t>
<section title="Namespace" anchor="namespace">
<t>
All NETCONF protocol elements are defined in the following namespace:
<list style="empty">
<t>urn:ietf:params:xml:ns:netconf:base:1.0</t>
</list>
</t>
<t>
NETCONF capability names MUST be URIs <xref target="RFC3986" />.
NETCONF capabilities are discussed in <xref target="capabilities" />.
</t>
</section>
<section title="No Document Type Declarations" anchor="nodtd">
<t>
Document type declarations MUST NOT appear in
NETCONF content.
</t>
</section>
</section> <!-- XML Considerations -->
<section title="RPC Model" anchor="rpcModel">
<t>
The NETCONF protocol uses an RPC-based communication
model. NETCONF peers use <rpc> and <rpc‑reply>
elements to provide transport protocol-independent framing of
NETCONF requests and responses.
</t>
<t>
The syntax and XML encoding of the Messages layer RPCs are
formally defined in the XML schema in <xref
target="xsdschema"/>.
</t>
<section title="<rpc> Element">
<t>
The <rpc> element is used to enclose a NETCONF request sent from
the client to the server.
</t>
<t>
The <rpc> 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 <rpc‑reply> message. For example:
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<some-method>
<!-- method parameters here... -->
</some-method>
</rpc>
]]></artwork>
</figure>
<t>
If additional attributes are present in an <rpc>
element, a NETCONF peer MUST return them unmodified in the
<rpc‑reply> element. This includes any "xmlns"
attributes.
</t>
<t>
The name and parameters of an RPC are encoded as the contents
of the <rpc> element. The name of the RPC is an element
directly inside the <rpc> element, and any parameters are
encoded inside this element.
</t>
<t>
The following example invokes a method called <my‑own‑method>,
which has two
parameters, <my‑first‑parameter>, with a value of "14", and
<another‑parameter>, with a value of "fred":
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<my-own-method xmlns="http://example.net/me/my-own/1.0">
<my-first-parameter>14</my-first-parameter>
<another-parameter>fred</another-parameter>
</my-own-method>
</rpc>
]]></artwork>
</figure>
<t>
The following example invokes a <rock‑the‑house> method with a
<zip‑code> parameter of "27606‑0100":
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rock-the-house xmlns="http://example.net/rock/1.0">
<zip-code>27606-0100</zip-code>
</rock-the-house>
</rpc>
]]></artwork>
</figure>
<t>
The following example invokes the NETCONF <get>
method with no parameters:
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get/>
</rpc>
]]></artwork>
</figure>
</section>
<section title="<rpc‑reply> Element">
<t>
The <rpc‑reply> message is sent in response to an <rpc> operation.
</t>
<t>
The <rpc‑reply> element has a mandatory attribute "message‑id",
which is equal to the "message-id" attribute of the <rpc> for
which this is a response.
</t>
<t>
A NETCONF server MUST also return any additional attributes
included in the <rpc> element unmodified in the
<rpc‑reply> element.
</t>
<t>
The response data is encoded as one or more child elements to the
<rpc‑reply> element.</t>
<!--
The response name and response data are encoded as the contents
of the <rpc‑reply> element. The name of the reply is an element
directly inside the <rpc‑reply> element, and any data is encoded
inside this element.
</t>
-->
<t>For example:</t>
<t>The following <rpc> element invokes the NETCONF <get>
method and includes an additional attribute called "user-id".
Note that the "user-id" attribute is not in the NETCONF namespace.
The returned <rpc‑reply> element returns the "user‑id"
attribute, as well as the requested content.</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ex="http://example.net/content/1.0"
ex:user-id="fred">
<get/>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:ex="http://example.net/content/1.0"
ex:user-id="fred">
<data>
<!-- contents here... -->
</data>
</rpc-reply>
]]></artwork>
</figure>
</section>
<section title="<rpc‑error> Element" anchor="rpcError">
<t>
The <rpc‑error> element is sent in
<rpc‑reply> messages if an error occurs during
the processing of an <rpc> request.
</t>
<t>
If a server encounters multiple errors during the processing
of an <rpc> request, the <rpc‑reply> MAY
contain multiple <rpc‑error> elements. However,
a server is not required to detect or report more than one
<rpc‑error> element, if a request contains
multiple errors. A server is not required to check for
particular error conditions in a specific sequence. A
server MUST return an <rpc‑error> element if any
error conditions occur during processing.
</t>
<t>
A server MUST NOT return application-level- or data-model-specific
error information in an <rpc‑error> element for which the
client does not have sufficient access rights.
</t>
<t>
The <rpc‑error> element includes the following
information:
</t>
<t>
<list style="hanging">
<t hangText="error-type:">
Defines the conceptual layer that the error occurred.
Enumeration. One of:
<list style="symbols">
<t>transport (layer: Secure Transport)</t>
<t>rpc (layer: Messages)</t>
<t>protocol (layer: Operations)</t>
<t>application (layer: Content)</t>
</list>
</t>
<t hangText="error-tag:">
Contains a string identifying the error condition.
See <xref target="errorList" /> for allowed values.
</t>
<t hangText="error-severity:">
Contains a string identifying the error severity,
as determined by the device.
One of:
<list style="symbols">
<t>error</t>
<t>warning</t>
</list>
Note that there are no <error-tag> values
defined in this document which utilize the
"warning" enumeration. This is reserved
for future use.
</t>
<t hangText="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 data-model
specific and a implementation-specific error-app-tag
both exist, then the data-model specific value MUST
be used by the server.
</t>
<t hangText="error-path:">
Contains the absolute XPath <xref
target="W3C.REC-xpath-19991116" /> expression
identifying the element path to the node that is
associated with the error being reported in a particular
rpc‑error element. This element will not be
present if no appropriate payload element or data store
node can be associated with a particular error
condition.</t>
<t>
The XPath expression is interpreted in the following context:
<list style="symbols">
<t>The set of namespace declarations are those in
scope on the rpc‑error element.</t>
<t>The set of variable bindings is empty.</t>
<t>The function library is the core function library.</t>
</list>
The context node depends on the node associated with the
error being reported:
<list style="symbols">
<t>If a payload element can be associated with the
error, the context node is the rpc request's document
node (i.e., the "rpc" element).</t>
<t>Otherwise, the context node is the root of all data
models, i.e., the node which has the top-level nodes
from all data models as children.</t>
</list>
</t>
<t hangText="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 <xref target="W3C.REC-xml-20001006" /> and
discussed in <xref target="RFC3470" />.
</t>
<t hangText="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 <xref target="errorList" />
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.
</t>
</list>
</t>
<t>
<xref target="errorList" /> enumerates the standard NETCONF errors.
</t>
<t>
<list style="hanging">
<t hangText="Example:">
<vspace blankLines="1"/>
An error is returned if an <rpc> element is
received without a message-id attribute. Note that only
in this case is it acceptable for the NETCONF peer to
omit the message-id attribute in the
<rpc‑reply> element.
</t>
</list>
</t>
<figure>
<artwork><![CDATA[
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
</get-config>
</rpc>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>rpc</error-type>
<error-tag>missing-attribute</error-tag>
<error-severity>error</error-severity>
<error-info>
<bad-attribute>message-id</bad-attribute>
<bad-element>rpc</bad-element>
</error-info>
</rpc-error>
</rpc-reply>
]]></artwork>
</figure>
<t>
The following <rpc‑reply> illustrates the case
of returning multiple <rpc‑error> elements.
</t>
<t>Note that the data models used in the examples in this section use
the <name> element to distinguish between multiple instances of
the <interface> element.
</t>
<figure>
<artwork><![CDATA[
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-path>
/t:top/t:interface[t:name="Ethernet0/0"]/t:mtu
</error-path>
<error-message xml:lang="en">
MTU value 25000 is not within range 256..9192
</error-message>
</rpc-error>
<rpc-error>
<error-type>application</error-type>
<error-tag>invalid-value</error-tag>
<error-severity>error</error-severity>
<error-path>
/t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name
</error-path>
<error-message xml:lang="en">
Invalid IP address for interface Ethernet1/0
</error-message>
</rpc-error>
</rpc-reply>
]]></artwork>
</figure>
</section>
<section title="<ok> Element" anchor="ok">
<t>
The <ok> element is sent in <rpc‑reply> messages
if no errors or warnings occurred during the processing of an <rpc>
request, and no data was returned from the operation. For example:
<figure>
<artwork><![CDATA[
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Pipelining">
<t>
NETCONF <rpc> requests MUST be processed serially by the managed device.
Additional <rpc> requests MAY be sent before previous ones
have been completed. The managed device MUST send responses only in
the order the requests were received.
</t>
</section>
</section> <!-- RPC Model -->
<section title="Configuration Model">
<t> 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
<xref target="capabilityExchange"/>.
</t>
<section title="Configuration Datastores">
<t>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.
</t>
<t>
Only the <running> configuration datastore is present in the
base model. Additional configuration datastores may be
defined by capabilities. Such configuration datastores
are available only on devices that advertise the
capabilities.
<list style="symbols">
<t>
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
<running> element.
</t>
</list>
</t>
<t>
The capabilities in Sections
<xref target="candidate" format="counter" /> and <xref target="startup" format="counter" />
define the <candidate> and <startup>
configuration datastores, respectively.
</t>
</section>
<section title="Data Modeling">
<t>
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.
</t>
<t>
NETCONF carries configuration data inside the <config> 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.
</t>
<t>
Devices and managers may support multiple data models,
including both standard and proprietary data models.
</t>
</section>
</section> <!-- Configuration Model -->
<section title="Subtree Filtering" anchor="subtree">
<section title="Overview">
<t>
XML subtree filtering is a mechanism that allows an application to
select particular XML subtrees to include in the <rpc‑reply> for a
<get> or <get‑config> operation. A small set of filters for
inclusion, simple content exact-match, and selection is provided,
which allows some useful, but also very limited, selection mechanisms.
The server does not need to utilize any data-model-specific semantics
during processing, allowing for simple and centralized implementation
strategies.
</t>
<t>
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.
</t>
<t>
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' attributes) within the
NETCONF message. If they are specified, the declared namespace MUST
exactly match a namespace supported by the server, with one exception.
A namespace wildcard mechanism is defined in
<xref target="NamespaceSelection"/>.
</t>
<t>
Note that prefix values
for qualified namespaces are not relevant when comparing filter
elements to elements in the underlying data model.
</t>
<t>
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 <filter>.
</t>
<t>
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.
</t>
</section>
<section title="Subtree Filter Components">
<t>
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:
<list style="symbols">
<t>Namespace Selection</t>
<t>Attribute Match Expressions</t>
<t>Containment Nodes</t>
<t>Selection Nodes</t>
<t>Content Match Nodes</t>
</list>
</t>
<section title="Namespace Selection" anchor="NamespaceSelection">
<t>
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 XML namespace associated
with a particular node within the <filter> element is the same
as in the underlying data model.
Note that namespace selection cannot be used by itself.
At least one element must be specified in the filter
any elements to be included in the filter output.
</t>
<t>
An XML namespace wildcard mechanism is defined for subtree
filtering. If an element
within the <filter> element
is not qualified by a namespace (e.g., xmlns=""),
then the server MUST evaluate all the XML namespaces it
supports, when processing that subtree filter node.
This wildcard mechanism is not applicable to XML attributes.
</t>
<t>
Example:
<figure>
<artwork><![CDATA[
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config"/>
</filter>
]]></artwork>
</figure>
</t>
<t>
In this example, the <top> element is a selection
node, and only this node in the
'http://example.com/schema/1.2/config' namespace and any
child nodes (from the underlying data model) will be
included in the filter output.
</t>
</section>
<section title="Attribute Match Expressions" anchor="attribute-match">
<t>
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.
</t>
<t>
Example:
<figure>
<artwork><![CDATA[
<filter type="subtree">
<t:top xmlns:t="http://example.com/schema/1.2/config">
<t:interfaces>
<t:interface t:ifName="eth0"/>
</t:interfaces>
</t:top>
</filter>
]]></artwork>
</figure>
</t>
<t>
In this example, the <top>, and <interfaces>
elements are containment nodes, the <interface>
element is a selection node, and 'ifName' is an attribute
match expression. Only 'interface' nodes in the
'http://example.com/schema/1.2/config' namespace that have
an 'ifName' attribute with the value 'eth0' and occur
within 'interfaces' nodes within 'top' nodes will be
included in the filter output.
</t>
</section>
<section title="Containment Nodes" anchor="containment-nodes">
<t>
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.
</t>
<t>
Example:
<figure>
<artwork><![CDATA[
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users/>
</top>
</filter>
]]></artwork>
</figure>
</t>
<t>
In this example, the <top> element is a containment node.
</t>
</section>
<section title="Selection Nodes">
<t>
An empty leaf node within a filter is called a "selection node",
and it represents an "explicit selection" filter on the underlying
data model. Presence of any selection nodes within a set of sibling
nodes will cause the filter to select the specified subtree(s)
and suppress automatic selection of the entire set of sibling nodes
in the underlying data model. For filtering purposes, an empty
leaf node can be declared either with an empty tag (e.g., <foo/>)
or with explicit start and end tags (e.g., <foo> </foo>). Any
whitespace characters are ignored in this form.
</t>
<t>
Example:
<figure>
<artwork><![CDATA[
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users/>
</top>
</filter>
]]></artwork>
</figure>
</t>
<t>
In this example, the <top> element is a containment node, and
the <users> element is a selection node. Only 'users'
nodes in the
'http://example.com/schema/1.2/config' namespace that occur
within a 'top' element that is the root of the configuration
datastore will be included in the filter output.
</t>
</section>
<section title="Content Match Nodes">
<t>
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:
<list style="symbols">
<t>A content match node must not contain nested elements (i.e.,
must resolve to a simpleType in the XML Schema
Definition (XSD)).</t>
<t>Multiple content match nodes (i.e., sibling nodes) are logically
combined in an "AND" expression.</t>
<t>Filtering of mixed content is not supported.</t>
<t>Filtering of list content is not supported.</t>
<t>Filtering of whitespace-only content is not supported.</t>
<t>A content match node must contain non-whitespace characters.
An empty element (e.g., <foo></foo>) will be interpreted as a
selection node (e.g., <foo/>).</t>
<t>Leading and trailing whitespace characters are ignored, but any
whitespace characters within a block of text characters are not
ignored or modified.</t>
</list>
</t>
<t>
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:
<list style="symbols">
<t>Each content match node in the sibling set is included in
the filter output.</t>
<t>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.</t>
<t>If any selection nodes are present in the sibling set, then all
of them are included in the filter output.</t>
<t>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.</t>
<t>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.</t>
</list>
</t>
<t>
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).
</t>
<t>
Example:
<figure>
<artwork><![CDATA[
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
</user>
</users>
</top>
</filter>
]]></artwork>
</figure>
</t>
<t>
In this example, the <users> and <user> nodes are both containment
nodes, and <name> is a content match node. Since no sibling nodes
of <name> are specified (and therefore no containment or selection
nodes), all of the sibling nodes of <name> are returned in the
filter output. Only 'user' nodes in the 'http://example.com/schema/1.2/config'
namespace that match the element hierarchy and
for which the <name> element is equal to 'fred' will be included in
the filter output.
</t>
</section>
</section>
<section title="Subtree Filter Processing">
<t>
The filter output (the set of selected nodes) is initially empty.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
</section>
<section title="Subtree Filtering Examples">
<section title="No Filter">
<t>
Leaving out the filter on the get operation returns the entire data
model.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get/>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<!-- ... entire set of data returned ... -->
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Empty Filter">
<t>
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.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
</filter>
</get>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Select the Entire <users> Subtree">
<t>
The filter in this example contains one selection node (<users>), so
just that subtree is selected by the filter. This example represents
the fully-populated <users> data model in most of the filter examples
that follow. In a real data model, the <company‑info> would not
likely be returned with the list of users for a particular host or
network.
</t>
<t>
NOTE: The filtering and configuration examples used in this document
appear in the namespace "http://example.com/schema/1.2/config". The
root element of this namespace is <top>. The <top> element
and its descendents represent an example configuration data model only.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users/>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<type>superuser</type>
<full-name>Charlie Root</full-name>
<company-info>
<dept>1</dept>
<id>1</id>
</company-info>
</user>
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
<company-info>
<dept>2</dept>
<id>2</id>
</company-info>
</user>
<user>
<name>barney</name>
<type>admin</type>
<full-name>Barney Rubble</full-name>
<company-info>
<dept>2</dept>
<id>3</id>
</company-info>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
<t>
The following filter request would have produced the same result, but
only because the container <users> defines one child element
(<user>).
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user/>
</users>
</top>
</filter>
</get-config>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="Select All <name> Elements within the <users> Subtree">
<t>
This filter contains two containment nodes (<users>, <user>) and one
selection node (<name>). All instances of the <name> element in the
same sibling set are selected in the filter output. The client may
need to know that <name> is used as an instance identifier in this
particular data structure, but the server does not need to know that
meta-data in order to process the request.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name/>
</user>
</users>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
</user>
<user>
<name>fred</name>
</user>
<user>
<name>barney</name>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="One Specific <user> Entry">
<t>
This filter contains two containment nodes (<users>, <user>) and one
content match node (<name>). All instances of the sibling set
containing <name> for which the value of <name> equals "fred" are
selected in the filter output.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
</user>
</users>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
<company-info>
<dept>2</dept>
<id>2</id>
</company-info>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Specific Elements from a Specific <user> Entry">
<t>
This filter contains two containment nodes (<users>, <user>), one
content match node (<name>), and two selection nodes (<type>,
<full‑name>). All instances of the <type> and <full‑name> elements
in the same sibling set containing <name> for which the value of
<name> equals "fred" are selected in the filter output. The
<company‑info> element is not included because the sibling set
contains selection nodes.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
<type/>
<full-name/>
</user>
</users>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Multiple Subtrees">
<t>
This filter contains three subtrees (name=root, fred, barney).
</t>
<t>
The "root" subtree filter contains two containment nodes
(<users>, <user>), one content match node
(<name>), and one selection node
(<company‑info>). The subtree selection
criteria is met, and just the company-info subtree for
"root" is selected in the filter output.
</t>
<t>
The "fred" subtree filter contains three containment nodes
(<users>, <user>, <company‑info>),
one content match node (<name>), and one selection
node (<id>). The subtree selection criteria is met,
and just the <id> element within the company‑info
subtree for "fred" is selected in the filter output.
</t>
<t>
The "barney" subtree filter contains three containment
nodes (<users>, <user>,
<company‑info>), two content match nodes
(<name>, <type>), and one selection node
(<dept>). The subtree selection criteria is not met
because user "barney" is not a "superuser", and the entire
subtree for "barney" (including its parent <user>
entry) is excluded from the filter output.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<company-info/>
</user>
<user>
<name>fred</name>
<company-info>
<id/>
</company-info>
</user>
<user>
<name>barney</name>
<type>superuser</type>
<company-info>
<dept/>
</company-info>
</user>
</users>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<company-info>
<dept>1</dept>
<id>1</id>
</company-info>
</user>
<user>
<name>fred</name>
<company-info>
<id>2</id>
</company-info>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
<section title="Elements with Attribute Naming">
<t>
In this example, the filter contains one containment node
(<interfaces>), one attribute match expression (ifName), and one
selection node (<interface>). All instances of the <interface>
subtree that have an ifName attribute equal to "eth0" are selected
in the filter output. The filter data elements and attributes must
be qualified because the ifName attribute will not be considered part
of the 'schema/1.2' namespace if it is unqualified.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<t:top xmlns:t="http://example.com/schema/1.2/stats">
<t:interfaces>
<t:interface t:ifName="eth0"/>
</t:interfaces>
</t:top>
</filter>
</get>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<t:top xmlns:t="http://example.com/schema/1.2/stats">
<t:interfaces>
<t:interface t:ifName="eth0">
<t:ifInOctets>45621</t:ifInOctets>
<t:ifOutOctets>774344</t:ifOutOctets>
</t:interface>
</t:interfaces>
</t:top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
<t>
If ifName were a child node instead of an attribute, then the
following request would produce similar results.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/stats">
<interfaces>
<interface>
<ifName>eth0</ifName>
</interface>
</interfaces>
</top>
</filter>
</get>
</rpc>
]]></artwork>
</figure>
</t>
</section>
</section>
</section> <!-- Subtree Filtering -->
<section title="Protocol Operations" anchor="protocolOperations">
<t>
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.
</t>
<t>
The base protocol includes the following protocol operations:
<list style="symbols">
<t>get</t>
<t>get-config</t>
<t>edit-config</t>
<t>copy-config</t>
<t>delete-config</t>
<t>lock</t>
<t>unlock</t>
<t>close-session</t>
<t>kill-session</t>
</list>
</t>
<t>
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.
</t>
<t>
The syntax and XML encoding of the protocol operations are
formally defined in the YANG module in <xref target="yangmodule"/>.
The following sections describe the semantics of each protocol operation.
</t>
<section title="<get‑config>" anchor="get-config">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
Retrieve all or part of a specified configuration.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="source:">
<vspace blankLines="1"/>
Name of the configuration datastore being queried,
such as <running/>.
</t>
<t hangText="filter:">
<vspace blankLines="1"/>
This parameter identifies the portions of the device
configuration to retrieve.
If this parameter is not present, the entire configuration
is returned.
<vspace blankLines="1"/>
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
<xref target="subtree" />. The value "subtree"
explicitly identifies this type of filtering.
<vspace blankLines="1"/>
If the NETCONF peer supports <xref target="xpath">the :xpath capability</xref>,
the value "xpath" may be used to indicate that the select
attribute on the filter element
contains an XPath expression.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device can satisfy the request, the server sends an
<rpc‑reply> element containing a <data> element
with the results of the query.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t hangText="Example:">
To retrieve the entire <users> subtree:
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config">
<users/>
</top>
</filter>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<type>superuser</type>
<full-name>Charlie Root</full-name>
<company-info>
<dept>1</dept>
<id>1</id>
</company-info>
</user>
<!-- additional <user> elements appear here... -->
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
<t>
<xref target="subtree"/> contains additional examples
of subtree filtering.
</t>
</list>
</t>
</section>
<section title="<edit‑config>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
The <edit‑config> 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.
<vspace blankLines="1"/>
If a NETCONF peer supports <xref target="url">the :url capability</xref>,
the <url> element can appear instead of the <config> parameter.
<vspace blankLines="1"/>
The device analyzes the source and target configurations and
performs the requested changes. The target configuration is not
necessarily
replaced, as with the <copy‑config> message. Instead, the
target configuration is changed in accordance with the source's
data and requested operations.
<vspace blankLines="1"/>
If the <edit-config> operation contains multiple sub-operations
which apply to the same conceptual node in the underlying
data model, then the result of the operation is undefined
(i.e., outside the scope of the NETCONF protocol).
</t>
<t hangText="Attributes:">
<list style="hanging">
<t hangText="operation:">
<vspace blankLines="1"/>
Elements in the <config> 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
<config> subtree.
<vspace blankLines="1"/>
If the operation attribute is not specified, the
configuration is merged into the configuration datastore.
<vspace blankLines="1"/>
The operation attribute has one of the following values:
<list style="hanging">
<t hangText="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.
</t>
<t hangText="replace:">
The configuration data identified by the element
containing this attribute replaces any related
configuration in the configuration datastore
identified by the target parameter. If no such
configuration data exists in the configuration
datastore, it is created. Unlike a
<copy‑config> operation, which
replaces the entire target configuration, only
the configuration actually present in the config
parameter is affected.
</t>
<t hangText="create:">
The configuration data identified by the element
containing this attribute is added to the
configuration if and only if the configuration
data does not already exist in the configuration
datastore. If the configuration data exists, an
<rpc‑error> element is returned with
an <error‑tag> value of
"data‑exists".
</t>
<t hangText="delete:">
The configuration data identified by the element
containing this attribute is deleted from the
configuration if and only if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, an
<rpc‑error> element is returned with
an <error‑tag> value of
"data‑missing".
</t>
<t hangText="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.
</t>
</list>
</t>
</list>
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="target:">
<vspace blankLines="1"/>
Name of the configuration datastore being edited, such as
<running/> or <candidate/>.
</t>
<t hangText="default-operation:">
<vspace blankLines="1"/>
Selects the default operation (as described in the
"operation" attribute) for this <edit‑config> request.
The default value for the default-operation
parameter is "merge".
<vspace blankLines="1"/>
The default-operation parameter is optional, but
if provided, it
must have one of the following values:
<list style="hanging">
<t hangText="merge:">
The configuration data in the <config> parameter is
merged with the configuration at the corresponding level in
the target datastore. This is the default behavior.
</t>
<t hangText="replace:">
The configuration data in the <config> parameter
completely replaces the configuration in the target
datastore. This is useful for loading previously saved
configuration data.
</t>
<t hangText="none:">
The target datastore is unaffected by the
configuration in the <config> parameter,
unless and until the
incoming configuration data uses the "operation" attribute to
request a different operation. If the configuration in the
<config> parameter contains data for which there is not a
corresponding level in the target datastore, an <rpc‑error>
is returned with an <error‑tag>
value of data-missing.
Using "none" allows operations like "delete" to avoid
unintentionally creating the parent hierarchy of the element to
be deleted.
</t>
</list>
</t>
<t hangText="test-option:">
<vspace blankLines="1"/>
The test-option element may be specified only if the device
advertises the <xref target="validate">:validate:1.1
capability</xref>.
<vspace blankLines="1"/>
The test-option element has one of the following values:
<list style="hanging">
<t hangText="test-then-set:">
Perform a validation test before attempting to set.
If validation errors occur, do not perform the <edit‑config>
operation. This is the default test-option.
</t>
<t hangText="set:">
Perform a set without a validation test first.
</t>
<t hangText="test-only:">
Perform only the validation test, without
attempting to set.
</t>
</list>
</t>
<t hangText="error-option:">
<vspace blankLines="1"/>
The error-option element has one of the following values:
<list style="hanging">
<t hangText="stop-on-error:">
Abort the edit-config operation on first error. This
is the default error-option.
</t>
<t hangText="continue-on-error:">
Continue to process configuration data on error;
error is recorded, and negative response is
generated if any errors occur.
</t>
<t hangText="rollback-on-error:">
If an error condition occurs
such that an error severity <rpc‑error> element is generated,
the server will stop processing the edit-config operation and
restore the specified configuration to its complete state
at the start of this edit-config operation. This option
requires the server to support the :rollback-on-error capability
described in <xref target="rollback-on-error"/>.
</t>
</list>
</t>
<t hangText="config:">
<vspace blankLines="1"/>
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 <xref target="capabilities"/>.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent containing an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> response is sent if the request cannot
be completed for any reason.
</t>
<t hangText="Example:">
<vspace blankLines="1"/>
The <edit‑config> 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.
<vspace blankLines="1"/>
Set the MTU to 1500 on an interface named "Ethernet0/0" in the
running configuration:
</t>
</list>
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
<t>
Add an interface named "Ethernet0/0" to the
running configuration, replacing any previous interface
with that name:
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<top xmlns="http://example.com/schema/1.2/config">
<interface xc:operation="replace">
<name>Ethernet0/0</name>
<mtu>1500</mtu>
<address>
<name>192.0.2.4</name>
<prefix-length>24</prefix-length>
</address>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
<t>
Delete the configuration for an
interface named "Ethernet0/0" from the running configuration:
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<default-operation>none</default-operation>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<top xmlns="http://example.com/schema/1.2/config">
<interface xc:operation="delete">
<name>Ethernet0/0</name>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
<t>
Delete interface 192.0.2.4 from an OSPF area (other
interfaces configured in the same area are unaffected):
</t>
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<default-operation>none</default-operation>
<config xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<top xmlns="http://example.com/schema/1.2/config">
<protocols>
<ospf>
<area>
<name>0.0.0.0</name>
<interfaces>
<interface xc:operation="delete">
<name>192.0.2.4</name>
</interface>
</interfaces>
</area>
</ospf>
</protocols>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</section>
<section title="<copy‑config>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
If a NETCONF peer supports <xref target="url">the :url capability</xref>,
the <url> element can appear as the <source> or <target>
parameter.
<vspace blankLines="1"/>
Even if it advertises the :writable-running capability,
a device may choose not to support the <running/> configuration
datastore as the <target> parameter of a <copy‑config>
operation.
A device may choose not to support remote-to-remote copy operations,
where both the <source> and <target> parameters use the
<url> element.
If the source and target parameters identify the same URL or
configuration datastore, an error MUST be returned with an error-tag
containing "invalid-value".
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="target:">
<vspace blankLines="1"/>
Name of the configuration datastore to
use as the destination of the
copy operation.
</t>
<t hangText="source:">
<vspace blankLines="1"/>
Name of the configuration datastore to use as the
source of the copy operation, or the
<config> element containing the
complete configuration to copy.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that includes an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included within the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<running/>
</target>
<source>
<url>https://user@example.com:passphrase/cfg/new.txt</url>
</source>
</copy-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="<delete‑config>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
Delete a configuration
datastore. The <running> configuration datastore cannot be deleted.
<vspace blankLines="1"/>
If a NETCONF peer supports <xref target="url">the :url capability</xref>,
the <url> element can appear as the <target> parameter.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="target:">
<vspace blankLines="1"/>
Name of the configuration datastore to delete.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that includes an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included within the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<delete-config>
<target>
<startup/>
</target>
</delete-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="<lock>" anchor="lock">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
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.
<vspace blankLines="1"/>
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 <edit‑config> operation
on the locked
configuration and using the locked configuration as a target of the
<copy‑config> operation will be disallowed by any other
NETCONF session.
Additionally, the system
will ensure that these locked configuration resources will not be
modified by other non-NETCONF management operations such as SNMP and
CLI. The <kill‑session> operation can be used to
force
the release of a lock owned by another NETCONF session. It
is beyond the scope of this document to define how to break
locks held by other entities.
</t>
<t>
A lock MUST not be granted if either of the following conditions is
true:
<list style="symbols">
<t>
A lock is already held by any NETCONF session or another entity.
</t>
<t>
The target configuration is <candidate>, it has already been
modified, and these changes have not been committed or rolled back.
</t>
</list>
</t>
<t>
The server MUST respond with either an <ok>
element or an <rpc‑error>.
</t>
<t>
A lock will be released by the system if the session holding
the lock is terminated for any reason.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="target:">
<vspace blankLines="1"/>
Name of the configuration datastore to lock.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an
<rpc‑reply> is sent that contains an
<ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the
<rpc‑reply> if the request cannot be
completed for any reason.
<vspace blankLines="1"/>
If the lock is already held, the <error‑tag>
element will be 'lock‑denied' and the
<error‑info> element will include the
<session‑id> of the lock owner. If the lock is
held by a non-NETCONF entity, a <session‑id>
of 0 (zero) is included. Note that any other entity
performing a lock on even a partial piece of a target
will prevent a NETCONF lock (which is global) from being
obtained on that target.
</t>
<t hangText="Example:">
<vspace blankLines="1"/>
The following example shows a successful acquisition of a lock.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <!-- lock succeeded -->
</rpc-reply>
]]></artwork>
</figure>
</t>
<t hangText="Example:">
<vspace blankLines="1"/>
The following example shows a failed attempt to acquire a lock
when the lock is already in use.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error> <!-- lock failed -->
<error-type>protocol</error-type>
<error-tag>lock-denied</error-tag>
<error-severity>error</error-severity>
<error-message>
Lock failed, lock is already held
</error-message>
<error-info>
<session-id>454</session-id>
<!-- lock is held by NETCONF session 454 -->
</error-info>
</rpc-error>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section><!-- end of Lock operation -->
<section title="<unlock>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
The unlock operation is used to release a configuration
lock, previously obtained with the <lock> operation.
<vspace blankLines="1"/>
An unlock operation will not succeed if any of the following
conditions are true:
<list style="symbols">
<t>the specified lock is not currently active</t>
<t>the session issuing the <unlock> operation is not
the same session that obtained the lock</t>
</list>
<vspace blankLines="1"/>
The server MUST respond with either an <ok> element or an <rpc‑error>.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="target:">
<vspace blankLines="1"/>
Name of the configuration datastore to unlock.
<vspace blankLines="1"/>
A NETCONF client is not permitted to unlock a
configuration datastore that it did not lock.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that contains an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<running/>
</target>
</unlock>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section> <!-- end of Unlock operation -->
<section title="<get>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
Retrieve running configuration and device state information.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="filter:">
<vspace blankLines="1"/>
This parameter specifies the portion of the system configuration and state
data to retrieve. If this parameter is not present, all the device configuration
and state information is returned.
<vspace blankLines="1"/>
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
<xref target="subtree" />. The value 'subtree'
explicitly identifies this type of filtering.
<vspace blankLines="1"/>
If the NETCONF peer supports <xref target="xpath">the :xpath capability</xref>,
the value "xpath" may be used to indicate that the select
attribute of the filter element
contains an XPath expression.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent. The <data> section contains the
appropriate subset.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get>
<filter type="subtree">
<top xmlns="http://example.com/schema/1.2/stats">
<interfaces>
<interface>
<ifName>eth0</ifName>
</interface>
</interfaces>
</top>
</filter>
</get>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/stats">
<interfaces>
<interface>
<ifName>eth0</ifName>
<ifInOctets>45621</ifInOctets>
<ifOutOctets>774344</ifOutOctets>
</interface>
</interfaces>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="<close-session>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
Request graceful termination of a NETCONF session.
<vspace blankLines="1"/>
When a NETCONF server receives a
<close‑session> request, it will
gracefully close the session. The server will release
any locks and resources associated with the session
and gracefully close any associated connections. Any
NETCONF requests received after a
<close‑session> request will be ignored.
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that includes an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the
<rpc‑reply> if the request cannot be completed for
any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<close-session/>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="<kill-session>">
<t>
<list style="hanging">
<t hangText="Description:">
<vspace blankLines="1"/>
Force the termination of a NETCONF session.
<vspace blankLines="1"/>
When a NETCONF entity receives a <kill‑session>
request for an open session, it will abort any operations
currently in process, release any locks and resources
associated with the session, and close any
associated connections.
<vspace blankLines="1"/>
If a NETCONF server receives a
<kill‑session> request while processing a
confirmed commit (<xref target='confirmed'/>), it must
restore the configuration to its state before the
confirmed commit was issued.
<vspace blankLines="1"/>
Otherwise, the <kill‑session> operation
does not roll back configuration or other device state
modifications made by the entity holding the lock.
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="session-id:">
<vspace blankLines="1"/>
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.
</t>
</list>
</t>
<t hangText="Positive Response:">
<vspace blankLines="1"/>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that includes an <ok> element.
</t>
<t hangText="Negative Response:">
<vspace blankLines="1"/>
An <rpc‑error> element is included in the
<rpc‑reply> if the request cannot be completed for
any reason.
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<kill-session>
<session-id>4</session-id>
</kill-session>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
</section>
<section title="Capabilities" anchor="capabilities">
<t>
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.
</t>
<t>
Additional capabilities can be defined using the template in
<xref target="capabilityTemplate" />.
Future capability definitions may be published as standards by
standards bodies or published as proprietary extensions.
</t>
<t>
A NETCONF capability is identified with a URI.
The base capabilities are defined using URNs following
the method described in <xref target="RFC3553">RFC 3553</xref>.
Capabilities defined in this document have the following format:
<list style="empty">
<t>urn:ietf:params:netconf:capability:{name}:1.x</t>
</list>
where {name} is the name of the capability. Capabilities are often
referenced in discussions and email using the shorthand :{name}, or
:{name}:{version} if the capability exists in multiple versions. For
example, the foo capability would have the formal name
"urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". The
shorthand form MUST NOT be used inside the protocol.
</t>
<section title="Capabilities Exchange" anchor="capabilityExchange">
<t>
Capabilities are advertised in messages sent
by each peer during session establishment. When the NETCONF session is
opened, each peer (both client and server) MUST send a <hello>
element containing a list of that peer's capabilities.
Each peer MUST send at least the base NETCONF capability,
"urn:ietf:params:netconf:base:1.1". A peer MAY include
capabilities for previous NETCONF versions, to indicate that
it supports multiple protocol versions.
</t>
<t>
Both NETCONF peers MUST verify that the other peer has advertised
a common protocol version. When comparing protocol version capability
URIs, only the base part is used, in the event any parameters are encoded
at the end of the URI string. If no protocol version capability in
common is found, the NETCONF peer MUST NOT continue the session.
If more than one protocol version URI in common is present, then
the highest numbered (most recent) protocol version MUST be used
by both peers.
</t>
<t>
A server sending the <hello> element
MUST include a <session‑id> element containing the
session ID for this NETCONF session.
A client sending the <hello> element MUST NOT
include a <session‑id> element.
</t>
<t>
A server receiving a <session‑id> element MUST NOT continue
the NETCONF session.
Similarly, a client that does not receive a <session‑id> element
in the server's <hello> message MUST NOT continue the NETCONF session.
In both cases, the underlying transport
should be closed.
</t>
<t>
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.
</t>
<figure>
<artwork><![CDATA[
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities>
<capability>
urn:ietf:params:netconf:base:1.1
</capability>
<capability>
urn:ietf:params:netconf:capability:startup:1.0
</capability>
<capability>
http://example.net/router/2.3/myfeature
</capability>
</capabilities>
<session-id>4</session-id>
</hello>
]]></artwork>
</figure>
<t>
Each peer sends its <hello> element simultaneously as soon as the
connection is open. A peer MUST NOT wait to receive the capability set
from the other side before sending its own set.
</t>
</section>
<section title="Writable-Running Capability">
<section title="Description">
<t>
The :writable-running capability indicates that the device
supports direct writes to the <running> configuration datastore. In other
words, the device supports edit-config and
copy-config operations where the <running> configuration is the
target.</t>
</section>
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :writable-running capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:writable-running:1.0</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<section title="<edit‑config>">
<t>
The :writable-running capability modifies the
<edit‑config> operation to accept the
<running> element as a <target>.
</t>
</section>
<section title="<copy‑config>">
<t>
The :writable-running capability modifies the
<copy‑config> operation to accept the
<running> element as a <target>.
</t>
</section>
</section>
</section> <!-- end of writable-running capability -->
<section title="Candidate Configuration Capability" anchor="candidate">
<section title="Description">
<t>
The candidate configuration capability, :candidate, indicates that
the device supports a candidate configuration datastore, which is used to hold
configuration data that can be manipulated without impacting the device's
current configuration. The candidate configuration is a full
configuration data set that serves as a work place for creating and
manipulating configuration data. Additions, deletions, and changes
may be made to this data to construct the desired configuration
data. A <commit> operation may be performed
at any time that causes the device's running configuration to be
set to the value of the candidate configuration.
</t>
<t>
The <commit> operation effectively sets the running
configuration to the current contents of the candidate configuration.
While it could be modeled as a simple copy, it is done as a distinct
operation for a number of reasons. In keeping high-level concepts
as first class operations, we allow developers to see more clearly
both what the client is requesting and what the server must perform.
This keeps the intentions more obvious, the special cases less complex,
and the interactions between operations more straightforward. For
example, the <xref target="confirmed">:confirmed-commit:1.1 capability </xref>
would make no sense as a "copy confirmed" operation.
</t>
<t>
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.
</t>
<t>
The client can discard any uncommitted changes to the candidate
configuration by executing the <discard‑changes> operation. This
operation reverts the contents of the candidate configuration
to the contents of the running configuration.
</t>
</section> <!-- end of Description -->
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t> The :candidate capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:candidate:1.0</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<section title="<commit>">
<t>
<list style="hanging">
<t hangText="Description:">
<list style="empty">
<t>
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.
</t>
<t>
To commit the candidate configuration as the device's new current
configuration, use the <commit> operation.
</t>
<t>
The <commit> operation instructs the device to implement the
configuration data contained in the candidate configuration.
If the device is unable to commit all of the changes in the candidate
configuration datastore, then the running configuration MUST
remain unchanged. If the device does succeed in committing, the
running configuration MUST be updated with the contents of the
candidate configuration.
</t>
<t>
If the running or candidate configuration is currently locked
by a different session, the <commit> operation
MUST fail with an <error‑tag> value of 'in‑use'.
</t>
<t>
If the system does not have the :candidate
capability, the <commit> operation is not available.
</t>
</list>
</t>
<t hangText="Positive Response:">
<list style="empty">
<t>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that contains an <ok> element.
</t>
</list>
</t>
<t hangText="Negative Response:">
<list style="empty">
<t>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
</list>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit/>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
<section title="<discard-changes>" anchor="discard-changes">
<t>
If the client decides that the candidate configuration should not be
committed, the <discard‑changes> operation can be used to revert the
candidate configuration to the current running configuration.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<discard-changes/>
</rpc>
]]></artwork>
</figure>
This operation discards any uncommitted changes by resetting the
candidate configuration with the content of the running configuration.
</t>
</section>
</section>
<section title="Modifications to Existing Operations">
<section title="<get‑config>, <edit‑config>, <copy‑config>, and <validate>">
<t>
The candidate configuration can be used as a source or target of any
<get‑config>, <edit‑config>, <copy‑config>, or <validate>
operation as a <source> or <target> parameter.
The <candidate> element is used to indicate the
candidate configuration:
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <!-- any NETCONF operation -->
<source>
<candidate/>
</source>
</get-config>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="<lock> and <unlock>">
<t>
The candidate configuration can be locked using the <lock>
operation with the <candidate> element as the <target> parameter:
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<candidate/>
</target>
</lock>
</rpc>
]]></artwork>
</figure>
Similarly, the candidate configuration is unlocked using
the <candidate> element as the <target> parameter:
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
]]></artwork>
</figure>
</t>
<t>
When a client fails with outstanding changes to the candidate
configuration, recovery can be difficult. To facilitate easy recovery,
any outstanding changes are discarded when the lock is released,
whether explicitly with the <unlock> operation or implicitly from
session failure.
</t>
</section>
</section>
</section>
<section title="Confirmed Commit Capability" anchor="confirmed">
<section title="Description">
<t>
The :confirmed-commit:1.1 capability indicates that the server will
support the <cancel‑commit> operation and the
<confirmed>, <confirm‑timeout>, <persist>, and
<persist‑id> parameters for the <commit>
operation. See <xref target="candidate" /> for further details on the
<commit> operation.
</t>
<t>
A confirmed commit operation MUST be reverted if a confirming commit
is not issued within 600 seconds (10 minutes). The confirming
commit is a commit operation without the <confirmed>
parameter. The timeout period can be adjusted with the
<confirm‑timeout> parameter. If a follow-up confirmed
commit operation is issued before the timer expires, the timer is
reset to the new value (600 seconds by default). Both the
confirming commit and a follow-up confirmed commit operation MAY
introduce additional changes to the configuration,
</t>
<t>
If the <persist> element is not given in the confirmed commit
operation, any follow-up commit and the confirming commit MUST be
issued on the same session that issued the confirmed commit. If the
<persist> element is given in the confirmed commit operation,
a follow-up commit and the confirming commit can be given on any
session, and they MUST include a <persist‑id> element
with a value equal to the given value of the <persist>
element.
</t>
<t>
If the server also advertises the :startup capability, a
<copy‑config> from running to startup is also necessary to
save the changes to startup.
</t>
<t>
If the session issuing the confirmed commit is terminated for any
reason before the confirm timeout expires, the server MUST restore the
configuration to its state before the confirmed commit was issued,
unless the confirmed commit also included a <persist> element.
</t>
<t>
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.
</t>
<t>
If a confirming commit is not issued, the device will revert its
configuration to the state prior to the issuance of the confirmed
commit. To cancel a confirmed commit and revert changes without
waiting for the confirm timeout to expire, the client can explicitly
restore the configuration to its state before the confirmed commit was
issued, by using the <cancel‑commit> operation.
</t>
<t>
For shared configurations, this feature can cause other
configuration changes (for example, via other NETCONF sessions) to be
inadvertently altered or removed, unless the configuration locking
feature is used (in other words, the lock is obtained before the edit-config
operation is started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration datastores,
configuration locking should also be used.
</t>
<t>
Version 1.0 of this capability was defined in <xref
target="RFC4741"/>. The current version is 1.1, and is
defined in this document. It extends version 1.0 by
adding a new operation, <cancel‑commit>, and
two new optional parameters, <persist> and
<persist‑id>. For backwards compatibility
with old clients, servers confirming to this
specification MAY advertise version 1.0 in addition to
version 1.1.
</t>
</section> <!-- end of Description -->
<section title="Dependencies">
<t>The :confirmed-commit:1.1 capability is only relevant if the :candidate
capability is also supported.</t>
</section>
<section title="Capability Identifier">
<t> The :confirmed-commit:1.1 capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:confirmed-commit:1.1</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<section title="<cancel-commit>">
<t>
<list style="hanging">
<t hangText="Description:">
<list style="empty">
<t>
Cancels an ongoing confirmed commit. If the
<persist‑id> parameter is not given, the
<cancel‑commit> operation MUST be issued
on the same session that issued the confirmed commit.
</t>
</list>
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="persist-id:">
<list style="empty">
<t>
Cancels a persistent confirmed commit. The
value MUST be equal to the value given in
the <persist> parameter to the commit
operation. If the value does not match, the
operation fails with an "invalid-value"
error.
</t>
</list>
</t>
</list>
</t>
<t hangText="Positive Response:">
<list style="empty">
<t>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that contains an <ok> element.
</t>
</list>
</t>
<t hangText="Negative Response:">
<list style="empty">
<t>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
</list>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
</commit>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<cancel-commit/>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
</section>
<section title="Modifications to Existing Operations">
<section title="<commit>">
<t>The :confirmed-commit:1.1 capability allows 4 additional
parameters to the <commit> operation.</t>
<t>
<list style="hanging">
<t hangText="Parameters:">
<list style="hanging">
<t hangText="confirmed:">
<list style="empty">
<t>
Perform a confirmed commit operation.
</t>
</list>
</t>
<t hangText="confirm-timeout:">
<list style="empty">
<t>
Timeout period for confirmed commit, in seconds.
If unspecified, the confirm timeout defaults to
600 seconds.
</t>
</list>
</t>
<t hangText="persist:">
<list style="empty">
<t>
Make the confirmed commit survive a session
termination, and set a token on the ongoing
confirmed commit.
</t>
</list>
</t>
<t hangText="persist-id:">
<list style="empty">
<t>
Used to issue a follow-up confirmed commit or a
confirming commit from any session, with the
token from the previous commit operation.
</t>
</list>
</t>
</list>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<confirm-timeout>120</confirm-timeout>
</commit>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<!-- start a persistent confirmed-commit -->
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<persist>IQ,d4668</persist>
</commit>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
<!-- confirm the persistent confirmed-commit,
possibly from another session -->
<rpc message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<persist-id>IQ,d4668</persist-id>
</commit>
</rpc>
<rpc-reply message-id="102"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section>
</section>
</section> <!-- confirmed commit capability -->
<section title="Rollback on Error Capability" anchor="rollback-on-error">
<section title="Description">
<t>
This capability indicates that the server will support the
'rollback‑on‑error' value in the
<error‑option> parameter to the
<edit‑config> operation.
</t>
<t>
For shared configurations, this feature can cause other
configuration changes (for example, via other NETCONF
sessions) to be inadvertently altered or removed, unless
the configuration locking feature is used (in other words,
the lock is obtained before the edit-config operation is
started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration
datastores, configuration locking also be used.
</t>
</section> <!-- end of Description -->
<section title="Dependencies">
<t>None</t>
</section>
<section title="Capability Identifier">
<t> The :rollback-on-error capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:rollback-on-error:1.0</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<section title="<edit‑config>">
<t>The :rollback-on-error capability allows the
'rollback‑on‑error' value to the
<error‑option> parameter on the
<edit‑config> operation.</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<error-option>rollback-on-error</error-option>
<config>
<top xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>100000</mtu>
</interface>
</top>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
</section>
</section> <!-- rollback-on-error capability -->
<section title="Validate Capability" anchor="validate">
<section title="Description">
<t>
Validation consists of checking a complete
configuration for syntactical and semantic errors before
applying the configuration to the device.
</t>
<t>
If this capability is advertised, the device supports the
<validate> protocol operation and checks at least for syntax
errors. In addition, this capability supports the test-option parameter to the
<edit‑config> operation and, when it is provided, checks at
least for syntax errors.
</t>
<t>
Version 1.0 of this capability was defined in <xref
target="RFC4741"/>. The current version is 1.1, and is
defined in this document. It extends version 1.0 by
adding a new value, "test-only", to the test-option
parameter of the edit-config operation. For backwards
compatibility with old clients, servers confirming to this
specification MAY advertise version 1.0 in addition to
version 1.1.
</t>
</section> <!-- end of Description -->
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :validate:1.1 capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:validate:1.1</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<section title="<validate>">
<t>
<list style="hanging">
<t hangText="Description:">
<list style="empty">
<t>
This protocol operation validates the contents of the
specified configuration.
</t>
</list>
</t>
<t hangText="Parameters:">
<list style="hanging">
<t hangText="source:">
<list style="empty">
<t>
Name of the configuration datastore to validate, such as
<candidate>, or the <config> element containing
the complete configuration to validate.
</t>
</list>
</t>
</list>
</t>
<t hangText="Positive Response:">
<list style="empty">
<t>
If the device was able to satisfy the request, an <rpc‑reply>
is sent that contains an <ok> element.
</t>
</list>
</t>
<t hangText="Negative Response:">
<list style="empty">
<t>
An <rpc‑error> element is included in the <rpc‑reply>
if the request cannot be completed for any reason.
</t>
<t>
A validate operation can fail for any of the following reasons:
<list style="symbols">
<t>Syntax errors</t>
<t>Missing parameters</t>
<t>References to undefined configuration data</t>
</list>
</t>
</list>
</t>
<t hangText="Example:">
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/>
</rpc-reply>
]]></artwork>
</figure>
</t>
</list>
</t>
</section> <!-- end of validate operation -->
</section>
<section title="Modifications to Existing Operations">
<section title="<edit‑config>">
<t>The :validate:1.1 capability modifies the
<edit‑config> operation to accept the
<test‑option> parameter.</t>
</section>
</section>
</section>
<section title="Distinct Startup Capability" anchor="startup">
<section title="Description">
<t>
The device supports separate running and startup configuration
datastores. The startup configuration is loaded by the device
when it boots. Operations that affect the running
configuration will not be automatically copied to the startup
configuration. An explicit <copy‑config> operation
from the <running> to the <startup> must be invoked
to update the startup configuration to the current contents of
the running configuration. NETCONF protocol operations refer to
the startup datastore using the <startup> element.
</t>
</section>
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :startup capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:startup:1.0</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<section title="General">
<t>
The :startup capability adds the <startup/>
configuration datastore to arguments of several
NETCONF operations. The server MUST support the
following additional values:
</t>
<texttable>
<ttcol width='30%'>Operation</ttcol>
<ttcol width='40%'>Parameters</ttcol>
<ttcol>Notes</ttcol>
<c><get‑config></c>
<c><source></c>
<c> </c>
<c><copy‑config></c>
<c><source> <target></c>
<c> </c>
<c><lock></c>
<c><target></c>
<c> </c>
<c><unlock></c>
<c><target></c>
<c> </c>
<c><validate></c>
<c><source></c>
<c>If :validate:1.1 is advertised</c>
<c><delete-config></c>
<c><target></c>
<c>Resets the device to its factory defaults</c>
</texttable>
<t>
To save the startup configuration, use the copy-config
operation to copy the <running> configuration
datastore to the <startup> configuration datastore.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<startup/>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
]]></artwork>
</figure>
</t>
</section>
</section>
</section>
<section title="URL Capability" anchor="url">
<section title="Description">
<t>
The NETCONF peer has the ability to accept the <url>
element in <source> and <target>
parameters. The capability is further identified by
URL arguments indicating the URL schemes supported.
</t>
</section>
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :url capability is identified by the
following capability string:
</t>
<t>urn:ietf:params:netconf:capability:url:1.0?scheme={name,...}</t>
<t>
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:
<list style="empty">
<t>urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<section title="<edit‑config>">
<t>The :url capability modifies the
<edit‑config> operation to accept the
<url> element as an alternative to the <config> parameter.
</t>
</section>
<section title="<copy‑config>">
<t>The :url capability modifies the
<copy‑config> operation to accept the
<url> element as the value of
the <source> and the <target> parameters.</t>
<t>
The file that the url refers to contains the
complete datastore, encoded in XML under the element
'config' in the
'urn:ietf:params:xml:ns:netconf:base:1.0' namespace.
</t>
</section>
<section title="<delete‑config>">
<t>The :url capability modifies the
<delete‑config> operation to accept the
<url> element as the value of
the <target> parameters.
</t>
</section>
<section title="<validate>">
<t>The :url capability modifies the
<validate> operation to accept the
<url> element as the value of
the <source> parameter.</t>
</section>
</section>
</section> <!-- end of URL capability -->
<section title="XPath Capability" anchor="xpath">
<section title="Description">
<t>
The XPath capability indicates that the NETCONF
peer supports the use of XPath expressions in the
<filter> element.
XPath is described in <xref target="W3C.REC-xpath-19991116" />.
</t>
<t>
The data model used in the XPath expression is the same
as that used in XPath 1.0 <xref
target="W3C.REC-xpath-19991116"/>, with the same
extension for root node children as used by XSLT 1.0
<xref target="W3C.REC-xslt-19991116"/> (section 3.1).
Specifically, it means that the root node may have any
number of element nodes as its children.
</t>
<t>The XPath expression is evaluated in the following context:
<list style="symbols">
<t>The set of namespace declarations are those in
scope on the filter element.</t>
<t>The set of variable bindings is defined by the data
model. If no such variable bindings are defined, the set
is empty.</t>
<t>The function library is the core function library,
plus any functions defined by the data model.</t>
<t>The context node is the root node.</t>
</list>
</t>
<t>
The XPath expression MUST return a node set. If it does
not return a node set, the operation fails with an
"invalid-value" error.
</t>
<t>
The response message contains the subtrees selected by
the filter expression. For each such subtree, the path
from the data model root node down to the subtree,
including any elements or attributes necessary to
uniquely identify the subtree, are included in the
response message.
</t>
</section>
<section title="Dependencies">
<t>None.</t>
</section>
<section title="Capability Identifier">
<t>The :xpath capability is identified by the
following capability string:
<list style="empty">
<t>urn:ietf:params:netconf:capability:xpath:1.0</t>
</list>
</t>
</section> <!-- end of Capability & Namespace -->
<section title="New Operations">
<t>None.</t>
</section>
<section title="Modifications to Existing Operations">
<section title="<get‑config> and <get>">
<t>
The :xpath capability modifies the <get> and <get‑config> operations
to accept the value "xpath" in the type attribute of the filter
element. When the type attribute is set to "xpath", a select
attribute MUST be present on the filter element. The select
attribute will be treated as an XPath expression and used to filter
the returned data. The filter element itself MUST be empty in this
case.
</t>
<t>
The XPath result for the select expression MUST be a node-set.
Each node in the node-set MUST correspond to a node in
underlying data model. In order to properly identify
each node, the following encoding rules are defined:
<list style="symbols">
<t>All ancestor nodes of the result node MUST be encoded
first, so the <data> element returned in the reply
contains only fully-specified sub-trees, according
to the underlying data model.</t>
<t>If any sibling or ancestor nodes of the result node are needed to
identify a particular instance within a conceptual data structure,
then these nodes MUST also be encoded in the response.
</t>
</list>
</t>
<t>
For example:
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config>
<source>
<running/>
</source>
<!-- get the user named fred -->
<filter xmlns:t="http://example.com/schema/1.2/config"
type="xpath"
select="/t:top/t:users/t:user[t:name='fred']"/>
</get-config>
</rpc>
<rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data>
<top xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
<company-info>
<id>2</id>
</company-info>
</user>
</users>
</top>
</data>
</rpc-reply>
]]></artwork>
</figure>
</t>
</section>
</section>
</section> <!-- end of XPath capability -->
</section> <!-- Capabilities -->
<section title="Security Considerations" anchor="security">
<t>
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.
</t>
<t>
Authorization of individual users via the NETCONF server may or may
not map 1:1 to other interfaces. First, the
data models may be incompatible. Second, it may be desirable to
authorize based on mechanisms available in the secure transport
layer (SSH, BEEP, etc).
</t>
<t>
In addition, operations on configurations may have unintended
consequences if those operations are also not guarded by the global
lock on the files or objects being operated upon. For instance, a
partially complete access list could be committed from a candidate
configuration unbeknownst to the owner of the lock of the candidate
configuration, leading to either an insecure or inaccessible device
if the lock on the candidate configuration does not also apply to
the <copy‑config> operation when applied to it.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
That having been said, it is important to recognize that some
operations are clearly more sensitive by nature than others. For
instance, <copy‑config> to the startup or running
configurations is clearly not a normal provisioning operation,
whereas <edit‑config> is.
Such global operations MUST disallow the changing of information
that an individual does not have authorization to perform.
For example, if a user A is not allowed to configure an IP
address on an interface but user B has configured an IP address
on an interface in the <candidate> configuration,
user A must not be allowed to commit the <candidate>
configuration.
</t>
<t>
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.
</t>
<t>
The <lock> operation will demonstrate that NETCONF
is intended for use by systems that have at least some trust of
the administrator. As specified in this document, it is possible
to lock portions of a configuration that a principal might not
otherwise have access to. After all, the entire configuration is
locked. To mitigate this problem, there are two approaches. It
is possible to kill another NETCONF session programmatically from
within NETCONF if one knows the session identifier of the
offending session. The other possible way to break a lock is to
provide an function within the device's native user interface.
These two mechanisms suffer from a race condition
that may be ameliorated by removing the offending user from an AAA
server. However, such a solution is not useful in all deployment
scenarios, such as those where SSH public/private key pairs are used.
</t>
</section> <!-- Security Considerations -->
<section title="IANA Considerations"> <!-- RFC 2434 -->
<section title="NETCONF XML Namespace">
<t>
This document registers a URI for the NETCONF XML namespace in the
<xref target="RFC3688">IETF XML registry</xref>.
</t>
<t>
IANA is requested to update the allocation of the following
URI to reference this document when it is published as an
RFC.
</t>
<t>
URI: urn:ietf:params:xml:ns:netconf:base:1.0
</t>
<t>
Registrant Contact: The IESG.
</t>
<t>
XML: N/A, the requested URI is an XML namespace.
</t>
</section>
<section title="NETCONF XML Schema">
<t>
This document registers a URI for the NETCONF XML schema in the
<xref target="RFC3688">IETF XML registry</xref>.
</t>
<t>
IANA is requested to update the allocation of the following
URI to reference this document when it is published as an
RFC.
</t>
<t>
URI: urn:ietf:params:xml:schema:netconf
</t>
<t>
Registrant Contact: The IESG.
</t>
<t>
XML: <xref target="xsdschema"/> of this document.
</t>
</section>
<section title="NETCONF YANG Module">
<t>
This document registers a YANG module in the YANG Module
Names registry <xref target="I-D.ietf-netmod-yang"/>.
<figure>
<artwork><![CDATA[
name: ietf-netconf
namespace: urn:ietf:params:xml:ns:netconf:base:1.0
prefix: nc
reference: RFCXXXX
]]></artwork></figure>
</t>
</section>
<section title="NETCONF Capability URNs">
<t>
IANA has created and will maintain a registry "Network Configuration
Protocol (NETCONF) Capability URNs" that allocates NETCONF capability
identifiers. Additions to the registry require IETF Standards Action.
</t>
<t>
IANA is requested to update the allocations of the following
capabilities to reference this document when it is published as an
RFC.
</t>
<texttable>
<ttcol width='30%'>Index</ttcol>
<ttcol>Capability Identifier</ttcol>
<c>:writable-running</c>
<c>urn:ietf:params:netconf:capability:writable-running:1.0</c>
<c>:candidate</c>
<c>urn:ietf:params:netconf:capability:candidate:1.0</c>
<c>:rollback-on-error</c>
<c>urn:ietf:params:netconf:capability:rollback-on-error:1.0</c>
<c>:startup</c>
<c>urn:ietf:params:netconf:capability:startup:1.0</c>
<c>:url</c>
<c>urn:ietf:params:netconf:capability:url:1.0</c>
<c>:xpath</c>
<c>urn:ietf:params:netconf:capability:xpath:1.0</c>
</texttable>
<t>
IANA is requested to add the following capabilities to the registry:
</t>
<texttable>
<ttcol width='30%'>Index</ttcol>
<ttcol>Capability Identifier</ttcol>
<c>:base:1.1</c>
<c>urn:ietf:params:netconf:base:1.1</c>
<c>:confirmed-commit:1.1</c>
<c>urn:ietf:params:netconf:capability:confirmed-commit:1.1</c>
<c>:validate:1.1</c>
<c>urn:ietf:params:netconf:capability:validate:1.1</c>
</texttable>
</section>
</section> <!-- IANA Considerations -->
<section title="Authors and Acknowledgements">
<t>This document was written by:
<list style="empty">
<t>Andy Bierman</t>
<t>Ken Crozier, Cisco Systems</t>
<t>Rob Enns, Juniper Networks</t>
<t>Ted Goddard, IceSoft</t>
<t>Eliot Lear, Cisco Systems</t>
<t>Phil Shafer, Juniper Networks</t>
<t>Steve Waldbusser</t>
<t>Margaret Wasserman, ThingMagic</t>
</list>
</t>
<t>
The authors would like to acknowledge the members of the NETCONF
working group. In particular, we would like to thank Wes Hardaker
for his persistence and patience in assisting us with security
considerations. We would also like to thank Randy Presuhn, Sharon
Chisholm, Juergen Schoenwalder, Glenn Waters, David Perkins, Weijing
Chen, Simon Leinen, Keith Allen, and Dave Harrington for all of
their valuable advice.
</t>
</section>
</middle>
<back>
<references title="Normative References">
&xml; <!-- XML spec -->
&xpath; <!-- XPath spec -->
&rfc2119; <!-- keywords -->
&rfc4742; <!-- NETCONF/SSH -->
&rfc3986; <!-- URI -->
&rfc3553; <!-- URNs for protocol params -->
&rfc3688; <!-- IETF XML registry -->
&rfc5717; <!-- NETCONF notifs -->
&draft-yang;
&draft-yang-types;
</references>
<references title="Informative References">
&xslt; <!-- XSLT spec -->
&rfc2865; <!-- RADIUS -->
&rfc3470; <!-- XML use in IETF -->
&rfc4251; <!-- SSH -->
&rfc4346; <!-- TLS -->
&rfc4741; <!-- NETCONF 1.0 -->
</references>
<?rfc needLines="30" ?>
<section title="NETCONF Error List" anchor="errorList">
<t>
This section is normative.
</t>
<t>
For each error‑tag, the valid error‑type and
error‑severity values are listed, together with any
mandatory error‑info, if any.
</t>
<figure>
<artwork><![CDATA[
error-tag: in-use
error-type: protocol, application
error-severity: error
error-info: none
Description: The request requires a resource that already is in use.
error-tag: invalid-value
error-type: protocol, application
error-severity: error
error-info: none
Description: The request specifies an unacceptable value for one
or more parameters.
error-tag: too-big
error-type: transport, rpc, protocol, application
error-severity: error
error-info: none
Description: The request or response (that would be generated) is
too large for the implementation to handle.
error-tag: missing-attribute
error-type: rpc, protocol, application
error-severity: error
error-info: <bad-attribute> : name of the missing attribute
<bad-element> : name of the element that should
contain the missing attribute
Description: An expected attribute is missing.
error-tag: bad-attribute
error-type: rpc, protocol, application
error-severity: error
error-info: <bad-attribute> : name of the attribute w/ bad value
<bad-element> : name of the element that contains
the attribute with the bad value
Description: An attribute value is not correct; e.g., wrong type,
out of range, pattern mismatch.
error-tag: unknown-attribute
error-type: rpc, protocol, application
error-severity: error
error-info: <bad-attribute> : name of the unexpected attribute
<bad-element> : name of the element that contains
the unexpected attribute
Description: An unexpected attribute is present.
error-tag: missing-element
error-type: protocol, application
error-severity: error
error-info: <bad-element> : name of the missing element
Description: An expected element is missing.
error-tag: bad-element
error-type: protocol, application
error-severity: error
error-info: <bad-element> : name of the element w/ bad value
Description: An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.
error-tag: unknown-element
error-type: protocol, application
error-severity: error
error-info: <bad-element> : name of the unexpected element
Description: An unexpected element is present.
error-tag: unknown-namespace
error-type: protocol, application
error-severity: error
error-info: <bad-element> : name of the element that contains
the unexpected namespace
<bad-namespace> : name of the unexpected namespace
Description: An unexpected namespace is present.
error-tag: access-denied
error-type: protocol, application
error-severity: error
error-info: none
Description: Access to the requested protocol operation, or
data model is denied because authorization failed.
error-tag: lock-denied
error-type: protocol
error-severity: error
error-info: <session-id> : session ID of session holding the
requested lock, or zero to indicate a non-NETCONF
entity holds the lock
Description: Access to the requested lock is denied because the
lock is currently held by another entity.
error-tag: resource-denied
error-type: transport, rpc, protocol, application
error-severity: error
error-info: none
Description: Request could not be completed because of
insufficient resources.
error-tag: rollback-failed
error-type: protocol, application
error-severity: error
error-info: none
Description: Request to rollback some configuration change (via
rollback-on-error or discard-changes operations) was
not completed for some reason.
error-tag: data-exists
error-type: application
error-severity: error
error-info: none
Description: Request could not be completed because the relevant
data model content already exists. For example,
a 'create' operation was attempted on data that
already exists.
error-tag: data-missing
error-type: application
error-severity: error
error-info: none
Description: Request could not be completed because the relevant
data model content does not exist. For example,
a 'delete' operation was attempted on
data that does not exist.
error-tag: operation-not-supported
error-type: protocol, application
error-severity: error
error-info: none
Description: Request could not be completed because the requested
operation is not supported by this implementation.
error-tag: operation-failed
error-type: rpc, protocol, application
error-severity: error
error-info: none
Description: Request could not be completed because the requested
operation failed for some reason not covered by
any other error condition.
error-tag: partial-operation
error-type: application
error-severity: error
error-info: <ok-element> : identifies an element in the data
model for which the requested operation has been
completed for that node and all its child nodes.
This element can appear zero or more times in the
<error-info> container.
<err-element> : identifies an element in the data
model for which the requested operation has failed
for that node and all its child nodes.
This element can appear zero or more times in the
<error-info> container.
<noop-element> : identifies an element in the data
model for which the requested operation was not
attempted for that node and all its child nodes.
This element can appear zero or more times in the
<error-info> container.
Description: This error-tag is obsolete, and SHOULD NOT be sent
by servers conforming to this document.
Some part of the requested operation failed or was
not attempted for some reason. Full cleanup has
not been performed (e.g., rollback not supported)
by the server. The error-info container is used
to identify which portions of the application
data model content for which the requested operation
has succeeded (<ok-element>), failed (<bad-element>),
or not been attempted (<noop-element>).
]]></artwork>
</figure>
</section>
<?rfc needLines="30" ?>
<section title="XML Schema for NETCONF Messages Layer" anchor="xsdschema">
<t>
This section is normative.
<figure>
<artwork><![CDATA[
<CODE BEGINS> file "netconf.xsd"
<?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0"
elementFormDefault="qualified"
attributeFormDefault="unqualified"
xml:lang="en"
version="1.1">
<xs:annotation>
<xs:documentation>
This schema defines the syntax for the NETCONF Message layer
messages 'hello', 'rpc', and 'rpc-reply'.
</xs:documentation>
</xs:annotation>
<!--
import standard XML definitions
-->
<xs:import namespace="http://www.w3.org/XML/1998/namespace"
schemaLocation="http://www.w3.org/2001/xml.xsd">
<xs:annotation>
<xs:documentation>
This import accesses the xml: attribute groups for the
xml:lang as declared on the error-message element.
</xs:documentation>
</xs:annotation>
</xs:import>
<!--
message-id attribute
-->
<xs:simpleType name="messageIdType">
<xs:restriction base="xs:string">
<xs:maxLength value="4095"/>
</xs:restriction>
</xs:simpleType>
<!--
Types used for session-id
-->
<xs:simpleType name="SessionId">
<xs:restriction base="xs:unsignedInt">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="SessionIdOrZero">
<xs:restriction base="xs:unsignedInt"/>
</xs:simpleType>
<!--
<rpc> element
-->
<xs:complexType name="rpcType">
<xs:sequence>
<xs:element ref="rpcOperation"/>
</xs:sequence>
<xs:attribute name="message-id" type="messageIdType"
use="required"/>
<!--
Arbitrary attributes can be supplied with <rpc> element.
-->
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:element name="rpc" type="rpcType"/>
<!--
data types and elements used to construct rpc-errors
-->
<xs:simpleType name="ErrorType">
<xs:restriction base="xs:string">
<xs:enumeration value="transport"/>
<xs:enumeration value="rpc"/>
<xs:enumeration value="protocol"/>
<xs:enumeration value="application"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ErrorTag">
<xs:restriction base="xs:string">
<xs:enumeration value="in-use"/>
<xs:enumeration value="invalid-value"/>
<xs:enumeration value="too-big"/>
<xs:enumeration value="missing-attribute"/>
<xs:enumeration value="bad-attribute"/>
<xs:enumeration value="unknown-attribute"/>
<xs:enumeration value="missing-element"/>
<xs:enumeration value="bad-element"/>
<xs:enumeration value="unknown-element"/>
<xs:enumeration value="unknown-namespace"/>
<xs:enumeration value="access-denied"/>
<xs:enumeration value="lock-denied"/>
<xs:enumeration value="resource-denied"/>
<xs:enumeration value="rollback-failed"/>
<xs:enumeration value="data-exists"/>
<xs:enumeration value="data-missing"/>
<xs:enumeration value="operation-not-supported"/>
<xs:enumeration value="operation-failed"/>
<xs:enumeration value="partial-operation"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ErrorSeverity">
<xs:restriction base="xs:string">
<xs:enumeration value="error"/>
<xs:enumeration value="warning"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="errorInfoType">
<xs:sequence>
<xs:choice>
<xs:element name="session-id" type="SessionIdOrZero"/>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:sequence>
<xs:element name="bad-attribute" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="bad-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="ok-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="err-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="noop-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="bad-namespace" type="xs:string"
minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:sequence>
</xs:choice>
<!-- elements from any other namespace are also allowed
to follow the NETCONF elements -->
<xs:any namespace="##other" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="rpcErrorType">
<xs:sequence>
<xs:element name="error-type" type="ErrorType"/>
<xs:element name="error-tag" type="ErrorTag"/>
<xs:element name="error-severity" type="ErrorSeverity"/>
<xs:element name="error-app-tag" type="xs:string"
minOccurs="0"/>
<xs:element name="error-path" type="xs:string" minOccurs="0"/>
<xs:element name="error-message" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="error-info" type="errorInfoType"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<!--
operation attribute used in <edit-config>
-->
<xs:simpleType name="editOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="merge"/>
<xs:enumeration value="replace"/>
<xs:enumeration value="create"/>
<xs:enumeration value="delete"/>
<xs:enumeration value="remove"/>
</xs:restriction>
</xs:simpleType>
<xs:attribute name="operation" type="editOperationType"/>
<!--
<rpc-reply> element
-->
<xs:complexType name="rpcReplyType">
<xs:choice>
<xs:element name="ok"/>
<xs:group ref="rpcResponse"/>
</xs:choice>
<xs:attribute name="message-id" type="messageIdType"
use="optional"/>
<!--
Any attributes supplied with <rpc> element must be returned
on <rpc-reply>.
-->
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:group name="rpcResponse">
<xs:sequence>
<xs:element ref="rpc-error"
minOccurs="0" maxOccurs="unbounded"/>
<xs:any namespace="##any" processContents="lax"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:group>
<xs:element name="rpc-reply" type="rpcReplyType"/>
<!--
<rpc-error> element
-->
<xs:element name="rpc-error" type="rpcErrorType"/>
<!--
rpcOperationType: used as a base type for all
NETCONF operations
-->
<xs:complexType name="rpcOperationType"/>
<xs:element name="rpcOperation"
type="rpcOperationType" abstract="true"/>
<!--
<hello> element
-->
<xs:element name="hello">
<xs:complexType>
<xs:sequence>
<xs:element name="capabilities">
<xs:complexType>
<xs:sequence>
<xs:element name="capability" type="xs:anyURI"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="session-id"
type="SessionId" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
<CODE ENDS>
]]></artwork>
</figure>
</t>
</section>
<section title="YANG Module for NETCONF Protocol Operations" anchor="yangmodule">
<t>
This section is normative.
<figure>
<artwork><![CDATA[
<CODE BEGINS> file "ietf-netconf@2010-06-04.yang"
module ietf-netconf {
// the namespace for NETCONF XML definitions has not changed
// this value is pre-determined by RFC 4741
namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
prefix nc;
import ietf-inet-types {
prefix inet;
}
organization
"IETF NETCONF (Network Configuration) Working Group";
contact
"WG Web: <http://tools.ietf.org/wg/netconf/>
WG List: <mailto:netconf@ietf.org>
WG Chair: Bert Wijnen
<mailto:bertietf@bwijnen.net>
WG Chair: Mehmet Ersue
<mailto:mehmet.ersue@nsn.com>
Editor: Martin Bjorklund
<mailto:mbj@tail-f.com>
Editor: Juergen Schoenwaelder
<mailto:j.schoenwaelder@jacobs-university.de>
Editor: Andy Bierman
<mailto:andy.bierman@brocade.com>";
description
"NETCONF Protocol Data Types and Protocol Operations.
Copyright (c) 2010 IETF Trust and the persons identified as
the document authors. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, is permitted pursuant to, and subject
to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents
(http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note
revision 2010-06-04 {
description
"Initial revision";
reference
"RFC XXXX: Network Configuration Protocol";
}
extension get-filter-element-attributes {
description
"If this extension is present within the
an 'anyxml' statement named 'filter', which must be
conceptually defined within the RPC input section
for the 'get' and 'get-config' protocol operations,
then the following unqualified XML attribute is
supported within the 'filter' element, within
a 'get' or 'get-config' protocol operation:
type : optional attribute with allowed
value strings 'subtree' and 'xpath'.
If missing, the default value is 'subtree'.
If the 'xpath' feature is supported, then the
following unqualified XML attribute is
also supported:
select: optional attribute containing a
string representing an XPath expression.
The 'type' attribute must be equal to 'xpath'
if this attribute is present.";
}
// NETCONF capabilities defined as features
feature writable-running {
description
"NETCONF :writable-running capability;
If the server advertises the :writable-running
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Writable-Running Capability#";
}
feature candidate {
description
"NETCONF :candidate capability;
If the server advertises the :candidate
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Candidate Configuration Capability#";
}
feature confirmed-commit {
if-feature candidate;
description
"NETCONF :confirmed-commit:1.1 capability;
If the server advertises the :confirmed-commit:1.1
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Confirmed Commit Capability#";
}
feature rollback-on-error {
description
"NETCONF :rollback-on-error capability;
If the server advertises the :rollback-on-error
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Rollback on Error Capability#";
}
feature validate {
description
"NETCONF :validate:1.1 capability;
If the server advertises the :validate:1.1
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Validate Capability#";
}
feature startup {
description
"NETCONF :startup capability;
If the server advertises the :startup
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#Distinct Startup Capability#";
}
feature url {
description
"NETCONF :url capability;
If the server advertises the :url
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#URL Capability#";
}
feature xpath {
description
"NETCONF :xpath capability;
If the server advertises the :xpath
capability for a session, then this feature must
also be enabled for that session. Otherwise,
this feature must not be enabled.";
reference "RFC XXXX, #X#XPath Capability#";
}
// NETCONF Simple Types
typedef session-id-type {
type uint32 {
range "1..max";
}
description
"NETCONF Session Id";
}
typedef session-id-or-zero-type {
type uint32;
description
"NETCONF Session Id or Zero to indicate none";
}
typedef error-tag-type {
type enumeration {
enum in-use {
description
"The request requires a resource that
already is in use.";
}
enum invalid-value {
description
"The request specifies an unacceptable value for one
or more parameters.";
}
enum too-big {
description
"The request or response (that would be generated) is
too large for the implementation to handle.";
}
enum missing-attribute {
description
"An expected attribute is missing.";
}
enum bad-attribute {
description
"An attribute value is not correct; e.g., wrong type,
out of range, pattern mismatch.";
}
enum unknown-attribute {
description
"An unexpected attribute is present.";
}
enum missing-element {
description
"An expected element is missing.";
}
enum bad-element {
description
"An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.";
}
enum unknown-element {
description
"An unexpected element is present.";
}
enum unknown-namespace {
description
"An unexpected namespace is present.";
}
enum access-denied {
description
"Access to the requested protocol operation, or
data model is denied because authorization failed.";
}
enum lock-denied {
description
"Access to the requested lock is denied because the
lock is currently held by another entity.";
}
enum resource-denied {
description
"Request could not be completed because of
insufficient resources.";
}
enum rollback-failed {
description
"Request to rollback some configuration change (via
rollback-on-error or discard-changes operations) was
not completed for some reason.";
}
enum data-exists {
description
"Request could not be completed because the relevant
data model content already exists. For example,
a 'create' operation was attempted on data that
already exists.";
}
enum data-missing {
description
"Request could not be completed because the relevant
data model content does not exist. For example,
a 'delete' operation was attempted on
data that does not exist.";
}
enum operation-not-supported {
description
"Request could not be completed because the requested
operation is not supported by this implementation.";
}
enum operation-failed {
description
"Request could not be completed because the requested
operation failed for some reason not covered by
any other error condition.";
}
enum partial-operation {
description
"This error-tag is obsolete, and SHOULD NOT be sent
by servers conforming to this document.";
}
}
description "NETCONF Error Tag";
reference "RFC XXXX, section YYY";
}
typedef error-severity-type {
type enumeration {
enum error {
description "Error severity";
}
enum warning {
description "Warning severity";
}
}
description "NETCONF Error Severity";
reference "RFC XXXX, section YYY";
}
typedef edit-operation-type {
type enumeration {
enum merge {
description
"The configuration data identified by the
element containing this attribute is merged
with the configuration at the corresponding
level in the configuration datastore identified
by the target parameter.";
}
enum replace {
description
"The configuration data identified by the element
containing this attribute replaces any related
configuration in the configuration datastore
identified by the target parameter. If no such
configuration data exists in the configuration
datastore, it is created. Unlike a
<copy-config> operation, which replaces the
entire target configuration, only the configuration
actually present in the config parameter is affected.";
}
enum create {
description
"The configuration data identified by the element
containing this attribute is added to the
configuration if and only if the configuration
data does not already exist in the configuration
datastore. If the configuration data exists, an
<rpc-error> element is returned with an
<error-tag> value of 'data-exists'.";
}
enum delete {
description
"The configuration data identified by the element
containing this attribute is deleted from the
configuration if and only if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, an <rpc-error> element is returned with
an <error-tag> value of 'data-missing'.";
}
enum remove {
description
"The configuration data identified by the element
containing this attribute is deleted from the
configuration if the configuration
data currently exists in the configuration
datastore. If the configuration data does not
exist, the 'remove' operation is silently ignored
by the server.";
}
}
default "merge";
description "NETCONF 'operation' attribute values";
reference "RFC XXXX, #X#<edit-config>#";
}
// NETCONF Standard Protocol Operations
rpc get-config {
description
"Retrieve all or part of a specified configuration.";
reference "RFC XXXX, #X#<get-config>#";
input {
container source {
description
"Particular configuration to retrieve.";
choice config-source {
mandatory true;
description
"The configuration to retrieve.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.
This is optional-to-implement on the server because
not all servers will support filtering for this
datastore.";
}
}
}
anyxml filter {
description
"Subtree or XPath filter to use.";
nc:get-filter-element-attributes;
}
}
output {
container data {
presence
"An empty data container indicates that the
request did not produce any results.";
description
"Copy of the source datastore subset which matched
the filter criteria (if any).";
}
}
}
rpc edit-config {
description
"The 'edit-config' operation loads all or part of a specified
configuration to the specified target configuration.";
reference "RFC XXXX, #X#<edit-config>#";
input {
container target {
description
"Particular configuration to edit.";
choice config-target {
mandatory true;
description
"The configuration target.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
if-feature writable-running;
type empty;
description
"The running configuration is the config source.";
}
}
}
leaf default-operation {
type enumeration {
enum merge {
description
"The default operation is merge.";
}
enum replace {
description
"The default operation is replace.";
}
enum none {
description
"There is no default operation.";
}
}
default "merge";
description
"The default operation to use.";
}
leaf test-option {
if-feature validate;
type enumeration {
enum test-then-set {
description
"The server will test and then set if no errors.";
}
enum set {
description
"The server will set without a test first.";
}
enum test-only {
description
"The server will only test and not set, even
if there are no errors.";
}
}
default "test-then-set";
description
"The test option to use.";
}
leaf error-option {
type enumeration {
enum stop-on-error {
description
"The server will stop on errors.";
}
enum continue-on-error {
description
"The server may continue on errors.";
}
enum rollback-on-error {
description
"The server will rollback on errors.
This value can only be used if the 'rollback-on-error'
feature is supported.";
}
}
default "stop-on-error";
description
"The error option to use.";
}
choice edit-content {
mandatory true;
description
"The content for the edit operation";
anyxml config {
description
"Inline Config content.";
}
leaf url {
if-feature url;
type inet:uri;
description
"URL based config content.";
}
}
}
}
rpc copy-config {
description
"Create or replace an entire configuration datastore with the
contents of another complete configuration datastore.";
reference "RFC XXXX, #X#<copy-config>#";
input {
container target {
description
"Particular configuration to copy to.";
choice config-target {
mandatory true;
description
"The configuration target of the copy operation.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
if-feature writable-running;
type empty;
description
"The running configuration is the config target.
This is optional-to-implement on the server.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
container source {
description
"Particular configuration to copy from.";
choice config-source {
mandatory true;
description
"The configuration source for the copy operation.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: 'config' element. Represents
an entire configuration datastore, not
a subset of the running datastore.";
}
}
}
}
}
rpc delete-config {
description
"Delete a configuration datastore.";
reference "RFC XXXX, #X#<delete-config>#";
input {
container target {
description
"Particular configuration to delete.";
choice config-target {
mandatory true;
description
"The configuration target to delete.";
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config target.";
}
}
}
}
}
rpc lock {
description
"The lock operation allows the client to lock the configuration
system of a device.";
reference "RFC XXXX, #X#<lock>#";
input {
container target {
description
"Particular configuration to lock";
choice config-target {
mandatory true;
description
"The configuration target to lock.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
type empty;
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
rpc unlock {
description
"The unlock operation is used to release a configuration lock,
previously obtained with the 'lock' operation.";
reference "RFC XXXX, #X#<unlock>#";
input {
container target {
description
"Particular configuration to unlock.";
choice config-target {
mandatory true;
description
"The configuration target to unlock.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config target.";
}
leaf running {
type empty;
description
"The running configuration is the config target.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config target.";
}
}
}
}
}
rpc get {
description
"Retrieve running configuration and device state information.";
reference "RFC XXXX, #X#<get>#";
input {
anyxml filter {
description
"This parameter specifies the portion of the system
configuration and state data to retrieve.";
nc:get-filter-element-attributes;
}
}
output {
container data {
presence
"An empty data container indicates that the filter
request did not match any results.";
description
"Copy of the running datastore subset and/or state
data which matched the filter criteria (if any).";
}
}
}
rpc close-session {
description
"Request graceful termination of a NETCONF session.";
reference "RFC XXXX, #X#<close-session>#";
}
rpc kill-session {
description
"Force the termination of a NETCONF session.";
reference "RFC XXXX, #X#<kill-session>#";
input {
leaf session-id {
type session-id-type;
mandatory true;
description
"Particular session to kill.";
}
}
}
rpc commit {
if-feature candidate;
description
"Commit the candidate configuration as the device's new
current configuration";
reference "RFC XXXX, #X#<commit>#";
input {
leaf confirmed {
if-feature confirmed-commit;
type empty;
description
"Requests a confirmed commit.";
reference "RFC XXXX, #X#<commit>#";
}
leaf confirm-timeout {
if-feature confirmed-commit;
type uint32 {
range "1..max";
}
units "seconds";
default "600"; // 10 minutes
description
"The timeout interval for a confirmed commit.";
reference "RFC XXXX, #X#<commit>#";
}
leaf persist {
if-feature confirmed-commit;
type string;
description
"This parameter is used to make a confirmed commit
persistent. A persistent confirmed commit is not aborted
if the NETCONF session terminates. The only way to abort a
persistent confirmed commit it to let the timer expire, or
to use the cancel-commit operation.
The value of this parameter is a token that must be given
in the 'persist-id' parameter of commit or cancel-commit in
order to confirm or cancel the persistent confirmed commit.
The token should be a random string.";
reference "RFC XXXX, #X#<commit>#";
}
leaf persist-id {
if-feature confirmed-commit;
type string;
description
"This parameter is given in order to commit a persistent
confirmed commit. The value must be equal to the value
given in the 'persist' parameter to the commit operation.
If it does not match, the operation fails with an
'invalid-value' error.";
reference "RFC XXXX, #X#<commit>#";
}
}
}
rpc discard-changes {
if-feature candidate;
description
"Revert the candidate configuration to the current
running configuration.";
reference "RFC XXXX, #X#<discard-changes>#";
}
rpc cancel-commit {
if-feature confirmed-commit;
description
"This operation is used to cancel an ongoing confirmed commit.
If the confirmed commit is persistent, the parameter
'persist-id' must be given, and it must match the value of the
'persist' parameter.";
reference "RFC XXXX, #X#<cancel-commit>#";
input {
leaf persist-id {
type string;
description
"This parameter is given in order to cancel a persistent
confirmed commit. The value must be equal to the value
given in the 'persist' parameter to the commit operation.
If it does not match, the operation fails with an
'invalid-value' error.";
}
}
}
rpc validate {
if-feature validate;
description
"Validates the contents of the specified configuration.";
reference "RFC XXXX, #X#<validate>#";
input {
container source {
description
"Particular configuration to validate.";
choice config-source {
mandatory true;
description
"The configuration source to validate.";
leaf candidate {
if-feature candidate;
type empty;
description
"The candidate configuration is the config source.";
}
leaf running {
type empty;
description
"The running configuration is the config source.";
}
leaf startup {
if-feature startup;
type empty;
description
"The startup configuration is the config source.";
}
leaf url {
if-feature url;
type inet:uri;
description
"The URL-based configuration is the config source.";
}
anyxml config {
description
"Inline Config content: 'config' element. Represents
an entire configuration datastore, not
a subset of the running datastore.";
}
}
}
}
}
}
<CODE ENDS>
]]></artwork>
</figure>
</t>
</section>
<?rfc needLines="30" ?>
<section title="Capability Template" anchor="capabilityTemplate">
<t>
This non-normative section defines a template that should be
used to define protocol capabilities. Data models written in
YANG usually do not need to define protocol capabilities
since the usage of YANG automatically leads to a capability
announcing the data model and any optional portions of the
data model, so called features in YANG terminology. The
capabilities template should only be used in cases where the
YANG mechanisms are not powerful enough (e.g., for handling
parametrized features) or a different data modeling language
is used.
</t>
<section title="capability-name (template)">
<section title="Overview">
</section>
<section title="Dependencies">
</section>
<section title="Capability Identifier">
<t>
The {name} capability is identified by the following capability string:
<list style="empty">
<t>{capability uri}</t>
</list>
</t>
</section>
<section title="New Operations">
<section title="<op-name>">
</section>
</section>
<section title="Modifications to Existing Operations">
<section title="<op-name>">
<t>If existing operations are not modified by this
capability, this section may be omitted.</t>
</section>
</section>
<section title="Interactions with Other Capabilities">
<t>If this capability does not interact with other
capabilities, this section may be omitted.</t>
</section>
</section>
</section>
<?rfc needLines="30" ?>
<section title="Configuring Multiple Devices with NETCONF" anchor="multidev">
<t>
This section is non-normative.
</t>
<section title="Operations on Individual Devices">
<t>
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.
</t>
<t>
Protecting each individual device consists of a number of steps:
<list style="symbols">
<t>Acquiring the configuration lock.</t>
<t>Checkpointing the running configuration.</t>
<t>Loading and validating the incoming configuration.</t>
<t>Changing the running configuration.</t>
<t>Testing the new configuration.</t>
<t>Making the change permanent (if desired).</t>
<t>Releasing the configuration lock.</t>
</list>
</t>
<t>
Let's look at the details of each step.
</t>
<section title="Acquiring the Configuration Lock">
<t>
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.
</t>
<t>
The lock can be acquired using the <lock> operation.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
]]></artwork>
</figure>
</t>
<t>
If the :candidate capability is supported, the candidate configuration
should be locked.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<lock>
<target>
<candidate/>
</target>
</lock>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="Checkpointing the Running Configuration">
<t>
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.
</t>
<t>
The checkpoint file can be created using the <copy‑config> operation.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<url>file://checkpoint.conf</url>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
]]></artwork>
</figure>
</t>
<t>
To restore the checkpoint file, reverse the source and target parameters.
</t>
</section>
<section title="Loading and Validating the Incoming Configuration.">
<t>
If the :candidate capability is supported, the configuration can be loaded onto the device without impacting the
running system.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<candidate/>
</target>
<config>
<!-- place incoming configuration changes here -->
</config>
</edit-config>
</rpc>
]]></artwork>
</figure>
</t>
<t>
If the device supports the :validate:1.1 capability, it will by
default validate the incoming configuration when it is loaded into
the candidate. To avoid this validation, pass the
<test‑option> parameter with the value "set". Full
validation can be requested with the <validate> operation.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="Changing the Running Configuration">
<t>
When the incoming configuration has been safely loaded onto the device
and validated, it is ready to impact the running system.
</t>
<t>
If the device supports the :candidate capability, use the <commit>
operation to set the running configuration to the candidate
configuration. Use the <confirmed> parameter to allow automatic
reversion to the original configuration if connectivity to the device
fails.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<confirm-timeout>120</confirm-timeout>
</commit>
</rpc>
]]></artwork>
</figure>
</t>
<t>
If the candidate is not supported by the device, the incoming configuration change is loaded directly into running.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<!-- place incoming configuration changes here -->
</config>
</edit-config>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="Testing the New Configuration">
<t>
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.
</t>
<t>
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).
</t>
</section>
<section title="Making the Change Permanent">
<t>
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.
</t>
<t>
If the device supports the :startup capability, the current
configuration can be saved to the startup configuration by using the
startup configuration as the target of the <copy‑config> operation.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<startup/>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
]]></artwork>
</figure>
</t>
<t>
If the device supports the :candidate capability and a confirmed
commit was requested, the confirming commit must be sent before the
timeout expires.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit/>
</rpc>
]]></artwork>
</figure>
</t>
</section>
<section title="Releasing the Configuration Lock">
<t>
When the configuration update is complete, the lock must be
released, allowing other applications access to the configuration.
</t>
<t>
Use the <unlock> operation to release the configuration lock.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<running/>
</target>
</unlock>
</rpc>
]]></artwork>
</figure>
</t>
<t>
If the :candidate capability is supported, the candidate configuration
should be unlocked.
<figure>
<artwork><![CDATA[
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
]]></artwork>
</figure>
</t>
</section>
</section>
<section title="Operations on Multiple Devices">
<t>
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.
</t>
<t>
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.
</t>
<t>
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.
</t>
<t>
To give transactional semantics, the same steps used in single device
operations listed above are used, but are performed in parallel across
all devices. Configuration locks should be acquired on all target
devices and kept until all devices are updated and the changes made
permanent. Configuration changes should be uploaded and validation
performed across all devices. Checkpoints should be made on each
device. Then the running configuration can be changed, tested, and
made permanent. If any of these steps fail, the previous
configurations can be restored on any devices upon which they were
changed. After the changes have been completely implemented or
completely discarded, the locks on each device can be released.
</t>
</section>
</section>
<section title="Changes from RFC 4741">
<t>
This section lists major changes between this document and RFC 4741.
<list style="symbols">
<t>
Added 'remove' enumeration value to
the operation attribute.
</t>
<t>
Obsoleted the 'partial-operation' error-tag
enumeration value.
</t>
<t>
Added <persist> and <persist-id>
parameters to the <commit> operation.
</t>
<t>
Updated the base protocol URI and clarified the
<hello> message exchange to select and
identify the base protocol version in use
for a particular session.
</t>
<t>
Added a YANG module to model the operations
and removed the operation layer from the XSD.
</t>
<t>
Clarified lock behavior for the candidate datastore.
</t>
<t>
Clarified the error response server requirements
for the 'delete' operation attribute enumeration
value.
</t>
<t>
Added a namespace wildcarding mechanism for subtree filtering.
</t>
<t>
Added a "test-only" value for the
<test‑option> parameter to the
<edit‑config> operation.
</t>
<t>
Added a <cancel‑commit> operation.
</t>
<t>
Introduced a NETCONF username and a requirement for
transport protocols to explain how a username is derived.
</t>
</list>
</t>
</section>
</back>
</rfc>
<!-- Local Variables: -->
<!-- tab-width: 2 -->
<!-- End: -->
| PAFTECH AB 2003-2026 | 2026-04-23 09:30:11 |