- play_arrow Overview
- play_arrow Junos XML Management Protocol and Junos XML API Overview
- play_arrow Junos XML Protocol and Junos XML Tags Overview
- XML and Junos OS Overview
- XML Overview
- XML and Junos XML Management Protocol Conventions Overview
- Map Junos OS Commands and Command Output to Junos XML Tag Elements
- Map Configuration Statements to Junos XML Tag Elements
- Using Configuration Response Tag Elements in Junos XML Protocol Requests and Configuration Changes
- play_arrow Junos XML Protocol and JSON Overview
-
- play_arrow Manage Configurations Using the Junos XML Protocol
- play_arrow Change the Configuration Using the Junos XML Protocol
- Request Configuration Changes Using the Junos XML Protocol
- Upload and Format Configuration Data in a Junos XML Protocol Session
- Upload Configuration Data as a File Using the Junos XML Protocol
- Upload Configuration Data as a Data Stream Using the Junos XML Protocol
- Define the Format of Configuration Data to Upload in a Junos XML Protocol Session
- Specify the Scope of Configuration Data to Upload in a Junos XML Protocol Session
- Replace the Configuration Using the Junos XML Protocol
- Create, Modify, or Delete Configuration Elements Using the Junos XML Protocol
- Create New Elements in Configuration Data Using the Junos XML Protocol
- Merge Elements in Configuration Data Using the Junos XML Protocol
- Replace Elements in Configuration Data Using the Junos XML Protocol
- Replace Only Updated Elements in Configuration Data Using the Junos XML Protocol
- Delete Elements in Configuration Data Using the Junos XML Protocol
- Rename Objects In Configuration Data Using the Junos XML Protocol
- Reorder Elements In Configuration Data Using the Junos XML Protocol
- Protect or Unprotect a Configuration Object Using the Junos XML Protocol
- Change a Configuration Element’s Activation State Using the Junos XML Protocol
- Change a Configuration Element’s Activation State Simultaneously with Other Changes Using the Junos XML Protocol
- Replace Patterns in Configuration Data Using the NETCONF or Junos XML Protocol
- play_arrow Commit the Configuration on a Device Using the Junos XML Protocol
- Verify Configuration Syntax Using the Junos XML Protocol
- Commit the Candidate Configuration Using the Junos XML Protocol
- Commit a Private Copy of the Configuration Using the Junos XML Protocol
- Commit a Configuration at a Specified Time Using the Junos XML Protocol
- Commit the Candidate Configuration Only After Confirmation Using the Junos XML Protocol
- Commit and Synchronize a Configuration on Redundant Control Planes Using the Junos XML Protocol
- Log a Message About a Commit Operation Using the Junos XML Protocol
- View the Configuration Revision Identifier for Determining Synchronization Status of Devices with NMS
- play_arrow Ephemeral Configuration Database
- Understanding the Ephemeral Configuration Database
- Unsupported Configuration Statements in the Ephemeral Configuration Database
- Enable and Configure Instances of the Ephemeral Configuration Database
- Commit and Synchronize Ephemeral Configuration Data Using the NETCONF or Junos XML Protocol
- Managing Ephemeral Configuration Database Space
-
- play_arrow Request Operational and Configuration Information Using the Junos XML Protocol
- play_arrow Request Operational Information Using the Junos XML Protocol
- play_arrow Request Configuration Information Using the Junos XML Protocol
- Request Configuration Data Using the Junos XML Protocol
- Specify the Source for Configuration Information Requests in a Junos XML Protocol Session
- Specify the Output Format for Configuration Data in a Junos XML Protocol Session
- Request Commit-Script-Style XML Configuration Data Using the Junos XML Protocol
- Specify the Output Format for Configuration Groups and Interface Ranges Using the Junos XML Protocol
- Request Identifier Indicators for Configuration Elements Using the Junos XML Protocol
- Request Change Indicators for Configuration Elements Using the Junos XML Protocol
- Specify the Scope of Configuration Data to Return in a Junos XML Protocol Session
- Request the Complete Configuration Using the Junos XML Protocol
- Request a Configuration Hierarchy Level or Container Object Without an Identifier Using the Junos XML Protocol
- Request All Configuration Objects of a Specific Type Using the Junos XML Protocol
- Request a Specific Number of Configuration Objects Using the Junos XML Protocol
- Request Identifiers for Configuration Objects of a Specific Type Using the Junos XML Protocol
- Request a Single Configuration Object Using the Junos XML Protocol
- Request Subsets of Configuration Objects Using Regular Expressions
- Request Multiple Configuration Elements Using the Junos XML Protocol
- Retrieve a Previous (Rollback) Configuration Using the Junos XML Protocol
- Retrieve the Rescue Configuration Using the Junos XML Protocol
- Compare the Active or Candidate Configuration to a Prior Version Using the Junos XML Protocol
- Compare Two Previous (Rollback) Configurations Using the Junos XML Protocol
- Request an XML Schema for the Configuration Hierarchy Using the Junos XML Protocol
-
- play_arrow Junos XML Protocol Utilities
- play_arrow Develop Junos XML Protocol C Client Applications
-
- play_arrow Configuration Statements and Operational Commands
Lock, Unlock, or Create a Private Copy of the Candidate Configuration 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.
<rpc> <lock-configuration/> </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 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.
<rpc-reply xmlns:junos="URL"> </rpc-reply>
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:
Another user or application has already locked the candidate configuration. The error message reports the login identity of the user or application.
The candidate configuration already includes changes that have not yet been committed. To commit the changes, see Committing the Candidate Configuration Using the Junos XML Protocol. To discard uncommitted changes, see Replacing the Configuration Using the Junos XML Protocol.
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:
<rpc> <unlock-configuration/> </rpc>
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.
<rpc-reply xmlns:junos="URL"> </rpc-reply>
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.
<rpc> <open-configuration> <private/> </open-configuration> </rpc>
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.
<rpc> <close-configuration/> </rpc>
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.
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.

Change History Table
Feature support is determined by the platform and release you are using. Use Feature Explorer to determine if a feature is supported on your platform.
<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.