Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Locking and Unlocking the Candidate Configuration or Creating a Private Copy Using the Junos XML Protocol

 

When a client application is requesting or changing configuration information, it can use one of the following methods to access the candidate configuration:

  • Lock the candidate configuration, which prevents other users or applications from changing the shared configuration database until the application releases the lock (equivalent to the CLI configure exclusive command).

  • Create a private copy of the candidate configuration, which enables the application to view or change configuration data without affecting the candidate or active configuration until the private copy is committed (equivalent to the CLI configure private command).

  • Change the candidate configuration without locking it. We do not recommend this method, because of the potential for conflicts with changes made by other applications or users that are editing the shared configuration database at the same time.

If an application is simply requesting configuration information and not changing it, locking the configuration or creating a private copy is not required. The application can begin requesting information immediately. However, if it is important that the information being returned not change during the session, it is appropriate to lock the configuration. The information from a private copy is guaranteed not to change, but can diverge from the candidate configuration if other users or applications are changing the candidate configuration.

The restrictions on, and interactions between, operations on the locked regular candidate configuration and a private copy are the same as for the CLI configure exclusive and configure private commands. For more information, see Committing a Private Copy of the Configuration Using the Junos XML Protocol and the CLI User Guide.

For more information about locking and unlocking the candidate configuration or creating a private copy, see the following sections:

Locking the Candidate Configuration

To lock the candidate configuration, a client application emits the <lock-configuration/> tag within an <rpc> tag.

Locking the candidate configuration prevents other users or applications from changing the candidate configuration until the lock is released. This is equivalent to the CLI configure exclusive command. Locking the configuration before making changes is recommended, particularly on devices where multiple users are authorized to change the configuration. A commit operation applies to all changes in the candidate configuration, not just those made by the user or application that requests the commit. Allowing multiple users or applications to make changes simultaneously can lead to unexpected results.

The Junos XML protocol confirms that it has locked the candidate configuration by returning an opening <rpc-reply> and closing </rpc-reply> tag with nothing between them.

If the Junos XML protocol server cannot lock the configuration, the <rpc-reply> tag instead encloses an <xnm:error> element explaining the reason for the failure. Reasons for the failure can include the following:

Only one application can hold the lock on the candidate configuration at a time. Other users and applications can read the candidate configuration while it is locked, or can change their private copies. The lock persists until either the Junos XML protocol session ends or the client application unlocks the configuration by emitting the <unlock-configuration/> tag, as described in Locking and Unlocking the Candidate Configuration or Creating a Private Copy Using the Junos XML Protocol.

If the candidate configuration is not committed before the client application unlocks it, or if the Junos XML protocol session ends for any reason before the changes are committed, the changes are automatically discarded. The candidate and committed configurations remain unchanged.

Unlocking the Candidate Configuration

As long as a client application holds a lock on the candidate configuration, other applications and users cannot change the candidate. To unlock the candidate configuration, the client application includes the <unlock-configuration/> tag in an <rpc> tag:

The Junos XML protocol server confirms that it has successfully unlocked the configuration by returning an opening <rpc-reply> and closing </rpc-reply> tag with nothing between them.

If the Junos XML protocol server cannot unlock the configuration, the <rpc-reply> tag instead encloses an <xnm:error> element explaining the reason for the failure.

Creating a Private Copy of the Configuration

To create a private copy of the candidate configuration, a client application emits the <private/> tag enclosed in <rpc> and <open-configuration> tags.

The client application can then perform the same operations on the private copy as on the regular candidate configuration.

After making changes to the private copy, the client application can commit the changes to the active configuration on the device running Junos OS by emitting the <commit-configuration> tag element, as for the regular candidate configuration. However, there are some restrictions on the commit operation for a private copy. For more information, see Committing a Private Copy of the Configuration Using the Junos XML Protocol.

To discard the private copy without committing it, a client application emits the <close-configuration/> tag enclosed in an <rpc> tag element.

Any changes to the private copy are lost. Changes to the private copy are also lost if the Junos XML protocol session ends for any reason before the changes are committed. It is not possible to save changes to a private copy other than by emitting the <commit-configuration> tag element.

Note

Starting in Junos OS Release 18.2R1, the Junos XML protocol <open-configuration> operation does not emit an "uncommitted changes will be discarded on exit" warning message when opening a private copy of the candidate configuration. However, Junos OS still discards the uncommitted changes upon closing the private copy.

The following example shows how to create a private copy of the configuration. The Junos XML protocol server includes a reminder in its confirmation response that changes are discarded from a private copy if they are not committed before the session ends.

Release History Table
Release
Description
Starting in Junos OS Release 18.2R1, the Junos XML protocol <open-configuration> operation does not emit an "uncommitted changes will be discarded on exit" warning message when opening a private copy of the candidate configuration.