Setting the Edit Configuration Mode in a NETCONF Session
When sending operation data to the NETCONF server, you can specify how a device should handle these configuration changes. This is known as the edit configuration mode. You can set the edit configuration mode globally for the entire session. You can also set the edit mode only for specific elements within the session.
The device has the following edit configuration modes:
- merge—The device merges new configuration data into the current candidate configuration. This is the default.
- replace—The device replaces existing configuration data with the new configuration data.
- no-change—The device does not change the existing configuration unless the new configuration element includes an operation attribute.
To set the mode globally for the session, place a configuration mode value within <default-operation> tags:
<rpc>
<edit-config>
<default-operation>mode</default-operation>
<edit-config>
</rpc>You can also set the mode for a specific configuration statement by adding an operation attribute with a value of replace to the configuration element:
<rpc>
<edit-config>
<config>
<configuration>
<protocols>
<rip>
<message-size operation=”replace”>255</message-size>
</rip>
</protocols>
</configuration>
</config>
</edit-config>
</rpc>You can set a global edit configuration mode for an entire set of configuration changes and specify a different mode for individual elements that you want handled in a different manner. For example:
<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>The edit configuration modes are discussed in more detail in the following sections:
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 Using NETCONF.
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 Using NETCONF.
To set the no-change edit configuration mode globally, the application can include the <default-operation> tag element with the value none in the <edit-config> tag element:
<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. |
When the no-change edit configuration mode is set globally, using the <default-operation> tag, you can override this behavior by specifying a different edit configuration mode for a specific element using the operation attribute. For example:
<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>
