May 04, 2017
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.
Note: You must have a user account on that appliance. The configuration operations that you can perform are limited by the administrative role assigned to your account.
The following sample code connects to a NetScaler SDX appliance with IP address 10.102.31.16 by using HTTPS protocol:
``` pre codeblock //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”);
Note: You must use the nitro\_service object in all further NITRO operations on the appliance. To disconnect from the appliance, invoke the logout() method as follows: ``` pre codeblock nitroservice.logout();
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:
- Set the value for the required properties of the resource by using the corresponding property name. The result is a resource object that contains the details required for the resource. Note: These values are set locally on the client. The values are not reflected on the appliance till the object is uploaded.
- Upload the resource object to the appliance, using the static add() method.
The following sample code creates a NetScaler instance named “ns_instance” on the NetScaler SDX appliance:
``` pre codeblock 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: 1. <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e59">Retrieve the configurations from the appliance by using the get() method. The result is a resource object.</span> 1. <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e64">Extract the required property from the object by using the corresponding property name.</span> The following sample code retrieves the details of all NetScaler resources: ``` pre codeblock //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:
``` pre codeblock 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: 1. <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e91">Set the id property to the ID of the resource to be updated.</span> 1. <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e93">Set the value for the required properties of the resource by using the corresponding property name. The result is a resource object.</span> Note: These values are set locally on the client. The values are not reflected on the appliance till the object is uploaded. 1. <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e97">Upload the resource object to the appliance, using the update() method.</span> The following sample code updates the name of the NetScaler instance with ID 123456a to 'ns\_instance\_new': ``` pre codeblock 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:
``` pre codeblock ns obj = new ns(); obj.id = “123456a”; ns.delete(nitroservice, obj);
**Bulk Operations** 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. To account for the failure of some operations within the bulk operation, NITRO allows you to configure one of the following behaviors: - <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e133">**Exit.** When the first error is encountered, the execution stops. The commands that were executed before the error are committed.</span> - <span id="reference_1191E76FA4AE4022990A778754D123E4__d3400e137">**Continue.** All the commands in the list are executed even if some commands fail.</span> Note: You must configure the required behavior while establishing a connection with the appliance, by setting the onerror param in the nitro\_service() method. The following sample code adds two NetScalers in one operation: ``` pre codeblock 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.
- An errorcode of 0 indicates that the operation is successful.
- A non-zero errorcode indicates an error in processing the NITRO request.
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.