miscellaneous use cases
This section covers some miscellaneous use cases.
Managing a Citrix ADC Cluster
For managing clusters, you can add or remove a cluster instance or an individual node and perform a few other instance or node operations such as viewing instance or node properties. You can also configure the cluster IP address. Other cluster-management tasks include joining a Citrix ADC appliance to the cluster and configuring a linkset. For detailed information and best practices, see Clustering.
Cluster Instance Operations
This topic covers cluster instance operations by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
All operations on a cluster instance must be performed on the clusterinstance object.
For example, to create a cluster instance with ID 1, connect to the Citrix ADC appliance that you are first adding to the cluster.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/clusterinstance
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"clusterinstance":
{
"clid":1,
"preemption":"ENABLED"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.cluster.clusterinstance class provides APIs to manage a cluster instance.
The following sample code creates a cluster instance with ID 1.
Java - Sample code to create a cluster instance
clusterinstance new_cl_inst_obj = new clusterinstance();
//Set the properties of the cluster instance locally
new_cl_inst_obj.set_clid(1);
new_cl_inst_obj.set_preemption("ENABLED");
//Upload the cluster instance
clusterinstance.add(ns_session,new_cl_inst_obj);
<!--NeedCopy-->
.NET - Sample code to create a cluster instance
clusterinstance new_cl_inst_obj = new clusterinstance();
//Set the properties of the cluster instance locally
new_cl_inst_obj.clid = 1;
new_cl_inst_obj.preemption = "ENABLED";
//Upload the cluster instance
clusterinstance.add(ns_session,new_cl_inst_obj);
<!--NeedCopy-->
Python - Sample code to create a cluster instance
new_cl_inst_obj = clusterinstance()
# Set the properties of the cluster instance locally
new_cl_inst_obj.clid = 1
# Upload the cluster instance
clusterinstance.add(ns_session, new_cl_inst_obj)
<!--NeedCopy-->
Cluster Node Operations
This topic covers cluster node operations by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
All operations on a cluster node must be performed on the clusternode object. For example, to add a Citrix ADC appliance with NSIP address 10.102.29.60 to the cluster.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/clusternode
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"clusternode":
{
"nodeid":1,
"ipaddress":"10.102.29.60",
"state":"ACTIVE",
"backplane":"1/1/2"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.cluster.clusternode class provides APIs to manage cluster nodes.
The following sample code adds a cluster node with NSIP address 10.102.29.60.
Java - Sample code to add a cluster node
clusternode new_cl_node_obj = new clusternode();
//Set the properties of the cluster node locally
new_cl_node_obj.set_nodeid(0);
new_cl_node_obj.set_ipaddress("10.102.29.60");
new_cl_node_obj.set_state("ACTIVE");
new_cl_node_obj.set_backplane("0/1/1");
//Upload the cluster node
clusternode.add(ns_session,new_cl_node_obj);
<!--NeedCopy-->
.NET - Sample code to add a cluster node
clusternode new_cl_node_obj = new clusternode();
//Set the properties of the cluster node locally
new_cl_node_obj.nodeid = 0;
new_cl_node_obj.ipaddress = "10.102.29.60";
new_cl_node_obj.state = "ACTIVE";
new_cl_node_obj.backplane = "0/1/1";
//Upload the cluster node
clusternode.add(ns_session,new_cl_node_obj);
<!--NeedCopy-->
Python - Sample code to add a cluster node
new_cl_node_obj = clusternode()
# Set the properties of the cluster node locally
new_cl_node_obj.nodeid = 0
new_cl_node_obj.ipaddress = "10.102.29.60"
new_cl_node_obj.state = "ACTIVE"
new_cl_node_obj.backplane = "0/1/1"
# Upload the cluster node
clusternode.add(ns_session, new_cl_node_obj)
<!--NeedCopy-->
Add a Cluster IP Address
This topic covers adding a cluster IP address by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To define a cluster IP address, specify the required parameters in the nsip object. For example, to configure a cluster IP address.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nsip
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"nsip":
{
"ipaddress":"10.102.29.61",
"netmask":"255.255.255.255",
"type":"CLIP"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.ns.nsip class provides the add() API to configure an IP address. To configure the IP address as a cluster IP address, you must specify the type as CLIP.
The following sample code configures a cluster IP address on Citrix ADC appliance with IP address 10.102.29.60.
Java - Sample code to add a cluster IP address
nsip new_nsip_obj = new nsip();
//Set the properties locally
new_nsip_obj.set_ipaddress("10.102.29.61");
new_nsip_obj.set_netmask("255.255.255.255");
new_nsip_obj.set_type("CLIP");
//Upload the cluster node
nsip.add(ns_session,new_nsip_obj);
<!--NeedCopy-->
.NET - Sample code to add a cluster IP address
nsip new_nsip_obj = new nsip();
//Set the properties locally
new_nsip_obj.ipaddress = "10.102.29.61";
new_nsip_obj.netmask = "255.255.255.255";
new_nsip_obj.type = "CLIP";
//Upload the cluster node
nsip.add(ns_session,new_nsip_obj);
<!--NeedCopy-->
Python - Sample code to add a cluster IP address
new_nsip_obj = nsip()
# Set the properties locally
new_nsip_obj.ipaddress = "10.102.29.61"
new_nsip_obj.netmask = "255.255.255.255"
new_nsip_obj.type = "CLIP"
# Upload the cluster node
nsip.add(ns_session, new_nsip_obj)
<!--NeedCopy-->
Add a Spotted IP Address
This topic covers adding a spotted IP address by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To configure an IP address as spotted, specify the required parameters in the nsip object. This configuration must be done on the cluster IP address.
For example, to configure a spotted SNIP address on a node with ID 1.
-
Request
HTTP Method:
POST
URL:
http://<cluster-ip-address>/nitro/v1/config/nsip
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"nsip":
{
"ipaddress":"10.102.29.77",
"netmask":"255.255.255.0",
"type":"SNIP",
"ownernode":1
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.ns.nsip class provides the add() API to configure an IP address. To configure the IP address as spotted, you must specify the ID of the node that must own the IP address. This configuration must be done on the cluster IP address.
The following sample code configures a spotted SNIP address on a node with ID 1.
Java - Sample code to configure a spotted IP address
nsip new_nsip_obj = new nsip();
//Set the properties locally
new_nsip_obj.set_ipaddress("10.102.29.77");
new_nsip_obj.set_netmask("255.255.255.0");
new_nsip_obj.set_type("SNIP");
new_nsip_obj.set_ownernode(1);
//Upload the cluster node
nsip.add(ns_session,new_nsip_obj);
<!--NeedCopy-->
.NET - Sample code to configure a spotted IP address
nsip new_nsip_obj = new nsip();
//Set the properties locally
new_nsip_obj.ipaddress = "10.102.29.77";
new_nsip_obj.netmask = "255.255.255.0";
new_nsip_obj.type = "SNIP";
new_nsip_obj.ownernode = 1;
//Upload the cluster node
nsip.add(ns_session,new_nsip_obj);
<!--NeedCopy-->
Python - Sample code to configure a spotted IP address
# Add a spotted IP address
new_nsip_obj = nsip()
# Set the properties locally
new_nsip_obj.ipaddress = "10.102.29.77"
new_nsip_obj.netmask = "255.255.255.0"
new_nsip_obj.type = "SNIP"
new_nsip_obj.ownernode = 1
# Upload the cluster node
nsip.add(ns_session, new_nsip_obj)
<!--NeedCopy-->
Join Citrix ADC Appliance to Cluster
This topic covers adding a Citrix ADC appliance to a cluster by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To join an appliance to a cluster, specify the required parameters in the cluster object. For example, to join a Citrix ADC appliance to a cluster.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/cluster
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"cluster":
{
"clip":"10.102.29.61",
"password":"verysecret"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.cluster.cluster class provides the join() API to join a Citrix ADC appliance to the cluster. You must specify the cluster IP address and the nsroot password of the configuration coordinator.
The following sample code joins a Citrix ADC appliance to a cluster.
Java - Sample code to join an appliance to a cluster
cluster new_cl_obj = new cluster();
//Set the properties of the cluster locally
new_cl_obj.set_clip("10.102.29.61");
new_cl_obj.set_password("verysecret");
//Upload the cluster
cluster.add(ns_session,new_cl_obj);
<!--NeedCopy-->
.NET - Sample code to join an appliance to a cluster
cluster new_cl_obj = new cluster();
//Set the properties of the cluster locally
new_cl_obj.clip = "10.102.29.61";
new_cl_obj.password = "verysecret";
//Upload the cluster node
cluster.add(ns_session,new_cl_node_obj);
<!--NeedCopy-->
Python - Sample code to join an appliance to a cluster
new_cl_obj = cluster()
# Set the properties of the cluster locally
new_cl_obj.clip = "10.102.29.61"
new_cl_obj.password = "verysecret"
# Upload the cluster
cluster.add(ns_session, new_cl_obj)
<!--NeedCopy-->
Linkset Operations
This topic covers some linkset operations by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To configure a linkset, do the following:
Create a linkset by specifying the required parameters in the linkset object. For example, to add a linkset LS/1:
Request:
HTTP Method:
POST
URL:
http://<cluster-ip-address>/nitro/v1/config/linkset
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
-
Request Payload
```json
{ “linkset”: { “id”:”LS/1” } }
- `Response`
`HTTP Status Code on Success:` 201 Created
`HTTP Status Code on Failure:` 4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
Bind the required interfaces to the linkset by specifying the interfaces in the linkset_interface_binding object.For example, to bind interfaces 1/1/2 and 2/1/2 to linkset LS/1.
- `Request`
`HTTP Method:` PUT
`URL:` http://http://http://http://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://http://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://http://http://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://http://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindlt;cluster-ip-addresshttp://\<cluster-ip-address\>/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bindgt;/nitro/v1/config/linkset_interface_binding/LS%2F1?action=bind
`Note.` The linkset name (LS/1), must be URL encoded as LS%2F1.
`Request Headers:`
Cookie:NITRO_AUTH_TOKEN=\<tokenvalue>
Content-Type:application/json
`Request Payload:`
```json
{
"linkset_interface_binding":
{
"id":"LS/1",
"ifnum":"1/1/2 2/1/2"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 Ok
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The com.citrix.netscaler.nitro.resource.config.network.linkset class provides the APIs to manage linksets.
To configure a linkset, do the following:
- Add a linkset by invoking the add() method of the linkset class.
- Bind the interfaces to the linkset using the add() method of the linkset_interface_binding class.
The following sample code creates a linkset LS/1 and bind interfaces 1/1/2 and 2/1/2 to it.
Java - Sample code to configure linksets
linkset new_linkset_obj = new linkset();
new_linkset_obj.set_id("LS/1");
linkset.add(ns_session,new_linkset_obj);
//Bind the interfaces to the linkset
linkset_interface_binding new_linkif_obj = new linkset_interface_binding();
new_linkif_obj.set_id("LS/1");
new_linkif_obj.set_ifnum("1/1/2 2/1/2");
linkset_interface_binding.add(ns_session,new_linkif_obj);
<!--NeedCopy-->
.NET - Sample code to configure linksets
linkset new_linkset_obj = new linkset();
new_linkset_obj.id = "LS/1";
linkset.add(ns_session,new_linkset_obj);
//Bind the interfaces to the linkset
linkset_interface_binding new_linkif_obj = new linkset_interface_binding();
new_linkif_obj.id = "LS/1";
new_linkif_obj.ifnum = "1/1/2 2/1/2";
linkset_interface_binding.add(ns_session,new_linkif_obj);
<!--NeedCopy-->
Python - Sample code to configure linksets
# Create a new linkset
new_linkset_obj = linkset()
new_linkset_obj.id = "LS/1"
linkset.add(ns_session, new_linkset_obj)
# Bind the interfaces to the linkset
new_linkif_obj = linkset_interface_binding()
new_linkif_obj.id = "LS/1"
new_linkif_obj.ifnum = "1/1/2 2/1/2"
linkset_interface_binding.add(ns_session, new_linkif_obj)
<!--NeedCopy-->
Configuring Admin Partitions
To create an admin partition, you must perform a set of operations on the default partition. To understand this procedure, let us consider a company that has two departments each of which has an application that requires the Citrix ADC functionality. The Citrix ADC admin wants to have a different partition for each department so that there is isolation of users and configurations. For detailed information and best practices, see Admin Partitions.
Creating an Admin Partition
While creating an admin partition, you must also specify the system resources that must be allocated to that partition.
-
Using REST APIs through HTTP
The following example creates an admin partition named partition-dept1.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nspartition
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"nspartition":
{
"partitionname":"partition-dept1",
"maxbandwidth":"10240",
"minbandwidth":"10240",
"maxconn":"1024",
"maxmemlimit":"10"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The following sample code creates an admin partition named partition-dept1.
Java - Sample code to create an admin partition
nspartition nspartitionObject = new nspartition();
nspartitionObject.set_partitionname("partition-dept1");
nspartitionObject.set_maxbandwidth(10240);
nspartitionObject.set_maxconn(1024);
nspartitionObject.set_maxmemlimit(10);
nspartitionObject.set_minbandwidth(1240);
base_response result = nspartition.add(nitroService, nspartitionObject);
<!--NeedCopy-->
.NET - Sample code to create an admin partition
nspartition nspartitionObject = new nspartition();
nspartitionObject.partitionname = "partition-dept1";
nspartitionObject.maxbandwidth = 10240;
nspartitionObject.maxconn = 1024;
nspartitionObject.maxmemlimit = 10;
nspartitionObject.minbandwidth = 1240;
base_response result = nspartition.add(nitroService, nspartitionObject);
<!--NeedCopy-->
Python - Sample code to create an admin partition
nspartitionObject = nspartition()
nspartitionObject.partitionname = "partition-dept1"
nspartitionObject.maxbandwidth = 10240
nspartitionObject.maxconn = 1024
nspartitionObject.maxmemlimit = 10
nspartitionObject.minbandwidth = 1240
result = nspartition.add(nitroService, nspartitionObject)
<!--NeedCopy-->
Associating Users with Partitions
Associate the appropriate users with the partition.
-
Using REST APIs through HTTP
The following example associates user1 to a partition named partition-dept1.
-
Request
HTTP Method:
PUT
URL:
http://<Citrix-ADC-ip-address(NSIP)>/nitro/v1/config/systemuser_nspartition_binding/user1
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"systemuser_nspartition_binding":
{
"username":"user1",
"partitionname":"partition-dept1"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The following sample code associates “user1” to a partition named “partition-dept1”.
Java - Sample code for associating user with partition
systemuser_nspartition_binding systemuser_nspartition_binding_object = new systemuser_nspartition_binding();
systemuser_nspartition_binding_object.set_partitionname("partition-dept1");
systemuser_nspartition_binding_object.set_username("user1");
base_response result = systemuser_nspartition_binding.add(nitroService, systemuser_nspartition_binding_object);
<!--NeedCopy-->
.NET - Sample code for associating user with partition
systemuser_nspartition_binding systemuser_nspartition_binding_object = new systemuser_nspartition_binding();
systemuser_nspartition_binding_object.partitionname = "partition-dept1";
systemuser_nspartition_binding_object.username = "user1";
base_response result = systemuser_nspartition_binding.add(nitroService, systemuser_nspartition_binding_object);
<!--NeedCopy-->
Python - Sample code for associating user with partition
systemuser_nspartition_binding_object = systemuser_nspartition_binding()
systemuser_nspartition_binding_object.partitionname = "partition-dept1"
systemuser_nspartition_binding_object.username = "user1"
result = systemuser_nspartition_binding.add(nitroService, systemuser_nspartition_binding_object)
<!--NeedCopy-->
Specifying Command Policy for Partition Users
Associate an appropriate command policy to the admin partition user.
-
Using REST APIs through HTTP
The following example associates the command policy partition-admin to user1.
-
Request
HTTP Method:
PUT
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/systemuser_systemcmdpolicy_binding/user1
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"systemuser_systemcmdpolicy_binding":
{
"username":"user1",
"policyname":"partition-admin",
"priority":"1"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The following sample code associates the command policy “partition-admin” to “user1”.
Java - Sample code to specify command policy for partition user
systemuser_systemcmdpolicy_binding binding_object = new systemuser_systemcmdpolicy_binding();
binding_object.set_username("user1");
binding_object.set_policyname("partition-admin");
binding_object.set_priority(1);
base_response result = systemuser_systemcmdpolicy_binding.add(nitroService,binding_object);
<!--NeedCopy-->
.NET - Sample code to specify command policy for partition user
systemuser_systemcmdpolicy_binding binding_object = new systemuser_systemcmdpolicy_binding();
binding_object.username = "user1";
binding_object.policyname = "partition-admin";
binding_object.priority = 1;
base_response result = systemuser_systemcmdpolicy_binding.add(nitroService,binding_object);
<!--NeedCopy-->
Python - Sample code to specify command policy for partition user
binding_object = systemuser_systemcmdpolicy_binding()
binding_object.username = "user1"
binding_object.policyname = "partition-admin"
binding_object.priority = 1
result = systemuser_systemcmdpolicy_binding.add(nitroService,binding_object)
<!--NeedCopy-->
Specifying the Admin Partition VLAN or Bridgegroup
Specify the VLANs or bridgegroups to be associated with the partition. This step ensures network isolation of the traffic. Traffic received on the interfaces of the VLAN or bridgegroup is isolated from the traffic of other partitions.
-
Using REST APIs through HTTP
The following example specifies a VLAN for an admin partition.
-
Request
HTTP Method:
PUT
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nspartition_vlan_binding/partition-dept1
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"nspartition_vlan_binding":
{
"partitionname":"partition-dept1",
"vlan":"2"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The following sample code specifies a VLAN for an admin partition.
Java - Sample Code to specify the VLAN
nspartition_vlan_binding nspartition_vlan_binding_object = new nspartition_vlan_binding();
nspartition_vlan_binding_object.set_vlan(2);
nspartition_vlan_binding_object.set_partitionname("partition-dept1");
base_response result = nspartition_vlan_binding.add(nitroService, nspartition_vlan_binding_object);
<!--NeedCopy-->
.NET - Sample code to specify the VLAN
nspartition_vlan_binding nspartition_vlan_binding_object = new nspartition_vlan_binding();
nspartition_vlan_binding_object.vlan = 2;
nspartition_vlan_binding_object.partitionname = "partition-dept1";
base_response result = nspartition_vlan_binding.add(nitroService, nspartition_vlan_binding_object);
<!--NeedCopy-->
Python - Sample code to specify the VLAN
nspartition_vlan_binding_object = nspartition_vlan_binding()
nspartition_vlan_binding_object.vlan = 2
nspartition_vlan_binding_object.partitionname = "partition-dept1"
result = nspartition_vlan_binding.add(nitroService, nspartition_vlan_binding_object)
<!--NeedCopy-->
Switching Partitions
If you are associated with multiple admin partitions, you can switch to the required partition.
-
Using REST APIs through HTTP
The following example shows how to switch from current partition to a partition named partition-dept2.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nspartition?action=Switch
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"nspartition":
{
"partitionname":"partition-dept2"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
The following sample code switches from current partition to a partition named “partition-dept2”.
Java - Sample code to switch partitions
nspartition nspartitionObject = new nspartition();
vnspartitionObject.set_partitionname("partition-dept2");
base_response result = nspartition.Switch(nitroService, nspartitionObject);
<!--NeedCopy-->
.NET - Sample code to switch partitions
nspartition nspartitionObject = new nspartition();
nspartitionObject.partitionname = "partition-dept2";
base_response result = nspartition.Switch(nitroService, nspartitionObject);
<!--NeedCopy-->
Python - Sample code to switch partitions
nspartitionObject = nspartition()
nspartitionObject.partitionname = "partition-dept2"
result = nspartition.Switch(nitroService, nspartitionObject)
<!--NeedCopy-->
Managing AppExpert Applications
The following sections talks about exporting and importing an AppExpert application using NITRO APIs.
Exporting an AppExpert Application
This topic covers exporting an AppExpert application by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To export an AppExpert application, specify the parameters needed for the export operation in the apptemplateinfo object. Optionally, you can specify basic information about the AppExpert application template, such as the author of the configuration, a summary of the template functionality, and the template version number, in the template_info object. This information is stored as part of the template file that is created.
For example, to export an AppExpert application named MyApp1.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/apptemplateinfo?action=export
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"apptemplateinfo":
{
"appname":"MyApp1",
"apptemplatefilename":"BizAp.xml",
"template_info":
{
"templateversion_major":"2",
"templateversion_minor":"1",
"author":"XYZ",
"introduction":"Intro",
"summary":"Summary"
}
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 OK
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
To export an AppExpert application, you must do the following:
-
Instantiate the com.citrix.netscaler.nitro.resource.config.app.application class.
Note.
For the python SDK, the package path is of the form nssrc.com.citrix.netscaler…… - Configure the properties of the AppExpert locally.
- Export the AppExpert application.
The following samples export an AppExpert application named MyApp1.
JAVA - sample code to export an AppExpert application
application myapp = new application();
myapp.set_appname("MyApp1");
myapp.set_apptemplatefilename("myapp_template");
application.export(ns_session,myapp);
<!--NeedCopy-->
.NET - sample code to export an AppExpert application
application myapp = new application();
myapp.appname = "MyApp1";
myapp.apptemplatefilename = "myapp_template";
application.export(ns_session,myapp);
<!--NeedCopy-->
Python - sample code to export an AppExpert application
myapp = application()
myapp.appname = "MyApp1"
myapp.apptemplatefilename = "myapp_template"
application.export(ns_session, myapp)
<!--NeedCopy-->
Importing an AppExpert Application
This topic covers importing an AppExpert application by using REST APIs through HTTP or SDKs.
-
Using REST APIs through HTTP
To import an AppExpert application, specify the parameters needed for the import operation in the apptemplateinfo object.
For example, to import an AppExpert application named MyApp1.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/apptemplateinfo?action=import
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"apptemplateinfo":
{
"apptemplatefilename":"BizAp.xml",
"deploymentfilename":"BizAp_deployment.xml",
"appname":"MyApp1"
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 OK
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
To import an AppExpert application by specifying different deployment settings.
-
Request
HTTP Method:
POST
URL:
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/apptemplateinfo?action=import
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"apptemplateinfo":
{
"apptemplatefilename":"BizAp.xml",
"appname":"Myapp2",
"deploymentinfo":
{
"appendpoint":
[
{
"ipv46":"11.2.3.8",
"port":80,
"servicetype":"HTTP"
}
],
"service":
[
{
"ip":"12.3.3.15",
"port":80,
"servicetype":"SSL"
},
{
"ip":"14.5.5.16",
"port":443,
"servicetype":"SSL"
}
]
}
}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 OK
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
-
Using REST APIs through SDKs
To import an AppExpert application, you must do the following:
-
Instantiate the com.citrix.netscaler.nitro.resource.config.app.application class.
Note
. For the python SDK, the package path is of the form nssrc.com.citrix.netscaler…… - Configure the properties of the AppExpert locally.
- Import the AppExpert application.
The following samples import an AppExpert application named MyApp1.
Java - sample code to import an AppExpert application
application myapp = new application();
myapp.set_appname("MyApp1");
myapp.set_apptemplatefilename("myapp_template");
application.Import(ns_session,myapp);
<!--NeedCopy-->
.NET - sample code to import an AppExpert application
application myapp = new application();
myapp.appname = "MyApp1";
myapp.apptemplatefilename = "myapp_template";
application.Import(ns_session,myapp);
<!--NeedCopy-->
Python - sample code to import an AppExpert application
myapp = application()
myapp.appname = "MyApp1"
myapp.apptemplatefilename = "myapp_template"
application.Import(ns_session, myapp)
<!--NeedCopy-->
Automate Citrix ADC Upgrade and Downgrade with a Single API
You can use the “install” API to automate not just installation, but also an upgrade or a downgrade of the build on a Citrix ADC appliance. You can specify a local or remote location for the build file.
-
Using REST APIs through HTTP
For example, the following information describes a downgrade to Citrix ADC release 10.5 build 46, using a local build file:
-
Request
HTTP Method:
POST
URL:
http://<NSIP>/nitro/v1/config/install
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue >
Content-Type: application/json
Request Payload:
{
“install”:
{
“url”: “file:///var/tagma/build_tagma_46_nc.tgz”
}
}
<!--NeedCopy-->
-
Response
HTTP status Code on Success:
201 Created
209 Citrix ADC specific warning
Note.
when “y” option is not specified and warning is enabled, API returns “1120 - The configuration must be saved and the system rebooted for these settings to take effect” message in X-NITRO-WARNING.
HTTP Status Code on Failure:
599 Citrix ADC specific error
-
Additional parameters available in the install API request payload
- “y”:“true” - This option enables reboot on successful loading of kernel.
-
“L”:“true” - This option enables the callhome feature.
Supported formats for the "url" parameter (specifies the location of the tar.gz file for the build)
- http://[user]:[password]@host/path/to/file
- https://[user]:[password]@host/path/to/file
- sftp://[user]:[password]@host/path/to/file
- scp://[user]:[password]@host/path/to/file
- ftp://[user]:[password]@host/path/to/file
-
file://path/to/file
-
Possible errors
- Installation failed. [No space on file system. Please check the log file /var/tmp/install]
- Installation failed. [File transfer failed]
- Installation failed. [File does not exist]
- Installation failed. [Failed to copy file to /var/tmp]
- Installation failed. [Extraction failed, invalid tar archive?]
- Installation failed. [Invalid file transfer protocol]
- Installation failed. [Unable to create temporary directory]
- Installation failed. [Please check the log file /var/tmp/install for more information]
Handle Multiple NITRO Calls in a Single Request
You can use the “macroapi” API to create, update, and delete multiple resources simultaneously, and thereby minimize network traffic. For example, multiple load-balancing virtual servers can be added in a single API.
To account for the failure of some operations within the bulk operation, NITRO allows configuring one of the following behaviors.
-
EXIT
. When the first error is encountered, execution stops. The commands that were executed before the error are committed. -
ROLLBACK
. When the first error is encountered, execution stops. The commands that were executed before the error are rolled back. Rollback is supported for add and bind commands only. -
CONTINUE
. All the commands in the request are executed even if some commands fail.
You must specify the behavior of the bulk operation in the request header, by using the X-NITRO-ONERROR parameter.
-
Advantages
Heterogeneous resources can be configured with a single API. For example, multiple load balancing virtual servers and multiple services can be created, and services can be bound to load balancing virtual servers in a single API.
-
Limitations
Only homogenous operation is supported in this API. For example, multiple load balancing virtual servers can be created but cannot be updated or deleted in the same API. “rollback” is supported only on “add” and “bind” operations.
-
Using REST APIs through HTTP
To add multiple load balancing resources in a single request:
-
Request
HTTP Method:
POST
URL:
http://<NSIP>/nitro/v1/config/macroapi
Request Headers:
Content-Type: application/json
Cookie: NITRO_AUTH_TOKEN=<tokenvalue>
X-NITRO-ONERROR: exit
Request Payload:
{
"lbvserver":[
{"name":"lbv1","servicetype":"http"},
{"name":"lbv2","servicetype":"http"}
],
"serviceGroup": [
{ "servicegroupname": "sg1", "servicetype": "HTTP" },
{ "servicegroupname": "sg2", "servicetype": "HTTP" }
],
"lbvserver_servicegroup_binding":[
{ "name":"lbv1", "servicegroupname":"sg1" },
{ "name":"lbv2", "servicegroupname":"sg2" }
]
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
201 Created for the add operation and 200 OK for the update operation.
HTTP Status Code on Failure:
207 Multi Status with error details in the response payload. For more information, see Error Handling.
For deleting multiple resources using macroapi, use POST HTTP method with query parameter “action=remove” in the URI.
Batch API support for NITRO calls
The batchapi
API can handle multiple NITRO calls in a single request and thereby minimize network traffic.
You can perform the following operations using batchapi
:
- You can use
batchapi
to create, update, and delete multipleheterogenous
resources simultaneously. - You can use
batchapi
to retrieve information of multiple heterogenous resources.
Note:
batchapi
allows you to perform different operations across the NITRO resources in the request. Whereasmacroapi
limits to the same operation.
To account for the failure of some operations within the bulk operation, NITRO allows configuring one of the following behaviors:
-
EXIT
. When the first error is encountered, execution stops. The commands that were executed before the error are committed. -
CONTINUE
. All the commands in the request are executed even if some commands fail.
Ignore specific error messages for command by specifying list of error messages to be ignored as part of key ignore_error_messages
.
Advantages of using Batch API
batchapi
works like batch command in CLI, wherein you can perform multiple operations in a single API. For example, you can add multiple load balancing virtual servers, update multiple services, delete multiple services in a single API.
batchapi
allows you to perform different operations across the NITRO resources in the request. Whereas the macroapi
API limits to the same operation.
Limitations
- ROLLBACK on failure is not supported.
-
GET
operation cannot be executed along with the config operations. -
batchapi
does not support the following operations:-
desiredState
API for servicegroup idempotent
bulkbindings
-
Configure features using batch API
You can use batchapi
to create, update, and delete multiple heterogenous
resources simultaneously.
Use following convention to specify the action to be performed on each command within batchapi
.
Operation to perform | Action key value |
---|---|
CREATE/POST/BIND | ADD |
UPDATE/PUT | SET |
REMOVE/DELETE/UNBIND | REMOVE |
Use the same keyword in the “action” field for non-CRUD operations. For example, enable, disable, link, unlink, and update operations.
The following batchapi
request:
- enables load balancing feature
- adds a load balancing virtual server
- adds a servicegroup
- binds the load balancing virtual server to the servicegroup
- updates load balancing monitor response code in a single request
Request components
Request field | Value |
---|---|
HTTP Method | POST |
URL | http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/batchapi |
Request Headers | Content-Type: application/json |
Request Payload | {“batchapi”:[ {“action”: “disable”, “type”: “nsfeature”, “properties”: {“feature”: [“lb”]}}, {“action”: “ADD”, “type”: “lbvserver”, “properties”: {“name”: “lbv1”, “servicetype”: “HTTP”}, “ignore_error_messages”: {“errorcode” : 273, “message” : “Resource already exists”}]}, { “action”: “ADD”, “type”: “servicegroup”, “properties”: {“servicegroupname”: “sg1”, “servicetype”: “HTTP”}}, { “action”: “ADD”, “type”: “lbvserver_servicegroup_binding”, “properties”: { “name”: “lbv1”, “servicegroupname”: “sg1”}}, { “action”: “ADD”, “type”: “sslcertKey”, “properties”: {“certkey”: “test_cert”,”cert”: “ns-root.cert”, “key”: “ns-root.key”}}, { “action”: “SET”, “type”: “lbmonitor”, “properties”: {“monitorname”: “http”, “type”: “HTTP”,”respcode”: [“201”]}} ]} |
Response components
The following lists the possible status codes returned for a batchapi
call used for configuring features:
-
HTTP Status Code on Success
: 201. -
HTTP Status Code on Failure
: 207 Multi Status with error details in the response payload. For more information, see Error and Exception Handling.
Retrieve configuration information using batch API
You can use batchapi
to retrieve information about multiple heterogenous resources.
Note:
Use either key
id
for sending unique identifier parameter value or useproperties
field to add unique identifier parameters (some resources have multiple unique identifier parameters).The following lists the query parameters that are supported in a
batchapi
show request:
filter
. Retrieves filtered information.view
. Retrieves summarized informationview=summary
count
. Retrieves only the count of resources ifcount=YES
attrs
. Retrieves information about the specified attributes.
Request components
The following request is an example to retrieve multiple resources in a single batchapi
request.
Request field | Value |
---|---|
HTTP Method | POST |
URL |
http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/batchapi?action=GET or http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/batchapi?action=SHOW
|
Request Headers | Content-Type: application/json |
Request Payload | { “batchapi”: [ { “type”: “lbvserver”, “id”: “lbv1”, “query_params” : {“attrs”: [“name”, “lbmethod”]} }, { “type”: “lbvserver”, “id”: “lbv1”, “query_params” : {“view”: “summary”} }, { “type”: “servicegroup”, “query_params” : {“count”: “YES”} }, { “type”: “lbvserver_servicegroup_binding”, “id”: “lbv1”, “query_params” : {“filter”: {“servicegroupname”: “sg1”}} }, { “type”: “admparameter” } ]} |
Response components
The following lists the possible status codes returned for a batchapi
call used for retrieving configuration information:
-
HTTP Status Code on Success
. 200 OK. -
HTTP Status Code on Failure
. 207 Multi Status with error details in the response payload. For more information, see Error and Exception Handling.
The sample response payload contains the information that was requested:
Response field | Value |
---|---|
Response payload | { “batchapi” : [ { “errorcode” : 0, “lbvserver” : [ { “lbmethod” : “LEASTCONNECTION”, “name” : “lbv1” } ], “message” : “Done”, “severity” : “NONE”}, { “errorcode” : 0, “lbvserver” : [ { “curstate” : “DOWN”, “effectivestate” : “DOWN”, “ipv46” : “0.0.0.0”, “lbmethod” : “LEASTCONNECTION”, “name” : “lbv1”, “port” : 0, “servicetype” : “HTTP”, “td” : “0” } ], “message” : “Done”, “severity” : “NONE” }, { “errorcode” : 0, “message” : “Done”, “servicegroup” : [ { “__count” : 1 } ], “severity” : “NONE” }, {“errorcode” : 0, “lbvserver_servicegroup_binding” : [ { “name” : “lbv1”, “servicegroupname” : “sg1”, “servicename” : “sg1”, “stateflag” : “536936463” } ], “message” : “Done”, “severity” : “NONE” }, { “admparameter” : { “admserviceconnect” : “ENABLED” }, “errorcode” : 0, “message” : “Done”, “severity” : “NONE” } ], “errorcode” : 0, “message” : “Done”, “severity” : “NONE” } |
Update service group with desired member set seamlessly using Desired State API
One of the most frequently modified configurations on a Citrix ADC appliance is service group member set. Depending on the scale requirements or runtime changes to application servers, the service group member configuration on the appliance must be updated. In large scale and dynamically changing deployments, there might be a delay in updating the appliance configuration.
Desired State API solves this problem by accepting the intended member set for a service group in a single API, thereby effectively updating the configuration. Using Desired State API, you can:
- Provide a list of service group members in a single PUT request on “servicegroup_servicegroupmemberlist_binding” resource.
- Provide their weight and state (optional) in that PUT request.
- Effectively synchronize the appliance configuration with deployment changes around application servers.
The Citrix ADC appliance compares the requested desired member set with the configured member set. Then, it automatically binds the new members and unbinds the members that are not present in the request.
To enable graceful unbind of the service group members, set the autodisablegraceful
and autodisabledelay
parameters on the service group resource. When these parameters are set, the members are unbound gracefully as specified in the configuration and not immediately. For more information on graceful unbind, see Configure a desired set of service group members for a service group in one NITRO API call.
Advantages of Desired State API
The following are some of the advantages of using the Desired State API.
- Better performance because a single API is used to bind and unbind multiple service group members.
- Desired State API is better than macroapi for service group member changes, as one can perform only either bulk bind or bulk unbind but not both in single macroapi API.
- Also, Desired State API implementation is driven inside the Citrix ADC Packet Engine which enhances performance.
- Synchronize deployment changes to Citrix ADC appliance in large scale deployments, such as Cloud Native deployments.
In large scale and highly dynamic deployments (for example Kubernetes, OpenShift, Pivotal), the challenge is to keep the appliance configuration up-to-date with the rate of change of deployments to accurately serve the application traffic.
In such deployments, controllers (Ingress or E-W Controller) are responsible for updating ADC configuration. In Kubernetes, whenever there are changes to deployment, kube-api server sends the effective set of endpoints through ‘Endpoints event’ to the controller. The controller uses the Read-Delta-Modify approach where it performs the following:
-
Fetches the currently configured endpoint set (service group member set of a service group) for the service undergoing the change from ADC appliance.
- Compares the configured endpoint set with the set in the received event.
- Binds the new endpoints (service group members), or unbinds the deleted endpoints.
Because the rate of change and the size of services is high in this environment, this configuration method is not efficient and might delay configuration updates.
Notes:
- Support for Desired State API is available only for HA deployments.
- Support for Desired State API within macroapi is supported from release Citrix ADC 13.0 build 52.24.
- Desired State API within macroapi does not support rollback operation.
- The service group on which Desired State API is being used must have the Autoscale parameter set to “API.” Otherwise, Desired State NITRO API returns the “Operation not permitted” error.
- You can only bind IP address based services using Desired State API, Domain Name based services are not allowed.
Payloads
Request
HTTP Method:
PUT
Request Headers:
Content-Type: application/json
Cookie: NITRO_AUTH_TOKEN=<tokenvalue>
URL: http://<nsip>/nitro/v1/config/servicegroup_servicegroupmemberlist_binding/activesvcgrp
Request Payload:
{
"servicegroup_servicegroupmemberlist_binding":
{
"servicegroupname":"activesvcgrp",
"members":
[
{ "ip":"10.112.123.17", "port":80, "weight":1},
{ "ip":"10.112.123.18", "port":8080, "weight":1},
{ "ip":"10.112.123.19", "port":80, "weight":1}
]
}
}
<!--NeedCopy-->
Response
Success Case:
Headers:
HTTP/1.1 200 Ok
Payload:
NULL
Failure Case
Headers:
HTTP/1.1 207 Multi Status
Payload:
If there are validation failures, NITRO API returns an error with message indicating the problem with the request payload. For example,
{
"errorcode": 1110,
"message": "Invalid IP address [127.0.02]",
"severity": "ERROR"
}
<!--NeedCopy-->
If there are runtime failures (for example memory allocation failures), the ADC appliance might not be able to create all the desired member sets. In such cases, the NITRO API returns an error with failedmembers
parameter listing the set of members which are not created. The recommendation is to retry the operation after some timeout. If the error persists, check the appliance memory and take action accordingly.
{
“errorcode”:1442,
“message”: “Failed to bind some servicegroup members”,
“severity”: “ERROR”,
“servicegroupmember_servicegroupmemberlist_binding”:
{
“servicegroupname”:”foo”,
“failedmembers”:
[
{ "ip":"10.112.123.17", "port":8080, "weight":1},
{ "ip":"10.112.123.19", "port":80, "weight":1}
]
}
}
<!--NeedCopy-->
Simplify Management Operations with an Idempotent API
You can add or update Citrix ADC resources seamlessly, with a single API. Previously, an attempt to add a resource that was already configured, or to update a resource that was not yet configured, caused an error.
If you enable the “idempotent” query parameter (“idempotent=yes”) in any POST request, NITRO executes the request in an idempotent manner. An idempotent HTTP method is an HTTP method that can be called many times without different results, and POST is desinged as a non-idempotent method.
Note.
Use POST request with “idempotent” option if you are unsure whether the resource in the request exists on Citrix ADC or not.
This API hides the inconsistencies between parameter lists of POST and PUT operations. For some NITRO resources, certain parameters are accepted only on PUT not in POST, or vice versa. By using this idempotent API, you can overcome such challenges.
-
Limitations
If a resource is already configured and you try to add the same resource again, the resource is “updated,” but the arguments already present are not unset. For example, if a load balancing virtual server named “V1” is configured to use the round robin load balancing method, and you try to ADD an lbvserver named “V1” without specifying a value for “lbmethod” in the request, the Citrix ADC appliance does not unset “lbmethod” to its default value of “leastconnection.”
-
Using REST APIs through HTTP
In the following example, “preferredntpserver” is allowed only in PUT, but when given in POST request with idempotent=yes, NITRO internally adds the ntpserver and updates it with given properties.
-
Request
HTTP Method:
POST
URL:
http://<NSIP>/nitro/v1/config/ntpserver?idempotent=yes
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type: application/json
Request Payload:
{
“ntpserver”:{“servername”:“ntp1”,“minpoll”:“4, “preferredntpserver”: “yes”}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 OK
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
Retrieve Bindings in Bulk
This topic covers retrieving bindings information in bulk by using REST APIs through HTTP.
-
Using REST APIs through HTTP
You can use a bulk GET API to fetch bindings of all the entities of a given entity type.
For example, you can fetch bindings of all the load balancing virtual servers in one call instead of by using multiple GET by “name” calls. In the examples below, the Citrix ADC appliance has the following configuration.
- add lb vserver lbv1 http
- add lb vserver lbv2 http
- add service svc1 10.20.30.40 http 80
- add servicegroup sg1 http
- bind lb vserver lbv1 svc1
- bind lb vserver lbv1 sg1
- bind lb vserver lbv2 svc1
- bind lb vserver lbv2 sg1
Example - To fetch bindings of all lbvservers, in a single NITRO API
-
Request
HTTP Method:
GET
URL:
http://<NSIP>/nitro/v1/config/lbvserver_binding?bulkbindings=yes
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Accept: application/json
-
Response
HTTP Status Code on Success:
200 OK
HTTP Status Code on Failure:
4xx <string> (for general HTTP errors) or 5xx <string> (for Citrix-ADC-specific errors). The response payload provides details of the error.
Response Header:
Content-Type:application/json
Response Payload:
{
"errorcode":0,
"message":"Done",
"severity":"NONE",
"lbvserver_binding":[
{
"name":"lbv1",
"lbvserver_service_binding":[
{
"name":"lbv1",
"servicename":"svc1",
"stateflag":"536936451",
"ipv46":"10.20.30.40",
"port":80,
"servicetype":"HTTP",
"curstate":"DOWN",
"weight":"1",
"dynamicweight":"0",
"cookieipport":"",
"vserverid":"mcw1",
"vsvrbindsvcip":"10.20.30.40",
"vsvrbindsvcport":80,
"preferredlocation":""
}
],
"lbvserver_servicegroup_binding":[
{
"name":"lbv1",
"servicegroupname":"sg1",
"stateflag":"536936464",
"servicename":"sg1"
}
]
},
{
"name":"lbv2",
"lbvserver_service_binding":[
{
"name":"lbv2",
"servicename":"svc1",
"stateflag":"536936451",
"ipv46":"10.20.30.40",
"port":80,
"servicetype":"HTTP",
"curstate":"DOWN",
"weight":"1",
"dynamicweight":"0",
"cookieipport":"",
"vserverid":"mcw2",
"vsvrbindsvcip":"10.20.30.40",
"vsvrbindsvcport":80,
"preferredlocation":""
}
],
"lbvserver_servicegroup_binding":[
{
"name":"lbv2",
"servicegroupname":"sg1",
"stateflag":"536936464",
"servicename":"sg1"
}
]
}
]
}
<!--NeedCopy-->
Example - To fetch only “service” bindings of all lbvservers
-
Request
HTTP Method:
GET
URL:
http://<NSIP>/nitro/v1/config/lbvserver_service_binding?bulkbindings=yes
Request Header:
Content-Type:application/json
-
Response
Response Payload:
{
"errorcode":0,
"message":"Done",
"severity":"NONE",
"lbvserver_service_binding":[
{
"name":"lbv1",
"servicename":"svc1",
"stateflag":"536936451",
"ipv46":"10.20.30.40",
"port":80,
"servicetype":"HTTP",
"curstate":"DOWN",
"weight":"1",
"dynamicweight":"0",
"cookieipport":"",
"vserverid":"mcw1",
"vsvrbindsvcip":"10.20.30.40",
"vsvrbindsvcport":80,
"preferredlocation":""
},
{
"name":"lbv2",
"servicename":"svc1",
"stateflag":"536936451",
"ipv46":"10.20.30.40",
"port":80,
"servicetype":"HTTP",
"curstate":"DOWN",
"weight":"1",
"dynamicweight":"0",
"cookieipport":"",
"vserverid":"mcw2",
"vsvrbindsvcip":"10.20.30.40",
"vsvrbindsvcport":80,
"preferredlocation":""
}
]
}
<!--NeedCopy-->
View Individual Counter Information
This topic viewing individual counter information by using REST APIs through HTTP.
-
Using REST APIs through HTTP
To view global counters that are not otherwise shown by the Citrix ADC CLI or the GUI, you can now use the following URL format.
URL
: http://<NSIP>/nitro/v1/stat/nsglobalcntr?args=counters:<counter1>;<counter2>
Previously, these counter values could be viewed only through the “nsconmsg” Shell command.
Note.
You can view only global counters of type ULONG and only up to 12 counters in a single request.
-
Example
This example shows how to view the individual counters http_tot_Requests and http_tot_Responses. Enter the details in the system or tool that you are using to generate HTTP or HTTPS requests.
-
Request
HTTP Method:
GET
URL:
http://<NSIP>/nitro/v1/stat/nsglobalcntr?args=counters:http_tot_Requests;http_tot_Responses
Response
{
"errorcode": 0,
"message": "Done",
"severity": "NONE",
"nsglobalcntr":
{
"http_tot_Requests": "5783",
"http_tot_Responses": "5783"
}
}
<!--NeedCopy-->
Prevent XSS and CSRF Attacks by Disabling Basic Authentication
As an administrator or a root user, you can now prevent users from making API calls after using basic authentication (such as one-time credentials) to log on. You can use this feature to prevent Cross-Site Scripting (XSS), Cross-Site Request Forgery (CSRF), and other types of attacks.
-
Procedure for Disabling Basic Authentication
Use the following formats to enter the details in the system or tool that you are using to generate HTTP or HTTPS requests.
-
Using REST APIs through HTTP
-
Request
URL:
http://<Citrix-ADC-ip-address(NSIP)>/nitro/v1/config/systemparameter
-
HTTP Method:
PUT
Request Headers:
Cookie:NITRO_AUTH_TOKEN=<tokenvalue>
Content-Type:application/json
Request Payload:
{
"systemparameter":{ "basicauth":"disabled",}
}
<!--NeedCopy-->
-
Response
HTTP Status Code on Success:
200 OK
After you disable the basic authentication, access to Citrix ADC through the one-time password is denied and an error message is displayed.
-
Example
This example shows what happens if you make any API call after basic authentication has been disabled.
-
Request
HTTP Method:
GET
After you make a GET call, the a logon screen appears. If you click Log In
after entering the logon credentials, then you get the following response, which shows an error message.
Response
{"errorcode": 1244,"message": "Authentication Failed: Use of Basic Authentication is Disabled.","severity": "ERROR"
}
<!--NeedCopy-->
In this article
- Managing a Citrix ADC Cluster
- Configuring Admin Partitions
- Managing AppExpert Applications
- Automate Citrix ADC Upgrade and Downgrade with a Single API
- Handle Multiple NITRO Calls in a Single Request
- Batch API support for NITRO calls
- Update service group with desired member set seamlessly using Desired State API
- Simplify Management Operations with an Idempotent API
- Retrieve Bindings in Bulk
- View Individual Counter Information
- Prevent XSS and CSRF Attacks by Disabling Basic Authentication