Product Documentation

High Availability

Jul 17, 2017

Two Citrix NetScaler VPX instances in AWS can be configured as a high availability (HA) pair. With one instance configured as the primary node and the other as the secondary node, the primary node accepts connections and manages servers while the secondary node monitors the primary. If, for any reason, the primary node is unable to accept connections, the secondary node takes over.

The following figure shows an example of the HA deployment architecture for NetScaler VPX on AWS.
Figure 1. NetScaler VPX on AWS - HA Deployment

To deploy HA for VPX on AWS, you must configure at least two ENIs on the primary instance and a single ENI on the secondary instance. On each instance, configure the NetScaler IP (NSIP) address (the management address) on the default ENI. On the primary instance, use the additional ENIs for client and server connections.

Example format for a key file is:
Note: For HA failover to work:
  1. The NSIP addresses for each NetScaler instance in an HA pair must be configured on the default ENI of the instance.
  2. Both the primary and secondary instances must have EIPs associated with the NSIP or NAT configured to handle outgoing traffic in order to have access to the AWS API servers.
  3. Client and server traffic (data-plane traffic) must not be configured on the default ENI.
  4. Access and secret keys associated with the user's AWS Identity and Access Management (IAM) account. If the correct key information is not used when creating VPX instances, the HA deployment will fail. The access and secret keys are required for sending Query APIs to the AWS server.
  5. Nameservers/DNS servers are configured at VPC level using DHCP options.
Notes on HA:
  • Because Amazon does not allow any broadcast/multicast packets in AWS, HA is implemented by migrating data-plane ENIs from the primary to the secondary (new primary) VPX instance when the primary VPX instance fails.
  • To deploy HA for VPX on AWS, you must configure at least two ENIs on the primary instance and a single ENI on the secondary instance.
  • Because the default ENI cannot be moved to another VPX instance, you should not use the default ENI for data.
  • The message AWSCONFIG IOCTL NSAPI_HOTPLUG_INTF success output 0 indicates that the two data ENI's have successfully attached to the secondary instance (the new primary).
  • Failover might take up to 20 seconds due to the AWS detach/attach ENI mechanism.
  • Upon failover, the failed instance always restarts.
  • The secondary node always has one ENI interface (for management) and the primary node can have up to four ENIs.
  • The heartbeat packets are received only on the management interface.
  • The configuration file of the primary and secondary NetScaler appliances is synchronized, including the nsroot password. The nsroot password of the secondary node is set to that of the primary node after the HA configuration synchronization.
  • The AWS debug messages are available in the log file, /var/log/ns.log, on the VPX instance.

Configuring High Availability for VPX on AWS

To deploy HA for two VPX instances on AWS, you must create the primary NetScaler VPX instances with three ENIs and the secondary NetScaler VPX with a single ENI.

Following is an example of launching a primary VPX instance with three ENIs:

C:\aws-vpc-config>ec2-run-instances ami-bd2986d4 -n 1 -t m1.large -k keyPairName -f ./access-secret-key-file -a :0:subnet-15fa057e:"NSIP": -a :1:subnet-1547ba7e:"CLIENT-SIDE":",,,,,,,," -a :2:subnet-cc47baa7:"SERVER-SIDE":",,,,,,,,"

Following is an example of launching a secondary VPX instance with a single ENI:

C:\aws-vpc-config>ec2-run-instances ami-bd2986d4 -n 1 -t m1.large -k keyPairName -f access-secret-key-file -a :0:subnet-15fa057e:"NSIP":
Note: The access-secret-key-file argument contains the access and secret key. (You cannot change the access-secret-key-file associated with a VPC instance after it is created.)

After the two NetScaler instances are UP, configure the HA pairing on both the instances. You have to configure the instance with two or more ENIs before configuring HA on the instance with one ENI. Use the add HA node command, from within the NetScaler CLI, or from the NetScaler GUI. For example:

On the VPX instance with two or more ENIs:

add HA node 1

On the VPX instance with one ENI:

add HA node 1

After you enter add HA node commands, the two nodes form an HA pair, and configuration information is synchronized between the two VPX instances.

To remove HA from NetScaler VPX pair
You can remove HA configuration from the NetScaler VPX pair by using the remove ha node command. You have to remove the HA configuration from the secondary NetScaler VPX before removing the HA configuration from the primary NetScaler VPX.

For example, on the Secondary NetScaler VPX instance, at the NetScaler command line, type:

