Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 4741

NETCONF Configuration Protocol

Pages: 95
Obsoleted by:  6241
Part 4 of 4 – Pages 68 to 95
First   Prev   None

ToP   noToC   RFC4741 - Page 68   prevText

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.
ToP   noToC   RFC4741 - Page 69
   [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.
ToP   noToC   RFC4741 - Page 70

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.
ToP   noToC   RFC4741 - Page 71
   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.
ToP   noToC   RFC4741 - Page 72
   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.
ToP   noToC   RFC4741 - Page 73
   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>).
ToP   noToC   RFC4741 - Page 74

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"/>
ToP   noToC   RFC4741 - Page 75
       </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>
ToP   noToC   RFC4741 - Page 76
     </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>
ToP   noToC   RFC4741 - Page 77
     </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"/>
ToP   noToC   RFC4741 - Page 78
       </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>
ToP   noToC   RFC4741 - Page 79
       </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">
ToP   noToC   RFC4741 - Page 80
       <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"/>
ToP   noToC   RFC4741 - Page 81
           </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>
ToP   noToC   RFC4741 - Page 82
         <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"/>
ToP   noToC   RFC4741 - Page 83
           </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">
ToP   noToC   RFC4741 - Page 84
       <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>
ToP   noToC   RFC4741 - Page 85
     </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
ToP   noToC   RFC4741 - Page 86

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.
ToP   noToC   RFC4741 - Page 87

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>
ToP   noToC   RFC4741 - Page 88
       </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.
ToP   noToC   RFC4741 - Page 89

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>
ToP   noToC   RFC4741 - Page 90
         </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>
ToP   noToC   RFC4741 - Page 91

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>
ToP   noToC   RFC4741 - Page 92

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
ToP   noToC   RFC4741 - Page 93
   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.
ToP   noToC   RFC4741 - Page 94

Editor's Address

Rob Enns Juniper Networks 1194 North Mathilda Ave Sunnyvale, CA 94089 US EMail: rpe@juniper.net
ToP   noToC   RFC4741 - Page 95
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.