Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 6241

Network Configuration Protocol (NETCONF)

Pages: 113
Proposed Standard
Errata
Obsoletes:  4741
Updated by:  7803
Part 5 of 5 – Pages 85 to 113
First   Prev   None

Top   ToC   RFC6241 - Page 85   prevText

Appendix C. YANG Module for NETCONF Protocol Operations

This section is normative. The ietf-netconf YANG module imports typedefs from [RFC6021]. <CODE BEGINS> file "ietf-netconf@2011-06-01.yang" module ietf-netconf { // the namespace for NETCONF XML definitions is unchanged // from RFC 4741, which this document replaces namespace "urn:ietf:params:xml:ns:netconf:base:1.0"; prefix nc; import ietf-inet-types { prefix inet; } organization "IETF NETCONF (Network Configuration) Working Group"; contact "WG Web: <http://tools.ietf.org/wg/netconf/> WG List: <netconf@ietf.org> WG Chair: Bert Wijnen <bertietf@bwijnen.net> WG Chair: Mehmet Ersue <mehmet.ersue@nsn.com> Editor: Martin Bjorklund <mbj@tail-f.com> Editor: Juergen Schoenwaelder <j.schoenwaelder@jacobs-university.de> Editor: Andy Bierman <andy.bierman@brocade.com>";
Top   ToC   RFC6241 - Page 86
    description
      "NETCONF Protocol Data Types and Protocol Operations.

       Copyright (c) 2011 IETF Trust and the persons identified as
       the document authors.  All rights reserved.

       Redistribution and use in source and binary forms, with or
       without modification, is permitted pursuant to, and subject
       to the license terms contained in, the Simplified BSD License
       set forth in Section 4.c of the IETF Trust's Legal Provisions
       Relating to IETF Documents
       (http://trustee.ietf.org/license-info).

       This version of this YANG module is part of RFC 6241; see
       the RFC itself for full legal notices.";
    revision 2011-06-01 {
      description
        "Initial revision";
      reference
        "RFC 6241: Network Configuration Protocol";
    }

    extension get-filter-element-attributes {
      description
        "If this extension is present within an 'anyxml'
         statement named 'filter', which must be conceptually
         defined within the RPC input section for the <get>
         and <get-config> protocol operations, then the
         following unqualified XML attribute is supported
         within the <filter> element, within a <get> or
         <get-config> protocol operation:

           type : optional attribute with allowed
                  value strings 'subtree' and 'xpath'.
                  If missing, the default value is 'subtree'.

         If the 'xpath' feature is supported, then the
         following unqualified XML attribute is
         also supported:

           select: optional attribute containing a
                   string representing an XPath expression.
                   The 'type' attribute must be equal to 'xpath'
                   if this attribute is present.";
    }

    // NETCONF capabilities defined as features
    feature writable-running {
Top   ToC   RFC6241 - Page 87
      description
        "NETCONF :writable-running capability;
         If the server advertises the :writable-running
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.2";
    }

    feature candidate {
      description
        "NETCONF :candidate capability;
         If the server advertises the :candidate
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.3";
    }

    feature confirmed-commit {
      if-feature candidate;
      description
        "NETCONF :confirmed-commit:1.1 capability;
         If the server advertises the :confirmed-commit:1.1
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";

      reference "RFC 6241, Section 8.4";
    }

    feature rollback-on-error {
      description
        "NETCONF :rollback-on-error capability;
         If the server advertises the :rollback-on-error
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.5";
    }

    feature validate {
      description
        "NETCONF :validate:1.1 capability;
         If the server advertises the :validate:1.1
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
Top   ToC   RFC6241 - Page 88
      reference "RFC 6241, Section 8.6";
    }

    feature startup {
      description
        "NETCONF :startup capability;
         If the server advertises the :startup
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.7";
    }

    feature url {
      description
        "NETCONF :url capability;
         If the server advertises the :url
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.8";
    }

    feature xpath {
      description
        "NETCONF :xpath capability;
         If the server advertises the :xpath
         capability for a session, then this feature must
         also be enabled for that session.  Otherwise,
         this feature must not be enabled.";
      reference "RFC 6241, Section 8.9";
    }

    // NETCONF Simple Types

    typedef session-id-type {
      type uint32 {
        range "1..max";
      }
      description
        "NETCONF Session Id";
    }

    typedef session-id-or-zero-type {
      type uint32;
      description
        "NETCONF Session Id or Zero to indicate none";
    }
Top   ToC   RFC6241 - Page 89
    typedef error-tag-type {
      type enumeration {
         enum in-use {
           description
             "The request requires a resource that
              already is in use.";
         }
         enum invalid-value {
           description
             "The request specifies an unacceptable value for one
              or more parameters.";
         }
         enum too-big {
           description
             "The request or response (that would be generated) is
              too large for the implementation to handle.";
         }
         enum missing-attribute {
           description
             "An expected attribute is missing.";
         }
         enum bad-attribute {
           description
             "An attribute value is not correct; e.g., wrong type,
              out of range, pattern mismatch.";
         }
         enum unknown-attribute {
           description
             "An unexpected attribute is present.";
         }
         enum missing-element {
           description
             "An expected element is missing.";
         }
         enum bad-element {
           description
             "An element value is not correct; e.g., wrong type,
              out of range, pattern mismatch.";
         }
         enum unknown-element {
           description
             "An unexpected element is present.";
         }
         enum unknown-namespace {
           description
             "An unexpected namespace is present.";
         }
         enum access-denied {
Top   ToC   RFC6241 - Page 90
           description
             "Access to the requested protocol operation or
              data model is denied because authorization failed.";
         }
         enum lock-denied {
           description
             "Access to the requested lock is denied because the
              lock is currently held by another entity.";
         }
         enum resource-denied {
           description
             "Request could not be completed because of
              insufficient resources.";
         }
         enum rollback-failed {
           description
             "Request to roll back some configuration change (via
              rollback-on-error or <discard-changes> operations)
              was not completed for some reason.";

         }
         enum data-exists {
           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.";
         }
         enum data-missing {
           description
             "Request could not be completed because the relevant
              data model content does not exist.  For example,
              a 'delete' operation was attempted on
              data that does not exist.";
         }
         enum operation-not-supported {
           description
             "Request could not be completed because the requested
              operation is not supported by this implementation.";
         }
         enum operation-failed {
           description
             "Request could not be completed because the requested
              operation failed for some reason not covered by
              any other error condition.";
         }
         enum partial-operation {
           description
Top   ToC   RFC6241 - Page 91
             "This error-tag is obsolete, and SHOULD NOT be sent
              by servers conforming to this document.";
         }
         enum malformed-message {
           description
             "A message could not be handled because it failed to
              be parsed correctly.  For example, the message is not
              well-formed XML or it uses an invalid character set.";
         }
       }
       description "NETCONF Error Tag";
       reference "RFC 6241, Appendix A";
    }

    typedef error-severity-type {
      type enumeration {
        enum error {
          description "Error severity";
        }
        enum warning {
          description "Warning severity";
        }
      }
      description "NETCONF Error Severity";
      reference "RFC 6241, Section 4.3";
    }

    typedef edit-operation-type {
      type enumeration {
        enum merge {
          description
            "The configuration data identified by the
             element containing this attribute is merged
             with the configuration at the corresponding
             level in the configuration datastore identified
             by the target parameter.";
        }
        enum replace {
          description
            "The configuration data identified by the element
             containing this attribute replaces any related
             configuration in the configuration datastore
             identified by the target parameter.  If no such
             configuration data exists in the configuration
             datastore, it is created.  Unlike a
             <copy-config> operation, which replaces the
             entire target configuration, only the configuration
             actually present in the config parameter is affected.";
Top   ToC   RFC6241 - Page 92
        }
        enum create {
          description
            "The configuration data identified by the element
             containing this attribute is added to the
             configuration if and only if the configuration
             data does not already exist in the configuration
             datastore.  If the configuration data exists, an
             <rpc-error> element is returned with an
             <error-tag> value of 'data-exists'.";
        }
        enum delete {
          description
            "The configuration data identified by the element
             containing this attribute is deleted from the
             configuration if and only if the configuration
             data currently exists in the configuration
             datastore.  If the configuration data does not
             exist, an <rpc-error> element is returned with
             an <error-tag> value of 'data-missing'.";
        }
        enum remove {
          description
            "The configuration data identified by the element
             containing this attribute is deleted from the
             configuration if the configuration
             data currently exists in the configuration
             datastore.  If the configuration data does not
             exist, the 'remove' operation is silently ignored
             by the server.";
        }
      }
      default "merge";
      description "NETCONF 'operation' attribute values";
      reference "RFC 6241, Section 7.2";
    }

    // NETCONF Standard Protocol Operations

    rpc get-config {
      description
        "Retrieve all or part of a specified configuration.";

      reference "RFC 6241, Section 7.1";

      input {
        container source {
          description
Top   ToC   RFC6241 - Page 93
            "Particular configuration to retrieve.";

          choice config-source {
            mandatory true;
            description
              "The configuration to retrieve.";
            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config source.";
            }
            leaf running {
              type empty;
              description
                "The running configuration is the config source.";
            }
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config source.
                 This is optional-to-implement on the server because
                 not all servers will support filtering for this
                 datastore.";
            }
          }
        }

        anyxml filter {
          description
            "Subtree or XPath filter to use.";
          nc:get-filter-element-attributes;
        }
      }

      output {
        anyxml data {
          description
            "Copy of the source datastore subset that matched
             the filter criteria (if any).  An empty data container
             indicates that the request did not produce any results.";
        }
      }
    }

    rpc edit-config {
      description
Top   ToC   RFC6241 - Page 94
        "The <edit-config> operation loads all or part of a specified
         configuration to the specified target configuration.";

      reference "RFC 6241, Section 7.2";

      input {
        container target {
          description
            "Particular configuration to edit.";

          choice config-target {
            mandatory true;
            description
              "The configuration target.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config target.";
            }
            leaf running {
              if-feature writable-running;
              type empty;
              description
                "The running configuration is the config source.";
            }
          }
        }

        leaf default-operation {
          type enumeration {
            enum merge {
              description
                "The default operation is merge.";
            }
            enum replace {
              description
                "The default operation is replace.";
            }
            enum none {
              description
                "There is no default operation.";
            }
          }
          default "merge";
          description
            "The default operation to use.";
Top   ToC   RFC6241 - Page 95
        }

        leaf test-option {
          if-feature validate;
          type enumeration {
            enum test-then-set {
              description
                "The server will test and then set if no errors.";
            }
            enum set {
              description
                "The server will set without a test first.";
            }

            enum test-only {
              description
                "The server will only test and not set, even
                 if there are no errors.";
            }
          }
          default "test-then-set";
          description
            "The test option to use.";
        }

        leaf error-option {
          type enumeration {
            enum stop-on-error {
              description
                "The server will stop on errors.";
            }
            enum continue-on-error {
              description
                "The server may continue on errors.";
            }
            enum rollback-on-error {
              description
                "The server will roll back on errors.
                 This value can only be used if the 'rollback-on-error'
                 feature is supported.";
            }
          }
          default "stop-on-error";
          description
            "The error option to use.";
        }

        choice edit-content {
Top   ToC   RFC6241 - Page 96
          mandatory true;
          description
            "The content for the edit operation.";

          anyxml config {
            description
              "Inline Config content.";
          }
          leaf url {
            if-feature url;
            type inet:uri;
            description
              "URL-based config content.";
          }
        }
      }
    }

    rpc copy-config {
      description
        "Create or replace an entire configuration datastore with the
         contents of another complete configuration datastore.";

      reference "RFC 6241, Section 7.3";

      input {
        container target {
          description
            "Particular configuration to copy to.";

          choice config-target {
            mandatory true;
            description
              "The configuration target of the copy operation.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config target.";
            }
            leaf running {
              if-feature writable-running;
              type empty;
              description
                "The running configuration is the config target.
                 This is optional-to-implement on the server.";
            }
Top   ToC   RFC6241 - Page 97
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config target.";
            }
            leaf url {
              if-feature url;
              type inet:uri;
              description
                "The URL-based configuration is the config target.";
            }
          }
        }

        container source {
          description
            "Particular configuration to copy from.";

          choice config-source {
            mandatory true;
            description
              "The configuration source for the copy operation.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config source.";
            }
            leaf running {
              type empty;
              description
                "The running configuration is the config source.";
            }
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config source.";
            }
            leaf url {
              if-feature url;
              type inet:uri;
              description
                "The URL-based configuration is the config source.";
            }
            anyxml config {
Top   ToC   RFC6241 - Page 98
              description
                "Inline Config content: <config> element.  Represents
                 an entire configuration datastore, not
                 a subset of the running datastore.";
            }
          }
        }
      }
    }

    rpc delete-config {
      description
        "Delete a configuration datastore.";

      reference "RFC 6241, Section 7.4";

      input {
        container target {
          description
            "Particular configuration to delete.";

          choice config-target {
            mandatory true;
            description
              "The configuration target to delete.";

            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config target.";
            }
            leaf url {
              if-feature url;
              type inet:uri;
              description
                "The URL-based configuration is the config target.";
            }
          }
        }
      }
    }

    rpc lock {
      description
        "The lock operation allows the client to lock the configuration
         system of a device.";
Top   ToC   RFC6241 - Page 99
      reference "RFC 6241, Section 7.5";

      input {
        container target {
          description
            "Particular configuration to lock.";

          choice config-target {
            mandatory true;
            description
              "The configuration target to lock.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config target.";
            }
            leaf running {
              type empty;
              description
                "The running configuration is the config target.";
            }
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config target.";
            }
          }
        }
      }
    }

    rpc unlock {
      description
        "The unlock operation is used to release a configuration lock,
         previously obtained with the 'lock' operation.";

      reference "RFC 6241, Section 7.6";

      input {
        container target {
          description
            "Particular configuration to unlock.";

          choice config-target {
            mandatory true;
Top   ToC   RFC6241 - Page 100
            description
              "The configuration target to unlock.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config target.";
            }
            leaf running {
              type empty;
              description
                "The running configuration is the config target.";
            }
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config target.";
            }
          }
        }
      }
    }

    rpc get {
      description
        "Retrieve running configuration and device state information.";

      reference "RFC 6241, Section 7.7";

      input {
        anyxml filter {
          description
            "This parameter specifies the portion of the system
             configuration and state data to retrieve.";
          nc:get-filter-element-attributes;
        }
      }

      output {
        anyxml data {
          description
            "Copy of the running datastore subset and/or state
             data that matched the filter criteria (if any).
             An empty data container indicates that the request did not
             produce any results.";
        }
Top   ToC   RFC6241 - Page 101
      }
    }

    rpc close-session {
      description
        "Request graceful termination of a NETCONF session.";

      reference "RFC 6241, Section 7.8";
    }

    rpc kill-session {
      description
        "Force the termination of a NETCONF session.";

      reference "RFC 6241, Section 7.9";

      input {
        leaf session-id {
          type session-id-type;
          mandatory true;
          description
            "Particular session to kill.";
        }
      }
    }

    rpc commit {
      if-feature candidate;

      description
        "Commit the candidate configuration as the device's new
         current configuration.";

      reference "RFC 6241, Section 8.3.4.1";

      input {
        leaf confirmed {
          if-feature confirmed-commit;
          type empty;
          description
            "Requests a confirmed commit.";
          reference "RFC 6241, Section 8.3.4.1";
        }

        leaf confirm-timeout {
          if-feature confirmed-commit;
          type uint32 {
            range "1..max";
Top   ToC   RFC6241 - Page 102
          }
          units "seconds";
          default "600";   // 10 minutes
          description
            "The timeout interval for a confirmed commit.";
          reference "RFC 6241, Section 8.3.4.1";
        }

        leaf persist {
          if-feature confirmed-commit;
          type string;
          description
            "This parameter is used to make a confirmed commit
             persistent.  A persistent confirmed commit is not aborted
             if the NETCONF session terminates.  The only way to abort
             a persistent confirmed commit is to let the timer expire,
             or to use the <cancel-commit> operation.

             The value of this parameter is a token that must be given
             in the 'persist-id' parameter of <commit> or
             <cancel-commit> operations in order to confirm or cancel
             the persistent confirmed commit.

             The token should be a random string.";
          reference "RFC 6241, Section 8.3.4.1";
        }

        leaf persist-id {
          if-feature confirmed-commit;
          type string;
          description
            "This parameter is given in order to commit a persistent
             confirmed commit.  The value must be equal to the value
             given in the 'persist' parameter to the <commit> operation.
             If it does not match, the operation fails with an
            'invalid-value' error.";
          reference "RFC 6241, Section 8.3.4.1";
        }

      }
    }

    rpc discard-changes {
      if-feature candidate;

      description
        "Revert the candidate configuration to the current
         running configuration.";
Top   ToC   RFC6241 - Page 103
      reference "RFC 6241, Section 8.3.4.2";
    }

    rpc cancel-commit {
      if-feature confirmed-commit;
      description
        "This operation is used to cancel an ongoing confirmed commit.
         If the confirmed commit is persistent, the parameter
         'persist-id' must be given, and it must match the value of the
         'persist' parameter.";
      reference "RFC 6241, Section 8.4.4.1";

      input {
        leaf persist-id {
          type string;
          description
            "This parameter is given in order to cancel a persistent
             confirmed commit.  The value must be equal to the value
             given in the 'persist' parameter to the <commit> operation.
             If it does not match, the operation fails with an
            'invalid-value' error.";
        }
      }
    }

    rpc validate {
      if-feature validate;

      description
        "Validates the contents of the specified configuration.";

      reference "RFC 6241, Section 8.6.4.1";

      input {
        container source {
          description
            "Particular configuration to validate.";

          choice config-source {
            mandatory true;
            description
              "The configuration source to validate.";

            leaf candidate {
              if-feature candidate;
              type empty;
              description
                "The candidate configuration is the config source.";
Top   ToC   RFC6241 - Page 104
            }
            leaf running {
              type empty;
              description
                "The running configuration is the config source.";
            }
            leaf startup {
              if-feature startup;
              type empty;
              description
                "The startup configuration is the config source.";
            }
            leaf url {
              if-feature url;
              type inet:uri;
              description
                "The URL-based configuration is the config source.";
            }
            anyxml config {
              description
                "Inline Config content: <config> element.  Represents
                 an entire configuration datastore, not
                 a subset of the running datastore.";
            }
          }
        }
      }
    }

  }

  <CODE ENDS>
