Editing Configuration (NETCONF)

Using NETCONFc, editing data from the connected server is also very convenient.

Lock datastore for editing

It is recommended you lock the running and candidate datastore before editing anything. You can easily lock the involved datastore by clicking the correspondent lock button for each config datastore.

_images/lock_datastore.png

Partial-lock data nodes for editing

To allow other managers to edit server’s configuration store simultaneously you can use <partial-lock> to lock only the subtrees you want to edit. To issue partially-lock , first use <get-config> to retrieve some data, then in the data tree on the right panel, select one or more rows, right click and select Partial lock

_images/partial_lock.png

Note

Partial-lock is only effective when the target datastore is running.

Note

After a successful partial-lock, you can right-click to issue partial-unlock to unlock the locked subtrees.

Basic <edit-config> operations

Either from schema tree on the left side or data tree on the right, you can send <edit-config>. See Send <edit-config> command from schema tree and Send <edit-config> command from data tree for more information.

From data tree on the right, you can edit nodes in different list entries or different list.

Use shortcut key <Ctrl + S> to send <edit-config>.

Create multiple list or leaf-list instance entries in a single request

You can create or edit multiple list instance entries from YANG data schema tree.

The following is an example that shows how to create two list instance entries in a single RPC.

First, enter value ‘rule1’ and ‘group1’ as shown, then right click and select Add to build <edit-config> data.

_images/edit_multiple_list_entry1.png

You should see an edit-config RPC was generated in the Send Request and Show Reply window at the right side of the screen.

Then, enter value ‘rule2’ and ‘group2’ as shown, then right click and again and select Add to build <edit-config> data.

_images/edit_multiple_list_entry2.png

You should see new value entries are added to the previous edit-config RPC generated. If you want to make any changes you can edit it here.

Finally click the button Click to Send RPC with above XML at the bottom of Send Request and Show Reply window pane to send the edit-config message to the remote server.

To clear <edit-config> you have built, select “Reset all values” context menu or hit <Ctrl + Q>.

Deal with list key nodes

When issuing <edit-config> on a list, list keys must be included and placed before all other non-key nodes. NETCONFc handles this ciritical step for you automatically.

When sending <edit-config> from schema tree, all key nodes must be given an appropriate value.

Note

If a list is a nested list, the parent list’s key nodes must also be specified.

When sending <edit-config> from data tree, all key nodes will use their current respective value, unless otherwise changed.

How to create a presence container node

If a presence container contains any child node that is part of the edit-config then the server should create it automatically. Otherwise a presence container need to be created explicitly.

