Help us improve your experience.

Let us know what you think.

Do you have time for a two-minute survey?

 
 

Using the NETCONF Java Toolkit to Perform Configuration Tasks

Using Device Object Methods to Load Configuration Changes

The NETCONF Java toolkit Device object has methods to help you configure remote devices. When appropriate, the methods are overloaded to take a number of different formats.

To load configuration data on a remote device, the Device object has several methods that enable you to define the configuration data as a set of Junos OS configuration mode commands, formatted ASCII text, or Junos XML tag elements. You can supply the configuration data in the program code, or you can reference data files that include the desired configuration changes.

To configure a private copy of the candidate configuration, call the openConfiguration("private") method with the string argument "private" on the device object before loading your configuration changes. This is equivalent to the configure private command in the Junos OS CLI. If you omit the call to the openConfiguration("private") method, your configuration changes are loaded into the global copy of the candidate configuration.

The method used to load the configuration data depends on the source and the format of the data. In the following methods, the string argument loadType has a value of either merge or replace, which performs the equivalent of the configuration mode commands load merge or load replace on a device running Junos OS.

  • Junos OS configuration mode commands—The following methods load configuration data as a set of Junos OS configuration mode commands. These methods are only supported on devices running Junos OS Release 11.4 or a later release. Junos OS executes the configuration instructions line by line. For each element, you can specify the complete statement path in the command, or you can use navigation commands, such as edit, to move around the configuration hierarchy as you do in CLI configuration mode.

    • loadSetConfiguration(String setCommands)—Specify the configuration data in the program code, either as a method argument or as a variable passed to the method.

    • loadSetFile(String filePath)—Load the configuration data from the file specified by filePath.

  • Formatted ASCII text—The following methods load configuration data as formatted ASCII text. Use the standard Junos OS CLI notations—the newline character, tabs, spaces, braces, and square brackets—to indicate the hierarchical relationships between configuration statements.

    • loadTextConfiguration(String textConfiguration, String loadType)—Specify the configuration data in the program code, either as a method argument or as a variable passed to the method.

    • loadTextFile(String filePath, String loadType)—Load the configuration data from the file specified by filePath.

  • Junos XML tag elements—The following methods load configuration data as Junos XML tag elements. Include the tag elements representing all levels of the configuration hierarchy under the root, the <configuration> tag element, down to each new or changed element.

    • loadXMLConfiguration(String XMLConfiguration, String loadType)—Specify the configuration data in the program code as a net.juniper.netconf.XML object, which is passed to the method.

    • loadXMLFile(String filePath, String loadType)—Load the configuration data from the file specified by filePath.

The following code snippet merges the ftp statement into the candidate configuration at the [edit system services] hierarchy level. The Java statement for each type of load configuration method is shown. When loading from a file, the file should contain the appropriate hierarchy in the desired format.

Example: NETCONF Java Application for Loading and Committing a Configuration

The following example NETCONF Java toolkit program constructs a configuration hierarchy, which is then merged with the candidate configuration on the specified device. The resulting configuration is then committed. The sample configuration hierarchy is for a device running Junos OS.

Requirements

  • Routing, switching, or security device running Junos OS.

  • NETCONF Java toolkit is installed on the configuration management server.

  • Client application can log in to the device where the NETCONF server resides.

  • NETCONF service over SSH is enabled on the device where the NETCONF server resides.

Overview

The following example performs a load merge operation to update the candidate configuration on a device running Junos OS and then commits the new configuration. The XML hierarchy that will be added into the configuration is constructed with the XMLBuilder object and stored in the ftp_config variable. Alternatively, you can load configuration data as text and, for devices running Junos OS Release 11.4 or a later release, as a set of Junos OS configuration mode commands.

The new configuration hierarchy, which enables FTP service on the device, is:

The program code creates a new Device object and calls the connect() method. This establishes an SSHv2 connection and a default NETCONF session with the device on which the NETCONF server runs.

To prevent conflicts with other users who might simultaneously edit the candidate configuration, the code calls the lockConfig() method on the device object to lock the configuration. If the lock fails, the method generates an error message, and the program exits. If the lock is successful, the loadXMLConfiguration(ftp_config.toString(), "merge") method loads the new configuration hierarchy into the candidate configuration using the merge option. Notice that, although the configuration hierarchy is initially constructed as XML, you must convert it to a string before passing it as an argument to the loadXMLConfiguration() method.

Once the new configuration hierarchy is merged with the candidate configuration, the program attempts to commit the configuration. If the commit operation is unsuccessful, the program prints the associated error message. The program then unlocks the configuration and closes the NETCONF session and device connection.

Note:

For more information about the merge and replace options for loading configuration hierarchies and statements into the candidate configuration, see the CLI User Guide.

Configuration

Creating the Java Program

Step-by-Step Procedure

