in php

Using PHP with the Nitro REST API

As a dedicated NetScaler fan and having some background in programming and scripting, I was looking for a way to start using the Nitro API, after attending a NetScaler MasterClass and reading some articles about it.

But what I found is that there were plenty of examples on how to achieve this on either Perl or Python, but I couldn’t find a simple PHP code snippet. Being a great PHP fan, PHP is my preferred weapon of choice if you will.

So I took it upon me to figure this out by trial and error. And now having achieved a way to access the NetScaler’s Nitro REST API through the means of PHP with the cURL extension.

In the code I will be showing you in just a second, bear in mind that this is just a simple example code, no classes, no functions and no error handling. I am a firm believer in the KISS principle for a getting started tutorial, so I act on it as well.

The most challenging part of this for me was to, a) set the custom request headers and b) after logging in, retrieve the necessary Nitro Auth Token and use this cookie in the successive Nitro calls.

Enough said, lets lay out some code.
Here are the pre-requisites to use this code:

  • A (preferably Linux) server running Apache2.
  • PHP5 with the cURL extension loaded.
  • The code editor of your choice.
  • A NetScaler.
  • Coffee or tea, whatever you fancy.

I myself used a Ubuntu 14.01 LTS server running on VMWare Fusion, connecting to a NetScaler VPX 10.5, also running on VMWare Fusion.

What are we going to achieve after this tutorial? Well, it consists mainly of four parts:

  1. Setting global variables to work with.
  2. Logging into the NetScaler and obtain the Nitro Auth Token.
  3. Perform a “stat” command and display the output on the screen.
  4. Logout and clean up.

Right, let’s dive in.

1.  Defining global variables

For this tutorial I am using the default username and password, be sure to change this to some correct username and password. Also, be sure to set the $nitroNSIP variable and point this to the NetScaler IP Address of your instance.

2. Logging into the NetScaler

First, I will be setting some more variables, derived from the official documentation:

After this we start to get to work with cURL:

So what I am doing here is first, initialise the URL that was passed on by the variable to login. After that I am setting various cURL options to be able to receive the correct output in order to filter out the Nitro Auth Token for instance. I am also setting the custom request header and the data, or the payload if you will. And lastly, defining what type of request this is.

Once we have that set, we can then let PHP execute the cURL command(s):

Right, now we have the output of the cURL command in our variable, the next step would be to extract the Nitro Auth Token, which we will need in every successive cURL connection we make. So first, I retrieved all cookies that were in the variable and stored them in an array:

After examining the output (by means of a simple var_dump($cookies) it was clear what name the Nitro Auth Token was using, so I extracted that cookie and stored it in a separate variable to use later on:

And after that, we simply close the cURL connection:

And there we have it, if everything went well, you’re now logged into the NetScaler. Moving on to the next step.

3. Performing a “stat” command

Now that we are logged in, lets set the next bunch of variables and cURL options, just like we did in the previous step, only this time, it will be customised for issuing a “stat” command:

In this case I wanted to get all of the statistics on the Network Interfaces. See how we’re using the previously captured Auth Token in the header? After this, we can execute the cURL command and output this on the screen and closing the cURL connection once more:

There, if all went well, you should be presented an array containing all information there is to know about your NetScaler NIC’s. So that leaves us only with one thing left to do in this tutorial….

4. Logout and clean up

Right, we’ll start up just like we did in the previous two steps by setting our variables and our cURL options:

Here we see one slight difference and that is, that while setting the CURLOPT_HTTPHEADER, I specify two array members, one being the Nitro Auth Token and the other being the request header needed for logging out. Then we initialise cURL just like before.

Then we can execute the cURL command, close the command and unset the Nitro Auth Token variable that is now invalid, due to the logging out process:

And there we have it, we’re all done.

As I mentioned earlier, this is just a “getting started” tutorial, I deliberately refrained from putting too much code in like error handling or database connections, I have kept it in the simplest form that I know of. But one can hopefully imagine how one could streamline this further, take it to the next level and perhaps put all of the different requests, URL’s, headers and payload in a MySQL table and make it even more dynamic.

If you have any questions or remarks, please feel free to contact me.

Regards,

Chris

What do you think?

Comment

  1. Very Good Chris.

    Are you able to provide an example POST request. I have been trying to add a a server using the above as a base for the last two hours without success!

    Thanks.

    • Hi John,

      Yes, here is an example POST request:
      object={
      "lbvserver":{
      "name":"Nitro vServer",
      "servicetype":"HTTP",
      "ipv46": "7.7.7.7",
      "port": "80",
      }}

      You would put this in an anrray and send it to: http://nsip_of_netscaler/nitro/v1/config/

      The response you would get, would be:
      Array
      (
      [errorcode] => 0
      [message] => Done
      [severity] => NONE
      )

      Then, the following action has happened on the NetScaler:
      Info : Command: add lb vserver "Nitro vServer" HTTP 7.7.7.7 80 -range 1 -timeout 2 -backupPersistenceTimeout 2 -lbMethod LEASTCONNECTION -rule none -Listenpolicy none -resRule none -persistMask 255.255.255.255 -v6persistmasklen 128 -pq OFF -sc OFF -m IP -sessionless DISABLED -state ENABLED -connfailover DISABLED -cacheable NO -soMethod NONE -soPersistence DISABLED -soPersistenceTimeOut 2 -healthThreshold 0 -redirectPortRewrite DISABLED -downStateFlush ENABLED -IPMapping 0.0.0.0 -disablePrimaryOnDown DISABLED -insertVserve Authorization Status: authorized Result: successful User: username

      Good luck and have fun 🙂

      Regards,
      Chris

  2. Hi Chris
    awesome. I want to enable / disable a service by using REST API. How I can achieve it? What will be the posting variables?

    Thanks in advance!

    Thanks

  3. here is a sample code which I am using

    $nitroUrl = “http://IP/nitro/v1/config/”;
    $nitroReq = “POST”;
    //$nitroData = ‘{“lbvserver”:{“name”:”‘.$server.'”,”state”:”‘.$state.'”}}’;

    $nitroData1 = ‘{“params”:{“action”:”enable”},”server”:{“name”:”‘.$server.'”}}’;

    $nitroHeader = “Cookie:NITRO_AUTH_TOKEN=$authToken”;

    // Initialize and set cURL options
    $ch = curl_init($nitroUrl);
    curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
    curl_setopt($ch, CURLOPT_HTTPHEADER,array($nitroHeader));
    curl_setopt($ch, CURLOPT_POSTFIELDS, $nitroData1);
    curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $nitroReq);

    // Execute the cURL command and put it into a variable
    $result1 = curl_exec($ch);

    but I am getting following error

    {“errorcode”:-1,”message”:”Invalid POST request”,”severity”:”ERROR”}

    Please assist.