For example, in toaster yang module (http://www.netconfcentral.org/modulereport/toaster), the node /toaster/toaster is a presence container that has no child nodes. If this is the case, you should see a special Create this presence container menu in the right-click context menu. Just select it an <edit-config> will be sent to create this node.

_images/create_presence_container.png

Alternatively you can also right click to select Assign empty value to include in RPC, and then select Send edit-config to send the command.

Delete a node from data tree

It is really easy to Delete a node from the data tree. Just select it, right-click and choose Delete.

_images/delete_instance_node.png

Reorder ordered-by-user list of leaf-lists

In the schema tree and data tree you can also rearrange the order of list and leaf-list that are defined as ordered-by-user.

Select a list of leaf-list that is ordered by user, right click to select set <edit-config> options | Reorder options | ...

_images/reorder_node.png

If you select insert before or insert after reorder options, a dialog will pop up and asks you to select a target entry before or after which you want to move the selected node to.

_images/reorder_target_selection.png

You will then notice the node name is tagged with options you selected. Now you simply right lick and select edit-config to send it!

_images/edit_config_instance_tree.png

Edit-config operation attributes

For any config node, you can assign an operation attribute. If it is not assigned explicitly, it will use the setting in its parent nodes. If no parent node has this attribute set, then the setting in default-operation option will be used.

If you select any operation, then the selected node will be tagged with your selection.

If you select any default operation, the selected node will not be tagged with the selection since it a general setting.

If you want to remove a selected option, select do not user/clear.

_images/edit_config_option.png

The operation attribute has one of the following values:

merge: 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. This is the default behavior.

replace: 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.

create: 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.

delete: 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.

remove: 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.

The default-operation option parameter has one of the following values:

merge: The configuration data is merged with the configuration at the corresponding level in the target datastore. This is the default behavior.

replace: The configuration data completely replaces the configuration in the target datastore. This is useful for loading previously saved configuration data.

none: The target datastore is unaffected by the configuration data, unless and until the incoming configuration data uses the “operation” attribute to request a different operation. If the configuration data contains data for which there is not a corresponding level in the target datastore, an <rpc-error> is returned. Using “none” allows operations like “delete” to avoid unintentionally creating the parent hierarchy of the element to be deleted.

Edit-config with XML config data or URL

Sometimes you may want to edit a datastore with manually built XML data, or a resource pointed at by an URL, NETCONFc also allows you to do that.

First select a config datastore by enabling the corresponding radio button, click the dropdown arrow button and select edit-config with inline data or URL.

_images/edit_with_xml_url.png

The data to edit can be specfied either in a file given by its url or inline config data.

When using a config file, simply select “use a config file (url)” and specify an url value in the “Config url” field.

When using inline config data, select “use inline config data” and specify config data in the “Config Data” filed.

In either case, the config data must be a well formed XML <config> string. For example: :: <config> <top xmlns=”http://example.com/schema/1.2/config”> <interface> <name>Ethernet0/0</name> <mtu>1500</mtu> </interface> </top> </config>

Additional edit-config options

You can assign the following additional options to <edit-config> by right-clicking and select “edit-config options | test-option or error-option”.

The <test-option> element is available only if the device advertises the :validate:1.1 capability. The <test-option> element has one of the following values:

test-then-set: Perform a validation test before attempting to set. If validation errors occur, do not perform the <edit-config> operation. This is the default test-option.

set: Perform a set without a validation test first.

test-only: Perform only the validation test, without attempting to set.

The <error-option> has one of the following values:

stop (stop-on-error): Abort the <edit-config> operation on first error. This is the default error-option.

continue (continue-on-error): Continue to process configuration data on error; error is recorded, and negative response is generated if any errors occur.

rollback (rollback-on-error): If an error condition occurs such that an error severity <rpc-error> element is generated, the server will stop processing the <edit-config> operation and restore the specified configuration to its complete state at the start of this <edit-config> operation. This option requires the server to support the :rollback-on-error capability.

Edit-config With-defaults attribute

An edit-config RPC can have a ‘default’ attribute.

If the server supports the ‘report-all-tagged’ mode, then the ‘default’ attribute defined in RFC6243 section 6 also impacts the <edit-config> operation. If the ‘default’ attribute is present and set to ‘true’, then the server MUST treat the new data node as a request to return that node to its default value (i.e., remove it from the configuration datastore). The data node within the NETCONF message MUST contain a value in this case, which MUST be equal to the schema default value.

If the ‘default’ attribute is present, then the effective operation for the target data node MUST be ‘create’, ‘merge’, or ‘replace’.

If you want to enable this attribute, use edit-config options | default-attribute as shown below:

_images/xml_default_attribute.png

Here is the corresponding XML snippet:

<cfgnetopeer:enabled xmlns:wd="urn:ietf:params:xml:ns:netconf:default:1.0" wd:default="true">false</cfgnetopeer:enabled>

Commit changes into running datastore

After making changes to candidate datastore, we must commit the changes into running datastore, otherwise the changes will not make effect to the device.

If the selected target datastore is running then you are editing it directly so nothing needs to be committed!

If the selected target datastore is candidate then you need to commit the changes you made to the candidate config datastore to the running config datastore.

  • To commit the changes made to candidate datastore into the running datastore, click the down-arrow button to the right of the candidate radio button, and select commit.

    _images/commit.png
  • To discard changes made to the candidate datastore and set it to the same as the current running, click the down-arrow button to the right of the candidate radio button, and select discard-changes and revert to the current running.

    _images/discard.png

Alternatively you can use <confirmed-commit> if the server supports it.

A confirmed-commit needs two separate commits. The second commit must be received by the server within the specified timeout period. Otherwise the commit process will be abandoned and the config will be reverted to the state before the first commit was issued.

Copy changes to startup datastore to keep it across reboot

If the server supports startup datastore, then after you make any changes, the current running config must be copied to startup so the changes can retain across reboot. Otherwise the changes won’t go back to the state before your editing.

If the server does not support startup datastore then the changes made to running datastore will be automatically retained and kept across reboot.

Normally we don’t edit the startup datastore directly, even if the remote server advertises the support for it.

There are two important operations we must know for startup datastore.

*If we find we are satisfied with the current running config store configuration, the we must copy the current running config to startup config datasrtore so it can be retained across reboot. To do that, click the down-arrow button to the right of the startup radio button, and select Save running as startup config.

_images/save_startup.png

*In case we messed up totally we want to revert to factory setting on next reboot, you can click the down-arrow button to the right of the startup radio button, and select Reset to factory settings (delete-config).

_images/reset_factory.png