Product Documentation

Launching the NetScaler VPX for AWS AMI

May 14, 2014
You can launch a Citrix NetScaler VPX AMI within an Amazon Web Services (AWS) Virtual Private Cloud (VPC) in one of two ways:
  1. Using the Amazon GUI and CLI toolkit.
  2. Using a Citrix authored CloudFormation template.
  3. Using the Amazon 1-Click launch.
Note: The following are the default administrator credentials to access a NetScaler VPX instance:
  • Username—nsroot
  • Password—The default password for the nsroot account is set to the AWS instance-ID of the NetScaler VPX instance. For a high availability configuration between two NetScaler VPX instances, the nsroot password of the secondary node is set to that of the primary node after the HA configuration synchronization.

Launching NetScaler VPX for AWS by Using the Amazon GUI and CLI toolkit

Updated: 2014-05-13

To launch a NetScaler VPX AMI within an Amazon Web Services (AWS) Virtual Private Cloud (VPC) by using the Amazon GUI and CLI toolkit, you need:
  • An AWS account
  • An AWS Virtual Private cloud (VPC)
  • The AWS API toolkit (if creating a VPX instance with three or more ENIs).
  • An IAM account

Creating an AWS Account

To launch a NetScaler VPX AMI in an Amazon Web Services (AWS) Virtual Private Cloud (VPC), you need an AWS account. You can create an AWS account for free at www.aws.amazon.com.

Creating an AWS Virtual Private Cloud (VPC)

Citrix recommends at least three IP addresses for a NetScaler instance. Currently, the only support that AWS provides for instances with multiple IP addresses is for instances within an AWS VPC.

To create an AWS VPC, first launch the AWS GUI console. For instructions for using the AWS GUI console, see http://docs.amazonwebservices.com/AmazonVPC/latest/GettingStartedGuide/GetStarted.html?r=2900.

To create an AWS VPC
  1. Use the VPC with a Single Public Subnet Only option to create a new AWS VPC in an AWS availability zone.
  2. Create additional subnets within the AWS VPC. Citrix recommends that you create at least three subnets, of the following types:
    • One subnet for NetScaler management traffic. You place the NetScaler management IP(NSIP) on this subnet.
    • One or more subnets for client-access (user-to-NetScaler) traffic, through which clients connect to one or more virtual IP (VIP) addresses assigned to NetScaler load balancing virtual servers.
    • One or more subnets for the server-access (NetScaler-to-server) traffic, through which your servers connect to NetScaler-owned subnet IP (SNIP) addresses.

      For more information about NetScaler load balancing and virtual servers, virtual IP addresses (VIPs), and subnet IP addresses (SNIPs), see: .

    Note:
    • All subnets should be in the same availability zone.
    • You can launch a NetScaler AMI in an AWS VPC with a single subnet. In this configuration, the management traffic, client-side traffic, and server-side traffic all use the same subnet, and high availability (HA) cannot be configured.
    • You can launch the NetScaler AMI into an AWS VPC with two subnets. In this configuration, one subnet is used for management traffic, and the other subnet is used for both client-side and server-side traffic. This topology supports NetScaler HA.
  3. Create an Internet gateway and attach it to the VPC instance.
  4. Create routing tables for all traffic flowing into or out of the VPC. You need routes for access to the NSIP and to any client-facing VIP addresses. Traffic leaving the VPC must be routed through the Internet Gateway of the AWS VPC.
    Note:
    • Make sure that you associate management and client subnets with the routing table.
    • Add a default route to the routing table for the traffic flowing out of the VPC. Set the Destination to 0.0.0.0/0, and the Target as the Internet gateway address.
  5. Create a security group and open the required ports.

Setting-up the AWS API Toolkit

The AWS GUI console does not allow you to launch instances with more than two ENIs. For a standard deployment, you have to create at least three ENIs for a VPC instance (though it is possible to launch a NetScaler AMI with one or two ENIs). To create three or more ENIs for a NetScaler instance, you must use the AWS CLI. To use the AWS CLI, you must install the AWS API toolkit.

