Citrix Web App Firewall on the AWS Cloud

Quick Start Reference Deployment

QS

August 2020
Citrix Systems, Inc.
AWS Quick Start team

Visit our GitHub repository for source files and to post feedback, report bugs, or submit feature ideas for this Quick Start.

This Quick Start was created by Citrix Systems, Inc. in collaboration with Amazon Web Services (AWS). Quick Starts are automated reference deployments that use AWS CloudFormation templates to deploy key technologies on AWS, following AWS best practices.

Overview

This Quick Start reference deployment guide provides step-by-step instructions for deploying Citrix WAF for high availability (HA) on the AWS Cloud.

This Quick Start is for users who want to mitigate threats to public or internal web assets running on AWS. Use this Quick Start to build and test a proof of concept or to create a highly available production-ready deployment of Citrix WAF as a front end for your web applications.

Amazon may share user-deployment information with the AWS Partner that collaborated with AWS on the Quick Start.

Citrix Web App Firewall on AWS

Citrix WAF is a firewall that protects web applications and sites from both known and unknown attacks, including application-layer and zero-day threats. Citrix WAF is positioned in front of a web server, monitoring web traffic before it reaches the web application, as shown in Figure 1.

Architecture
Figure 1. How Citrix WAF works on AWS

Citrix WAF filters requests to and from the web server as follows:

  1. When a request comes in, Citrix WAF matches it against the signatures that protect your websites against known attacks. If any of these checks fail, WAF redirects the request to a user-designated error object.

  2. If the request passes the signature checks, WAF performs other security checks, such as SQL injection, cross-site scripting, buffer overflow, etc. If any of these checks fail, WAF redirects the request to a user-designated error object.

  3. If the request passes all the incoming checks, WAF forwards it to the web server. It then performs security checks on the server’s responses and outgoing requests, such as those pertaining to sensitive data, credit cards, and social security numbers. If any security check fails, WAF responds with a 404. If they all pass, WAF forwards the request to the user’s browser.

Citrix WAF is based on a Citrix Application Delivery Controller (ADC) platform. Citrix ADC platforms have a single code base that enables consistency across your applications and workflows. This Quick Start deploys an HA pair of Citrix ADC instances with WAF enabled.

Specifically, this Quick Start uses Citrix ADC VPX virtual appliances to deploy Citrix WAF on the AWS Cloud. The Citrix ADC VPX virtualizes your networking infrastructure. With the Citrix ADC VPX, functionality that’s typically available only on specialized, high-end network devices is available dynamically on a single server or across enterprise data centers.

You can customize this Quick Start by changing the configuration parameters. The Quick Start deploys a full working stack that you can inspect and use as a reference. You can deploy more than one WAF node by launching the AWS CloudFormation template multiple times.

Cost

You are responsible for the cost of the AWS services used while running this Quick Start. There is no additional cost for using the Quick Start.

The AWS CloudFormation templates for Quick Starts include configuration parameters that you can customize. Some of the settings, such as the instance type, affect the cost of deployment. For cost estimates, see the pricing pages for each AWS service you use. Prices are subject to change.

After you deploy the Quick Start, create AWS Cost and Usage Reports to deliver billing metrics to an Amazon Simple Storage Service (Amazon S3) bucket in your account. These reports provide cost estimates based on usage throughout each month and aggregate the data at the end of the month. For more information, see What are AWS Cost and Usage Reports?

Software licenses

There are two license models for the Citrix WAF Amazon Machine Image (AMI):

  • Pay-as-you-go (PAYG) subscription-based model for production licenses: This model is restricted to a specific bandwidth and other performance metrics based on the license edition that the listing is bound to. In AWS Marketplace, the PAYG options for the Citrix WAF AMI are called “Citrix Web App Firewall (WAF).” You can choose from two throughput options: 200 Mbps or 1000 Mbps.

  • Bring-your-own-license (BYOL) model: This model applies if you have purchased a license through other channels. You need this type of license to dynamically modify the bandwidth—that is, to go for a higher throughput (such as > 5 Gbps). These are pooled-capacity licenses that are used with Citrix Application Delivery Management (ADM). In AWS Marketplace, the BYOL options for the Citrix WAF AMI are called Citrix ADC VPX - Customer Licensed. To use the BYOL model, you must have an AppFW feature enabled and must configure Citrix ADM as a licensing server. Whether you deploy Citrix ADM on premises or as an agent in the cloud, you must use a reachable ADM IP address as an input parameter when deploying the Quick Start.

    With the BYOL model, you choose one of the three modes:

    • Pooled licensing: With this mode, you can share bandwidth or instance licenses across ADC form factors and instances.

    • Check-in-check-out (CICO): With this mode, you choose between VPX-200, VPX-1000, VPX-3000, and VPX-5000 application platform types. Make sure that you have the same throughput license in your ADM licensing server.

    • Virtual CPU (vCPU) usage-based licensing: This mode has a specified number of CPUs that a particular Citrix WAF is entitled to.

