NETCONF Java Toolkit Classes

A net.juniper.netconf.Device object represents an SSHv2 connection and a default NETCONF session between the configuration management server and the device on which the NETCONF server resides.

When creating a Device object, you must provide the IP address or hostname and the authentication details to create the SSHv2 connection. Authentication can be user-password based or RSA/DSA key-based. You also have the option of specifying the port number for the SSHv2 connection and the client capabilities to send to the NETCONF server.

The constructor syntax is:

The constructor parameters are:

• hostname—(Required) IP address or hostname of the device on which the NETCONF server is running and to which to connect via SSHv2.

• login—(Required) Username for the login account on the device on which the NETCONF server is running.

• password—(Required) Password for either user password-based authentication or key-based authentication. If no password is required for key-based authentication, pass this argument as null.

• pemKeyFile—(Required) Path of the file containing the DSA/RSA private key in PEM format for key-based authentication. For user password-based authentication, pass this argument as null.

• port—(Optional) Port number on which to establish the SSHv2 connection. The default port is 830. If you are connecting to a device that is configured for NETCONF over SSH on a port other than the default port, you must specify that port number in the arguments.

• capabilities—(Optional) Client capabilities to be communicated to the NETCONF server, if the capabilities are other than the default capabilities.

  The default capabilities sent to the NETCONF server are:

The general syntax for creating a Device object is:

By default, a NetconfSession object is created when you create a new instance of Device and connect to a NETCONF server. Once you have created a Device object, you can perform NETCONF operations.

Examples

The following example creates a Device object with an authenticated SSHv2 connection to IP address 10.10.1.1. The connection uses user password-based authentication with the login name “admin” and the password “PaSsWoRd”. When the connect() method is called, it connects to the device and automatically establishes a default NETCONF session.

To create a Device object with a NETCONF-over-SSH connection on port 49000 instead of the default port 830, add the port number to the constructor arguments.

The default timeout value for connecting to the device is 5000 milliseconds. To set the timeout value to a different interval, call the setTimeOut() method on the device object.

A net.juniper.netconf.NetconfSession object represents the NETCONF session between the configuration management server and the device on which the NETCONF server resides.

By default, a NETCONF session is created when you create a new instance of Device and connect to a NETCONF server, so you do not need to explicitly create a NetconfSession object. You can perform the NETCONF operations directly from the Device object by calling the associated methods.

However, there might be times when you need multiple NETCONF sessions on the same SSHv2 connection. To create multiple sessions, call the createNetconfSession() method on the Device object as shown in the following example:

Once you create an additional NETCONF session, you call the NETCONF operation methods for the new NetconfSession object in the same way as you call them for the Device object.

The Device and NetconfSession classes contain many identical methods, which perform NETCONF operations such as executing remote procedure calls (RPCs) and performing configuration changes. When you call a method on the Device object, it acts on the default NETCONF session. When you call a method on any additional NetconfSession object, it acts on that NETCONF session.

Example: Creating Multiple NETCONF Sessions

In the following example, the code snippet creates a new Device object. When the connect() method is called, the program connects to the remote device and establishes a default NETCONF session. The program creates a second NetconfSession object, second_session. Calling device.getSessionID() returns the session ID of the default NETCONF session, and calling second_session.getSessionID() returns the session ID of the second NETCONF session.

A net.juniper.netconf.XML object represents XML-encoded data and provides methods to modify and parse the XML. The XML object internally maintains an org.w3c.dom.Document object, corresponding to the XML data it represents.

It is recommended that you work with the XML object to create new configurations, remote procedure calls (RPCs), or any XML-based data. Using an XML object, you can easily add, delete, or modify elements and attributes. To facilitate modification of XML content, the XML object maintains an ‘active’ element, which represents the hierarchy level exposed for modification.

To create an XML object, you first create an XMLBuilder object and construct the initial XML hierarchy. The XMLBuilder methods return an XML object on which you can then build. This makes it convenient to create XML-based configurations and RPCs and also parse the XML-based replies received from the NETCONF server.

Example: Creating a Configuration Hierarchy

This example creates the following sample XML configuration hierarchy. The steps used to create the configuration hierarchy are outlined in Table 1.

