Editing the Candidate Configuration

To change the candidate configuration on a device, a client application emits the <copy-config>, the <edit-config>, or the <discard-changes> tag element and the corresponding tag subelements within the <rpc> tag element.

<rpc>
    <copy-config> 
        <target><candidate/></target>
        <default-operation> (merge | none | replace) </default-operation>
        <error-operation> (ignore-error | stop-on-error) </error-operation>
        <source><url>location</url></source>
    </copy-config> 
</rpc>
]]>]]>

<rpc>
     <edit-config> 
        <target><candidate/></target>
        <default-operation>operation</default-operation>
        <error-operation>error</error-operation>
        <(config | config-text | url)>
            <!-- configuration change file or data -->
        </(config | config-test | url)>
    </edit-config> 
</rpc>
]]>]]>

<rpc>
    <discard-changes/> 
</rpc>
]]>]]>

Notice that the three tags—<copy-config>, <edit-config>, and <discard-changes>—correspond to the three basic configuration tasks available to you:

• Overwriting the candidate configuration with a new configuration—Using the <copy-config> tag element, you can replace the current candidate configuration with a new configuration.
• Editing the candidate configuration elements—Using the <edit-config> tag element, you can add, change, or delete specific configuration elements within the candidate configuration.
• Rolling back changes to the current configuration—Using the <discard-changes> tag element, you can roll back the candidate configuration to a previously committed configuration. This tag element provides functionality analogous to the CLI command rollback.

Notice also that the <copy-config> and the <edit-config> tags both have additional subtags related to each tag element. These subtag elements are described in the following sections:

• Formatting the Configuration Data
• Setting the Edit Configuration Mode
• Handling Errors

Formatting the Configuration Data

A client application can use a text file or streaming data to deliver configuration data to the candidate configuration. The data delivered can be in one of two formats: Junos XML or CLI configuration statements. You can specify the delivery mechanism and the format used when delivering configuration changes to the device.

For more information on Junos XML tag elements, see XML Overview. For more information on CLI configuration statements, see the Junos CLI User Guide.

• Delivery Mechanism: Data Files Versus Streaming Data
• Data Format: Junos XML versus CLI Configuration Statements

Delivery Mechanism: Data Files Versus Streaming Data

When formatting your configuration data output, you can choose to stream your configuration changes within your session or reference data files that include the desired configuration changes. Each method has advantages and disadvantages. Streaming data allows you to send your configuration change data in line, using your NETCONF connection. This is useful when the device is behind a firewall and you cannot establish another connection to upload a data file. With text files you can keep the edit configuration commands simple; with data files, there is no need to include the possibly complex configuration data stream.

Referencing Configuration Data Files

To reference configuration data as a file, a client application emits the file location between <url> tag elements within the <rpc> and the <edit-config> tag elements.

<rpc>
    <edit-config>
        <target>
            <candidate/>
        </target>
        <url> 
            <!-- location and name of  file containing configuration data -->
        </url> 

    </edit-config>
</rpc>
]]>]]>

The data within these files can be formatted as either Junos XML or CLI configuration statements. When the configuration data is formatted as CLI configuration statements, you set the <url> format attribute to text.

<rpc>
    <edit-config>
        ...
      <url format=”text”>
        <!-- location and name of file containing configuration data -->
      </url>
    </edit-config>
</rpc>

The configuration file can be placed locally or as a network resource:

• When placed locally, the configuration file path can be relative or absolute:
  • Relative file path—The file location is based on the user’s home directory.
  • Absolute file path—The file location is based on the directory structure of the device, for example <drive>:filename or <drive>/:path/filename, If you are using removable media, the drive can be in the MS-DOS or UNIX (UFS) format.
• When located on the network, the configuration file can be accessed using FTP or HTTP:
  • FTP example:
    ftp://username:password@hostname/path/filename

    Note: The default value for the FTP path variable is the user’s home directory. Thus, by default the file path to the configuration file is relative to the user directory. To specify an absolute path when using FTP, start the path with the characters %2F; for example: ftp://username:password@hostname/%2Fpath/filename.

  • HTTP example:
    http://username:password@hostname/path/filename