Architecture

Deploying this Quick Start for a new virtual private cloud (VPC) with default parameters builds the following Citrix WAF environment in the AWS Cloud.

Architecture
Figure 2. Quick Start architecture for Citrix WAF on AWS

As shown in Figure 2, the Quick Start sets up the following:

  • A highly available architecture that spans two Availability Zones.*

  • A virtual private cloud (VPC) configured with two public and four private subnets, according to AWS best practices.*

  • An internet gateway attached to the VPC, and route tables associated with public subnets, to allow access to the internet. This gateway is used by the WAF host to send and receive traffic. (The VPN connection and VPN gateway shown here are not deployed as part of the Quick Start; they represent a way to connect to the VPC privately instead.)*

  • Two instances of Citrix WAF (primary and secondary), one in each Availability Zone. Together, these are called the Citrix WAF HA pair.

  • Three security groups (not shown), each spanning the two Availability Zones and acting as a virtual firewall to control the traffic for the WAF instances:

    • A security group for the client network interfaces.

    • A security group for the server network interfaces.

    • A security group for the management network interfaces.

  • In the public subnets:

    • Managed network address translation (NAT) gateways with associated Elastic IP addresses to allow outbound internet access for resources in the private subnets.*

    • An elastic network interface for the client network interface (VIP) of the Citrix WAF instance.

    • An optional Linux bastion host (not shown) in an Auto Scaling group to allow inbound Secure Shell (SSH) access to Amazon Elastic Compute Cloud (Amazon EC2) instances in public and private subnets.*

    • An optional Elastic IP address (not shown) attached to the client network interface of the primary Citrix WAF instance. 

  • In the private subnets (two per Availability Zone):

    • An elastic network interface with a private IP address for the management network interface (NSIP) of the Citrix WAF instance.

    • An elastic network interface with a private IP address for the server network interface (SNIP) of the Citrix WAF instance.

  • AWS Lambda functions to configure Citrix WAF high availability and load balancing.

  • An AWS Identity and Access Management (IAM) role to securely control access to AWS services and resources for your users. By default, the deployment creates the required IAM role. Alternatively, you can provide your own. See Prerequisites.

*The template that deploys the Quick Start into an existing VPC skips the components marked by asterisks and prompts you for your existing VPC configuration.

Backend servers are not deployed by the Quick Start. If you intend to use the Quick Start for a sandbox deployment, deploy a Linux bastion host in the public subnet (by choosing Create bastion host, as documented later). This allows inbound Secure Shell (SSH) access to EC2 instances in public and private subnets. An Elastic IP address is allocated to that bastion host.

Planning the deployment

Specialized knowledge

This deployment requires a moderate level of familiarity with AWS services. If you’re new to AWS, visit Getting Started with AWS and Training and Certification. These sites provide materials for learning how to design, deploy, and operate your infrastructure and applications on the AWS Cloud.

This Quick Start assumes familiarity with basic networking and Citrix WAF on ADC. Also, if you want to use pooled licensing for Citrix ADC, be well versed in how Citrix ADM manages licensing in a pooled setup.

AWS account

If you don’t already have an AWS account, create one at https://aws.amazon.com by following the on-screen instructions. Part of the sign-up process involves receiving a phone call and entering a PIN using the phone keypad.

Your AWS account is automatically signed up for all AWS services. You are charged only for the services you use.

Technical requirements

Before you launch the Quick Start, your account must be configured as specified in the following table. Otherwise, deployment might fail.

Resource quotas

If necessary, request service quota increases for the following resources. You might need to request increases if your existing deployment currently uses these resources and if this Quick Start deployment could result in exceeding the default quotas. The Service Quotas console displays your usage and quotas for some aspects of some services. For more information, see What is Service Quotas? and AWS service quotas.

Resource This deployment uses

VPCs

1

Elastic IP addresses

2 (Optional: +1 for client elastic network interfaces, +1 for bastion host)

IAM security groups

3

IAM roles

1

Subnets

6 (3 per Availability Zone)

Internet gateway

1

Route tables

5

EC2 instances

2

Bastion host

0 (1 optional)

NAT gateways

2

Supported Regions

This deployment includes Citrix WAF, which isn’t currently supported in all AWS Regions. For a current list of supported Regions, see VPX-AWS support matrix in the Citrix documentation.

Certain Regions are available on an opt-in basis. See Managing AWS Regions.

EC2 key pairs

Make sure that at least one Amazon EC2 key pair exists in your AWS account in the Region where you plan to deploy the Quick Start. Make note of the key pair name. You need it during deployment. To create a key pair, see Amazon EC2 key pairs and Linux instances.

