draft-ietf-netconf-4741bis-09.txt   draft-ietf-netconf-4741bis-10.txt 
Network Working Group R. Enns, Ed. Network Working Group R. Enns, Ed.
Internet-Draft Juniper Networks Internet-Draft Juniper Networks
Obsoletes: 4741 (if approved) M. Bjorklund, Ed. Obsoletes: 4741 (if approved) M. Bjorklund, Ed.
Intended status: Standards Track Tail-f Systems Intended status: Standards Track Tail-f Systems
Expires: August 16, 2011 J. Schoenwaelder, Ed. Expires: September 15, 2011 J. Schoenwaelder, Ed.
Jacobs University Jacobs University
A. Bierman, Ed. A. Bierman, Ed.
Brocade Brocade
February 12, 2011 March 14, 2011
Network Configuration Protocol (NETCONF) Network Configuration Protocol (NETCONF)
draft-ietf-netconf-4741bis-09 draft-ietf-netconf-4741bis-10
Abstract Abstract
The Network Configuration Protocol (NETCONF) defined in this document The Network Configuration Protocol (NETCONF) defined in this document
provides mechanisms to install, manipulate, and delete the provides mechanisms to install, manipulate, and delete the
configuration of network devices. It uses an Extensible Markup configuration of network devices. It uses an Extensible Markup
Language (XML)-based data encoding for the configuration data as well Language (XML)-based data encoding for the configuration data as well
as the protocol messages. The NETCONF protocol operations are as the protocol messages. The NETCONF protocol operations are
realized as Remote Procedure Calls (RPC). realized as Remote Procedure Calls (RPC). This document obsoletes
RFC 4741.
Status of this Memo Status of this Memo
This Internet-Draft is submitted in full conformance with the This Internet-Draft is submitted in full conformance with the
provisions of BCP 78 and BCP 79. provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on August 16, 2011. This Internet-Draft will expire on September 15, 2011.
Copyright Notice Copyright Notice
Copyright (c) 2011 IETF Trust and the persons identified as the Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 3, line 10 skipping to change at page 3, line 10
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 6
1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7 1.1. Terminology . . . . . . . . . . . . . . . . . . . . . . . 7
1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8 1.2. Protocol Overview . . . . . . . . . . . . . . . . . . . . 8
1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 9 1.3. Capabilities . . . . . . . . . . . . . . . . . . . . . . 10
1.4. Separation of Configuration and State Data . . . . . . . 10 1.4. Separation of Configuration and State Data . . . . . . . 10
2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12 2. Transport Protocol Requirements . . . . . . . . . . . . . . . 12
2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 12 2.1. Connection-Oriented Operation . . . . . . . . . . . . . . 12
2.2. Authentication, Integrity, and Confidentiality . . . . . 12 2.2. Authentication, Integrity, and Confidentiality . . . . . 12
2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 13 2.3. Mandatory Transport Protocol . . . . . . . . . . . . . . 13
3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 14 3. XML Considerations . . . . . . . . . . . . . . . . . . . . . 14
3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 14 3.1. Namespace . . . . . . . . . . . . . . . . . . . . . . . . 14
3.2. Document Type Declarations . . . . . . . . . . . . . . . 14 3.2. Document Type Declarations . . . . . . . . . . . . . . . 14
4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 15 4. RPC Model . . . . . . . . . . . . . . . . . . . . . . . . . . 15
4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 15 4.1. <rpc> Element . . . . . . . . . . . . . . . . . . . . . . 15
skipping to change at page 5, line 20 skipping to change at page 5, line 20
8.9.5. Modifications to Existing Operations . . . . . . . . 75 8.9.5. Modifications to Existing Operations . . . . . . . . 75
9. Security Considerations . . . . . . . . . . . . . . . . . . . 77 9. Security Considerations . . . . . . . . . . . . . . . . . . . 77
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 79
10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 79 10.1. NETCONF XML Namespace . . . . . . . . . . . . . . . . . . 79
10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 79 10.2. NETCONF XML Schema . . . . . . . . . . . . . . . . . . . 79
10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 79 10.3. NETCONF YANG Module . . . . . . . . . . . . . . . . . . . 79
10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 79 10.4. NETCONF Capability URNs . . . . . . . . . . . . . . . . . 79
11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 81 11. Authors and Acknowledgements . . . . . . . . . . . . . . . . 81
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 82 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 82
12.1. Normative References . . . . . . . . . . . . . . . . . . 82 12.1. Normative References . . . . . . . . . . . . . . . . . . 82
12.2. Informative References . . . . . . . . . . . . . . . . . 82 12.2. Informative References . . . . . . . . . . . . . . . . . 83
Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 84 Appendix A. NETCONF Error List . . . . . . . . . . . . . . . . . 84
Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 88 Appendix B. XML Schema for NETCONF Messages Layer . . . . . . . 88
Appendix C. YANG Module for NETCONF Protocol Operations . . . . 93 Appendix C. YANG Module for NETCONF Protocol Operations . . . . 93
Appendix D. Capability Template . . . . . . . . . . . . . . . . 113 Appendix D. Capability Template . . . . . . . . . . . . . . . . 113
D.1. capability-name (template) . . . . . . . . . . . . . . . 113 D.1. capability-name (template) . . . . . . . . . . . . . . . 113
D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 113 D.1.1. Overview . . . . . . . . . . . . . . . . . . . . . . 113
D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 113 D.1.2. Dependencies . . . . . . . . . . . . . . . . . . . . 113
D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 113 D.1.3. Capability Identifier . . . . . . . . . . . . . . . . 113
D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 113 D.1.4. New Operations . . . . . . . . . . . . . . . . . . . 113
D.1.5. Modifications to Existing Operations . . . . . . . . 113 D.1.5. Modifications to Existing Operations . . . . . . . . 113
skipping to change at page 6, line 16 skipping to change at page 6, line 16
The NETCONF protocol defines a simple mechanism through which a The NETCONF protocol defines a simple mechanism through which a
network device can be managed, configuration data information can be network device can be managed, configuration data information can be
retrieved, and new configuration data can be uploaded and retrieved, and new configuration data can be uploaded and
manipulated. The protocol allows the device to expose a full, formal manipulated. The protocol allows the device to expose a full, formal
application programming interface (API). Applications can use this application programming interface (API). Applications can use this
straightforward API to send and receive full and partial straightforward API to send and receive full and partial
configuration data sets. configuration data sets.
The NETCONF protocol uses a remote procedure call (RPC) paradigm. A The NETCONF protocol uses a remote procedure call (RPC) paradigm. A
client encodes an RPC in XML [1] and sends it to a server using a client encodes an RPC in XML [W3C.REC-xml-20001006] and sends it to a
secure, connection-oriented session. The server responds with a server using a secure, connection-oriented session. The server
reply encoded in XML. The contents of both the request and the responds with a reply encoded in XML. The contents of both the
response are fully described in XML DTDs or XML schemas, or both, request and the response are fully described in XML DTDs or XML
allowing both parties to recognize the syntax constraints imposed on schemas, or both, allowing both parties to recognize the syntax
the exchange. constraints imposed on the exchange.
A key aspect of NETCONF is that it allows the functionality of the A key aspect of NETCONF is that it allows the functionality of the
management protocol to closely mirror the native functionality of the management protocol to closely mirror the native functionality of the
device. This reduces implementation costs and allows timely access device. This reduces implementation costs and allows timely access
to new features. In addition, applications can access both the to new features. In addition, applications can access both the
syntactic and semantic content of the device's native user interface. syntactic and semantic content of the device's native user interface.
NETCONF allows a client to discover the set of protocol extensions NETCONF allows a client to discover the set of protocol extensions
supported by a server. These "capabilities" permit the client to supported by a server. These "capabilities" permit the client to
adjust its behavior to take advantage of the features exposed by the adjust its behavior to take advantage of the features exposed by the
device. The capability definitions can be easily extended in a device. The capability definitions can be easily extended in a
noncentralized manner. Standard and non-standard capabilities can be noncentralized manner. Standard and non-standard capabilities can be
defined with semantic and syntactic rigor. Capabilities are defined with semantic and syntactic rigor. Capabilities are
discussed in Section 8. discussed in Section 8.
The NETCONF protocol is a building block in a system of automated The NETCONF protocol is a building block in a system of automated
configuration. XML is the lingua franca of interchange, providing a configuration. XML is the lingua franca of interchange, providing a
flexible but fully specified encoding mechanism for hierarchical flexible but fully specified encoding mechanism for hierarchical
content. NETCONF can be used in concert with XML-based content. NETCONF can be used in concert with XML-based
transformation technologies, such as XSLT [11], to provide a system transformation technologies, such as XSLT [W3C.REC-xslt-19991116], to
for automated generation of full and partial configurations. The provide a system for automated generation of full and partial
system can query one or more databases for data about networking configurations. The system can query one or more databases for data
topologies, links, policies, customers, and services. This data can about networking topologies, links, policies, customers, and
be transformed using one or more XSLT scripts from a task-oriented, services. This data can be transformed using one or more XSLT
vendor-independent data schema into a form that is specific to the scripts from a task-oriented, vendor-independent data schema into a
vendor, product, operating system, and software release. The form that is specific to the vendor, product, operating system, and
resulting data can be passed to the device using the NETCONF software release. The resulting data can be passed to the device
protocol. using the NETCONF protocol.
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this
document are to be interpreted as described in RFC 2119 [3]. document are to be interpreted as described in RFC 2119 [RFC2119].
1.1. Terminology 1.1. Terminology
o candidate configuration datastore: A configuration datastore that o candidate configuration datastore: A configuration datastore that
can be manipulated without impacting the device's current can be manipulated without impacting the device's current
configuration and that can be committed to the running configuration and that can be committed to the running
configuration datastore. Not all devices support a candidate configuration datastore. Not all devices support a candidate
configuration datastore. configuration datastore.
o capability: A functionality that supplements the base NETCONF o capability: A functionality that supplements the base NETCONF
skipping to change at page 9, line 35 skipping to change at page 9, line 35
Figure 1: NETCONF Protocol Layers Figure 1: NETCONF Protocol Layers
1. The Secure Transport layer provides a communication path between 1. The Secure Transport layer provides a communication path between
the client and server. NETCONF can be layered over any transport the client and server. NETCONF can be layered over any transport
protocol that provides a set of basic requirements. Section 2 protocol that provides a set of basic requirements. Section 2
discusses these requirements. discusses these requirements.
2. The Messages layer provides a simple, transport-independent 2. The Messages layer provides a simple, transport-independent
framing mechanism for encoding RPCs and notifications. Section 4 framing mechanism for encoding RPCs and notifications. Section 4
documents the RPC messages, and [8] documents notifications. documents the RPC messages, and [RFC5717] documents
notifications.
3. The Operations layer defines a set of base protocol operations 3. The Operations layer defines a set of base protocol operations
invoked as RPC methods with XML-encoded parameters. Section 7 invoked as RPC methods with XML-encoded parameters. Section 7
details the list of base protocol operations. details the list of base protocol operations.
4. The Content layer is outside the scope of this document. It is 4. The Content layer is outside the scope of this document. It is
expected that separate efforts to standardize NETCONF data models expected that separate efforts to standardize NETCONF data models
will be undertaken. will be undertaken.
The YANG data modeling language [9] has been developed for specifying The YANG data modeling language [RFC6020] has been developed for
NETCONF data models and protocol operations, covering the Operations specifying NETCONF data models and protocol operations, covering the
and the Content layers of Figure 1. Operations and the Content layers of Figure 1.
1.3. Capabilities 1.3. Capabilities
A NETCONF capability is a set of functionality that supplements the A NETCONF capability is a set of functionality that supplements the
base NETCONF specification. The capability is identified by a base NETCONF specification. The capability is identified by a
uniform resource identifier (URI). uniform resource identifier (URI) [RFC3986].
Capabilities augment the base operations of the device, describing Capabilities augment the base operations of the device, describing
both additional operations and the content allowed inside operations. both additional operations and the content allowed inside operations.
The client can discover the server's capabilities and use any The client can discover the server's capabilities and use any
additional operations, parameters, and content defined by those additional operations, parameters, and content defined by those
capabilities. capabilities.
The capability definition might name one or more dependent The capability definition might name one or more dependent
capabilities. To support a capability, the server MUST support any capabilities. To support a capability, the server MUST support any
capabilities upon which it depends. capabilities upon which it depends.
skipping to change at page 12, line 36 skipping to change at page 12, line 36
delivery. NETCONF connections are long-lived, persisting between delivery. NETCONF connections are long-lived, persisting between
protocol operations. protocol operations.
In addition, resources requested from the server for a particular In addition, resources requested from the server for a particular
connection MUST be automatically released when the connection closes, connection MUST be automatically released when the connection closes,
making failure recovery simpler and more robust. For example, when a making failure recovery simpler and more robust. For example, when a
lock is acquired by a client, the lock persists until either it is lock is acquired by a client, the lock persists until either it is
explicitly released or the server determines that the connection has explicitly released or the server determines that the connection has
been terminated. If a connection is terminated while the client been terminated. If a connection is terminated while the client
holds a lock, the server can perform any appropriate recovery. The holds a lock, the server can perform any appropriate recovery. The
lock operation is further discussed in Section 7.5. <lock> operation is further discussed in Section 7.5.
2.2. Authentication, Integrity, and Confidentiality 2.2. Authentication, Integrity, and Confidentiality
NETCONF connections MUST provide authentication, data integrity, NETCONF connections MUST provide authentication, data integrity,
confidentiality, and replay protection. NETCONF depends on the confidentiality, and replay protection. NETCONF depends on the
transport protocol for this capability. A NETCONF peer assumes that transport protocol for this capability. A NETCONF peer assumes that
appropriate levels of security and confidentiality are provided appropriate levels of security and confidentiality are provided
independently of this document. For example, connections could be independently of this document. For example, connections could be
encrypted in TLS [16] or SSH [14], depending on the underlying encrypted using TLS [RFC5246] or SSH [RFC4251], depending on the
protocol. underlying protocol.
NETCONF connections MUST be authenticated. The transport protocol is NETCONF connections MUST be authenticated. The transport protocol is
responsible for authentication of the server to the client and responsible for authentication of the server to the client and
authentication of the client to the server. A NETCONF peer assumes authentication of the client to the server. A NETCONF peer assumes
that the connection's authentication information has been validated that the connection's authentication information has been validated
by the underlying transport protocol using sufficiently trustworthy by the underlying transport protocol using sufficiently trustworthy
mechanisms and that the peer's identity has been sufficiently proven. mechanisms and that the peer's identity has been sufficiently proven.
One goal of NETCONF is to provide a programmatic interface to the One goal of NETCONF is to provide a programmatic interface to the
device that closely follows the functionality of the device's native device that closely follows the functionality of the device's native
interface. Therefore, it is expected that the underlying protocol interface. Therefore, it is expected that the underlying protocol
uses existing authentication mechanisms available on the device. For uses existing authentication mechanisms available on the device. For
example, a NETCONF server on a device that supports RADIUS [12] might example, a NETCONF server on a device that supports RADIUS [RFC2865]
allow the use of RADIUS to authenticate NETCONF sessions. might allow the use of RADIUS to authenticate NETCONF sessions.
The authentication process MUST result in an authenticated client The authentication process MUST result in an authenticated client
identity whose permissions are known to the server. The identity whose permissions are known to the server. The
authenticated identity of a client is commonly referred to as the authenticated identity of a client is commonly referred to as the
NETCONF username. The algorithm used to derive the username is NETCONF username. The username is a string of characters that match
transport protocol specific and in addition specific to the the "Char" production from section 2.2 of [W3C.REC-xml-20001006] .
authentication mechanism used by the transport protocol. NETCONF The algorithm used to derive the username is transport protocol
transport protocols therefore MUST explain how a NETCONF username is specific and in addition specific to the authentication mechanism
derived from the authentication mechanisms supported by the transport used by the transport protocol. The transport protocol MUST provide
protocol. a username to be used by the other NETCONF layers.
The access permissions of a given client, identified by its NETCONF The access permissions of a given client, identified by its NETCONF
username, are part of the configuration of the NETCONF server. These username, are part of the configuration of the NETCONF server. These
permissions MUST be enforced during the remainder of the NETCONF permissions MUST be enforced during the remainder of the NETCONF
session. The details how access control is configured is outside the session. The details how access control is configured is outside the
scope of this document. scope of this document.
2.3. Mandatory Transport Protocol 2.3. Mandatory Transport Protocol
A NETCONF implementation MUST support the SSH transport protocol A NETCONF implementation MUST support the SSH transport protocol
mapping [4]. mapping [I-D.ietf-netconf-rfc4742bis].
3. XML Considerations 3. XML Considerations
XML serves as the encoding format for NETCONF, allowing complex XML serves as the encoding format for NETCONF, allowing complex
hierarchical data to be expressed in a text format that can be read, hierarchical data to be expressed in a text format that can be read,
saved, and manipulated with both traditional text tools and tools saved, and manipulated with both traditional text tools and tools
specific to XML. specific to XML.
All NETCONF messages MUST be well-formed XML, encoded in UTF-8. If a All NETCONF messages MUST be well-formed XML, encoded in UTF-8
peer receives an <rpc> message that is not well-formed XML or not [RFC3629]. If a peer receives an <rpc> message that is not well-
encoded in UTF-8, it SHOULD reply with a "malformed-message" error. formed XML or not encoded in UTF-8, it SHOULD reply with a
If a reply cannot be sent for any reason, the server MUST close the "malformed-message" error. If a reply cannot be sent for any reason,
session. the server MUST terminate the session.
A NETCONF message MAY begin with an XML declaration (see section 2.8 A NETCONF message MAY begin with an XML declaration (see section 2.8
of [1]). of [W3C.REC-xml-20001006]).
This section discusses a small number of XML-related considerations This section discusses a small number of XML-related considerations
pertaining to NETCONF. pertaining to NETCONF.
3.1. Namespace 3.1. Namespace
All NETCONF protocol elements are defined in the following namespace: All NETCONF protocol elements are defined in the following namespace:
urn:ietf:params:xml:ns:netconf:base:1.0 urn:ietf:params:xml:ns:netconf:base:1.0
NETCONF capability names MUST be URIs [5]. NETCONF capabilities are NETCONF capability names MUST be URIs [RFC3986]. NETCONF
discussed in Section 8. capabilities are discussed in Section 8.
3.2. Document Type Declarations 3.2. Document Type Declarations
Document type declarations MUST NOT appear in NETCONF content. Document type declarations (see section 2.8 of
[W3C.REC-xml-20001006]) MUST NOT appear in NETCONF content.
4. RPC Model 4. RPC Model
The NETCONF protocol uses an RPC-based communication model. NETCONF The NETCONF protocol uses an RPC-based communication model. NETCONF
peers use <rpc> and <rpc-reply> elements to provide transport peers use <rpc> and <rpc-reply> elements to provide transport
protocol-independent framing of NETCONF requests and responses. protocol-independent framing of NETCONF requests and responses.
The syntax and XML encoding of the Messages layer RPCs are formally The syntax and XML encoding of the Messages layer RPCs are formally
defined in the XML schema in Appendix B. defined in the XML schema in Appendix B.
skipping to change at page 15, line 26 skipping to change at page 15, line 26
The <rpc> element is used to enclose a NETCONF request sent from the The <rpc> element is used to enclose a NETCONF request sent from the
client to the server. client to the server.
The <rpc> element has a mandatory attribute "message-id", which is a The <rpc> element has a mandatory attribute "message-id", which is a
string chosen by the sender of the RPC that will commonly encode a string chosen by the sender of the RPC that will commonly encode a
monotonically increasing integer. The receiver of the RPC does not monotonically increasing integer. The receiver of the RPC does not
decode or interpret this string but simply saves it to be used as a decode or interpret this string but simply saves it to be used as a
"message-id" attribute in any resulting <rpc-reply> message. The "message-id" attribute in any resulting <rpc-reply> message. The
sender MUST ensure that the "message-id" value is normalized sender MUST ensure that the "message-id" value is normalized
according to the XML attribute value normalization rules defined in according to the XML attribute value normalization rules defined in
[1] if the sender wants the string to be returned unmodified. For [W3C.REC-xml-20001006] if the sender wants the string to be returned
example: unmodified. For example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<some-method> <some-method>
<!-- method parameters here... --> <!-- method parameters here... -->
</some-method> </some-method>
</rpc> </rpc>
If additional attributes are present in an <rpc> element, a NETCONF If additional attributes are present in an <rpc> element, a NETCONF
peer MUST return them unmodified in the <rpc-reply> element. This peer MUST return them unmodified in the <rpc-reply> element. This
skipping to change at page 18, line 27 skipping to change at page 18, line 27
future use. future use.
error-app-tag: Contains a string identifying the data-model-specific error-app-tag: Contains a string identifying the data-model-specific
or implementation-specific error condition, if one exists. This or implementation-specific error condition, if one exists. This
element will not be present if no appropriate application error element will not be present if no appropriate application error
tag can be associated with a particular error condition. If a tag can be associated with a particular error condition. If a
data-model specific and a implementation-specific error-app-tag data-model specific and a implementation-specific error-app-tag
both exist, then the data-model specific value MUST be used by the both exist, then the data-model specific value MUST be used by the
server. server.
error-path: Contains the absolute XPath [2] expression identifying error-path: Contains the absolute XPath [W3C.REC-xpath-19991116]
the element path to the node that is associated with the error expression identifying the element path to the node that is
being reported in a particular rpc-error element. This element associated with the error being reported in a particular
will not be present if no appropriate payload element or datastore <rpc-error> element. This element will not be present if no
node can be associated with a particular error condition. appropriate payload element or datastore node can be associated
with a particular error condition.
The XPath expression is interpreted in the following context: The XPath expression is interpreted in the following context:
* The set of namespace declarations are those in scope on the * The set of namespace declarations are those in scope on the
rpc-error element. <rpc-error> element.
* The set of variable bindings is empty. * The set of variable bindings is empty.
* The function library is the core function library. * The function library is the core function library.
The context node depends on the node associated with the error The context node depends on the node associated with the error
being reported: being reported:
* If a payload element can be associated with the error, the * If a payload element can be associated with the error, the
context node is the rpc request's document node (i.e., the context node is the rpc request's document node (i.e., the
"rpc" element). <rpc> element).
* Otherwise, the context node is the root of all data models, * Otherwise, the context node is the root of all data models,
i.e., the node which has the top-level nodes from all data i.e., the node which has the top-level nodes from all data
models as children. models as children.
error-message: Contains a string suitable for human display that error-message: Contains a string suitable for human display that
describes the error condition. This element will not be present describes the error condition. This element will not be present
if no appropriate message is provided for a particular error if no appropriate message is provided for a particular error
condition. This element SHOULD include an xml:lang attribute as condition. This element SHOULD include an "xml:lang" attribute as
defined in [1] and discussed in [13]. defined in [W3C.REC-xml-20001006] and discussed in [RFC3470].
error-info: Contains protocol- or data-model-specific error content. error-info: Contains protocol- or data-model-specific error content.
This element will not be present if no such error content is This element will not be present if no such error content is
provided for a particular error condition. The list in Appendix A provided for a particular error condition. The list in Appendix A
defines any mandatory error-info content for each error. After defines any mandatory error-info content for each error. After
any protocol-mandated content, a data model definition MAY mandate any protocol-mandated content, a data model definition MAY mandate
that certain application-layer error information be included in that certain application-layer error information be included in
the error-info container. An implementation MAY include the error-info container. An implementation MAY include
additional elements to provide extended and/or implementation- additional elements to provide extended and/or implementation-
specific debugging information. specific debugging information.
Appendix A enumerates the standard NETCONF errors. Appendix A enumerates the standard NETCONF errors.
Example: Example:
An error is returned if an <rpc> element is received without a An error is returned if an <rpc> element is received without a
message-id attribute. Note that only in this case is it "message-id" attribute. Note that only in this case is it
acceptable for the NETCONF peer to omit the message-id attribute acceptable for the NETCONF peer to omit the "message-id" attribute
in the <rpc-reply> element. in the <rpc-reply> element.
<rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <rpc xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <get-config>
<source> <source>
<running/> <running/>
</source> </source>
</get-config> </get-config>
</rpc> </rpc>
skipping to change at page 20, line 17 skipping to change at page 20, line 17
the <name> element to distinguish between multiple instances of the the <name> element to distinguish between multiple instances of the
<interface> element. <interface> element.
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns:xc="urn:ietf:params:xml:ns:netconf:base:1.0">
<rpc-error> <rpc-error>
<error-type>application</error-type> <error-type>application</error-type>
<error-tag>invalid-value</error-tag> <error-tag>invalid-value</error-tag>
<error-severity>error</error-severity> <error-severity>error</error-severity>
<error-path> <error-path xmlns:t="http://example.com/schema/1.2/config">
/t:top/t:interface[t:name="Ethernet0/0"]/t:mtu /t:top/t:interface[t:name="Ethernet0/0"]/t:mtu
</error-path> </error-path>
<error-message xml:lang="en"> <error-message xml:lang="en">
MTU value 25000 is not within range 256..9192 MTU value 25000 is not within range 256..9192
</error-message> </error-message>
</rpc-error> </rpc-error>
<rpc-error> <rpc-error>
<error-type>application</error-type> <error-type>application</error-type>
<error-tag>invalid-value</error-tag> <error-tag>invalid-value</error-tag>
<error-severity>error</error-severity> <error-severity>error</error-severity>
<error-path> <error-path xmlns:t="http://example.com/schema/1.2/config">
/t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name /t:top/t:interface[t:name="Ethernet1/0"]/t:address/t:name
</error-path> </error-path>
<error-message xml:lang="en"> <error-message xml:lang="en">
Invalid IP address for interface Ethernet1/0 Invalid IP address for interface Ethernet1/0
</error-message> </error-message>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
4.4. <ok> Element 4.4. <ok> Element
skipping to change at page 26, line 14 skipping to change at page 26, line 14
<filter type="subtree"> <filter type="subtree">
<top xmlns="http://example.com/schema/1.2/config"> <top xmlns="http://example.com/schema/1.2/config">
<users/> <users/>
</top> </top>
</filter> </filter>
In this example, the <top> element is a containment node, and the In this example, the <top> element is a containment node, and the
<users> element is a selection node. Only "users" nodes in the <users> element is a selection node. Only "users" nodes in the
"http://example.com/schema/1.2/config" namespace that occur within a "http://example.com/schema/1.2/config" namespace that occur within a
"top" element that is the root of the configuration datastore will be <top> element that is the root of the configuration datastore will be
included in the filter output. included in the filter output.
6.2.5. Content Match Nodes 6.2.5. Content Match Nodes
A leaf node that contains simple content is called a "content match A leaf node that contains simple content is called a "content match
node". It is used to select some or all of its sibling nodes for node". It is used to select some or all of its sibling nodes for
filter output, and it represents an exact-match filter on the leaf filter output, and it represents an exact-match filter on the leaf
node element content. The following constraints apply to content node element content. The following constraints apply to content
match nodes: match nodes:
skipping to change at page 28, line 32 skipping to change at page 28, line 32
and processes the nodes according to the rules for their type. If and processes the nodes according to the rules for their type. If
any nodes in the sibling set are selected, then the process is any nodes in the sibling set are selected, then the process is
recursively applied to the sibling sets of each selected node. The recursively applied to the sibling sets of each selected node. The
algorithm continues until all sibling sets in all subtrees specified algorithm continues until all sibling sets in all subtrees specified
in the filter have been processed. in the filter have been processed.
6.4. Subtree Filtering Examples 6.4. Subtree Filtering Examples
6.4.1. No Filter 6.4.1. No Filter
Leaving out the filter on the get operation returns the entire data Leaving out the filter on the <get> operation returns the entire data
model. model.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get/> <get/>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<data> <data>
<!-- ... entire set of data returned ... --> <!-- ... entire set of data returned ... -->
</data> </data>
</rpc-reply> </rpc-reply>
6.4.2. Empty Filter 6.4.2. Empty Filter
An empty filter will select nothing because no content match or An empty filter will select nothing because no content match or
selection nodes are present. This is not an error. The filter type selection nodes are present. This is not an error. The <filter>
attribute used in these examples is discussed further in Section 7.1. element's "type" attribute used in these examples is discussed
further in Section 7.1.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get> <get>
<filter type="subtree"> <filter type="subtree">
</filter> </filter>
</get> </get>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
skipping to change at page 36, line 23 skipping to change at page 36, line 23
</company-info> </company-info>
</user> </user>
</users> </users>
</top> </top>
</data> </data>
</rpc-reply> </rpc-reply>
6.4.8. Elements with Attribute Naming 6.4.8. Elements with Attribute Naming
In this example, the filter contains one containment node In this example, the filter contains one containment node
(<interfaces>), one attribute match expression (ifName), and one (<interfaces>), one attribute match expression ("ifName"), and one
selection node (<interface>). All instances of the <interface> selection node (<interface>). All instances of the <interface>
subtree that have an ifName attribute equal to "eth0" are selected in subtree that have an "ifName" attribute equal to "eth0" are selected
the filter output. The filter data elements and attributes are in the filter output. The filter data elements and attributes are
qualified because the ifName attribute will not be considered part of qualified because the "ifName" attribute will not be considered part
the "schema/1.2" namespace if it is unqualified. of the "schema/1.2" namespace if it is unqualified.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get> <get>
<filter type="subtree"> <filter type="subtree">
<t:top xmlns:t="http://example.com/schema/1.2/stats"> <t:top xmlns:t="http://example.com/schema/1.2/stats">
<t:interfaces> <t:interfaces>
<t:interface t:ifName="eth0"/> <t:interface t:ifName="eth0"/>
</t:interfaces> </t:interfaces>
</t:top> </t:top>
skipping to change at page 37, line 32 skipping to change at page 37, line 32
<t:interfaces> <t:interfaces>
<t:interface t:ifName="eth0"> <t:interface t:ifName="eth0">
<t:ifInOctets>45621</t:ifInOctets> <t:ifInOctets>45621</t:ifInOctets>
<t:ifOutOctets>774344</t:ifOutOctets> <t:ifOutOctets>774344</t:ifOutOctets>
</t:interface> </t:interface>
</t:interfaces> </t:interfaces>
</t:top> </t:top>
</data> </data>
</rpc-reply> </rpc-reply>
If ifName were a child node instead of an attribute, then the If "ifName" were a child node instead of an attribute, then the
following request would produce similar results. following request would produce similar results.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get> <get>
<filter type="subtree"> <filter type="subtree">
<top xmlns="http://example.com/schema/1.2/stats"> <top xmlns="http://example.com/schema/1.2/stats">
<interfaces> <interfaces>
<interface> <interface>
<ifName>eth0</ifName> <ifName>eth0</ifName>
skipping to change at page 39, line 16 skipping to change at page 39, line 16
Name of the configuration datastore being queried, such as Name of the configuration datastore being queried, such as
<running/>. <running/>.
filter: filter:
This parameter identifies the portions of the device This parameter identifies the portions of the device
configuration datastore to retrieve. If this parameter is not configuration datastore to retrieve. If this parameter is not
present, the entire configuration is returned. present, the entire configuration is returned.
The filter element MAY optionally contain a "type" attribute. The <filter> element MAY optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the filter element. The default filtering mechanism in within the <filter> element. The default filtering mechanism
NETCONF is referred to as subtree filtering and is described in in NETCONF is referred to as subtree filtering and is described
Section 6. The value "subtree" explicitly identifies this type in Section 6. The value "subtree" explicitly identifies this
of filtering. type of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" MAY be used to indicate that (Section 8.9), the value "xpath" MAY be used to indicate that
the select attribute on the filter element contains an XPath the "select" attribute on the <filter> element contains an
expression. XPath expression.
Positive Response: Positive Response:
If the device can satisfy the request, the server sends an If the device can satisfy the request, the server sends an
<rpc-reply> element containing a <data> element with the results <rpc-reply> element containing a <data> element with the results
of the query. of the query.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
skipping to change at page 41, line 26 skipping to change at page 41, line 26
Attributes: Attributes:
operation: operation:
Elements in the <config> subtree MAY contain an "operation" Elements in the <config> subtree MAY contain an "operation"
attribute. The attribute identifies the point in the attribute. The attribute identifies the point in the
configuration to perform the operation and MAY appear on configuration to perform the operation and MAY appear on
multiple elements throughout the <config> subtree. multiple elements throughout the <config> subtree.
If the operation attribute is not specified, the configuration If the "operation" attribute is not specified, the
is merged into the configuration datastore. configuration is merged into the configuration datastore.
The operation attribute has one of the following values: The "operation" attribute has one of the following values:
merge: The configuration data identified by the element merge: The configuration data identified by the element
containing this attribute is merged with the configuration containing this attribute is merged with the configuration
at the corresponding level in the configuration datastore at the corresponding level in the configuration datastore
identified by the target parameter. This is the default identified by the <target> parameter. This is the default
behavior. behavior.
replace: The configuration data identified by the element replace: The configuration data identified by the element
containing this attribute replaces any related configuration containing this attribute replaces any related configuration
in the configuration datastore identified by the target in the configuration datastore identified by the <target>
parameter. If no such configuration data exists in the parameter. If no such configuration data exists in the
configuration datastore, it is created. Unlike a configuration datastore, it is created. Unlike a
<copy-config> operation, which replaces the entire target <copy-config> operation, which replaces the entire target
configuration, only the configuration actually present in configuration, only the configuration actually present in
the config parameter is affected. the <config> parameter is affected.
create: The configuration data identified by the element create: The configuration data identified by the element
containing this attribute is added to the configuration if containing this attribute is added to the configuration if
and only if the configuration data does not already exist in and only if the configuration data does not already exist in
the configuration datastore. If the configuration data the configuration datastore. If the configuration data
exists, an <rpc-error> element is returned with an exists, an <rpc-error> element is returned with an
<error-tag> value of "data-exists". <error-tag> value of "data-exists".
delete: The configuration data identified by the element delete: The configuration data identified by the element
containing this attribute is deleted from the configuration containing this attribute is deleted from the configuration
skipping to change at page 42, line 30 skipping to change at page 42, line 30
target: target:
Name of the configuration datastore being edited, such as Name of the configuration datastore being edited, such as
<running/> or <candidate/>. <running/> or <candidate/>.
default-operation: default-operation:
Selects the default operation (as described in the "operation" Selects the default operation (as described in the "operation"
attribute) for this <edit-config> request. The default value attribute) for this <edit-config> request. The default value
for the default-operation parameter is "merge". for the <default-operation> parameter is "merge".
The default-operation parameter is optional, but if provided, The <default-operation> parameter is optional, but if provided,
it has one of the following values: it has one of the following values:
merge: The configuration data in the <config> parameter is merge: The configuration data in the <config> parameter is
merged with the configuration at the corresponding level in merged with the configuration at the corresponding level in
the target datastore. This is the default behavior. the target datastore. This is the default behavior.
replace: The configuration data in the <config> parameter replace: The configuration data in the <config> parameter
completely replaces the configuration in the target completely replaces the configuration in the target
datastore. This is useful for loading previously saved datastore. This is useful for loading previously saved
configuration data. configuration data.
skipping to change at page 43, line 8 skipping to change at page 43, line 8
a different operation. If the configuration in the <config> a different operation. If the configuration in the <config>
parameter contains data for which there is not a parameter contains data for which there is not a
corresponding level in the target datastore, an <rpc-error> corresponding level in the target datastore, an <rpc-error>
is returned with an <error-tag> value of data-missing. is returned with an <error-tag> value of data-missing.
Using "none" allows operations like "delete" to avoid Using "none" allows operations like "delete" to avoid
unintentionally creating the parent hierarchy of the element unintentionally creating the parent hierarchy of the element
to be deleted. to be deleted.
test-option: test-option:
The test-option element MAY be specified only if the device The <test-option> element MAY be specified only if the device
advertises the :validate:1.1 capability (Section 8.6). advertises the :validate:1.1 capability (Section 8.6).
The test-option element has one of the following values: The <test-option> element has one of the following values:
test-then-set: Perform a validation test before attempting to test-then-set: Perform a validation test before attempting to
set. If validation errors occur, do not perform the set. If validation errors occur, do not perform the
<edit-config> operation. This is the default test-option. <edit-config> operation. This is the default test-option.
set: Perform a set without a validation test first. set: Perform a set without a validation test first.
test-only: Perform only the validation test, without test-only: Perform only the validation test, without
attempting to set. attempting to set.
error-option: error-option:
The error-option element has one of the following values: The <error-option> element has one of the following values:
stop-on-error: Abort the edit-config operation on first error. stop-on-error: Abort the edit-config operation on first error.
This is the default error-option. This is the default error-option.
continue-on-error: Continue to process configuration data on continue-on-error: Continue to process configuration data on
error; error is recorded, and negative response is generated error; error is recorded, and negative response is generated
if any errors occur. if any errors occur.
rollback-on-error: If an error condition occurs such that an rollback-on-error: If an error condition occurs such that an
error severity <rpc-error> element is generated, the server error severity <rpc-error> element is generated, the server
skipping to change at page 44, line 18 skipping to change at page 44, line 18
sent containing an <ok> element. sent containing an <ok> element.
Negative Response: Negative Response:
An <rpc-error> response is sent if the request cannot be completed An <rpc-error> response is sent if the request cannot be completed
for any reason. for any reason.
Example: Example:
The <edit-config> examples in this section utilize a simple data The <edit-config> examples in this section utilize a simple data
model, in which multiple instances of the "interface" element can model, in which multiple instances of the <interface> element can
be present, and an instance is distinguished by the "name" element be present, and an instance is distinguished by the <name> element
within each "interface" element. within each <interface> element.
Set the MTU to 1500 on an interface named "Ethernet0/0" in the Set the MTU to 1500 on an interface named "Ethernet0/0" in the
running configuration: running configuration:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
<target> <target>
<running/> <running/>
</target> </target>
skipping to change at page 48, line 5 skipping to change at page 48, line 5
If a NETCONF peer supports the :url capability (Section 8.8), the If a NETCONF peer supports the :url capability (Section 8.8), the
<url> element can appear as the <source> or <target> parameter. <url> element can appear as the <source> or <target> parameter.
Even if it advertises the :writable-running capability, a device Even if it advertises the :writable-running capability, a device
MAY choose not to support the <running/> configuration datastore MAY choose not to support the <running/> configuration datastore
as the <target> parameter of a <copy-config> operation. A device as the <target> parameter of a <copy-config> operation. A device
MAY choose not to support remote-to-remote copy operations, where MAY choose not to support remote-to-remote copy operations, where
both the <source> and <target> parameters use the <url> element. both the <source> and <target> parameters use the <url> element.
If the source and target parameters identify the same URL or If the <source> and <target> parameters identify the same URL or
configuration datastore, an error MUST be returned with an error- configuration datastore, an error MUST be returned with an error-
tag containing "invalid-value". tag containing "invalid-value".
Parameters: Parameters:
target: target:
Name of the configuration datastore to use as the destination Name of the configuration datastore to use as the destination
of the copy operation. of the <copy-config> operation.
source: source:
Name of the configuration datastore to use as the source of the Name of the configuration datastore to use as the source of the
copy operation, or the <config> element containing the complete <copy-config> operation, or the <config> element containing the
configuration to copy. complete configuration to copy.
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is If the device was able to satisfy the request, an <rpc-reply> is
sent that includes an <ok> element. sent that includes an <ok> element.
Negative Response: Negative Response:
An <rpc-error> element is included within the <rpc-reply> if the An <rpc-error> element is included within the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
<running/> <running/>
</target> </target>
<source> <source>
<url>https://user@example.com:passphrase/cfg/new.txt</url> <url>https://user:password@example.com/cfg/new.txt</url>
</source> </source>
</copy-config> </copy-config>
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.4. <delete-config> 7.4. <delete-config>
skipping to change at page 50, line 6 skipping to change at page 50, line 6
</rpc> </rpc>
<rpc-reply message-id="101" <rpc-reply message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<ok/> <ok/>
</rpc-reply> </rpc-reply>
7.5. <lock> 7.5. <lock>
Description: Description:
The lock operation allows the client to lock the entire The <lock> operation allows the client to lock the entire
configuration datastore system of a device. Such locks are configuration datastore system of a device. Such locks are
intended to be short-lived and allow a client to make a change intended to be short-lived and allow a client to make a change
without fear of interaction with other NETCONF clients, non- without fear of interaction with other NETCONF clients, non-
NETCONF clients (e.g., SNMP and command line interface (CLI) NETCONF clients (e.g., SNMP and command line interface (CLI)
scripts), and human users. scripts), and human users.
An attempt to lock the configuration datastore MUST fail if an An attempt to lock the configuration datastore MUST fail if an
existing session or other entity holds a lock on any portion of existing session or other entity holds a lock on any portion of
the lock target. the lock target.
When the lock is acquired, the server MUST prevent any changes to When the lock is acquired, the server MUST prevent any changes to
the locked resource other than those requested by this session. the locked resource other than those requested by this session.
SNMP and CLI requests to modify the resource MUST fail with an SNMP and CLI requests to modify the resource MUST fail with an
appropriate error. appropriate error.
The duration of the lock is defined as beginning when the lock is The duration of the lock is defined as beginning when the lock is
acquired and lasting until either the lock is released or the acquired and lasting until either the lock is released or the
NETCONF session closes. The session closure can be explicitly NETCONF session closes. The session closure can be explicitly
performed by the client, or implicitly performed by the server performed by the client, or implicitly performed by the server
based on criteria such as failure of the underlying transport, or based on criteria such as failure of the underlying transport,
simple inactivity timeout. This criteria is dependent on the simple inactivity timeout, or detection of abusive behavior on the
part of the client . This criteria is dependent on the
implementation and the underlying transport. implementation and the underlying transport.
The lock operation takes a mandatory parameter, target. The The <lock> operation takes a mandatory parameter, <target>. The
target parameter names the configuration datastore that will be <target> parameter names the configuration datastore that will be
locked. When a lock is active, using the <edit-config> operation locked. When a lock is active, using the <edit-config> operation
on the locked configuration datastore and using the locked on the locked configuration datastore and using the locked
configuration as a target of the <copy-config> operation will be configuration as a target of the <copy-config> operation will be
disallowed by any other NETCONF session. Additionally, the system disallowed by any other NETCONF session. Additionally, the system
will ensure that these locked configuration resources will not be will ensure that these locked configuration resources will not be
modified by other non-NETCONF management operations such as SNMP modified by other non-NETCONF management operations such as SNMP
and CLI. The <kill-session> operation can be used to force the and CLI. The <kill-session> operation can be used to force the
release of a lock owned by another NETCONF session. It is beyond release of a lock owned by another NETCONF session. It is beyond
the scope of this document to define how to break locks held by the scope of this document to define how to break locks held by
other entities. other entities.
skipping to change at page 52, line 39 skipping to change at page 52, line 41
<session-id>454</session-id> <session-id>454</session-id>
<!-- lock is held by NETCONF session 454 --> <!-- lock is held by NETCONF session 454 -->
</error-info> </error-info>
</rpc-error> </rpc-error>
</rpc-reply> </rpc-reply>
7.6. <unlock> 7.6. <unlock>
Description: Description:
The unlock operation is used to release a configuration lock, The <unlock> operation is used to release a configuration lock,
previously obtained with the <lock> operation. previously obtained with the <lock> operation.
An unlock operation will not succeed if any of the following An <unlock> operation will not succeed if any of the following
conditions are true: conditions are true:
* the specified lock is not currently active * the specified lock is not currently active
* the session issuing the <unlock> operation is not the same * the session issuing the <unlock> operation is not the same
session that obtained the lock session that obtained the lock
The server MUST respond with either an <ok> element or an The server MUST respond with either an <ok> element or an
<rpc-error>. <rpc-error>.
skipping to change at page 54, line 12 skipping to change at page 54, line 12
Parameters: Parameters:
filter: filter:
This parameter specifies the portion of the system This parameter specifies the portion of the system
configuration and state data to retrieve. If this parameter is configuration and state data to retrieve. If this parameter is
not present, all the device configuration and state information not present, all the device configuration and state information
is returned. is returned.
The filter element MAY optionally contain a "type" attribute. The <filter> element MAY optionally contain a "type" attribute.
This attribute indicates the type of filtering syntax used This attribute indicates the type of filtering syntax used
within the filter element. The default filtering mechanism in within the <filter> element. The default filtering mechanism
NETCONF is referred to as subtree filtering and is described in in NETCONF is referred to as subtree filtering and is described
Section 6. The value "subtree" explicitly identifies this type in Section 6. The value "subtree" explicitly identifies this
of filtering. type of filtering.
If the NETCONF peer supports the :xpath capability If the NETCONF peer supports the :xpath capability
(Section 8.9), the value "xpath" MAY be used to indicate that (Section 8.9), the value "xpath" MAY be used to indicate that
the select attribute of the filter element contains an XPath the "select" attribute of the <filter> element contains an
expression. XPath expression.
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> is If the device was able to satisfy the request, an <rpc-reply> is
sent. The <data> section contains the appropriate subset. sent. The <data> section contains the appropriate subset.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
skipping to change at page 58, line 20 skipping to change at page 58, line 20
understand only those capabilities that it might use and MUST ignore understand only those capabilities that it might use and MUST ignore
any capability received from the other peer that it does not require any capability received from the other peer that it does not require
or does not understand. or does not understand.
Additional capabilities can be defined using the template in Additional capabilities can be defined using the template in
Appendix D. Future capability definitions can be published as Appendix D. Future capability definitions can be published as
standards by standards bodies or published as proprietary extensions. standards by standards bodies or published as proprietary extensions.
A NETCONF capability is identified with a URI. The base capabilities A NETCONF capability is identified with a URI. The base capabilities
are defined using URNs following the method described in RFC 3553 are defined using URNs following the method described in RFC 3553
[6]. Capabilities defined in this document have the following [RFC3553]. Capabilities defined in this document have the following
format: format:
urn:ietf:params:netconf:capability:{name}:1.x urn:ietf:params:netconf:capability:{name}:1.x
where {name} is the name of the capability. Capabilities are often where {name} is the name of the capability. Capabilities are often
referenced in discussions and email using the shorthand :{name}, or referenced in discussions and email using the shorthand :{name}, or
:{name}:{version} if the capability exists in multiple versions. For :{name}:{version} if the capability exists in multiple versions. For
example, the foo capability would have the formal name example, the foo capability would have the formal name
"urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo". "urn:ietf:params:netconf:capability:foo:1.0" and be called ":foo".
The shorthand form MUST NOT be used inside the protocol. The shorthand form MUST NOT be used inside the protocol.
skipping to change at page 59, line 6 skipping to change at page 59, line 6
encoded at the end of the URI string. If no protocol version encoded at the end of the URI string. If no protocol version
capability in common is found, the NETCONF peer MUST NOT continue the capability in common is found, the NETCONF peer MUST NOT continue the
session. If more than one protocol version URI in common is present, session. If more than one protocol version URI in common is present,
then the highest numbered (most recent) protocol version MUST be used then the highest numbered (most recent) protocol version MUST be used
by both peers. by both peers.
A server sending the <hello> element MUST include a <session-id> A server sending the <hello> element MUST include a <session-id>
element containing the session ID for this NETCONF session. A client element containing the session ID for this NETCONF session. A client
sending the <hello> element MUST NOT include a <session-id> element. sending the <hello> element MUST NOT include a <session-id> element.
A server receiving a <session-id> element MUST close the NETCONF A server receiving a <hello> message with a <session-id> element MUST
session. Similarly, a client that does not receive a <session-id> terminate the NETCONF session. Similarly, a client that does not
element in the server's <hello> message MUST close the NETCONF receive a <session-id> element in the server's <hello> message MUST
session. terminate the NETCONF session (without first sending a
<close-session>).
In the following example, a server advertises the base NETCONF In the following example, a server advertises the base NETCONF
capability, one NETCONF capability defined in the base NETCONF capability, one NETCONF capability defined in the base NETCONF
document, and one implementation-specific capability. document, and one implementation-specific capability.
<hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <hello xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<capabilities> <capabilities>
<capability> <capability>
urn:ietf:params:netconf:base:1.1 urn:ietf:params:netconf:base:1.1
</capability> </capability>
skipping to change at page 59, line 40 skipping to change at page 59, line 41
Each peer sends its <hello> element simultaneously as soon as the Each peer sends its <hello> element simultaneously as soon as the
connection is open. A peer MUST NOT wait to receive the capability connection is open. A peer MUST NOT wait to receive the capability
set from the other side before sending its own set. set from the other side before sending its own set.
8.2. Writable-Running Capability 8.2. Writable-Running Capability
8.2.1. Description 8.2.1. Description
The :writable-running capability indicates that the device supports The :writable-running capability indicates that the device supports
direct writes to the <running> configuration datastore. In other direct writes to the <running> configuration datastore. In other
words, the device supports edit-config and copy-config operations words, the device supports <edit-config> and <copy-config> operations
where the <running> configuration is the target. where the <running> configuration is the target.
8.2.2. Dependencies 8.2.2. Dependencies
None. None.
8.2.3. Capability Identifier 8.2.3. Capability Identifier
The :writable-running capability is identified by the following The :writable-running capability is identified by the following
capability string: capability string:
skipping to change at page 63, line 7 skipping to change at page 63, line 7
8.3.5.1. <get-config>, <edit-config>, <copy-config>, and <validate> 8.3.5.1. <get-config>, <edit-config>, <copy-config>, and <validate>
The candidate configuration can be used as a source or target of any The candidate configuration can be used as a source or target of any
<get-config>, <edit-config>, <copy-config>, or <validate> operation <get-config>, <edit-config>, <copy-config>, or <validate> operation
as a <source> or <target> parameter. The <candidate> element is used as a <source> or <target> parameter. The <candidate> element is used
to indicate the candidate configuration: to indicate the candidate configuration:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<get-config> <!-- any NETCONF operation --> <get-config>
<source> <source>
<candidate/> <candidate/>
</source> </source>
</get-config> </get-config>
</rpc> </rpc>
8.3.5.2. <lock> and <unlock> 8.3.5.2. <lock> and <unlock>
The candidate configuration can be locked using the <lock> operation The candidate configuration can be locked using the <lock> operation
with the <candidate> element as the <target> parameter: with the <candidate> element as the <target> parameter:
skipping to change at page 64, line 8 skipping to change at page 64, line 8
8.4.1. Description 8.4.1. Description
The :confirmed-commit:1.1 capability indicates that the server will The :confirmed-commit:1.1 capability indicates that the server will
support the <cancel-commit> operation and the <confirmed>, support the <cancel-commit> operation and the <confirmed>,
<confirm-timeout>, <persist>, and <persist-id> parameters for the <confirm-timeout>, <persist>, and <persist-id> parameters for the
<commit> operation. See Section 8.3 for further details on the <commit> operation. See Section 8.3 for further details on the
<commit> operation. <commit> operation.
A confirmed commit operation MUST be reverted if a confirming commit A confirmed commit operation MUST be reverted if a confirming commit
is not issued within 600 seconds (10 minutes). The confirming commit is not issued within the timeout period (by default 600 seconds = 10
is a commit operation without the <confirmed> parameter. The timeout minutes). The confirming commit is a <commit> operation without the
period can be adjusted with the <confirm-timeout> parameter. If a <confirmed> parameter. The timeout period can be adjusted with the
follow-up confirmed commit operation is issued before the timer <confirm-timeout> parameter. If a follow-up confirmed commit
expires, the timer is reset to the new value (600 seconds by operation is issued before the timer expires, the timer is reset to
default). Both the confirming commit and a follow-up confirmed the new value (600 seconds by default). Both the confirming commit
commit operation MAY introduce additional changes to the and a follow-up confirmed commit operation MAY introduce additional
configuration. changes to the configuration.
If the <persist> element is not given in the confirmed commit If the <persist> element is not given in the confirmed commit
operation, any follow-up commit and the confirming commit MUST be operation, any follow-up commit and the confirming commit MUST be
issued on the same session that issued the confirmed commit. If the issued on the same session that issued the confirmed commit. If the
<persist> element is given in the confirmed commit operation, a <persist> element is given in the confirmed commit operation, a
follow-up commit and the confirming commit can be given on any follow-up commit and the confirming commit can be given on any
session, and they MUST include a <persist-id> element with a value session, and they MUST include a <persist-id> element with a value
equal to the given value of the <persist> element. equal to the given value of the <persist> element.
If the server also advertises the :startup capability, a If the server also advertises the :startup capability, a
skipping to change at page 64, line 49 skipping to change at page 64, line 49
If a confirming commit is not issued, the device will revert its If a confirming commit is not issued, the device will revert its
configuration to the state prior to the issuance of the confirmed configuration to the state prior to the issuance of the confirmed
commit. To cancel a confirmed commit and revert changes without commit. To cancel a confirmed commit and revert changes without
waiting for the confirm timeout to expire, the client can explicitly waiting for the confirm timeout to expire, the client can explicitly
restore the configuration to its state before the confirmed commit restore the configuration to its state before the confirmed commit
was issued, by using the <cancel-commit> operation. was issued, by using the <cancel-commit> operation.
For shared configurations, this feature can cause other configuration For shared configurations, this feature can cause other configuration
changes (for example, via other NETCONF sessions) to be inadvertently changes (for example, via other NETCONF sessions) to be inadvertently
altered or removed, unless the configuration locking feature is used altered or removed, unless the configuration locking feature is used
(in other words, the lock is obtained before the edit-config (in other words, the lock is obtained before the <edit-config>
operation is started). Therefore, it is strongly suggested that in operation is started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration datastores, order to use this feature with shared configuration datastores,
configuration locking SHOULD also be used. configuration locking SHOULD also be used.
Version 1.0 of this capability was defined in [15]. Version 1.1 is Version 1.0 of this capability was defined in [RFC4741]. Version 1.1
defined in this document, and extends version 1.0 by adding a new is defined in this document, and extends version 1.0 by adding a new
operation, <cancel-commit>, and two new optional parameters, operation, <cancel-commit>, and two new optional parameters,
<persist> and <persist-id>. For backwards compatibility with old <persist> and <persist-id>. For backwards compatibility with old
clients, servers confirming to this specification MAY advertise clients, servers confirming to this specification MAY advertise
version 1.0 in addition to version 1.1. version 1.0 in addition to version 1.1.
8.4.2. Dependencies 8.4.2. Dependencies
The :confirmed-commit:1.1 capability is only relevant if the The :confirmed-commit:1.1 capability is only relevant if the
:candidate capability is also supported. :candidate capability is also supported.
skipping to change at page 65, line 41 skipping to change at page 65, line 41
Cancels an ongoing confirmed commit. If the <persist-id> Cancels an ongoing confirmed commit. If the <persist-id>
parameter is not given, the <cancel-commit> operation MUST be parameter is not given, the <cancel-commit> operation MUST be
issued on the same session that issued the confirmed commit. issued on the same session that issued the confirmed commit.
Parameters: Parameters:
persist-id: persist-id:
Cancels a persistent confirmed commit. The value MUST be Cancels a persistent confirmed commit. The value MUST be
equal to the value given in the <persist> parameter to the equal to the value given in the <persist> parameter to the
commit operation. If the value does not match, the <commit> operation. If the value does not match, the
operation fails with an "invalid-value" error. operation fails with an "invalid-value" error.
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element. is sent that contains an <ok> element.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
skipping to change at page 68, line 44 skipping to change at page 68, line 44
8.5.1. Description 8.5.1. Description
This capability indicates that the server will support the This capability indicates that the server will support the
"rollback-on-error" value in the <error-option> parameter to the "rollback-on-error" value in the <error-option> parameter to the
<edit-config> operation. <edit-config> operation.
For shared configurations, this feature can cause other configuration For shared configurations, this feature can cause other configuration
changes (for example, via other NETCONF sessions) to be inadvertently changes (for example, via other NETCONF sessions) to be inadvertently
altered or removed, unless the configuration locking feature is used altered or removed, unless the configuration locking feature is used
(in other words, the lock is obtained before the edit-config (in other words, the lock is obtained before the <edit-config>
operation is started). Therefore, it is strongly suggested that in operation is started). Therefore, it is strongly suggested that in
order to use this feature with shared configuration datastores, order to use this feature with shared configuration datastores,
configuration locking also be used. configuration locking also be used.
8.5.2. Dependencies 8.5.2. Dependencies
None None
8.5.3. Capability Identifier 8.5.3. Capability Identifier
skipping to change at page 70, line 15 skipping to change at page 70, line 15
8.6. Validate Capability 8.6. Validate Capability
8.6.1. Description 8.6.1. Description
Validation consists of checking a complete configuration for Validation consists of checking a complete configuration for
syntactical and semantic errors before applying the configuration to syntactical and semantic errors before applying the configuration to
the device. the device.
If this capability is advertised, the device supports the <validate> If this capability is advertised, the device supports the <validate>
protocol operation and checks at least for syntax errors. In protocol operation and checks at least for syntax errors. In
addition, this capability supports the test-option parameter to the addition, this capability supports the <test-option> parameter to the
<edit-config> operation and, when it is provided, checks at least for <edit-config> operation and, when it is provided, checks at least for
syntax errors. syntax errors.
Version 1.0 of this capability was defined in [15]. Version 1.1 is Version 1.0 of this capability was defined in [RFC4741]. Version 1.1
defined in this document, and extends version 1.0 by adding a new is defined in this document, and extends version 1.0 by adding a new
value, "test-only", to the test-option parameter of the edit-config value, "test-only", to the <test-option> parameter of the
operation. For backwards compatibility with old clients, servers <edit-config> operation. For backwards compatibility with old
confirming to this specification MAY advertise version 1.0 in clients, servers confirming to this specification MAY advertise
addition to version 1.1. version 1.0 in addition to version 1.1.
8.6.2. Dependencies 8.6.2. Dependencies
None. None.
8.6.3. Capability Identifier 8.6.3. Capability Identifier
The :validate:1.1 capability is identified by the following The :validate:1.1 capability is identified by the following
capability string: capability string:
skipping to change at page 71, line 15 skipping to change at page 71, line 15
Positive Response: Positive Response:
If the device was able to satisfy the request, an <rpc-reply> If the device was able to satisfy the request, an <rpc-reply>
is sent that contains an <ok> element. is sent that contains an <ok> element.
Negative Response: Negative Response:
An <rpc-error> element is included in the <rpc-reply> if the An <rpc-error> element is included in the <rpc-reply> if the
request cannot be completed for any reason. request cannot be completed for any reason.
A validate operation can fail for any of the following reasons: A <validate> operation can fail for a number of reasons, such
as syntax errors, missing parameters, references to undefined
+ Syntax errors configuration data or any other violations of rules established
by the underlying data model.
+ Missing parameters
+ References to undefined configuration data
Example: Example:
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<validate> <validate>
<source> <source>
<candidate/> <candidate/>
</source> </source>
</validate> </validate>
skipping to change at page 73, line 4 skipping to change at page 72, line 48
| | | | | | | |
| <unlock> | <target> | | | <unlock> | <target> | |
| | | | | | | |
| <validate> | <source> | If :validate:1.1 | | <validate> | <source> | If :validate:1.1 |
| | | is advertised | | | | is advertised |
| | | | | | | |
| <delete-config> | <target> | Resets the device | | <delete-config> | <target> | Resets the device |
| | | to its factory | | | | to its factory |
| | | defaults | | | | defaults |
+--------------------+--------------------------+-------------------+ +--------------------+--------------------------+-------------------+
To save the startup configuration, use the copy-config operation to
To save the startup configuration, use the <copy-config> operation to
copy the <running> configuration datastore to the <startup> copy the <running> configuration datastore to the <startup>
configuration datastore. configuration datastore.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config> <copy-config>
<target> <target>
<startup/> <startup/>
</target> </target>
<source> <source>
skipping to change at page 74, line 4 skipping to change at page 73, line 46
comma-separated list of scheme names indicating which schemes the comma-separated list of scheme names indicating which schemes the
NETCONF peer supports. For example: NETCONF peer supports. For example:
urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file urn:ietf:params:netconf:capability:url:1.0?scheme=http,ftp,file
8.8.4. New Operations 8.8.4. New Operations
None. None.
8.8.5. Modifications to Existing Operations 8.8.5. Modifications to Existing Operations
8.8.5.1. <edit-config> 8.8.5.1. <edit-config>
The :url capability modifies the <edit-config> operation to accept The :url capability modifies the <edit-config> operation to accept
the <url> element as an alternative to the <config> parameter. the <url> element as an alternative to the <config> parameter.
The file that the url refers to contains the configuration data
hierarchy to be modified, encoded in XML under the element <config>
in the "urn:ietf:params:xml:ns:netconf:base:1.0" namespace.
8.8.5.2. <copy-config> 8.8.5.2. <copy-config>
The :url capability modifies the <copy-config> operation to accept The :url capability modifies the <copy-config> operation to accept
the <url> element as the value of the <source> and the <target> the <url> element as the value of the <source> and the <target>
parameters. parameters.
The file that the url refers to contains the complete datastore, The file that the url refers to contains the complete datastore,
encoded in XML under the element "config" in the encoded in XML under the element <config> in the
"urn:ietf:params:xml:ns:netconf:base:1.0" namespace. "urn:ietf:params:xml:ns:netconf:base:1.0" namespace.
8.8.5.3. <delete-config> 8.8.5.3. <delete-config>
The :url capability modifies the <delete-config> operation to accept The :url capability modifies the <delete-config> operation to accept
the <url> element as the value of the <target> parameters. the <url> element as the value of the <target> parameters.
8.8.5.4. <validate> 8.8.5.4. <validate>
The :url capability modifies the <validate> operation to accept the The :url capability modifies the <validate> operation to accept the
<url> element as the value of the <source> parameter. <url> element as the value of the <source> parameter.
8.9. XPath Capability 8.9. XPath Capability
8.9.1. Description 8.9.1. Description
The XPath capability indicates that the NETCONF peer supports the use The XPath capability indicates that the NETCONF peer supports the use
of XPath expressions in the <filter> element. XPath is described in of XPath expressions in the <filter> element. XPath is described in
[2]. [W3C.REC-xpath-19991116].
The data model used in the XPath expression is the same as that used The data model used in the XPath expression is the same as that used
in XPath 1.0 [2], with the same extension for root node children as in XPath 1.0 [W3C.REC-xpath-19991116], with the same extension for
used by XSLT 1.0 [11] (section 3.1). Specifically, it means that the root node children as used by XSLT 1.0 [W3C.REC-xslt-19991116]
root node MAY have any number of element nodes as its children. (section 3.1). Specifically, it means that the root node MAY have
any number of element nodes as its children.
The XPath expression is evaluated in the following context: The XPath expression is evaluated in the following context:
o The set of namespace declarations are those in scope on the filter o The set of namespace declarations are those in scope on the
element. <filter> element.
o The set of variable bindings is defined by the data model. If no o The set of variable bindings is defined by the data model. If no
such variable bindings are defined, the set is empty. such variable bindings are defined, the set is empty.
o The function library is the core function library, plus any o The function library is the core function library, plus any
functions defined by the data model. functions defined by the data model.
o The context node is the root node. o The context node is the root node.
The XPath expression MUST return a node set. If it does not return a The XPath expression MUST return a node set. If it does not return a
skipping to change at page 75, line 37 skipping to change at page 75, line 37
8.9.4. New Operations 8.9.4. New Operations
None. None.
8.9.5. Modifications to Existing Operations 8.9.5. Modifications to Existing Operations
8.9.5.1. <get-config> and <get> 8.9.5.1. <get-config> and <get>
The :xpath capability modifies the <get> and <get-config> operations The :xpath capability modifies the <get> and <get-config> operations
to accept the value "xpath" in the type attribute of the filter to accept the value "xpath" in the "type" attribute of the <filter>
element. When the type attribute is set to "xpath", a select element. When the "type" attribute is set to "xpath", a "select"
attribute MUST be present on the filter element. The select attribute MUST be present on the <filter> element. The "select"
attribute will be treated as an XPath expression and used to filter attribute will be treated as an XPath expression and used to filter
the returned data. The filter element itself MUST be empty in this the returned data. The <filter> element itself MUST be empty in this
case. case.
The XPath result for the select expression MUST be a node-set. Each The XPath result for the select expression MUST be a node-set. Each
node in the node-set MUST correspond to a node in underlying data node in the node-set MUST correspond to a node in underlying data
model. In order to properly identify each node, the following model. In order to properly identify each node, the following
encoding rules are defined: encoding rules are defined:
o All ancestor nodes of the result node MUST be encoded first, so o All ancestor nodes of the result node MUST be encoded first, so
the <data> element returned in the reply contains only fully- the <data> element returned in the reply contains only fully-
specified sub-trees, according to the underlying data model. specified sub-trees, according to the underlying data model.
skipping to change at page 77, line 35 skipping to change at page 77, line 35
consequences if those operations are also not guarded by the global consequences if those operations are also not guarded by the global
lock on the files or objects being operated upon. For instance, a lock on the files or objects being operated upon. For instance, a
partially complete access list could be committed from a candidate partially complete access list could be committed from a candidate
configuration unbeknownst to the owner of the lock of the candidate configuration unbeknownst to the owner of the lock of the candidate
configuration, leading to either an insecure or inaccessible device configuration, leading to either an insecure or inaccessible device
if the lock on the candidate configuration does not also apply to the if the lock on the candidate configuration does not also apply to the
<copy-config> operation when applied to it. <copy-config> operation when applied to it.
Configuration information is by its very nature sensitive. Its Configuration information is by its very nature sensitive. Its
transmission in the clear and without integrity checking leaves transmission in the clear and without integrity checking leaves
devices open to classic eavesdropping attacks. Configuration devices open to classic eavesdropping and false data injection
information often contains passwords, user names, service attacks. Configuration information often contains passwords, user
descriptions, and topological information, all of which are names, service descriptions, and topological information, all of
sensitive. Because of this, this protocol SHOULD be implemented which are sensitive. Because of this, this protocol SHOULD be
carefully with adequate attention to all manner of attack one might implemented carefully with adequate attention to all manner of attack
expect to experience with other management interfaces. one might expect to experience with other management interfaces.
The protocol, therefore, MUST minimally support options for both The protocol, therefore, MUST minimally support options for both
confidentiality and authentication. It is anticipated that the confidentiality and authentication. It is anticipated that the
underlying protocol (SSH, BEEP, etc) will provide for both underlying protocol (SSH, BEEP, etc) will provide for both
confidentiality and authentication, as is required. It is further confidentiality and authentication, as is required. It is further
expected that the identity of each end of a NETCONF session will be expected that the identity of each end of a NETCONF session will be
available to the other in order to determine authorization for any available to the other in order to determine authorization for any
given request. One could also easily envision additional given request. One could also easily envision additional
information, such as transport and encryption methods, being made information, such as transport and encryption methods, being made
available for purposes of authorization. NETCONF itself provide no available for purposes of authorization. NETCONF itself provide no
skipping to change at page 79, line 10 skipping to change at page 79, line 10
user interface. These two mechanisms suffer from a race condition user interface. These two mechanisms suffer from a race condition
that could be ameliorated by removing the offending user from an AAA that could be ameliorated by removing the offending user from an AAA
server. However, such a solution is not useful in all deployment server. However, such a solution is not useful in all deployment
scenarios, such as those where SSH public/private key pairs are used. scenarios, such as those where SSH public/private key pairs are used.
10. IANA Considerations 10. IANA Considerations
10.1. NETCONF XML Namespace 10.1. NETCONF XML Namespace
This document registers a URI for the NETCONF XML namespace in the This document registers a URI for the NETCONF XML namespace in the
IETF XML registry [7]. IETF XML registry [RFC3688].
IANA is requested to update the allocation of the following URI to IANA is requested to update the allocation of the following URI to
reference this document when it is published as an RFC. reference this document when it is published as an RFC.
URI: urn:ietf:params:xml:ns:netconf:base:1.0 URI: urn:ietf:params:xml:ns:netconf:base:1.0
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: N/A, the requested URI is an XML namespace. XML: N/A, the requested URI is an XML namespace.
10.2. NETCONF XML Schema 10.2. NETCONF XML Schema
This document registers a URI for the NETCONF XML schema in the IETF This document registers a URI for the NETCONF XML schema in the IETF
XML registry [7]. XML registry [RFC3688].
IANA is requested to update the allocation of the following URI to IANA is requested to update the allocation of the following URI to
reference this document when it is published as an RFC. reference this document when it is published as an RFC.
URI: urn:ietf:params:xml:schema:netconf URI: urn:ietf:params:xml:schema:netconf
Registrant Contact: The IESG. Registrant Contact: The IESG.
XML: Appendix B of this document. XML: Appendix B of this document.
10.3. NETCONF YANG Module 10.3. NETCONF YANG Module
This document registers a YANG module in the YANG Module Names This document registers a YANG module in the YANG Module Names
registry [9]. registry [RFC6020].
name: ietf-netconf name: ietf-netconf
namespace: urn:ietf:params:xml:ns:netconf:base:1.0 namespace: urn:ietf:params:xml:ns:netconf:base:1.0
prefix: nc prefix: nc
reference: RFCXXXX reference: RFCXXXX
10.4. NETCONF Capability URNs 10.4. NETCONF Capability URNs
IANA has created and will maintain a registry "Network Configuration IANA has created and will maintain a registry "Network Configuration
Protocol (NETCONF) Capability URNs" that allocates NETCONF capability Protocol (NETCONF) Capability URNs" that allocates NETCONF capability
skipping to change at page 82, line 9 skipping to change at page 82, line 9
for his persistence and patience in assisting us with security for his persistence and patience in assisting us with security
considerations. We would also like to thank Randy Presuhn, Sharon considerations. We would also like to thank Randy Presuhn, Sharon
Chisholm, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen, Chisholm, Glenn Waters, David Perkins, Weijing Chen, Simon Leinen,
Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent Keith Allen, Dave Harrington, Ladislav Lhotka, Tom Petch, and Kent
Watsen for all of their valuable advice. Watsen for all of their valuable advice.
12. References 12. References
12.1. Normative References 12.1. Normative References
[1] Paoli, J., Sperberg-McQueen, C., Bray, T., and E. Maler, [W3C.REC-xml-20001006]
"Extensible Markup Language (XML) 1.0 (Second Edition)", World Bray, T., Sperberg-McQueen, C., Paoli, J., and E. Maler,
Wide Web Consortium FirstEdition REC-xml-20001006, "Extensible Markup Language (XML) 1.0 (Second Edition)",
October 2000, <http://www.w3.org/TR/2000/REC-xml-20001006>. World Wide Web Consortium FirstEdition REC-xml-20001006,
October 2000,
<http://www.w3.org/TR/2000/REC-xml-20001006>.
[2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version [W3C.REC-xpath-19991116]
1.0", World Wide Web Consortium Recommendation REC-xpath- DeRose, S. and J. Clark, "XML Path Language (XPath)
19991116, November 1999, Version 1.0", World Wide Web Consortium
<http://www.w3.org/TR/1999/REC-xpath-19991116>. Recommendation REC-xpath-19991116, November 1999,
<http://www.w3.org/TR/1999/REC-xpath-19991116>.
[3] Bradner, S., "Key words for use in RFCs to Indicate Requirement [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration [I-D.ietf-netconf-rfc4742bis]
Protocol over Secure Shell (SSH)", Wasserman, M. and T. Goddard, "Using the NETCONF
draft-ietf-netconf-rfc4742bis-06 (work in progress), Configuration Protocol over Secure Shell (SSH)",
January 2011. draft-ietf-netconf-rfc4742bis-07 (work in progress),
February 2011.
[5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, Resource Identifier (URI): Generic Syntax", STD 66,
January 2005. RFC 3986, January 2005.
[6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF [RFC3553] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An
URN Sub-namespace for Registered Protocol Parameters", BCP 73, IETF URN Sub-namespace for Registered Protocol
RFC 3553, June 2003. Parameters", BCP 73, RFC 3553, June 2003.
[7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
January 2004. 10646", STD 63, RFC 3629, November 2003.
[8] Lengyel, B. and M. Bjorklund, "Partial Lock Remote Procedure [RFC3688] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688,
Call (RPC) for NETCONF", RFC 5717, December 2009. January 2004.
[9] Bjorklund, M., "YANG - A Data Modeling Language for the Network [RFC5717] Lengyel, B. and M. Bjorklund, "Partial Lock Remote
Configuration Protocol (NETCONF)", RFC 6020, October 2010. Procedure Call (RPC) for NETCONF", RFC 5717,
December 2009.
[10] Schoenwaelder, J., "Common YANG Data Types", RFC 6021, [RFC6020] Bjorklund, M., "YANG - A Data Modeling Language for the
October 2010. Network Configuration Protocol (NETCONF)", RFC 6020,
October 2010.
[RFC6021] Schoenwaelder, J., "Common YANG Data Types", RFC 6021,
October 2010.
12.2. Informative References 12.2. Informative References
[11] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide [W3C.REC-xslt-19991116]
Web Consortium Recommendation REC-xslt-19991116, November 1999, Clark, J., "XSL Transformations (XSLT) Version 1.0", World
<http://www.w3.org/TR/1999/REC-xslt-19991116>. Wide Web Consortium Recommendation REC-xslt-19991116,
November 1999,
<http://www.w3.org/TR/1999/REC-xslt-19991116>.
[12] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote [RFC2865] Rigney, C., Willens, S., Rubens, A., and W. Simpson,
Authentication Dial In User Service (RADIUS)", RFC 2865, "Remote Authentication Dial In User Service (RADIUS)",
June 2000. RFC 2865, June 2000.
[13] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the [RFC3470] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for
Use of Extensible Markup Language (XML) within IETF Protocols", the Use of Extensible Markup Language (XML)
BCP 70, RFC 3470, January 2003. within IETF Protocols", BCP 70, RFC 3470, January 2003.
[14] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol [RFC4251] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH)
Architecture", RFC 4251, January 2006. Protocol Architecture", RFC 4251, January 2006.
[15] Enns, R., "NETCONF Configuration Protocol", RFC 4741, [RFC4741] Enns, R., "NETCONF Configuration Protocol", RFC 4741,
December 2006. December 2006.
[16] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
Appendix A. NETCONF Error List Appendix A. NETCONF Error List
This section is normative. This section is normative.
For each error-tag, the valid error-type and error-severity values For each error-tag, the valid error-type and error-severity values
are listed, together with any mandatory error-info, if any. are listed, together with any mandatory error-info, if any.
error-tag: in-use error-tag: in-use
error-type: protocol, application error-type: protocol, application
skipping to change at page 88, line 5 skipping to change at page 87, line 46
or not been attempted (<noop-element>). or not been attempted (<noop-element>).
error-tag: malformed-message error-tag: malformed-message
error-type: rpc error-type: rpc
error-severity: error error-severity: error
error-info: none error-info: none
Description: A message could not be handled because it failed to Description: A message could not be handled because it failed to
be parsed correctly. For example, the message is not be parsed correctly. For example, the message is not
well-formed XML or it uses an invalid character set. well-formed XML or it uses an invalid character set.
This error-tag is new in :base:1.1 and MUST NOT be
sent to old clients.
Appendix B. XML Schema for NETCONF Messages Layer Appendix B. XML Schema for NETCONF Messages Layer
This section is normative. This section is normative.
<CODE BEGINS> file "netconf.xsd" <CODE BEGINS> file "netconf.xsd"
<?xml version="1.0" encoding="UTF-8"?> <?xml version="1.0" encoding="UTF-8"?>
<xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"
targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0"
skipping to change at page 93, line 9 skipping to change at page 93, line 9
</xs:complexType> </xs:complexType>
</xs:element> </xs:element>
</xs:schema> </xs:schema>
<CODE ENDS> <CODE ENDS>
Appendix C. YANG Module for NETCONF Protocol Operations Appendix C. YANG Module for NETCONF Protocol Operations
This section is normative. This section is normative.
The ietf-netconf YANG module imports typedefs from [10]. The ietf-netconf YANG module imports typedefs from [RFC6021].
// RFC Ed.: please update the date to the date of publication // RFC Ed.: please update the date to the date of publication
<CODE BEGINS> file "ietf-netconf@2011-01-16.yang" <CODE BEGINS> file "ietf-netconf@2011-03-08.yang"
module ietf-netconf { module ietf-netconf {
// the namespace for NETCONF XML definitions has not changed // the namespace for NETCONF XML definitions is unchanged
// this value is pre-determined by RFC 4741 // from RFC 4741 which this document replaces
namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; namespace "urn:ietf:params:xml:ns:netconf:base:1.0";
prefix nc; prefix nc;
import ietf-inet-types { import ietf-inet-types {
prefix inet; prefix inet;
} }
organization organization
"IETF NETCONF (Network Configuration) Working Group"; "IETF NETCONF (Network Configuration) Working Group";
skipping to change at page 94, line 17 skipping to change at page 94, line 17
to the license terms contained in, the Simplified BSD License to the license terms contained in, the Simplified BSD License
set forth in Section 4.c of the IETF Trust's Legal Provisions set forth in Section 4.c of the IETF Trust's Legal Provisions
Relating to IETF Documents Relating to IETF Documents
(http://trustee.ietf.org/license-info). (http://trustee.ietf.org/license-info).
This version of this YANG module is part of RFC XXXX; see This version of this YANG module is part of RFC XXXX; see
the RFC itself for full legal notices."; the RFC itself for full legal notices.";
// RFC Ed.: replace XXXX with actual RFC number and remove this note // RFC Ed.: replace XXXX with actual RFC number and remove this note
// RFC Ed.: please update the date to the date of publication // RFC Ed.: please update the date to the date of publication
revision 2011-01-16 { revision 2011-03-08 {
description description
"Initial revision"; "Initial revision";
reference reference
"RFC XXXX: Network Configuration Protocol"; "RFC XXXX: Network Configuration Protocol";
} }
extension get-filter-element-attributes { extension get-filter-element-attributes {
description description
"If this extension is present within the "If this extension is present within the
an 'anyxml' statement named 'filter', which must be an 'anyxml' statement named 'filter', which must be
skipping to change at page 99, line 14 skipping to change at page 99, line 14
} }
enum malformed-message { enum malformed-message {
description description
"A message could not be handled because it failed to "A message could not be handled because it failed to
be parsed correctly. For example, the message is not be parsed correctly. For example, the message is not
well-formed XML or it uses an invalid character set."; well-formed XML or it uses an invalid character set.";
} }
} }
description "NETCONF Error Tag"; description "NETCONF Error Tag";
reference "RFC XXXX, section YYY"; reference "RFC XXXX, Appendix A.";
} }
typedef error-severity-type { typedef error-severity-type {
type enumeration { type enumeration {
enum error { enum error {
description "Error severity"; description "Error severity";
} }
enum warning { enum warning {
description "Warning severity"; description "Warning severity";
} }
} }
description "NETCONF Error Severity"; description "NETCONF Error Severity";
reference "RFC XXXX, section YYY"; reference "RFC XXXX, section 4.3.";
} }
typedef edit-operation-type { typedef edit-operation-type {
type enumeration { type enumeration {
enum merge { enum merge {
description description
"The configuration data identified by the "The configuration data identified by the
element containing this attribute is merged element containing this attribute is merged
with the configuration at the corresponding with the configuration at the corresponding
level in the configuration datastore identified level in the configuration datastore identified
skipping to change at page 115, line 47 skipping to change at page 115, line 47
<copy-config> <copy-config>
<target> <target>
<url>file://checkpoint.conf</url> <url>file://checkpoint.conf</url>
</target> </target>
<source> <source>
<running/> <running/>
</source> </source>
</copy-config> </copy-config>
</rpc> </rpc>
To restore the checkpoint file, reverse the source and target To restore the checkpoint file, reverse the <source> and <target>
parameters. parameters.
E.1.3. Loading and Validating the Incoming Configuration. E.1.3. Loading and Validating the Incoming Configuration.
If the :candidate capability is supported, the configuration can be If the :candidate capability is supported, the configuration can be
loaded onto the device without impacting the running system. loaded onto the device without impacting the running system.
<rpc message-id="101" <rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config> <edit-config>
skipping to change at page 120, line 11 skipping to change at page 120, line 11
configurations can be restored on any devices upon which they were configurations can be restored on any devices upon which they were
changed. After the changes have been completely implemented or changed. After the changes have been completely implemented or
completely discarded, the locks on each device can be released. completely discarded, the locks on each device can be released.
Appendix F. Changes from RFC 4741 Appendix F. Changes from RFC 4741
This section lists major changes between this document and RFC 4741. This section lists major changes between this document and RFC 4741.
o Added the "malformed-message" error-tag. o Added the "malformed-message" error-tag.
o Added "remove" enumeration value to the operation attribute. o Added "remove" enumeration value to the "operation" attribute.
o Obsoleted the "partial-operation" error-tag enumeration value. o Obsoleted the "partial-operation" error-tag enumeration value.
o Added <persist> and <persist-id> parameters to the <commit> o Added <persist> and <persist-id> parameters to the <commit>
operation. operation.
o Updated the base protocol URI and clarified the <hello> message o Updated the base protocol URI and clarified the <hello> message
exchange to select and identify the base protocol version in use exchange to select and identify the base protocol version in use
for a particular session. for a particular session.
o Added a YANG module to model the operations and removed the o Added a YANG module to model the operations and removed the
operation layer from the XSD. operation layer from the XSD.
o Clarified lock behavior for the candidate datastore. o Clarified lock behavior for the candidate datastore.
o Clarified the error response server requirements for the "delete" o Clarified the error response server requirements for the "delete"
operation attribute enumeration value. enumeration value of the "operation" attribute.
o Added a namespace wildcarding mechanism for subtree filtering. o Added a namespace wildcarding mechanism for subtree filtering.
o Added a "test-only" value for the <test-option> parameter to the o Added a "test-only" value for the <test-option> parameter to the
<edit-config> operation. <edit-config> operation.
o Added a <cancel-commit> operation. o Added a <cancel-commit> operation.
o Introduced a NETCONF username and a requirement for transport o Introduced a NETCONF username and a requirement for transport
protocols to explain how a username is derived. protocols to explain how a username is derived.
 End of changes. 113 change blocks. 
222 lines changed or deleted 247 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/