The AWS API toolkit is available for download at http://aws.amazon.com/developertools/351/. To install the AWS API toolkit, complete the following tasks on a Windows or Linux machine:
  1. Download the AWS API Toolkit.
  2. Download X.509 certificate files and X.509 private key file.
  3. Download the private key.
  4. Convert the downloaded private key (.pem file) for SSH connectivity.
  5. Configure the AWS API Toolkit environment on your Windows or Linux computer.
To download the AWS API toolkit
  1. In a web browser, open the following website: http://aws.amazon.com/developertools/351/.
  2. On the Amazon EC2 API Tools page, in the Download section, click Download the Amazon EC2 API Tools.
  3. Save the file, ec2-api-tools.zip, to a local disk and use a file compression utility (for example, WinZip) to extract the files.
To download the X.509 certificate file and X.509 private key file
  1. In your browser, open the following website: http://aws.amazon.com/.
  2. Click My Account/Console, and then click Security Credentials.
  3. On the Amazon Web Services Sign in page, use your Amazon account credentials to sign in.
  4. On the Security Credentials page, in the Access Credentials section, on the X.509 Certificates tab, click Create a New Certificate.
  5. In the X509 Certificate Created dialog box, Click Download Private Key File and save the private key file to a secure folder on your local drive.
  6. Click Download X.509 Certificate and save the certificate to a secure folder on your local drive.
  7. Click Close.
Note: The Private Key File can be downloaded only at the time of creating a certificate. However, you can download the certificate at any time after creating it.
To download private key for SSH connectivity
  1. In your browser, open the following website: http://aws.amazon.com/ .
  2. Click My Account/Console.
  3. On the Amazon Web Services Sign in page, use your Amazon account credentials to sign in.
  4. In the Service pane, in Amazon Web Services, click EC2.
  5. In the Navigation section, in Network and Security, click Key Pairs.
  6. In the Key Pairs pane, click Create Key Pair.
  7. In the Create Key Pair dialog box, type the name for key pair and click Create.
  8. Download the Key Pair to the local disk and click Close.
To convert the downloaded private key for SSH connectivity
For SSH connections from a management machine using Putty, you must convert the .pem file (Private Key) into .ppk file. The .ppk file is the private key for SSH connections to the NetScaler VPX instance hosted in the AWS environment. To convert the .pem file to a .ppk file, use the Putty application's PuttyGen utility. Make sure that the key pairs and certificate files are stored in an unshared and secured directory. After the conversion, you can use SSH to securely connect to the management address of the VPX on AWS instance.
To configure the AWS API Toolkit environment on a Windows machine
  1. Move the certificate files to an unshared folder (for example, aws-ec2-api-tools).
  2. Move the extracted AWS API toolkit folder to the unshared folder (for example, the aws-ec2-api-tools folder created in example in Step 1).
  3. Create a batch file to configure the specific AWS environment in the unshared folder (aws-ec2-api-tools if you used the example in the preceding two steps). Following is an example of the batch file. The file location used in this example is C:\aws-vpc-config\ and the file name is set-aws-environment.bat.

    rem Setup Amazon EC2 Command-Line Tools

    set JAVA_HOME="C:\Program Files\Java\jre7\"

    set EC2_HOME="C:\aws-ec2-api-tools\"

    set PATH=%PATH%;%EC2_HOME%\bin

    set EC2_PRIVATE_KEY=C:\aws-ec2-security-files\pk-3T6ACCLBEDGD3O3SMAM7YDI76VP5HXSU.pem

    set EC2_CERT=C:\aws-ec2-security-files\cert-3T6ACCLBEDGD3O3SMAM7YDI76VP5HXSU.pem

    set EC2_URL=https://<aws-region>.ec2.amazonaws.com

  4. Open the command prompt and run the batch file. For the file in the above example, type:

    C:\aws-vpc-config> set-aws-environment.bat

  5. Run the ec2ver command to verify that the AWS toolkit is installed properly. For example:

    C:\aws-vpc-config>ec2ver 1.5.6.1 2012-06-15