<configuration>
   <security>
      <policies>
         <policy>
         </policy>
      </policies>
   </security>
</configuration>

<configuration>
   <security>
      <policies>
         <policy>
 
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
 
         </policy>
      </policies>
   </security>
</configuration> 

<configuration>
   <security>
      <policies>
         <policy>
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
 
            <policy>
               <name>my-sec-policy</name>
            </policy>
 
         </policy>
      </policies>
   </security>
</configuration>

<configuration>
   <security>
      <policies>
         <policy>
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
            <policy>
               <name>my-sec-policy</name>
 
               <match>
                  <application>junos-ftp</application>
                  <application>junos-ntp</application>
                  <application>junos-ssh</application>
               </match>
 
            </policy>
         </policy>
      </policies>
   </security>
</configuration>

<configuration>
   <security>
      <policies>
         <policy>
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
            <policy>
               <name>my-sec-policy</name>
               <match>
                  <application>junos-ftp</application>
                  <application>junos-ntp</application>
                  <application>junos-ssh</application>
 
                  <source-address>any</source-address>
                  <destination-address>
                     any
                  </destination-address>
 
               </match>
            </policy>
         </policy>
      </policies>
   </security>
</configuration>

<configuration>
   <security>
      <policies>
         <policy>
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
            <policy>
               <name>my-sec-policy</name>
               <match>
                  <application>junos-ftp</application>
                  <application>junos-ntp</application>
                  <application>junos-ssh</application>
                  <source-address>any</source-address>
                  <destination-address>
                     any
                  </destination-address>
               </match>
 
               <then>
                  <permit/>
               </then>
 
            </policy>
         </policy>
      </policies>
   </security>
</configuration>

XMLBuilder builder = new XMLBuilder();
XML policy = builder.createNewConfig("security","policies","policy");
policy.append("from-zone-name","trust");
policy.append("to-zone-name","untrust");
XML policyOne = policy.append("policy");
policyOne.append("name","my-sec-policy");
XML match = policyOne.append("match");
String[] applications = {"junos-ftp","junos-ntp","junos-ssh"};
match.append("application", applications);
match.append("source-address","any");
match.append("destination-address","any");
policyOne.append("then").append("permit");

<configuration>
   <security>
      <policies>
         <policy>
            <from-zone-name>trust</from-zone-name>
            <to-zone-name>untrust</to-zone-name>
            <policy>
               <name>my-sec-policy</name>
               <match>
                  <application>junos-ftp</application>
                  <application>junos-ntp</application>
                  <application>junos-ssh</application>
                  <source-address>any</source-address>
                  <destination-address>any
                  </destination-address>
               </match>
               <then>
                  <permit/>
               </then>
            </policy>
         </policy>
      </policies>
   </security>
</configuration>

In a NETCONF session, communication between the configuration management server and the NETCONF server is through XML-encoded data. The configuration management server sends remote procedure calls (RPCs) to the NETCONF server, and the NETCONF server processes the RPC and returns an RPC reply. The net.juniper.netconf.XMLBuilder and net.juniper.netconf.XML objects help create and parse XML-encoded data.

You use the XMLBuilder object to create a new XML object. The constructor syntax is:

The XMLBuilder class includes methods to create a configuration hierarchy, an RPC, or an XML object as XML-encoded data. Each method is overloaded to accept multiple hierarchy levels. The methods return an XML object. For example, the methods to construct a configuration, RPC, or XML object with a single-tier hierarchy are:

• createNewConfig(String elementLevelOne)

• createNewRPC(String elementLevelOne)

• createNewXML(String elementLevelOne)

The following sample code creates a new XMLBuilder object, builder. The XMLBuilder object calls the createNewConfig() method to construct a three-tier configuration hierarchy consisting of a “security” element, a “policies” element child tag, and a “policy” element that is a child of “policies”.

The resulting XML hierarchy is as follows.

Notice that the createNewConfig() method always encloses the hierarchy within a top-level root element <configuration>. Similarly, the createNewRPC() method encloses the hierarchy within an <rpc> tag element.

Once you generate an XML object, you can call methods from the XML class to manipulate that object.