Top   ToC   RFC6241 - Page 105

Appendix D. Capability Template

This non-normative section defines a template that can be used to define protocol capabilities. Data models written in YANG usually do not need to define protocol capabilities since the usage of YANG automatically leads to a capability announcing the data model and any optional portions of the data model, so called features in YANG terminology. The capabilities template is intended to be used in cases where the YANG mechanisms are not powerful enough (e.g., for handling parameterized features) or a different data modeling language is used.

D.1. capability-name (template)

D.1.1. Overview

D.1.2. Dependencies

D.1.3. Capability Identifier

The {name} capability is identified by the following capability string: {capability uri}

D.1.4. New Operations

D.1.4.1. <op-name>

D.1.5. Modifications to Existing Operations

D.1.5.1. <op-name>
If existing operations are not modified by this capability, this section may be omitted.

D.1.6. Interactions with Other Capabilities

If this capability does not interact with other capabilities, this section may be omitted.
Top   ToC   RFC6241 - Page 106

Appendix E. Configuring Multiple Devices with NETCONF

This section is non-normative.

E.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 Checkpointing the running configuration. o Loading and validating the incoming 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.

E.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 if the update fails. 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.
Top   ToC   RFC6241 - Page 107
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <lock>
         <target>
           <running/>
         </target>
       </lock>
     </rpc>

   If the :candidate capability is supported, the candidate
   configuration should be locked.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <lock>
         <target>
           <candidate/>
         </target>
       </lock>
     </rpc>