For testing or proof-of-concept purposes, we recommend creating a new key pair instead of using one that’s already being used by a production instance.

IAM permissions

Before launching the Quick Start, you must sign in to the AWS Management Console with IAM permissions for the resources that the templates deploy. The AdministratorAccess managed policy within IAM provides sufficient permissions, although your organization may choose to use a custom policy with more restrictions. For more information, see AWS managed policies for job functions.

Deployment options

This Quick Start provides two deployment options:

  • Deploy Citrix WAF into a new VPC. This option builds a new AWS environment consisting of the VPC, subnets, NAT gateways, security groups, bastion hosts, and other infrastructure components. It then deploys Citrix WAF into this new VPC.

  • Deploy Citrix WAF into an existing VPC. This option provisions Citrix WAF in your existing AWS infrastructure.

The Quick Start provides separate templates for these options. It also lets you configure Classless Inter-Domain Routing (CIDR) blocks, instance types, and Citrix WAF settings, as discussed later in this guide.

Deployment steps

Sign in to your AWS account

  1. Sign in to your AWS account at https://aws.amazon.com with an IAM user role that has the necessary permissions. For details, see Planning the deployment earlier in this guide.

  2. Use the Region selector in the navigation bar to choose the AWS Region where you want to deploy high availability across AWS Availability Zones.

  3. Make sure that your AWS account is configured correctly, as discussed in the Technical requirements section.

Subscribe to the Citrix WAF AMI

This Quick Start requires a subscription to the AMI for Citrix WAF in AWS Marketplace.

  1. Sign in to your AWS account.

  2. For the PAYG model, you can choose one of the following AWS Marketplace AMIs: Citrix WAF 200 Mbps or Citrix WAF 1000 Mbps. For the BYOL model, refer to the Software licenses section to see the available options. To retrieve the AMI ID, see Citrix Products on AWS Marketplace on GitHub.

  3. On the desired AWS Marketplace page, choose Continue to Subscribe.

  4. Review the terms and conditions for software usage, and then choose Accept Terms. A confirmation page loads, and an email confirmation is sent to the account owner. For detailed subscription instructions, see the AWS Marketplace documentation.

  5. When the subscription process is complete, exit out of AWS Marketplace without further action. Do not provision the software from AWS Marketplace—the Quick Start deploys the AMI for you.

Launch the Quick Start

You are responsible for the cost of the AWS services used while running this Quick Start reference deployment. There is no additional cost for using this Quick Start. For full details, see the pricing pages for each AWS service used by this Quick Start. Prices are subject to change.
  1. Sign in to your AWS account, and choose one of the following options to launch the AWS CloudFormation template. For help with choosing an option, see deployment options earlier in this guide.

Deploy Citrix WAF into a new VPC on AWS

Deploy Citrix WAF into an existing VPC on AWS

If you’re deploying Citrix WAF into an existing VPC, make sure that your VPC has two private subnets in different Availability Zones for the workload instances, and that the subnets aren’t shared. This Quick Start doesn’t support shared subnets. These subnets require NAT gateways in their route tables, to allow the instances to download packages and software without exposing them to the internet. Also, make sure that the domain name option in the DHCP options is configured as explained in the Amazon VPC documentation. You provide your VPC settings when you launch the Quick Start.

Each deployment takes about 15 minutes to complete.

  1. Check the AWS Region that’s displayed in the upper-right corner of the navigation bar, and change it if necessary. This is where the network infrastructure for Citrix WAF will be built. The template is launched in the us-east-2 Region by default.

  1. On the Create stack page, keep the default setting for the template URL, and then choose Next.

  2. On the Specify stack details page, change the stack name if needed. Review the parameters for the template. Provide values for the parameters that require input. For all other parameters, review the default settings and customize them as necessary.

In the following tables, parameters are listed by category and described separately for the deployment options. When you finish reviewing and customizing the parameters, choose Next.

Unless you are customizing the Quick Start templates for your own deployment projects, keep the default settings for the parameters Quick Start S3 bucket name, Quick Start S3 bucket Region, and Quick Start S3 key prefix. Changing these settings automatically updates code references to point to a new Quick Start location. For more information, see the AWS Quick Start Contributor’s Guide.

Parameters for launching into a new VPC

Table 1. VPC network configuration
Parameter label (name) Default value Description

Primary Availability Zone (PrimaryAvailabilityZone)

Requires input

Availability Zone for primary Citrix WAF deployment.

Secondary Availability Zone (SecondaryAvailabilityZone)

Requires input

Availability Zone for secondary Citrix WAF deployment.

VPC CIDR (VPCCIDR)

10.0.0.0/16

CIDR block for the VPC. Must be a valid IP CIDR range of the form x.x.x.x/x.