Before loading the file, the client application or an administrator saves Junos XML tag elements as the contents of the file. The file includes the tag elements representing all levels of the configuration hierarchy from the root (represented by the <configuration> tag element) down to each element to change. The notation is the same as that used to request configuration information, as described in Requesting Information. For more detailed information about the Junos XML representation of Junos configuration statements, see Mapping Configuration Statements to Junos XML Tag Elements.

The following example shows how to incorporate configuration data stored in the file /var/tmp/configFile on the FTP server called ftp.myco.com:

Streaming Configuration Data

To provide configuration data as a data stream, a client application emits the <config> or <config-text> tag elements within the <rpc> and <edit-config> tag elements. To specify the configuration elements to change, the application emits Junos XML or CLI configuration statements representing all levels of the configuration hierarchy from the root (represented by the <configuration> or <configuration-text> tag element) down to each element to change. The Junos XML notation is the same as that used to request configuration information, as described in Requesting Information. For more detailed information about the mappings between Junos configuration elements and Junos XML tag elements, see Mapping Configuration Statements to Junos XML Tag Elements. The CLI configuration statement notation are further described in the CLI User Guide.

<rpc>
    <edit-config>
        <target>
            <candidate/>
        </target>
        <config> or <config-text> 
            <configuration> or <configuration-text>
                <!-- configuration changes --> 
            </configuration> or </configuration-text> 
        </config> or </config-text> 
    </edit-config>
</rpc>
]]>]]>

The following example shows how to provide Junos XML configuration data for the messages system log file in a data stream:

Data Format: Junos XML versus CLI Configuration Statements

You can format the configuration data using one of two formats: Junos XML or CLI configuration statements. The choice between one data format over the other is personal preference.

If you are supplying the configuration changes in the form of data files, you enclose the data filename and path within <url> tags. By default, these tags specify that the referenced data files are written in Junos XML. Thus, the following code declares that the data within the file is Junos XML:

<url>dataFile</url>

To specify that the data file be written as CLI configuration statements, you set the <url> tag's format attribute to text:

<url format=”text”>dataFile</url>

When streaming data, you specify the data format by selecting one of two tags: <config> for Junos XML statements and <config-text> for CLI configuration statements.

In the following example, Junos XML formatted configuration data is included between the <configuration> tag:

<config>
  <configuration>
    <system>
      <services>
        <ssh>
           <protocol-version>v2</protocol-version>
        </ssh>
      </services>
    </system>
  <configuration>
</config>

In this next example, the same data written formatted as CLI configuration statements and included within <configuration-text> tags:

<config-text>
  <configuration-text>
    system {
      services {
        ssh {
           protocol-version v2 ;
        }
      }
    }
  </configuration-text>
</config-text>

Setting the Edit Configuration Mode

<rpc>
  <edit-config>
    <default-operation>ConfigModeValue</default-operation>
  <edit-config>
</rpc>

<rpc>
  <edit-config>
    <config>
      <configuration>
        <protocols>
          <rip>
            <message-size operation=”replace”>255</message-size>
          </rip>
        </protocols>
      </configuration>
    </config>
  </edit-config>
</rpc>

<rpc>
  <edit-config>
    <default-operation>merge</default-operation>
    <config>
      <configuration>
        <protocols>
          <rip>
            <message-size operation=”replace”>255</message-size>
          </rip>
        </protocols>
      </configuration>
    </config>
  </edit-config>
</rpc>

Specifying the merge Data Mode

By default, the NETCONF server merges new configuration data into the candidate configuration. Thus, if no edit-configuration mode is specified, the device will merge the new configuration elements into the existing candidate configuration. Merging configurations is performed according to the following rules:

