Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

Example: Configuring 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 devices running Junos OS 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:

  • MX Series router running Junos OS Release 16.2R2 or a later release.

Before you begin:

  • Enable the NETCONF-over-SSH service on the device running Junos OS.

Overview

Multiple NETCONF and Junos XML protocol client applications can simultaneously load and commit configuration changes to a device running Junos OS by using ephemeral database instances. This example enables the ephemeral database instance eph1 on a device running Junos OS 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, Junos OS 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

Enabling the Ephemeral Database Instance

Step-by-Step Procedure

To enable the ephemeral database instance on the device running Junos OS:

  1. Configure the name of the instance.
  2. Commit the configuration.

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.

Configuring 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:

  1. Open the ephemeral database instance.
  2. Load the configuration data into the open ephemeral instance, and include the appropriate tags and attributes for that data.
  3. If the <load-configuration> operation does not generate any errors, commit the configuration.
  4. Close the ephemeral database instance.

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

Verifying 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

Meaning

The UI_EPHEMERAL_COMMIT_COMPLETED message tag indicates that the commit operation on the eph1 instance was successful.

Verifying 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.

Tip

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

Troubleshooting 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:

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.

Troubleshooting Operational Issues

Problem

The device running Junos OS 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 those 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.