Network Working Group R. Enns, Editor
Internet-Draft Juniper Networks
Expires: August 14, 2004 February 14, 2004
NETCONF Configuration Protocol
draft-ietf-netconf-prot-02
Status of this Memo
This document is an Internet-Draft and is in full conformance with
all provisions of Section 10 of RFC2026.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as
Internet-Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at http://
www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 14, 2004.
Copyright Notice
Copyright (C) The Internet Society (2004). All Rights Reserved.
Abstract
There is a need for standardized mechanisms to manipulate, install,
edit, and delete the configuration of a network device. In addition,
there is a need to retrieve device state information and receive
asynchronous device state messages in a manner consistent with the
configuration mechanisms. There is great interest in using an
XML-based data encoding because a significant set of tools for
manipulating ASCII text and XML encoded data already exists.
Please send comments to netconf@ops.ietf.org. To subscribe, use
netconf-request@ops.ietf.org.
Enns, Editor Expires August 14, 2004 [Page 1]
Internet-Draft NETCONF Protocol February 2004
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 5
1.1 Protocol Overview . . . . . . . . . . . . . . . . . . . . . 6
1.2 Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 7
1.3 Separation of Configuration and State Data . . . . . . . . . 7
1.4 Terminology . . . . . . . . . . . . . . . . . . . . . . . . 8
1.4.1 Session . . . . . . . . . . . . . . . . . . . . . . . . . . 8
2. Application Protocol Requirements . . . . . . . . . . . . . 9
2.1 Connection-oriented operation . . . . . . . . . . . . . . . 9
2.2 Security and Privacy . . . . . . . . . . . . . . . . . . . . 9
2.3 Authentication . . . . . . . . . . . . . . . . . . . . . . . 9
3. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.1 Namespace . . . . . . . . . . . . . . . . . . . . . . . . . 11
3.2 <rpc> Element . . . . . . . . . . . . . . . . . . . . . . . 11
3.3 <rpc-reply> Element . . . . . . . . . . . . . . . . . . . . 12
3.4 <rpc-error> Element . . . . . . . . . . . . . . . . . . . . 12
3.5 <ok> Element . . . . . . . . . . . . . . . . . . . . . . . . 13
3.6 Pipelining . . . . . . . . . . . . . . . . . . . . . . . . . 13
4. Configuration Model . . . . . . . . . . . . . . . . . . . . 14
4.1 Configuration Datastores . . . . . . . . . . . . . . . . . . 14
5. Protocol Operations . . . . . . . . . . . . . . . . . . . . 15
5.1 <get-config> . . . . . . . . . . . . . . . . . . . . . . . . 15
5.2 <edit-config> . . . . . . . . . . . . . . . . . . . . . . . 18
5.3 <copy-config> . . . . . . . . . . . . . . . . . . . . . . . 22
5.4 <delete-config> . . . . . . . . . . . . . . . . . . . . . . 24
5.5 <lock> . . . . . . . . . . . . . . . . . . . . . . . . . . . 25
5.6 <unlock> . . . . . . . . . . . . . . . . . . . . . . . . . . 27
5.7 <get-all> . . . . . . . . . . . . . . . . . . . . . . . . . 28
5.8 <kill-session> . . . . . . . . . . . . . . . . . . . . . . . 29
6. Capabilities . . . . . . . . . . . . . . . . . . . . . . . . 31
6.1 Capabilities Exchange . . . . . . . . . . . . . . . . . . . 31
6.2 Manager Capability . . . . . . . . . . . . . . . . . . . . . 32
6.2.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 32
6.2.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 32
6.2.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 32
6.2.5 Modifications to Existing Operations . . . . . . . . . . . . 32
6.3 Agent Capability . . . . . . . . . . . . . . . . . . . . . . 32
6.3.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 32
6.3.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 33
6.3.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 33
6.3.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 33
6.3.5 Modifications to Existing Operations . . . . . . . . . . . . 33
6.4 Writable-Running Capability . . . . . . . . . . . . . . . . 33
6.4.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 33
6.4.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 33
6.4.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 33
Enns, Editor Expires August 14, 2004 [Page 2]
Internet-Draft NETCONF Protocol February 2004
6.4.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 33
6.4.5 Modifications to Existing Operations . . . . . . . . . . . . 34
6.5 Candidate Configuration Capability . . . . . . . . . . . . . 34
6.5.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 34
6.5.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 35
6.5.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 35
6.5.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 35
6.5.5 Modifications to Existing Operations . . . . . . . . . . . . 37
6.6 Validate Capability . . . . . . . . . . . . . . . . . . . . 38
6.6.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 38
6.6.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 38
6.6.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 38
6.6.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 39
6.7 Distinct Startup Capability . . . . . . . . . . . . . . . . 40
6.7.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 40
6.7.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 40
6.7.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 40
6.7.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 40
6.7.5 Modifications to Existing Operations . . . . . . . . . . . . 40
6.8 URL Capability . . . . . . . . . . . . . . . . . . . . . . . 41
6.8.1 Description . . . . . . . . . . . . . . . . . . . . . . . . 41
6.8.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 41
6.8.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 41
6.8.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 41
6.8.5 Modifications to Existing Operations . . . . . . . . . . . . 41
7. XML Usage Guidelines for NETCONF . . . . . . . . . . . . . . 43
7.1 No DTDs . . . . . . . . . . . . . . . . . . . . . . . . . . 43
7.2 Avoid Mixed Content . . . . . . . . . . . . . . . . . . . . 43
7.3 Use an Explicit Namespace on Attributes . . . . . . . . . . 43
7.4 Use Container Elements for Lists . . . . . . . . . . . . . . 44
7.5 Elements and Attributes . . . . . . . . . . . . . . . . . . 44
7.5.1 Consider Attributes as Metadata . . . . . . . . . . . . . . 44
7.5.2 Consider the Lack of Extensibility of Attributes . . . . . . 44
7.6 Proper Tag Names . . . . . . . . . . . . . . . . . . . . . . 44
7.7 Namespaces . . . . . . . . . . . . . . . . . . . . . . . . . 45
8. XML Schema for NETCONF RPC and Protocol Operations . . . . . 47
9. XML Schema for NETCONF State Data . . . . . . . . . . . . . 53
10. Security Considerations . . . . . . . . . . . . . . . . . . 56
11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 57
Normative References . . . . . . . . . . . . . . . . . . . . 58
Informative References . . . . . . . . . . . . . . . . . . . 59
Author's Address . . . . . . . . . . . . . . . . . . . . . . 59
A. Capability Template . . . . . . . . . . . . . . . . . . . . 60
A.1 capability-name (template) . . . . . . . . . . . . . . . . . 60
A.1.1 Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 60
A.1.2 Dependencies . . . . . . . . . . . . . . . . . . . . . . . . 60
A.1.3 Capability and Namespace . . . . . . . . . . . . . . . . . . 60
A.1.4 New Operations . . . . . . . . . . . . . . . . . . . . . . . 60
Enns, Editor Expires August 14, 2004 [Page 3]
Internet-Draft NETCONF Protocol February 2004
A.1.5 Modifications to Existing Operations . . . . . . . . . . . . 60
A.1.6 Interactions with Other Capabilities . . . . . . . . . . . . 60
B. Configuring Multiple Devices with NETCONF . . . . . . . . . 61
B.1 Operations on Individual Devices . . . . . . . . . . . . . . 61
B.1.1 Acquiring the Configuration Lock . . . . . . . . . . . . . . 61
B.1.2 Loading the Update . . . . . . . . . . . . . . . . . . . . . 62
B.1.3 Validating the Incoming Configuration . . . . . . . . . . . 63
B.1.4 Checkpointing the Running Configuration . . . . . . . . . . 64
B.1.5 Changing the Running Configuration . . . . . . . . . . . . . 64
B.1.6 Testing the New Configuration . . . . . . . . . . . . . . . 65
B.1.7 Making the Change Permanent . . . . . . . . . . . . . . . . 65
B.1.8 Releasing the Configuration Lock . . . . . . . . . . . . . . 66
B.2 Operations on Multiple Devices . . . . . . . . . . . . . . . 66
C. Change Log . . . . . . . . . . . . . . . . . . . . . . . . . 68
C.1 draft-ietf-netconf-prot-02 . . . . . . . . . . . . . . . . . 68
Intellectual Property and Copyright Statements . . . . . . . 69
Enns, Editor Expires August 14, 2004 [Page 4]
Internet-Draft NETCONF Protocol February 2004
1. Introduction
The NETCONF protocol defines a simple mechanism through which a
network device can be managed. Configuration data and system state
information can be retrieved. 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 straight-forward API to send and receive full and partial
configuration data sets.
NETCONF uses a remote procedure call (RPC) paradigm to define a
formal API for the network device. A client encodes an RPC in XML
[1] and sends it to a server using secure, connection-oriented
session. The server responds with a reply encoded in XML. The
contents of both the request and the response are fully described in
XML DTDs or XML schemas, or both, allowing both parties to recognize
the syntax constraints imposed on the exchange.
A key aspect of NETCONF is an attempt to allow the functionality of
the API to closely mirror the native functionality of the device.
This reduces implementation costs and allows timely access to new
features. In addition, applications can access both the syntactic
and semantic content of the device's native user interface.
NETCONF allows a client to discover the set of protocol extensions
supported by the 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 vendor-specific capabilities can
be defined with semantic and syntactic rigor. Capabilities are
discussed in Section 6.
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 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 [6] scripts from a
vendor-independent data schema into a form that is specific to the
vendor, product, operating system, and software release. The
resulting data can be passed to the device using the NETCONF
protocol.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
Enns, Editor Expires August 14, 2004 [Page 5]
Internet-Draft NETCONF Protocol February 2004
document are to be interpreted as described in RFC 2119 [2].
1.1 Protocol Overview
NETCONF uses a simple RPC-based mechanism to facilitate communication
between a client and a server. The client is a script or application
typically running as part of a network manager. The server is a
network device. The terms "device" and "server" are used
interchangeably in this document, as are "client" and "application".
NETCONF can be conceptually partitioned into four layers:
Layer Example
+-------------+ +-----------------------------+
| Content | | Configuration data |
+-------------+ +-----------------------------+
| |
+-------------+ +-----------------------------+
| Operations | | <get-config>, <edit-config> |
+-------------+ +-----------------------------+
| |
+-------------+ +-----------------------------+
| RPC | | <rpc>, <rpc-reply> |
+-------------+ +-----------------------------+
| |
+-------------+ +-----------------------------+
| Application | | BEEP, SSH, SSL, console |
| Protocol | | |
+-------------+ +-----------------------------+
1. The application protocol layer provides a communication path
between the client and server. NETCONF can be layered over any
application protocol that provides a set of basic requirements.
Section 2 discusses these requirements.
2. The RPC layer provides a simple, transport-independent framing
mechanism for encoding RPCs. Section 3 documents this protocol.
3. The operations layer defines a set of base operations invoked as
RPC methods with XML-encoded parameters. Section 5 details the
list of base operations.
4. The content layer is outside the scope of this document. Given
the current proprietary nature of the configuration data being
manipulated, the specification of this content depends on the
device vendor. It is expected that a separate effort to specify
a standard data definition language and standard content will be
undertaken.
Enns, Editor Expires August 14, 2004 [Page 6]
Internet-Draft NETCONF Protocol February 2004
1.2 Capabilities
A NETCONF capability is a set of functionality that supplements the
base NETCONF specification. The capability is identified by a
uniform resource identifier (URI). These URIs should follow the
guidelines as described in Section 6.
Capabilities augment the base operations of the device, describing
both additional operations and the content allowed inside operations.
The client can discover the server's capabilities and use any
additional operations, parameters, and content defined by those
capabilities.
The capability definition may name one or more dependent
capabilities. These capabilities must be implemented before the
first capability can function properly. To support a capability, the
server MUST support any capabilities upon which it depends.
Section 6 defines the capabilities exchange that allows the client to
discover the server's capabilities. Section 6 also lists the set of
capabilities defined in this document.
Additional capabilities can be defined at any time in external
documents, allowing the set of capabilities to expand over time.
Standards bodies may define standardized capabilities and vendors may
define proprietary ones. The URI MUST sufficiently distinguish the
naming authority to avoid naming collisions.
1.3 Separation of Configuration and State Data
The information that can be retrieved from a running system is
separated into two classes, configuration data and state data.
Configuration data is the set of writable data that is required to
transform a system from its initial default state into its current
state. State data is the additional data on a system that is not
configuration data such as read-only status information and collected
statistics. When a device is performing configuration operations a
number of problems would arise if state data were included:
o Comparisons of configuration files would be dominated by
irrelevant entries such as different statistics.
o A command to load the file would contain nonsensical commands such
as commands to write read-only data.
o The configuration file would be too large.
To account for these issues, the NETCONF protocol recognizes the
Enns, Editor Expires August 14, 2004 [Page 7]
Internet-Draft NETCONF Protocol February 2004
difference between configuration data and state data and provides
commands that operate on each independently. The <get-config>
command retrieves configuration data only while the <get-all> command
retrieves configuration and state data.
Note that the NETCONF protocol is concerned only with information
required to get the system software into its desired running state.
Other important persistent data such as user files and databases are
not treated as configuration data by the NETCONF protocol.
Similarly, the collection of configuration files stored on a system
(for example, the configuration files themselves) is not itself
included in configuration data.
If a local database of user authentication data is stored on the
device, whether it is included in configuration data is an
implementation dependent matter.
1.4 Terminology
1.4.1 Session
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 MAY
support more than one. Global configuration attributes can be
changed during any session, and the affects are visible in all
sessions. Session-specific attributes affect only the session in
which they are changed.
Enns, Editor Expires August 14, 2004 [Page 8]
Internet-Draft NETCONF Protocol February 2004
2. Application Protocol Requirements
NETCONF uses an RPC-based communication paradigm. A client sends a
series of one or more RPC request operations, which cause the server
to respond with a corresponding series of RPC replies.
The NETCONF protocol can be layered on any application protocol that
provides the required set of functionality. It is not bound to any
particular application protocol, but allows a mapping to define how
it can be implemented over any specific protocol.
This section details the characteristics that NETCONF requires from
the underlying application protocol.
2.1 Connection-oriented operation
NETCONF is connection-oriented, requiring a persistent connection
between peers. This connection must provide reliable, sequenced data
delivery.
NETCONF connections are long-lived, persisting between protocol
operations. This allows the client to make changes to the state of
the connection that will persist for the lifetime of the connection.
For example, authentication information specified for a connection
remains in effect until the connection is closed.
In addition, resources requested from the server for a particular
connection MUST be automatically released when the connection closes,
making failure recovery simpler and more robust. For example, when a
lock is acquired by a peer, the lock persists until either explicitly
released or the server is informed that the connection has been
terminated. If a connection is terminated while the client holds a
lock, the server can perform any appropriate recovery. The lock
operation is further discussed in Section 5.5
2.2 Security and Privacy
NETCONF connections must provide security and privacy. NETCONF
depends on the application protocol for this capability. A NETCONF
peer assumes that an appropriate level of security and privacy are
provided independent of this document. For example, connections may
be encrypted in TLS [4] (or SSH [10]), depending on the underlying
protocol.
2.3 Authentication
NETCONF connections must be authenticated. The application protocol
is responsible for authentication. The peer assumes that the
Enns, Editor Expires August 14, 2004 [Page 9]
Internet-Draft NETCONF Protocol February 2004
connection's authentication information has been validated by the
underlying protocol using sufficiently trustworthy mechanisms and
that the peer's entity can be trusted.
One goal of NETCONF is to provide a programmatic interface to the
device that closely follows the functionality of the device's native
interface. Therefore, it is expected that the underlying protocol
uses existing authentication mechanisms defined by the device. For
example, a device that supports RADIUS [5] should use RADIUS to
authenticate NETCONF sessions.
The authentication process should result in an entity whose
permissions and capabilities are known to the device. These
permissions must be enforced during the NETCONF session. For
example, if the native user interface restricts users from changing
the network interface configuration, the user should not be able to
change this configuration data using NETCONF.
Enns, Editor Expires August 14, 2004 [Page 10]
Internet-Draft NETCONF Protocol February 2004
3. RPC Model
The NETCONF protocol uses an RPC-based communication model. NETCONF
peers use <rpc> and <rpc-reply> elements to provide application
protocol-independent framing of NETCONF requests and responses.
3.1 Namespace
The <rpc> and <rpc-reply> elements are defined in the following
namespace:
http://ietf.org/netconf/base/1.0
3.2 <rpc> Element
The <rpc> element is used to enclose a NETCONF request sent from the
manager to the agent.
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 use
as a "message-id" attribute in any resulting <rpc-reply> message.
For example:
<rpc message-id="101" xmlns="http://ietf.org/netconf/base/1.0">
<some-method>
...
</some-method>
</rpc>
If additional attributes are present in an <rpc> element, a NETCONF
peer must return them unmodified in the <rpc-reply> element.
The name and parameters of an RPC are encoded as the contents of the
<rpc> element. The name of the RPC is an element directly inside the
<rpc> element, and any parameters are encoded inside this element.
The following example invokes a method called "my-own-method" which
has two parameters, "my-first-parameter", with a value of "14", and
"another-parameter", with a value of "fred":
<rpc message-id="102" xmlns="http://ietf.org/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>
Enns, Editor Expires August 14, 2004 [Page 11]
Internet-Draft NETCONF Protocol February 2004
</rpc>
The following example invokes a "rock-the-house" method with a
"zip-code" parameter of "27606-0100":
<rpc message-id="103" xmlns="http://ietf.org/netconf/base/1.0">
<rock-the-house xmlns="http://example.net/house/rock/1.0">
<zip-code>27606-0100</zip-code>
</rock-the-house>
</rpc>
The following example invokes the "rock-the-world" method with no
parameters:
<rpc message-id="104" xmlns="http://ietf.org/netconf/base/1.0">
<rock-the-world xmlns="http://example.net/house/rock/1.0"/>
</rpc>
3.3 <rpc-reply> Element
The <rpc-reply> message is sent in response to a <rpc> operation.
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.
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.
For example:
<rpc-reply message-id="101" xmlns="http://ietf.org/netconf/base/1.0">
<some-content>
...
</some-content>
</rpc-reply>
3.4 <rpc-error> Element
The <rpc-error> element is sent in <rpc-reply> messages if an error
occurs during the processing of an <rpc> request.
The <rpc-error> element includes the following information:
Enns, Editor Expires August 14, 2004 [Page 12]
Internet-Draft NETCONF Protocol February 2004
o tag: String identifying the error condition.
o error-code: Integer identifying the error condition.
o severity: String identifying the error severity, as determined by
the device.
o edit-path: Configuration data that provides the context for the
command that caused the error. This can be the empty string if
the command causing the error is located at the top level of the
command hierarchy.
o statement: Configuration or command that caused the error.
o message: String describing the error condition.
o action: Action taken by the device in response to this error.
[ed: A list of standard error codes is TBD. Both protocol error and
application error codes will be supported by <rpc-error>.]
<rpc-error message-id="102" xmlns="http://ietf.org/netconf/base/1.0">
<tag>EXAMPLE_MTU_RANGE</tag>
<error-code>128</error-code>
<severity>error</severity>
<statement>mtu 21050;</statement>
<message>MTU 21050 on Ethernet/1 is outside range 256..9192</message>
</rpc-error>
3.5 <ok> Element
The <ok> element is sent in <rpc-reply> messages if no error occurred
during the processing of an <rpc> request. For example:
<rpc-reply message-id="102" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
3.6 Pipelining
NETCONF <rpc> requests are 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.
Enns, Editor Expires August 14, 2004 [Page 13]
Internet-Draft NETCONF Protocol February 2004
4. Configuration Model
NETCONF provides an initial set of operations and a number of
capabilities that can be used to extend the base. NETCONF peers
exchange device capabilities when the session is initiated as
described in Section 6.1.
4.1 Configuration Datastores
NETCONF defines the existence of one or more configuration datastores
and allows configuration operations on them. A configuration
datastore is defined as the complete set of configuration data that
is required to get a device from its initial default state into a
desired operational state. The configuration datastore does not
include state data or executive commands.
Only the <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.
o Running: The complete configuration currently active on the
network device. Only one configuration datastore of this type
exists on the device, and it is always present. NETCONF protocol
operations refer to this datastore using the <running> element.
Section 6.5 and Section 6.7 define the <candidate> and <startup>
configuration datatores, respectively.
Enns, Editor Expires August 14, 2004 [Page 14]
Internet-Draft NETCONF Protocol February 2004
5. Protocol Operations
The NETCONF protocol provides a small set of low-level operations to
manage device configurations and retrieve device state information.
The base protocol provides operations to retrieve, configure, copy,
and delete configuration datastores. Additional operations are
provided, based on the capabilities advertised by the device.
The base protocol includes the following protocol operations:
o get-config
o edit-config
o copy-config
o delete-config
o lock
o unlock
o get-all
o kill-session
A protocol operation may fail for various reasons, including
"operation not supported". An initiator should not assume that any
operation will always succeed. The return values in any RPC reply
should be checked for error responses.
The syntax and XML encoding of the protocol operations are formally
defined in the XML schema in Section 8. The following sections
describe the semantics of each protocol operation.
5.1 <get-config>
Description:
Retrieve all or part of a specified configuration.
Parameters:
source: @config-name
Name of the configuration datastore being queried, such as
<running>.
Enns, Editor Expires August 14, 2004 [Page 15]
Internet-Draft NETCONF Protocol February 2004
config: @element-subtree
Portions of the configuration command subtree to retrieve.
The namespace of this configuration should be specified as
an attribute of this parameter. If this parameter is empty,
the entire configuration is returned. If the format
parameter is equal to "text", the contents of this parameter
are proprietary.
Positive Response:
If the device can satisfy the request, the server sends an
<rpc-reply> element containing a <config> element with the
results of the query.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
Example:
Enns, Editor Expires August 14, 2004 [Page 16]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="105" xmlns="http://ietf.org/netconf/base/1.0">
<get-config>
<source>
<running/>
</source>
<config xmlns="http://example.com/schema/1.2/config">
<users/>
</config>
<format>xml</format>
</get-config>
</rpc>
<rpc-reply message-id="105" xmlns="http://ietf.org/netconf/base/1.0">
<config xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>root</name>
<type>superuser</type>
<full-name>Charlie Root</full-name>
</user>
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
</user>
<user>
<name>barney</name>
<type>admin</type>
<full-name>Barney Rubble</full-name>
</user>
</users>
</config>
</rpc-reply>
The following example shows how additional nesting within the
<config> parameter can be used to filter more of the output in the
response:
Enns, Editor Expires August 14, 2004 [Page 17]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="106" xmlns="http://ietf.org/netconf/base/1.0">
<get-config>
<source>
<running/>
</source>
<config xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
</user>
</users>
</config>
<format>xml</format>
</get-config>
</rpc>
<rpc-reply message-id="106" xmlns="http://ietf.org/netconf/base/1.0">
<config xmlns="http://example.com/schema/1.2/config">
<users>
<user>
<name>fred</name>
<type>admin</type>
<full-name>Fred Flintstone</full-name>
</user>
</users>
</config>
</rpc-reply>
5.2 <edit-config>
Description:
Load 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 is created.
The device analyzes the source and target configurations and
performs the requested changes. The target configuration is
not simply replaced, as with the <copy-config> message.
Attributes:
operation: (merge | replace | delete) [default: merge]
Enns, Editor Expires August 14, 2004 [Page 18]
Internet-Draft NETCONF Protocol February 2004
Elements in the <config> subtree may contain an operation
attribute. The attribute identifies the point in the
configuration to perform the operation.
In the interest of simplicity, all operation attributes
appearing within the <config> subtree MUST have the same value.
If the operation attribute is not specified, the configuration
is merged into the configuration datastore.
The operation attribute has one of the following values:
merge: The configuration data identified by the element
containing this attribute is merged with the configuration
at the corresponding level in the configuration datastore
identified by the target parameter.
replace: The configuration data identified by the element
containing this attribute replaces any related configuration
in the configuration datastore identified by the target
parameter. Unlike a <copy-config> operation, which replaces
the entire target configuration, only the configuration
actually present in the config parameter is affected.
delete: The configuration data identified by the element
containing this attribute is deleted in the configuration
datastore identified by the target parameter.
[ed. The operation attribute needs to be added to the XML
schema in Section 8.]
Parameters:
target: @config-name
Configuration datastore being edited, such as <running>.
test-option: (test-then-set | set) [default: set]
test-then-set: Perform a validation test before attempting
to set; skip set if any errors.
set: Perform a set without a validation test first.
The test-option element may be specified only if the device
advertises the #validate capability (Section 6.6).
Enns, Editor Expires August 14, 2004 [Page 19]
Internet-Draft NETCONF Protocol February 2004
error-option: (stop-on-error | ignore-error) [default:
stop-on-error]
stop-on-error: Abort the rpc request on first error.
ignore-error: Continue to process configuration data on
error; error is recorded and negative response is generated
if any errors occur.
config: @element-tree
Portion of the configuration subtree to set. The namespace
of this configuration should be specified as an attribute of
this parameter.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent containing an <ok> element.
Negative Response:
An <rpc-error> response is sent if the request cannot be
completed for any reason.
Example: Set the MTU to 1500 on an interface named "Ethernet0/0" in
the running configuration:
<rpc message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns="http://example.com/schema/1.2/config">
<interface>
<name>Ethernet0/0</name>
<mtu>1500</mtu>
</interface>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
Enns, Editor Expires August 14, 2004 [Page 20]
Internet-Draft NETCONF Protocol February 2004
Add an interface named "Ethernet0/0" to the running configuration,
replacing any previous interface with that name:
<rpc message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns="http://example.com/schema/1.2/config"
xmlns:xc="http://ietf.org/netconf/base/1.0">
<interface xc:operation="replace">
<name>Ethernet0/0</name>
<mtu>1500</mtu>
<address>
<name>1.2.3.4</name>
<mask>255.0.0.0</mask>
</address>
</interface>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
Delete the interface named "Ethernet0/0" from the running
configuration:
<rpc message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns="http://example.com/schema/1.2/config"
xmlns:xc="http://ietf.org/netconf/base/1.0">
<interface xc:operation="delete">
<name>Ethernet0/0</name>
</interface>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
Enns, Editor Expires August 14, 2004 [Page 21]
Internet-Draft NETCONF Protocol February 2004
Delete interface 192.168.0.1 from an OSPF area (other interfaces
configured in the same area are unaffected):
<rpc message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<target>
<running/>
</target>
<config xmlns="http://example.com/schema/1.2/config"
xmlns:xc="http://ietf.org/netconf/base/1.0">
<protocols>
<ospf>
<area>
<name>0.0.0.0</name>
<interfaces>
<interface xc:operation="delete">
<name>192.168.0.1</name>
</interface>
</interfaces>
</area>
</ospf>
</protocols>
</config>
</edit-config>
</rpc>
<rpc-reply message-id="107" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
5.3 <copy-config>
Description:
Create or replace an entire configuration file with the
contents of another complete configuration file. If the target
file exists, it is overwritten; otherwise, a new file is
created.
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. The source and target parameters cannot
identify the same file.
The device may choose not to support format conversions with
this operation. The running and startup configurations are
Enns, Editor Expires August 14, 2004 [Page 22]
Internet-Draft NETCONF Protocol February 2004
considered to be format neutral, but all other configuration
files are created in a specific format (text or XML). A copy
operation on any of these format-specific files may fail if the
format parameter specifies a value different than the source
file format. It is suggested that the format parameter be
omitted in this type of operation, to select the source file
format.
Parameters:
source: @config-name | config
Name of the configuration datastore to use as the source of
the copy operation or the <config> element containing the
configuration subtree to copy.
target: @config-name
Name of the configuration datastore to use as the
destination of the copy operation.
format: (xml | text) [default: xml]
Format of the configuration file, either "xml" or "text".
The format of the source and target configurations must
match. Configuration datastores (such as <running>) match
either format.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that includes an <ok> element.
Negative Response:
An <rpc-error> element is included within the <rpc-reply> if
the request cannot be completed for any reason.
Example:
Enns, Editor Expires August 14, 2004 [Page 23]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="108" xmlns="http://ietf.org/netconf/base/1.0">
<copy-config>
<source>
<running/>
</source>
<target>
<url>ftp://example.com/configs/testbed-dec10.txt</url>
</target>
<format>text</format>
</copy-config>
</rpc>
<rpc-reply message-id="108" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
5.4 <delete-config>
Description:
Delete a configuration datastore. The <running> configuration
file cannot be deleted.
Parameters:
target: @config-name
Name of the configuration datastore to delete.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that includes an <ok> element.
Negative Response:
An <rpc-error> element is included within the <rpc-reply> if
the request cannot be completed for any reason.
Example:
Enns, Editor Expires August 14, 2004 [Page 24]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="108" xmlns="http://ietf.org/netconf/base/1.0">
<delete-config>
<target>
<startup/>
</target>
</delete-config>
</rpc>
<rpc-reply message-id="108" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
5.5 <lock>
Description:
The lock operation allows the client to lock the configuration
system of a device. Such locks are intended to be short-lived
and allow a client to make a change without fear of interaction
with other NETCONF clients, non-NETCONF clients (SNMP and
Expect scripts) and human users.
An attempt to lock the configuration MUST fail if an existing
session currently holds the lock.
When the lock is acquired, the server MUST prevent any changes
to the locked resource other than those requested by this
session. SNMP and CLI requests to modify the resource MUST
fail with an appropriate error.
The duration of the lock is defined as beginning when the lock
is acquired and lasting until either the lock is released or
the NETCONF session closes. The session closure may be
explicitly performed by the client, or implicitly performed by
the server based on criteria such as lack of network
connectivity, failure of the underlying transport, or simple
inactivity timeout. This criteria is dependent on the vendor's
implementation and the underlying transport.
The lock operation takes an OPTIONAL parameter, target. If the
target parameter is specified, it names the configuration that
will be locked. If the target parameter is not specified, then
by default the running configuration datastore 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 session. Additionally, the system will ensure that these
Enns, Editor Expires August 14, 2004 [Page 25]
Internet-Draft NETCONF Protocol February 2004
locked configuration resources will not be modified by other
non-NETCONF management operations such as SNMP and CLI. The
<kill-session> message (at the RPC layer) can be used to force
the release of a lock.
A lock will not be granted if any of the following conditions
are true:
+ a lock is already held by another session
+ the target configuration has already been modified and these
changes have not been committed
+ lock capability not supported
The server MUST respond with either an <ok> element or an
<rpc-error>.
A lock will be released by the system if the session holding
the lock is terminated for any reason.
Parameters:
target: @config-name [Optional]
Name of the configuration datastore to lock. If this
parameter is not present, then by default the running
configuration datastore will be locked.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason. This error
response will include the session number of the lock owner (if
failure due to lock already held).
Example:
Enns, Editor Expires August 14, 2004 [Page 26]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="120" xmlns="http://ietf.org/netconf/base/1.0">
<lock>
<target>
<running/>
</target>
</lock>
</rpc>
<rpc-reply message-id="120" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
5.6 <unlock>
Description:
The unlock operation is used to release a configuration lock,
previously obtained with the <lock> operation.
An unlock operation will not succeed if any of the following
conditions are true:
+ the specified lock is not currently active
+ the session issuing the <unlock> operation is not the same
session that obtained the lock
The server MUST respond with either an <ok> element or an
<rpc-error>.
Parameters:
target: @config-name [Optional]
Name of the configuration datastore to unlock. If this
parameter is not present, then by default the running
configuration datastore will be unlocked.
A NETCONF client is not permitted to unlock a configuration
datastore that it did not lock.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element.
Enns, Editor Expires August 14, 2004 [Page 27]
Internet-Draft NETCONF Protocol February 2004
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
Example:
<rpc message-id="121" xmlns="http://ietf.org/netconf/base/1.0">
<unlock>
<target>
<running/>
</target>
</unlock>
</rpc>
<rpc-reply message-id="121" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
5.7 <get-all>
Description:
Retrieve configuration and device state information. Section 9
describes the XML schema for NETCONF state data.
Parameters:
state: (@element-subtree | text)
If the <format> parameter is equal to "xml", this parameter
specifies the portion of the system state subtree to
retrieve. The namespace of this configuration should be
specified as an attribute of this parameter. If the
<format> parameter is equal to "text", the contents of this
parameter are proprietary. If this parameter is empty, all
the device state information are returned.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent. The <state> section contains the appropriate subset.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
Enns, Editor Expires August 14, 2004 [Page 28]
Internet-Draft NETCONF Protocol February 2004
Example:
<rpc message-id="109" xmlns="http://ietf.org/netconf/base/1.0">
<get-all>
<state xmlns="http://example.com/schema/1.2/int-stats">
<interface name="ethernet0/1">
<intstats></intstats>
</interface>
</state>
<format>xml</format>
</get-all>
</rpc>
<rpc-reply message-id="109" xmlns="http://ietf.org/netconf/base/1.0">
<state xmlns="http://example.com/schema/1.2/int-stats">
<interface name="ethernet0/1">
<intstats>
<inPkts>9456823</inPkts>
<inOctets>1228484566</inOctets>
<inErrors>4326</inErrors>
<outPkts>4821050</outPkts>
<outOctets>634712154</outOctets>
<outErrors>2096</outErrors>
</intstats>
</interface>
</state>
</rpc-reply>
5.8 <kill-session>
Description:
Force the termination of a NETCONF session.
Parameters:
session-id: (Positive Integer)
Session identifier of the NETCONF session to be terminated.
If this value is equal to the current session ID, a 'Bad
Value' error is sent.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that includes an <ok> element.
Enns, Editor Expires August 14, 2004 [Page 29]
Internet-Draft NETCONF Protocol February 2004
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
Example:
<rpc message-id="110" xmlns="http://ietf.org/netconf/base/1.0">
<kill-session>
<session-id>4</session-id>
</kill-session>
</rpc>
<rpc-reply message-id="110" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
Enns, Editor Expires August 14, 2004 [Page 30]
Internet-Draft NETCONF Protocol February 2004
6. Capabilities
This section defines a set of capabilities that a client or a server
MAY implement. Each peer advertises its capabilities by sending them
during an initial capabilities exchange. Each peer needs to
understand only those capabilities that it might use and must be able
to process and ignore any capability received from the other peer
that it does not require or does not understand.
Additional capabilities can be defined using the template in Appendix
A. Future capability definitions may be published as standards by
standards bodies or published as propriety by vendors.
A capability is identified with a URI, in the form:
http://{naming authority}/{protocol}/{category}/{version}#{name}
Capabilities defined in this document have the following format:
http://ietf.org/netconf/base/1.0#{name}
where {name} is the name of the capability. Capabilities are often
referenced in discussions and email using the shorthand #{name}. For
example, the foo capability would have the formal name "http://
ietf.org/netconf/base/1.0#foo" and be called "#foo". The shorthand
form MUST NOT be used inside the protocol.
6.1 Capabilities Exchange
A NETCONF capability is a set of additional functionality implemented
on top of the base NETCONF specification. The capability is
distinguished by a URI. These URIs should follow the guidelines as
described in Section 7.7.
Capabilities are advertised in messages sent on the NETCONF channel
when each peer starts operation. When the NETCONF channel is opened,
each peer sends a <hello> element containing a list of that peer's
capabilities.
In the following example, the peer advertises the base NETCONF
capability, one NETCONF capability defined in the base NETCONF
document, and one vendor-specific capability.
Enns, Editor Expires August 14, 2004 [Page 31]
Internet-Draft NETCONF Protocol February 2004
<hello>
<capabilities>
<capability>http://ietf.org/netconf/base/1.0</capability>
<capability>http://ietf.org/netconf/base/1.0#startup</capability>
<capability>http:/example.net/router/2.3/core#cool-feature</capability>
</capabilities>
</hello>
Each peer sends its <hello> element simultaneously as soon as the
connection is open. A peer MUST NOT wait to receive the capability
set from the other side before sending its own set.
6.2 Manager Capability
6.2.1 Description
The #manager capability indicates that this NETCONF peer intends to
manage the other peer using the NETCONF protocol.
6.2.2 Dependencies
None.
6.2.3 Capability and Namespace
The #manager capability is identified by the following capability
string:
http://ietf.org/netconf/base/1.0#manager
The #manager capability uses the base NETCONF namespace URI.
6.2.4 New Operations
None.
6.2.5 Modifications to Existing Operations
None.
6.3 Agent Capability
6.3.1 Description
The #agent capability indicates that this NETCONF peer is willing to
be managed using the NETCONF protocol.
Enns, Editor Expires August 14, 2004 [Page 32]
Internet-Draft NETCONF Protocol February 2004
6.3.2 Dependencies
None.
6.3.3 Capability and Namespace
The #agent capability is identified by the following capability
string:
http://ietf.org/netconf/base/1.0#agent
The #agent capability uses the base NETCONF namespace URI.
6.3.4 New Operations
None.
6.3.5 Modifications to Existing Operations
None.
6.4 Writable-Running Capability
6.4.1 Description
The #writable-running capability indicates that the device supports
writes directly to the <running> configuration datastore. In other
words, the device supports edit-config and copy-config operations
where the <running> configuration is the target.
6.4.2 Dependencies
None.
6.4.3 Capability and Namespace
The #writable-running capability is identified by the following
capability string:
http://ietf.org/netconf/base/1.0#writable-running
The #writable-running capability uses the base NETCONF namespace URI.
6.4.4 New Operations
None.
Enns, Editor Expires August 14, 2004 [Page 33]
Internet-Draft NETCONF Protocol February 2004
6.4.5 Modifications to Existing Operations
6.4.5.1 <edit-config>
The #writable-running capability modifies the <edit-config> operation
to accept the <running> element as a <target>.
6.4.5.2 <copy-config>
The #writable-running capability modifies the <copy-config> operation
to accept the <running> element as a <target>.
6.5 Candidate Configuration Capability
6.5.1 Description
The candidate configuration capability, #candidate, indicates that
the device supports a candidate configuration datastore, which is
used to hold configuration data that can 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 a 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.
The candidate configuration can be used as a source or target of any
operation with a <source> or <target> parameter. The <candidate>
element is used to indicate the candidate configuration:
<rpc message-id="112" xmlns="http://ietf.org/netconf/base/1.0">
<operation>
<source>
<candidate/>
</source>
</operation>
</rpc>
The candidate configuration may be shared among multiple sessions.
Unless a client has specific information that the candidate
configuration is not shared (for example, through another
capability), it must assume that other sessions may be able to modify
the candidate configuration at the same time. It is therefore
prudent for a client to lock the candidate configuration before
modifying it.
The client can discard any changes since the last <commit> operation
Enns, Editor Expires August 14, 2004 [Page 34]
Internet-Draft NETCONF Protocol February 2004
by executing the <discard-changes> operation. The candidate
configuration's content then reverts to the current committed
configuration.
6.5.2 Dependencies
None.
6.5.3 Capability and Namespace
The #candidate capability is identified by the following capability
string:
http://ietf.org/netconf/base/1.0#candidate
The #candidate capability uses the base NETCONF namespace URI.
6.5.4 New Operations
6.5.4.1 <commit>
Description:
When a candidate configuration's content is complete, the
configuration data can be committed, publishing the data set to
the rest of the device and requesting the device to conform to
the behavior described in the new configuration.
To commit the candidate configuration as the device's new
current configuration, use the <commit> operation.
The <commit> operation instructs the device to implement the
configuration data contained in the candidate configuration.
If the system does not have the #candidate capability, the
<commit> operation is not available.
Parameters:
confirmed:
The <confirmed> element indicates that the <commit>
operation MUST be reverted if a confirming commit is not
issued within ten (10) minutes. The timeout period can be
adjusted with the <confirm-timeout> element.
Enns, Editor Expires August 14, 2004 [Page 35]
Internet-Draft NETCONF Protocol February 2004
confirmed-timeout: Timeout period for confirmed commit, in
minutes.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
Example:
<rpc message-id="113" xmlns="http://ietf.org/netconf/base/1.0">
<commit/>
</rpc>
<rpc-reply message-id="113" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
<rpc message-id="114" xmlns="http://ietf.org/netconf/base/1.0">
<commit>
<confirmed/>
<confirm-timeout>20</confirmed-timeout>
</commit>
</rpc>
<rpc-reply message-id="114" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
</rpc-reply>
6.5.4.2 <discard-changes>
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 committed configuration.
<rpc xmlns="http://ietf.org/netconf/base/1.0">
<discard-changes/>
</rpc>
This operation discards any uncommitted changes.
Enns, Editor Expires August 14, 2004 [Page 36]
Internet-Draft NETCONF Protocol February 2004
6.5.5 Modifications to Existing Operations
6.5.5.1 <lock> and <unlock>
The candidate configuration can be locked using the <lock> operation
with the <candidate> element as the <target> parameter:
<rpc message-id="115" xmlns="http://ietf.org/netconf/base/1.0">
<lock>
<target>
<candidate/>
</target>
</lock>
</rpc>
Similarly, the candidate configuration is unlocked using the
<candidate> element as the <target> parameter:
<rpc message-id="1151" xmlns="http://ietf.org/netconf/base/1.0">
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
On devices implementing the #candidate capability the default target
of the <lock> and <unlock> operations is the candidate configuration
datastore.
Devices implementing the #candidate capability WILL NOT allow a
configuration lock to be acquired when there are outstanding changes
to the candidate configuration. An error WILL be returned and the
status of the lock will remain unchanged.
When a client fails with outstanding changes to the candidate
configuration, recovery can be difficult. To facilitate easy
recovery, the #candidate capability adds a <discard-changes> element
to the <lock> operation. If this element contains the value
"automatic", any outstanding changes are discarded when the lock is
released, whether explicitly with the <unlock> operation or
implicitly from session failure.
Enns, Editor Expires August 14, 2004 [Page 37]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="116" xmlns="http://ietf.org/netconf/base/1.0">
<lock>
<target>
<candidate/>
</target>
<discard-changes>automatic</discard-changes>
</lock>
</rpc>
6.5.5.2 <get-config> and <edit-config>
The candidate configuration is the default target for the
<edit-config> and <get-config> operations. It may be explicitly
named using the <candidate> element:
<rpc message-id="117" xmlns="http://ietf.org/netconf/base/1.0">
<get-config>
<source>
<candidate/>
</source>
</get-config>
</rpc>
6.6 Validate Capability
6.6.1 Description
Validation consists of checking a candidate configuration for
syntactical and semantic errors before applying the configuration to
the device.
If this capability is advertised, the device supports the <validate>
protocol operation and checks at least for syntax errors. In
addition, this capability supports the validate parameter to the
<edit-config> operation and, when it is provided, checks at least for
syntax errors.
6.6.2 Dependencies
None.
6.6.3 Capability and Namespace
The #validate capability is identified by the following capability
string:
Enns, Editor Expires August 14, 2004 [Page 38]
Internet-Draft NETCONF Protocol February 2004
http://ietf.org/netconf/base/1.0#validate
The #validate capability uses the base NETCONF namespace URI.
6.6.4 New Operations
6.6.4.1 <validate>
Description:
This protocol operation validates the contents of the specified
configuration.
Parameters:
source: @config-name
Name of the configuration datastore being validated, such as
<candidate>.
Positive Response:
If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element.
Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason.
A validate operation can fail for any of the following reasons:
+ Syntax errors
+ Missing parameters
+ References to undefined configuration data
Example:
<rpc message-id="118" xmlns="http://ietf.org/netconf/base/1.0">
<validate>
<candidate/>
</validate>
</rpc>
<rpc-reply message-id="118" xmlns="http://ietf.org/netconf/base/1.0">
<ok/>
Enns, Editor Expires August 14, 2004 [Page 39]
Internet-Draft NETCONF Protocol February 2004
</rpc-reply>
6.7 Distinct Startup Capability
6.7.1 Description
The device supports separate running and startup configuration
datastores. Operations which 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.
6.7.2 Dependencies
None.
6.7.3 Capability and Namespace
The #startup capability is identified by the following capability
string:
http://ietf.org/netconf/base/1.0#startup
The #startup capability uses the base NETCONF namespace URI.
6.7.4 New Operations
None.
6.7.5 Modifications to Existing Operations
6.7.5.1 <copy-config>
To save the startup configuration, use the copy-config command to
copy the <running> configuration datastore to the <startup>
configuration datastore.
Enns, Editor Expires August 14, 2004 [Page 40]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="119" xmlns="http://ietf.org/netconf/base/1.0">
<copy-config>
<source>
<running/>
</source>
<target>
<startup/>
</target>
<format>text</format>
</copy-config>
</rpc>
6.8 URL Capability
6.8.1 Description
The NETCONF peer has the ability to accept the <url> element in
<source> and <target> parameters. The capability is further
identified by URL arguments indicating the protocols supported.
6.8.2 Dependencies
None.
6.8.3 Capability and Namespace
The #url capability is identified by the following capability string:
http://ietf.org/netconf/base/1.0#url?protocol={protocol-name,...}
The #url capability uses the base NETCONF namespace URI.
The #url capability URI MUST contain a "protocol" argument assigned a
comma-separated list of protocol names indicating which protocols the
NETCONF peer supports. For example:
http://ietf.org/netconf/base/1.0#url?protocol=http,ftp,file
The #url capability uses the base NETCONF namespace URI.
6.8.4 New Operations
None.
6.8.5 Modifications to Existing Operations
Enns, Editor Expires August 14, 2004 [Page 41]
Internet-Draft NETCONF Protocol February 2004
6.8.5.1 <edit-config>
The #url capability modifies the <edit-config> operation to accept
the <url> element as the <config> parameter.
6.8.5.2 <copy-config>
The #url capability modifies the <copy-config> operation to accept
the <url> element as the value of the the <source> and the <target>
parameters.
6.8.5.3 <delete-config>
The #url capability modifies the <delete-config> operation to accept
the <url> element as the value of the the <target> parameters. If
this parameter contains a URL, then it should identify a local
configuration file.
6.8.5.4 <validate>
The #url capability modifies the <validate> operation to accept the
<url> element as the value of the the <source> parameter.
Enns, Editor Expires August 14, 2004 [Page 42]
Internet-Draft NETCONF Protocol February 2004
7. XML Usage Guidelines for NETCONF
XML serves as an 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.
To simplify manipulation of NETCONF content, use of XML is restricted
to a simple subset of XML, as described in this section.
7.1 No DTDs
Document type declarations (DTDs) are not permitted to appear in
NETCONF content.
7.2 Avoid Mixed Content
Mixed content is defined as elements that can contain both data and
other elements. Elements in NETCONF can contain either data or
additional elements only.
This greatly simplifies the complexity of parsing XML, especially in
the area of significant whitespace. Whitespace inside data elements
is significant. Whitespace outside data elements is not.
<valid>
<element>data</element>
<more>data</more>
</valid>
<not-valid>
<element>data<more>data</more>maybe some</element>
</not-valid>
7.3 Use an Explicit Namespace on Attributes
All attributes should be prefixed so that they belong to a specific
namespace. This encourages meaningful definitions that are free of
collisions.
<valid xmlns="http://valid/" xmlns:v="http://valid/" v:foo="cool"></valid>
<not-valid xmlns="http://not-valid/" foo="not-cool"></not-valid>
Enns, Editor Expires August 14, 2004 [Page 43]
Internet-Draft NETCONF Protocol February 2004
7.4 Use Container Elements for Lists
When encoding lists with multiple instances, use a distinct container
element, preferably the plural form of the instance element.
In this example, the element 'grommet' is contained within the
'grommets' element.
<valid>
<grommets>
<grommet>....</grommet>
<grommet>....</grommet>
<grommet>....</grommet>
</grommets>
</valid>
Use of container elements allows simpler manipulation of lists and
list members.
7.5 Elements and Attributes
The choice of elements and attributes has been widely discussed, but
no absolute guidelines exist. When designing encoding rules for
NETCONF content, the following guidelines should be used:
7.5.1 Consider Attributes as Metadata
Attributes should contain metadata about the element, not true data.
By extension, vital information should not be encoded in attributes.
7.5.2 Consider the Lack of Extensibility of Attributes
Attributes are unordered, can appear only once, and can have no
children. Data scenarios which must leave room for future expansion
(in future specifications or future software releases) should avoid
attributes.
7.6 Proper Tag Names
When choosing element names, consider the following guidelines:
o Prefer ASCII (7-bit).
o Prefer lowercase.
o Prefer dashes to underscores.
o Prefer full words. Note that "config" is considered a full word.
Enns, Editor Expires August 14, 2004 [Page 44]
Internet-Draft NETCONF Protocol February 2004
These are guidelines only and should be considered secondary to the
need for consistency with existing vocabularies. For example, when
encoding MIB variables names in NETCONF, use the existing names
(ifAddr) instead of shifting to these guidelines (if-address). These
guidelines are valuable when no common vocabulary exists, because
they help to avoid the scenario in which a dozen developers choose a
dozen names that differ in ways that lead to frustrating
inconsistencies, such as ifaddr, if-addr, if-address,
interface-address, intf-addr, iaddr, and iface-addr.
7.7 Namespaces
A namespace URI uniquely identifies the content and meaning of an XML
element. When designing XML namespaces for NETCONF content, the
following guidelines should be used:
o Prefer domain names in URIs. Use the domain name of the
organization that controls the content of the scheme.
o Prefer version numbers in namespaces. Use dates when version
numbers are not appropriate. Versions should be formatted in
strings that are consistent with the software being referenced.
Dates should be formatted as "YYYY-MM-DD".
o Prefer URLish URIs, but do not expect them all to be reachable or
meaningful. While URIs are not URLs and are not required to
reference any resource, using non-URL syntax is needlessly
confusing. For example, the following URI looks like a programmer
mistake:
ietf.org:/rfc/rfc1234.txt
The model namespace looks like:
http://${naming-authority}/${topic}/${version}/${area}
For example:
http://ietf.org/netconf/base/1.0-config
In this usage, 'topic' might be the product name, 'version' might be
the software version, and 'area' might be the portion of that
software documented in this particular namespace.
http://example.net/magic-os/84.1.3/bgp
The ${topic} segment might contain a qualifying hierarchy. For
example, if the Puff Router Company has a large set of operating
Enns, Editor Expires August 14, 2004 [Page 45]
Internet-Draft NETCONF Protocol February 2004
systems targeted at differing market segments, it may express this
relationship in the ${topic}:
http://example.net/embedded/magic-os/84.1.3/bgp
Enns, Editor Expires August 14, 2004 [Page 46]
Internet-Draft NETCONF Protocol February 2004
8. XML Schema for NETCONF RPC and Protocol Operations
<?xml version="1.0" encoding="UTF-8"?>
<xsd:schema targetNamespace="http://ietf.org/netconf/base/1.0"
xmlns:xc="http://ietf.org/netconf/base/1.0"
xmlns:xsd="http://www.w3.org/2001/XMLSchema"
elementFormDefault="unqualified">
<xsd:complexType name="rpcType">
<xsd:sequence>
<xsd:element ref="xc:rpcOperation"/>
</xsd:sequence>
<xsd:attribute name="message-id" type="xsd:string" use="required"/>
</xsd:complexType>
<xsd:element name="rpc" type="xc:rpcType"/>
<xsd:complexType name="rpc-errorType">
<xsd:sequence>
<xsd:element name="tag" type="xsd:string" minOccurs="0"/>
<xsd:element name="error-code" type="xsd:integer" minOccurs="0"/>
<xsd:element name="severity" type="xsd:string" minOccurs="0"/>
<xsd:element name="edit-path" type="xsd:string" minOccurs="0"/>
<xsd:element name="statement" type="xsd:string" minOccurs="0"/>
<xsd:element name="message" type="xsd:string" minOccurs="0"/>
<xsd:element name="action" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:complexType>
<xsd:complexType name="rpc-replyType">
<xsd:choice>
<xsd:element name="ok" minOccurs="0"/>
<xsd:element name="rpc-error"
type="xc:rpc-errorType" minOccurs="0"/>
<xsd:element ref="xc:config" minOccurs="0"/>
<xsd:element ref="xc:state" minOccurs="0"/>
</xsd:choice>
<xsd:attribute name="message-id" type="xsd:string" use="required"/>
</xsd:complexType>
<xsd:element name="rpc-reply" type="xc:rpc-replyType"/>
<xsd:simpleType name="responseAttributeType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="terse"/>
<xsd:enumeration value="full"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:simpleType name="test-optionType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="test"/>
<xsd:enumeration value="test-then-set"/>
<xsd:enumeration value="set"/>
Enns, Editor Expires August 14, 2004 [Page 47]
Internet-Draft NETCONF Protocol February 2004
</xsd:restriction>
</xsd:simpleType>
<xsd:element name="test-option" type="xc:test-optionType"/>
<xsd:simpleType name="error-optionType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="stop-on-error"/>
<xsd:enumeration value="ignore-error"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:element name="error-option" type="xc:error-optionType"/>
<xsd:complexType name="rpcOperationType">
<xsd:attribute name="response" type="xc:responseAttributeType"
default="terse"/>
</xsd:complexType>
<xsd:element name="rpcOperation" type="xc:rpcOperationType"
abstract="true"/>
<xsd:simpleType name="configFormatType">
<xsd:restriction base="xsd:string">
<xsd:enumeration value="xml"/>
<xsd:enumeration value="text"/>
</xsd:restriction>
</xsd:simpleType>
<xsd:element name="format" type="xc:configFormatType"/>
<xsd:complexType name="config-inlineType">
<xsd:complexContent>
<xsd:extension base="xsd:anyType">
<xsd:attribute name="format" type="xc:configFormatType"/>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="config" type="xc:config-inlineType"/>
<xsd:element name="state" type="xc:config-inlineType"/>
<xsd:complexType name="config-nameType"/>
<xsd:element name="config-name" type="xc:config-nameType"
abstract="true"/>
<xsd:element name="startup" type="xc:config-nameType"
substitutionGroup="xc:config-name"/>
<xsd:element name="candidate" type="xc:config-nameType"
substitutionGroup="xc:config-name"/>
<xsd:element name="running" type="xc:config-nameType"
substitutionGroup="xc:config-name"/>
<xsd:complexType name="config-uriType">
<xsd:simpleContent>
<xsd:extension base="xsd:anyURI">
<xsd:attribute name="format" type="xc:configFormatType"/>
</xsd:extension>
</xsd:simpleContent>
</xsd:complexType>
Enns, Editor Expires August 14, 2004 [Page 48]
Internet-Draft NETCONF Protocol February 2004
<xsd:element name="url" type="xc:config-uriType"/>
<xsd:complexType name="rpcOperationSourceType">
<xsd:choice>
<xsd:element ref="xc:config"/>
<xsd:element ref="xc:config-name"/>
<xsd:element ref="xc:url"/>
</xsd:choice>
</xsd:complexType>
<xsd:element name="source" type="xc:rpcOperationSourceType"/>
<xsd:complexType name="rpcOperationTargetType">
<xsd:choice>
<xsd:element ref="xc:config-name"/>
<xsd:element ref="xc:url"/>
</xsd:choice>
</xsd:complexType>
<xsd:element name="target" type="xc:rpcOperationTargetType"/>
<xsd:complexType name="get-configType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:source"/>
<xsd:element ref="xc:config" minOccurs="0"/>
<xsd:element ref="xc:format" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="get-config" type="xc:get-configType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="edit-configType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:source" minOccurs="0"/>
<xsd:element ref="xc:target"/>
<xsd:element ref="xc:test-option" minOccurs="0"/>
<xsd:element ref="xc:write-option" minOccurs="0"/>
<xsd:element ref="xc:error-option" minOccurs="0"/>
<xsd:element ref="xc:config" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="edit-config" type="xc:edit-configType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="copy-configType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
Enns, Editor Expires August 14, 2004 [Page 49]
Internet-Draft NETCONF Protocol February 2004
<xsd:sequence>
<xsd:element ref="xc:source"/>
<xsd:element ref="xc:target"/>
<xsd:element ref="xc:format"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="copy-config" type="xc:copy-configType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="delete-configType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:target"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="delete-config" type="xc:delete-configType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="get-allType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:state"/>
<xsd:element ref="xc:format" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="get-all" type="xc:get-allType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="lockType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:target"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="lock" type="xc:lockType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="unlockType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
Enns, Editor Expires August 14, 2004 [Page 50]
Internet-Draft NETCONF Protocol February 2004
<xsd:element ref="xc:target"/>
<xsd:element name="discard-changes" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="unlock" type="xc:unlockType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="validateType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element ref="xc:source"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="validate" type="xc:validateType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="commitType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element name="confirmed" minOccurs="0"/>
<xsd:element name="confirmed-timeout" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="commit" type="xc:commitType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="discard-changesType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType"/>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="discard-changes" type="xc:discard-changesType"
substitutionGroup="xc:rpcOperation"/>
<xsd:complexType name="kill-sessionType">
<xsd:complexContent>
<xsd:extension base="xc:rpcOperationType">
<xsd:sequence>
<xsd:element name="session-id" type="xsd:string" minOccurs="0"/>
</xsd:sequence>
</xsd:extension>
</xsd:complexContent>
</xsd:complexType>
<xsd:element name="kill-session" type="xc:kill-sessionType"
Enns, Editor Expires August 14, 2004 [Page 51]
Internet-Draft NETCONF Protocol February 2004
substitutionGroup="xc:rpcOperation"/>
</xsd:schema>
Enns, Editor Expires August 14, 2004 [Page 52]
Internet-Draft NETCONF Protocol February 2004
9. XML Schema for NETCONF State Data
<schema
targetNamespace="http://ietf.org/netconf/1.0/state"
xmlns="http://www.w3.org/2001/XMLSchema"
xmlns:xc="http://ietf.org/netconf/1.0/state"
elementFormDefault="unqualified">
<annotation>
<documentation xml:lang="en">
Initial schema for NETCONF state information.
</documentation>
</annotation>
<element name="netconf-state">
<complexType>
<sequence>
<element name="capabilities">
<annotation>
<documentation xml:lang="en">
List of NETCONF capabilities supported by this device.
</documentation>
</annotation>
<complexType>
<sequence>
<element name="capability" type="anyURI"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
<element name="sessions">
<annotation>
<documentation xml:lang="en">
List of NETCONF sessions currently active on this device.
</documentation>
</annotation>
<complexType>
<sequence>
<element name="my-session-id" type="positiveInteger"/>
<element name="session" type="xc:NetconfSessionInfo"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
Enns, Editor Expires August 14, 2004 [Page 53]
Internet-Draft NETCONF Protocol February 2004
<element name="configs">
<annotation>
<documentation xml:lang="en">
List of NETCONF configuration databases supported on this device.
</documentation>
</annotation>
<complexType>
<sequence>
<element name="config" type="xc:NetconfConfigInfo"
minOccurs="0" maxOccurs="unbounded"/>
</sequence>
</complexType>
</element>
</sequence>
</complexType>
</element>
<complexType name="NetconfSessionInfo">
<sequence>
<element name="session-id" type="positiveInteger"/>
<element name="username" type="string"/>
<element name="login-time" type="dateTime"/>
</sequence>
</complexType>
<complexType name="NetconfConfigInfo">
<sequence>
<element name="config-name" type="xc:ConfigName"/>
<element name="lock-status" type="xc:LockStatus"/>
</sequence>
</complexType>
<complexType name="ConfigName">
<choice>
<element name="candidate"/>
<element name="running"/>
<element name="startup"/>
</choice>
</complexType>
<complexType name="LockStatus">
<sequence>
<element name="lock-state">
<simpleType>
<restriction base="string">
<enumeration value="locked"/>
<enumeration value="unlocked"/>
Enns, Editor Expires August 14, 2004 [Page 54]
Internet-Draft NETCONF Protocol February 2004
</restriction>
</simpleType>
</element>
<element name="locked-by" type="positiveInteger"
minOccurs="0"/>
</sequence>
</complexType>
</schema>
Enns, Editor Expires August 14, 2004 [Page 55]
Internet-Draft NETCONF Protocol February 2004
10. Security Considerations
Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves
devices open to classic so-called "person in the middle" attacks.
Configuration information often times contains passwords, user names,
service descriptions, and topological information, all of which are
sensitive.
The protocol, therefore, must minimally support options for both
confidentiality and authentication.
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 then a simple "permission 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.
Enns, Editor Expires August 14, 2004 [Page 56]
Internet-Draft NETCONF Protocol February 2004
11. Authors and Acknowledgements
This document was written by:
Andy Bierman, Cisco Systems
Ken Crozier, Cisco Systems
Rob Enns, Juniper Networks
Ted Goddard, Wind River
Eliot Lear, Cisco Systems
David Perkins, Riverstone Networks
Phil Shafer, Juniper Networks
Steve Waldbusser
Margaret Wasserman, Wind River
Enns, Editor Expires August 14, 2004 [Page 57]
Internet-Draft NETCONF Protocol February 2004
Normative References
[1] Bray, T., Paoli, J., Sperberg-McQueen, C. and E. Maler,
"Extensible Markup Language (XML) 1.0 (Second Edition)", W3C REC
REC-xml-20001006, October 2000.
[2] Bradner, S., "Key words for use in RFCs to Indicate Requirement
Levels", BCP 14, RFC 2119, March 1997.
[3] Myers, J., "Simple Authentication and Security Layer (SASL)",
RFC 2222, October 1997.
[4] Dierks, T., Allen, C., Treese, W., Karlton, P., Freier, A. and
P. Kocher, "The TLS Protocol Version 1.0", RFC 2246, January
1999.
[5] Rigney, C., Willens, S., Rubens, A. and W. Simpson, "Remote
Authentication Dial In User Service (RADIUS)", RFC 2865, June
2000.
Enns, Editor Expires August 14, 2004 [Page 58]
Internet-Draft NETCONF Protocol February 2004
Informative References
[6] Clark, J., "XSL Transformations (XSLT) Version 1.0", W3C REC
REC-xslt-19991116, November 1999.
[7] Hollenbeck, S., Rose, M. and L. Masinter, "Guidelines for the
Use of Extensible Markup Language (XML) within IETF Protocols",
BCP 70, RFC 3470, January 2003.
[8] Boyer, J., "Canonical XML Version 1.0", RFC 3076, March 2001.
[9] Rose, M., "The Blocks Extensible Exchange Protocol Core", RFC
3080, March 2001.
[10] Ylonen, T., Kivinen, T., Saarinen, M., Rinne, T. and S.
Lehtinen, "SSH Protocol Architecture",
draft-ietf-secsh-architecture-14 (work in progress), July 2003.
Author's Address
Rob Enns
Juniper Networks
1194 North Mathilda Ave
Sunnyvale, CA 94089
US
EMail: rpe@juniper.net
Enns, Editor Expires August 14, 2004 [Page 59]
Internet-Draft NETCONF Protocol February 2004
Appendix A. Capability Template
A.1 capability-name (template)
A.1.1 Overview
A.1.2 Dependencies
A.1.3 Capability and Namespace
The {name} is identified by following capability string:
http://ietf.org/netconf/base/1.0#{name}
The {name} capability uses the base NETCONF namespace URI.
A.1.4 New Operations
A.1.4.1 <op-name>
A.1.5 Modifications to Existing Operations
A.1.5.1 <op-name>
If existing operations are not modified by this capability, this
section may be omitted.
A.1.6 Interactions with Other Capabilities
If this capability does not interact with other capabilities, this
section may be omitted.
Enns, Editor Expires August 14, 2004 [Page 60]
Internet-Draft NETCONF Protocol February 2004
Appendix B. Configuring Multiple Devices with NETCONF
B.1 Operations on Individual Devices
Consider the work involved in performing a configuration update
against a single individual device. In making a change to the
configuration, the application needs to build trust that its change
has been made correctly and that it has not impacted the operation of
the device. The application (and the application user) should feel
confident that their change has not damaged the network.
Protecting each individual device consists of a number of steps:
o Acquiring the configuration lock.
o Loading the update.
o Validating the incoming configuration.
o Checkpointing the running configuration.
o Changing the running configuration.
o Testing the new configuration.
o Making the change permanent (if desired).
o Releasing the configuration lock.
Let's look at the details of each step.
B.1.1 Acquiring the Configuration Lock
A lock should be acquired to prevent simultaneous updates from
multiple sources. If multiple sources are affecting the device, the
application is hampered in both testing of its change to the
configuration and in recovery should the update fail. Acquiring a
short-lived lock is a simple defense to prevent other parties from
introducing unrelated changes while.
The lock can be acquired using the <lock> operation.
<rpc message-id="201" xmlns="http://ietf.org/netconf/base/1.0">
<lock>
<target>
<running/>
</target>
</lock>
Enns, Editor Expires August 14, 2004 [Page 61]
Internet-Draft NETCONF Protocol February 2004
</rpc>
If the #candidate capability is also supported, failure recovery can
be simplified by using the <discard-changes> parameter.
<rpc message-id="202" xmlns="http://ietf.org/netconf/base/1.0">
<lock>
<target>
<candidate/>
</target>
<discard-changes>automatic</discard-changes>
</lock>
</rpc>
B.1.2 Loading the Update
The configuration can be loaded onto the device without impacting the
running system. If the #url capability is supported, incoming
changes can be placed in a local file.
<rpc message-id="203" xmlns="http://ietf.org/netconf/base/1.0">
<copy-config>
<source>
<config>
<!-- place incoming configuration here -->
</config>
</source>
<target>
<url>file://incoming.conf</url>
</target>
<format>text</format>
</copy-config>
</rpc>
If the #candidate capability is supported, the candidate
configuration can be used.
Enns, Editor Expires August 14, 2004 [Page 62]
Internet-Draft NETCONF Protocol February 2004
<rpc message-id="204" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<source>
<config>
<!-- place incoming configuration here -->
</config>
</source>
<target>
<candidate/>
</target>
</edit-config>
</rpc>
If the update fails, the user file can be deleted using the
<delete-config> operation or the candidate configuration reverted
using the <discard-changes> operation.
B.1.3 Validating the Incoming Configuration
Before applying the incoming configuration, it is often useful to
validate it. Validation allows the application to gain confidence
that the change will succeed and simplifies recovery if it does not.
If the device supports the #url capability, use the <validate>
operation with the <source> parameter set to the proper user file:
<rpc message-id="205" xmlns="http://ietf.org/netconf/base/1.0">
<validate>
<source>
<url>file://incoming.conf</url>
</source>
</validate>
</rpc>
If the device supports the #candidate capability, some validation
will be performed as part of loading the incoming configuration into
the candidate. For full validation, either pass the <validate>
parameter during the <edit-config> step given above, or use the
<validate> operation with the <source> parameter set to <candidate>.
<rpc message-id="206" xmlns="http://ietf.org/netconf/base/1.0">
<validate>
<source>
<candidate/>
</source>
</validate>
</rpc>
Enns, Editor Expires August 14, 2004 [Page 63]
Internet-Draft NETCONF Protocol February 2004
B.1.4 Checkpointing the Running Configuration
The running configuration can be saved into a local file as a
checkpoint before loading the new configuration. If the update
fails, the configuration can be restored by reloading the checkpoint
file.
The checkpoint file can be created using the <copy-config> operation.
<rpc message-id="207" xmlns="http://ietf.org/netconf/base/1.0">
<copy-config>
<source>
<running/>
</source>
<target>
<url>file://checkpoint.conf</url>
</target>
<format>text</format>
</copy-config>
</rpc>
To restore the checkpoint file, reverse the source and target
parameters.
B.1.5 Changing the Running Configuration
When the incoming configuration has been safely loaded onto the
device and validated, it is ready to impact the running system.
If the device supports the #url capability, use the <edit-config>
operation to merge the incoming configuration into the running
configuration.
<rpc message-id="208" xmlns="http://ietf.org/netconf/base/1.0">
<edit-config>
<source>
<url>file://incoming.conf</url>
</source>
<target>
<running/>
</target>
</edit-config>
</rpc>
If the device supports the #candidate capability, use the <commit>
operation to set the running configuration to the candidate
configuration. Use the <confirm> parameter to allow automatic
reverting to the original configuration if connectivity to the device
Enns, Editor Expires August 14, 2004 [Page 64]
Internet-Draft NETCONF Protocol February 2004
fails.
<rpc message-id="209" xmlns="http://ietf.org/netconf/base/1.0">
<commit>
<confirmed/>
<confirm-timeout>15</confirm-timeout>
</commit>
</rpc>
B.1.6 Testing the New Configuration
Now that the incoming configuration has been integrated into the
running configuration, the application needs to gain trust that the
change has affected the device in the way intended without affecting
it negatively.
To gain this confidence, the application can run tests of the
operational state of the device. The nature of the test is dependent
on the nature of the change and is outside the scope of this
document. Such tests may include reachability from the system
running the application (using ping), changes in reachability to the
rest of the network (by comparing the device's routing table), or
inspection of the particular change (looking for operational evidence
of the BGP peer that was just added).
B.1.7 Making the Change Permanent
When the configuration change is in place and the application has
sufficient faith in the proper function of this change, the
application should make the change permanent.
If the device supports the #startup capability, the current
configuration can be saved to the startup configuration by using the
startup configuration as the target of the <copy-config> operation.
<rpc message-id="210" xmlns="http://ietf.org/netconf/base/1.0">
<copy-config>
<source>
<running/>
</source>
<target>
<startup/>
</target>
<format>text</format>
</copy-config>
</rpc>
Enns, Editor Expires August 14, 2004 [Page 65]
Internet-Draft NETCONF Protocol February 2004
If the device supports the #candidate capability and a confirmed
commit was requested, the confirming commit must be sent before the
timeout expires.
<rpc message-id="211" xmlns="http://ietf.org/netconf/base/1.0">
<commit/>
</rpc>
B.1.8 Releasing the Configuration Lock
When the configuration update is complete, the lock must be released,
allowing other applications access to the configuration.
Use the <unlock> operation to release the configuration lock.
<rpc message-id="212" xmlns="http://ietf.org/netconf/base/1.0">
<unlock/>
</rpc>
B.2 Operations on Multiple Devices
When a configuration change requires updates across a number of
devices, care should be taken to provide the required transaction
semantics. The NETCONF protocol contains sufficient primitives upon
which transaction-oriented operations can be built. Providing
complete transactional semantics across multiple devices is
prohibitively expensive, but the size and number of windows for
failure scenarios can be reduced.
There are two classes of multidevice operations. The first class of
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.
A example of this class might be adding an NTP server. For this
class of operations, failure avoidance and recovery are focused on
the individual device. This means recovery of the device, reporting
the failure, and perhaps scheduling another attempt.
The second class is more interesting, requiring that the operation
should complete on all devices or be fully reversed. The network
should either be transformed into a new state or be reset to its
original state. For example, a change to a VPN may require updates
to a number of devices. Another example of this might be adding a
class-of-service definition. Leaving the network in a state where
only a portion of the devices have been updated with the new
definition will lead to future failures when the definition is
Enns, Editor Expires August 14, 2004 [Page 66]
Internet-Draft NETCONF Protocol February 2004
referenced.
To give transactional semantics, the same steps used in single device
operations listed above are used, but are performed in parallel
across all devices. Configuration locks should be acquired on all
target devices and kept until all devices are updated and the changes
made permanent. Configuration changes should be uploaded and
validation performed across all devices. Checkpoints should be made
on each device. Then the running configuration can be changed,
tested, and made permanent. If any of these steps fail, the previous
configurations can be restored on any devices upon which it was
changed. After the changes have been completely implemented or
completely discarded, the locks on each device can be released.
Enns, Editor Expires August 14, 2004 [Page 67]
Internet-Draft NETCONF Protocol February 2004
Appendix C. Change Log
This appendix will be removed before publication as RFC.
C.1 draft-ietf-netconf-prot-02
Refer to the NETCONF issue list for futher detail on the issue
numbers below. The issue list is found at http://www.nextbeacon.com/
netconf/.
o Remove <rpc-abort>, <rpc-abort-reply>, and <rpc-progress> (issues
12.1, 12.2, 12.3).
o Remove channels (issues 3.*).
o Remove notifications (issues 2.*, 4.2, 13.9, 13.10, 13.11).
o Move version number to last component of the capability URI (issue
11.1.1).
o Remove format parameter from <get-config> (issue 13.3.3).
o Remove mention of #lock capability from Appendix B. Locking is a
mandatory NETCONF operation.
o Added text indicating that attributes received in <rpc> should be
echoed on <rpc-reply> (issue 16.1).
o Reworded Section 7.3 to encourage always prefixing attributes with
namespaces.
Enns, Editor Expires August 14, 2004 [Page 68]
Internet-Draft NETCONF Protocol February 2004
Intellectual Property Statement
The IETF takes no position regarding the validity or scope of any
intellectual property or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; neither does it represent that it
has made any effort to identify any such rights. Information on the
IETF's procedures with respect to rights in standards-track and
standards-related documentation can be found in BCP-11. Copies of
claims of rights made available for publication and any assurances of
licenses to be made available, or the result of an attempt made to
obtain a general license or permission for the use of such
proprietary rights by implementors or users of this specification can
be obtained from the IETF Secretariat.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights which may cover technology that may be required to practice
this standard. Please address the information to the IETF Executive
Director.
Full Copyright Statement
Copyright (C) The Internet Society (2004). All Rights Reserved.
This document and translations of it may be copied and furnished to
others, and derivative works that comment on or otherwise explain it
or assist in its implementation may be prepared, copied, published
and distributed, in whole or in part, without restriction of any
kind, provided that the above copyright notice and this paragraph are
included on all such copies and derivative works. However, this
document itself may not be modified in any way, such as by removing
the copyright notice or references to the Internet Society or other
Internet organizations, except as needed for the purpose of
developing Internet standards in which case the procedures for
copyrights defined in the Internet Standards process must be
followed, or as required to translate it into languages other than
English.
The limited permissions granted above are perpetual and will not be
revoked by the Internet Society or its successors or assignees.
This document and the information contained herein is provided on an
"AS IS" basis and THE INTERNET SOCIETY AND THE INTERNET ENGINEERING
TASK FORCE DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING
BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION
Enns, Editor Expires August 14, 2004 [Page 69]
Internet-Draft NETCONF Protocol February 2004
HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Acknowledgement
Funding for the RFC Editor function is currently provided by the
Internet Society.
Enns, Editor Expires August 14, 2004 [Page 70]
