Databases

A NETCONF database is conceptually represented as an XML instance document.

There are 3 conceptual databases, which all share the exact same structure.

• <candidate>: scratch-pad to gather edits to apply to <running> all at once

• <running>: configuration data in effect

• <startup>: configuration data for the next reboot

When the <running> configuration is saved to non-volatile storage, the top-level element of this document is the <config> container element.

The XML namespace of this element is the netconfd-pro module namespace, but a client application should expect that other server implementations may use a different namespace, such as the NETCONF namespace, or perhaps no namespace at all for this top-level element.

When database contents are returned in the <get>, <get-config>, or <copy-config> operations, the top-level container will be the <data> element in the NETCONF base namespace.

The top-level YANG module data structures that are present in the configuration will be present as child nodes of the <config> or <data> container node.

The exact databases that are present in the server are controlled by 3 capabilities:

• :candidate

• :writable-running

• :startup

The edit target in the server is set with the --target configuration parameter. This will select either the :candidate or :writable-running capabilities.

The server behavior for non-volatile storage of the <running> configuration is set with the --with-startup configuration parameter. The :startup capability will be supported if this parameter is set to 'true'.

The following diagram shows the 4 database usage modes that netconfd-pro supports:

Database Locking

It is strongly suggested that the <lock> and <unlock> operations be used whenever a database is being edited. All the databases on the server should be locked, not just one, because different operations are controlled by different locks. The only way to insure that the entire database transaction is done in isolation is to keep all the databases locked during the entire transaction.

The affected configurations should be locked during the entire transaction, and not released until the edits have been saved in non-volatile storage.

If the edit target is the <candidate> configuration, then the <candidate> and <running> configurations should be locked.

If the edit target is the <running> configuration, then the <running> and <startup> configurations should be locked.

Whenever the lock on the <candidate> configuration is released, a <discard-changes> operation is performed by the server. This is required by the NETCONF protocol.

Of the <candidate> configuration contains any edits, then a lock will fail with a 'resource-denied' error. In this case, a lock on the <candidate> configuration cannot be granted until the <discard-changes> operation is completed.

Using the <candidate> Database

The <candidate> database is available if the :candidate capability is advertised by the server.

The <lock> operation will fail on this database if there are any edits already pending in the <candidate>. If a 'lock-failed' error occurs and no session is holding a lock, then use the <discard-changes> operation to clear the <candidate> buffer of any edits.

Once all the edits have been made, the <validate> operation can be used to check if all database validation tests will pass. This step is optional.

Once the edits are completed, the <commit> operation is used to activate the configuration changes, and save them in non-volatile storage.

The <discard-changes> operation is used to clear any edits from this database.

Using the <running> Database

The <running> database is available at all times for reading.

If the :writable-running capability is advertised by the server, then this database will be available as the target for <edit-config> operations.

Edits to the <running> configuration will take affect right away, as each <edit-config> operation is completed.

Once all the edits are completed, the <copy-config> operation can be used to save the current <running> configuration to non-volatile storage, by setting the target of the <copy-config> operation to the <startup> configuration.

Using the <startup> Database

The <startup> database is available if the :startup capability is advertised by the server.

The <copy-config> operation can be used to save the contents of the <running> configuration to the <startup> configuration.

The <get-config> operation can be used to retrieve the contents of the <startup> configuration.

The <delete-config> operation can be used to delete the <startup> configuration. Only a superuser account is allowed to do this, by default.