Mick Hilhorst 's Tech Blog

It feel like the Citrix ADC Nitro API does not get utilized (or promoted for that matter) far enough in our current IT environments. It’s a great API that enables you to automate many difficult and tedious tasks.

My “Turbo ADC” application is written in Python to help IT admins out with their ADC’s. This process sparked the idea that I should probably blog about it, and maybe set you on your way to writing your own first script or application. It’s tons of fun, really!

Introduction

First, let me introduce you to the Nitro API. As Citrix puts it in their own documentation:

The Citrix ADC NITRO protocol allows you to configure and monitor the Citrix ADC appliance programmatically by using Representational State Transfer (REST) interfaces. Therefore, NITRO applications can be developed in any programming language. Additionally, for applications that must be developed in Java or .NET or Python, NITRO APIs are exposed through relevant libraries that are packaged as separate Software Development Kits (SDKs).

Any language, how cool is that! In this blog, we will be setting up Powershell to help you start writing your own first script and or application :).
You can use any IDE, but for familiarity I will be using the Powershell ISE.
Before we start we need to import the Nitro API Powershell SDK.
You might wonder what the difference is between the API and the SDK.
In short, with the API you work with webrequests and the SDK makes that easier for you.

Without the SDK (source: Citrix), we would need to take care of all this:

Method: tell NITRO what you want to do. Whether you want to retrieve data (GET), add new data (POST), update existing data (PUT) or delete data (DELETE)

URL: specifies NetScaler IP address, whether you address the NetScaler configuration or statistical data, which resource type you want to address and gives you the additional option to specify a resource name or the action you want to perform.

Request Header: provides NITRO with meta data, like the content type for the request body.

Request Body: sends the actual information to NITRO, preferably using a JSON formatted payload

With the SDK, it looks like this:

nitrosession = new-object com.citrix.netscaler.nitro.service.nitro_service($nsip,”http”)
$session = $nitrosession.login($user,$pass)

Installing/importing the Powershell Nitro SDK

You can find the SDK’s in your ADC.
Just login to the GUI and browse to ‘Downloads -> Nitro API samples for Powershell’.
Please note that there are different API versions, based on your ADC major release the version might differ.
The latest at the time of writing is the 13.1 version and is that is also the version used in this blog.

If the download presents you with an error like below, use WinSCP instead and browse to /var/netscaler/gui/nitro-powershell.tgz

Open up the downloaded .TGZ. The contents should look like this:

We will need the ‘lib’ folder. This folder contains two .dll files. You can simply copy the lib folder to your script location.
Keep in mind that anybody using your script will also need to have these two lib files, so it would be wise to package them with your script.

I highly recommend also checking out the ‘Sample’ folder as it contains a couple of interesting examples.
Word of advice, don’t run any scripts of production ADC’s. The ‘myfirstnitroapplication.ps1’ clears and saves your ADC configuration for example.
While not having ran the script on a production ADC, I speak from the experience of my development ADC being wiped :- ).

First Script

Alright, so create a .ps1 file and make sure you have the following directory structure:
-lib (including DLL’s)
-script.ps1

Now open up the .ps1 and lets start scripting.
We will need to start with creating the references to the DLL’s.

That’s it! Now we can utilize all the great stuff they have to offer.
Before we can actually run any code, we need to make sure we are logged in to the ADC.
I’m keeping the script very simple for tutorial purposes, make sure to implement actual code with try and catch, hashed password etc.

For the login bit, we will need to provide a couple of variables.
-Username
-Password
-Nsip
-protocol (http/https)

Then, after we have submitted the login, we want to know if it is succesful. We can check this with the .isLogin() boolean.

Now with the login done, we can do do all the stuff we want on the ADC with the $nitrosession variable to handle the authentication.

Lets create a simple example, we want to retrieve the lb_vservers currently on the ADC.
You can view all the possibilities in the Citrix documentation of the Nitro API here.

We need to start by creating another reference to the object type.
This can take a little bit of getting used to, but luckily auto-completion guides us.
We want to select the LB services, as we want to do something regarding to loadbalancing.

Then we want to refer to the loadbalancing virtual servers, so we choose this option:

Play around with the auto completion for a bit to get a feel of all the possibilities.
Like I said already, it can take a bit of getting used too.

One of the brilliant minds in our field, Esther Barthel, has also created a nice powershell module to help out with this. Please do consider checking it out.

In the end, we declared this:
1.The module type
2.The action (get/update/delete)
3.The reference to our session
4.The name of the lb_vserver we want to use

Brilliant, now lets print out the name and service type of this object:

I think this should be enough to help you on your way with the Powershell SDK.
In my opinion the Powershell documentation is the least attractive as there is very little.
Be sure to checkout the examples, you might notice that my explanation is based on that too :).

Any questions? Always feel free to reach out.
Happy scripting!


Full script:

#Load DLL
$path = "$PSScriptRoot\lib\nitro.dll"
[System.Reflection.Assembly]::LoadFile($path)

#Load DDL
$path2 = "$PSScriptRoot\lib\Newtonsoft.Json.dll"
[System.Reflection.Assembly]::LoadFile($path2)

#Define variables for login
$nsip = "192.168.176.106"
$username = "nsroot"
$password = "nsroot1"
$protocol = "http"


#Create instance that takes care of login
$nitrosession = new-object com.citrix.netscaler.nitro.service.nitro_service($nsip,$protocol)
#Login to earlier instance and save that to a variable
$session = $nitrosession.login($username,$password)
#write to console if login is succesful. 
write-host $nitrosession.isLogin()

#Refer to the lbvserver module in the SDK and create an object
$result = [com.citrix.netscaler.nitro.resource.config.lb.lbvserver]::get($nitrosession,"lb_PowershellExample");
Write-Host "The name is: " $result.name " And it uses the following servicetype " $result.servicetype;