Performing Basic Citrix ADC Operations

This section covers procedures for performing the following basic Citrix ADC operations using NITRO APIs.

• Log on to a Citrix ADC Appliance
• Log on to a Citrix ADC appliance that has two factor authentication configured for system users
• Enable Citrix ADC Features and Modes
• Save Citrix ADC Configurations
• Kill a system Session
• Disconnect from the Citrix ADC Appliance

Log on to a Citrix ADC Appliance

The first step towards using NITRO is to establish a session with the Citrix ADC appliance and then authenticate the session by using the Citrix ADC administrator’s credentials.

Some points to note with regards to session timeout:

• 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.

• Using REST APIs through HTTP

  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.

Notes:

• 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 log on to the Citrix ADC 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/json

For example, to connect and create a session with a Citrix ADC 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/json

Request Payload:

{
    "login":
    {
    "username":"admin",
    "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.

Response Header:

Set-Cookie:NITRO_AUTH_TOKEN=<tokenvalue>;
path=/nitro/v1
<!--NeedCopy-->

• Using REST APIs through SDKs

  You must create an object of the com.citrix.netscaler.nitro.service.nitro_service class by specifying the Citrix ADC IP (NSIP) address and the protocol to connect to the appliance (HTTP or HTTPS). You then use this object and log on to the appliance by specifying the user name and the password of the Citrix ADC administrator.

Note:

• For the python SDK, the package path is of the form nssrc.com.citrix.netscaler…
• You must have a user account on that appliance. The configuration operations that you perform are limited by the administrative roles assigned to your account.

The following sample code establishes a session with a Citrix ADC appliance with IP address 10.102.29.60 by using the HTTPS protocol and also sets a session timeout period (in seconds) of 60 minutes.

Java - Sample code to establish session

//Specify the Citrix ADC appliance IP address and protocol
nitro_service ns_session = new nitro_service("10.102.29.60","https");

//Specify the login credentials
ns_session.login("admin","verysecret",3600);
<!--NeedCopy-->

.NET - Sample code to establish session

//Specify the Citrix ADC appliance IP address and protocol
nitro_service ns_session = new nitro_service("10.102.29.60","https");

//Specify the login credentials
ns_session.login("admin","verysecret",3600);
<!--NeedCopy-->

Python - Sample code to establish session

# Specify the Citrix ADC appliance IP address and protocol

ns_session = nitro_service("10.102.29.60","https")

# Specify the login credentials

ns_session.login("admin","verysecret",3600)
<!--NeedCopy-->

Disable SSL Checks

When using HTTPS, you must make sure that the root CA is added to the truststore. By default, NITRO validates the SSL certificate and verifies the hostname.

• Using REST APIs through SDKs

  Disable these validations as shown in the following sample codes.

Java - Sample code for disabling SSL checks

ns_session.set_certvalidation(false);
ns_session.set_hostnameverification(false);
<!--NeedCopy-->

.NET - Sample code for disabling SSL checks

ns_session.certvalidation = false;
ns_session.hostnameverification = false;
<!--NeedCopy-->

Python - Sample code for disabling SSL checks

ns_session.certvalidation = false
<!--NeedCopy-->

Log on to a Citrix ADC appliance that has two factor authentication configured for system users

Two factor authentication is a security mechanism where a Citrix ADC appliance authenticates a system user at two authenticator levels. The appliance grants access to the user only after successful validation of passwords by both levels of authentication.

For information about configuring two factor authentication for system users by using Citrix ADC CLI or GUI, see Two factor authentication for system users.

Steps to log on to a Citrix ADC appliance that has two factor authentication configured

1. Send user credentials for the first level authentication
2. Send user credentials for the second level authentication

Send user credentials for the first level authentication

You use the login API object to send the username and first password to the Citrix ADC appliance for first level authentication.

The Citrix ADC appliance responds with a session (token) ID, error code, a next factor login message, and other details. The error code and next factor login message indicates that a second level authentication is required to complete the login process.

Request structure

Send user credentials for the second level authentication

You use the loginnextfactorresponse API object to send the following information to the Citrix ADC appliance for second level authentication.

• Second password (next factor password)
• Session ID (received as part of first level authentication)

The Citrix ADC appliance responds with an error code, a message, and other details. An error code of 0 and a message of Done indicate that the two factor authentication process is completed with success. The session ID received must be specified in the request header of all further operations in the session.

Request structure

Sample configuration

Enabling Citrix ADC Features and Modes

Some Citrix ADC features and modes are disabled by default and therefore must be enabled before they can be configured. To enable a Citrix ADC feature or mode, specify the action as “enable” in the URL query string, and in the request payload, specify the feature or mode to be enabled.

• Using REST APIs through HTTP

  To disable a feature or mode, in the URL query string, specify the action as “disable”.

For example, to enable the load balancing and content switching features:

• Request

  HTTP Method: POST

URL: http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nsfeature?action=enable

Request Headers:

Cookie:NITRO_AUTH_TOKEN=<tokenvalue>

Content-Type:application/json

Request Payload:

{
    "nsfeature":
    {
        "feature":
        [
            "LB",
            "CS"
        ]
    }
}
<!--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 enable the L2 and fast ramp modes:

• Request

  HTTP Method: POST

URL: http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nsmode?action=enable

Request Headers:

Cookie:NITRO_AUTH_TOKEN=<tokenvalue>

Content-Type:application/json

Request Payload:

{
    "nsmode":
    {
        "mode":
        [
            "L2",
            "FR"
        ]
    }
}
<!--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.

Saving Citrix ADC Configurations

To make sure that the configurations persist on rebooting the appliance, you must save the Citrix ADC configurations. To save the configurations, specify the action as “save” in the URL query string.

• Using REST APIs through HTTP

  To save the configurations:

• Request

  HTTP Method: POST

URL: http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/nsconfig?action=save

Request Headers:

Cookie:NITRO_AUTH_TOKEN=<tokenvalue>

Content-Type:application/json

Request Payload:

{
    "nsconfig":
    {}
}
<!--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.

Killing a System Session

A Citrix ADC administrator can kill any system session by specifying the action as “kill” in the URL query string and by specifying the required system session ID in the request payload.

• Using REST APIs through HTTP

  For example, to kill a system session that has ID as 311:

• Request

  HTTP Method: POST

URL: http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/systemsession?action=kill

Request Headers:

Cookie:NITRO_AUTH_TOKEN=<tokenvalue>

Content-Type:application/json

Request Payload:

{
    "systemsession":
    {
    "sid":"311"
    }
}
<!--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.

Disconnecting from the Citrix ADC Appliance

Before disconnecting (logging out) from the Citrix ADC appliance, make sure that you have saved the Citrix ADC configurations.

• Using REST APIs through HTTP

  To logout of the Citrix ADC appliance:

• Request

  HTTP Method: POST

URL: http://<Citrix-ADC-IP-address(NSIP)>/nitro/v1/config/logout

Request Headers:

Cookie:NITRO_AUTH_TOKEN=<tokenvalue>

Content-Type:application/json

Request Payload:

{
    "logout":{}
}
<!--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.