RFC 4741
NETCONF Configuration Protocol
12. References
12.1. Normative References
[1] Sperberg-McQueen, C., Paoli, J., Maler, E., and T. Bray, "Extensible Markup Language (XML) 1.0 (Second Edition)", World Wide Web Consortium, http://www.w3.org/TR/2000/REC-xml-20001006, October 2000. [2] Clark, J. and S. DeRose, "XML Path Language (XPath) Version 1.0", World Wide Web Consortium Recommendation, http://www.w3.org/TR/1999/REC-xpath-19991116, November 1999. [3] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [4] Wasserman, M. and T. Goddard, "Using the NETCONF Configuration Protocol over Secure SHell (SSH)", RFC 4742, December 2006.
[5] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [6] Mealling, M., Masinter, L., Hardie, T., and G. Klyne, "An IETF URN Sub-namespace for Registered Protocol Parameters", BCP 73, RFC 3553, June 2003. [7] Mealling, M., "The IETF XML Registry", BCP 81, RFC 3688, January 2004.12.2. Informative References
[8] Clark, J., "XSL Transformations (XSLT) Version 1.0", World Wide Web Consortium Recommendation, http://www.w3.org/TR/1999/REC- xslt-19991116, November 1999. [9] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.1", RFC 4346, April 2006. [10] Ylonen, T. and C. Lonvick, "The Secure Shell (SSH) Protocol Architecture", RFC 4251, January 2006. [11] Rigney, C., Willens, S., Rubens, A., and W. Simpson, "Remote Authentication Dial In User Service (RADIUS)", RFC 2865, June 2000. [12] Hollenbeck, S., Rose, M., and L. Masinter, "Guidelines for the Use of Extensible Markup Language (XML) within IETF Protocols", BCP 70, RFC 3470, January 2003.
Appendix A. NETCONF Error List
Tag: in-use Error-type: protocol, application Severity: error Error-info: none Description: The request requires a resource that already in use. Tag: invalid-value Error-type: protocol, application Severity: error Error-info: none Description: The request specifies an unacceptable value for one or more parameters. Tag: too-big Error-type: transport, rpc, protocol, application Severity: error Error-info: none Description: The request or response (that would be generated) is too large for the implementation to handle. Tag: missing-attribute Error-type: rpc, protocol, application Severity: error Error-info: <bad-attribute> : name of the missing attribute <bad-element> : name of the element that should contain the missing attribute Description: An expected attribute is missing. Tag: bad-attribute Error-type: rpc, protocol, application Severity: error Error-info: <bad-attribute> : name of the attribute w/ bad value <bad-element> : name of the element that contains the attribute with the bad value Description: An attribute value is not correct; e.g., wrong type, out of range, pattern mismatch. Tag: unknown-attribute Error-type: rpc, protocol, application Severity: error Error-info: <bad-attribute> : name of the unexpected attribute <bad-element> : name of the element that contains the unexpected attribute Description: An unexpected attribute is present.
Tag: missing-element
Error-type: rpc, protocol, application
Severity: error
Error-info: <bad-element> : name of the missing element
Description: An expected element is missing.
Tag: bad-element
Error-type: rpc, protocol, application
Severity: error
Error-info: <bad-element> : name of the element w/ bad value
Description: An element value is not correct; e.g., wrong type,
out of range, pattern mismatch.
Tag: unknown-element
Error-type: rpc, protocol, application
Severity: error
Error-info: <bad-element> : name of the unexpected element
Description: An unexpected element is present.
Tag: unknown-namespace
Error-type: rpc, protocol, application
Severity: error
Error-info: <bad-element> : name of the element that contains
the unexpected namespace
<bad-namespace> : name of the unexpected namespace
Description: An unexpected namespace is present.
Tag: access-denied
Error-type: rpc, protocol, application
Severity: error
Error-info: none
Description: Access to the requested RPC, protocol operation,
or data model is denied because authorization failed.
Tag: lock-denied
Error-type: protocol
Severity: error
Error-info: <session-id> : session ID of session holding the
requested lock, or zero to indicate a non-NETCONF
entity holds the lock
Description: Access to the requested lock is denied because the
lock is currently held by another entity.
Tag: resource-denied
Error-type: transport, rpc, protocol, application
Severity: error
Error-info: none
Description: Request could not be completed because of insufficient
resources.
Tag: rollback-failed
Error-type: protocol, application
Severity: error
Error-info: none
Description: Request to rollback some configuration change (via
rollback-on-error or discard-changes operations) was
not completed for some reason.
Tag: data-exists
Error-type: application
Severity: error
Error-info: none
Description: Request could not be completed because the relevant
data model content already exists. For example,
a 'create' operation was attempted on data that
already exists.
Tag: data-missing
Error-type: application
Severity: error
Error-info: none
Description: Request could not be completed because the relevant
data model content does not exist. For example,
a 'replace' or 'delete' operation was attempted on
data that does not exist.
Tag: operation-not-supported
Error-type: rpc, protocol, application
Severity: error
Error-info: none
Description: Request could not be completed because the requested
operation is not supported by this implementation.
Tag: operation-failed
Error-type: rpc, protocol, application
Severity: error
Error-info: none
Description: Request could not be completed because the requested
operation failed for some reason not covered by
any other error condition.
Tag: partial-operation
Error-type: application
Severity: error
Error-info: <ok-element> : identifies an element in the data model
for which the requested operation has been completed
for that node and all its child nodes. This element
can appear zero or more times in the <error-info>
container.
<err-element> : identifies an element in the data model
for which the requested operation has failed for that
node and all its child nodes. This element
can appear zero or more times in the <error-info>
container.
<noop-element> : identifies an element in the data model
for which the requested operation was not attempted for
that node and all its child nodes. This element
can appear zero or more times in the <error-info>
container.
Description: Some part of the requested operation failed or was
not attempted for some reason. Full cleanup has
not been performed (e.g., rollback not supported)
by the server. The error-info container is used
to identify which portions of the application
data model content for which the requested operation
has succeeded (<ok-element>), failed (<bad-element>),
or not been attempted (<noop-element>).
Appendix B. XML Schema for NETCONF RPC and Protocol Operations
BEGIN <?xml version="1.0" encoding="UTF-8"?> <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" targetNamespace="urn:ietf:params:xml:ns:netconf:base:1.0" elementFormDefault="qualified" attributeFormDefault="unqualified" xml:lang="en"> <!-- import standard XML definitions --> <xs:import namespace="http://www.w3.org/XML/1998/namespace" schemaLocation="http://www.w3.org/2001/xml.xsd"> <xs:annotation> <xs:documentation> This import accesses the xml: attribute groups for the xml:lang as declared on the error-message element. </xs:documentation> </xs:annotation> </xs:import> <!-- message-id attribute --> <xs:simpleType name="messageIdType"> <xs:restriction base="xs:string"> <xs:maxLength value="4095"/> </xs:restriction> </xs:simpleType> <!-- Types used for session-id --> <xs:simpleType name="SessionId"> <xs:restriction base="xs:unsignedInt"> <xs:minInclusive value="1"/> </xs:restriction> </xs:simpleType> <xs:simpleType name="SessionIdOrZero"> <xs:restriction base="xs:unsignedInt"/> </xs:simpleType> <!-- <rpc> element --> <xs:complexType name="rpcType"> <xs:sequence> <xs:element ref="rpcOperation"/>
</xs:sequence>
<xs:attribute name="message-id" type="messageIdType"
use="required"/>
<!--
Arbitrary attributes can be supplied with <rpc> element.
-->
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:element name="rpc" type="rpcType"/>
<!--
data types and elements used to construct rpc-errors
-->
<xs:simpleType name="ErrorType">
<xs:restriction base="xs:string">
<xs:enumeration value="transport"/>
<xs:enumeration value="rpc"/>
<xs:enumeration value="protocol"/>
<xs:enumeration value="application"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ErrorTag">
<xs:restriction base="xs:string">
<xs:enumeration value="in-use"/>
<xs:enumeration value="invalid-value"/>
<xs:enumeration value="too-big"/>
<xs:enumeration value="missing-attribute"/>
<xs:enumeration value="bad-attribute"/>
<xs:enumeration value="unknown-attribute"/>
<xs:enumeration value="missing-element"/>
<xs:enumeration value="bad-element"/>
<xs:enumeration value="unknown-element"/>
<xs:enumeration value="unknown-namespace"/>
<xs:enumeration value="access-denied"/>
<xs:enumeration value="lock-denied"/>
<xs:enumeration value="resource-denied"/>
<xs:enumeration value="rollback-failed"/>
<xs:enumeration value="data-exists"/>
<xs:enumeration value="data-missing"/>
<xs:enumeration value="operation-not-supported"/>
<xs:enumeration value="operation-failed"/>
<xs:enumeration value="partial-operation"/>
</xs:restriction>
</xs:simpleType>
<xs:simpleType name="ErrorSeverity">
<xs:restriction base="xs:string">
<xs:enumeration value="error"/>
<xs:enumeration value="warning"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="errorInfoType">
<xs:sequence>
<xs:choice>
<xs:element name="session-id" type="SessionIdOrZero"/>
<xs:sequence minOccurs="0" maxOccurs="unbounded">
<xs:sequence>
<xs:element name="bad-attribute" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="bad-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="ok-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="err-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="noop-element" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
<xs:element name="bad-namespace" type="xs:QName"
minOccurs="0" maxOccurs="1"/>
</xs:sequence>
</xs:sequence>
</xs:choice>
<!-- elements from any other namespace are also allowed
to follow the NETCONF elements -->
<xs:any namespace="##other"
minOccurs="0" maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
<xs:complexType name="rpcErrorType">
<xs:sequence>
<xs:element name="error-type" type="ErrorType"/>
<xs:element name="error-tag" type="ErrorTag"/>
<xs:element name="error-severity" type="ErrorSeverity"/>
<xs:element name="error-app-tag" type="xs:string"
minOccurs="0"/>
<xs:element name="error-path" type="xs:string" minOccurs="0"/>
<xs:element name="error-message" minOccurs="0">
<xs:complexType>
<xs:simpleContent>
<xs:extension base="xs:string">
<xs:attribute ref="xml:lang" use="optional"/>
</xs:extension>
</xs:simpleContent>
</xs:complexType>
</xs:element>
<xs:element name="error-info" type="errorInfoType"
minOccurs="0"/>
</xs:sequence>
</xs:complexType>
<!--
<rpc-reply> element
-->
<xs:complexType name="rpcReplyType">
<xs:choice>
<xs:element name="ok"/>
<xs:group ref="rpcResponse"/>
</xs:choice>
<xs:attribute name="message-id" type="messageIdType"
use="optional"/>
<!--
Any attributes supplied with <rpc> element must be returned
on <rpc-reply>.
-->
<xs:anyAttribute processContents="lax"/>
</xs:complexType>
<xs:group name="rpcResponse">
<xs:sequence>
<xs:element name="rpc-error" type="rpcErrorType"
minOccurs="0" maxOccurs="unbounded"/>
<xs:element name="data" type="dataInlineType" minOccurs="0"/>
</xs:sequence>
</xs:group>
<xs:element name="rpc-reply" type="rpcReplyType"/>
<!--
Type for <test-option> parameter to <edit-config>
-->
<xs:simpleType name="testOptionType">
<xs:restriction base="xs:string">
<xs:enumeration value="test-then-set"/>
<xs:enumeration value="set"/>
</xs:restriction>
</xs:simpleType>
<!--
Type for <error-option> parameter to <edit-config>
-->
<xs:simpleType name="errorOptionType">
<xs:restriction base="xs:string">
<xs:annotation>
<xs:documentation>
Use of the rollback-on-error value requires
the :rollback-on-error capability.
</xs:documentation>
</xs:annotation>
<xs:enumeration value="stop-on-error"/>
<xs:enumeration value="continue-on-error"/>
<xs:enumeration value="rollback-on-error"/>
</xs:restriction>
</xs:simpleType>
<!--
rpcOperationType: used as a base type for all
NETCONF operations
-->
<xs:complexType name="rpcOperationType"/>
<xs:element name="rpcOperation"
type="rpcOperationType" abstract="true"/>
<!--
Type for <config> element
-->
<xs:complexType name="configInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType"/>
</xs:complexContent>
</xs:complexType>
<!--
Type for <data> element
-->
<xs:complexType name="dataInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType"/>
</xs:complexContent>
</xs:complexType>
<!--
Type for <filter> element
-->
<xs:simpleType name="FilterType">
<xs:restriction base="xs:string">
<xs:annotation>
<xs:documentation>
Use of the xpath value requires the :xpath capability.
</xs:documentation>
</xs:annotation>
<xs:enumeration value="subtree"/>
<xs:enumeration value="xpath"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="filterInlineType">
<xs:complexContent>
<xs:extension base="xs:anyType">
<xs:attribute name="type"
type="FilterType" default="subtree"/>
<!-- if type="xpath", the xpath expression
appears in the select element -->
<xs:attribute name="select"/>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<!--
configuration datastore names
-->
<xs:annotation>
<xs:documentation>
The startup datastore can be used only if the :startup
capability is advertised. The candidate datastore can
be used only if the :candidate datastore is advertised.
</xs:documentation>
</xs:annotation>
<xs:complexType name="configNameType"/>
<xs:element name="config-name"
type="configNameType" abstract="true"/>
<xs:element name="startup" type="configNameType"
substitutionGroup="config-name"/>
<xs:element name="candidate" type="configNameType"
substitutionGroup="config-name"/>
<xs:element name="running" type="configNameType"
substitutionGroup="config-name"/>
<!--
operation attribute used in <edit-config>
-->
<xs:simpleType name="editOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="merge"/>
<xs:enumeration value="replace"/>
<xs:enumeration value="create"/>
<xs:enumeration value="delete"/>
</xs:restriction>
</xs:simpleType>
<xs:attribute name="operation"
type="editOperationType" default="merge"/>
<!--
<default-operation> element
-->
<xs:simpleType name="defaultOperationType">
<xs:restriction base="xs:string">
<xs:enumeration value="merge"/>
<xs:enumeration value="replace"/>
<xs:enumeration value="none"/>
</xs:restriction>
</xs:simpleType>
<!--
<url> element
-->
<xs:complexType name="configURIType">
<xs:annotation>
<xs:documentation>
Use of the url element requires the :url capability.
</xs:documentation>
</xs:annotation>
<xs:simpleContent>
<xs:extension base="xs:anyURI"/>
</xs:simpleContent>
</xs:complexType>
<!--
Type for <source> element (except <get-config>)
-->
<xs:complexType name="rpcOperationSourceType">
<xs:choice>
<xs:element name="config" type="configInlineType"/>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
Type for <source> element in <get-config>
-->
<xs:complexType name="getConfigSourceType">
<xs:choice>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
Type for <target> element
-->
<xs:complexType name="rpcOperationTargetType">
<xs:choice>
<xs:element ref="config-name"/>
<xs:element name="url" type="configURIType"/>
</xs:choice>
</xs:complexType>
<!--
<get-config> operation
-->
<xs:complexType name="getConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="source"
type="getConfigSourceType"/>
<xs:element name="filter"
type="filterInlineType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="get-config" type="getConfigType"
substitutionGroup="rpcOperation"/>
<!--
<edit-config> operation
-->
<xs:complexType name="editConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:annotation>
<xs:documentation>
Use of the test-option element requires the
:validate capability. Use of the url element
requires the :url capability.
</xs:documentation>
</xs:annotation>
<xs:element name="target"
type="rpcOperationTargetType"/>
<xs:element name="default-operation"
type="defaultOperationType"
minOccurs="0"/>
<xs:element name="test-option"
type="testOptionType"
minOccurs="0"/>
<xs:element name="error-option"
type="errorOptionType"
minOccurs="0"/>
<xs:choice>
<xs:element name="config"
type="configInlineType"/>
<xs:element name="url"
type="configURIType"/>
</xs:choice>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="edit-config" type="editConfigType"
substitutionGroup="rpcOperation"/>
<!--
<copy-config> operation
-->
<xs:complexType name="copyConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
<xs:element name="source" type="rpcOperationSourceType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="copy-config" type="copyConfigType"
substitutionGroup="rpcOperation"/>
<!--
<delete-config> operation
-->
<xs:complexType name="deleteConfigType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="delete-config" type="deleteConfigType"
substitutionGroup="rpcOperation"/>
<!--
<get> operation
-->
<xs:complexType name="getType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="filter"
type="filterInlineType" minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="get" type="getType"
substitutionGroup="rpcOperation"/>
<!--
<lock> operation
-->
<xs:complexType name="lockType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target"
type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="lock" type="lockType"
substitutionGroup="rpcOperation"/>
<!--
<unlock> operation
-->
<xs:complexType name="unlockType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="target" type="rpcOperationTargetType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="unlock" type="unlockType"
substitutionGroup="rpcOperation"/>
<!--
<validate> operation
-->
<xs:complexType name="validateType">
<xs:annotation>
<xs:documentation>
The validate operation requires the :validate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="source" type="rpcOperationSourceType"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="validate" type="validateType"
substitutionGroup="rpcOperation"/>
<!--
<commit> operation
-->
<xs:simpleType name="confirmTimeoutType">
<xs:restriction base="xs:unsignedInt">
<xs:minInclusive value="1"/>
</xs:restriction>
</xs:simpleType>
<xs:complexType name="commitType">
<xs:annotation>
<xs:documentation>
The commit operation requires the :candidate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:annotation>
<xs:documentation>
Use of the confirmed and confirm-timeout elements
requires the :confirmed-commit capability.
</xs:documentation>
</xs:annotation>
<xs:element name="confirmed" minOccurs="0"/>
<xs:element name="confirm-timeout"
type="confirmTimeoutType"
minOccurs="0"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="commit" type="commitType"
substitutionGroup="rpcOperation"/>
<!--
<discard-changes> operation
-->
<xs:complexType name="discardChangesType">
<xs:annotation>
<xs:documentation>
The discard-changes operation requires the
:candidate capability.
</xs:documentation>
</xs:annotation>
<xs:complexContent>
<xs:extension base="rpcOperationType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="discard-changes"
type="discardChangesType"
substitutionGroup="rpcOperation"/>
<!--
<close-session> operation
-->
<xs:complexType name="closeSessionType">
<xs:complexContent>
<xs:extension base="rpcOperationType"/>
</xs:complexContent>
</xs:complexType>
<xs:element name="close-session" type="closeSessionType"
substitutionGroup="rpcOperation"/>
<!--
<kill-session> operation
-->
<xs:complexType name="killSessionType">
<xs:complexContent>
<xs:extension base="rpcOperationType">
<xs:sequence>
<xs:element name="session-id"
type="SessionId" minOccurs="1"/>
</xs:sequence>
</xs:extension>
</xs:complexContent>
</xs:complexType>
<xs:element name="kill-session" type="killSessionType"
substitutionGroup="rpcOperation"/>
<!--
<hello> element
-->
<xs:element name="hello">
<xs:complexType>
<xs:sequence>
<xs:element name="capabilities">
<xs:complexType>
<xs:sequence>
<xs:element name="capability" type="xs:anyURI"
maxOccurs="unbounded"/>
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="session-id"
type="SessionId" minOccurs="0"/>
</xs:sequence>
</xs:complexType>
</xs:element>
</xs:schema>
END
Appendix C. Capability Template
C.1. capability-name (template)
C.1.1. Overview
C.1.2. Dependencies
C.1.3. Capability Identifier
The {name} capability is identified by the following capability string: {capability uri}C.1.4. New Operations
C.1.4.1. <op-name>
C.1.5. Modifications to Existing Operations
C.1.5.1. <op-name>
If existing operations are not modified by this capability, this section may be omitted.C.1.6. Interactions with Other Capabilities
If this capability does not interact with other capabilities, this section may be omitted.
Appendix D. Configuring Multiple Devices with NETCONF
D.1. Operations on Individual Devices
Consider the work involved in performing a configuration update against a single individual device. In making a change to the configuration, the application needs to build trust that its change has been made correctly and that it has not impacted the operation of the device. The application (and the application user) should feel confident that their change has not damaged the network. Protecting each individual device consists of a number of steps: o Acquiring the configuration lock. o Loading the update. o Validating the incoming configuration. o Checkpointing the running configuration. o Changing the running configuration. o Testing the new configuration. o Making the change permanent (if desired). o Releasing the configuration lock. Let's look at the details of each step.D.1.1. Acquiring the Configuration Lock
A lock should be acquired to prevent simultaneous updates from multiple sources. If multiple sources are affecting the device, the application is hampered in both testing of its change to the configuration and in recovery should the update fail. Acquiring a short-lived lock is a simple defense to prevent other parties from introducing unrelated changes. The lock can be acquired using the <lock> operation. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <lock> <target> <running/> </target>
</lock>
</rpc>
D.1.2. Loading the Update
The configuration can be loaded onto the device without impacting the
running system. If the :url capability is supported and lists "file"
as a supported scheme, incoming changes can be placed in a local
file.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<copy-config>
<target>
<url>file://incoming.conf</url>
</target>
<source>
<config>
<!-- place incoming configuration here -->
</config>
</source>
</copy-config>
</rpc>
If the :candidate capability is supported, the candidate
configuration can be used.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<candidate/>
</target>
<config>
<!-- place incoming configuration here -->
</config>
</edit-config>
</rpc>
If the update fails, the user file can be deleted using the
<delete-config> operation, or the candidate configuration can be
reverted using the <discard-changes> operation.
D.1.3. Validating the Incoming Configuration
Before the incoming configuration is applied, validating it is often useful. Validation allows the application to gain confidence that the change will succeed and simplifies recovery if it does not. If the device supports the :url capability and lists "file" as a supported scheme, use the <validate> operation with the <source> parameter set to the proper user file: <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <validate> <source> <url>file://incoming.conf</url> </source> </validate> </rpc> If the device supports the :candidate capability, some validation will be performed as part of loading the incoming configuration into the candidate. For full validation, either pass the <validate> parameter during the <edit-config> step given above, or use the <validate> operation with the <source> parameter set to <candidate>. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <validate> <source> <candidate/> </source> </validate> </rpc>D.1.4. Checkpointing the Running Configuration
The running configuration can be saved into a local file as a checkpoint before loading the new configuration. If the update fails, the configuration can be restored by reloading the checkpoint file. The checkpoint file can be created using the <copy-config> operation. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <copy-config> <target> <url>file://checkpoint.conf</url>
</target>
<source>
<running/>
</source>
</copy-config>
</rpc>
To restore the checkpoint file, reverse the source and target
parameters.
D.1.5. Changing the Running Configuration
When the incoming configuration has been safely loaded onto the
device and validated, it is ready to impact the running system.
If the device supports the :url capability and lists "file" as a
supported scheme, use the <edit-config> operation to merge the
incoming configuration into the running configuration.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<edit-config>
<target>
<running/>
</target>
<config>
<url>file://incoming.conf</url>
</config>
</edit-config>
</rpc>
If the device supports the :candidate capability, use the <commit>
operation to set the running configuration to the candidate
configuration. Use the <confirmed> parameter to allow automatic
reversion to the original configuration if connectivity to the device
fails.
<rpc message-id="101"
xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
<commit>
<confirmed/>
<confirm-timeout>120</confirm-timeout>
</commit>
</rpc>
D.1.6. Testing the New Configuration
Now that the incoming configuration has been integrated into the running configuration, the application needs to gain trust that the change has affected the device in the way intended without affecting it negatively. To gain this confidence, the application can run tests of the operational state of the device. The nature of the test is dependent on the nature of the change and is outside the scope of this document. Such tests may include reachability from the system running the application (using ping), changes in reachability to the rest of the network (by comparing the device's routing table), or inspection of the particular change (looking for operational evidence of the BGP peer that was just added).D.1.7. Making the Change Permanent
When the configuration change is in place and the application has sufficient faith in the proper function of this change, the application should make the change permanent. If the device supports the :startup capability, the current configuration can be saved to the startup configuration by using the startup configuration as the target of the <copy-config> operation. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <copy-config> <target> <startup/> </target> <source> <running/> </source> </copy-config> </rpc> If the device supports the :candidate capability and a confirmed commit was requested, the confirming commit must be sent before the timeout expires. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <commit/> </rpc>
D.1.8. Releasing the Configuration Lock
When the configuration update is complete, the lock must be released, allowing other applications access to the configuration. Use the <unlock> operation to release the configuration lock. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <unlock> <target> <running/> </target> </unlock> </rpc>D.2. Operations on Multiple Devices
When a configuration change requires updates across a number of devices, care should be taken to provide the required transaction semantics. The NETCONF protocol contains sufficient primitives upon which transaction-oriented operations can be built. Providing complete transactional semantics across multiple devices is prohibitively expensive, but the size and number of windows for failure scenarios can be reduced. There are two classes of multi-device operations. The first class allows the operation to fail on individual devices without requiring all devices to revert to their original state. The operation can be retried at a later time, or its failure simply reported to the user. An example of this class might be adding an NTP server. For this class of operations, failure avoidance and recovery are focused on the individual device. This means recovery of the device, reporting the failure, and perhaps scheduling another attempt. The second class is more interesting, requiring that the operation should complete on all devices or be fully reversed. The network should either be transformed into a new state or be reset to its original state. For example, a change to a VPN may require updates to a number of devices. Another example of this might be adding a class-of-service definition. Leaving the network in a state where only a portion of the devices have been updated with the new definition will lead to future failures when the definition is referenced. To give transactional semantics, the same steps used in single device operations listed above are used, but are performed in parallel across all devices. Configuration locks should be acquired on all
target devices and kept until all devices are updated and the changes made permanent. Configuration changes should be uploaded and validation performed across all devices. Checkpoints should be made on each device. Then the running configuration can be changed, tested, and made permanent. If any of these steps fail, the previous configurations can be restored on any devices upon which they were changed. After the changes have been completely implemented or completely discarded, the locks on each device can be released.Appendix E. Deferred Features
The following features have been deferred until a future revision of this document. o Granular locking of configuration objects. o Named configuration files/datastores. o Support for multiple NETCONF channels. o Asynchronous notifications. o Explicit protocol support for rollback of configuration changes to prior versions.
Editor's Address
Rob Enns Juniper Networks 1194 North Mathilda Ave Sunnyvale, CA 94089 US EMail: rpe@juniper.net
Full Copyright Statement Copyright (C) The IETF Trust (2006). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST, AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgement Funding for the RFC Editor function is currently provided by the Internet Society.