Lock and Unlock the Candidate Configuration Using NETCONF
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. This is equivalent to the CLI
configure exclusivecommand.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 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.
For more information about locking and unlocking the candidate configuration, see the following sections:
Locking the Candidate Configuration
To lock the candidate configuration, a client application emits
the <lock> and <target> tag elements and the <candidate/> tag
in the <rpc> tag element.
<rpc>
<lock>
<target>
<candidate/>
</target>
</lock>
</rpc>
]]>]]>
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 NETCONF server confirms that it has locked the candidate
by returning the <ok/> tag in the <rpc-reply> tag element.
<rpc-reply xmlns="URN" xmlns:junos="URL">
<ok/>
</rpc-reply>
]]>]]>
If the NETCONF server cannot lock the configuration, the <rpc-reply> tag element instead encloses an <rpc-error> tag element explaining the reason for
the failure. Reasons for the failure can include the following:
Another user or application has already locked the candidate configuration. The error message reports the NETCONF session identifier of the user or application. If the client application has the necessary Junos OS access privilege, it can terminate the session that holds the lock. For more information, see Terminate a NETCONF Session.
The candidate configuration already includes changes that have not yet been committed. To commit the changes, see Commit the Candidate Configuration Using NETCONF. To discard uncommitted changes, see Roll Back Uncommitted Changes in the Candidate Configuration Using NETCONF.
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. The lock persists until either the NETCONF session
ends or the client application unlocks the configuration by emitting
the <unlock> tag element, as described
in Unlocking the Candidate Configuration.
If the candidate configuration is not committed before the client application unlocks it, or if the NETCONF 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> and <target> tag elements and the <candidate/> tag
in an <rpc> tag element.
<rpc>
<unlock>
<target>
<candidate/>
</target>
</unlock>
</rpc>
]]>]]>
The NETCONF server confirms that it has unlocked the
candidate by returning the <ok/> tag
in the <rpc-reply> tag element.
<rpc-reply xmlns="URN" xmlns:junos="URL">
<ok/>
</rpc-reply>
]]>]]>
If the NETCONF server cannot unlock the configuration, the <rpc-reply> tag element instead encloses an <rpc-error> tag element explaining the reason for
the failure.