Restricted web app CIDR (RestrictedWebAppCIDR)

Requires input

CIDR block that is allowed to access the web apps behind WAF on TCP ports 80, 443. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses. Using 0.0.0.0/0 enables all IP addresses to access your instance using SSH.

Restricted SSH CIDR (RestrictedSSHCIDR)

Requires input

CIDR block that is allowed to access the bastion host (if present) or WAF management interface on port 22. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses. Note: Since the WAF management interface is deployed in a private subnet, initiate the SSH connection from a host with network connectivity to this private subnet, like bastion host or on-premises host with AWS Direct Connect.

Primary management private subnet CIDR (PrimaryManagementPrivateSubnetCIDR)

10.0.1.0/24

CIDR block for the primary management private subnet located in the primary Availability Zone.

Primary client public subnet CIDR (PrimaryClientPublicSubnetCIDR)

10.0.2.0/24

CIDR block for the primary client public subnet located in the primary Availability Zone.

Primary server private subnet CIDR (PrimaryServerPrivateSubnetCIDR)

10.0.3.0/24

CIDR block for the primary server private subnet located in the primary Availability Zone.

Secondary management private subnet CIDR (SecondaryManagementPrivateSubnetCIDR)

10.0.4.0/24

CIDR block for the secondary management private subnet located in the secondary Availability Zone.

Secondary client public subnet CIDR (SecondaryClientPublicSubnetCIDR)

10.0.5.0/24

CIDR block for the secondary client public subnet located in the secondary Availability Zone.

Secondary server private subnet CIDR (SecondaryServerPrivateSubnetCIDR)

10.0.6.0/24

CIDR block for the secondary server private subnet located in the secondary Availability Zone.

