NetScaler SDX NITRO APIs are categorized depending on the scope and purpose of the APIs into system APIs and configuration APIs. You can also troubleshoot NITRO operations.
The first step towards using NITRO is to establish a session with the NetScaler SDX appliance and then authenticate the session by using the administrator's credentials.
You must create an object of the nitro_service class by specifying the IP address of the appliance and the protocol to connect to the appliance (HTTP or HTTPS). You then use this object and log on to the appliance by specifying the user name and the password of the administrator.
The following sample code connects to a NetScaler SDX appliance with IP address 10.102.31.16 by using HTTPS protocol:
//Specify the IP address of the appliance and service type nitro_service nitroservice = new nitro_service ("10.102.31.16", "https"); //Specify the login credentials nitroservice.login("nsroot", "verysecret");
To disconnect from the appliance, invoke the logout() method as follows:
The NITRO protocol can be used to configure resources of the NetScaler SDX appliance.
The APIs to configure a resource are grouped into packages or namespaces that have the format com.citrix.sdx.nitro.resource.config.<resource_type>. Each of these packages or namespaces contain a class named <resource_type> that provides the APIs to configure the resource.
For example, the NetScaler resource has the com.citrix.sdx.nitro.resource.config.ns package or namespace.
A resource class provides APIs to perform other operations such as creating a resource, retrieving resources and resource properties, updating a resource, deleting resources, and performing bulk operations on resources.
Creating a Resource
To create a new resource (for example, a NetScaler instance) on the NetScaler SDX appliance:
The following sample code creates a NetScaler instance named "ns_instance" on the NetScaler SDX appliance:
ns newns = new ns(); //Set the properties of the NetScaler locally newns.name = "ns_instance"; newns.ip_address = "10.70.136.5"; newns.netmask = "255.255.255.0"; newns.gateway = "10.70.136.1"; newns.image_name = "nsvpx-9.3.45_nc.xva"; newns.profile_name = "ns_nsroot_profile"; newns.vm_memory_total = 2048; newns.throughput = 1000; newns.pps = 1000000; newns.license = "Standard"; newns.username = "admin"; newns.password = "admin"; int number_of_interfaces = 2; network_interface interface_array = new network_interface[number_of_interfaces]; //Adding 10/1 interface_array = new network_interface(); interface_array.port_name = "10/1"; //Adding 10/2 interface_array = new network_interface(); interface_array.port_name = "10/2"; newns.network_interfaces = interface_array; //Upload the NetScaler instance ns result = ns.add(nitroservice, newns);
Retrieve Resource Details
To retrieve the properties of a resource on the NetScaler SDX appliance, do the following:
The following sample code retrieves the details of all NetScaler resources:
//Retrieve the resource object from the NetScaler SDX appliance ns returned_ns = ns.get(nitroservice); //Extract the properties of the resource from the object Console.WriteLine(returned_ns[i].ip_address); Console.WriteLine(returned_ns[i].netmask);
Retrieve Resource Statistics
A NetScaler SDX appliance collects statistics on the usage of its features. You can retrieve these statistics using NITRO.
The following sample code retrieves statistics of a NetScaler instance with ID 123456a:
ns obj = new ns(); obj.id = "123456a"; ns stats = ns.get(nitroservice, obj); Console.WriteLine("CPU Usage:" + stats.ns_cpu_usage); Console.WriteLine("Memory Usage:" + stats.ns_memory_usage); Console.WriteLine("Request rate/sec:" +stats.http_req);
Updating a Resource
To update the properties of an existing resource on the appliance, do the following:
The following sample code updates the name of the NetScaler instance with ID 123456a to 'ns_instance_new':
ns update_obj = new ns(); //Set the ID of the NetScaler to be updated update_obj.id = "123456a"; //Get existing NetScaler details update_obj = ns.get(nitroservice, update_obj); //Update the name of the NetScaler to "ns_instance_new" locally update_obj.name = "ns_instance_new"; //Upload the updated NetScaler details ns result = ns.update(nitroservice, update_obj);
Deleting a Resource
To delete an existing resource, invoke the static method delete() on the resource class, by passing the ID of the resource to be removed, as an argument.
The following sample code deletes a NetScaler instance with ID 1:
ns obj = new ns(); obj.id = "123456a"; ns.delete(nitroservice, obj);
You can query or change multiple resources simultaneously and thus minimize network traffic. For example, you can add multiple NetScaler appliances in the same operation.
Each resource class has methods that take an array of resources for adding, updating, and removing resources. To perform a bulk operation, specify the details of each operation locally and then send the details at one time to the server.
The following sample code adds two NetScalers in one operation:
ns newns = new ns; //Specify details of first NetScaler newns = new ns(); newns.name = "ns_instance1"; newns.ip_address = "10.70.136.5"; newns.netmask = "255.255.255.0"; newns.gateway = "10.70.136.1"; ... ... //Specify details of second NetScaler newns = new ns(); newns.name = "ns_instance2"; newns.ip_address = "10.70.136.8"; newns.netmask = "255.255.255.0"; newns.gateway = "10.70.136.1"; ... ... //upload the details of the NetScalers to the NITRO server ns result = ns.add(nitroservice, newns);
The errorcode field indicates the status of the operation.
The error message field provides a brief explanation and the nature of the failure.
All exceptions in the execution of NITRO APIs are caught by the com.citrix.sdx.nitro.exception.nitro_exception class. To get information about the exception, you can use the getErrorCode() method.
For a more detailed description of the error codes, see the API reference available in the <NITRO_SDK_HOME>/doc folder.