Product Documentation

Connecting to the NetScaler Appliance

Jun 14, 2016

The first step towards using NITRO is to establish a session with the NetScaler appliance and then authenticate the session by using the NetScaler administrator's credentials. You must specify the username and password in the login object. The session ID that is created must be specified in the request header of all further operations in the session.

Note:
  • You must have a user account on the appliance to log on to it. The configuration operations that you can perform are limited by the administrative roles assigned to your account.
  • To ensure secure communication, use the HTTPS protocol in NITRO requests.
  • Instead of creating a NITRO session, you can logon to the NetScaler appliance while performing individual operations. To do this, you must specify the username and password in the request header of the NITRO request as follows:
    X-NITRO-USER:<username> 
    X-NITRO-PASS:<password> 
    Content-Type:application/vnd.com.citrix.netscaler.lbvserver+json
    
For example, to connect and create a session with a NetScaler appliance with NSIP address 10.102.29.60 by using the HTTP protocol:
  • Request:

    HTTP Method
    POST
    URL
    http://10.102.29.60/nitro/v1/config/login
    Request Headers
    Content-Type:application/vnd.com.citrix.netscaler.login+json
    
    Request Payload
    { 
        "login": 
        { 
            "username":"<username>", 
            "password":"<password>" 
        } 
    }
    
  • Response:

    HTTP Status Code on Success
    201 Created
    HTTP Status Code on Failure
    4xx <string> (for general HTTP errors) or 5xx <string> (for NetScaler-specific errors). The response payload provides details of the error.
    Response Header
    Set-Cookie: 
    NITRO_AUTH_TOKEN=<tokenvalue>;  
    path=/nitro/v1
    

Modifying the Session Timeout

You can modify the timeout period by specifying a new timeout period (in seconds) in the login object. For example, to modify the timeout period to 60 minutes:

{ 
    "login": 
    { 
        "username":"<username>", 
        "password":"<password>", 
        "timeout":"3600" 
    } 
}
Some points to note with regards to session timeout for NetScaler 10.5 and later versions:
  • When restricted timeout param is enabled, NITRO, by default, uses the timeout value that is configured for the logged in user. You can customize this value but it must be limited to the value specified for the user. If no value is specified for the user, the default timeout value of 15 minutes is used.
  • When restricted timeout param is not enabled, NITRO uses the default value of 30 minutes as session timeout.