To construct the Java program file that contains the code for the configuration changes and requests:

  1. Give the file a descriptive name.

    The filename must be the same as the class name. For this example, the file and class are named EditConfig.

  2. Add the code to the file and update the environment-specific variables such as the remote host IP address, username, and password.

    The complete Java code for the EditConfig program is presented here.

Compiling and Running the Java Program

Step-by-Step Procedure

You need a Java compiler to compile the source code and to create an executable program.

To compile the code and run the program on the configuration management server:

  1. Compile the EditConfig.java file.

  2. Execute the EditConfig program.

Verification

Verifying Program Execution

Purpose

Verify that the EditConfig program runs correctly.

Action

If the program executes successfully, it establishes a connection and a creates a NETCONF session with the specified device. The program merges the new hierarchy with the candidate configuration on the device and commits the configuration.

You can verify that the configuration was correctly merged and committed by viewing the resulting configuration on the remote device. The ftp statement should now be in the active configuration. On a device running Junos OS, enter the following operational mode command to view the [edit system services] hierarchy:

Troubleshooting

Troubleshooting Error Messages

Problem

The following error message is printed to the display:

Solution

Another user currently has a lock on the candidate configuration. Wait until the lock is released and execute the program.

Example: NETCONF Java Application for Loading Set Configuration Commands

This NETCONF Java toolkit program demonstrates the loadSetConfiguration() method, which updates the configuration using a set of Junos OS configuration mode commands.

Requirements

  • Routing, switching, or security device running Junos OS Release 11.4 or later.

  • NETCONF Java toolkit is installed on the configuration management server.

  • Client application can log in to the device where the NETCONF server resides.

  • NETCONF service over SSH is enabled on the device where the NETCONF server resides.

Overview

The Device class contains the loadSetConfiguration() and loadSetFile() methods, which load configuration data as a set of Junos OS configuration mode commands on devices running Junos OS Release 11.4 or a later release. For each configuration element, you can specify the complete statement path in the command, or you can use navigation commands , such as edit, to move around the configuration hierarchy as you do in CLI configuration mode. The NETCONF Java toolkit converts the command set to the equivalent RPC in XML that can be processed by the NETCONF server on devices running Junos OS. Junos OS executes the configuration instructions line by line.

The method syntax is:

The loadSetConfiguration() method takes as an argument the configuration command string that you would enter in Junos OS CLI configuration mode. For example, to add the ftp statement at the [edit system services] hierarchy level, you use the set system services ftp command. The loadSetFile() method takes as an argument the path of the file containing the set of configuration commands.

You can also use both methods to load multiple commands. To load multiple commands using the loadSetConfiguration() method, you can either list the commands as a single string and separate them with the \n newline sequence, or you can execute the method separately for each command. To load multiple commands using the loadSetFile() method, place each command on a separate line in the file.

Note:

When using the loadSetConfiguration() method with navigation commands, you should list the commands as a single string and separate them with the \n newline sequence. You cannot call the loadSetConfiguration() method with a single navigation command such as up.

The program in this example loads two configuration commands, which merge two statements into the candidate configuration on a device running Junos OS Release 11.4. The first command, set system services ftp, adds the ftp statement at the [edit system services] hierarchy level. The second command, set interfaces ge-0/0/0 disable, adds the disable statement at the [edit interfaces ge-0/0/0] hierarchy level. The relevant statements in the program code are:

Configuration

Creating the Java Program

Step-by-Step Procedure

To construct the Java program file:

  1. Give the file a descriptive name.

    The filename must be the same as the class name. For this example, the file and class are named LoadSetConfig.

  2. Add the code to the file and update the environment-specific variables such as the remote host IP address, username, password, and <rpc-reply> tag elements.

    The complete Java code for the LoadSetConfig.java program is presented here.

    If you load the set of commands from a file, create a file containing the commands, and replace the two loadSetConfiguration() method calls with a call to the loadSetFile() method.

Compiling and Running the Java Program

Step-by-Step Procedure

You need a Java compiler to compile the source code and to create an executable program.

To compile the code and run the program on the configuration management server:

  1. Compile the LoadSetConfig.java file.

  2. Execute the LoadSetConfig program.

Verification

To confirm that the program is working properly:

Verifying Program Execution

Purpose

Verify that the LoadSetConfig program runs correctly.

Action

If the program executes successfully, it establishes a connection and creates a NETCONF session with the specified device. The program merges the new statements with the candidate configuration on the device and commits the configuration.

Verifying the Configuration Changes

Purpose

You can verify that the configuration was correctly merged and committed by viewing the resulting configuration on the remote device. The ftp and the disable statements should now be in the active configuration. On a device running Junos OS, issue the following operational mode commands to view the [edit system services] and [edit interfaces] hierarchy levels:

Action

Verifying the Commit

Purpose

Additionally, you can review the commit log to verify that the commit was successful. On a device running Junos OS, issue the show system commit operational mode command to view the commit log. In this example, the log confirms that the user admin committed the candidate configuration in a NETCONF session at the given date and time.

Action

Issue the show system commit operational mode command and review the commit log.