To configure the AWS API Toolkit on a Linux machine
  1. Move the certificate files to an unshared folder (for example, aws-ec2-api-tools).
  2. Move the extracted AWS API toolkit folder to the unshared folder (for example, the aws-ec2-api-tools folder created in example in Step 1).
  3. Create a shell script to configure the specific AWS environment in the unshared folder (aws-ec2-api-tools if you used the example in the preceding two steps). Following is an example of the batch file. In this example, the file location used is C:\aws-vpc-config\ and the file name used is set-aws-environment.bat.

    # Setup Amazon EC2 Command-Line Tools

    export EC2_HOME=~/ec2-api-tools-1.5.6.0

    export EC2_URL= https://us-east-1.ec2.amazonaws.com

    export PATH=$EC2_HOME/bin:/usr/bin:$/usr/sbin:/usr/local/sbin:/sbin

    export EC2_PRIVATE_KEY=~/pk-XOX3NS2UPZL6BGLFO7PM5OGLYBDPBUCB.pem

    export EC2_CERT=~/cert-XOX3NS2UPZL6BGLFO7PM5OGLYBDPBUCB.pem

    export JAVA_HOME=/usr

    export PS1="AWS PROMPT >"

  4. Run the ec2ver command to verify that the AWS toolkit is installed properly. For example:

    AWS PROMPT >ec2ver

    1.5.6.1 2012-06-15

Creating an IAM Account

Before you launch the VPX AMI instance, you have to create a new IAM user account with the Access and Secret keys. The Access and Secret key credentials from the new IAM user are required for launching the NetScaler AMI instance. To create a new IAM user for NetScaler, complete the following steps.
  1. In a web browser, open the website at www.aws.amazon.com and log on with AWS credentials.
  2. Click My Account/Console, and then click AWS Management Console.

  3. On the Amazon Web Services page, click IAM.

  4. In the Navigation pane, click Users, and then click Create New Users.
  5. In the Create User dialog box, in one of the Enter User Names text boxes, type a user name (for example, cns_ha). Also select the Generate an access key for each User check box, and then click Create.

  6. After a new IAM user is created, click Download Credentials to download the Access and Secret Keys to a safe location. These keys are required for launching NetScaler AMI. Click Close.
    Note: The Access Key ID and Secret Access Key values are used to create the key-pair file and to launch an instance.

  7. In the Users pane, select the newly created IAM user and click the Permissions tab. Then, click Attach User Policy to set policies for the user.

  8. In the Manage User Permissions dialog box, next to Effect, select the Allow option. For AWS Service, select Amazon EC2. From the Actions drop-down list, select the following four actions:
    • AttachNetworkInterface
    • DescribeInstances
    • DescribeNetworkInterfaces
    • DetachNetworkInterface

  9. Click Add Statement.

  10. Click Continue.

  11. Click Apply Policy to set the new permissions for the selected user.

Launching the NetScaler AMI

Use the AWS CLI to launch the NetScaler AMI in an AWS VPC. Use the ec2-run-instances command. For information about the ec2-run-instances command, see http://docs.amazonwebservices.com/AWSEC2/latest/CommandLineReference/ApiReference-cmd-RunInstances.html.

Following are Windows and Linux examples of running the command to launch a single NetScaler instance. The EC2 instance type is m3.large. It is configured with the following entities:
  • NetScaler AMI named ami-bd2986d4.
  • Three ENIs (named NSIP, CLIENT-SIDE, and SERVER-SIDE) associated with the three subnets (15fa057e, 1547ba7e, and 1547ba7e) within the VPC.
  • A single IP address for the NSIP ENI.
  • Multiple private IP addresses (for multiple VIPs) on the CLIENT-SIDE ENI.
  • Multiple private IPs (for multiple SNIPs) on the SERVER-SIDE ENI.