remove ha node

save config

On the Primary NetScaler VPX instance, at the NetScaler command line, type:

remove ha node

save config

Launching a NetScaler VPX HA Pair by Using IAM ROLE

From NetScaler release 11.1 onwards, you can create a VPX HA pair in AWS without any Access Key ID and Secret Access Key, by using IAM role. Follow these steps:

  1. Log on to the AWS marketplace ( by using your Amazon AWS credentials.
  2. In the search field, type NetScaler VPX to search for the NetScaler AMI, and click Go.
  3. On the search result page, click the desired Citrix NetScaler VPX offering. 
  4. Select the Delivery Method as Netscaler AWS-VPX Cluster and click Continue.
localized image

5. In the next page, select Software Pricing, Version, and Region according to your requirement.

6. In the Select Template page, select the default template and click Next.

7. In the Specify Details page, enter required details such as client subnet, key name, NSIP subnet, and so on.


If you need specific IP addresses to be assigned from the selected subnet, you can fill NsIP, NsIPSec, Server ip box with the required IP address.

localized image

8. In the Options page, add Tag for the VPX instance and keep the default value of IAMRole, and click Next.

9. On the Review page, review the template, check the box "I acknowledge that AWS CloudFormation might create IAM resources." at the bottom of the page, and click Create to create an IAM role.

10. The CREATE-IN-PROGRESS status should be displayed. Wait untill the status is CREATE-COMPLETE. If the status does not change to "COMPLETE," check the Events tab for the reason of failure and recreate the instance with proper configurations. 

localized image

11. After an IAM resource is created, go to EC2 Management Console > Instances. You should notice 2 VPX insntances created with IAM role. The primary node is created with three private IP addresses and three network interfaces. 

localized image

The secondary node is created with one private IP addresss and one network interface. 



 The secondary node is created with one interface by default in AWS. During failover, the interface from the primary node gets attached to the secondary node (the new primary node) and gets detached from the original primary node (the new secondary node)  


13. Log on to the primary node with user name nsroot and the instance ID as the password. From the  NetScaler GUI, go to System > High Availability

14. Under Nodes, click Add and enter the IP address of the secondary instance.

localized image

This completes the high availability setup.  You should see both the  primary and secondary nodes under System > High Availability > Nodes, in both the VPX instances.

Launching NetScaler VPX pairs for HA by using Citrix CloudFormation

  1. In a web browser, open the website at and log on with AWS credentials.

  2. Click My Account/Console, and then click AWS Management Console.

  3. On the Amazon Web Services page, in the Deployment & Management section, click Cloud Formation.

  4. On the CloudFormation Stacks page, select the Region in which you plan to deploy the NetScaler VPX instance, and then click Create New Stack.

  5. In the Create Stack dialog box, specify value for Stack Name, select the Upload a Template File option, and then click Browse. Select the template for HA NetScaler VPX from the local drive, and then click Continue.

  6. In the next pane, specify values for:
    • VpcID: An identifier to assign to the Virtual Private Cloud (VPC).
    • NsipSubnet: Subnet in which the NSIP is configured in VPC.
    • ServerSubnet: Subnet in which the server farm is configured in VPC.
    • ClientSubnet: SubnetId in which the client side is configured in VPC.
    • SecurityGroup: VPC Security group id.
    • VPXPrimary: Name of Primary VPX instance type.
    • AccessKey: Access Key for IAM user account.
    • SecretKey: Secret Key for IAM user account.
    • TenancyType: Instance tenancy type, can be default or dedicated.
    • NsIP: Private IP assigned to the NSIP ENI. The last octet of NSIP should be between 5 and 254.
    • NsIPSec: Private IP assigned to the NSIP ENI of Secondary. last octet has to be between 5 and 254.
    • ServerIP: Private IP assigned to the Server ENI. The last octet should be between 5 and 254.
    • ClientIP: Private IP assigned to the Client ENI. The last octet should be between 5 and 254.
    • KeyName: Name of an existing EC2 KeyPair to enable SSH access to the instances.
    Note: Make sure that the VPC, subnets, security groups, routes associations, gateway associations are already configured.

  7. Click Continue.
  8. Review the specified values in the Create Stack dialog box.

  9. Click Continue to create a Stack.

  10. Click Close to close the Create Stack dialog box.
  11. The new stack that you created appears on the CloudFormation Stacks page.