Use the NETCONF Java Toolkit to Perform Configuration Tasks
Use 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 anet.juniper.netconf.XMLobject, 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.
/*
r1-config-set.txt:
set system services ftp
r1-config-text.txt:
system {
services {
ftp;
}
}
r1-config-xml.txt:
<system>
<services>
<ftp/>
</services>
</system>
*/
String config_file_set = "configs/r1-config-set.txt"
String config_file_text = "configs/r1-config-text.txt"
String config_file_xml = "configs/r1-config-xml.txt"
XMLBuilder builder = new XMLBuilder();
XML ftp_config = builder.createNewConfig("system", "services", "ftp");
Device device = new Device("10.10.1.1","admin","PaSsWoRd",null);
device.connect();
//open a private copy of the candidate configuration
device.openConfiguration("private");
// load configuration data as Junos OS configuration mode commands
device.loadSetConfiguration("set system services ftp");
device.loadSetFile(config_file_set);
// load configuration data as formatted ASCII text
device.loadTextConfiguration("system { services { ftp; } }", "merge");
device.loadTextFile(config_file_text, "merge");
// load configuration data as Junos XML tag elements
device.loadXMLConfiguration(ftp_config.toString(), "merge");
device.loadXMLFile(config_file_xml, "merge");
device.commit();
device.close();
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:
<configuration>
<system>
<services>
<ftp/>
</services>
</system>
</configuration>
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.
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:
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.
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.
import java.io.IOException; import javax.xml.parsers.ParserConfigurationException; import net.juniper.netconf.CommitException; import net.juniper.netconf.Device; import net.juniper.netconf.LoadException; import net.juniper.netconf.NetconfException; import net.juniper.netconf.XML; import net.juniper.netconf.XMLBuilder; import org.xml.sax.SAXException; public class EditConfig { public static void main(String[] args) throws LoadException, IOException, NetconfException, ParserConfigurationException, SAXException { /*Build the following XML hierarchy to add to the configuration: * <configuration> * <system> * <services> * <ftp/> * </services> * </system> * </configuration> */ XMLBuilder builder = new XMLBuilder(); XML ftp_config = builder.createNewConfig("system", "services", "ftp"); //Create the device Device device = new Device("10.10.1.1","admin","PaSsWoRd",null); device.connect(); //Lock the configuration boolean isLocked = device.lockConfig(); if(!isLocked) { System.out.println("Could not lock configuration. Exit now."); return; } //Load and commit the configuration try { device.loadXMLConfiguration(ftp_config.toString(), "merge"); device.commit(); } catch(LoadException e) { System.out.println(e.getMessage()); return; } catch(CommitException e) { System.out.println(e.getMessage()); return; } //Unlock the configuration and close the device device.unlockConfig(); device.close(); } }
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:
Compile the EditConfig.java file.
> javac EditConfig.java
Execute the EditConfig program.
> java EditConfig
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:
user@host> show configuration system services
ftp;
netconf {
ssh;
}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:
public void loadSetConfiguration (String setCommands) public void loadSetFile (String filePath)
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.
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:
String system_config = "set system services ftp"; String interfaces_config = "set interfaces ge-0/0/0 disable"; device.loadSetConfiguration(system_config); device.loadSetConfiguration(interfaces_config);
Configuration
Creating the Java Program
Step-by-Step Procedure
To construct the Java program file:
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.
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 theloadSetFile()method./*LoadSetConfig*/ import java.io.IOException; import javax.xml.parsers.ParserConfigurationException; import net.juniper.netconf.Device; import net.juniper.netconf.CommitException; import net.juniper.netconf.LoadException; import net.juniper.netconf.NetconfException; import net.juniper.netconf.XML; import org.xml.sax.SAXException; public class LoadSetConfig { public static void main(String args[]) throws NetconfException, ParserConfigurationException, SAXException, IOException { String system_config = "set system services ftp"; String interfaces_config = "set interfaces ge-0/0/0 disable"; Device device = new Device("10.10.1.1","admin","PaSsWoRd",null); try { device.connect(); System.out.println("Connection successful."); if (device.lockConfig()) { System.out.println("Configuration successfully locked."); try { System.out.println("Updating configuration."); device.loadSetConfiguration(system_config); device.loadSetConfiguration(interfaces_config); System.out.println("Committing configuration."); device.commit(); } catch (LoadException e) { System.out.println("LoadException occurred: " + e.getMessage()); } catch (CommitException e) { System.out.println("CommitException occurred: " + e.getMessage()); } device.unlockConfig(); device.close(); } else { System.out.println("Error - cannot lock configuration"); } } catch (NetconfException e) { System.out.println("Could not connect to device: " + e.getMessage()); } } }
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:
Compile the LoadSetConfig.java file.
> javac LoadSetConfig.java
Execute the LoadSetConfig program.
> java LoadSetConfig
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.
>java LoadSetConfig Connection successful. Configuration successfully locked. Updating configuration. Committing 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
admin@host> show configuration system services
ftp;
netconf {
ssh;
}admin@host> show configuration interfaces
ge-0/0/0 {
disable;
}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.
admin@host> show system commit 0 2011-09-02 14:16:44 PDT by admin via netconf 1 2011-07-08 14:33:46 PDT by root via other