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 that supports configuring the ephemeral database and is running Junos OS Release 16.2R2 or later or Junos OS Evolved Release 22.1R1 or later.
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, which 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 the configuration data must be enclosed in the <configuration-text> element.
This examples 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 configuration data
is merged 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 there is conflicting data
in the different configuration databases, statements in the eph1
instance have a higher priority than those in the default ephemeral instance or the
static configuration database. If there are other user-defined ephemeral instances,
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 committed ephemeral data is retained until the device is rebooted,
at which time the device 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, client applications perform the following steps:
Open the ephemeral database instance.
<rpc> <open-configuration> <ephemeral-instance>eph1</ephemeral-instance> </open-configuration> </rpc> ]]>]]>Load the configuration data into the open ephemeral instance, and include 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> ]]>]]>If the
<load-configuration>operation does not generate any errors, commit the configuration.<rpc> <commit-configuration/> </rpc> ]]>]]>Close 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 correct configuration data has been added to the ephemeral instance.
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/16.2R2/junos">
<configuration-text xmlns="http://xml.juniper.net/xnm/1.1/xnm">
## Last changed: 2017-02-10 13:20:32 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
in Junos OS Release 18.2R1 and later releases or by issuing the show ephemeral-configuration instance-name operational command in earlier releases.
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, but the operations on that ephemeral
instance are not processed 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, 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 there is another user-defined ephemeral instance that has conflicting configuration data and a higher priority. If there is conflicting data in the ephemeral instances, 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 there are multiple user-defined ephemeral instances, 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. Instances are listed in order from highest
to lowest priority. If there are other instances that have 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 in Junos
OS Release 18.2R1 and later releases or by issuing the show ephemeral-configuration
| display merge command in earlier releases.
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.