On a Windows platform:
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":10.20.15.21 -a :1:subnet-1547ba7e:"CLIENT-SIDE":10.20.10.21::::"10.20.10.22,10.20.10.23,10.20.10.24,10.20.10.25,10.20.10.26,10.20.10.27,10.20.10.28,10.20.10.29,10.20.10.30" -a :2:subnet-cc47baa7:"SERVER-SIDE":10.20.1.21::::"10.20.1.22,10.20.1.23,10.20.1.24,10.20.1.25,10.20.1.26,10.20.1.27,10.20.1.28,10.20.1.29,10.20.1.30"
Note: The access-secret-key-file file contains the access and secret keys.
On a Linux platform:
AWS PROMPT > ec2-run-instances ami-bd2986d4 -n 1 -t m1.large -k keyPairName -f access-secret-key-file -a :0:subnet-15fa057e:"NSIP":10.20.15.21 -a :1:subnet-1547ba7e:"CLIENT-SIDE":10.20.10.21::::10.20.10.22,10.20.10.23,10.20.10.24,10.20.10.25,10.20.10.26,10.20.10.27,10.20.10.28,10.20.10.29,10.20.10.30 -a :2:subnet-cc47baa7:"SERVER-SIDE":10.20.1.21::::10.20.1.22,10.20.1.23,10.20.1.24,10.20.1.25,10.20.1.26,10.20.1.27,10.20.1.28,10.20.1.29,10.20.1.30
Note: The access-secret-key-file file contains the access and secret keys.

The command returns the instance ID and the associated information. You can see the instance running within your AWS GUI Console.

Note: Make sure that the environment variable EC2_URL points to the region where you want to launch the VPX instance.
To access the EC2 instance
  1. In a web browser, open the website at www.aws.amazon.com and log on with AWS credentials.

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

  3. On the Amazon Web Services page, click EC2.

  4. On the Amazon EC2 Console Dashboard page, in the Navigation pane, click Instances and verify that all of the NetScaler VPX instances are configured with the IP addresses that you specified when you used the ec2-run-instances command.
    Note: The VPX instance or instances can take from five to ten minutes to start running.

The ec2-run-instances command does not allow associating AWS elastic IP with an ENI. To associate one or more EIPs with an ENI in the Navigation pane, in the NETWORK & SECURITY area, click Elastic IPs and associate EIPs with Private IP addresses for any of the VIPs that need to be externally routable.

You must also associate the instance ENIs with appropriate security groups. Go to the Network Interfaces section, right-click on the individual ENI, and select the Change Security Groups option. You can then associate a proper VPC security group.

Using the Citrix CloudFormation Template to launch CloudBridge VPX for AWS

Using the Citrix Cloud Formation Template to launch NetScaler VPX for AWS

Citrix also provides a CloudFormation template that can be used to automate NetScaler instance launch. The tool requires an existing VPC environment. It launches a NetScaler instance with three ENIs. Therefore, to use the CloudFormation template, make sure that you have the following:
  1. AWS account
  2. AWS VPC
  3. Three subnets within the VPC
  4. A security group to use for the NetScaler instances ENIs

Refer to Creating an AWS Virtual Private Cloud (VPC) for information about how to configure subnets and security groups within a VPC. After configuring the required subnets and security groups, you can launch the NetScaler VPX AMI in AWS VPC. The CloudFormation tool provides functionality to launch a single NetScaler VPX instance or, to create a high availability environment, a pair of NetScaler VPX instances.

Launching a single NetScaler VPX instance in AWS
  1. In a web browser, open the website at www.aws.amazon.comand log on with AWS credentials.

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

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

  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 a value for Stack Name, select the Upload a Template File option, and then click Browse. Select the template for a standalone NetScaler VPX from the local drive, and then click Continue.
    Note:
  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 the VPC
    • ServerSubnet: Subnet in which the server farm is configured in the VPC
    • ClientSubnet: SubnetId in which the client side is configured in the VPC
    • SecurityGroup: VPC Security group ID
    • VPXPrimary: Name of the 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.
    • 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 and gateway associations are already configured.

  7. Click Continue.
  8. Review the 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.
    Note:
    • Currently, the CloudFormation utility does not provide the functionality to add secondary IP addresses. Use the AWS console, after deploying a NetScaler VPX instance, to add the secondary IP addresses to the ENIs.
    • The CloudFormation scripts for the standalone and HA pair VPX instances have the latest AMIs for the five supported regions. You have to update the scripts to synchronize with the latest AMIs.
    • The script automatically selects the correct AMI for the region in which the VPX instance is being deployed.
    • By default, all the ENIs are attached to one security group, use the AWS console to attach an ENI to a different security group.
    • EIPs are automatically allocated and assigned to an instance. If the EIP limit exceeds the threshold for the region, the CloudFormation script fails and displays an error message.

