Example: Configure the Ephemeral Configuration Database Using NETCONF
The ephemeral database is an alternate configuration database that enables client applications to simultaneously load and commit configuration changes on Junos devices and with significantly greater throughput than when committing data to the candidate configuration database. This example shows how to enable an instance of the ephemeral configuration database and make updates to that instance in a NETCONF session.
Requirements
This example uses the following software components:
-
A device running Junos OS or a device running Junos OS Evolved that supports configuring the ephemeral database.
Before you begin:
Enable the NETCONF-over-SSH service on the Junos device.
Overview
Multiple NETCONF and Junos XML protocol client applications can simultaneously load and commit
configuration changes to a Junos device by using ephemeral database instances. This
example enables the ephemeral database instance eph1 and then
configures the instance through a NETCONF session.
A client application must open an instance of the ephemeral configuration database in order to
view or modify it. After establishing a NETCONF session, the client opens the
ephemeral instance by using the Junos XML protocol
<open-configuration> operation. The element encloses the
<ephemeral-instance> child tag and the name of the
instance. Opening the ephemeral instance automatically acquires an exclusive lock on
it.
The client then loads configuration data in text format into the eph1 ephemeral
instance. Because the configuration data is in text format, the
<load-configuration> operation must include the
format="text" attribute, and a
<configuration-text> element must enclose the
configuration data.
The client application commits the configuration changes in the ephemeral instance by emitting
the Junos XML protocol <commit-configuration> operation. The
<load-configuration>
action="merge" attribute only determines how the the device merges
configuration data into that instance of the ephemeral database. After you commit
the changes to the ephemeral instance, the device merges the configuration data into
the active configuration according to the rules of prioritization. If the different
configuration databases have conflicting data, statements in the
eph1 instance have a higher priority than statements in the
default ephemeral instance or the static configuration database. If other
user-defined ephemeral instances are in use, the priority is determined by the order
in which the instances are listed in the configuration at the [edit system
configuration-database ephemeral] hierarchy level.
The <close-configuration/> operation closes the open ephemeral instance
and releases the exclusive lock. The device retains the committed ephemeral data
until the device is rebooted or the data is deleted. If you reboot the device, the
system deletes the configuration data in the eph1 ephemeral
instance as well as the data in all other ephemeral instances.
Configuration
Enable the Ephemeral Database Instance
Step-by-Step Procedure
To enable the ephemeral database instance:
Configure the name of the instance.
[edit] user@host# set system configuration-database ephemeral instance eph1
Commit the configuration.
[edit] user@host# commit
Results
From configuration mode, confirm your configuration
by entering the show system configuration-database command.
If the output does not display the intended configuration, repeat
the instructions in this example to correct the configuration.
[edit]
user@host# show system configuration-database
ephemeral {
instance eph1;
}
Configure the Ephemeral Database Instance
Step-by-Step Procedure
To configure the ephemeral database instance and commit the changes from within a NETCONF session, a client application performs the following steps:
Opens the ephemeral database instance.
<rpc> <open-configuration> <ephemeral-instance>eph1</ephemeral-instance> </open-configuration> </rpc> ]]>]]>Loads the configuration data into the open ephemeral instance, and includes the appropriate tags and attributes for that data.
<rpc> <load-configuration action="merge" format="text"> <configuration-text> protocols { mpls { label-switched-path to-hastings { to 192.0.2.1; } } } </configuration-text> </load-configuration> </rpc> ]]>]]>The NETCONF server indicates a successful
<load-configuration>operation by returning an empty<ok/>tag enclosed within the<load-configuration-results>and<rpc-reply>elements.Commits the configuration, provided the
<load-configuration>operation does not generate any errors.<rpc> <commit-configuration/> </rpc> ]]>]]>Closes the ephemeral database instance.
<rpc> <close-configuration/> </rpc> ]]>]]>
Results
If there are no errors when opening or closing the
database, the NETCONF server returns an empty <rpc-reply> element in response to the requests. The NETCONF server indicates
a successful <load-configuration> operation
by returning an empty <ok/> tag enclosed
within the <load-configuration-results> and <rpc-reply> elements. Similarly,
the NETCONF server indicates a successful <commit-configuration> operation by returning an empty <ok/> tag enclosed in an <rpc-reply> element.
Verification
Verify the Commit
Purpose
The NETCONF server’s response to the commit operation should indicate the success or failure of the commit. You can also verify the success of the commit by reviewing the commit events for the ephemeral database in the system log file.
Action
Review the system log file and display events that match UI_EPHEMERAL.
user@host> show log messages | match UI_EPHEMERAL Feb 10 13:20:32 host mgd[5172]: UI_EPHEMERAL_COMMIT: User 'user' has requested commit on 'eph1' ephemeral database Feb 10 13:20:32 host mgd[5172]: UI_EPHEMERAL_COMMIT_COMPLETED: commit complete on 'eph1' ephemeral database
Meaning
The UI_EPHEMERAL_COMMIT_COMPLETED message tag indicates that the commit operation on the eph1 instance was successful.
Verify the Configuration Data in the Ephemeral Database Instance
Purpose
Verify that the ephemeral instance has the correct configuration data.
Action
Within the NETCONF session, open the ephemeral database instance and retrieve the configuration.
<rpc>
<open-configuration>
<ephemeral-instance>eph1</ephemeral-instance>
</open-configuration>
</rpc>
]]>]]>
<rpc>
<get-configuration format="text"/>
</rpc>
]]>]]>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/25.2R1.9/junos">
<configuration-text xmlns="http://xml.juniper.net/xnm/1.1/xnm">
## Last changed: 2025-10-10 18:46:38 PDT
protocols {
mpls {
label-switched-path to-hastings {
to 192.0.2.1;
}
}
}
</configuration-text>
</rpc-reply>
]]>]]><rpc>
<close-configuration/>
</rpc>
]]>]]>
You can view the configuration data committed to an ephemeral database instance from the CLI by
issuing the show ephemeral-configuration instance
instance-name operational
command.
Troubleshooting
Troubleshoot Issues When Opening the Ephemeral Instance
Problem
You attempt to open an instance of the ephemeral database,
and the server returns only an opening <rpc-reply> tag. For example:
<rpc>
<open-configuration>
<ephemeral-instance>eph1</ephemeral-instance>
</open-configuration>
</rpc>
]]>]]>
<rpc-reply xmlns="urn:ietf:params:xml:ns:netconf:base:1.0" xmlns:junos="http://xml.juniper.net/junos/16.2R2/junos">
This issue can occur when another client has the exclusive lock on that instance.
Solution
If another user has an exclusive lock on the ephemeral instance, a client application can issue
remote procedure calls (RPCs) to update the ephemeral instance. However, the
device does not process the operations on that ephemeral instance until the
lock is released. When the lock is released, the server should issue the
closing </rpc-reply> tag and process any RPCs emitted
while the ephemeral instance was locked.
Alternatively, a client application can choose to update a different ephemeral instance, but with the caveat that different ephemeral instances have different priority levels when resolving conflicting configuration statements.
Troubleshoot Operational Issues
Problem
The device does not execute operational changes that should occur as a result of committing certain configuration data to the ephemeral database instance. This occurs even though you have verified that the commit was successful and that the configuration data is present in the configuration for that ephemeral instance.
The operational changes might not occur if the device has another user-defined ephemeral instance that has conflicting configuration data and a higher priority. If the ephemeral instances have conflicting data, statements in an instance with a higher priority override statements in an instance with a lower priority. A user-defined instance of the ephemeral configuration database has higher priority than the default ephemeral database instance, which has higher priority than the static configuration database. If the device has multiple user-defined ephemeral instances in use, the priority is determined by the order in which the instances are listed in the configuration.
Solution
You can verify the configured ephemeral instances and their priority order by issuing the
show configuration system configuration-database
ephemeral operational command on the device. The
configuration lists the instances in order from highest to lowest priority.
If the device has other instances in use with a higher priority, review the
configuration data in those instances to determine if there are conflicting
statements. You can also display the merged view of the static and ephemeral
configuration databases by issuing the show ephemeral-configuration
merge
command.
If your ephemeral instance has conflicting configuration data and a lower priority than another user-defined ephemeral instance, and the configuration at that hierarchy level should go into effect on the device, you must either delete the conflicting data in the other ephemeral instance or place your configuration data in a higher priority instance.