E.1.2. 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.
Top   ToC   RFC6241 - Page 108

E.1.3. Loading and Validating the Incoming Configuration

If the :candidate capability is supported, the configuration can be loaded onto the device without impacting the running system. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <edit-config> <target> <candidate/> </target> <config> <!-- place incoming configuration changes here --> </config> </edit-config> </rpc> If the device supports the :validate:1.1 capability, it will by default validate the incoming configuration when it is loaded into the candidate. To avoid this validation, pass the <test-option> parameter with the value "set". Full validation can be requested with the <validate> operation. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <validate> <source> <candidate/> </source> </validate> </rpc>

E.1.4. 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 :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.
Top   ToC   RFC6241 - Page 109
     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <commit>
         <confirmed/>
         <confirm-timeout>120</confirm-timeout>
       </commit>
     </rpc>

   If the candidate is not supported by the device, the incoming
   configuration change is loaded directly into running.

     <rpc message-id="101"
          xmlns="urn:ietf:params:xml:ns:netconf:base:1.0">
       <edit-config>
         <target>
           <running/>
         </target>
         <config>
           <!-- place incoming configuration changes here -->
         </config>
       </edit-config>
     </rpc>

E.1.5. 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).

E.1.6. 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 is expected to 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.
Top   ToC   RFC6241 - Page 110
     <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>