• A configuration element (hierarchy level or configuration object) that exists in the candidate configuration but not in the new configuration remains unchanged.
• A configuration element that exists in the new configuration but not in the candidate configuration is added to the candidate configuration.
• If a configuration element exists in both configurations, the following results occur:
  • If a child statement of the configuration element (represented by a child tag element) exists in the candidate configuration but not in the new configuration, it remains unchanged.
  • If a child statement exists in the new configuration but not in the candidate, it is added to the candidate configuration.
  • If a child statement exists in both configurations, the value in the new data replaces the value in the candidate configuration.

To explicitly specify that data be merged, the application can include the <default-operation> tag element with the value merge in the <edit-config> tag element:

<rpc>
    <edit-config>
        <default-operation>merge</default-operation> 
        <!-- other child tag elements of the <edit-config> tag element -->
    </edit-config>
</rpc>
]]>]]>

Specifying the replace Data Mode

In the replace edit configuration mode, the new configuration data completely replaces the candidate configuration. To specify that the data be replaced, the application can include the <default-operation> tag element with the value replace in the <edit-config> tag element:

<rpc>
    <edit-config>
        <default-operation>replace</default-operation> 
    </edit-config>
</rpc>
]]>]]>

We recommend using the global replace mode only when you plan to completely overwrite the candidate configuration with new configuration data. Furthermore, when the edit configuration mode is set to replace, we do not recommend using the operation attribute on individual configuration elements.

You can also replace individual configuration elements while merging or creating others. See Replacing Configuration Elements.

Specifying the no-change Data Mode

In the no-change mode, configuration changes to the configuration are ignored. This mode is useful when you are deleting elements, and it prevents the NETCONF server from creating parent hierarchy levels for an element that is being deleted. For more information, see Deleting Configuration Elements:

<rpc>
  <edit-config>
    <default-operation>none</default-operation>
  </edit-config>
</rpc>

Note: If the new configuration data includes a configuration element that does not exist in the candidate, the NETCONF server returns an error. We recommend using no-change mode only when removing configuration elements from the candidate configuration. When creating or modifying elements, applications need to use merge mode. For more information, see Deleting Configuration Elements.

<rpc>
  <edit-config>
    <default-operation>none</default-operation>
    <config>
      <configuration>
        <system>
          <services>
            <outbound-ssh>
              <client>
                <name>test</name>
                <device-id>test</device-id>
                <keep-alive>
                  <retry operation=”merge”>4</retry>
                  <timeout operation=”merge”>15</timeout>
                </keep-alive>
              </client>
            </outbound-ssh>
          </services>
        </system>
      </configuration>
    </config>
  </edit-config>
</rpc>

Handling Errors

If the NETCONF server cannot incorporate the configuration data, the <rpc-error> tag element is returned with information explaining the reason for the failure. By default, when the NETCONF server encounters an error while incorporating new configuration data into the candidate configuration, it halts the incorporation process. A client application can explicitly specify this response to errors by including the <error-option> tag element with the value stop-on-error in the <edit-config> tag element:

<rpc>
    <edit-config>
        <error-option>stop-on-error</error-option> 
        <!-- other child tag elements of the <edit-config> tag element -->
    </edit-config>
</rpc>
]]>]]>

Alternatively, the application can specify that the NETCONF server continue to incorporate new configuration data when it encounters an error. The application includes the <error-option> tag element with the value ignore-error in the <edit-config> tag element:

<rpc>
    <edit-config>
        <error-option>ignore-error</error-option> 
        <!-- other child tag elements of the <edit-config> tag element -->
    </edit-config>
</rpc>
]]>]]>

The client application can include the optional <test-option> tag element described in the NETCONF specification. Regardless of the value provided, the NETCONF server for the Junos OS performs a basic syntax check on the configuration data in the <edit-config> tag element. When the <test-option> tag is included, NETCONF performs a complete syntactic and semantic validation in response to the <commit> and <validate> tag elements (that is, when the configuration is committed or explicitly checked), but not in response to the <edit-config> tag element. For information about the <commit> and <validate> tag elements, see Committing Configurations.