Primary management private IP (NSIP) (PrimaryManagementPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s management network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary management subnet CIDR.

Primary client private IP (VIP) (PrimaryClientPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s client network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary client subnet CIDR.

Primary server private IP (SNIP) (PrimaryServerPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s server network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary server subnet CIDR.

Secondary management private IP (NSIP) (SecondaryManagementPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s management network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary management subnet CIDR.

Secondary client private IP (VIP) (SecondaryClientPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s client network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary client subnet CIDR.

Secondary server private IP (SNIP) (SecondaryServerPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s server network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary server subnet CIDR.

VPC tenancy attribute (VPCTenancy)

default

Allowed tenancy of instances launched into the VPC. To launch EC2 instances dedicated to a single customer, choose dedicated. See InstanceTenancy at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-vpc.html.

Table 2. Bastion host configuration
Parameter label (name) Default value Description

Create bastion host (BastionRequired)

No

For a sandbox deployment, choose Yes from the dropdown list. This deploys a Linux bastion host in the public subnet with an Elastic IP address that gives you access to the components in the private and public subnets.

Table 3. Citrix WAF configuration
Parameter label (name) Default value Description

Key pair name (KeyPairName)

Requires input

Name of an existing public/private key pair. If you do not have one in this AWS Region, create it before continuing.

Citrix WAF instance type (CitrixADCInstanceType)

m4.xlarge

EC2 instance type to use for the WAF instances. Choose an instance type that’s available in the AWS Marketplace for the Region of deployment.

Citrix WAF AMI ID (CitrixADCImageID)

Blank string

(Optional) AMI ID of the Citrix WAF to be provisioned. If you are opting for a pooled license from ADM, enter the latest BYOL AMI ID. If opting for a PAYG subscription license, enter the AMI ID of the Citrix WAF to be provisioned. If you keep this box blank, Citrix Web App Firewall (WAF) - 200 Mbps Version 13.0-52.24 (https://aws.amazon.com/marketplace/pp/B08286P96W) is provisioned by default.

Citrix WAF IAM role (CitrixADCIAMRole)

Blank string

(Optional) If you want to use an existing role or create a new one, ensure that it has the required permissions, and then enter the name of the role. Otherwise, keep this box blank, and the deployment creates the required IAM role. See https://docs.citrix.com/en-us/citrix-adc/13/deploying-vpx/deploy-aws/prerequisites.html.

Assign Elastic IP address to client VIP (ClientEIPRequired)

Yes

Choose No to assign client Elastic IP address manually after the deployment.

Table 4. Licensing configuration
Parameter label (name) Default value Description

Pooled license from ADM (PooledLicense)

No

If choosing BYOL option for licensing, choose Yes. This would allow you to upload your already purchased licenses. Before choosing Yes, configure Citrix ADM as a license server for the Citrix ADC pooled capacity. Refer to https://docs.citrix.com/en-us/citrix-application-delivery-management-software/13/license-server/adc-pooled-capacity/configuring-adc-pooled-capacity.html#configure-citrix-adm-as-a-license-server for details.

Citrix ADM IP address (ADMIP)

Blank string

(Optional) IP address of the Citrix ADM (deployed either on-premises or as an agent in cloud) reachable from the ADC instances. If using pool licensing, enter an IP address. Otherwise, keep this box blank.

Licensing mode (LicensingMode)

Blank string

(Optional) By default, Citrix Web App Firewall (WAF) - 200 Mbps Version 13.0-52.24 (https://aws.amazon.com/marketplace/pp/B08286P96W) is provisioned. If you are opting for the BYOL license from ADM, choose Yes for PooledLicense, enter the latest BYOL AMI ID in the CitrixADCImageID box, and choose one of the three licensing modes: Pooled-Licensing, CICO-Licensing (check-in-check-out), CPU-Licensing.

License bandwidth in Mbps (Bandwidth)

0

(Optional) Specify only if the licensing mode is Pooled-Licensing. It allocates an initial bandwidth of the license in Mbps to be allocated after BYOL ADCs are created. If using, enter a multiple of 10 Mbps.

Pooled edition (PooledEdition)

Premium

(Optional) License edition for pooled capacity licensing mode. This is used only if licensing mode is Pooled-Licensing.

Appliance platform type (Platform)

Blank string

(Optional) Appliance platform type for vCPU licensing mode. If licensing mode is CICO-Licensing, choose VPX-200, VPX-1000, VPX-3000, or VPX-5000.

vCPU Edition (VCPUEdition)

Premium

(Optional) License edition for vCPU licensing mode. This is needed only if licensing mode is CPU-Licensing.

Table 5. AWS Quick Start configuration
Parameter label (name) Default value Description

Quick Start S3 bucket name (QSS3BucketName)

aws-quickstart

S3 bucket that you created for your copy of Quick Start assets. Use this if you decide to customize the Quick Start. This bucket name can include numbers, lowercase letters, uppercase letters, and hyphens but should not start or end with a hyphen.

Quick Start S3 bucket Region (QSS3BucketRegion)

us-east-1

AWS Region where the Quick Start S3 bucket (QSS3BucketName) is hosted. When using your own bucket, you must specify this value.

Quick Start S3 key prefix (QSS3KeyPrefix)

quickstart-citrix-adc-waf/

S3 key name prefix that is used to simulate a directory for your copy of Quick Start assets. Use this if you decide to customize the Quick Start. This prefix can include numbers, lowercase letters, uppercase letters, hyphens, and forward slashes. See https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html.

Parameters for launching into an existing VPC

Table 6. VPC network configuration
Parameter label (name) Default value Description

VPC ID (VPCID)

Requires input

ID of your existing VPC (e.g., vpc-0343606e).

Bastion security group ID (BastionSecurityGroupID)

Blank string

(Optional) Security group ID associated with the bastion host, if present. This is used to allow access from the bastion hosts to the interfaces belonging to the security groups that will be created for the Citrix WAF HA pair. Effectively, the bastion hosts can open connections to all WAF interfaces (management, client, and server).

Restricted SSH CIDR (RestrictedSSHCIDR)

Requires input

CIDR block that is allowed to access the bastion host (if present) or WAF management interface on port 22. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses. Note: Since the WAF management interface is deployed in a private subnet, initiate the SSH connection from a host with network connectivity to this private subnet, like bastion host or on-premises host with AWS Direct Connect.

Restricted web app CIDR (RestrictedWebAppCIDR)

Requires input

CIDR block that is allowed to access the web apps behind WAF on TCP ports 80, 443. We recommend that you use a constrained CIDR range to reduce the potential of inbound attacks from unknown IP addresses. Using 0.0.0.0/0 enables all IP addresses to access your instance using SSH.

Primary management private subnet ID (PrimaryManagementPrivateSubnetID)

Requires input

Private subnet ID of an existing subnet dedicated for primary management network interface.

Primary client public subnet ID (PrimaryClientPublicSubnetID)

Requires input

Public subnet ID of an existing subnet dedicated for primary client network interface.

Primary server private subnet ID (PrimaryServerPrivateSubnetID)

Requires input

Private subnet ID of an existing subnet dedicated for primary server network interface.

Secondary management private subnet ID (SecondaryManagementPrivateSubnetID)

Requires input

Private subnet ID of an existing subnet dedicated for secondary management network interface.

Secondary client public subnet ID (SecondaryClientPublicSubnetID)

Requires input

Public subnet ID of an existing subnet dedicated for secondary client network interface.

Secondary server private subnet ID (SecondaryServerPrivateSubnetID)

Requires input

Private subnet ID of an existing subnet dedicated for secondary server network interface.

Primary management private IP (NSIP) (PrimaryManagementPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s management network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary management subnet CIDR.

Primary client private IP (VIP) (PrimaryClientPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s client network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary client subnet CIDR.

Primary server private IP (SNIP) (PrimaryServerPrivateIP)

Blank string

(Optional) Private IP address of the primary Citrix WAF instance’s server network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the primary server subnet CIDR.

Secondary management private IP (NSIP) (SecondaryManagementPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s management network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary management subnet CIDR.

Secondary client private IP (VIP) (SecondaryClientPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s client network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary client subnet CIDR.

Secondary server private IP (SNIP) (SecondaryServerPrivateIP)

Blank string

(Optional) Private IP address of the secondary Citrix WAF instance’s server network interface. If you want to provide your own IP address, enter a number between 5 and 254 for the last octet. Otherwise, keep this box blank, and an IP address is automatically assigned from the secondary server subnet CIDR.

VPC tenancy attribute (VPCTenancy)

default

Allowed tenancy of instances launched into the VPC. To launch EC2 instances dedicated to a single customer, choose dedicated. See InstanceTenancy at https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ec2-vpc.html.

Table 7. Citrix WAF configuration
Parameter label (name) Default value Description

Key pair name (KeyPairName)

Requires input

Name of an existing public/private key pair. If you do not have one in this AWS Region, create it before continuing.

Citrix WAF instance type (CitrixADCInstanceType)

m4.xlarge

EC2 instance type to use for the WAF instances. Choose an instance type that’s available in the AWS Marketplace for the Region of deployment.

Citrix WAF AMI ID (CitrixADCImageID)

Blank string

(Optional) AMI ID of the Citrix WAF to be provisioned. If you are opting for a pooled license from ADM, enter the latest BYOL AMI ID. If opting for a PAYG subscription license, enter the AMI ID of the Citrix WAF to be provisioned. If you keep this box blank, Citrix Web App Firewall (WAF) - 200 Mbps Version 13.0-52.24 (https://aws.amazon.com/marketplace/pp/B08286P96W) is provisioned by default.

Citrix WAF IAM role (CitrixADCIAMRole)

Blank string

(Optional) If you want to use an existing role or create a new one, ensure that it has the required permissions, and then enter the name of the role. Otherwise, keep this box blank, and the deployment creates the required IAM role. See https://docs.citrix.com/en-us/citrix-adc/13/deploying-vpx/deploy-aws/prerequisites.html.

Assign Elastic IP address to client VIP (ClientEIPRequired)

Yes

Choose No to assign client Elastic IP address manually after the deployment.

Table 8. Licensing configuration
Parameter label (name) Default value Description

Pooled license from ADM (PooledLicense)

No

If choosing BYOL option for licensing, choose Yes. This would allow you to upload your already purchased licenses. Before choosing Yes, configure Citrix ADM as a license server for the Citrix ADC pooled capacity. Refer to https://docs.citrix.com/en-us/citrix-application-delivery-management-software/13/license-server/adc-pooled-capacity/configuring-adc-pooled-capacity.html#configure-citrix-adm-as-a-license-server for details.

Citrix ADM IP address (ADMIP)

Blank string

(Optional) IP address of the Citrix ADM (deployed either on-premises or as an agent in cloud) reachable from the ADC instances. If using pool licensing, enter an IP address. Otherwise, keep this box blank.

Licensing mode (LicensingMode)

Blank string

(Optional) By default, Citrix Web App Firewall (WAF) - 200 Mbps Version 13.0-52.24 (https://aws.amazon.com/marketplace/pp/B08286P96W) is provisioned. If you are opting for the BYOL license from ADM, choose Yes for PooledLicense, enter the latest BYOL AMI ID in the CitrixADCImageID box, and choose one of the three licensing modes: Pooled-Licensing, CICO-Licensing (check-in-check-out), CPU-Licensing.

License bandwidth in Mbps (Bandwidth)

0

(Optional) Specify only if the licensing mode is Pooled-Licensing. It allocates an initial bandwidth of the license in Mbps to be allocated after BYOL ADCs are created. If using, enter a multiple of 10 Mbps.

Pooled edition (PooledEdition)

Premium

(Optional) License edition for pooled capacity licensing mode. This is used only if licensing mode is Pooled-Licensing.

Appliance platform type (Platform)

Blank string

(Optional) Appliance platform type for vCPU licensing mode. If licensing mode is CICO-Licensing, choose VPX-200, VPX-1000, VPX-3000, or VPX-5000.

vCPU Edition (VCPUEdition)

Premium

(Optional) License edition for vCPU licensing mode. This is needed only if licensing mode is CPU-Licensing.

Table 9. AWS Quick Start configuration
Parameter label (name) Default value Description

Quick Start S3 bucket name (QSS3BucketName)

aws-quickstart

S3 bucket that you created for your copy of Quick Start assets. Use this if you decide to customize the Quick Start. This bucket name can include numbers, lowercase letters, uppercase letters, and hyphens but should not start or end with a hyphen.

Quick Start S3 bucket region (QSS3BucketRegion)

us-east-1

AWS Region where the Quick Start S3 bucket (QSS3BucketName) is hosted. When using your own bucket, you must specify this value.

Quick Start S3 key prefix (QSS3KeyPrefix)

quickstart-citrix-adc-waf/

S3 key name prefix that is used to simulate a folder for your copy of Quick Start assets. Use this if you decide to customize the Quick Start. This prefix can include numbers, lowercase letters, uppercase letters, hyphens, and forward slashes. See https://docs.aws.amazon.com/AmazonS3/latest/dev/UsingMetadata.html.

  1. On the Configure stack options page, you can specify tags (key-value pairs) for resources in your stack and set advanced options. When you’re finished, choose Next.

  2. On the Review page, review and confirm the template settings. Under Capabilities, select the two check boxes to acknowledge that the template creates IAM resources and might require the ability to automatically expand macros.

  3. Choose Create stack to deploy the stack.

  4. Monitor the status of the stack. When the status is CREATE_COMPLETE, the Citrix WAF deployment is ready.

  5. Use the values displayed in the Outputs tab for the stack, as shown in Figure 3, to view the created resources.

cfn_outputs
Figure 3. Citrix WAF outputs after successful deployment

Test the deployment

Connect to the primary Citrix WAF instance

Connect to the management interface of the primary Citrix WAF instance in accordance with your deployment scenario (sandbox or production):

Production deployment (no bastion host provisioned—the default)

  1. You can connect to the primary Citrix WAF instance by using a proxy server, a jump server (a Linux/Windows/FW instance running in AWS, or the bastion host) or another device reachable to that VPC, or an AWS Direct Connect connection if dealing with on-premises connectivity.

  2. Alternatively, you can make the management network interface reachable from outside the VPC. Then connect to the primary Citrix WAF instance directly using SSH, connecting to the NSIP with username nsroot, and the password being the instance ID for the primary instance.

    For testing purpose, attach two Elastic IP addresses with the primary instance so as to make the management network interface reachable from outside, one with client network interface (VIP) and the other with management interface (NSIP). To get administrative access to the primary WAF instance, use the IPv4 public IP associated with the eth0 interface as shown in Figure 4.

image_placeholder
Figure 4. Retrieving the NSIP to connect to the primary WAF instance for production deployment

Sandbox deployment (bastion host provisioned—optional)

  1. In the AWS CloudFormation console, choose the root stack.

  2. On the Outputs tab, as shown in Figure 5, note the values for LinuxBastionHostEIP1, PrimaryManagementPrivateNSIP, and PrimaryADCInstanceID.

image_placeholder
Figure 5. Citrix WAF HA pair deployment resources
  1. To store the key in your keychain, run the command ssh-add -K <your-key-pair>.pem. (On Linux terminal, you might need to omit the -K flag.)

  2. Log in to the bastion host using the following command, using the value for LinuxBastionHostEIP1 that you noted in step 2.

ssh -A ubuntu@<LinuxBastionHostEIP1>
  1. From the bastion host, as shown in Figure 6, you can connect to the primary WAF instance by using SSH with username nsroot and PrimaryManagementPrivateNSIP (associated with eth0) and password being PrimaryADCInstanceID noted in step 2.

ssh nsroot@<Primary Management Private NSIP>

Password: <Primary ADC Instance ID>
image
Figure 6. Connecting to the primary Citrix WAF instance

Validate the deployment

In the previous step, you connected to the primary Citrix WAF instance for either the production or the sandbox deployment scenarios. Here are few commands you can try.

  1. To view the current HA configuration, you can run the show ha node command.

  2. To verify that QS-Profile is present, run sh appfw profile QS-Profile command.

image
Figure 7. Citrix WAF profiles

Test failover

When the Quick Start has been deployed successfully, traffic goes through the primary Citrix WAF instance, which is configured in Availability Zone 1. During failover conditions, when the primary instance does not respond to client requests, the secondary WAF instance takes over. The Elastic IP address of the virtual IP address of the primary instance migrates to the secondary instance, which takes over as the new primary instance. We can test the deployment by verifying this failover, where Citrix WAF does the following:

  • Checks the virtual servers that have IP sets attached to them.

  • Finds the IP address that has an associated public IP address from the two IP addresses that the vserver is listening on. One that is directly attached to the vserver, and one that is attached through the IP set.

  • Reassociates the public Elastic IP address to the private IP address that belongs to the new primary virtual IP address.

To test failover, follow these steps.

  1. Run the sh ha node command. Notice that the instance master state is primary, as shown in Figure 8.

image
Figure 8. Citrix WAF nodes before failover—master state as primary
  1. Run the force ha failover command. When prompted Please confirm whether you want force-failover, as shown in Figure 9, enter Y. This initiates the failover condition.

image
Figure 9. Initiating force-failover test
  1. Run the sh ha node (show) command. Notice that the instance master state has changed to secondary, as shown in Figure 10.

image
Figure 10. After failover—master state changed to secondary
  1. In the Amazon EC2 console, check the Elastic IP address assigned to the primary WAF instance. Notice that after failover this address migrated to the secondary instance.

Best practices for using Citrix WAF on AWS

For deploying a Citrix WAF instance on AWS, certain limitations and usage information needs to be adhered to. See the limitations and usage guidelines on the Citrix website.

For information about configuration details that apply to WAF HA pair, see How high availability across AWS Availability Zones work the Citrix website.

FAQ

Q. I encountered a CREATE_FAILED error when I launched the Quick Start.

A. If AWS CloudFormation fails to create the stack, we recommend that you relaunch the template with Rollback on failure set to Disabled. (This setting is under Advanced in the AWS CloudFormation console, Options page.) With this setting, the stack’s state is retained and the instance is left running, so you can troubleshoot the issue. (For Windows, look at the log files in %ProgramFiles%\Amazon\EC2ConfigService and C:\cfn\log.)

When you set Rollback on failure to Disabled, you continue to incur AWS charges for this stack. Please make sure to delete the stack when you finish troubleshooting.

For additional information, see Troubleshooting AWS CloudFormation on the AWS website.

Q. I encountered a size limitation error when I deployed the AWS CloudFormation templates.

A. We recommend that you launch the Quick Start templates from the links in this guide or from another S3 bucket. If you deploy the templates from a local copy on your computer or from a location other than an S3 bucket, you might encounter template size limitations. For more information about AWS CloudFormation quotas, see the AWS documentation.

Q. The vserver (sample_lb_vserver) is showing as down.

A. This might be because no backend servers have been deployed. We recommend configuring service and service groups and binding them with the load-balancing virtual servers (LB vservers). For more information, see Configure service groups.

Q. While testing in my environment, the backend servers in the remote Availability Zone show as down.

A. Try one of the following options:

  • Add a static route to the remote Availability Zone server subnet by specifying the subnet IP address (SNIP) as the next hop. For more information, see Configuring static routes.

  • Change the subnet mask so that subnets in both Availability Zones are accommodated.

Q. I get the error “FAIL: Could not add licenseserver.”

A. You probably selected Yes when prompted, “Do you want to allocate license from ADM?” and then provided incorrect ADM/Agent IP, which is not reachable. To solve the issue, configure your management interface in such a way that you get access to the endpoints via NAT gateway and associate this NAT gateway with the management subnet (if not already done) in both the Availability Zones, or separate VPC endpoints for S3 and EC2 need to be configured.

Q. I get this error: Failed to create resource. See the details in CloudWatch Log Stream: HTTPSConnectionPool(host=’’, port=443): Max retries exceeded with url: /nitro/v1/config/route (Caused by NewConnectionError('<urllib3.connection.HTTPSConnection object at ‘’>: Failed to establish a new connection: [Errno 110] Connection timed out',))`

A. This could be due to an existing VPC deployment when amazonaws endpoints (ec2.amazonaws.com and s3.amazonaws.com) are not reachable. As a resolution, create a NAT gateway in the public subnet and thereby associate this NAT gateway with the management subnet (if not already done) in both the Availability Zones.

Additional resources

Send us feedback

To post feedback, submit feature ideas, or report bugs, use the Issues section of the GitHub repository for this Quick Start. To submit code, see the Quick Start Contributor’s Guide.

Quick Start reference deployments

GitHub repository

Visit our GitHub repository to download the templates and scripts for this Quick Start, to post your comments, and to share your customizations with others.


Notices

This document is provided for informational purposes only. It represents AWS’s current product offerings and practices as of the date of issue of this document, which are subject to change without notice. Customers are responsible for making their own independent assessment of the information in this document and any use of AWS’s products or services, each of which is provided “as is” without warranty of any kind, whether expressed or implied. This document does not create any warranties, representations, contractual commitments, conditions, or assurances from AWS, its affiliates, suppliers, or licensors. The responsibilities and liabilities of AWS to its customers are controlled by AWS agreements, and this document is not part of, nor does it modify, any agreement between AWS and its customers.

The software included with this paper is licensed under the Apache License, version 2.0 (the "License"). You may not use this file except in compliance with the License. A copy of the License is located at http://aws.amazon.com/apache2.0/ or in the accompanying "license" file. This code is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either expressed or implied. See the License for specific language governing permissions and limitations.