E.1.7. 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> If the :candidate capability is supported, the candidate configuration should be unlocked. <rpc message-id="101" xmlns="urn:ietf:params:xml:ns:netconf:base:1.0"> <unlock> <target> <candidate/> </target> </unlock> </rpc>
Top   ToC   RFC6241 - Page 111

E.2. Operations on Multiple Devices

When a configuration change requires updates across a number of devices, care needs to 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.
Top   ToC   RFC6241 - Page 112

Appendix F. Changes from RFC 4741

This section lists major changes between this document and RFC 4741. o Added the "malformed-message" error-tag. o Added "remove" enumeration value to the "operation" attribute. o Obsoleted the "partial-operation" error-tag enumeration value. o Added <persist> and <persist-id> parameters to the <commit> operation. o Updated the base protocol URI and clarified the <hello> message exchange to select and identify the base protocol version in use for a particular session. o Added a YANG module to model the operations and removed the operation layer from the XSD. o Clarified lock behavior for the candidate datastore. o Clarified the error response server requirements for the "delete" enumeration value of the "operation" attribute. o Added a namespace wildcarding mechanism for subtree filtering. o Added a "test-only" value for the <test-option> parameter to the <edit-config> operation. o Added a <cancel-commit> operation. o Introduced a NETCONF username and a requirement for transport protocols to explain how a username is derived.
Top   ToC   RFC6241 - Page 113

Authors' Addresses

Rob Enns (editor) Juniper Networks EMail: rob.enns@gmail.com Martin Bjorklund (editor) Tail-f Systems EMail: mbj@tail-f.com Juergen Schoenwaelder (editor) Jacobs University EMail: j.schoenwaelder@jacobs-university.de Andy Bierman (editor) Brocade EMail: andy.bierman@brocade.com