Collaborating to Deliver High-Quality Products and Content Launching NetScaler VPX by using the AWS 1-Click

Updated: 2015-01-29

1-Click helps you to launch an instance of NetScaler VPX on AWS, quickly as compared to other launching methods, with the default options. After the instance is launched on AWS, you can modify these options by using either the AWS CLI or the AWS GUI.

The default options include the following elastic network interfaces (ENIs) for the NetScaler instance:

  • Management Interface—Associates a subnet for management related traffic. You add the NetScaler management IP (NSIP) address to this subnet.
  • Public Interface—Associates a subnet for the client-access (user-to-NetScaler) traffic. You add one or more virtual IP (VIP) addresses on this subnet.
  • Private Interface—Associates a subnet for server-access (NetScaler-to-server) traffic. You add subnet IP (SNIP) addresses on this subnet.
Before you begin launching an instance of NetScaler VPX on AWS, consider the following points :
  • For security reasons, none of the elastic IP addresses are attached to the ENIs of the NetScaler VPX instance launched by using 1-Click. This means that the NetScaler VPX instance (including the management IP address) is not reachable from outside the AWS Virtual Private Cloud (VPC). If your VPC uses a Virtual Gateway or other method to provide a VPN access to the VPC, you can administer the instance by using the IP address of the network interface in the management subnet. If you do not have VPN access to your VPC, Citrix recommends that you set up a jump box instance within the VPC, and then use this as the source for accessing or managing other instances within the VPC. For instructions to create an SSH jump box, see https://s3.amazonaws.com/awsmp-usageinstructions/Creating_and_using_VPC.txt.
  • Three default security policies are created. A policy each is attached to the management, public and private interfaces, respectively.
    • The security policy for the management interface allows traffic from a set of ports.
    • The security policies for the public and private interfaces block all the traffic to or from these interfaces. You can later modify these security groups to filter the desired traffic.
  • High Availability configuration is not supported for a NetScaler VPX instance launched by using AWS 1-click.
Before you begin launching an instance of NetScaler VPX on AWS, make sure that you have the following:
  • An AWS account
  • An AWS Virtual Private Cloud (VPC)
  • Three subnets within the AWS VPC (one each for management interface, public interface, and private interface of the NetScaler instance)
  • An IAM key pair

For information about creating an AWS account, a VPC, subnets in a VPC, and an IAM key pair, see Launching NetScaler VPX for AWS by Using the Amazon GUI and CLI toolkit.

To launch an instance of NetScaler VPX on AWS by using 1-Click

  1. Log on to the AWS marketplace (https://aws.amazon.com/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. On the Citrix NetScaler VPX page, click Continue.
  5. Click the 1-Click Launch tab. On the 1-Click Launch tab, specify values for the following fields:
    • Version
    • Region
    • EC2 Instance type
    • Key Pair
  6. On the VPC Settings pane, click Setup.

  7. On the VPC Settings page, specify values for the following fields, and then click Done:
    • VPC
    • Network Interface (Management subnet)
    • Network Interface (Private subnet)
    • Network Interface (Public subnet)
    Note: You need to make sure that the subnets attached to these ENIs are different from each other. Attaching the same subnet to more than one ENI might cause routing issues.
  8. Click Accept Terms & Launch with 1-Click.

    After few minutes, the NetScaler instance is launched with three ENIs. You can now connect to the NSIP address (the IP address on the management ENI) of the instance by using the NetScaler CLI or NetScaler GUI and start configuring the NetScaler features, for example, load balancing.