NetScaler NITRO and REST

 NetScaler NITRO and REST

Last Updated: [last-modified] (UTC)

 

NetScaler uses an API that Citrix like to call NITRO. For the most part, this is just a normal REST interface. We’re going to have a look at how to get started with REST on the NetScaler. I’m going to assume that you’re running NetScaler 10.5 or later.

NITRO gets its fancy name as it also includes extra libraries for Java, .NET, and Python. The documentation states that you need to download the NITRO package. But this is only true if you want to use these libraries.

For this article, we’re only going to look at simple REST queries through Postman. So, the extra libraries are not needed for what we’re doing here.

 

Need a quick refresher on HTTP and REST?

[maxbutton id=”4″ text=”HTTP” url=”https://networkdirection.net/HTTP+Protocol”][maxbutton id=”4″ text=”REST” url=”https://networkdirection.net/REST+API”]

 

 

The API documentation is at http://docs.citrix.com/zh-cn/netscaler/11/nitro-api/nitro-rest/api-reference.html. It’s a good idea to have the documentation available while going through this article.

All NITRO operations are logged to /var/log/nitro.log, so this is the first place to look if you run into any trouble.

 

 

Authentication

Each request needs you to be authenticated. There are two ways you can do this:

  • Use headers to send a username and password with every request
  • Create a session, and pass the token with each request

Both of these options mean passing the username and password to the NetScaler, so be sure to use HTTPS.

Header Authentication

To authenticate with each request, add the following headers to the request.

Header Value
X-NITRO-User Username
X-NITRO-PASS Password
Content-Type application/json

Test this by sending a GET to https://x.x.x.x/nitro/v1/stat. If this has worked, the NetScaler will return status code 200, and a message body.

Session Authentication

To use session authentication, you need to POST a request to https://x.x.x.x/nitro/v1/config/login. This request should contain the Content-Type header, with a value of application/json.

The request should also include the message body, as shown below.

If successful, the NetScaler will return status 201 Created, a message body, and a cookie. Both the message body and the cookie contain the token.

JSON Payload (Log In)
{ 
    "login": 
    { 
        "username":"USER", 
        "password":"PASS",
        "timeout":600
    } 
}

You must send the token with each request. To do this, include the Cookie header, with the value NITRO_AUTH_TOKEN=token. Here, ‘token‘ is the string that you retrieved from the message body when creating the session.

To log out, repeat the logon process, but with the message body below. Remember to include the session token in this request.

If this is successful, the NetScaler will return 201 Created. It will also return a Set-Cookie header, showing that the deletion of the session.

JSON Payload (Log Out)
{ 
    "logout":{} 
}

Resources

There are two base URL’s for accessing the NetScaler:

  • https://x.x.x.x/nitro/v1/config/ for configuring the NetScaler
  • https://x.x.x.x/nitro/v1/stat/ for retrieving statistics

Remember to send a Content-Type header and your authentication information.

In the NITRO documentation, there is a list of resources you can access. For example, for load balancing, you may want to access lbvserver. You can do this with https://x.x.x.x/nitro/v1/config/lbvserver for configuration, or https://x.x.x.x/nitro/v1/stat/lbvserver for statistics.

If you request load balancer configuration with a GET, you will get a list of load balancers by name. If you have a load balancer called WebLB, you can access this directly at https://x.x.x.x/nitro/v1/config/lbvserver/WebLB.

If you want to make configuration changes, send a POST to the URL instead.

Example – Save NetScaler Config

Check Status

First, check if the running config, needs saving. Send a GET to https://x.x.x.x/nitro/v1/config/nsconfig.

The NetScaler will send a message body in response. See if configchanged is set to true. If it is, the config needs to be saved.

Save Config

To save the config, set the message body as below, and POST it to https://x.x.x.x/nitro/v1/config/nsconfig?action=save. Remember to send authentication details, and the Content-Type header.

If this is successful, the NetScaler returns 200 OK.

JSON Payload (Save Config)
{ 
    "nsconfig": 
    {} 
}

References

Citrix – Nitro API

Citrix – REST Web Services

 

Leave a Reply