tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search

RFC 4741

 
 
 

NETCONF Configuration Protocol

Part 4 of 4, p. 68 to 95
Prev RFC Part

 


prevText      Top      Up      ToC       Page 68 
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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       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      Up      ToC       Page 94 
Editor's Address

   Rob Enns
   Juniper Networks
   1194 North Mathilda Ave
   Sunnyvale, CA  94089
   US

   EMail: rpe@juniper.net

Top      Up      ToC       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.