Product Documentation

Feature Configuration APIs

Sep 08, 2016

NetScaler resources are organized into a set of packages or namespaces. Each package or namespace corresponds to a NetScaler feature. For example, all load-balancing related resources, such as load balancing virtual server, load balancing group, and load balancing monitor are available in com.citrix.netscaler.nitro.resource.config.lb.

Similarly, all application firewall related resources, such as application firewall policy and application firewall archive are available in com.citrix.netscaler.nitro.resource.config.appfw.

Each NetScaler resource is represented by a class. For example, the class that represents a load balancing virtual server is called lbvserver (in com.citrix.netscaler.nitro.resource.config.lb). The state of a resource is represented by properties of a class. You can get and set the properties of the class.

Note: The setter and getter properties are always executed locally on the client. They do not involve any network interaction with the NITRO web service. All properties have basic simple types: integer, long, boolean, and string.

A resource class provides APIs to perform the following operations:

Create | Retrieve | Update | Delete | Enable/Disable | Unset | Bind/Unbind | Global bind | Bulk operations

Create

To create a new resource, instantiate the resource class, configure the resource by setting its properties locally, and then upload the new resource instance to the NetScaler appliance.

The following sample code creates a load balancing virtual server:

//Create an instance of the lbvserver class 
lbvserver new_lbvserver_obj = new lbvserver();  
 
//Set the properties of the resource locally 
new_lbvserver_obj.name = "MyFirstLbVServer"; 
new_lbvserver_obj.ipv46 = "10.102.29.88"; 
new_lbvserver_obj.port = 88; 
new_lbvserver_obj.servicetype = "HTTP"; 
new_lbvserver_obj.lbmethod = "ROUNDROBIN"; 
 
//Upload the resource to NetScaler 
lbvserver.add(ns_session,new_lbvserver_obj);

Retrieve

To retrieve the properties of a resource, retrieve the resource object from the NetScaler appliance. Once the object is retrieved, you can extract the required properties of the resource locally, without incurring further network traffic.

The following sample code retrieves the details of a load balancing virtual server:

//Retrieve the resource object from the NetScaler 
new_lbvserver_obj = lbvserver.get(ns_session,"MyFirstLbVServer"); 
 
//Extract the properties of the resource from the object locally 
Console.WriteLine(new_lbvserver_obj.name); 
Console.WriteLine(new_lbvserver_obj.servicetype);

You can also retrieve resources by specifying a filter on the value of their properties by using the com.citrix.netscaler.nitro.util.filtervalue class.

For example, you can retrieve all the load balancing virtual servers that have their port set to 80 and servicetype to HTTP:

filtervalue[] filter = new filtervalue[2]; 
filter[0] = new filtervalue("port","80"); 
filter[1] = new filtervalue("servicetype","HTTP"); 
lbvserver[] result = lbvserver.get_filtered(ns_session,filter);

You can also retrieve all NetScaler resources of a certain type, such as all services in the NetScaler appliance, by calling the static get() method on the service class, without providing a second parameter, as follows:

service[] resources = service.get(ns_session);

Update

To update the properties of a resource, instantiate the resource class, specify the name of the resource to be updated, configure the resource by updating its properties locally, and then upload the updated resource instance to the NetScaler appliance.

The following sample code updates the service type and load balancing method of a load balancing virtual server:

//Create an instance of the lbvserver class 
lbvserver update_lb = new lbvserver(); 
 
//Specify the name of the lbvserver to be updated 
update_lb.name = "MyFirstLbVServer"; 
 
//Specify the updated service type and lb method 
update_lb.servicetype = "https"; 
update_lb.lbmethod = "LEASTRESPONSETIME"; 
 
//Upload the resource to NetScaler 
lbvserver.update(ns_session, update_lb);
Note: Some properties in some NetScaler resources are not allowed to be modified after creation. The port number or the service type (protocol) of a load balancing virtual server or a service, are examples of such properties. Even though the update method appears to succeed, these properties retain their original values on the appliance.

Delete

To delete an existing resource, invoke the static method delete() on the resource class, by passing the name of the resource.

The following sample code deletes a load balancing virtual server with name "MyFirstLbVServer":

lbvserver remove_lb = new lbvserver(); 
remove_lb.name("MyFirstLbVServer"); 
lbvserver.delete(ns_session, remove_lb);

Enable/Disable

To enable a resource, invoke the enable() method.

The following sample code enables a load balancing virtual server named "lb_vip":

lbvserver obj = new lbvserver(); 
obj.name = "lb_vip"; 
lbvserver.enable(ns_session, obj);
Note: To disable a resource, invoke the disable() method.
lbvserver.disable(ns_session, obj);

Unset

To unset the value that is set to a parameter, invoke the unset() method on the resource class, by passing the name of the resource and the parameters to be unset. If the parameter has a default value, the value is reset to that value.

The following sample code unsets the load balancing method and the comments of a load balancing virtual server named "lb_123":

