Product Documentation

Deploying a NetScaler VPX HA Pair on AWS

Nov 29, 2017

You can configure two Citrix NetScaler VPX instances on AWS as a high availability (HA) active-passive 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.

For more information on HA, see High Availability.

The following figure shows an example of the HA deployment architecture for NetScaler VPX instances on AWS.

Figure 1. A NetScaler VPX HA Pair on AWS

To deploy HA for two VPX instances on AWS, you either create the instances with IAM Role manually by using the AWS Management Console and then configure HA on them, or you can automate the HA deployment by using the Citrix CloudFormation template. 

The CloudFormation template significantly decreases the number of steps involved for creating an HA pair, and it automatically creates an IAM Role. This section shows how to deploy a NetScaler VPX HA (active-passive) pair by using the Citrix CloudFormation template.

Keep the following points in mind while deploying two NetScaler VPX  instances as an HA pair.

Usage Guidelines

  • HA on AWS requires the primary node to have at least two ENIs  (one for management and the other for data traffic), and the secondary node to have one management ENI. However, for security purposes, create three ENIs on the primary node, because this setup allows you to segregate private and public network (recommended).
  • The secondary node always has one ENI interface (for management) and the primary node can have up to four ENIs.
  • The NSIP addresses for each NetScaler instance in an HA pair must be configured on the default ENI of the instance.
  • 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.
  • Because the default (management) ENI cannot be moved to another VPX instance, do not use the default ENI for client and server traffic (data-plane traffic).
  • The message AWSCONFIG IOCTL NSAPI_HOTPLUG_INTF success output 0  in the /var/log/ns.log indicates that the two data ENIs 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 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.
  • To have access to the AWS API servers, either the Netscaler instance must have a public IP address assigned or routing must be set up correctly at VPC subnet level pointing to internet gateway of the VPC.
  • Nameservers/DNS servers are configured at VPC level using DHCP options.
  • The Citrix CloudFormation template does not create an HA setup between different availability zones.
  • The Citrix CloudFormation template does not create an INC mode.
  • The AWS debug messages are available in the log file, /var/log/ns.log, on the VPX instance.

Deploy a NetScaler VPX HA Pair on AWS by Using the Citrix CloudFormation Template

Before start the CloudFormation template, ensure that you complete the following requirements:

  • A VPC
  • Three subnets within the VPC
  • A security group with UDP 3003, TCP 3009-3010, HTTP,  SSH ports open
  • A key pair


The Citrix CloudFormation template automatically creates an IAM Role. The template has no option to select an existing IAM Role.

To  launch the Citrix CloudFormation template

  1. Log on to the AWS marketplace ( by using your 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. Under For Region, select your region.
  5. Select the Delivery Methods as Netscaler AWS-VPX Cluster and click Continue.

localized image

6. On the Launch on EC2 page , under Version, select the correct NetScaler version.  Ensure that the Region and Deployment Options are correct. Check pricing details.

7. Click Launch with CloudFormation Console to launch the Citrix CloudFormation template..

8. The Select Template page appears.  Click Next.

9. The Specify Details appears. Enter the following details.

   a. Type a Stack name. The name must be within 25 characters.

   b. Under High Availability Configuration

  Select Yes from the drop-down menu for Create HA pair?.

   c. Under Virtual Private Network Configuration

Select the VPC that you’ve already created for VPC ID.

Type Remote SSH CIDR IP.

Type Remote HTTP CIDR IP.

Type Remote HTTPS CIDR IP.

Select the key pair that you’ve already created from the drop-down menu for Key Pair.

   d. Under Network Interface Configuration

Select Management SubnetworkClient Subnetwork, and Server Subnetwork.  Ensure that you select the correct subnetworks  you created within the VPC that you selected under VPC ID in step c.

Add Primary Management IPSecondary Management IPClient IP, and Server IP. The IP addresses should belong to the same subnets of the respective subnetworks.  Alternatively, you can let the template assign the IP addresses automatically. 

   e. Under Other Parameters

Select  m4.large for Instant Type.

Select default for Tenancy Type.

   f. Click Next.

8.  The Options page appears. (This is an optional page.). Click Next

9. The Review page appears. Take a moment to review the settings and make necessary changes if required. 

10. Select the I acknowledge that AWS CloudFormation might create IAM resources. check box, and then click Create.

11.  The CREATE-IN-PROGRESS status appears. Wait until 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 two 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

Next, configure the HA pairing on both the instances. Configure the instance with three 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. 

add HA node <private IP of the first instance>

add HA node <private IP of the second instance>

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