So far in this NITRO blog series we have seen various benefits and features of NITRO APIs and how to use them with NetScaler, Command Center and SDX appliance. Last one (/blogs/2011/08/27/nitro-providing-programmatic-management-and-monitoring-through-command-center/) covered the usage with Command Center. It is the time for real hands-on data and specific code snippets which will help you write your programs for NetScaler management using NetScaler API and SDK. In this blog we will focus on how to write a Java based program utilizing NetScaler NITRO APIs.

We provide Java SDK for NITRO and that helps a lot while you start to code as most of the core methods and functionality is built-in and ready to use by importing base classes. We will go over the steps to do following simple tasks which put together can give you the first program:

  • Login to NetScaler
  • Add LB vserver
  • Set LB vserver
  • Show LB vserver
  • Remove LB vserver
  • Logout from NetScaler

 

Let us go over step by step procedure on how we can accomplish this.

Step 1: Import relevant Java classes

  • import com.citrix.netscaler.nitro.exception.nitro_exception;
  • import com.citrix.netscaler.nitro.resource.base.base_response;
  • import com.citrix.netscaler.nitro.resource.config.lb.lbvserver;
  • import com.citrix.netscaler.nitro.service.nitro_service;

 

These classes provide functions for session creation/termination, dealing with LB vserver configuration, handling the response and dealing with exceptions. NITRO has excellent exception handling support and you can use “getErrorCode()” and “getMessage()” APIs to get key data on the exception.

Step 2: Logging into the NetScaler and creating a session

Before you do any functional operation using NITRO API, must have a valid session established by performing login to the NetScaler appliance.

  • nitro_service session= new nitro_service(ip_address,”https”);   
  • base_response result=session.login(username,password);

 

The above code provides a NITRO session with NetScaler on given IP address and performs login with given username and password. You need to parse and handle the response to check for exceptions and errors. You can use http instead of https as the medium of communication but that will not be secure.

Step 3: Adding LB vserver

Once you have established valid session, it is very easy to start with specific LB vserver configuration.

  • lbvserver lbvserver1 = new lbvserver();
  • lbvserver1.set_name(“lbvip1”);
  • lbvserver1.set_servicetype(“http”);      
  • lbvserver1.set_ipv46(“10.10.10.11”);
  • lbvserver1.set_port(80);
  • base_response result = lbvserver.add(session,lbvserver1);

 

We are creating a LB vserver object from relevant class such that we can use the built-in variables and methods. We set the mandatory arguments like Name, Servicetype, IP address and Port before calling the function to add this LB vserver on NetScaler. You must look through the response for any error or exception.

Step 4: Setting LB vserver properties

LB vserver has several properties which you may want to change at runtime using the Update function.

  • lbvserver1.set_lbmethod(“ROUNDROBIN”);     
  • base_response result = lbvserver.update(session,lbvserver1);

 

For update we are using the “lbvserver1” object created in previous step. We are updating LB method which is changed from default “Least Connection” to “Round Robin”. If you are doing this update in a separate session then you will need to set the LB vserver name to start with.

  • lbvserver lbvserver1 = new lbvserver();
  • lbvserver1.set_name(“lbvip1″);
  • lbvserver1.set_lbmethod(“ROUNDROBIN”);
  • base_response result = lbvserver.update(session,lbvserver1);

Similarly you can set rest of the parameters on same object and finally call the “update” method to do single call and change all required properties.

Step 5: Show LB vserver

Show operation is straight forward and only requires single API call.

  • lbvserver result = lbvserver.get(session,”lbvip1”);

 

This call returns you the complete structure for the LB vserver “lbvip1”. You can parse the result and use further methods to get specific data out.

  • result.get_name()
    • fetches the name of LB vserver
  • result.get_port()
    • fetches the port on which vserver is listening
  • result.get_servicetype()
    • fetches the servicetype/protocol parameter

 

Similarly there are multiple other methods to get specific information.

Step 6: Remove LB vserver

Let us delete the LB vserver configuration we have created in this example. It is again a simple operation with single API call to remove the configuration.

  • base_response result = lbvserver.delete(session,lbvserver1);

 

We are using the same session and “lbvserver1” object which we created to add LB vserver and set its properties. Using same object we can call the “delete” method to remove LB vserver configured.

So are we done? Yeah looks like as we have completed all the operations we wanted to.

What about the “session” object, did we do anything about it?? That’s an active and authenticated session which can be used to communicate with same NetScaler unless the session timeout. Hmmm… so we need to logout and kill the session structure before we call it done. Otherwise we are creating security holes!!

Step 7: Logging out of NetScaler

Another simple API

  • base_response result= session.logout();

 

With this you have ensured successful logout from the system. Be sure to parse the response and ensure a successful logout. Isn’t it easy to write this Java program with the help of NITRO SDK for Java 🙂