lbvserver obj = new lbvserver(); 
obj.name = "lb_123"; 
String[] args = { "lbmethod","comment" }; 
lbvserver.unset(ns_session, lb1, args);

Bind/Unbind

NetScaler resources form relationships with each other through the process of binding. This is how services are associated with a load balancing virtual server (by binding them to it), or how various policies are bound to a load balancing virtual server. Each binding relationship is represented in NITRO by its own class.

To bind one NetScaler resource to another, you must instantiate the appropriate binding class (for example, to bind a service to a load balancing virtual server, you must instantiate the lbvserver_service_binding class) and add it to the NetScaler configuration (by using the static add() method on this class).

Binding classes have a property representing the name of each resource in the binding relationship. They can also have other properties related to that relationship (for example, the weight of the binding between a load balancing virtual server and a service).

The following sample code binds a service to a load balancing virtual server, by specifying a certain weight for the binding:

lbvserver_service_binding bindObj = new lbvserver_service_binding(); 
bindObj.name = "MyFirstLbVServer"; 
bindObj.servicename = "svc_prod"; 
bindObj.weight = 20; 
lbvserver_service_binding.add(ns_session,bindObj);
Note: To unbind a resource from another, invoke the delete() method from the resource binding class, by passing the name of the two resources.

The following code sample unbinds a service from a server:

lbvserver_service_binding bindObj = new lbvserver_service_binding(); 
bindObj.name("MyFirstLbVServer"); 
bindObj.servicename("svc_prod"); 
lbvserver_service_binding.delete(ns_session,bindObj);

Global bind

Some NetScaler resources can be bound globally to affect the whole system. For example, a compression policy can be bound to an load balancing virtual server, in which case the policy affects only the traffic on that load balancing virtual server. However, if bound globally, it can affect any traffic on the appliance, regardless of which virtual servers handle the traffic.

Some NITRO classes can be used to bind resources globally. These classes have names that follow the following pattern: <featurename>global_<resourcetype>_binding.

For example, the class aaaglobal_preauthenticationpolicy_binding is used to bind preauthentication policies globally.

The following sample code creates a preauthentication action and a preauthentication policy that uses that action, and then binds the policy globally at priority 200:

aaapreauthenticationaction preauth_act1; 
aaapreauthenticationpolicy preauth_pol1; 
aaaglobal_aaapreauthenticationpolicy_binding glob_binding; 
preauth_act1 = new aaapreauthenticationaction(); 
preauth_act1.name = "preauth_act1"; 
preauth_act1.preauthenticationaction = "ALLOW"; 
aaapreauthenticationaction.add(ns_session, preauth_act1); 
 
preauth_pol1 = new aaapreauthenticationpolicy(); 
preauth_pol1.name = "preauth_pol1"; 
preauth_pol1.rule = "CLIENT.APPLICATION.PROCESS(antivirus.exe) EXISTS"; 
preauth_pol1.reqaction = "preauth_act1"; 
aaapreauthenticationpolicy.add(ns_session, preauth_pol1); 
 
glob_binding = new aaaglobal_aaapreauthenticationpolicy_binding(); 
glob_binding.policy = "preauth_pol1";  
glob_binding.priority = 200; 
aaaglobal_aaapreauthenticationpolicy_binding.add(ns_session,glob_binding);

Bulk operations

You can create, retrieve, update, and delete multiple resources simultaneously and thus minimize network traffic. For example, you can add multiple load balancing virtual servers in the same operation. To perform a bulk operation, you instantiate an array of the resource class, configure the properties of all the instances locally, and then upload all the instances to the NetScaler with one command.

To account for the failure of some operations within the bulk operation, NITRO allows you to configure one of the following behaviors:
  • Exit. When the first error is encountered, the execution stops. The commands that were executed before the error are committed.
  • Rollback. When the first error is encountered, the execution stops. The commands that were executed before the error are rolled back. Rollback is only supported for add and bind commands.
  • Continue. All the commands in the list are executed even if some commands fail.
Note: You must configure the required behavior while establishing a connection with the appliance.
nitro_service ns_session = new nitro_service("10.102.29.60","http"); 
ns_session.onerror = OnerrorEnum.CONTINUE; 
ns_session.login("admin","verysecret");

The following sample code creates two load balancing virtual servers:

//Create an array of lbvserver instances 
lbvserver[] lbs = new lbvserver[2]; 
 
//Specify details of first lbvserver 
lbs[0] = new lbvserver(); 
lbs[0].name = "lbvserv1"; 
lbs[0].servicetype = "http"; 
lbs[0].ipv46 = "10.70.136.5"; 
lbs[0].port = 80; 
 
//Specify details of second lbvserver 
lbs[1] = new lbvserver(); 
lbs[1].name = "lbvserv2"; 
lbs[1].servicetype = "https"; 
lbs[1].ipv46 = "10.70.136.5"; 
lbs[1].port = 443; 
 
//upload the details of the lbvservers to the NITRO server 
lbvserver.add(ns_session,lbs);