Professional Documents
Culture Documents
0
Apr 12, 20 18
FAQs
AppFlow
AutoScale
Call Home
Clustering
Connection Management
NetScaler GUI
Content Switching
Debugging
High Availability
Hardware
Integrated Caching
Load Balancing
SDX
SSL
Dual-Stack Lite
Load Balance Control-Plane T raffic that is based on Diameter, SIP, and SMPP Protocols
Provide DNS Infrastructure/T raffic Services, such as, Load Balancing, Caching, and Logging for T elecom Service
Providers
Provide Subscriber Load Distribution Using GSLB Across Core-Networks of a T elecom Service Provider
NetScaler T CP Optimization
NetScaler Solutions
Setting Up NetScaler for XenApp/XenDesktop
NetScaler in a Private Cloud Managed by Microsoft Windows Azure Pack and Cisco ACI
Features at a Glance
Hardware Platforms
Initial Configuration
T roubleshooting
Hardware FAQs
Licensing
NetScaler Licensing Overview
Upgrading an HA Pair
Downgrading an HA Pair
T roubleshooting
FAQs
Enabling AAA
Session Settings
T raffic Settings
SAML Authentication
OAuth Authentication
Admin Partitioning
Benefits and Uses of Admin Partitions
Partitioning a NetScaler
FAQs
AppExpert
Action Analytics
AppQoE
Entity T emplates
HT T P Callouts
Variables
Rate Limiting
Responder
Rewrite
String Maps
URL Sets
AppFlow
Configuring the AppFlow Feature
Application Firewall
FAQs and Deployment Guide
Introduction
Signatures
T op-Level Protections
Profiles
Policy Labels
Policies
Imports
Global Configuration
Cache Redirection
Cache Redirection Policies
Clustering
NetScaler Configuration Support in a Cluster
Cluster Overview
FAQs
Content Switching
Configuring Basic Content Switching
T roubleshooting
DataStream
Configuring Database Users
Use Case 2: Configuring the T oken Method of Load Balancing for DataStream
DataStream Reference
Caching of EDNS0 Client Subnet Data when the NetScaler Appliance is in Proxy Mode
Enterprise Environment
Multiple-Firewall Environment
GSLB Methods
GSLB Dashboard
How-to Articles
Load Balancing
How Load Balancing Works
T he Built-in Monitors
Custom Monitors
Use Case 2: Configuring Rule Based Persistence Based on a Name-Value Pair in a T CP Byte Stream
Use Case 6: Configuring Load Balancing in DSR Mode for IPv6 Networks by Using the T OS Field
Use Case 14: ShareFile Wizard for Load Balancing Citrix ShareFile
T roubleshooting
Networking
IP Addressing
Interfaces
IP Routing
T raffic Domains
VXLAN
NetScaler Extensions
NetScaler Extensions - Language Overview
Protocol Extensions
Policy Extensions
Optimization
Client Keep-Alive
HT T P Compression
Integrated Caching
Content Accelerator
SPDY (Speedy)
Media Classification
Reputation
IP Reputation
Managing Certificates
Use Case 3: Configuring SSL Acceleration with HT T P on the Front End and SSL on the Back End
Use Case 6: Configuring SSL Monitoring when Client Authentication is Enabled on the Backend Service
Support for a Hybrid FIPS Mode on the MPX/SDX 14000 FIPS Platform
T roubleshooting
SSL FAQs
Security
Content Filtering
HT T P Denial-of-Service Protection
Priority Queuing
SureConnect
Surge Protection
System
Basic Operations
T CP Configurations
HT T P Configurations
SNMP
Audit Logging
Call Home
Reporting T ool
CloudBridge Connector
High Availability
T CP Optimization
Nitro API
REST Web Services
Java API
.NET API
Python API
Reference Material
Note
T he [# XXXXXX] labels under the issue descriptions are internal tracking IDs used by the NetScaler team.
T hese release notes do not document security related fixes. For a list of security related fixes and advisories, see the Citrix
security bulletin.
T he Release History section includes all the NetScaler 12.0 builds that had been released earlier. However, builds starting only
from 53.22 are available on the Downloads site.
To view the latest release notes document (build 58.15), click this link.
T he Citrix NetScaler product is an application switch that performs application-specific traffic analysis to intelligently
distribute, optimize, and secure Layer 4-Layer 7 (L4– L7) network traffic for web applications. For example, a NetScaler
bases load balancing decisions on individual HT T P requests instead of on long-lived TCP connections, so that the failure or
slowdown of a server is managed much more quickly and with less disruption to clients. T he NetScaler feature set can be
broadly categorized as consisting of switching features, security and protection features, and server-farm optimization
features.
Switching Features
When deployed in front of application servers, a NetScaler ensures optimal distribution of traffic by the way in which it
directs client requests. Administrators can segment application traffic according to information in the body of an HT T P or
TCP request, and on the basis of L4– L7 header information such as URL, application data type, or cookie. Numerous load
balancing algorithms and extensive server health checks improve application availability by ensuring that client requests are
directed to the appropriate servers.
Optimization Features
Optimization features offload resource-intensive operations, such as Secure Sockets Layer (SSL) processing, data
compression, client keep-alive, TCP buffering, and the caching of static and dynamic content from servers. T his improves the
performance of the servers in the server farm and therefore speeds up applications. A NetScaler supports several
transparent TCP optimizations, which mitigate problems caused by high latency and congested network links, accelerating
the delivery of applications while requiring no configuration changes to clients or servers.
When a NetScaler receives traffic, the appropriate policy list determines how to process the traffic. Each policy on the list
contains one or more expressions, which together define the criteria that a connection must meet to match the policy.
For all policy types except Rewrite policies, a NetScaler implements only the first policy that a request matches, not any
additional policies that it might also match. For Rewrite policies, the NetScaler evaluates the policies in order and, in the
case of multiple matches, performs the associated actions in that order. Policy priority is important for getting the results
you want.
Depending on requirements, you can choose to configure multiple features. For example, you might choose to configure
both compression and SSL offload. As a result, an outgoing packet might be compressed and then encrypted before being
sent to the client.
Updated: 2013-09-04
A NetScaler appliance logically residing between clients and servers can be deployed in either of two physical modes: inline
and one-arm. In inline mode, multiple network interfaces are connected to different Ethernet segments, and the appliance
is placed between the clients and the servers. T he appliance has a separate network interface to each client network and a
separate network interface to each server network. T he appliance and the servers can exist on different subnets in this
configuration. It is possible for the servers to be in a public network and the clients to directly access the servers through
the appliance, with the appliance transparently applying the L4-L7 features. Usually, virtual servers (described later) are
configured to provide an abstraction of the real servers. T he following figure shows a typical inline deployment.
In one-arm mode, only one network interface of the appliance is connected to an Ethernet segment. T he appliance in this
case does not isolate the client and server sides of the network, but provides access to applications through configured
virtual servers. One-arm mode can simplify network changes needed for NetScaler installation in some environments.
For examples of inline (two-arm) and one-arm deployment, see "Understanding Common Network Topologies."
Updated: 2013-09-04
By default, all network interfaces are members of a pre-defined VLAN, VLAN 1. Address Resolution Protocol (ARP) requests
and responses are forwarded to all network interfaces that are members of the same VLAN. To avoid bridging loops, L2
mode must be disabled if another L2 device is working in parallel with the NetScaler.
For information about how the L2 and L3 modes interact, see "Configuring Modes of Packet Forwarding."
For information about configuring L2 mode, see "Enabling and Disabling Layer 2 Mode."
Updated: 2014-03-14
A NetScaler appliance can function as a packet forwarding device, and this mode of operation is called L3 mode. With L3
mode enabled, the appliance forwards any received unicast packets that are destined for an IP address that does not
belong to the appliance, if there is a route to the destination. T he appliance can also route packets between VLANs.
In both modes of operation, L2 and L3, the appliance generally drops packets that are in:
Multicast frames
Unknown protocol frames destined for an appliance's MAC address (non-IP and non-ARP)
Spanning T ree protocol (unless BridgeBPDUs is ON)
For information about how the L2 and L3 modes interact, see "Configuring Modes of Packet Forwarding."
For information about configuring the L3 mode, see "Enabling and Disabling Layer 3 Mode."
Depending on the configuration, an appliance might process the traffic before forwarding the request to a server. For
example, if the client attempts to access a secure application on the server, the appliance might perform the necessary SSL
processing before sending traffic to the server.
To facilitate efficient and secure access to server resources, an appliance uses a set of IP addresses collectively known as
NetScaler-owned IP addresses. To manage your network traffic, you assign NetScaler-owned IP addresses to virtual
entities that become the building blocks of your configuration. For example, to configure load balancing, you create virtual
servers to receive client requests and distribute them to services, which are entities representing the applications on your
servers.
To function as a proxy, a NetScaler appliance uses a variety of IP addresses. T he key NetScaler-owned IP addresses are:
IP Set
An IP set is a set of IP addresses, which are configured on the appliance as SNIP . An IP set is identified with a meaningful
name that helps in identifying the usage of the IP addresses contained in it.
Net Prof ile
A net profile (or network profile) contains an IP address or an IP set. A net profile can be bound to load balancing or
content switching virtual servers, services, service groups, or monitors. During communication with physical servers or peers,
the appliance uses the addresses specified in the profile as source IP addresses.
Because a NetScaler appliance functions as a TCP proxy, it translates IP addresses before sending packets to a server.
When you configure a virtual server, clients connect to a VIP address on the NetScaler instead of directly connecting to a
In the absence of a virtual server, when an appliance receives a request, it transparently forwards the request to the server.
T his is called the transparent mode of operation. When operating in transparent mode, an appliance translates the source
IP addresses of incoming client requests to the SNIP address but does not change the destination IP address. For this
mode to work, L2 or L3 mode has to be configured appropriately.
For cases in which the servers need the actual client IP address, the appliance can be configured to modify the HT T P
header by inserting the client IP address as an additional field, or configured to use the client IP address instead of a SNIP
address for connections to the servers.
T he configuration of a NetScaler appliance is typically built up with a series of virtual entities that serve as building blocks
for traffic management. T he building block approach helps separate traffic flows. Virtual entities are abstractions, typically
representing IP addresses, ports, and protocol handlers for processing traffic. Clients access applications and resources
through these virtual entities. T he most commonly used entities are virtual servers and services. Virtual servers represent
Most features and traffic settings are enabled through virtual entities. For example, you can configure an appliance to
compress all server responses to a client that is connected to the server farm through a particular virtual server. To configure
the appliance for a particular environment, you need to identify the appropriate features and then choose the right mix of
virtual entities to deliver them. Most features are delivered through a cascade of virtual entities that are bound to each
other. In this case, the virtual entities are like blocks being assembled into the final structure of a delivered application. You
can add, remove, modify, bind, enable, and disable the virtual entities to configure the features. T he following figure shows
the concepts covered in this section.
In the example shown in the following figure, the NetScaler appliance is configured to function as a load balancer. For this
configuration, you need to configure virtual entities specific to load balancing and bind them in a specific order. As a load
balancer, an appliance distributes client requests across several servers and thus optimizes the utilization of resources.
T he basic building blocks of a typical load balancing configuration are services and load balancing virtual servers. T he services
represent the applications on the servers. T he virtual servers abstract the servers by providing a single IP address to which
the clients connect. To ensure that client requests are sent to a server, you need to bind each service to a virtual server.
T hat is, you must create services for every server and bind the services to a virtual server. Clients use the VIP address to
connect to a NetScaler appliance. When the appliance receives client requests sent to the VIP address, it sends them to a
server determined by the load balancing algorithm. Load balancing uses a virtual entity called a monitor to track whether a
specific configured service (server plus application) is available to receive requests.
A virtual server is a named NetScaler entity that external clients can use to access applications hosted on the servers. It is
represented by an alphanumeric name, virtual IP (VIP) address, port, and protocol. T he name of the virtual server is of only
local significance and is designed to make the virtual server easier to identify. When a client attempts to access applications
on a server, it sends a request to the VIP instead of the IP address of the physical server. When the appliance receives a
request at the VIP address, it terminates the connection at the virtual server and uses its own connection with the server
on behalf of the client. T he port and protocol settings of the virtual server determine the applications that the virtual server
represents. For example, a web server can be represented by a virtual server and a service whose port and protocol are set
to 80 and HT T P, respectively. Multiple virtual servers can use the same VIP address but different protocols and ports.
Virtual servers are points for delivering features. Most features, like compression, caching, and SSL offload, are normally
enabled on a virtual server. When the appliance receives a request at a VIP address, it chooses the appropriate virtual server
by the port on which the request was received and its protocol. T he appliance then processes the request as appropriate
for the features configured on the virtual server.
In most cases, virtual servers work in tandem with services. You can bind multiple services to a virtual server. T hese services
represent the applications running on physical servers in a server farm. After the appliance processes requests received at a
VIP address, it forwards them to the servers as determined by the load balancing algorithm configured on the virtual server.
T he following figure illustrates these concepts.
Virtual servers are not always represented by specific IP addresses, port numbers, or protocols. T hey can be represented by
wildcards, in which case they are known as wildcard virtual servers. For example, when you configure a virtual server with a
wildcard instead of a VIP, but with a specific port number, the appliance intercepts and processes all traffic conforming to
that protocol and destined for the predefined port. For virtual servers with wildcards instead of VIPs and port numbers, the
appliance intercepts and processes all traffic conforming to the protocol.
Understanding Services
Services represent applications on a server. While services are normally combined with virtual servers, in the absence of a
virtual server, a service can still manage application-specific traffic. For example, you can create an HT T P service on a
NetScaler appliance to represent a web server application. When the client attempts to access a web site hosted on the
web server, the appliance intercepts the HT T P requests and creates a transparent connection with the web server.
In service-only mode, an appliance functions as a proxy. It terminates client connections, uses a SNIP address to establish a
connection to the server, and translates the source IP addresses of incoming client requests to a SNIP address. Although
the clients send requests directly to the IP address of the server, the server sees them as coming from the SNIP address.
T he appliance translates the IP addresses, port numbers, and sequence numbers.
A service is also a point for applying features. Consider the example of SSL acceleration. To use this feature, you must
create an SSL service and bind an SSL certificate to the service. When the appliance receives an HT T PS request, it decrypts
the traffic and sends it, in clear text, to the server. Only a limited set of features can be configured in the service-only case.
Services use entities called monitors to track the health of applications. Every service has a default monitor, which is based
on the service type, bound to it. As specified by the settings configured on the monitor, the appliance sends probes to the
application at regular intervals to determine its state. If the probes fail, the appliance marks the service as down. In such
cases, the appliance responds to client requests with an appropriate error message or re-routes the request as determined
by the configured load balancing policies.
A NetScaler appliance can be integrated into any network as a complement to existing load balancers, servers, caches, and
firewalls. It requires no additional client or server side software, and can be configured using the NetScaler web-based GUI
and CLI configuration utilities.
NetScaler hardware is available in a variety of platforms that have a range of hardware specifications:
Standard
Enterprise
Platinum
T he Enterprise and Standard editions have limited features available. Feature licenses are required for all editions.
For more information about NetScaler software editions, see the NetScaler Editions datasheet.
For information about how to obtain and install licenses, see Licensing.
See the following compatibility matrix tables for all NetScaler hardware platforms and the software releases supported on
these platforms:
Supported Browsers
To access the NetScaler GUI, your workstation must have a supported web browser.
To use the SDX appliance, you must complete the following tasks by following the instructions given in the resources
provided in table. Complete the tasks in the sequence given.
Task Description
Unpack your appliance and ensure all parts were delivered, prepare the site and rack, and follow
2. Prepare for installation
basic electrical safety precautions before you install your new appliance.
Rack mount the appliance, install transceivers (if available), and connect the appliance to the network
3. Install the hardware and a power source.
4. Configure the appliance Configure the initial settings of the SDX appliance by using the SDX GUI or the serial console.
Follow the steps given in the following documentations to complete these tasks:
If you encounter an IP address conflict when deploying multiple NetScaler units, check for the following possible causes:
Did you select an NSIP that is an IP address already assigned to another device on your network?
Did you assign the same NSIP to multiple NetScaler appliances?
T he NSIP is reachable on all physical ports. T he ports on a NetScaler are host ports, not switch ports.
CLI Console N
Updated: 2013-09-04
You can access the CLI either locally, by connecting a workstation to the console port, or remotely, by connecting through
secure shell (SSH) from any workstation on the same network.
If you do not have a working SSH client, you can download and install any of the following SSH client programs:
PuT T Y
"http://www.chiark.greenend.org.uk/~sgtatham/putty/"
"http://www.vandyke.com/products/securecrt/"
T hese programs have been tested by the Citrix NetScaler team, which has verified that they work correctly with a
NetScaler appliance. Other programs may also work correctly, but have not been tested.
To verify that the SSH client is installed properly, use it to connect to any device on your network that accepts SSH
connections.
Done
>
Updated: 2014-06-30
Important: A certificate-key pair is required for HT T PS access to the NetScaler configuration utility. On a NetScaler ADC, a
certificate-key pair is automatically bound to the internal services. On an MPX or SDX appliance, the default key size is 1024
bytes, and on a VPX instance, the default key size is 512 bytes. However, most browsers today do not accept a key that is
less than 1024 bytes. As a result, HT T PS access to the VPX configuration utility is blocked.
Additionally, if a license is not present on an MPX appliance when it starts, and you add a license later and restart the
appliance, you might lose the certificate binding.
Citrix recommends that you install a certificate-key pair of at least 1024 bytes on a NetScaler ADC for HT T PS access to
the configuration utility, and that you install an appropriate license before starting the ADC.
T he graphical user interface includes a configuration utility and a statistical utility, called Dashboard, either of which you
access through a workstation connected to an Ethernet port on the appliance.
T he system requirements for the workstation running the GUI are as follows:
Your workstation must have a supported web browser to access the configuration utility and Dashboard.
1. Open your web browser and enter the NetScaler IP (NSIP) as an HT T P address. If you have not yet set up the initial
configuration, enter the default NSIP (http://192.168.100.1). T he Citrix Logon page appears.
Note: If you have two NetScaler appliances in a high availability setup, make sure that you do not access the GUI by
entering the IP address of the secondary NetScaler. If you do so and use the GUI to configure the secondary NetScaler,
your configuration changes will not be applied to the primary NetScaler.
2. In the User Name text box, type nsroot.
3. In the Password text box, type the administrative password you assigned to the nsroot account during initial
configuration and click Login. T he Configuration Utility page appears.
If you need to access the online help, select Help from the Help menu at the top right corner.
To log on to Dashboard
1. Open your web browser and enter the NSIP as an HT T P address (http://<NSIP>). T he Citrix Logon page appears.
2. In the User Name text box, type nsroot.
For initial configuration of a Citrix SDX appliance, see Initial Configuration of a Citrix SDX appliance.
You can use the NIT RO API to configure the NetScaler appliance. NIT RO exposes its functionality through
Representational State Transfer (REST ) interfaces. T herefore, NIT RO applications can be developed in any programming
language. Additionally, for applications that must be developed in Java or .NET or Python, NIT RO APIs are exposed through
relevant libraries that are packaged as separate Software Development Kits (SDKs). For more information, see NIT RO API.
Each NetScaler in a high availability pair monitors the other by sending periodic messages, called heartbeat messages or
health checks, to determine the health or state of the peer node. If a health check for a primary unit fails, the secondary
unit retries the connection for a specific time period. For more information about high availability, see "High Availability." If a
retry does not succeed by the end of the specified time period, the secondary unit takes over for the primary unit in a
process called failover. T he following figure shows two high availability configurations, one in one-arm mode and the other
in two-arm mode.
In two-arm configuration, both NS1 and NS2 are connected to two switches. T he servers S1, S2, and S3 are connected to
the second switch. T he traffic between client and the servers passes through either NS1 or NS2.
To set up a high availability environment, configure one NetScaler as primary and another as secondary. Perform the
following tasks on each of the NetScalers:
Add a node.
Disable high availability monitoring for unused interfaces.
Adding a Node
Updated: 2013-06-24
A node is a logical representation of a peer NetScaler appliance. It identifies the peer unit by ID and NSIP. An appliance uses
these parameters to communicate with the peer and track its state. When you add a node, the primary and secondary
units exchange heartbeat messages asynchronously. T he node ID is an integer that must not be greater than 64.
Verify that the node you added appears in the list of nodes in the Nodes tab.
Updated: 2013-06-24
T he high availability monitor is a virtual entity that monitors an interface. You must disable the monitor for interfaces that
are not connected or being used for traffic. When the monitor is enabled on an interface whose status is DOWN, the state
of the node becomes NOT UP. In a high availability configuration, a primary node entering a NOT UP state might cause a
high availability failover. An interface is marked DOWN under the following conditions:
To disable the high availability monitor for an unused interface by using the
command line interface
At the command prompt, type the following commands to disable the high availability monitor for an unused interface and
verify that it is disabled:
To disable the high availability monitor for unused interfaces by using the
configuration utility
1. Navigate to System > Network > Interfaces.
2. Select the interface for which the monitor must be disabled.
3. Click Open. T he Modify Interface dialog box appears.
4. In HA Monitoring, select the OFF option.
5. Click OK.
6. Verify that, when the interface is selected, "HA Monitoring: OFF" appears in the details at the bottom of the page.
On a NetScaler MPX appliance virtual appliance, a certificate-key pair is automatically bound to the internal services. On a
FIPS appliance, a certificate-key pair must be imported into the hardware security module (HSM) of a FIPS card. To do so,
you must configure the FIPS card, create a certificate-key pair, and bind it to the internal services.
1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information about initializing the
HSM, see "Configuring the HSM."
2. If the appliance is part of a high availability setup, enable the SIM. For information about enabling the SIM on the
primary and secondary appliances, see "Configuring FIPS Appliances in a High Availability Setup."
3. Import the FIPS key into the HSM of the FIPS card of the appliance. At the command prompt, type:
import ssl fipskey serverkey -key ns-server.key -inform PEM
5. Bind the certificate-key created in the previous step to the following internal services. At the command prompt, type:
bind ssl service nshttps-127.0.0.1-443 -certkeyname server
1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information about initializing the
HSM, see "Configuring the HSM."
2. If the appliance is part of a high availability setup, enable the secure information system (SIM). For information about
enabling the SIM on the primary and secondary appliances, see " Configuring FIPS Appliances in a High Availability Setup."
3. Import the FIPS key into the HSM of the FIPS card of the appliance. For more information about importing a FIPS key,
see "Importing an Existing FIPS Key."
4. Navigate to T raffic Management > SSL > Certificates.
5. In the details pane, click Install.
6. In the Install Certificate dialog box, type the certificate details.
7. Click Create, and then click Close.
8. Navigate to T raffic Management > Load Balancing > Services.
9. In the details pane, on the Action tab, click Internal Services.
10. Select nshttps-127.0.0.1-443 from the list, and then click Open.
11. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add, and then click OK.
12. Select nshttps-::11-443 from the list, and then click Open.
1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information about initializing the
HSM, see "Configuring the HSM."
2. Enable the secure information system (SIM). For information about enabling the SIM on the primary and secondary
appliances, see " Configuring FIPS Appliances in a High Availability Setup."
3. Import the FIPS key into the HSM of the FIPS card of the appliance. At the command prompt, type:
import ssl fipskey serverkey -key ns-server.key -inform PEM
5. Bind the certificate-key pair to the following internal services. At the command prompt, type:
bind ssl service nsrpcs-127.0.0.1-3008 -certkeyname server
1. Initialize the hardware security module (HSM) on the FIPS card of the appliance. For information about initializing the
HSM, see "Configuring the HSM."
2. Enable the secure information system (SIM). For information about enabling the SIM on the primary and secondary
appliances, see " Configuring FIPS Appliances in a High Availability Setup."
3. Import the FIPS key into the HSM of the FIPS card of the appliance. For more information about importing a FIPS key,
see "Importing an Existing FIPS Key."
4. Navigate to T raffic Management > SSL > Certificates.
5. In the details pane, click Install.
6. In the Install Certificate dialog box, type the certificate details.
7. Click Create, and then click Close.
8. Navigate to T raffic Management > Load Balancing > Services.
9. In the details pane, on the Action tab, click Internal Services.
10. Select nsrpcs-127.0.0.1-3008 from the list, and then click Open.
11. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add, and then click OK.
12. Select nskrpcs-127.0.0.1-3009 from the list, and then click Open.
13. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add, and then click OK.
14. Select nsrpcs-::11-3008 from the list, and then click Open.
15. On the SSL Settings tab, in the Available pane, select the certificate created in step 7, click Add, and then click OK.
16. Click OK.
17. Navigate to System > Network > RPC
18. In the details pane, select the IP address, and click Open.
19. In the Configure RPC Node dialog box, select Secure.
20. Click OK.
In a two-arm topology, one network interface is connected to the client network and another network interface is
connected to the server network, ensuring that all traffic flows through the appliance. T his topology might require you to
reconnect your hardware and also might result in a momentary downtime. T he basic variations of two-arm topology are
multiple subnets, typically with the appliance on a public subnet and the servers on a private subnet, and transparent mode,
with both the appliance and the servers on the public network.
Setting Up a Simple Two-Arm Multiple Subnet Topology
One of the most commonly used topologies has the NetScaler appliance inline between the clients and the servers, with a
virtual server configured to handle the client requests. T his configuration is used when the clients and servers reside on
different subnets. In most cases, the clients and servers reside on public and private subnets, respectively.
For example, consider an appliance deployed in two-arm mode for managing servers S1, S2, and S3, with a virtual server of
type HT T P configured on the appliance, and with HT T P services running on the servers. T he servers are on a private subnet
and a SNIP is configured on the appliance to communicate with the servers. T he Use SNIP (USNIP) option must be enabled
on the appliance so that it uses the SNIP instead of the MIP.
As shown in the following figure, the VIP is on public subnet 217.60.10.0, and the NSIP, the servers, and the SNIP are on
private subnet 192.168.100.0/24.
1. Configure the NSIP and default gateway, as described in "Configuring the NetScaler IP Address (NSIP)."
2. Configure the SNIP, as described in "Configuring Subnet IP Addresses."
3. Enable the USNIP option, as described in "T o enable or disable USNIP mode."
4. Configure the virtual server and the services, as described in "Creating a Virtual Server" and "Configuring Services."
5. Connect one of the network interfaces to a private subnet and the other interface to a public subnet.
1. Configure the NSIP, MIP, and default gateway, as described in "Configuring a NetScaler by Using the Command Line
Interface."
2. Enable L2 mode, as described in "Enabling and Disabling Layer 2 Mode."
3. Configure the default gateway of the managed servers as the MIP.
4. Connect the network interfaces to the appropriate ports on the switch.
T he two basic variations of one-arm topology are with a single subnet and with multiple subnets.
1. Configure the NSIP, MIP, and the default gateway, as described in "Configuring the NetScaler IP Address (NSIP)".
2. Configure the virtual server and the services, as described in "Creating a Virtual Server" and "Configuring Services".
3. Connect one of the network interfaces to the switch.
1. Configure the NSIP and the default gateway, as described in "Configuring the NetScaler IP Address (NSIP)".
2. Configure the SNIP and enable the USNIP option, as described in "Configuring Subnet IP Addresses".
3. Configure the virtual server and the services, as described in "Creating a Virtual Server" and "Configuring Services".
4. Connect one of the network interfaces to the switch.
Note: In addition to the tasks listed above, you can configure Syslog logging. For instructions, see “Audit Logging.”
You can also configure a NetScaler appliance to open FT P connections on a controlled range of ports instead of ephemeral
ports for data connections. T his improves security, because opening all ports on the firewall is insecure. You can set the
range anywhere from 1,024 to 64,000.
Before deployment, go through the verification checklists to verify your configuration. To configure HT T P parameters and
the FT P port range, use the NetScaler configuration utility.
You can modify the types of HT T P parameters described in the following table.
HT T P Port T he web server HT T P ports used by your managed servers. If you specify the ports, the
Information appliance performs request switching for any client request that has a destination port
matching a specified port.
Note: If an incoming client request is not destined for a service or a virtual server that is
specifically configured on the appliance, the destination port in the request must match one of
the globally configured HT T P ports. T his allows the appliance to perform connection keep-alive
and server off-load.
Limits T he maximum number of connections to each managed server, and the maximum number of
requests sent over each connection. For example, if you set Max Connections to 500, and the
appliance is managing three servers, it can open a maximum of 500 connections to each of the
three servers. By default, the appliance can create an unlimited number of connections to any
of the servers it manages. To specify an unlimited number of requests per connection, set Max
Requests to 0.
Note: If you are using the Apache HT T P server, you must set Max Connections equal to the
value of the MaxClients parameter in the Apache httpd.conf file. Setting this parameter is
optional for other web servers.
Client IP Insertion Enable/disable insertion of the client's IP address into the HT T P request header. You can
specify a name for the header field in the adjacent text box. When a web server managed by an
appliance receives a mapped IP address or a subnet IP address, the server identifies it as the
client’s IP address. Some applications need the client’s IP address for logging purposes or to
dynamically determine the content to be served by the web server.
You can enable insertion of the actual client IP address into the HT T P header request sent
from the client to one, some, or all servers managed by the appliance. You can then access the
Cookie Version T he HT T P cookie version to use when COOKIEINSERT persistence is configured on a virtual
server. T he default, version 0, is the most common type on the Internet. Alternatively, you can
specify version 1.
Requests/Responses Options for handling certain types of requests, and enable/disable logging of HT T P error
responses.
An appliance can use the following modes to forward the packets it receives:
Updated: 2013-09-13
Layer 2 mode controls the Layer 2 forwarding (bridging) function. You can use this mode to configure a NetScaler appliance
to behave as a Layer 2 device and bridge the packets that are not destined for it. When this mode is enabled, packets are
not forwarded to any of the MAC addresses, because the packets can arrive on any interface of the appliance and each
interface has its own MAC address.
With Layer 2 mode disabled (which is the default), the appliance drops packets that are not destined for one of its MAC
address. If another Layer 2 device is installed in parallel with the appliance, Layer 2 mode must be disabled to prevent
Note: T he appliance does not support spanning tree protocol. T o avoid loops, if you enable L2 mode, do not connect two
interfaces on the appliance to the same broadcast domain.
To enable or disable Layer 2 mode by using the command line interface
At the command prompt, type the following commands to enable/disable Layer 2 mode and verify that it has been
enabled/disabled:
Updated: 2013-09-13
Layer 3 mode controls the Layer 3 forwarding function. You can use this mode to configure a NetScaler appliance to look
at its routing table and forward packets that are not destined for it. With Layer 3 mode enabled (which is the default), the
appliance performs route table lookups and forwards all packets that are not destined for any appliance-owned IP address.
If you disable Layer 3 mode, the appliance drops these packets.
Updated: 2013-09-13
You can use MAC-based forwarding to process traffic more efficiently and avoid multiple-route or ARP lookups when
forwarding packets, because the NetScaler appliance remembers the MAC address of the source. To avoid multiple lookups,
the appliance caches the source MAC address of every connection for which it performs an ARP lookup, and it returns the
data to the same MAC address.
MAC-based forwarding is useful when you use VPN devices because the appliance ensures that all traffic flowing through a
particular VPN passes through the same VPN device.
T he source (a transmitting device such as router, firewall, or VPN device) of the inbound connection.
T he server that responds to the requests.
When a server responds through an appliance, the appliance sets the destination MAC address of the response packet to
the cached address, ensuring that the traffic flows in a symmetric manner, and then forwards the response to the client.
T he process bypasses the route table lookup and ARP lookup functions. However, when an appliance initiates a
connection, it uses the route and ARP tables for the lookup function. To enable MAC-based forwarding, use the
configuration utility or the command line.
Some deployments require the incoming and outgoing paths to flow through different routers. In these situations, MAC-
based forwarding breaks the topology design. For a global server load balancing (GSLB) site that requires the incoming and
outgoing paths to flow through different routers, you must disable MAC-based forwarding and use the appliance’s default
router as the outgoing router.
With MAC-based forwarding disabled and Layer 2 or Layer 3 connectivity enabled, a route table can specify separate
routers for outgoing and incoming connections. To disable MAC-based forwarding, use the configuration utility or the
command line.
Virtual LANs
T he NetScaler supports (Layer 2) port and IEEE802.1Q tagged virtual LANs (VLANs). VLAN configurations are useful when
you need to restrict traffic to certain groups of stations. You can configure a network interface to belong to multiple
VLANs by using IEEE 802.1q tagging.
You can bind your configured VLANs to IP subnets. T he NetScaler (if it is configured as the default router for the hosts on
the subnets) then performs IP forwarding between these VLANs. A NetScaler supports the following types of VLANs.
Link aggregation combines incoming data from multiple ports into a single high speed link. Configuring the link aggregate
channel increases the capacity and availability of the communication channel between a NetScaler and other connected
devices. An aggregated link is also referred to as a channel.
When a network interface is bound to a channel, the channel parameters have precedence over the network interface
parameters. A network interface can be bound to only one channel. Binding a network interface to a link aggregate
channel changes the VLAN configuration. T hat is, binding network interfaces to a channel removes them from the VLANs
that they originally belonged to and adds them to the default VLAN. However, you can bind the channel back to the old
VLAN, or to a new one. For example, if you have bound network interfaces 1/2 and 1/3 to a VLAN with ID 2, and then you
bind them to link aggregate channel LA/1, the network interfaces are moved to the default VLAN, but you can bind them
to VLAN 2.
Note: You can also use Link Aggregation Control Protocol (LACP) to configure link aggregation. For more information, see
Configuring Link Aggregation by Using the Link Aggregation Control Protocol.
If you do not have a local NT P server, you can find a list of public, open access, NT P servers at the official NT P site at
http://www.ntp.org.
restrict 127.0.0.2
T hese entries are required only if you want to run the device as a time server. However, this feature is not supported on
the NetScaler.
3. Edit /nsconfig/ntp.conf by typing the IP address for the desired NT P server under the file’s server and restrict entries.
4. Create a file named rc.netscaler in the /nsconfig directory, if the file does not already exist in the directory.
5. Edit /nsconfig/rc.netscaler by adding the following entry: /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ntpd.log &
T his entry starts the ntpd service, checks the ntp.conf file, and logs messages in the /var/log directory.
Note: If the time difference between the NetScaler and the time server is more than 1000 sec, the ntpd service
terminates with a message to the NetScaler log. T o avoid this, you need to start ntpd with the -g option, which forcibly
syncs the time. Add the following entry in /nsconfig/rc.netscaler:
/usr/sbin/ntpd -g -c /nsconfig/ntp.conf -l /var/log/ntpd.log &
If you do not want to forcibly sync the time when there is a large difference, you can set the date manually and then
start ntpd again. You can check the time difference between the appliance and the time server by running the following
command in the shell:
A common practice is to configure an appliance as a forwarder. For this configuration, you need to add external name
servers. After you have added the external servers, you should verify that your configuration is correct.
You can add, remove, enable, and disable external name servers. You can create a name server by specifying its IP address, or
you can configure an existing virtual server as the name server.
When adding name servers, you can specify IP addresses or virtual IP addresses (VIPs). If you use IP addresses, the appliance
load balances requests to the configured name servers in a round robin manner. If you use VIPs, you can specify any load
balancing method.
At the command prompt, type the following commands to add a name server and verify the configuration:
SNMP monitoring uses traps messages and alarms. SNMP traps messages are asynchronous events that the agent
generates to signal abnormal conditions, which are indicated by alarms. For example, if you want to be informed when CPU
utilization is above 90 percent, you can set up an alarm for that condition. T he following figure shows a network with a
NetScaler that has SNMP enabled and configured.
T he SNMP agent on a NetScaler supports SNMP version 1 (SNMPv1), SNMP version 2 (SNMPv2), and SNMP version 3
(SNMPv3). Because it operates in bilingual mode, the agent can handle SNMPv2 queries, such as Get-Bulk, and SNMPv1
queries. T he SNMP agent also sends traps compliant with SNMPv2 and supports SNMPv2 data types, such as counter64.
SNMPv1 managers (programs on other servers that request SNMP information from the NetScaler) use the NS-MIB-
smiv1.mib file when processing SNMP queries. SNMPv2 managers use the NS-MIB-smiv2.mib file.
To configure SNMP, you specify which managers can query the SNMP agent, add SNMP trap listeners that will receive the
SNMP trap messages, and configure SNMP Alarms.
Updated: 2013-06-05
Updated: 2013-09-13
After configuring the alarms, you need to specify the trap listener to which the appliance will send the trap messages. Apart
from specifying parameters like IP address and the destination port of the trap listener, you can specify the type of trap
(either generic or specific) and the SNMP version.
You can configure a maximum of 20 trap listeners for receiving either generic or specific traps.
Updated: 2013-09-13
You configure alarms so that the appliance generates a trap message when an event corresponding to one of the alarms
occurs. Configuring an alarm consists of enabling the alarm and setting the severity level at which a trap is generated. T here
are five severity levels: Critical, Major, Minor, Warning, and Informational. A trap is sent only when the severity of the alarm
matches the severity specified for the trap.
Some alarms are enabled by default. If you disable an SNMP alarm, the appliance will not generate trap messages when
corresponding events occur. For example, if you disable the Login-Failure SNMP alarm, the appliance will not generate a trap
message when a login failure occurs.
To set the severity of the alarm by using the command line interface
At the command prompt, type the following commands to set the severity of the alarm and verify that the severity has
been set correctly:
Configuration Checklist
_________________________________________
If the NetScaler is placed behind an external load balancer, then the load balancing policy on the external load balancer
is not “least connection.”
T he load balancing policy configured on the external load balancer is:
_________________________________________
If the NetScaler is placed in front of a firewall, the session time-out on the firewall is set to a value greater than or equal
to 300 seconds.
Note: T he T CP idle connection timeout on a NetScaler appliance is 360 seconds. If the timeout on the firewall is also set
to 300 seconds or more, then the appliance can perform T CP connection multiplexing effectively because connections
will not be closed earlier.
T he value configured for the session time-out is: ___________________
T he default gateway has been set to the correct value. (T he default gateway should either be a NetScaler or upstream
router.) T he default gateway is:
_________________________________________
If the Microsoft® Internet Information Server is used, buffering is enabled on the server.
If an Apache Server is used, the MaxConn (maximum number of connections) parameter is configured on the server and
on the NetScaler.
T he MaxConn (maximum number of connections) value that has been set is:
_________________________________________
If a Netscape® Enterprise Server™ is used, the maximum requests per connection parameter is set on the NetScaler. T he
maximum requests per connection value that has been set is:
_________________________________________
Does the Layer 2 mode feature need to be disabled? (Disable if another Layer 2 device is working in parallel with a
NetScaler.)
Reason for enabling or disabling:
_________________________________________
Does the MAC-based forwarding feature need to be disabled? (If the MAC address used by return traffic is different, it
should be disabled.)
Reason for enabling or disabling:
_________________________________________
Does host-based reuse need to be disabled? (Is there virtual hosting on the servers?)
Reason for enabling or disabling:
_________________________________________
_________________________________________
Access Checklist
Note: When you are using the ping utility, ensure that the pinged server has ICMP ECHO enabled, or your ping will not
succeed.
Firewall Checklist
To configure load balancing, you define a virtual server to proxy multiple servers in a server farm and balance the load among
them.
When a client initiates a connection to the server, a virtual server terminates the client connection and initiates a new
connection with the selected server, or reuses an existing connection with the server, to perform load balancing. T he load
balancing feature provides traffic management from Layer 4 (TCP and UDP) through Layer 7 (FT P, HT T P, and HT T PS).
T he NetScaler appliance uses a number of algorithms, called load balancing methods, to determine how to distribute the
load among the servers. T he default load balancing method is the Least Connections method.
A typical load balancing deployment consists of the entities described in the following figure.
Virt ual server. An entity that is represented by an IP address, a port, and a protocol. T he virtual server IP address (VIP) is
usually a public IP address. T he client sends connection requests to this IP address. T he virtual server represents a bank
of servers.
Service . A logical representation of a server or an application running on a server. Identifies the server's IP address, a
port, and a protocol. T he services are bound to the virtual servers.
Server object . An entity that is represented by an IP address. T he server object is created when you create a service.
T he IP address of the service is taken as the name of the server object. You can also create a server object and then
Note: After you deploy the configuration, you can display statistics that show how the entities in the configuration are
performing. Use the statistical utility or the stat lb vserver <vserverName> command.
Optionally, you can assign weights to a service. T he load balancing method then uses the assigned weight to select a
service. For getting started, however, you can limit optional tasks to configuring some basic persistence settings, for
sessions that must maintain a connection to a particular server, and some basic configuration-protection settings.
Before configuring load balancing, make sure that the load balancing feature is enabled.
enable feature lb
show feature
Example
Updated: 2013-06-24
When you have identified the services you want to load balance, you can implement your initial load balancing configuration
by creating the service objects, creating a load balancing virtual server, and binding the service objects to the virtual server.
To implement the initial load balancing configuration by using the command line
interface
At the command prompt, type the following commands to implement and verify the initial configuration:
If persistence is configured, it overrides the load balancing methods once the server has been selected. If the configured
persistence applies to a service that is down, the appliance uses the load balancing methods to select a new service, and
the new service becomes persistent for subsequent requests from the client. If the selected service is in an Out Of Service
state, it continues to serve the outstanding requests but does not accept new requests or connections. After the
shutdown period elapses, the existing connections are closed. T he following table lists the types of persistence that you
can configure.
T able 1. Limit at ions on Number of Simult aneous P ersist ent Connect ions
CookieInsert, URL passive, Custom Memory limit. In case of CookieInsert, if time out is not 0, any number of
Server ID connections is allowed until limited by memory.
If the configured persistence cannot be maintained because of a lack of resources on an appliance, the load balancing
methods are used for server selection. Persistence is maintained for a configured period of time, depending on the
persistence type. Some persistence types are specific to certain virtual servers. T he following table shows the relationship.
T able 2. P ersist ence T ypes Available f or Each T ype of Virt ual Server
Two commonly used persistence types are persistence based on cookies and persistence based on server IDs in URLs.
Updated: 2013-08-23
When you enable persistence based on cookies, the NetScaler adds an HT T P cookie into the Set-Cookie header field of
the HT T P response. T he cookie contains information about the service to which the HT T P requests must be sent. T he
client stores the cookie and includes it in all subsequent requests, and the NetScaler uses it to select the service for those
requests. You can use this type of persistence on virtual servers of type HT T P or HT T PS.
where:
<NSC_XXXX> is the virtual server ID that is derived from the virtual server name.
<ServiceIP> is the hexadecimal value of the IP address of the service.
<ServicePort> is the hexadecimal value of the port of the service.
T he NetScaler encrypts ServiceIP and ServicePort when it inserts a cookie, and decrypts them when it receives a cookie.
Note: If the client is not allowed to store the HT T P cookie, the subsequent requests do not have the HT T P cookie, and
persistence is not honored.
By default, the NetScaler sends HT T P cookie version 0, in compliance with the Netscape specification. It can also send
version 1, in compliance with RFC 2109.
You can configure a timeout value for persistence that is based on HT T P cookies. Note the following:
If HT T P cookie version 0 is used, the NetScaler inserts the absolute Coordinated Universal T ime (GMT ) of the cookie’s
expiration (the expires attribute of the HT T P cookie), calculated as the sum of the current GMT time on a NetScaler,
and the timeout value.
If an HT T P cookie version 1 is used, the NetScaler inserts a relative expiration time (Max-Age attribute of the HT T P
cookie). In this case, the client software calculates the actual expiration time.
Note: Most client software currently installed (Microsoft Internet Explorer and Netscape browsers) understand HT T P
cookie version 0; however, some HT T P proxies understand HT T P cookie version 1.
If you set the timeout value to 0, the NetScaler does not specify the expiration time, regardless of the HT T P cookie
version used. T he expiration time then depends on the client software, and such cookies are not valid if that software is
shut down. T his persistence type does not consume any system resources. T herefore, it can accommodate an unlimited
number of persistent clients.
An administrator can use the procedure in the following table to change the HT T P cookie version.
Note: For information about the parameters, see "Configuring Persistence Based on Cookies."
To configure persistence based on cookies by using the command line interface
At the command prompt, type the following commands to configure persistence based on cookies and verify the
configuration:
set lb vserver <name> -persistenceT ype COOKIEINSERT
show lb vserver <name>
Example
Updated: 2013-08-23
T he NetScaler can maintain persistence based on the server IDs in the URLs. In a technique called URL passive persistence,
the NetScaler extracts the server ID from the server response and embeds it in the URL query of the client request. T he
server ID is an IP address and port specified as a hexadecimal number. T he NetScaler extracts the server ID from
subsequent client requests and uses it to select the server.
URL passive persistence requires configuring either a payload expression or a policy infrastructure expression specifying the
location of the server ID in the client requests. For more information about expressions, see "Policy Configuration and
Reference."
T he expression, URLQUERY contains sid= configures the system to extract the server ID from the URL query of a client
request, after matching token sid=. T hus, a request with the URL http://www.citrix.com/index.asp?&sid;=c0a864100050 is
directed to the server with the IP address10.102.29.10 and port 80.
T he timeout value does not affect this type of persistence, which is maintained as long as the server ID can be extracted
from the client requests. T his persistence type does not consume any system resources, so it can accommodate an
unlimited number of persistent clients.
Updated: 2013-06-24
You can configure a redirect URL to communicate the status of the appliance in the event that a virtual server of type
HT T P or HT T PS is down or disabled. T his URL can be a local or remote link. T he appliance uses HT T P 302 redirect.
Redirects can be absolute URLs or relative URLs. If the configured redirect URL contains an absolute URL, the HT T P redirect
is sent to the configured location, regardless of the URL specified in the incoming HT T P request. If the configured redirect
URL contains only the domain name (relative URL), the HT T P redirect is sent to a location after appending the incoming URL
to the domain configured in the redirect URL.
Note: If a load balancing virtual server is configured with both a backup virtual server and a redirect URL, the backup virtual
server takes precedence over the redirect URL. In this case, a redirect is used when both the primary and backup virtual
servers are down.
To configure a virtual server to redirect client requests to a URL by using the
command line interface
At the command prompt, type the following commands to configure a virtual server to redirect client requests to a URL and
verify the configuration:
Updated: 2013-06-24
If the primary virtual server is down or disabled, the appliance can direct the connections or client requests to a backup
virtual server that forwards the client traffic to the services. T he appliance can also send a notification message to the
client regarding the site outage or maintenance. T he backup virtual server is a proxy and is transparent to the client.
You can configure a backup virtual server when you create a virtual server or when you change the optional parameters of
an existing virtual server. You can also configure a backup virtual server for an existing backup virtual server, thus creating a
cascaded backup virtual server. T he maximum depth of cascading backup virtual servers is 10. T he appliance searches for a
backup virtual server that is up and accesses that virtual server to deliver the content.
You can configure URL redirection on the primary for use when the primary and the backup virtual servers are down or have
reached their thresholds for handling requests.
Note: If no backup virtual server exists, an error message appears, unless the virtual server is configured with a redirect URL.
If both a backup virtual server and a redirect URL are configured, the backup virtual server takes precedence.
To configure a backup virtual server by using the command line interface
At the command prompt, type the following commands to configure a backup server and verify the configuration:
T he virtual server selects the service and assigns it to serve client requests. Consider the scenario in the preceding figure,
where the services service-HT T P-1 and service-HT T P-2 are created and bound to the virtual server named virtual server-LB-
1. Virtual server-LB-1 forwards the client request to either service-HT T P-1 or service-HT T P-2. T he system selects the service
for each request by using the Least Connections load balancing method. T he following table lists the names and values of
the basic entities that must be configured on the system.
T he following figure shows the load balancing sample values and required parameters that are described in the preceding
T he following tables list the commands used to configure this load balancing setup by using the command line interface.
T ask Command
T o create a service named service-HT T P-1 add service service-HT T P-1 10.102.29.5 HT T P
80
T o create a service named service-HT T P-2 add service service-HT T P-2 10.102.29.6
HT T P 80
T o bind a service named service-HT T P-1 to a virtual server named bind lb vserver vserver-LB-1 service-HT T P-1
vserver-LB-1
T o bind a service named service-HT T P-2 to a virtual server named bind lb vserver vserver-LB-1 service-HT T P-2
vserver-LB-1
For more information about the initial configuration tasks, see "Enabling Load Balancing" and "Configuring Services and a
Vserver."
T ask Command
T o view the properties of a virtual server named vserver-LB-1 show lb vserver vserver-LB-1
T o view the properties of a service named service-HT T P-1 show service service-HT T P-1
T o view the statistics of a service named service-HT T P-1 stat service service-HT T P-1
T o view the bindings of a service named service-HT T P-1 show service bindings service-HT T P-1
T ask Command
T o configure persistence on a virtual server named vserver- set lb vserver vserver-LB-1 -persistenceT ype SOURCEIP -
LB-1 persistenceMask 255.255.255.255 -timeout 2
T o configure COOKIEINSERT persistence on a virtual server set lb vserver vserver-LB-1 -persistenceT ype
named vserver-LB-1 COOKIEINSERT
T o configure URLPassive persistence on a virtual server set lb vserver vserver-LB-1 -persistenceT ype URLPASSIVE
named vserver-LB-1
T o configure a virtual server to redirect the client request set lb vserver vserver-LB-1 -redirectURL
to a URL on a virtual server named vserver-LB-1 http://www.newdomain.com/mysite/maintenance
T o set a backup virtual server on a virtual server named set lb vserver vserver-LB-1 -backupVserver vserver-LB-2
vserver-LB-1
For more information about configuring persistence, see "Choosing and Configuring Persistence Settings." For information
about configuring a virtual server to redirect a client request to a URL and setting up a backup virtual server, see "Configuring
Features to Protect the Load Balancing Configuration."
NetScaler compression is a policy-based feature. A policy filters requests and responses to identify responses to be
compressed, and specifies the type of compression to apply to each response. T he appliance provides several built-in
policies to compress common MIME types such as text/html, text/plain, text/xml, text/css, text/rtf, application/msword,
application/vnd.ms-excel, and application/vnd.ms-powerpoint. You can also create custom policies. T he appliance does not
compress compressed MIME types such as application/octet-stream, binary, bytes, and compressed image formats such as
GIF and JPEG.
To configure compression, you must enable it globally and on each service that will provide responses that you want
compressed. If you have configured virtual servers for load balancing or content switching, you should bind the polices to
the virtual servers. Otherwise, the policies apply to all traffic that passes through the appliance.
Updated: 2013-08-22
T he following flow chart shows the sequence of tasks for configuring basic compression in a load balancing setup.
Updated: 2013-06-07
By default, compression is not enabled. You must enable the compression feature to allow compression of HT T P responses
that are sent to the client.
Updated: 2013-08-22
In addition to enabling compression globally, you must enable it on each service that will deliver files to be compressed.
Updated: 2013-09-04
If you bind a policy to a virtual server, the policy is evaluated only by the services associated with that virtual server. You can
bind compression policies to a virtual server either from the Configure Virtual Server (Load Balancing) dialog box or from the
Compression Policy Manager dialog box. T his topic includes instructions to bind compression policies to a load balancing
virtual server by using the Configure Virtual Server (Load Balancing) dialog box. For information about how you can bind a
compression policy to a load balancing virtual server by using the Compression Policy Manager dialog box, see "Configuring
and Binding Policies with the Policy Manager."
To configure SSL, you must first enable it. T hen, you configure HT T P or TCP services and an SSL virtual server on the
appliance, and bind the services to the virtual server. You must also add a certificate-key pair and bind it to the SSL virtual
server. If you use Outlook Web Access servers, you must create an action to enable SSL support and a policy to apply the
action. An SSL virtual server intercepts incoming encrypted traffic and decrypts it by using a negotiated algorithm. T he SSL
virtual server then forwards the decrypted data to the other entities on the appliance for appropriate processing.
To configure SSL, you must first enable it. T hen, you must create an SSL virtual server and HT T P or TCP services on the
NetScaler. Finally, you must bind a valid SSL certificate and the configured services to the SSL virtual server.
An SSL virtual server intercepts incoming encrypted traffic and decrypts it using a negotiated algorithm. T he SSL virtual
server then forwards the decrypted data to the other entities on the NetScaler for appropriate processing.
T he following flow chart shows the sequence of tasks for configuring a basic SSL offload setup.
A service on the appliance represents an application on a server. Once configured, services are in the disabled state until the
appliance can reach the server on the network and monitor its status. T his topic covers the steps to create an HT T P
service.
Note: For T CP traffic, perform the procedures in this and the following topics, but create T CP services instead of HT T P
services.
To add an HTTP service by using the command line interface
At the command prompt, type the following commands to add a HT T P service and verify the configuration:
In a basic SSL offloading setup, the SSL virtual server intercepts encrypted traffic, decrypts it, and sends the clear text
messages to the services that are bound to the virtual server. Offloading CPU-intensive SSL processing to the appliance
allows the back-end servers to process a greater number of requests.
Caution: T o ensure secure connections, you must bind a valid SSL certificate to the SSL-based virtual server before you
enable it.
To add an SSL-based virtual server by using the configuration utility
1. Navigate to T raffic Management > SSL Offload > Virtual Servers.
2. In the details pane, click Add.
3. In the Create Virtual Server (SSL Offload) dialog box, in the Name, IP Address, and Port text boxes, type the name of the
virtual server, IP address, and port (for example, Vserver-SSL-1, 10.102.29.50, and 443).
4. In the Protocol list, select the type of the virtual server, for example, SSL.
5. Click Create, and then click Close.
6. Verify that the parameters you configured are correctly configured by selecting the virtual server and viewing the Details
section at the bottom of the pane. T he virtual server is marked as DOWN because a certificate-key pair and services
have not been bound to it.
Caution: T o ensure secure connections, you must bind a valid SSL certificate to the SSL-based virtual server before you
enable it.
After decrypting the incoming data, the SSL virtual server forwards the data to the services that you have bound to the
virtual server.
Data transfer between the appliance and the servers can be encrypted or in clear text. If the data transfer between the
appliance and the servers is encrypted, the entire transaction is secure from end to end. For more information about
configuring the system for end-to-end security, see "SSL Offload and Acceleration."
An SSL certificate is an integral element of the SSL Key-Exchange and encryption/decryption process. T he certificate is
used during SSL handshake to establish the identity of the SSL server. You can use a valid, existing SSL certificate that you
have on the NetScaler appliance, or you can create your own SSL certificate. T he appliance supports RSA/DSA certificates
of up to 4096 bits.
Note: Citrix recommends that you use a valid SSL certificate that has been issued by a trusted certificate authority. Invalid
certificates and self-created certificates are not compatible with all SSL clients.
Before a certificate can be used for SSL processing, you must pair it with its corresponding key. T he certificate key pair is
then bound to the virtual server and used for SSL processing.
After you have paired an SSL certificate with its corresponding key, you must bind the certificate key pair to the SSL virtual
server so that it can be used for SSL processing. Secure sessions require establishing a connection between the client
computer and an SSL-based virtual server on the appliance. SSL processing is then carried out on the incoming traffic at the
virtual server. T herefore, before enabling the SSL virtual server on the appliance, you need to bind a valid SSL certificate to
the SSL virtual server.
To bind an SSL certificate key pair to a virtual server by using the command line
interface
At the command prompt, type the following commands to bind an SSL certificate key pair to a virtual server and verify the
configuration:
bind ssl vserver <vServerName> -certkeyName <string>
show ssl vserver <name>
Example
To bind an SSL certificate key pair to a virtual server by using the configuration
utility
1. Navigate to T raffic Management > SSL Offload > Virtual Servers.
2. Select the virtual server to which you want to bind the certificate key pair, for example, Vserver-SSL-1, and click Open.
3. In the Configure Virtual Server (SSL Offload) dialog box, on the SSL Settings tab, under Available, select the certificate
key pair that you want to bind to the virtual server (for example, Certkey-SSL-1), and then click Add.
4. Click OK.
5. Verify that the certificate key pair that you selected appears in the Configured area.
If you use Outlook Web Access (OWA) servers on your NetScaler appliance, you must configure the appliance to insert a
special header field, FRONT -END-HT T PS: ON, in HT T P requests directed to the OWA servers, so that the servers generate
URL links as https:// instead of http://.
Note: You can enable OWA support for HT T P-based SSL virtual servers and services only. You cannot apply it for T CP-
based SSL virtual servers and services.
To configure OWA support, do the following:
Before you can enable Outlook Web Access (OWA) support, you must create an SSL action. SSL actions are bound to SSL
policies and triggered when incoming data matches the rule specified by the policy.
SSL policies are created by using the policy infrastructure. Each SSL policy has an SSL action bound to it, and the action is
carried out when incoming traffic matches the rule that has been configured in the policy.
At the command prompt, type the following commands to configure an SSL policy and verify the configuration:
After you configure an SSL policy for Outlook Web Access, bind the policy to a virtual server that will intercept incoming
Outlook traffic. If the incoming data matches any of the rules configured in the SSL policy, the policy is triggered and the
action associated with it is carried out.
At the command prompt, type the following commands to bind an SSL policy to an SSL virtual server and verify the
configuration:
To understand the order in which the features perform their processing, see Processing Order of Features section.
Load Balancing
Load balancing decisions are based on a variety of algorithms, including round robin, least connections, weighted least
bandwidth, weighted least packets, minimum response time, and hashing based on URL, domain source IP, or destination IP.
Both the T CP and UDP protocols are supported, so the NetScaler can load balance all traffic that uses those protocols as
the underlying carrier (for example, HT T P, HT T PS, UDP, DNS, NNT P, and general firewall traffic). In addition, the NetScaler
can maintain session persistence based on source IP, cookie, server, group, or SSL session. It allows users to apply custom
Extended Content Verification (ECV) to servers, caches, firewalls and other infrastructure devices to ensure that these
systems are functioning properly and are providing the right content to users. It can also perform health checks using ping,
T CP, or HT T P URL, and the user can create monitors based on Perl scripts. T o provide high-scale WAN optimization, the
CloudBridge appliances deployed at data centers can be load balanced through NetScaler appliances. T he bandwidth and
number of concurrent sessions can be improved significantly.
For more information, see "Load Balancing."
T raf f ic Domains
T raffic domains provide a way to create logical ADC partitions within a single NetScaler appliance. T hey enable you to
segment network traffic for different applications. You can use traffic domains to create multiple isolated environments
whose resources do not interact with each other. An application belonging to a specific traffic domain communicates only
with entities, and processes traffic, within that domain. T raffic belonging to one traffic domain cannot cross the boundary
of another traffic domain. T herefore, you can use duplicate IP addresses on the appliance as long as an addresses is not
duplicated within the same domain.
For more information, see "Traffic Domains."
INAT — In Inbound NAT (INAT ), an IP address (usually public) configured on the NetScaler appliance listens to connection
requests on behalf of a server. For a request packet received by the appliance on a public IP address, the NetScaler replaces
the destination IP address with the private IP address of the server. In other words, the appliance acts as a proxy between
clients and the server. INAT configuration involves INAT rules, which define a 1:1 relationship between the IP address on the
NetScaler appliance and the IP address of the server.
RNAT — In Reverse Network Address Translation (RNAT ), for a session initiated by a server, the NetScaler appliance replaces
the source IP address in the packets generated by the server with an IP address (type SNIP) configured on the appliance.
T he appliance thereby prevents exposure of the server's IP address in any of the packets generated by the server. An RNAT
configuration involves an RNAT rule, which specifies a condition. T he appliance performs RNAT processing on those packets
that match the condition.
St at eless NAT 4 6 T ranslat ion — Stateless NAT 46 enables communication between IPv4 and IPv6 networks, by way of
IPv4 to IPv6 packet translation and vice versa, without maintaining any session information on the NetScaler appliance. A
stateless NAT 46 configuration involves an IPv4-IPv6 INAT rule and an NAT 46 IPv6 prefix.
St at ef ul NAT 64 T ranslat ion — T he stateful NAT 64 feature enables communication between IPv4 clients and IPv6
servers through IPv6 to IPv4 packet translation, and vice versa, while maintaining session information on the NetScaler
appliance. A stateful NAT 64 configuration involves an NAT 64 rule and an NAT 64 IPv6 prefix.
CloudBridge Connect or
T he Citrix NetScaler CloudBridge Connector feature, a fundamental part of the Citrix OpenCloud framework, is a tool used
to build a cloud-extended data center. T he OpenCloud Bridge enables you to connect one or more NetScaler appliances or
NetScaler virtual appliances on the cloud-to your network without reconfiguring your network. Cloud hosted applications
appear as though they are running on one contiguous enterprise network. T he primary purpose of the OpenCloud Bridge is
to enable companies to move their applications to the cloud while reducing costs and the risk of application failure. In
addition, the OpenCloud Bridge increases network security in cloud environments. An OpenCloud Bridge is a Layer-2
network bridge that connects a NetScaler appliance or NetScaler virtual appliance on a cloud instance to a NetScaler
appliance or NetScaler virtual appliance on your LAN. T he connection is made through a tunnel that uses the Generic
Routing Encapsulation (GRE) protocol. T he GRE protocol provides a mechanism for encapsulating packets from a wide
variety of network protocols to be forwarded over another protocol. T hen Internet Protocol security (IPsec) protocol suite
is used to secure the communication between the peers in the OpenCloud Bridge.
When deployed in front of database servers, a NetScaler ensures optimal distribution of traffic from the application servers
and Web servers. Administrators can segment traffic according to information in the SQL query and on the basis of
database names, user names, character sets, and packet size.
You can configure load balancing to switch requests according to load balancing algorithms, or you can elaborate the
switching criteria by configuring content switching to make a decision based on SQL query parameters, such as user name,
database names, and command parameters. You can further configure monitors to track the states of database servers.
T he advanced policy infrastructure on the NetScaler appliance includes expressions that you can use to evaluate and
process the requests. T he advanced expressions evaluate traffic associated with MySQL database servers. You can use
request-based expressions (expressions that begin with MYSQL.CLIENT and MYSQL.REQ) in advanced policies to make
request switching decisions at the content switching virtual server bind point and response-based expressions (expressions
that begin with MYSQL.RES) to evaluate server responses to user-configured health monitors.
AppCache
Helps optimize web content and application data delivery by providing a fast in-memory HT T P/1.1 and HT T P/1.0 compliant
web caching for both static and dynamic content. T his on-board cache stores the results of incoming application requests
even when an incoming request is secured or the data compressed, and then reuses the data to fulfill subsequent requests
for the same information. By serving data directly from the on-board cache, the appliance can reduce page regeneration
times by eliminating the need to funnel static and dynamic content requests to the server.
For more information, see "Integrated Caching."
T CP Buf f ering
Buffers the server’s response and delivers it to the client at the client’s speed, thus offloading the server faster and thereby
improving the performance of web sites.
For more information, see "TCP Buffering."
T he appliance aggressively defends against these types of attacks by preventing the allocation of server resources for
these connections. T his insulates servers from the overwhelming flood of packets associated with these events.
T he appliance also protects network resources from ICMP based attacks by using ICMP rate limiting and aggressive ICMP
packet inspection. It performs strong IP reassembly, drops a variety of suspicious and malformed packets, and applies
Access Control Lists (ACLs) to site traffic for further protection.
Responder
Functions like an advanced filter and can be used to generate responses from the appliance to the client. Some common
uses of this feature are generation of redirect responses, user defined responses, and resets.
For more information, see "Responder."
Rewrit e
Modifies HT T P headers and body text. You can use the rewrite feature to add HT T P headers to an HT T P request or
response, make modifications to individual HT T P headers, or delete HT T P headers. It also enables you to modify the HT T P
body in requests and responses.
When the appliance receives a request or sends a response, it checks for rewrite rules, and if applicable rules exist, it applies
them to the request or response before passing it on to the web server or client computer.
P riorit y Queuing
Prioritizes user requests to ensure that the most important traffic is serviced first during surges in request volume. You can
establish priority based on request URLs, cookies, or a variety of other factors. T he appliance places requests in a three-tier
queue based on their configured priority, enabling business-critical transactions to flow smoothly even during surges or site
attacks.
For more information, see "Priority Queuing."
AppFlow provides visibility at the transaction level for HT T P, SSL, TCP, and SSL_TCP flows. You can sample and filter the flow
types that you want to monitor.
To limit the types of flows to monitor, by sampling and filtering the application traffic, you can enable AppFlow for a virtual
server. AppFlow can also provide statistics for the virtual server.
You can also enable AppFlow for a specific service, representing an application server, and monitor the traffic to that
application server.
If the web site or application does not change frequently, you can use products that collect statistical data, and then
manually analyze the statistics and optimize the delivery of content. However, if you do not want to perform manual
optimizations, or if your web site or application is dynamic in nature, you need infrastructure that can not only collect
statistical data but can also automatically optimize the delivery of resources on the basis of the statistics. On the
NetScaler appliance, this functionality is provided by the Stream Analytics feature. T he feature operates on a single
NetScaler appliance and collects run-time statistics on the basis of criteria that you define. When used with NetScaler
policies, the feature also provides you with the infrastructure that you need for automatic, real-time traffic optimization.
If your organization uses Citrix CloudPlatform to deploy and manage the cloud environment, users can use the AutoScale
feature in CloudPlatform, in conjunction with a Citrix NetScaler appliance, to automatically scale their applications as
needed. T he AutoScale feature is part of the elastic load balancing feature in CloudPlatform. A CloudPlatform user can use
the AutoScale feature to specify thresholds for various conditions for automatically scaling the application fleet upward
and downward. CloudPlatform, in turn, configures the NetScaler appliance (by using the NetScaler NIT RO API) to load
balance traffic to the application virtual machines (VMs), monitor application thresholds and performance, and trigger scale-
up and scale-down actions to add or remove VMs to or from the application fleet.
As the NetScaler administrator, you do not have to perform any tasks for configuring AutoScale on the NetScaler
appliance. However, you might have to be aware of certain prerequisites, and you might have to troubleshoot the
configuration if issues arise in the AutoScale configuration. To troubleshoot the configuration, you have to be aware of
how CloudPlatform works and what configuration CloudPlatform pushes to the NetScaler appliance. You also need a
working knowledge of how to troubleshoot issues on a NetScaler appliance.
For more information about AutoScale, see "AutoScale: Automatic Scaling in the Citrix CloudPlatform Environment."
This section provides the frequently asked questions on the following NetScaler
features:
AppFlow
AutoScale
Call Home
Clustering
Connection Management
NetScaler GUI
Content Switching
Debugging
High Availability
Hardware
Integrated Caching
Load Balancing
SDX
SSL
Af t er an upgrade t o Net Scaler Version 9.3 Build 4 8.6 Cl, why does an at t empt t o open a virt ual server f rom
t he GUI result in t he error message "T he AppF low f eat ure is only available on Cit rix Net scaler Ncore"
AppFlow is supported only on nCore appliances. When you open the virtual server configuration tab, clear the AppF low
checkbox.
What commands can I run on t he Net Scaler appliance t o verif y t hat t he AppF low act ion is a hit ?
T he show appflow action. For example:
When you add an AppFlow collector by using the add appflowCollector command, you can specify the port to be used.
Can t he CloudP lat f orm Aut oScale f eat ure be used wit hout a Net Scaler appliance?
No. T he NetScaler appliance is currently required for the AutoScale feature to work. If the CloudPlatform administrator
configures AutoScale in a network that does not include a NetScaler appliance, CloudPlatform throws an error.
What happens if t he Aut oScale f eat ure is used wit h a Net Scaler release t hat does not support Aut oScale?
If the AutoScale feature is used with a NetScaler release that does not support AutoScale, the CloudPlatform user
interface throws an error. CloudPlatform also writes a message to the log file, indicating that the configured NetScaler
does not support AutoScale.
What versions of CloudP lat f orm and Net Scaler should I use t o implement Aut oScale?
For information about NetScaler releases that support AutoScale, see Supported Environment.
In a load balancing rule, can manually provisioned virt ual machine inst ances coexist wit h inst ances
provisioned by t he Aut oScale f eat ure?
No. T he CloudPlatform virtual machine group in a load balancing rule can contain only manually provisioned instances or
only instances provisioned by the AutoScale feature. T hey cannot coexist.
Is t here a limit on t he number of virt ual machine inst ances t o which we can scale up by using Aut oScale?
Yes. T he CloudPlatform administrator specifies the maximum number of members to which the configuration can scale up.
When the limit is reached, virtual machines are not provisioned even if the scale-up condition is satisfied. T he upper limit
prevents uncontrolled spawning of VMs due to misconfiguration of the AutoScale feature or unexpected load conditions.
What should a CloudP lat f orm administ rat or do bef ore perf orming maint enance t asks on a CloudP lat f orm
net work in which Aut oScale is conf igured?
T he CloudPlatform administrator should disable the AutoScale configuration from the CloudPlatform user interface.
Disabling the AutoScale configuration temporarily disables any scale-up or scale-down events. However, disabling AutoScale
for an application, in CloudPlatform, does not affect the ability of the NetScaler appliance to serve traffic to existing
virtual machines.
Wit h Aut oScale conf igured, are any conf igured VM limit s enf orced on t he user account ?
T he NetScaler appliance works in the context of an AutoScale user account. T herefore, any limits that the CloudPlatform
Note: Admin users can also log on through the NetScaler GUI to log on, by using a browser to connect to the NSIP address.
T he GUI internally opens a NIT RO API connection. T herefore, a GUI session is equivalent to a NIT RO API connection, and
FAQs related to NIT RO API apply to GUI.
How many concurrent admin connect ions are allowed on a Net Scaler appliance?
T he appliance allows up to 20 concurrent admin connections.
Which ext ernal aut hent icat ion met hods does a Net Scaler appliance support ?
T he appliance supports the following external authentication methods:
RADIUS
LDAP
T ACACS
What is a client ?
A client is a device (laptop or desktop), used by admin user to open an admin connection.
A NIT RO API session is considered active if the session token timeout has not expired on the NetScaler appliance.
How does Net Scaler enf orce t he concurrent connect ion limit ?
Every time the NetScaler appliance receives an admin connection request (SSH or NIT RO API), it checks the number of
Which count er ref lect s t he number of admin connect ions on a Net Scaler appliance?
T he connection counter (nsconfigd_cur_clients) reflects the number of active connections. T his counter is incremented
when a client opens new connection to the appliance, and is decremented when a connection is closed.
Which count er ref lect s t he number of act ive t okens on t he Net Scaler appliance?
T he configd_cur_tokens counter reflects the number of active tokens on NetScaler appliance.
Does a CLI or GUI session on a connect ion t o t he management address count against t he admin connect ion
limit ?
Yes, all CLI and GUI connections are T CP based connections, and every T CP connection to the management address counts
against the admin connection limit.
What is t he def ault t imeout period f or AP I, GUI, and CLI sessions on Net Scaler appliance?
T he following table lists the default timeout period for API, GUI and CLI sessions on the NetScaler appliance:
Net Scaler CLI def ault t imeout AP I def ault t imeout GUI def ault t imeout period
Releases period (min) period (min) (min)
How can you set t he CLI sessions t ime out on a Net Scaler appliance?
T he CLI session timeout can be configured by executing the following command at the CLI prompt:
How do you override t he def ault t imeout period when using t he NIT RO AP I?
You can override the default timeout period for a NIT RO API by setting the timeout duration in the “timeout” field of the
login object. If the session timeout is set to zero, the session token has an infinite timeout.
Note: An infinite timeout is not advisable, because sessions that do not time out continue to count against the admin
connection count.
What happens if a user account is delet ed f rom t he Net Scaler appliance af t er an admin session is creat ed?
For internal system users, NetScaler appliance closes the existing CLI or NIT RO API session.
Can NIT RO AP I client s use a single session t oken t o open mult iple admin connect ions on t he Net Scaler
appliance?
Yes. Each such connection counts against the admin connection limit.
If management access is enabled f or a MIP or SNIP address, do admin connect ions t o t hat address count
against t he limit f or t he number of admin connect ions?
Yes, admin connections to management address (MIP or SNIP) count against the admin connection limit on NetScaler ADC.
Can a Net Scaler admin log on t o t he Net Scaler appliance af t er t he maximum connect ions limit is reached?
Yes. One additional admin connection is allowed after the maximum connection limit is reached.
Can NIT RO AP I endpoint s open mult iple admin connect ions on Net Scaler t he appliance?
Yes, NIT RO API endpoints can open multiple admin connections and exhaust the concurrent admin connection limit on a
NetScaler appliance. In such situations, an additional SSH/CLI connection is allowed and the admin can force closure of old
API sessions, or reduce the session timeout duration for the existing API sessions.
Can same client open mult iple AP I sessions on a Net Scaler appliance?
Yes, a client can open multiple API session by repeatedly logging on. For example, the client might log back on after a
reboot.
Note: Repeated client logons count against the admin connection limit on NetScaler appliance.
Note: If a client’s session timeout is zero, the token is valid forever. Repeated logons using new session tokens can count
against the limit for API session tokens.
What is connect ion limit and AP I session limit applicable f or various Net Scaler releases?
T he following table lists the maximum concurrent admin connection and active API session limits applicable for various
NetScaler releases:
A: Firefox will eventually display the differences in the configurations, but the process takes a considerable amount of time
if there are more than 1000 differences. Use Chrome for a faster response.
Q: I am using a MAC Safari browser to upgrade a NetScaler ADC. On the upgrade wizard, when I click the Browse button to
choose the build file from the appliance, the dialog box does not show any files or folders. Also, when I navigate back to the
root folder, the dialog box displays the top level folder, but I cannot browse it. What should I do?
A: On the Safari browser, click the Settings icon and navigate to Preferences > Security > Manage Website Settings > Java,
and then change value of the When visiting other websites setting to Run in unsafe mode.
A: Open TCP port 3010 when using HT T P to access the configuration utility.
A: Open TCP port 3008 when using HT T PS to access the configuration utility.
Q: With which browsers is the configuration utility compatible for different operating systems?
Safari 5.1.3
Q: When I access the NetScaler configuration utility by using Internet Explorer version 8 or 9, the browser displays only a
grey bar at the top of the screen. What should I do?
A: T he browser might be set in compatibility mode. To disable compatibility mode, go to Tools > Compat ibilit y View
Set t ings and clear the Display all websit es in Compat ibilit y View check box.
Q: Even after I disable compatibility mode in Internet Explorer version 8 or 9, the configuration utility does not appear. What
should I do?
A: Make sure that the browser mode and document mode in the browser are set to the same version. To view the
configuration, press F12. Set the values to either Internet Explorer 8 or Internet Explorer 9.
Q: After logging into the NetScaler appliance, the page appears blank. What should I do?
A: Make sure you have disabled the Protected mode in your browser settings. If this is enabled, the Java Script is causing the
NetScaler user interface screen to appear blank.
2. Go to Securit y tab settings, click Rest rict ed sit es zone to disable Enable P rot ect ed Mode check box.
Q: When I access the NetScaler configuration utility by using Internet Explorer version 9, the utility displays the following
error message: "You are not logged in. Please login." What should I do?
A: Make sure that the cookies are not blocked in your Interner Explorer settings. Go to Tools > Int ernet Opt ions . Click
the P rivacy tab, and then under Set t ings , make sure that the slider is set to Medium or any lower value.
How is a Cont ent swit ching virt ual server dif f erent f rom a load balancing virt ual server?
A Content switching virtual server is capable only of sending the client requests to other virtual servers. It does not
communicate with the servers.
A Load balancing virtual server balances the client load among servers and communicates with the servers. It monitors server
availability and can be used to apply different load balancing algorithms to distribute the traffic load.
Content switching is a method used to direct client requests for specific types of content to targeted servers by way of
load balancing virtual servers. You can direct the client requests to the servers best suited to handle them. T his result in
reduced overheads to process the client requests on the servers.
I want t o implement t he Cont ent swit ching f eat ure of t he Net Scaler appliance t o direct t he client request s.
What t ypes of client request can I direct by using t he Cont ent swit ching f eat ure?
You can direct only HT T P, HT T PS, FT P, T CP, Secure T CP, and RT SP client requests by using the Content switching feature.
T o direct HT T PS client requests, you must configure the SSL offload feature on the appliance.
I want t o creat e Cont ent swit ching rules on t he Net Scaler appliance. What are t he various element s of t he
client request on which I can creat e a cont ent swit ching rule?
You can create the content switching rules based on the following elements and their values in the client request:
URL
URL tokens
HT T P version
HT T P Headers
Source IP address of the client
Client version
Destination T CP port
I underst and t hat t he cont ent swit ching f eat ure of t he Net Scaler appliance helps enhance t he perf ormance
of t he net work. Is t his correct ?
Yes. You can direct the client requests you the servers best suited to handle them. T he result is reduced overhead for
processing the client requests on the servers.
Which f eat ure of t he Net Scaler appliance should I conf igure on t he Net Scaler appliance t o enhance t he sit e
manageabilit y and response t ime t o t he client request s?
You can configure the content switching feature of the NetScaler appliance to enhance the site manageability and
Multiple partitions dividing a Web site into various domain names and IP addresses force the browser to create a separate
connection for each domain it finds when rendering and fetching the content of a web page. T hese additional WAN
connections degrade the response time for the web page.
I have host ed a web sit e on a web server f arm. What advant ages does t he Net Scaler cont ent swit ching
f eat ure of f er f or t his t ype of set up?
T he content switching feature provides the following advantages on a NetScaler appliance in a site that is based in a web
server farm:
Manage the site content by creating a content group within the same domain and IP address.
Enhance the response time to client requests by using the content group within the same domain and IP address.
Avoid the need for full content replication across domains.
Enable application-specific content partitioning. For example, you can direct client requests to a server that handles only
dynamic content or only static content, as appropriate for the request.
Support multi-homing of multiple domains on the same server and use the same IP address.
Reuse connections to the servers.
I want t o implement t he cont ent swit ching f eat ure on t he Net Scaler appliance. I want t o direct t he client
request s t o t he various servers af t er evaluat ing t he various paramet ers of each request . What approach
should I f ollow t o implement t his set up when conf iguring t he cont ent swit ching f eat ure?
You can use policy expressions to create policies for the content switching feature. An expression is a condition evaluated
by comparing the qualifiers of the client request to an operand by using an operator. You can use the following parameters
of the client request to create an expression:
Met hod - HT T P request method.
URL - URL in the HT T P header.
URL T OKENS - Special tokens in the URL.
VERSION - HT T P request version.
URL QUERY - Contains the URL Query LEN, URL LEN, and HT T P header.
SOURCEIP - IP address of the client.
Following is a complete list of the operators that you can use to create an expression:
== (equals)
!= (not equals)
EXIST S
NOT EXIST S
CONT AINS
NOT CONT AINS
GT (greater than)
LT (less than)
You can also create various rules, which are logical aggregations of a set of expressions. You can combine multiple
expressions to create rules. To combine expressions, you can use the && (AND) and || (OR) operators. You can also use
parenthesis to create nested and complex rules.
I want t o conf igure a rule based policy along wit h a URL based policy f or t he same cont ent swit ching virt ual
I want t o creat e cont ent swit ching policies t hat evaluat e t he domain name, along wit h a pref ix and suf f ix of
a URL, and direct t he client request s accordingly. Which t ype of cont ent swit ching policy should I creat e?
You can create a Domain and Exact URL policy. When this type of policy is evaluated, the NetScaler appliance selects a
content group if the complete domain name and the URL in the client request match the ones configured. T he client
request must match the configured domain name and exactly match the prefix and suffix of the URL if they are
configured.
I want t o creat e cont ent swit ching policies t hat evaluat e t he domain name, along wit h a part ial pref ix and
suf f ix of URL, and direct t he client request s accordingly. Which t ype of cont ent swit ching policy should I
creat e?
You can create a Domain and Wildcard URL policy for the content switching virtual server. When this type of policy is
evaluated, the NetScaler appliance selects a content group if the request matches the complete domain name and partially
matches the URL prefix.
If some of t he cont ent is t he same f or all client request s, what t ype of precedence should I use f or
evaluat ing policies?
If some of the content is same for all the users and different content should be served on the basis of client attributes,
you can use URL-based precedence for policy evaluation.
What policy expression synt axes are support ed in cont ent swit ching?
Content switching supports two types of policy expressions:
Classic Synt ax- Classic syntax in content switching starts with the keyword REQ and is more advanced than the
default syntax. Classic policies cannot be bound to an action. T herefore, the target load balancing virtual server can be
added only after binding the content switching virtual server.
Def ault Synt ax: Default syntax generally starts with key word HT T P and is easier to configure. A target load balancing
virtual server action can be bound to a Default Syntax policy, and the policy can be used on multiple content switching
virtual servers.
What conf igurat ions are not synced or propagat ed in an HA conf igurat ion in eit her INC or non-INC mode?
Configurations implemented with the following commands are neither propagated nor synced to the secondary node:
All node specific HA configuration commands. For example, add ha node, set ha node, and bind ha node.
All Interface related configuration commands. For example, set interface and unset interface.
All channel related configuration commands. For example, add channel, set channel, and bind channel.
Note: For more information about HA Configuration in INC mode, see Configuring High Availability Nodes in Different
Subnets.
What conf igurat ions are not synced or propagat ed in an HA conf igurat ion in INC mode?
T he following configurations are neither synced nor propagated. Each node has its own.
MIPs
SNIPs
VLANs
Routes (except LLB routes)
Route monitors
RNAT rules (except any RNAT rule with VIP as the NAT IP)
Dynamic routing configurations.
Does a conf igurat ion added t o t he secondary node get synchronized on t he primary?
No, a configuration added to the secondary node is not synchronized to the primary.
What could be t he reason f or bot h nodes claiming t o be t he primary in an HA conf igurat ion?
T he most likely reason is that the primary and secondary nodes are both healthy but the secondary does not receive the
heartbeat packets from the primary. T he problem could be with the network between the nodes.
In an HA conf igurat ion, if t he secondary node t akes over as t he primary, does it swit ch back t o secondary
st at us if t he original primary comes back online?
No. After the secondary node takes over as the primary, it remains as primary even if the original primary node comes back
online again. T o interchange the primary and secondary status of the nodes, run the force failover command.
How is a DEF AULT cont ent group dif f erent f rom ot her cont ent groups?
T he behavior of the DEFAULT content group is exactly the same as any other group. T he only attribute that makes the DEFAULT content group special is that if an object is being
cached and no content group has been created, the object is cached in the DEFAULT group.
What is a miss?
A miss occurs when a request or response does not match any cache policy. A miss can also occur if the request or response matches a cache policy but some override of RFC
behavior prevents the object from being stored in the cache.
I have conf igured Int egrat ed Caching f eat ure of t he Net Scaler appliance. When adding t he f ollowing policy, an error message appears. Is t here any error in
t he command?
add cache policy image_caching -rule exp1 | ns_ext_not_jpeg –action cache
> ERROR: No such command
In the preceding command, the expression should be within the quotation marks. Without quotation marks, the operator is considered to be the pipe operator.
What are t he commands t hat I can run on t he Net Scaler appliance t o check t he memory allocat ed t o cache?
T o display the memory allocated for cache in the NetScaler appliance, run any of the following commands from the command line interface:
show cache parameter
In the output, check the value of the Memory usage limit parameter. T his is the maximum memory allocated for cache.
My Net Scaler appliance has 2 GB of memory. Is t here any recommended memory limit f or cache?
For any model of the NetScaler appliance, you can allocate half of the memory to the cache. However, Citrix recommends allocating a little less than half of the memory, because
of internal memory dependency. You can run the following command to allocate 1 GB of memory to cache:
What is t he dependency of memory bet ween int egrat ed cache and T CP buf f er?
If the NetScaler appliance has 2 GB memory, then the appliance reserves approximately 800 to 900 MB of memory and remaining is allocated to FreeBSD operating system.
T herefore, you can allocate up to 512 MB of memory to integrated cache and the rest is allocated to T CP buffer.
Does it af f ect t he caching process if I do not allocat e global memory t o t he int egrat ed cache?
What is t he command t hat I can run t o display t he charact erist ics of an object st ored in cache?
If the object stored in the cache is, for example, GET //10.102.12.16:80/index.html, you can display the details about the object by running the following command from the
command line interface of the appliance:
Is it mandat ory t o specif y t he group name as a paramet er t o display t he paramet erized object s in cache?
Yes. It is mandatory to specify the group name as a parameter to display the parameterized objects in cache. For example, consider that you have added the following policies with
the same rule:
add cache policy p2 -rule ns_url_path_cgibin -action CACHE –storeInGroup g1
add cache policy p1 -rule ns_url_path_cgibin -action CACHE -storeInGroup g2
In this case, for the multiple requests, if policy p1 is evaluated, its hit counter is incremented and the policy stores the object in the g1 group, which has hit parameters. T herefore,
you have to run the following command to display the objects from the cache:
Similarly, for another set of multiple requests, if policy p2 is evaluated, its hit counter is incremented and the policy stores the object in the g2 group, which does not have hit
parameters. T herefore, you have to run the following command to display the objects from the cache:
I not ice t hat t here are some blank ent ries in t he out put of t he nscachemgr command. What are t hose ent ries?
Consider the following sample output of the nscachemgr command. T he blank entries in this output are highlighted in bold face for your reference:
root@ns# /netscaler/nscachemgr -a
//10.102.3.89:80/image8.gif
//10.102.3.97:80/staticdynamic.html
//10.102.3.97:80/
//10.102.3.89:80/image1.gif
//10.102.3.89:80/file5.html
//10.102.3.96:80/
//10.102.3.97:80/bg_logo_segue.gif
//10.102.3.89:80/file500.html
//10.102.3.92:80/
//10.102.3.96:80/cgi-bin/rfc/ccProxyReval.pl
Total URLs in IC = 10
T he blank entries in the output are due to the default caching properties for GET / HT T P/1.1.
T o flush the specific object, you have to specify the query parameters. You specify the invalParam parameter to flush the object. T his parameter applies only to a query.
Does any change in t he cache conf igurat ion t rigger f lushing of cache?
Yes. When you make any changes to the cache configuration, all the SET cache commands inherently flush the appropriate content groups.
Does t he Net Scaler appliance proact ively receive object s upon expiry?
T he NetScaler appliance never proactively receives objects on expiry. T his is true even for the negative objects. T he first access after expiry triggers a request to the server.
Does t he int egrat ed cache add client s t o t he queue f or serving even bef ore it st art s receiving t he response?
Yes. T he integrated cache adds clients to the queue for serving even before it starts receiving the response.
What is t he def ault value f or t he Verif y cached object using paramet er of t he cache conf igurat ion?
HOST NAME_AND_IP is the default value.
Does t he Net Scaler appliance creat e log ent ries in t he log f iles?
Yes. T he NetScaler appliance creates log entries in the log files.
What happens t o object s t hat are current ly st ored in cache and are being accessed t hough SSL VP N?
Objects stored in the cache and accessed regularly are served as cache hits when accessed through SSL VPN.
What happens t o object s st ored in t he cache when accessed t hrough SSL VP N and lat er accessed t hrough a regular connect ion?
T he objects stored through the SSL VPN access are served as a hit when accessed through the regular connection.
When using weblogging, how do I dif f erent iat e ent ries t hat indicat e response served f rom cache f rom t hose served by t he server?
For responses served from the integrated cache, the server log field contains the value IC. For responses served from a server, the server log field contains the value sent by the
server. Following is a sample log entry for an integrated caching transaction:
"10.102.1.52 - "Mozilla/4.0 (compatible; MSIE 6.0; Windows NT 4.0; .NET CLR 1.0.3705)" "GET /" 200 0 "IC" 10.102.1.45"
Along with a client request, the response logged is the one sent to the client and not necessarily the one sent by the server.
Can I enable t he P oll every t ime (P ET ) and F lash Cache f eat ures on t he same cont ent group?
No. You cannot enable PET and Flash Cache on the same content group. T he integrated cache does not perform AutoPET function on Flash Cache content groups. T he PET
feature ensures that the integrated cache does not serve a stored object without consulting the server. You can configure PET explicitly for a content group.
What is t he meaning of t he DNS, HOST NAME, and HOST NAME_AND_IP values of t he Verif y cached object using paramet er of t he cache conf igurat ion?
T he meanings are as follows:
set cache parameter -verifyUsing HOST NAME
T his ignores the destination IP address.
I have set weakNegRelExpiry t o 600, which is 10 minut es. I not iced t hat 4 04 responses are not get t ing cached. What is t he reason ?
T his completely depends on your configuration. By default, 404 responses are cached for 10 minutes. If you want all 404 responses to be fetched form the server, specify–
weakNegRelExpiry 0. You can fine tune the – weakNegRelExpiry to a desired value, such as higher or lower to get the 404 responses cached appropriately. If you have configured –
absExpiry for positive responses, then it might not yield desired results.
When t he user accesses t he sit e by using t he Mozilla F iref ox browser, t he updat ed cont ent is served. However, when t he user accesses t he sit e by using t he
Microsof t Int ernet Explorer browser, st ale cont ent is served. What could be t he reason?
T he Microsoft Internet Explorer browser might be taking the content from its local cache instead of the NetScaler integrated cache. T he reason could be that the Microsoft
Internet Explorer browser is not respecting the expiry related header in the response.
To resolve this issue, you can disable the local cache of the Internet Explorer and clear the offline content. After clearing the offline content, the browser should display the
updated content
root@ns180# date
Why are policies get t ing hit s but not hing is being cached?
Verify that memory is allocated to the integrated cache and that the allocation is greater than zero.
Can I achieve t he Web f arm securit y by implement ing load balancing using t he Net Scaler appliance?
Yes. You can achieve Web farm security by implementing load balancing using the NetScaler appliance. NetScaler appliance
enables you to implement the following options of the load balancing feature:
IP Address hiding: Enables you to install the actual servers to be on private IP address space for security reasons and for
IP address conservation. T his process is transparent to the end-user because the NetScaler appliance accepts requests
on behalf of the server. While in the address hiding mode, the appliance completely isolates the two networks.
T herefore, a client can access a service running on the private subnet, such as FT P or a T elnet server, through a different
VIP on the appliance for that service.
Port Mapping: Enables the actual T CP services to be hosted on non-standard ports for security reasons. T his process is
transparent to the end-user as the NetScaler appliance accepts requests on behalf of the server on the standard
advertised IP address and port number.
What are various devices t hat I can use t o load balance wit h a Net Scaler appliance?
You can load balance following devices with a NetScaler appliance:
Server farms
Caches or Reverse Proxies
Firewall devices
Intrusion detection systems
SSL offload devices
Compression devices
Content Inspection servers
Why do I need t o disable t he Mac Based F orwarding (MBF ) opt ion f or Link Load Balancing (LLB)?
If you enable the MBF option, the NetScaler appliance considers that the incoming traffic from the client and the
outgoing traffic to the same client flow through the same upstream router. However, the LLB feature requires that the
best path be chosen for the return traffic.
Enabling the MBF option breaks this topology design by sending the outgoing traffic through the router that forwarded
the incoming client traffic.
What are t he various persist ence t ypes available on t he Net Scaler appliance?
Source IP
Cookie insert
SSL session ID
URL passive
Custom Server ID
Rule
DEST IP
What is SDX?
SDX is a true service delivery networking platform for enterprises and cloud datacenters. SDX features an advanced
virtualization architecture that supports multiple NetScaler instances on a single hardware appliance.
Can we migrat e t he exist ing conf igurat ion (ns.conf ) f rom t he MP X plat f orm t o SDX VP X inst ance?
Yes, but some configuration, such as RBA policies and SNMP community configuration, is deleted.
Is SDX int eroperable wit h my rout ing and swit ching inf rast ruct ure?
Yes, although link aggregation control protocol (LACP) is currently not supported. However, SDX supports manual link
aggregation.
We are a VMware shop. We have no inf rast ruct ure available t o support XenServer, do you have a VMware
variant of SDX?
No additional XenServer infrastructure is necessary. SDX is a fully contained networking appliance with its own control
plane, and the virtualization layer is transparent to the deployment.
Why is t he syst em healt h monit oring page not showing any dat a?
You have to install the supplemental pack before you can use this feature. For installation instructions for the supplemental
pack, see http://support.citrix.com/article/CT X132877.
How do I verif y t hat t he supplement al pack inst allat ion was successf ul?
After installation, a pop up window shows whether installation was successful or if there was an error.
1. You provision a VPX instance, by using the Management Service, with interfaces 10/1, 10/2, 10/7, and tag VLAN 512 to
interface 10/2. When you log on to that VPX instance, you see that interfaces 10/1, 10/2, and 10/3 are configured.
2. If you later modify the instance and remove interface 10/1, you lose connectivity to the instance, because interface
10/2 is renamed to 10/1 in the VPX instance.
Where are link paramet ers, such as speed and duplex, conf igured?
Link parameters are configured from the Management Service.
What happens t o product ion inst ances if I remove my plat f orm license?
T here is no change to the production instances. However, you cannot add new instances.
Should member int erf aces in manual link aggregat ion be part of same VLAN?
Yes. Member interfaces in manual link aggregation should be part of the same VLAN.
How many VLANs are support ed per int erf ace wit h VLAN f ilt ering enabled? What happens if I conf igure
more?
With VLAN filtering enabled, 10G interfaces support up to 63 VLANs, and 1G interfaces suppport up to 31 VLANs. T his is a
hard limit based on the number of the queues supported by the NIC. An error message appears if the limit is exceeded.
If I have separat e management net works, do I need t o manually add t hese net works t o t he Management
Service?
No. Communication is over an external device.
Why does Core usage show 50% when I'm not passing any t raf f ic t hrough my Net Scaler inst ance?
CPU core usage shows, from the hypervisor perspective, the CPU utilization of one physical CPU, which has two
hyperthreads: one for the packet engine and one for the management CPU. For example, assume a single instance with
one dedicated core. Even if you are not passing any traffic through your appliance, PE CPU utilization will be 100%, and
average core utilization will be 50%.
Will rest art ing t he Management Service int errupt my product ion inst ances?
No. Your production instances will continue to pass traffic without interruption while the Management Service restarts.
T he same applies when you upgrade the Management Service.
If my Management Service and VP X inst ances are on dif f erent net works, how can I manage t he VP X
inst ance t hrough HT T P S?
T he same way as if they are on the same network.
If my Management Service and VP X inst ances are on dif f erent net works, how can I manage t he VP X
inst ance t hrough t he Management Service?
If the Management Service and the VPX instance are in different networks but the instance can be reached from
Management Service, the Management Service shows the instance as UP. If an instance is UP, you can manage it from the
Management Service. However, if communication between the two fails, the Management Service shows the instance as
"Out of Service".
How many inst ances can I provision on t he SDX appliance? How much aggregat e t hroughput can I expect ?
T his number is dependent on the hardware and the license that you purchased, as shown below:
11500, 13500, 14500, 16500, 18500, 20500— 5 to 20 instances. T hroughput ranges from 8 to 42 Gbps.
17500, 19500, 21500— 5 to 20 instances. T hroughput ranges from 20 to 50 Gbps.
17550, 19550, 20550, 21550— 5 to 40 instances. T hroughput ranges from 20 to 50 Gbps.
8400, 8600— 2 to 5 instances. T hroughput ranges from 4 to 6 Gbps.
How many SDX models are t here, and how do t hey dif f er?
T he NetScaler SDX appliance comes in the following variants:
SDX 11500/13500/14500/16500/18500/20500— 8 to 42 Gbps, maximum 20 instances, 8x1G ports, 4x10G ports.
SDX 17500/19500/21500— 20 to 50 Gbps, maximum 20 instances, 8x10G ports.
Note: T his platform is going EOS this year.
SDX 17550/19550/20550/ 21550— 20 to 50 Gbps, maximum 40 instances, 8x10G ports.
SDX 8400/8600— 4 to 6 Gbps, maximum 5 instances, (6x10/100/1000Base-T copper Ethernet ports + 6x1G SFP) and
(6x10/100/1000Base-T copper Ethernet ports + 2x10G SFP+)
What is t he minimum Net Scaler sof t ware version required f or SDX inst ances?
NetScaler VPX instances should run release 9.3 and later to be able to work on SDX.
How many SSL cards (cores) are support ed on a Net Scaler SDX appliance?
T he number of SSL cards supported varies by the platform as follows:
SDX 17500/19500/21500— 16 cards.
SDX 11500/13500/14500/16500/18500/20500— 16 cards.
SDX 17550/19550/20550/21550— 36 cards.
Note: Instances cannot share SSL cores. Any SSL cores that are allocated at the time of provisioning an instance are
dedicated to that instance.
Why are t he hardware sensors not displayed on t he Net Scaler SDX 17 500/19500/21500 appliance?
T he NetScaler SDX 17500/19500/21500 is built on the MPX 17500/19500/21500 hardware platform. T hese appliance
configurations do not support monitoring of hardware components.
When I upgraded my MP X t o an SDX, t he LCD panel went dark. Is t hat expect ed?
Yes, that is normal behavior. SDX does not support the LCD panel.
I want t o change t he SSH port (22) on t he Net Scaler appliance t o some ot her port . Is it possible t o change
t he SSH port on t he appliance?
Yes. You can change the SSH port on the NetScaler appliance by editing the sshd_config file in the /nsconfig directory. If
the file does not exist in the /nsconfig directory, copy it from the /etc directory.
In the sshd_config file, edit the entry for Port 22 to Port <Number>, where <Number> is the target port number. If you do
not want to restart the appliance and make the changes effective, terminate the sshd process by using the kill command,
and then restart the process.
T he f lash direct ory is missing f rom t he Net Scaler appliance. What procedure should I f ollow t o mount t he
f lash direct ory?
T o mount the flash directory, do the following:
1. Start the NetScaler appliance in single-user mode.
When the appliance starts, the following message appears:
Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in 10 seconds...” Hit space and you
should see the following prompt:
Type '?' for a list of commands, 'help' for more detailed help.
Note: If the preceding command displays an error message about permissions, run the following command to check the
disk for consistency:
fsck /dev/ad0s1a
I want t o log on t o t he Net Scaler appliance wit hout ent ering t he password. Is it possible t o conf igure SSH
on t he appliance t o allow t hat ?
2. Run the following command to copy the id_rsa.pub file to the .ssh directory of the remote host that you want to log on
to:
# scp id_dsa.pub <user>@<remote_host>/.ssh/id_dsa.pub
# rm id_dsa.pub
What is t he procedure t o reset t he Net Scaler appliance BIOS? Under what circumst ances should I reset t he
BIOS?
T o reset BIOS of the NetScaler appliance, complete the following procedure:
1. Connect to the appliance through the serial port.
2. Start the appliance and press Delete as soon as the boot-up process starts.
Pressing Delete during the POST process displays the appliance’s BIOS settings.
5. Select OK.
6. Make the following changes to the BIOS settings on the various tabs:
You need to reset BIOS when the serial console does not respond. T his usually happens after you upgrade the appliance
and the serial console is disabled. However, you can still access the appliance by using the telnet or SSH utility.
I need t o reset t he Net Scaler appliance t o t he f act ory def ault s. What procedure should I f ollow?
T o reset the NetScaler appliance to the factory defaults, you need to reset two environments: the NetScaler application
environment and the base FreeBSD environment.
T o reset the NetScaler application environment of the appliance to the factory defaults, do the following:
1. Make a backup of the appliance’s /nsconfig/ns.conf.
2. Delete the /nsconfig/ns.conf file.
3. Restart the appliance.
T o reset the FreeBSD environment of the appliance to the factory defaults, do the following:
1. Install a fresh NetScaler code image on the appliance. T his overwrites a number of FreeBSD-level configuration files with
default values.
2. Delete any users and groups that are added to the appliance, that is, all except the default users.
3. Delete the /etc/resolv.conf file.
4. Delete the entries that you have added to the /etc/hosts file.
5. If the /etc/rc.netscaler file exists, delete it.
6. Open the /etc/nsperm_group_suser file and make sure that all IOCT L entries are comment entries.
7. Open the /etc/rc.conf file and make sure that the syslogd_enable=NO entry is not changed to syslogd_enable=YES.
8. Open the /etc/syslog.conf file and make sure that there are no additional entries in the file.
9. Delete the contents of the /var/nslog, /var/nstrace, and /var/crash files.
10. If the syslog process is enabled on the appliance and the appliance creates log files locally, delete the contents of the
log files listed in the /etc/syslog.conf file. T he files are created in the /var/log directory. For example, if syslog process
writes system events to the /var/log/events file, and sslvpn access events to the /var/log/sslvpnevents file, delete these
files.
T he appliance displays a message similar t o t he “Jun 21 12:20:18 ns /f lash/ns-10.0-4 7 .15: [1/2]dc0: NIC hang
condit ion #663: T X 10000/10000, RX 0, HF 0” message on t he console. What is t he meaning of t his message?
T he message consists of the following components (shown here as examples):
#663: Number of times this condition has occurred on the appliance.
T X 10000/10000: Number of packets that the appliance attempted to transmit, and number of packets transmitted. If
both numbers are the same, as in this example, the NIC transmitted all the packets that the appliance attempted to
transmit.
If the appliance does not receive any packets, it reports a hang condition, because on a network it is very unlikely not to
receive any packets. However, if the appliance is plugged into quite interface, you can ignore this error message.
Af t er I upgraded t he Net Scaler release on t he appliance, t he appliance st ill displays t he earlier release/build.
What could be t he reason?
T he appliance displays the software version number from the /flash/boot/loader.conf file. If the kernel entry for the current
NetScaler release is missing from that file, the appliance displays the last NetScaler release version for which the entry was
available.
T o resolve this issue, do the following:
1. Verify that the kernel file exists in the /nsconfig directory.
2. Check the /flash/boot/loader.conf file for an entry for the kernel.
(You can expect the entry for the kernel of the release/build that you just installed to be missing from the file.)
3. Open the loader.conf file in a text editor, such as the vi editor, and update the kernel entry for the new release/build.
4. Save and close the file.
5. Repeat step 2 through step 4 for the /flash/boot/loader.conf.local file.
6. Update the release/build entry in the ns.conf file.
7. Restart the appliance.
Since I upgraded t he Net Scaler release on t he appliance, t he LCD display on t he f ront panel of t he appliance
displays t he out of service message or does not display anyt hing. How can I resolve t his issue?
Run the following command from the appliance’s shell prompt:
/netscaler/nslcd – k
I have upgraded t he Net Scaler release/build. However, af t er t he upgrade process, t he appliance f ails t o
st art . Can I downgrade t he appliance’s sof t ware t o t he previous release/build?
Yes. You can start the appliance with the kernel.old kernel file. When you restart the appliance, press the F1 key as soon as
the appliance console displays the Press F1 message. T ype kernel.old and press Enter.
Af t er upgrading t he Net Scaler release on t he appliance, I accident ly delet ed t he kernel f ile f rom t he /f lash
direct ory. As a result , I am not able t o st art t he appliance. Is t here a met hod f or st art ing t he appliance in
t his sit uat ion?
Yes. You can start the appliance by using the kernel.GENERIC kernel file, as follows:
1. When you restart the appliance, press the F1 key as soon as the appliance console displays the Press F1 message.
2. T ype kernel.GENERIC and press Enter.
3. Login as the root user.
4. Reinstall the NetScaler release.
5. Restart the appliance.
I have received a Net Scaler appliance wit h t he lat est Net Scaler release inst alled on it . However, I want t o
downgrade t he sof t ware release. Can I do so?
No. If you attempt to downgrade the software release, the appliance might not work as expected, because the ns.conf
file of the later release might not be compatible with the earlier release, and the appliance might restore to the factory
settings.
T his issue could be the result of incorrect version information in the ns.conf file. To resolve this issue, open the ns.conf file in
a text editor, such as the vi editor. Update the release-specific entry in the ns.conf file to #NS<Release_No> Build
<Build_No>. Here, <Release_No> is the NetScaler release number to which you want to downgrade the software, and the
<Build_No> is the build number of the software release to which you want to downgrade the software.
Af t er upgrading t he appliance sof t ware t o Net Scaler release 10.0, I am not able t o log on t o t he appliance,
and t he f ollowing message is appears:
login: nsroot
Password:
connect: No such file or directory
nsnet_connect: No such file or directory
Login incorrect
I t ried t o resolve t his issue by using t he password recovery procedure, but I was not successf ul. Have I done
somet hing incorrect ly?
You cannot resolve this issue by using the password recovery procedure. NetScaler releases 8.0 and later use the new
licensing system, based on the Imgrd daemon, which runs during the startup procedure. For this daemon to work properly,
the host name of NetScaler appliance, which is set in the /nsconfig/rc.conf file, must be resolved by a name server to the
NetScaler IP address. Alternately, you can create a hosts file in the /nsconfig directory and add the 127.0.0.1 <Host_Name>
entry in file.
Additionally, make sure that you have copied the license files to the /nsconfig/license/ directory.
During an upgrade of a high availabilit y pair, t he f ollowing message appears repeat edly:
<auth.err> ns sshd[5035]: error: Invalid username or password
What could be t he reason?
T his error message appears when the appliances involved in the high availability pairing have either a different NetScaler
release or a different builds of the same release installed. T he appliances can have different version installed if you have
upgraded or downgraded one appliance but not the other.
I want t o change t he net mask of t he Net Scaler IP address on a Net Scaler appliance. Can I do so wit hout
causing an out age?
Changing the netmask of the NetScaler IP might result in a short outage. Make sure that you change the netmask on the
To change the netmask on the appliance, run the configns command from the CLI prompt, and then choose the second
option in the menu.
I have conf igured a High Availabilit y pair of Net Scaler appliances. Af t er upgrading t he sof t ware release f rom
a bet a release t o a f inal release, I not iced t hat some of t he appliance conf igurat ions are missing. Can I
ret rieve t he lost conf igurat ions?
You can use the following procedure to restore the configuration:
1. Log on to the command line interface of the primary appliance.
2. Run the following commands:
save config
shell
T he rollback procedure is similar to the basic upgrade procedure. Select the target build that you want to roll back to and
perform the downgrade.Before rolling back to a different release, Citrix recommends that you create a copy of your
current configuration files. To downgrade from a release, see Downgrading a NetScaler Standalone Appliance or to
downgrade to an earlier build, see Downgrading to an Earlier Build within Release 11.1 .
Can I upgrade a Net Scaler appliance direct ly f rom release 10.0 t o 10.5, or should I upgrade t o 10.1 first and
t hen t o 10.5?
You can directly upgrade a NetScaler appliance regardless of the version or the build number.
Yes. Only version 9.3 or earlier supports classic builds. For details, see Upgrading from a Classic to an nCore Release .
No. Release 10.0 supports only nCore builds. You must have a multi-processor Netscaler (MPX or higher) to upgrade to 10.0.
Recommended practice is to use the same version and build number on both the primary and the secondary appliance.Can
both the appliances in an High Availability (HA) pair be upgraded at the same time?No. In an HA pair, first upgrade the
secondary node and then upgrade the primary node. For details, refer Upgrading a High Availability Pair or Upgrading a
NetScaler High Availability Pair to a Later Build.
Yes.
It is not required to upgrade the SDX version when the NetScaler appliance is upgraded. However, some features might not
work.
No. You must first download the firmware from the Citrix download site, save it on your local computer and then upgrade
the appliance.
Is t he procedure f or upgrading t he Net Scaler appliance wit h GSLB configurat ions dif f erent f rom an upgrade
of an appliance t hat is not involved in GSLB?
No. T he upgrade procedure is similar to the basic upgrade procedure. T he only difference is that you can upgrade the
standalone or HA appliances on different sites in a phased manner.
Service provides offer the core infrastructure needed for carrying the user's apps and data over the network. Because the
core infrastructure serves millions of subscribers and a wide variety of apps and data, requirements for scale and protocol
support are very high. T he core infrastructure handles two major types of traffic: data plane and control plane. Each of
these planes has its own scale and protocol-support requirements.
T he data plane is the part of the core infrastructure that carries user apps and data from end to end, that is, between end-
user equipment and the application server. T he number of users accessing apps and data is in the thousands of millions, so
throughput and IP-addressing requirements are very high. Every user in the network must be uniquely identifiable. Only then
can the service provider control the traffic, monitor network usage, deliver user-specific services, and log information
correctly. Many of the today's client devices and application servers support IPv6 natively. T he core infrastructure must not
only support a mix of IPv4 and IPv6 clients and servers, but also provide the technologies for cross-communication between
IPv4 and IPv6. Finally, a service provider is measured by the quality of service (directly related to end-user experience) and
the availability of service without disruptions. T he data plane should be resilient enough to provide both quality and
availability at the same time.
T he control-plane infrastructure manages user traffic and maintains the business and network operations services. T he
most important of the many protocols that run in this plane are Diameter, Radius, and SMPP. Diameter is a base protocol
over which several other function-specific protocols have been developed. For example:
Gx interface between the Policy and Charging Enforcement Function (PCEF) and the Policy and Charging Rules Function
(PCRF)
Gy interface between the Online Charging System (OCS) and the Cisco Packet Data Network Gateway (PGW)/Policy
and Charging Enforcement Function (PCEF)
T he volume of control plane traffic is in direct proportion to user activity. To manage the control plane traffic, service
providers use several ADC functionalities, such as load balancing and content switching. T hey need fine-grain control of
control plane traffic, which equals data-plane traffic in complexity.
Service providers must meet demanding service-level agreements (SLAs), and are scrutinized thoroughly by regulators for
compliance. Adhering to requirements while managing the data and control plane traffic requires a service provider to keep
its infrastructure nimble, within budget, easily upgradable, and flexible. As the most powerful and advanced ADCs in the
market today, Citrix NetScaler products are a natural fit for the service-provider environment.
Note
T his feature is available with a NetScaler enterprise or platinum edition license.
T he Internet’s phenomenal growth has resulted in a shortage of public IPv4 addresses. Large Scale NAT (LSN/CGNAT )
provides a solution to this issue, maximizing the use of available public IPv4 addresses by sharing a few public IPv4 addresses
among a large pool of Internet users.
LSN translates private IPv4 addresses into public IPv4 addresses. It includes network address and port translation methods
to aggregate many private IP addresses into fewer public IPv4 addresses. LSN is designed to handle NAT on a large scale.
T he NetScaler LSN feature is very useful for Internet Service Providers (ISPs) and carriers providing millions of translations to
support a large number of users (subscribers) and at very high throughput.
T he LSN architecture of an ISP using Citrix products consists of subscribers (Internet users) in private address spaces
accessing the Internet through a NetScaler appliance deployed in ISP’s core network. Subscribers are connected to the ISP
through the ISP's access network. Usually, subscribers for commercial use of the Internet are directly connected to the
ISP's access network. Serving those subscribers requires only one level of NAT (NAT 44).
Noncommercial subscribers, however, are typically behind customer-premises equipment (CPE), such as routers and modems,
that also implements NAT. T hese two levels of NAT create the NAT 444 model. Deploying a NetScaler appliance in an ISP’s
core network for LSN functionality is transparent to the subscribers and requires no configuration changes to subscribers or
the CPEs.
T he NetScaler appliance logs the allocated NAT IP address and the port block for a subscriber. For a connection, a
subscriber can be identified just by its mapped NAT IP address and port block. Because of this reason, the NetScaler
Dynamic. T he NetScaler appliance allocates a random NAT IP address and a port from the LSN NAT pool for a
subscriber's connection. When port block allocation is enabled in the configuration, the NetScaler allocates a random
NAT IP address and a block of ports for a subscriber when it initiates a connection for the first time. T he NetScaler
appliance then allocates this NAT IP address and one of the ports from the allocated block to each subsequent
connection from this subscriber. If the entire block of ports is being used, the appliance allocates a new random port
block to the subscriber when it initiates a new connection. One of the port in the new port block is allocated for the
new connection.
IP Pooling
T he following NAT resource allocation options are available for subsequent sessions of a subscriber who was allocated a
random NAT IP address and port for an existing session.
P aired. T he NetScaler appliance allocates the same NAT IP address for all sessions associated with the same subscriber.
When no more ports are available for that address, the appliance drops any new connections from the subscriber. T his
option is needed for proper functioning of certain applications that require creation of multiple sessions on the same
source IP address (for example in peer-to-peer applications that use RT P or RT CP protocol.
Random. T he NetScaler appliance allocates random NAT IP addresses, from the pool, for different sessions associated
with the same subscriber.
LSN Filtering
T he NetScaler appliance can filter packets from external hosts based on the active LSN sessions and LSN mappings.
Consider an example of an LSN mapping that includes the mapping of subscriber IP:port (X:x), NAT IP:port (N:n), and external
host IP:port (Y:y). T he NetScaler LSN feature supports the following types of filtering:
1. Endpoint Independent . T he NetScaler appliance filters out only those packets that are not destined to NAT IP:port
(N:n), which represents subscriber IP:port (X:x), regardless of the external host IP address and port source (Z:z). T he
NetScaler appliance forwards any packets destined to X:x. In other words, sending packets from the subscriber to any
external IP address is sufficient to allow packets from any external host to the subscriber. T his type of filtering is useful
for proper functioning of VOIP and peer-to-peer applications.
2. Address dependent . T he NetScaler appliance filters out packets not destined to NAT IP:port (N:n), which represents
subscriber IP:port (X:x). In addition, the appliance filters out packets from external host IP address and port (Y:y) destined
for N:n if the subscriber has not previously sent packets to Y:anyport (external port independent). In other words,
receiving packets from a specific external host requires that the subscriber first send packets to that specific external
Quotas
T he NetScaler appliance can limit the number of NAT ports and sessions for each subscriber to ensure fair distribution of
resources among subscribers. T he NetScaler appliance can also limit the number of session for a subscriber group to ensure
fair distribution of resources among different subscriber groups.
P ort quot a. T he NetScaler appliance can limit the LSN NAT ports to be used at a time by each subscriber for a specified
protocol. For example, you could limit each subscriber to a maximum of 500 T CP NAT ports. When the LSN NAT
mappings for a subscriber reach the limit, the NetScaler appliance does not allocate additional NAT ports of the
specified protocol to that subscriber.
Subscriber Session Limit . T he number of concurrent session for a subscriber can be more than it port quota. T he
NetScaler appliance can limit the LSN sessions allowed for each subscriber for a specified protocol. When the number of
LSN sessions reaches the limit for a subscriber, the NetScaler appliance does not allow the subscriber to open additional
sessions of the specified protocol.
Group Session Limit . T he NetScaler appliance can limit the total number of LSN sessions allowed for a subscriber
group for a specified protocol. When the total number of LSN sessions reaches the limit for a group for a specified
protocol, the NetScaler appliance does not allow any subscriber of the group to open additional sessions of the
specified protocol. For example, You limit a group to a maximum of 10000 UDP sessions. When the total number of UDP
sessions for this group reaches 10000, the NetScaler appliance does not allow any subscriber of the group to open
additional UDP sessions.
Hairpin Support
T he NetScaler appliance supports communication between subscribers or internal hosts using NAT IP addresses. T his type
of communication between two subscribers using NAT IP addresses is called hairpin flow. Hairpin flow is enabled by default,
and you cannot disable it.
T he following table lists the maximum numbers of different LSN entities and bindings that can be created on a NetScaler
appliance. T hese limits are also subject to memory available on the NetScaler appliance.
LSN transport profiles that can be bound to an LSN group 3 (one each for T CP, UDP, and ICMP protocols )
To bind a net work address or an ACL rule t o an LSN client by using t he command line int erf ace
bind lsn client <clientname> ((-net work <ip_addr> [-net mask <netmask>] [-t d <positive_integer>]) |
-aclname <string>)
show lsn client
To bind an IP address range t o an LSN pool by using t he command line int erf ace
Not e : For removing LSN IP addresses from an LSN pool, use the unbind lsn pool command.
To creat e an LSN t ransport profile by using t he command line int erf ace
add lsn t ransport prof ile <transportprofilename> <transportprotocol> [-sessiont imeout <secs>]
[-f inrst t imeout <secs>] [-port quot a <positive_integer>] [-sessionquot a <positive_integer>]
[-port preserveparit y ( ENABLED | DISABLED )] [-port preserverange (ENABLED | DISABLED )]
[-syncheck ( ENABLED | DISABLED )]
show lsn t ransport prof ile
To creat e an LSN applicat ion profile by using t he command line int erf ace
To bind an applicat ion prot ocol port range t o an LSN applicat ion profile by using t he command line int erf ace
add lsn group <groupname> -client name <string> [-nat t ype ( DYNAMIC |DET ERMINIST IC )]
[-port blocksize <positive_integer>] [-logging (ENABLED | DISABLED )]
[-sessionLogging ( ENABLED | DISABLED )][-sessionSync (ENABLED | DISABLED )]
[-snmpt raplimit <positive_integer>] [-f t p ( ENABLED | DISABLED )]
show lsn group
To bind LSN profiles and LSN pools t o an LSN group by using t he command line int erf ace
bind lsn group <groupname> (-poolname <string> | -t ransport prof ilename <string> | -appsprof ilename <string>)
show lsn group
To configure an LSN client and bind an IP v4 net work address or an ACL rule by using t he configurat ion ut ilit y
Navigate to Syst em > Large Scale NAT > Client s , and add a client and then bind an IPv4 network address or an ACL rule
to the client.
To configure an LSN pool and bind NAT IP addresses by using t he configurat ion ut ilit y
Navigate to Syst em > Large Scale NAT > P ools , and add a pool and then bind an NAT IP address or a range of NAT IP
addresses to the pool.
To configure an LSN group and bind an LSN client , pools, t ransport profiles, and applicat ion profiles by using
t he configurat ion ut ilit y
Navigate to Syst em > Large Scale NAT > Groups , and add a group and then bind an LSN client, pools, transport profiles,
and application profiles to the group.
net work
IPv4 address(es) of the LSN subscriber(s) or subscriber network(s) on whose traffic you want the NetScaler appliance to
perform Large Scale NAT .
net mask
Subnet mask for the IPv4 address specified in the Network parameter.
td
ID of the traffic domain on which this subscriber or the subscriber network (as specified by the network parameter) belongs.
If you do not specify an ID, the subscriber or the subscriber network becomes part of the default traffic domain.
Default value: 0
Minimum value: 0
aclname
Name(s) of any configured extended ACL(s) whose action is ALLOW. T he condition specified in the extended ACL rule
identifies the traffic from an LSN subscriber for which the NetScaler appliance is to perform large scale NAT. Maximum
Length: 127
nat t ype
Type of NAT IP address and port allocation (from the LSN pools bound to an LSN group) for subscribers (of the LSN client
entity bound to the LSN group):
Det erminist ic — Allocate a NAT IP address and a block of ports to each subscriber (of the LSN client bound to the LSN
group). T he NetScaler appliance sequentially allocates NAT resources to these subscribers. T he NetScaler appliance
assigns the first block of ports (block size determined by the port block size parameter of the LSN group) on the
beginning NAT IP address to the beginning subscriber IP address. T he next range of ports is assigned to the next
subscriber, and so on, until the NAT address does not have enough ports for the next subscriber. In this case, the first
port block on the next NAT address is used for the subscriber, and so on. Because each subscriber now receives a
deterministic NAT IP address and a block of ports, a subscriber can be identified without any need for logging. For a
You must set the port block size in the bound LSN group. For a subscriber, if all the ports are allocated from the subscribers
allocated port block, the NetScaler appliance allocates a new random port block for the subscriber.
For Deterministic NAT, this parameter is enabled by default, and you cannot disable it.
Deterministic NAT
Address-Dependent filtering and Address-Port-Dependent filtering
Dynamic NAT with port block allocation
Default value: 0
When the queue size is full, the next port deallocated is reallocated immediately for a new LSN session.
lsnip
IPv4 address or a range of IPv4 addresses to be used as NAT IP address(es) for LSN.
After the pool is created, these IPv4 addresses are added to the NetScaler appliance as NetScaler owned IP address of
type LSN. An LSN IP address associated with an LSN pool cannot be shared with other LSN pools. IP addresses specified for
this parameter must not already exist on the NetScaler appliance as any NetScaler owned IP addresses. In the command
line interface, separate the range with a hyphen. For example: 10.102.29.30-10.102.29.189. You can later remove some or all
the LSN IP addresses from the pool, and add IP addresses to the LSN pool.
sessiont imeout
T imeout, in seconds, for an idle LSN session. If an LSN session is idle for a time that exceeds this value, the NetScaler
appliance removes the session.
T his timeout does not apply for a TCP LSN session when a FIN or RST message is received from either of the endpoints.
Minimum value: 60
f a TCP LSN session is idle (after the NetScaler appliance receives a FIN or RST message) for a time that exceeds this value,
the NetScaler appliance removes the session.
Since the LSN feature of the NetScaler appliance does not maintain state information of any TCP LSN sessions, this
timeout accommodates the transmission of the FIN or RST, and ACK messages from the other endpoint so that both
endpoints can properly close the connection.
Default value: 30
port quot a
Maximum number of LSN NAT ports to be used at a time by each subscriber for the specified protocol. For example, each
subscriber can be limited to a maximum of 500 TCP NAT ports. When the LSN NAT mappings for a subscriber reach the limit,
the NetScaler appliance does not allocate additional NAT ports for that subscriber.
Default value: 0
Minimum value: 0
sessionquot a
Maximum number of concurrent LSN sessions allowed for each subscriber for the specified protocol. When the number of
LSN sessions reaches the limit for a subscriber, the NetScaler appliance does not allow the subscriber to open additional
sessions.
Default value: 0
Minimum value: 0
port preserveparit y
Enable port parity between a subscriber port and its mapped LSN NAT port. For example, if a subscriber initiates a
connection from an odd numbered port, the NetScaler appliance allocates an odd numbered LSN NAT port for this
connection. You must set this parameter for proper functioning of protocols that require the source port to be even or odd
numbered, for example, in peer-to-peer applications that use RT P or RTCP protocol.
port preserverange
If a subscriber initiates a connection from a well-known port (0-1023), allocate a NAT port from the well-known port range
(0-1023) for this connection. For example, if a subscriber initiates a connection from port 80, the NetScaler appliance can
allocate port 100 as the NAT port for this connection.
T his parameter applies to dynamic NAT without port block allocation. It also applies to Deterministic NAT if the range of
ports allocated includes well-known ports.
syncheck
Silently drop any non-SYN packets for connections for which there is no LSN-NAT session present on the NetScaler
appliance.
If you disable this parameter, the NetScaler appliance accepts any non-SYN packets and creates a new LSN session entry
for this connection.
Following are some reasons for the NetScaler appliance to receive such packets:
LSN session for a connection existed but the NetScaler appliance removed this session because the LSN session was idle
for a time that exceeded the configured session timeout.
Such packets can be a part of a DoS attack.
ippooling
NAT IP address allocation options for sessions associated with the same subscriber.
P aired — T he NetScaler appliance allocates the same NAT IP address for all sessions associated with the same
subscriber. When all the ports of a NAT IP address are used in LSN sessions (for same or multiple subscribers), the
NetScaler appliance drops any new connection from the subscriber.
Random— T he NetScaler appliance allocates random NAT IP addresses, from the pool, for different sessions associated
mapping
Type of LSN mapping to apply to subsequent packets originating from the same subscriber IP address and port.
Consider an example of an LSN mapping that includes the mapping of the subscriber IP:port (X:x), NAT IP:port (N:n), and
external host IP:port (Y:y).
ENDP OINT -INDEP ENDENT — Reuse the LSN mapping for subsequent packets sent from the same subscriber IP
address and port (X:x) to any external IP address and port.
ADDRESS-DEP ENDENT — Reuse the LSN mapping for subsequent packets sent from the same subscriber IP address
and port (X:x) to the same external IP address (Y), regardless of the external port.
ADDRESS-P ORT -DEP ENDENT — Reuse the LSN mapping for subsequent packets sent from the same internal IP
address and port (X:x) to the same external IP address and port (Y:y) while the mapping is still active.
f ilt ering
Type of filter to apply to packets originating from external hosts.
Consider an example of an LSN mapping that includes the mapping of subscriber IP:port (X:x), NAT IP:port (N:n), and external
host IP:port (Y:y).
ENDP OINT INDEP ENDENT — Filters out only packets not destined to the subscriber IP address and port X:x,
regardless of the external host IP address and port source (Z:z). T he NetScaler appliance forwards any packets destined
to X:x. In other words, sending packets from the subscriber to any external IP address is sufficient to allow packets from
any external hosts to the subscriber.
ADDRESS DEP ENDENT — Filters out packets not destined to subscriber IP address and port X:x. In addition, the
appliance filters out packets from Y:y destined for the subscriber (X:x) if the client has not previously sent packets to
Y:anyport (external port independent). In other words, receiving packets from a specific external host requires that the
subscriber first send packets to that specific external host's IP address.
ADDRESS P ORT DEP ENDENT (the default)— Filters out packets not destined to subscriber IP address and port (X:x).
In addition, the NetScaler appliance filters out packets from Y:y destined for the subscriber (X:x) if the subscriber has not
previously sent packets to Y:y. In other words, receiving packets from a specific external host requires that the subscriber
first send packets first to that external IP address and port.
td
ID of the traffic domain through which the NetScaler appliance sends the outbound traffic after performing LSN.
If you do not specify an ID, the appliance sends the outbound traffic through the default traffic domain, which has an ID
of 0.
lsnport
Port numbers or range of port numbers to match against the destination port of the incoming packet from a subscriber.
When the destination port is matched, the LSN application profile is applied for the LSN session. Separate a range of ports
with a hyphen. For example, 40-90.
client name
Name of the LSN client entity to be associated with the LSN group. You can associate only one LSN client entity with an
LSN group. You cannot remove this association or replace with another LSN client entity once the LSN group is created.
Det erminist ic — Allocate a NAT IP address and a block of ports to each subscriber (of the LSN client bound to the LSN
group). T he NetScaler appliance sequentially allocates NAT resources to these subscribers. T he NetScaler appliance
assigns the first block of ports (block size determined by the port block size parameter of the LSN group) on the
beginning NAT IP address to the beginning subscriber IP address. T he next range of ports is assigned to the next
subscriber, and so on, until the NAT address does not have enough ports for the next subscriber. In this case, the first
port block on the next NAT address is used for the subscriber, and so on. Because each subscriber now receives a
deterministic NAT IP address and a block of ports, a subscriber can be identified without any need for logging. For a
connection, a subscriber can be identified based only on the NAT IP address and port, and the destination IP address and
port.
Dynamic — Allocate a random NAT IP address and a port from the LSN NAT pool for a subscriber's connection. If port
block allocation is enabled (in LSN pool) and a port block size is specified (in the LSN group), the NetScaler appliance
allocates a random NAT IP address and a block of ports for a subscriber when it initiates a connection for the first time.
T he appliance allocates this NAT IP address and a port (from the allocated block of ports) for different connections
from this subscriber. If all the ports are allocated (for different subscribers connections) from the subscribers allocated
port block, the appliance allocates a new random port block for the subscriber.
port blocksize
Size of the NAT port block to be allocated for each subscriber.
To set this parameter for Dynamic NAT, you must enable the port block allocation parameter in the bound LSN pool. For
Deterministic NAT, the port block allocation parameter is always enabled, and you cannot disable it.
In Dynamic NAT, the NetScaler appliance allocates a random NAT port block, from the available NAT port pool of an NAT IP
address, for each subscriber. For a subscriber, if all the ports are allocated from the subscribers allocated port block, the
appliance allocates a new random port block for the subscriber.
logging
Log mapping entries and sessions created or deleted for this LSN group. T he NetScaler appliance logs LSN sessions for this
LSN group only when both logging and session logging parameters are enabled.
T he appliance uses its existing syslog and audit log framework to log LSN information. You must enable global level LSN
logging by enabling the LSN parameter in the related NSLOG action and SYLOG action entities. When the Logging
parameter is enabled, the NetScaler appliance generates log messages related to LSN mappings and LSN sessions of this
LSN group. T he appliance then sends these log messages to servers associated with the NSLOG action and SYSLOG
actions entities.
A log message for an LSN mapping entry consists of the following information:
sessionLogging
Log sessions created or deleted for the LSN group. T he NetScaler appliance logs LSN sessions for this LSN group only when
both logging and session logging parameters are enabled.
sessionSync
In a high availability (HA) deployment, synchronize information of all LSN sessions related to this LSN group with the
secondary node. After a failover, established TCP connections and UDP packet flows are kept active and resumed on the
secondary node (new primary).
For this setting to work, you must enable the global session synchronization parameter.
snmpt raplimit
Maximum number of SNMP Trap messages that can be generated for the LSN group in one minute.
Minimum value: 0
Not e : T he NetScaler appliance also includes ALG for ICMP and T FT P protocols. ALG for the ICMP protocol is enabled by
default, and there is no provision to disable it. ALG for the T FT P protocol is disabled by default. ALG is enabled
automatically for an LSN group when you bind a UDP LSN application profile, with endpoint-independent-mapping,
endpoint-independent filtering, and destination port as 69 (well-known port for T FT P), to the LSN group.
poolname
Name of the LSN pool to bind to the specified LSN group. Only LSN Pools and LSN groups with the same NAT type settings
can be bound together. Multiples LSN pools can be bound to an LSN group.
For Deterministic NAT, pools bound to an LSN group cannot be bound to other LSN groups. For Dynamic NAT, pools bound
to an LSN group can be bound to multiple LSN groups. Maximum Length: 127
By default, one LSN transport profile with default settings for TCP, UDP, and ICMP protocols is bound to an LSN group
during its creation. T his profile is called a default transport.
An LSN transport profile that you bind to an LSN group overrides the default LSN transport profile for that protocol.
Maximum Length: 127
appsprof ilename
Name of the LSN application profile to bind to the specified LSN group. For each set of destination ports, bind a profile for
each protocol for which you want to specify settings.
By default, one LSN application profile with default settings for TCP, UDP, and ICMP protocols for all destination ports is
bound to an LSN group during its creation. T his profile is called a default application profile.
When you bind an LSN application profile, with a specified set of destination ports, to an LSN group, the bound profile
T ask St eps
Done
Done
Done
Done
Done
Create an LSN configuration with >add ns acl LSN-ACL-2 ALLOW -srcIP 192.0.2.10-192.0.2.20
an extended ACL for identifying
Done
LSN subscribers
>apply acls
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
add lsn static <name> <transportprotocol> <subscrIP> <subscrPort> [-td <positive_integer>] [<natIP> [<natPort>]] [-
destIP <ip_addr> [-dsttd <positive_integer>]]
show lsn static
Navigate to System > Large Scale NAT > Static, and add a new static mapping.
add lsn st at ic
name
Name for the LSN static mapping entry. Must begin with an ASCII alphanumeric or underscore (_) character, and must
contain only ASCII alphanumeric, underscore, hash (#), period (.), space, colon (:), at (@), equals (=), and hyphen (-) characters.
Cannot be changed after the LSN group is created. T he following requirement applies only to the NetScaler CLI: If the
name includes one or more spaces, enclose the name in double or single quotation marks (for example, "lsn static1" or 'lsn
static1'). T his is a mandatory argument. Maximum Length: 127
subscrIP
IPv4 address of an LSN subscriber for the LSN mapping entry. T his is a mandatory argument.
subscrP ort
Port of the LSN subscriber for the LSN mapping entry. T his is a mandatory argument. Maximum value: 65535
td
ID of the traffic domain to which the subscriber belongs. If you do not specify an ID, the subscriber is assumed to be a part
of the default traffic domain. Default value: 0, Minimum value: 0, Maximum value: 4094
nat IP
IPv4 address, already existing on the NetScaler appliance as type LSN, to be used as NAT IP address for this mapping entry.
nat P ort
NAT port for this LSN mapping entry.
dest IP
Destination IP address for the LSN mapping entry.
Some situations might require exposing all ports (64K) of a subscriber to the Internet (for example, a server hosted on an
internal network and running a different service on each port). To make these internal services accessible through the
Internet, you have to expose all the ports of the server to the Internet.
One way to meet this requirement is to add 64K one-to-one static mapping entries, one mapping entry for each port.
Creating 64K entries is very cumbersome and a big task. Also, this large number of configuration entries might lead to
performance issues in the NetScaler appliance.
Another simple method is to use wildcard ports in a static mapping entry. You just need to create one static mapping entry
with NAT -port and subscriber-port parameters set to the wildcard character (*), and the protocol parameter set to ALL, to
expose all the ports of a subscriber to the Internet. For a subscriber’s inbound or outbound connections matching a
wildcard static mapping entry, the subscriber’s port does not change after the NAT operation.
When a subscriber-initiated connection to the Internet matches a wildcard static mapping entry, the NetScaler appliance
assigns a NAT port that has the same number as the subscriber port from which the connection is initiated. Similarly, an
Internet host gets connected to a subscriber’s port by connecting to the NAT port that has the same number as the
subscriber’s port.
To configure the NetScaler appliance to provide access to all ports of an IPv4 subscriber, create a wildcard static map with
the following mandatory parameter settings:
Protocol=ALL
Subscriber port = *
NAT port = *
In a wildcard static map, unlike in a one-to-one static map, setting the NAT IP parameter is mandatory. Also, the NAT IP
address assigned to a wildcard static map cannot be used for any other subscribers.
add lsn static <name> ALL <subscrIP> * <natIP> * [-td <positive_integer>] [-destIP <ip_addr> [-
dsttd <positive_integer>]]
show lsn static
Sample Configuration
Done
ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.
ALG for the T FT P protocol is disabled by default. T FT P ALG is enabled automatically for an LSN configuration when you
bind a UDP LSN application profile, with endpoint-independent-mapping, endpoint-independent filtering, and destination
port as 69 (well-known port for T FT P), to the LSN group.
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
> add lsn appsprofile LSNAPPSPROFILE-TFTP-2 UDP -mapping ENDPOINT-INDEPENDENT –filtering ENDPOINT-INDEPENDENT
Done
Done
Done
PPT P is a network protocol that enables secure transfer of data from a remote client to an enterprise server by creating a
tunnel across TCP/IP-based data networks. PPT P encapsulates PPP packets into IP packets for transmission over the
Internet. PPT P establishes a tunnel for each communicating PPT P network server (PNS)-PPT P Access Concentrator (PAC)
pair. After the tunnel is set up, enhanced generic routing encapsulation (GRE) is used to exchange PPP packets. A call ID in
the GRE header indicates the session to which a particular PPP packet belongs.
T he NetScaler appliance recognizes PPT P packets that arrive on the default TCP port, 1723. T he appliance parses PPT P
control packets, translates the call ID, and assigns a NAT IP address. For two-way data communication between the client
and server, the NetScaler appliance creates an LSN session entry based on the server call ID, and an LSN session based on
the client call ID. T he appliance then parses the GRE data packets and translates call IDs on the basis of the two LSN
session entries.
For PPT P protocol, the NetScaler also includes timeout setting for any idle PPT P LSN sessions. If a PPT P LSN session is idle
for a time that exceeds the timeout setting, the NetScaler appliance removes the session.
Limit at ions
Configuring P P T P ALG
Configuring PPT P ALG on the NetScaler appliance consist of the following tasks:
Create an LSN configuration and enable PPT P ALG on it. In an LSN configuration, the LSN group includes the PPT P ALG
setting. For instructions on creating an LSN configuration, see Configuration Steps for LSN.
(Optional) Set the global timeout for idle PPT P LSN sessions.
To enable PPT P ALG for an LSN configuration by using the NetScaler command line
add lsn group <groupname> -client name <string> [-ppt p ( ENABLED | DISABLED )]
show lsn group
To set the global timeout for idle PPT P LSN sessions by using the NetScaler command line
Done
Done
Done
Done
Done
Done
Done
How IP address translation is performed depends on the type and direction of the message. A message can be any of the following:
Inbound request
Outbound response
Outbound request
Inbound response
For an outgoing message, the private IP address and port number of the SIP client are replaced with the NetScaler-owned public IP address and port number, called the LSN pool IP address and port
number, specified during LSN configuration. For an incoming message, the LSN pool IP address and the port number are replaced with the private address of the client. If the message contains any
public IP addresses, the NetScaler SIP ALG retains them. Also, a pinhole is created on the:
LSN pool IP address and port on behalf of the private client, so that the messages that arrive at this IP address and port from the public network are treated as SIP messages.
Public IP address and port on behalf of the public clients, so that the messages that arrive at this IP address and port from the private network are treated as SIP messages.
When a SIP message is sent out across the network, the SIP Application Layer Gateway (ALG) collects information from the message and translates the IP addresses in the following headers into
LSN pool IP addresses:
Via
Contact
Route
Record-Route
In the following sample SIP request message, LSN replaces the IP addresses in the header fields to hide them from the outside network.
INVITE adam@10.102.185.156 SIP/2.0 Via: SIP/2.0/UDP 192.170.1.161:62914 From: eve@10.120.210.3 To: adam@10.102.185.156 Call-ID: a12abcde@10.120.210.3 Contact: adam@10.102.185.156 Route: <sip
When a message containing SDP information arrives, the SIP ALG collects information from the message and translates the IP addresses in the following fields into LSN pool IP addresses and port
numbers:
c= (connection information)
T his field can appear at the session or media level. It appears in the following format:
c=<network-type><address-type><connection-address>
If the destination IP address is a unicast IP address, the SIP ALG creates pinholes by using the IP address and port numbers specified in the m= field.
m= (media announcement)
T his field appears at the media level and contains the description of the media. It appears in the following format:
m=<media><port><transport><fmt list>
T his field can appear at the session or media level, in the following format:
a=<attribute>
a=<attribute>:<value>
T he following excerpt from a sample SDP section shows the fields that are translated for resource allocation.
From: None
Call-ID: None
Via: None
Record-Route None
Route: None
From: None
Call-ID: None
Via: None
Record-Route None
Route: None
From: None
Call-ID: None
Request-URI: None
Record-Route None
Route: None
From: None
Call-ID: None
Request-URI: None
Record-Route None
Route: None
T he following SIP clients and proxy server have been tested with SIP ALG:
Outgoing Calls
A SIP call is initiated with a SIP INVIT E message sent from the internal to the external network. T he SIP ALG performs NAT on the IP addresses and port numbers in the Via, Contact, Route, and
Record-Route SIP header fields, replacing them with the LSN pool IP address and port number. LSN stores these mappings for subsequent SIP messages in the SIP call. T he SIP ALG then opens
separate pinholes in the NetScaler configuration to allow SIP and media through the NetScaler appliance on the dynamically assigned ports specified in the SDP and SIP headers. When a 200 OK
message arrives at the NetScaler, it is captured by one of the created pinholes. T he SIP ALG replaces the SIP header, restoring the original Contact, Via, Route, and Record-Route SIP fields, and then
Incoming Calls
A SIP incoming call is initiated with a SIP INVIT E message from the external client to the internal network. T he SIP registrar forwards the INVIT E message to the SIP client in the internal network,
using the pinhole that was created when the Internal SIP client registered with the SIP registrar.
T he SIP ALG performs NAT on the LSN IP addresses and port numbers in the Via, Contact, Route, and Record-Route SIP header fields, translating them to the IP address and port number of the
internal SIP client, and forwards the request to the SIP client. When the 200 OK response message sent by the internal SIP client arrives at the NetScaler appliance, the SIP ALG performs NAT on the
IP addresses and port numbers in the Via, Contact, Route, and Record-Route SIP header fields, translating them to the LSN pool IP address and port number, forwards the response message to the
Call Termination
T he BYE message terminates a call. When the device receives a BYE message, it translates the header fields in the message just as it does for any other message. But because a BYE message must be
acknowledged by the receiver with a 200 OK, the ALG delays call teardown for 15 seconds to allow time for transmission of the 200 OK.
If you want to host the SIP Proxy server inside the private network, Citrix recommends that you do one of the following:
Configure a static LSN Mapping for the private SIP proxy. For more information, see Configuring Static LSN Maps. Make sure that the NAT port is the same as the port configured in the SIP ALG
profile.
Configure the SIP Proxy server inside a demilitarized zone (DMZ).
T ime stamp
T ype of SIP message (for example, SIP request)
Source IP address and port of the SIP client
Destination IP address and port of the SIP proxy
NAT IP address and port
SIP method
Sequence number
Whether or not the SIP client is registered
Caller’s user name and domain
Receiver’s user name and domain
You need to configure the SIP ALG as part of the LSN configuration. For instructions on configuring LSN, see Configuration Steps for LSN. While configuring LSN, make sure that you:
Set the following parameters while adding the LSN application profile:
IP Pooling = PAIRED
Address and Port Mapping = ENDPOINT -INDEPENDENT
Filtering = ENDPOINT -INDEPENDENT
Important: For the SIP ALG to work, a full cone NAT configuration is mandatory.
Example
add lsn appsprofile app_tcp TCP -ippooling PAIRED -mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPENDENT
Create a SIP ALG profile and make sure that you define either the source port range or destination port range.
Example
add lsn sipalgprofile sipalgprofile_tcp -sipsrcportrange 1-65535 -sipdstportrange 5060 -openViaPinhole ENABLED -openRecordRoutePinhole ENABLED –sipTransportProtocol TCP
Example
Streaming media from a private network to a public network requires translating IP addresses and port numbers over the
network. NetScaler functionality includes an Application Layer Gateway (ALG) for RT SP, which can be used with Large Scale NAT
(LSN) to parse the media stream and make any necessary changes to ensure that the protocol continues to work over the
network.
How IP address translation is performed depends on the type and direction of the message, and the type of media supported
by the client-server deployment. Messages are translated as follows:
Outbound request— Private IP address to NetScaler-owned public IP address called an LSN pool IP address.
Inbound response— LSN pool IP address to private IP address.
Inbound request— No translation.
Outbound response— Private IP address to LSN pool IP address.
Multicast RT SP sessions
RT SP session over UDP
T D/admin partitioning/cluster deployments
RST P Authentication
HT T P tunneling
T he following figure shows an RT SP SET UP request flow. Typically, a SET UP request specifies how a single media stream must
be transported. T he request contains the media stream URL and a transport specifier. T his specifier typically includes one local
port for receiving RT P data (audio or video), and another for receiving RTCP data (meta information). T he server reply usually
confirms the chosen parameters and fills in the missing parts, such as the server's chosen ports. Each media stream must be
configured by using the SET UP command before an aggregate play request can be sent.
T he media server in the private network uses the LSN pool IP address and LSN port number to send a 200 OK response to the
media client in the public network. T he NetScaler RT SP ALG intercepts the response and replaces the LSN pool IP address and
LSN port number with the public IP address and port number of the media client. T he following figure shows the translation
performed by a NetScaler appliance in the media stream for an inbound response:
Set the NAT T ype as DET ERMINST IC or DYNAMIC while adding the LSN pool.
Set the following parameters while adding the LSN application profile:
IP Pooling = PAIRED
Address and Port Mapping = ENDPOINT -INDEPENDENT
Filtering = ENDPOINT -INDEPENDENT
Create a RT SP ALG profile and bind the RT SP ALG profile to the LSN group
NAT -Traversal (NAT -T ) capable IPSec endpoints detect the presence of an intermediate NAT device during IKE phase 1 and
switch to UDP port 4500 for all subsequent IKE and ESP traffic (encapsulating ESP in UDP). Without NAT -T support on the
peer IPSec endpoints, IPSec protected ESP traffic is transmitted without any UDP encapsulation. T herefore, IPSec ESP
traffic fails at the NAT device.
T he NetScaler appliance supports IPSec application layer gateway (ALG) functionality for large scale NAT configurations.
T he IPSec ALG processes IPSec ESP traffic and maintains session information so that the traffic does not fail when the
IPSec endpoints do no support NAT -T (UDP encapsulation of ESP traffic).
An IPSec ALG monitors IKE traffic between a client and the server, and permits only one IKE phase 2 message exchange
between the client and the server at any given time.
Once the two-way ESP packets are received for a particular flow, the IPSec ALG creates a NAT session for this particular
flow so that subsequent ESP traffic can flow smoothly. T he ESP traffic is identified by Security Parameters Indexes (SPIs),
which are unique for a flow and for each direction. An IPSec ALG uses ESP SPIs in place of source and destination ports for
performing large scale NAT.
If a gate receives no traffic, it times out. After both gates time out, another IKE phase 2 exchange is permitted.
ESP Gate Timeout. Maximum time that the NetScaler appliance blocks an IPSec ALG gate for a particular client on a
specific NAT IP address for a given server if no two-way ESP traffic is exchanged between the client and the server.
IKE Session Timeout. Maximum time that the NetScaler appliance keeps the IKE session information before removing it
if there is no IKE traffic for that session.
ESP Session Timeout. Maximum time that NetScaler appliance keeps the ESP session information before removing it if
there is no ESP traffic for that session.
Before you start configuring IPSec ALG, consider the following points:
Configuring IPSec ALG for large scale NAT 44 on a NetScaler appliance consists of the following tasks:
Create an LSN application prof ile and bind it to the LSN conf iguration. Set the following parameters while
configuring an application profile:
Protocol=UDP
IP Pooling = PAIRED
Port=500
Bind the application profile to the LSN group of an LSN configuration. For instructions on creating an LSN
configuration, see Configuration Steps for LSN.
Create an IPSec ALG prof ile. An IPSec profile includes various IPSec timeouts, such as IKE session timeout, ESP session
timeout, and ESP gate timeout. You bind an IPSec ALG profile to an LSN group. An IPSec ALG profile has the following
default settings:
IKE session timeout = 60 minutes
ESP session timeout = 60 minutes
ESP gate timeout = 30 seconds
Bind the IPSec ALG prof ile to the LSN conf iguration. IPSec ALG is enabled for an LSN configuration when you bind
an IPSec ALG profile to the LSN configuration. Bind the IPSec ALG profile to the LSN configuration by setting the IPSec
ALG profile parameter to the name of the created profile in the LSN group. An IPSec ALG profile can be bound to
multiple LSN groups, but an LSN group can have only one IPSec ALG profile.
To create an LSN application profile by using the command line interf ace
To bind destination port to the LSN application profile by using the command line interf ace
To bind an LSN application profile to an LSN group by using the command line interf ace
To create an LSN application profile and bind it to an LSN configuration by using the NetScaler GUI
Navigate to System > Large Scale NAT > Profiles, click Application tab, add an LSN application profile and bind it to an
LSN group.
Navigate to System > Large Scale NAT > Profiles, click IPSEC ALG tab, and then add an IPSec ALG profile.
To bind an IPSec ALG profile to an LSN configuration by using the NetScaler GUI
1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + IPSEC ALG Prof ile to bind the created IPSec ALG profile to the LSN group.
Sample Configuration
In the following sample large scale NAT 44 configuration, IPSec ALG is enabled for subscribers in the 192.0.2.0/24 network.
IPSec ALG profile IPSECALGPROFILE-1 with various IPSec timeout settings is created and is bound to LSN group LSN Group
-1.
Done
Done
Done
Done
Done
Done
> add ipsecalg profile IPSECALGPROFILE-1 -ikeSessionTimeout 45 –espSessionTimeout 40 –espGateTimeout 20 -connfailover ENABLED
Done
Done
Done
Done
Logging LSN
Updated: 2015-06-29
Logging LSN information is one of the important functions required by the ISPs to meet legal requirements and for identifying the source of traffic at any given time.
A NetScaler appliance logs LSN mapping entries and the LSN sessions created or deleted for each LSN group. You can control logging of LSN information for an LSN group by using
the logging and session logging parameters of the LSN group. T hese are group level parameters and are disabled by default. T he NetScaler appliance logs LSN sessions for an LSN
group only when both logging and session logging parameters are enabled.
T he following table displays the logging behavior for an LSN group for various settings of logging and session logging parameters.
Enabled Disabled Logs LSN mapping entries but not LSN sessions.
A log message for an LSN mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced.
T ime stamp
Entry type (MAPPING)
Whether the LSN mapping entry was created or deleted
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID might be present, depending on the following conditions:
Destination IP address and port are not logged for Endpoint-Independent mapping.
Only the destination IP address is logged for Address-Dependent mapping. T he port is not logged.
Destination IP address and port are logged for Address-Port-Dependent mapping.
T he appliance uses its existing syslog and audit log framework to log LSN information. You must enable global level LSN logging by enabling the LSN parameter in the related NSLOG
action and SYLOG action entities. When the Logging parameter is enabled, the NetScaler appliance generates log messages related to LSN mappings and LSN sessions of this LSN
group. T he appliance then sends these log messages to servers associated with the NSLOG action and SYSLOG action entities.
Note:
T he SYSLOG generated on NetScaler appliance are dynamically sent to the external log servers.
When using SYSLOG over T CP, if the T CP connection is down or the SYSLOG server is busy, then the NetScaler appliances stores the logs in buffer and send the data once the
connection is active.
add audit syslogAction <name> <serverIP> [-serverPort <port>] -logLevel <logLevel>... [-transport (T CP)] [-lsn ( ENABLED | DISABLED )]
To create a SYSLOG server policy for LSN logging by using the command line interface
1. Navigate to Systems > Auditing > Syslog and, on the Servers tab, add a new auditing server or edit an existing server.
2. T o enable LSN logging, select the Large Scale NAT Logging option.
3. (Optional) T o enable SYSLOG over T CP, select the TCP Logging option.
To configure a SYSLOG server policy for LSN logging by using the configuration utility
Navigate to Systems > Auditing > Syslog and, on the Policies tab, add a new policy or edit an existing policy.
To bind a SYSLOG server policy to system global for LSN logging by using the configuration utility
add audit nslogAction <name> <serverIP> [-serverPort <port>] -logLevel <logLevel> ... [-lsn ( ENABLED | DISABLED )]
To create a NSLOG server policy for LSN logging by using the command line interface
1. Navigate to Systems > Auditing > Nslog and, on the Servers tab, add a new auditing server or, edit an existing server.
2. T o enable LSN logging, select the Large Scale NAT Logging option.
To configure a NSLOG server policy for LSN logging by using the configuration utility
Navigate to Systems > Auditing > Nslog and, on the Policies tab, add a new policy or edit an existing policy.
To bind a NSLOG server policy to system global for LSN logging by using the configuration utility
Example
T he following configuration specifies two SYSLOG and two NSLOG servers for storing log entries including LSN logs. LSN Logging is configured for LSN groups LSN-GROUP-2 and LSN-
GROUP-3.
T he NetScaler appliance generates log messages related to LSN mappings and LSN sessions of these LSN groups, and sends them to the specified log servers.
> add lsn group LSN-GROUP-3 -clientname LSN-CLIENT-2 –logging ENABLED –sessionLogging ENABLED
Done
> set lsn group LSN-GROUP-2 –logging ENABLED –sessionLogging ENABLED
Done
T he following configuration specifies SYSLOG configuration for sending log messages to
the external SYSLOG server 192.0.2.10 using TCP.
> add audit syslogAction SYS-ACT ION-1 192.0.2.10 -logLevel ALL -transport TCP
Done
T he following table displays sample LSN log entries of each type stored on the configured log servers. T hese LSN log entries are generated by a NetScaler appliance whose NSIP
address is 10.102.37.115.
LSN session Local4.Informational 10.102.37.115 08/05/2014:09:59:48 GMT 0-PPE-0 : LSN LSN_SESSION 2581750 : SESSION CREAT ED Client IP:Port:T D 192.0.2.10: 15136:0,
creation NatIP:NatPort 203.0.113.6: 6234, Destination IP:Port:T D 198.51.100.9: 80:0, Protocol: T CP
LSN session Local4.Informational 10.102.37.115 08/05/2014:10:05:12 GMT 0-PPE-0 : LSN LSN_SESSION 3871790 : SESSION DELET ED Client IP:Port:T D 192.0.2.11: 15130:0,
deletion NatIP:NatPort 203.0.113.6: 7887, Destination IP:Port:T D 198.51.101.2:80:0, Protocol: T CP
LSN mapping Local4.Informational 10.102.37.115 08/05/2014:09:59:47 GMT 0-PPE-0 : LSN LSN_MAPPING 2581580 : EIM CREAT ED Client IP:Port 192.0.2.15: 14567,
creation NatIP:NatPort 203.0.113.5: 8214, Protocol: T CP
LSN mapping Local4.Informational 10.102.37.115 08/05/2014:10:05:12 GMT 0-PPE-0 : LSN LSN_MAPPING 3871700 : EIM DELET ED Client IP:Port 192.0.3.15: 14565,
deletion NatIP:NatPort 203.0.113.11: 8217, Protocol: T CP
Minimal Logging
T he minimal logging feature for deterministic LSN configurations and dynamic LSN configurations with port block is enabled by default and there is no provision to disable it. In other
words, the NetScaler appliance automatically do minimal logging for deterministic LSN configurations and dynamic LSN configurations with port block. T here is no option available for
disabling this feature. T he NetScaler sends the log messages to all the configured log servers.
A log message for each port block consists of the following information:
NSIP address of the NetScaler appliance
T ime stamp
Entry type as DET ERMINIST IC or PORT BLOCK
Whether a port block is allocated or is freed
Subscriber’s IP address and the assigned NAT IP address and port block
Protocol name
In this LSN configuration, the port block size is set to 32768 and LSN NAT IP address pool has IP addresses in the range 203.0.113.19-203.0.113.23.
T he NetScaler appliance does not log any LSN session created or deleted for these subscribers. T he NetScaler generates the following log messages for the LSN configuration.
1) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201453 0 : Dtrstc ALLOC Client 12.0.0.241, NatInfo 50.0.0.2:59904 to 60415
2) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201454 0 : Dtrstc ALLOC Client 12.0.0.242, NatInfo 50.0.0.2:60416 to 60927
3) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201455 0 : Dtrstc ALLOC Client 12.0.0.243, NatInfo 50.0.0.2:60928 to 61439
4) 03/23/2015:00:30:56 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201455 0 : Dtrstc ALLOC Client 12.0.0.243, NatInfo 50.0.0.2:60928 to 61439
When you remove the LSN configuration, the allocated NAT IP address and block of ports is freed from each subscriber. T he NetScaler logs NAT IP address and block of ports freed
from each subscriber. T he NetScaler generates the following log messages for each subscriber when you remove the LSN configuration.
1) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201706 0 : Dtrstc FREE Client 12.0.0.238, NatInfo 50.0.0.2:58368 to 58879
2) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201707 0 : Dtrstc FREE Client 12.0.0.239, NatInfo 50.0.0.2:58880 to 59391
3) 03/23/2015:00:33:57 GMT Informational 0-PPE-0 : default LSN LSN_DETERMINISTIC 79201708 0 : Dtrstc FREE Client 12.0.0.240, NatInfo 50.0.0.2:59392 to 59903
Minimal Logging for Dynamic LSN Configuration with Port Block
Consider an example of a simple dynamic LSN configuration with port block for any subscriber in the network 192.0.2.0/24. In this LSN configuration, the port block size is set to 1024
and LSN NAT IP address pool has IP addresses in the range 203.0.113.3-203.0.113.4.
T he NetScaler generates the following log message when the subscriber, having the IP address 192.0.2.1, initiates a session. T he log message shows that the NetScaler has allocated
NAT IP address 203.0.113.3 and port block 1024-2047 to the subscriber.
03/23/2015:00:07:12 GMT Informational 0-PPE-3 : default LSN LSN_PORTBLOCK 106725793 0 : Portblock ALLOC Client 12.0.2.72, NatInfo 203.0.113.3:1024 to 2047, Proto:TCP
Once there are no more sessions left that is using the allocated NAT IP address and one of the ports in the allocated port block, the allocated NAT IP address and block of ports is
freed from the subscriber. T he NetScaler logs that the NAT IP address and the block of ports is freed from the subscriber. T he NetScaler generates the following log messages for the
subscriber, having the IP address 192.0.2.1 , when no more sessions are left that is using the allocated NAT IP address ( 203.0.113.3 ) and a port from the allocated port block ( 1024-
2047 ). T he log message shows that the NAT IP address and port block are freed from the subscriber.
03/23/2015:00:11:09 GMT Informational 0-PPE-3 : default LSN LSN_PORTBLOCK 106814342 0 : Portblock FREE Client 12.0.3.122, NatInfo 203.0.113.3: 1024 to 2047, Proto:TC
Load Balancing SYSLOG Servers
T he NetScaler appliance send its SYSLOG events and messages to all the configured external log servers. T his results in storing redundant messages and makes monitoring difficult for
system administrators. To address this issue, the NetScaler appliance offers load balancing algorithms that can load balance the SYSLOG messages among the external log servers for
better maintenance and performance. T he supported load balancing algorithms include RoundRobin, LeastBandwidth, CustomLoad, LeastConnection, LeastPackets, and
AuditlogHash.
2. Add a load balancing virtual server, specify the service type as SYSLOGT CP or SYSLOGT CP, and load balancing method as AUDIT LOGHASH.
add lb vserver <name> <serviceType (SYSLOGTCP | SYSLOGUDP)> [-lbMethod <AUDIT LOGHASH>]
4. Add a SYSLOG action and specify the load balancing server name that has SYSLOGT CP or SYSLOGUDP as service type.
add syslogaction <name> <serverIP> [-lbVserverName <string>] [-logLevel <logLevel>]
6. Bind the SYSLOG policy to the system global for the policy to take effect.
bind system global <policyName>
2. Add a load balancing virtual server, specify the service type as SYSLOGT CP or SYSLOGT CP, and load balancing method as AUDIT LOGHASH.
Navigate to Traffic Management > Virtual Servers, click Add and select SYLOGTCP or SYSLOGUDPas protocol.
3. Bing the service to the load balancing virtual server to the service.
Bing the service to the load balancing virtual server.
Navigate to Traffic Management > Virtual Servers, select a virtual server and then selectAUDIT LOGHASH in the Load Balancing Method.
4. Add a SYSLOG action and specify the load balancing server name that has SYSLOGT CP or SYSLOGUDP as service type.
Navigate to System > Auditing, click Servers and add a server by selecting LB Vserver option inServers.
6. Bind the SYSLOG policy to the system global for the policy to take effect.
Navigate to System > Syslog, select a SYSLOG policy and click Action, and then click Global Bindings and bind the policy to system global.
Example
T he following configuration specifies load balance of SYSLOG messages among the external log servers using the AUDIT LOGHASH as load balancing method. T he NetScaler appliance
generates SYSLOG events and messages that are load balanced amongst the services, service1, service2, and service 3.
Updated: 2015-05-12
T he NetScaler appliance can now log request header information of an HT T P connection that is using the LSN fucntionality of the NetScaler. T he following header information of an
HT T P request packet can be logged:
URL that the HT T P request is destined to.
HT T P Method specified in the HT T P request.
HT T P version used in the HT T P request.
IP address of the subscriber that sent the HT T P request.
T he HT T P header logs can be used by ISPs to see the trends related to the HT T P protocol among a set a subscribers. For example, an ISP can use this feature to find out the most
popular websites among a set of subscribers.
An HT T P header log profile is a collection of HT T P header attributes (for example, URL and HT T P method) that can be enabled or disabled for logging. T he HT T P header log profile is
then bound to an LSN group. T he NetScaler appliance then logs HT T P header attributes, which are enabled in the bound HT T P header log profile for logging, of any HT T P requests
related to the LSN group. T he NetScaler then sends the log messages to the configured log servers.
An HT T P header log profile can be bound to multiple LSN groups but an LSN group can have only one HT T P header log profile.
To create an HTTP header log profile by using the the command line interface
At the command prompt, type:
add lsn httphdrlogprofile <httphdrlogprofilename> [-logURL ( ENABLED | DISABLED )] [-logMethod ( ENABLED | DISABLED )] [-logVersion ( ENABLED | DISABLED )] [-logHost (
ENABLED | DISABLED )]
show lsn httphdrlogprofile
To bind an HTTP header log profile to an LSN group by using the the command line interface
At the command prompt, type:
Example
In the following example of an LSN configuration, HT T P header log profile HT T P-Header-LOG-1 is bound to LSN group LSN-GROUP-1. T he log profile has all the HT T P attributes (URL,
HT T P method, HT T P version, and HOST IP address) enabled for logging so that all these attributes are logged for any HT T P requests from subscribers (in the network 192.0.2.0/24)
related to the LSN group.
T he log message tells us that a client having the IP address 192.0.2.33 sends an HT T P request to URL example.com using HT T P method GET and HT T P version 1.1.
03/19/2015:16:24:04 GMT Informational 0-PPE-1 : default LSN Message 59 0 : "LSN Client IP:TD 10.102.37.118:0 URL: example.com Host: 192.0.2.33 Version: HTTP1.1 Method: GET"
Logging MSISDN Inf ormation
A Mobile Station Integrated Subscriber Directory Number (MSISDN) is a telephone number uniquely identifying a subscriber across multiple mobile networks. T he MSISDN is associated
with a country code and a national destination code identifying the subscriber's operator.
You can configure a NetScaler appliance to include MSISDNs in LSN log entries for subscribers in mobile networks. T he presence of MSISDNs in the LSN logs helps the administrator in
faster and accurate back tracing of a mobile subscriber who has violated a policy or law, or whose information is required by lawful interception agencies.
T he following sample LSN log entries include MSISDN information for a connection from a mobile subscriber in an LSN configuration. T he log entries show that a mobile subscriber
whose MSISDN is E164:5556543210 was connected to destination IP:port 23.0.0.1:80 through the NAT IP:port 203.0.113.3:45195.
LSN session Oct 14 15:37:30 10.102.37.77 10/14/2015:10:08:14 GMT 0-PPE-6 : default LSN LSN_SESSION 25012 0 : SESSION CREAT ED E164:5556543210 Client
IP:Port:T D 192.0.2.50:4649:0, NatIP:NatPort 203.0.113.3:45195, Destination IP:Port:T D 23.0.0.1:0:0, Protocol: TCP
creation
LSN mapping creation Oct 14 15:37:30 10.102.37.77 10/14/2015:10:08:14 GMT 0-PPE-6 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM
CREAT ED E164:5556543210 Client IP:Port:T D 192.0.2.50:4649:0, NatIP:NatPort 203.0.113.3:45195, Destination IP:Port:T D 23.0.0.1:0:0, Protocol: TCP
LSN session deletion Oct 14 15:40:30 10.102.37.77 10/14/2015:10:11:14 GMT 0-PPE-6 : default LSN LSN_SESSION 25012 0 : SESSION CREAT ED E164:5556543210 Client
IP:Port:T D 192.0.2.50:4649:0, NatIP:NatPort 203.0.113.3:45195, Destination IP:Port:T D 23.0.0.1:0:0, Protocol: TCP
LSN mapping
Oct 14 15:40:30 10.102.37.77 10/14/2015:10:11:14 GMT 0-PPE-6 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM
CREAT ED E164:5556543210 Client IP:Port:T D 192.0.2.50:4649:0, NatIP:NatPort 203.0.113.3:45195, Destination IP:Port:T D 23.0.0.1:0:0, Protocol: TCP
Perform the following tasks for including MSISDN information in LSN logs:
Create an LSN log prof ile. An LSN log profile includes the log subscriber ID parameter, which specifies whether to or not to include the MSISDN information in the LSN logs of an
LSN configuration. Enable the log subscriber ID parameter when creating the LSN log profile.
Bind the LSN log prof ile to an LSN group of an LSN conf iguration. Bind the created LSN log profile to an LSN group of an LSN configuration by setting the log profile name
parameter to the created LSN log profile name. For instructions on configuring Large Scale NAT , see Configuration Steps for LSN.
To bind an LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
In this example of LSN configuration, the LSN log profile has the log subscriber ID parameter enabled. The profile is bound to LSN group LSN-GROUP-9. MSISDN information is included in the LSN session and LSN m
Done
Done
Done
Done
Done
Done
Done
Done
You can display the current LSN sessions for detecting any unwanted or inefficient LSN sessions on the NetScaler appliance. You can display all or some LSN sessions on the basis of
selection parameters.
Note: When more than a million LSN sessions exist on the NetScaler appliance, Citrix recommends displaying selected LSN sessions instead of all by using the selection parameters.
Configuration Using the Command Line Interface
To display all LSN sessions by using the command line interface
show lsn session [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <ip_addr> [-natPort <port>]]
Example
To display all LSN sessions existing on a NetScaler ADC
Done
Done
To display all LSN sessions that uses 203.0.113.5 as the NAT IP address
1. Navigate to System > Large Scale NAT > Sessions, and click the NAT 44 tab.
2. For displaying LSN sessions on the basis of selection parameters, click Search.
td
Traffic domain ID of the LSN client entity.
Default value: 0
Minimum value: 0
You can display statistics related to the LSN feature for evaluating the performance of the LSN feature or to troubleshoot problems. You can display a summary of statistics of the
LSN feature or of a particular LSN group. T he statistical counters reflect events since the NetScaler appliance was last restarted. All these counters are reset to 0 when the NetScaler
appliance is restarted.
stat lsn
To display statistics for a specified LSN group by using the command line interface
At the command prompt, type:
Done
Done
f ullValues
Specifies that numbers and strings should be displayed in their full form. Without this option, long strings are shortened and large numbers are abbreviated.
ntimes
T he number of times, in intervals of seven seconds, the statistics should be displayed.
Default value: 1
logFile
T he name of the log file to be used as input.
clearstats
Clear the statsistics / counters
Compact Logging
Logging LSN information is one of the important functions needed by ISPs to meet legal requirements and be able to identify the source of traffic at any given time. T his eventually
results in a huge volume of log data, requiring the ISPs to make large investments to maintain the logging infrastructure.
Compact logging is a technique for reducing the log size by using a notational change involving short codes for event and protocol names. For example, C for client, SC for session
created, and T for TCP. Compact logging results in an average of 40 percent reduction in log size.
T he following examples of NAT 44 mapping creation log entries show the advantage of compact logging.
Default logging format 02/02/2016:01:13:01 GMT Informational 0-PPE-2 : default LSN LSN_ADDRPORT _MAPPING 85 0 : A&PDM CREAT ED
ClientIP:Port:T D1.1.1.1:6500:0,NatIP:NatPort8.8.8.8:47902, DestinationIP:Port:T D2.2.2.2:80:0, Protocol: TCP
Configuration Steps
Perform the following tasks for logging LSN information in compact format:
Create an LSN log prof ile. An LSN log profile includes the Log Compact parameter, which specifies whether to or not to log information in compact format for an LSN
configuration.
Bind the LSN log prof ile to an LSN group of an LSN conf iguration. Bind the created LSN log profile to an LSN group of an LSN configuration by setting the Log Profile Name
parameter to the created LSN log profile name. All sessions and mappings for this LSN group are logged in compact format.
To bind an LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
Done
Done
Done
Done
Done
Done
Done
Done
IPFIX Logging
T he NetScaler appliance supports sending information about LSN events in Internet Protocol Flow Information Export (IPFIX) format to the configured set of IPFIX collector(s). T he
appliance uses the existing AppFlow feature to send LSN events in IPFIX format to the IPFIX collectors.
IPFIX based logging is available for the following large scale NAT 44 related events:
You must configure the AppFlow feature and IPFIX collector(s) on the NetScaler appliance. For instructions, see Configuring the AppFlow feature.
Configuration Steps
Perform the following tasks for logging LSN information in IPFIX format:
Enable LSN logging in the AppFlow conf iguration. Enable the LSN logging parameter as part of AppFlow configuration.
Create an LSN log prof ile. An LSN log profile includes the IPFIX parameter that enables or disables the log information in IPFIX format.
Bind the LSN log prof ile to an LSN group of an LSN conf iguration. Bind the LSN log profile to one or multiple LSN group(s). Events related to the bound LSN group will be
logged in IPFIX format.
To enable LSN logging in the AppFlow configuration by using the NetScaler command line
To create an LSN log profile by using the NetScaler command lineAt the command prompt , type:
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
Navigate to System > Large Scale NAT > Profiles, click Log tab, and then add a log profile.
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler GUI
1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Prof ile to bind the created Log profile to the LSN group.
In an LSN deployment of a NetScaler appliance for an ISP, interactive communication applications (for example real-time voice, video, and messaging) running on a subscribers can use the ST UN
protocol to discover whether it is behind a NAT (NetScaler appliance) device or not. T hese applications send a request to a known ST UN server. On receiving the request, the NetScaler allocates a NAT
IP address and a port for this request, creates an LSN session and an LSN mapping entry, translates the packet with the allocated NAT IP address and port, and then forwards the packet to the
ST UN server. T he ST UN server embeds the allocated NAT IP address and port in the payload of its response packet. When the subscriber finally receives the packet, from the payload of the packet it
learns that it is behind a NAT device, and the NAT IP address and port allocated for the session.
T he application then notifies the peer applications that it is reachable at the NAT IP address and the port of the LSN mapping entry created for the ST UN session. It notifies by embedding the NAT
IP address and port in the payload of the packets sent to the peer applications. For making the application reachable at the same LSN mapping entry for any external application, full Cone NAT
(endpoint Independent mapping and Endpoint Independent filtering) is enabled for the LSN configuration on the NetScaler.
T he NetScaler detects an LSN session of type ST UN if the request packets are destined to TCP or UDP port 3478, and then marks the created mapping entry of type ST UN. T he NetScaler applies a
timeout called, ST UN timeout, to the created ST UN LSN mapping entry. A ST UN timeout is the maximum time that the NetScaler maintains an idle ST UN LSN mapping entry since it was last used by
any LSN session. If the ST UN LSN mapping session is unused for a time that exceeds the ST UN timeout, the NetScaler removes the mapping entry.
For an application on a subscriber that use ST UN LSN mapping entry to stay available to other peer applications on the Internet, the application periodically sends keep-alive messages to the
NetScaler appliance so that the ST UN LSN mapping entry does not timeout. A higher frequency of keep-alive messages can have an affect on the performance a subscriber, especially, if the
subscriber is a mobile device. A higher value of ST UN timeout reduces the frequency of keep-alive messages from a subscriber.
ALGs on the NetScaler appliance do not apply to an LSN session that use a ST UN LSN mapping entry because NAT IP address and NAT port are communicated in payload of the packets related to
the session.
For subscribers’ applications that use ST UN protocol, the LSN configuration must have the following settings:
ST UN timeout. In an LSN configuration, the LSN group includes the ST UN timeout setting.
Endpoint-independent mapping and endpoint-independent filtering for ST UN protocol ports.
For instructions on creating an LSN configuration, see Configuration Steps for LSN.
Example
The following sample LSN configuration applies to applications that use STUN protocol over TCP or UDP. STUN timeout is set to 10 mins. Endpoint-independent mapping and endpoint-independent filtering is set f
>add lsn client LSN-CLIENT-1
Done
>bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
Done
>add lsn pool LSN-POOL-1
Done
>bind lsn pool LSN-POOL-1 203.0.113.3
Done
>add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 -stuntimeout 10
Done
>bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
Done
>add lsn appsprofile LSNAPPSPROFILE-TCP-STUN-1 TCP -mapping ENDPOINT-INDEPENDENT –filtering ENDPOINT-INDEPENDENT
Done
>bind lsn appsprofile LSNAPPSPROFILE-TCP-STUN-1 3748
Done
>bind lsn group LSN-GROUP-1 -applicationprofilename LSNAPPSPROFILE-TCP-STUN-1
Done
>add lsn appsprofile LSNAPPSPROFILE-UDP-STUN-1 UDP -mapping ENDPOINT-INDEPENDENT –filtering ENDPOINT-INDEPENDENT
Done
>bind lsn appsprofile LSNAPPSPROFILE-UDP-STUN-1 3748
Done
>bind lsn group LSN-GROUP-1 -applicationprofilename LSNAPPSPROFILE-UDP-STUN-1
Done
Example
In the following sample LSN configuration, SYN idle timeout is set to 30 secs for TCP connections related to subscribers from the 192.0.2.0/24 network.
>add lsn client LSN-CLIENT-1
Done
>bind lsn client LSN-CLIENT-1 -network 192.0.2.0 -netmask 255.255.255.0
Done
>add lsn pool LSN-POOL-1
Done
>bind lsn pool LSN-POOL-1 203.0.113.3
Done
>add lsn group LSN-GROUP-1 -clientname LSN-CLIENT-1 –synidletimeout 30
Done
>bind lsn group LSN-GROUP-1 -poolname pool1 LSN-POOL-1
Done
T his option is useful in an LSN deployment that includes NetScaler appliances and value added services, such as firewall and
optimization devices. In this type of deployment, the ingress traffic on the NetScaler appliance is required to pass through
these value-added services before an LSN configuration on the appliance is applied to the traffic. For the NetScaler
appliance to send the ingress traffic to a value added service, a load balancing configuration is created and override LSN is
enabled on the appliance. T he load balancing configuration includes value added services, represented as load balancing
services, bound to a virtual server of type ANY. T he virtual server is configured with listen policies for identifying the traffic
to be sent to the value added service.
To enable override lsn in a net profile by using the NetScaler command line
T o enable override lsn while adding a net profile, at the command prompt, type:
add netProf ile <name> -overrideLsn ( ENABLED | DISABLED )
show netprof ile <name>
T o enable override lsn while adding a net profile, at the command prompt, type:
set netProf ile <name> -overrideLsn ( ENABLED | DISABLED )
show netprof ile <name>
In the following sample configuration, net profile NET PROFILE-OVERRIDELSN-1 has override LSN option enabled and is
bound to load balancing virtual server LBVS-1.
Done
Done
To clear all LSN sessions by using the command line interf ace
To clear selective LSN sessions by using the command line interf ace
flush lsn session [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-td <positive_integer>]] [-natIP <ip_addr> [-
natPort <port>]]
show lsn session
Example
Clear all LSN sessions existing on a NetScaler ADC
> flush lsn session
Done
Clear all LSN sessions related to a subscriber network (192.0.2.0) of LSN client entity LSN-CLIENT-2 belonging to traffic domain 100
> flush lsn session -clientname LSN-CLIENT-2 –network 192.0.2.0 –netmask 255.255.255.0 –td 100
Done
To clear all LSN sessions by using the configuration utility
Navigate to System > Large Scale NAT > Sessions, and click Flush Sessions.
Parameter Descriptions (of commands listed in the CLI procedure)
td
Default value: 0
Minimum value: 0
natIP
Mapped NAT IP address used in LSN sessions.
natPort
Mapped NAT port used in the LSN sessions.
T he NetScaler appliance send its SYSLOG events and messages to all the configured external log servers. T his results in
storing redundant messages and makes monitoring difficult for system administrators. To address this issue, the NetScaler
appliance offers load balancing algorithms that can load balance the SYSLOG messages among the external log servers for
better maintenance and performance. T he supported load balancing algorithms include RoundRobin, LeastBandwidth,
CustomLoad, LeastConnection, LeastPackets, and AuditlogHash.
2. Add a load balancing virtual server, specify the service type as SYSLOGT CP or SYSLOGT CP, and load balancing method as
AUDIT LOGHASH.
add lb vserver <name> <serviceType (SYSLOGTCP | SYSLOGUDP)> [-lbMethod <AUDIT LOGHASH>]
4. Add a SYSLOG action and specify the load balancing server name that has SYSLOGT CP or SYSLOGUDP as service type.
add syslogaction <name> <serverIP> [-lbVserverName <string>] [-logLevel <logLevel>]
6. Bind the SYSLOG policy to the system global for the policy to take effect.
bind system global <policyName>
2. Add a load balancing virtual server, specify the service type as SYSLOGT CP or SYSLOGT CP, and load balancing method as
AUDIT LOGHASH.
Navigate to Traffic Management > Virtual Servers, click Add and select SYLOGTCP or SYSLOGUDPas protocol.
3. Bing the service to the load balancing virtual server to the service.
Bing the service to the load balancing virtual server.
Navigate to Traffic Management > Virtual Servers, select a virtual server and then selectAUDIT LOGHASH in the Load
Balancing Method.
4. Add a SYSLOG action and specify the load balancing server name that has SYSLOGT CP or SYSLOGUDP as service type.
Navigate to System > Auditing, click Servers and add a server by selecting LB Vserver option inServers.
6. Bind the SYSLOG policy to the system global for the policy to take effect.
Navigate to System > Syslog, select a SYSLOG policy and click Action, and then click Global Bindings and bind the policy
to system global.
Example
T he following configuration specifies load balance of SYSLOG messages among the external log servers using the
AUDIT LOGHASH as load balancing method. T he NetScaler appliance generates SYSLOG events and messages that are load
balanced amongst the services, service1, service2, and service 3.
Limitations
T he NetScaler appliance does not support an external load balancing virtual server load balancing the SYSLOG messages
among the log servers.
Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself and/or for other 3rd party
devices. T he large scale NAT device creates an LSN map and sends it to the subscriber. T he subscriber sends the remote
devices on the Internet the NAT IP address:NAT port at which they can connect to the subscriber.
Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN mappings do not
time out. PCP helps reduce the frequency of such keep-alive messages by enabling the applications to learn the timeout
settings of the LSN mappings. T his helps reduce bandwidth consumption on the ISP’s access network and battery
consumption on mobile devices.
PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance implements the PCP server
component and is compliant with RFC 6887.
Configuration Steps
(Optional) Create a PCP profile. A PCP profile includes settings for PCP related parameters (for example, to listen for
mapping and peer PCP requests). A PCP profile can be bound to a PCP server. A PCP profile bound to a PCP server applies
all its settings to the PCP server. A PCP profile can be bound to multiple PCP servers. By default, one PCP profile with
default parameters settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the default
PCP profile settings for that server. A default PCP profile has the following parameter settings:
Mapping: Enabled
Peer: Enabled
Minimum map life: 120 seconds
Maximum max life: 86400 seconds
Announce count: 10
T hird Party: Disabled
Create a PCP server and bind a PCP profile to it. Create a PCP server on the NetScaler appliance to listen for PCP related
requests and messages from the subscribers. A Subnet IP (SNIP) address must be assigned to a PCP server to access it.
By default, a PCP server listens on port 5351.
Bind the PCP server to an LSN group of an LSN configuration. Bind the created PCP server to an LSN group of an LSN
configuration by setting the PCP Server parameter to specify the created PCP server. T he created PCP server can be
accessed only by the subscribers of this LSN group.
Note
A PCP server for a large scale NAT configuration does not serve requests from subscribers that are identified from ACL rules.
add pcp prof ile <name> [-mapping ( ENABLED | DISABLED )] [-peer ( ENABLED | DISABLED )] [-minMapLif e <secs>] [-
maxMapLif e <secs>] [-announceMultiCount <positive_integer>][-thirdParty ( ENABLED | DISABLED )]
show pcp profile <name>
add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProf ile <string>]
show pcp server <name>
Done
Done
Done
Done
Done
Done
Done
Done
Dual Stack Lite (DS-Lite) is an IPv6 transition solution for ISPs with IPv6 infrastructure to connect their IPv4 subscribers to
the Internet. DS-Lite uses IPv4-in-IPv6 tunneling to send a subscriber’s IPv4 packet through a tunnel on the IPv6 access
network to the ISP. T he IPv6 packet is decapsulated to recover the subscriber’s IPv4 packet and is then sent to the
Internet after NAT address and port translation and other LSN related processing. T he response packets traverse through
the same path to the subscriber.
T he NetScaler appliance implements the AFT R component of a DS-Lite deployment and is compliant with RFC 6333.
Architecture
Example
Architecture
Basic Bridging Broadband (B4 ). Basic Bridging broadband, or B4, is a device or component that resides in the subscriber
premises. T ypically, B4 is a component in the CPE devices in the subscriber premises. IPv4 subscribers are connected to
the IPv6-only ISP access network through the CPE device containing the B4 component. T he main function of the B4 is
to initiate an IPv6 tunnel between B4 and an address family transition router (AFT R) in order to send or receive subscriber
IPv4 request or response packets over the tunnel. B4 includes an IPv6 address known as the B4 tunnel endpoint
address. B4 uses this address to source IPv6 packets to AFT R and receive packets from AFT R.
Address f amily transition router (AFTR). AFT R is a device or component residing in the ISP’s core network. AFT R
terminates the IPv6 tunnel from the B4 device. In other words, the IPv6 tunnel is formed between B4 in the subscriber
premise and AFT R in ISP core network. AFT R decapsulates IPv6 packets received from B4 to recover the subscribers’
original IPv4 packets. AFT R sends the IPv4 packets to the LSN device or component. LSN routes the IPv4 packets to
their destination after performing NAT address and port translation (NAT 44) and other LSN related processing. AFT R
includes an IPv6 address known as the AFT R tunnel endpoint address. AFT R uses this address to source IPv6 packets to
B4 and receive IPv6 packets from B4. T he NetScaler appliance implements the AFT R component.
Sof twire. T he IPv6 tunnel created between B4 and AFT R is called a softwire.
IPv4 subscribers connected to the CPE device are assigned private IPv4 addresses either manually or through DHCP
server running on the CPE device. On the CPE device, the AFT R tunnel endpoint address is specified manually or through
DHCPv6. Configuration of CPE devices is vendor specific and therefore outside the scope of this documentation.
Upon receiving a request packet that is from an IPv4 subscriber and destined to a location on the Internet, the B4
component of the CPE device encapsulates the IPv4 packet in an IPv6 packet and sends it to the NetScaler appliance in
the ISP core network. T he NetScaler appliance‘s AFT R functionality decapsulates the IPv6 packet to recover
the subscriber’s original IPv4 packet. T he LSN functionality of the NetScaler appliance translates the source IP address and
port of the IPv4 packet to an NAT IP address and NAT port selected from the configured NAT pool, and then sends the
packet to its destination on the Internet.
T he appliance maintains a record of all active sessions that use the AFT R and LSN functionalities. T hese sessions are called
DS-Lite sessions. T he NetScaler appliance also maintains the mappings between B4 IPv6 address, subscriber IPv4 address
and port, and NAT IPv4 address and port, for each DS-Lite session. T hese mappings are called DS-Lite LSN mappings. From
DS-Lite session entries and DS-Lite LSN mapping entries, the NetScaler appliance recognizes a response packet (received
from the Internet) as belonging to a particular DS-Lite session.
When the NetScaler appliance receives a response packet belonging to a particular DS-Lite session, the appliance’s LSN
functionality translates the destination IP address and port of the response packet from NAT IP address and port to the
subscriber IP address and port, the AFT R functionality encapsulates the resulting packet in an IPv6 packet and sends it to
the CPE device. T he B4 functionality of the CPE device decapsulates the IPv6 packet to recover the IPv4 response packet,
and then sends the IPv4 packet to the subscriber.
Example
Consider an example of a DS-Lite deployment consisting of NetScaler NS-1 in an ISP’s core network, CPE device B4-CPE-1
in a subscriber premise, and a single IPv4 subscriber SUB-1. B4-CPE-1 supports the B4 functionality of DS-Lite feature.
2. Upon receiving the IPv4 request packet, B4-CPE-1 encapsulates it in the payload of an IPv6 packet and then sends the
IPv6 packet to NS-1. T he IPv6 packet has:
3. When NS-1 receives the IPv6 packet, the AFT R module decapsulates the packet by removing the IPv6 headers. T he
resulting packet is SUB-1’s original IPv4 request packet.
4. T he LSN module of NS-1 translates the source IP address and port of the packet to an NAT IP address and NAT port
selected from the configured NAT pool. T he translated IPv4 packet has:
5. T he LSN module also creates an LSN mapping and session entry for this DS Lite session. T he mapping includes the
following information:
6. NS-1 sends the resulting IPv4 packet to its destination on the Internet.
7. T he server for www.example.com processes the request packet and sends a response packet. T he IPv4 response
packet has:
9. T he AFT R module of NS-1 encapsulates the IPv4 packet in an IPv6 packet and then sends the IPv6 packet to B4-CPE-
1. T he IPv6 packet has:
10. Upon receiving the packet, B4-CPE-1 decapsualtes the IPv6 packet by removing the IPv6 headers, and then sends the
resulting IPv4 packet to CL-1.
1. You must understand the different components of DS-Lite, described in RFC 6333.
2. A DS-lite configuration on a NetScaler appliance uses the LSN commands sets. In a DS-Lite configuration, the LSN client
entity specifies the IPv6 address or IPv6 network address or ACL6 rules for identifying the traffic from the B4 device. A DS-
Lite configuration also includes an IPv6 profile, which specifies the IPv6 address AFT R component on a NetScaler appliance.
For more information on NetScaler’s LSN feature, see Large Scale NAT .
3. For a DS-Lite configuration, the NetScaler appliance supports LSN for IPv4 packets that belong to one of the
following protocols only. T he NetScaler appliance drops IPv4 packets belonging to other protocols:
T CP
UDP
ICMP
ICMP
FT P
T FT P
Session Initiation Protocol (SIP)
Real T ime Streaming Protocol (RT SP)
Set the global LSN parameters. Global parameters include the amount of NetScaler memory reserved for the LSN
feature and synchronization of LSN sessions in a high availability setup.
Create an LSN client entity f or identif ying traf f ic f rom B4 CPE devices. T he LSN client entity refers to a set of DS-
Lite B4 devices. T he client entity includes IPv6 addresses or IPv6 network address or ACL6 rules for identifying the traffic
from these B4 devices. An LSN client can be bound to only one LSN group. T he command line interface has two
commands for creating an LSN client entity and binding a subscriber to the LSN client entity. T he configuration utility
combines these two operations on a single screen.
Create an LSN pool and bind NAT IP addresses to it. An LSN pool defines a pool of NAT IP addresses to be used by
the NetScaler appliance to perform LSN. T he command line interface has two commands for creating an LSN pool and
binding NAT IP addresses to the LSN pool. T he configuration utility combines these two operations on a single screen.
Create an LSN IP6 prof ile. An LSN IP6 profile defines the IPv6 address of the DS-Lite AFT R component on the
NetScaler appliance. T he IPv6 address must be one of the NetScaler owned IPv6 address of type SNIP6.
(Optional) Create an LSN Transport Prof ile f or a specif ied protocol. An LSN transport profile defines various
timeouts and limits, such as maximum LSN sessions and maximum ports usage that a subscriber can have for a given
protocol. You bind an LSN transport profile for each protocol (T CP, UDP, and ICMP) to an LSN group. A profile can be
bound to multiple LSN groups. A profile bound to an LSN group applies to all subscribers of an LSN client bound to the
same group. By default, one LSN transport profile with default settings for T CP, UDP, and ICMP protocols is bound to an
LSN group during its creation. T his profile is called the default transport profile. An LSN transport profile that you bind to
an LSN group overrides the default LSN transport profile for that protocol.
(Optional) Create an LSN Application Prof ile f or a specif ied protocol and bind a set of destination ports to
it. An LSN application profile defines the LSN mapping and LSN filtering controls of a group for a given protocol and for
a set of destination ports. For a set of destination ports, you bind an LSN profile for each protocol (T CP, UDP, and ICMP)
to an LSN group. A profile can be bound to multiple LSN groups. An LSN application profile bound to an LSN group
applies to all subscribers of an LSN client bound to the same group. By default, one LSN application profile with default
settings for T CP, UDP, and ICMP protocols for all destination ports is bound to an LSN group during its creation. T his
profile is called a default application profile. When you bind an LSN application profile, with a specified set of destination
ports, to an LSN group, the bound profile overrides the default LSN application profile for that protocol at that set of
destination ports. T he command line interface has two commands for creating an LSN application profile and binding a
set of destination ports to the LSN application profile. T he configuration utility combines these two operations on a
single screen.
Create an LSN Group and bind LSN pools, LSN IPv6 prof ile, (optional) LSN transport prof iles, and (optional) LSN
application prof iles to the LSN group. An LSN group is an entity consisting of an LSN client, an LSN IPv6 profile, LSN
pool(s), LSN transport profile(s), and LSN application profiles(s). A group is assigned parameters, such as port block size
and logging of LSN sessions. T he parameter settings apply to all the subscribers of an LSN client bound to the LSN
group. Only one LSN IPv6 profile can be bound to an LSN group, and an LSN IPv6 profile bound to an LSN group cannot
be bound to other LSN groups. Only LSN Pools and LSN groups with the same NAT type settings can be bound
To bind an IPv6 network or an ACL6 rule to an LSN client by using the command line interf ace
To bind an IP address range to an LSN pool by using the command line interf ace
Note: For removing LSN IP addresses from an LSN pool, use the unbind lsn pool command.
To configure an LSN IPv6 profile by using the command line interf ace
add lsn ip6prof ile <name> –type DS-Lite –network6 < ipv6_addr|*s >
show lsn ip6prof ile
To create an LSN transport profile by using the command line interf ace
add lsn transportprof ile <transportprofilename> <transportprotocol> [-sessiontimeout <secs>] [-f inrsttimeout
<secs>] [-portquota <positive_integer>] [-sessionquota <positive_integer>] [-portpreserveparity ( ENABLED |
DISABLED )] [-portpreserverange (ENABLED | DISABLED )] [-syncheck ( ENABLED | DISABLED )]
show lsn transportprof ile
add lsn appsprof ile <appsprofilename> <transportprotocol> [-ippooling (PAIRED | RANDOM )] [-mapping <mapping>]
[-f iltering <filtering>][-tcpproxy ( ENABLED | DISABLED )] [-td <positive_integer>]
show lsn appsprof ile
To bind an application protocol port range to an LSN application profile by using the command line interf ace
add lsn group <groupname> -clientname <string> [-nattype ( DYNAMIC )] [-portblocksize <positive_integer>] [-
logging (ENABLED | DISABLED )] [-sessionLogging ( ENABLED | DISABLED )][-sessionSync ( ENABLED | DISABLED )] [-
snmptraplimit<positive_integer>] [-f tp ( ENABLED | DISABLED )] [-pptp ( ENABLED |DISABLED )] [-sipalg ( ENABLED |
DISABLED )] [-rtspalg ( ENABLED |DISABLED )] [-ip6prof ile <string>]
show lsn group
To bind LSN protocol profiles and LSN pools to an LSN group by using the command line interf ace
bind lsn group <groupname> (-poolname <string> | -transportprof ilename <string> | -httphdrlogprof ilename
<string> | -appsprof ilename <string> | -sipalgprof ilename <string> | rtspalgprofilename <string>)
show lsn group
To configure an LSN client and bind an IPv6 network address or an ACL6 rule by using the configuration utility
Navigate to System > Large Scale NAT > Clients, and add a client and then bind an IPv6 network address or an ACL6 rule
to the client.
To configure an LSN pool and bind NAT IP addresses by using the configuration utility
Navigate to System > Large Scale NAT > Pools, and add a pool and then bind an NAT IP address or a range of NAT IP
addresses to the pool.
Navigate to System > Large Scale NAT > Profiles, click the IPv6 tab, and assign an IPv6 address for DS-Lite AFT R.
To configure an LSN group and bind an LSN client , an LSN IPv6 profile, pools, transport profiles, and application
profiles by using the configuration utility
Navigate to System > Large Scale NAT > Groups, and add a group and then bind an LSN client, an LSN IPv6 profile, pools,
transport profiles, and application profiles to the group.
Example COPY
Done
Done
Done
Done
Done
> add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1
Done
Done
You can log DS-Lite information to diagnose or troubleshoot problems, and to meet legal requirements. T he NetScaler
appliance supports all LSN logging features for logging DS-Lite information. For configuring DS-Lite logging, use the
procedures for configuring LSN logging, described at Logging and Monitoring LSN.
A log message for a DS-Lite LSN mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (MAPPING)
Whether the DS-Lite LSN mapping entry was created or deleted
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID might be present, depending on the following conditions:
Destination IP address and port are not logged for Endpoint-Independent mapping.
Only the destination IP address is logged for Address-Dependent mapping. T he port is not logged.
Destination IP address and port are logged for Address-Port-Dependent mapping.
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (SESSION)
Whether the DS-Lite session is created or removed
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID
T he following table shows sample DS-Lite log entries of each type stored on the configured log servers. T hese log entries
are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.You can log DS-Lite information to diagnose
or troubleshoot problems, and to meet legal requirements. T he NetScaler appliance supports all LSN logging features for
logging DS-Lite information. For configuring DS-Lite logging, use the procedures for configuring LSN logging, described at
Logging and Monitoring LSN.
A log message for a DS-Lite LSN mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (MAPPING)
Whether the DS-Lite LSN mapping entry was created or deleted
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (SESSION)
Whether the DS-Lite session is created or removed
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID
T he following table shows sample DS-Lite log entries of each type stored on the configured log servers. T hese log entries
are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.
You can display the current DS-Lite sessions for detecting any unwanted or inefficient sessions on the NetScaler appliance.
You can display all or some DS-Lite sessions, on the basis of selection parameters.
To display selected DS-Lite sessions by using the command line interf ace
show lsn session –nattype DS-Lite [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-td
<positive_integer>]] [-natIP <ip_addr> [-natPort <port>]]
Example COPY
The following sample ouput displays all DS-Lite sessions existing on a NetScaler appliance:
B4-Address SubscrIP SubscrPort SubscrTD DstIP DstPort DstTD NatIP NatPort Proto Dir
Done
1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. For displaying DS-Lite sessions on the basis of selection parameters, click Search.
You can remove any unwanted or inefficient DS-Lite sessions from the NetScaler appliance. T he appliance immediately
releases the resources (such as NAT IP address, port, and memory) allocated for these sessions, making the resources
available for new sessions. T he appliance also drops all the subsequent packets related to these removed sessions. You can
To clear all DS-Lite sessions by using the command line interf ace
To clear selected DS-Lite sessions by using the command line interf ace
f lush lsn session –nattype DS-Lite [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-
td <positive_integer>]] [-natIP <ip_addr> [-natPort <port>]]
show lsn session –nattype DS-Lite
1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. Click Flush Sessions.
Static DS-Lite LSN mappings are useful in cases where you want to ensure that the connections initiated to a NAT IP
address and port map to the subscriber IP address and port through the specified B4 device (for example, web servers
located in the internal network).
Note: T his feature is supported in release 11.0 build 64.x and later.
add lsn static <name> <transportprotocol> <subscrIP> <subscrPort> [-td <positive_integer>] [-network6 <B4_ADDR>]
[<natIP> [<natPort>]] [-destIP<ip_addr> [-dsttd <positive_integer>]]
show lsn static
Navigate to System > Large Scale NAT > Static, and add a new DS-Lite static LSN mapping.
Parameter Descriptions
name
Name for the LSN static mapping entry. Must begin with an ASCII alphanumeric or underscore (_) character, and must
contain only ASCII alphanumeric, underscore, hash (#), period (.), space, colon (:), at (@), equals (=), and hyphen (-) characters.
Cannot be changed after the LSN group is created. T he following requirement applies only to the NetScaler CLI: If the
name includes one or more spaces, enclose the name in double or single quotation marks (for example, "ds-lite lsn static1" or
'ds-lite lsn static1'). T his is a mandatory argument. Maximum Length: 127
transportprotocol
subscrIP
subscrPort
td
ID of the traffic domain to which the B4 device belongs. T he IPv6 address of the B4 device is specified in the network6
paramter. If you do not specify an ID, the B4 device is assumed to be a part of the default traffic domain.
natIP
IPv4 address, already existing on the NetScaler appliance as type LSN, to be used as NAT IP address for this mapping entry.
natPort
destIP
dsttd
ID of the traffic domain through which the destination IP address for this DS-Lite LSN mapping entry is reachable from the
NetScaler appliance. If you do not specify an ID, the destination IP address is assumed to be reachable through the default
traffic domain, which has an ID of 0.
Note: T his feature is supported in release 11.0 build 64.x and later.
T he appliance sequentially allocates NAT resources to these subscribers. It assigns the first block of ports on the beginning
NAT IP address to the beginning subscriber IP address. T he next range of ports is assigned to the next subscriber, and so on,
until the NAT address does not have enough ports for the next subscriber. At that point, the first port block on the next
NAT address is assigned to the subscriber, and so on.
T he NetScaler appliance logs the allocated NAT IP address and the port block for a subscriber. For a connection, a
subscriber can be identified by just its mapped NAT IP address and port block. For this reason, the NetScaler appliance does
not log the creation or deletion of an LSN session.
A DS-Lite subscriber can have only one deterministic port block. If the entire block of ports is being used, the NetScaler
appliance drops any new connection from the subscriber.
In this example, a deterministic DS-Lite configuration includes four subscribers with IP addresses 192.0.17.5, 192.0.17.6,
192.0.17.7, and 192.0.17.8. T hese ipv4 subscribers are behind a B4 device having the IPv6 address 2001:DB8::3:4. In this
configuration, the port block size is set to 20480 and LSN NAT IP address pool has IP addresses in the range 203.0.113.41-
203.0.113.42.
T he NetScaler appliance sequentially pre-allocates, from the LSN NAT IP pool and on the basis of the set port block size, an
LSN NAT IP address and a block of ports to each subscriber. It assigns the first block of ports (1024-21503) on the beginning
NAT IP address (203.0.113.41) to the beginning subscriber IP address (192.0.17.5). T he next range of ports is assigned to the
next subscriber, and so on, until the NAT address does not have enough ports for the next subscriber. At that point, the first
port block on the next NAT IP address is assigned to the subscriber, and so on. T he NetScaler logs the NAT IP address and
the block of ports allocated for each subscriber.
T he NetScaler appliance does not log any LSN session created or deleted for these subscribers.
T he following table lists the NAT IP address and blocks of ports allocated to each subscriber in this example:
Subscriber IP address Allocated NAT IP address Allocated Block of Ports IPv6 address of B4
Configuration Steps
You need to configure deterministic NAT as part of the DS-Lite configuration. For instructions on configuring DS-Lite, see
Configuring DS-Lite.
Set the NAT T ype parameter to Deterministic when adding the LSN pool and the LSN group.
Set the desired port block size parameter when adding the LSN group, unless you can accept the default value.
T he complete IP address of each subscriber must be specified in a separate add lsn client command, by setting the
Network and Netmask parameters. (Set Netmask to 255.255.255.255.) Also the IPv4 address of the B4 device specified
in Network6 parameter must be complete (/128 prefix). In other words, Network and Network6 parameter do not
accept addresses other than /32 bit mask and /128 prefix, respectively.
T he NetScaler appliance drops connections from subscribers that are not specified in any deterministic DS-Lite
configuration but are behind B4 devices specified in a deterministic DS-lite configuration.
T he NetScaler appliance recognizes subscribers having the same IPv4 address as different subscribers if they are behind
different B4 devices. A combination of subscriber IPv4 address and B4 device defines a unique subscriber in the LSN
client entity of a DS-Lite configuration.
The following configuration uses the settings listed in section Example: Deterministic DS-Lite.
Done
> bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.5 -netmask 255.255.255.255 -network6 2001:DB8::3:4/128
Done
> bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.6 -netmask 255.255.255.255 -network6 2001:DB8::3:4/128
Done
> bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.7 -netmask 255.255.255.255 -network6 2001:DB8::3:4/128
Done
> bind lsn client LSN-DSLITE-CLIENT-10 -network 192.0.17.8 -netmask 255.255.255.255 -network6 2001:DB8::3:4/128
Done
Done
Done
Done
> add lsn group LSN-DSLITE-GROUP-10 -clientname LSN-DSLITE-CLIENT-10 -nattype DETERMINISTIC -portblocksize 20480 -ip6profile LSN-D
Done
Done
T he NetScaler appliance supports ALG for the following protocols for DS-Lite:
FT P
ICMP
T FT P
SIP
RT SP
ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.
ALG for the T FT P protocol is disabled by default. T FT P ALG is enabled automatically for a DS-Lite configuration when you
bind a UDP LSN application profile, with endpoint-independent-mapping, endpoint-independent filtering, and destination
port as 69 (well-known port for T FT P), to the LSN group.
You need to configure the SIP ALG as part of the LSN configuration. For instructions on configuring LSN, see Configuring
DS-Lite. While configuring LSN, make sure that you:
o IP Pooling = PAIRED
Create a SIP ALG profile and make sure that you define either the source port range or destination port range. Bind the
SIP ALG profile to the LSN group
Enable SIP ALG in the LSN group
To enable SIP ALG f or an LSN configuration by using the NetScaler command line
To enable SIP ALG f or an LSN configuration by using the NetScaler command line
Sample Configuration
T he following sample DS-Lite configuration, SIP ALG is enabled for TCP traffic from B4 devices in the network
2001:DB8::3:0/96.
Done
Done
Done
Done
Done
> add lsn appsprofile LSN-DSLITE-APPS-PROFILE-1 TCP -ippooling PAIRED –mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEP
Done
Done
> add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1 -sipalg ENA
Done
Done
Done
Done
Streaming media from a private network to a public network requires translating IP addresses and port numbers over the
network. NetScaler functionality includes an Application Layer Gateway (ALG) for RT SP, which can be used with Large Scale
NAT (LSN) to parse the media stream and make any necessary changes to ensure that the protocol continues to work over
the network.
How IP address translation is performed depends on the type and direction of the message, and the type of media
supported by the client-server deployment. Messages are translated as follows:
Outbound request— Private IP address to NetScaler-owned public IP address called LSN IP address.
Inbound response— LSN IP address to private IP address.
Inbound request— No translation.
Outbound response— Private IP address to LSN pool IP address.
Multicast RT SP sessions
RT SP session over UDP
Admin partitions
NetScaler clusters
RT SP Authentication
HT T P tunneling
Configure RT SP ALG as part of the LSN configuration. For instructions on configuring LSN, see Configuring DS-Lite. While
configuring LSN, make sure that you:
To enable RTSP ALG f or an LSN configuration by using the NetScaler command line
To enable RTSP ALG f or an LSN configuration by using the NetScaler command line
Done
Done
Done
Done
Done
> add lsn appsprofile LSN-DSLITE-APPS-PROFILE-5 TCP -ippooling PAIRED –mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEP
Done
> add lsn group LSN-DSLITE-GROUP-5 -clientname LSN-DSLITE-CLIENT-5 -portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-5 -rtspalg EN
Done
Done
Done
Done
A log message for a DS-Lite LSN mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (MAPPING)
Whether the DS-Lite LSN mapping entry was created or deleted
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID might be present, depending on the following conditions:
Destination IP address and port are not logged for Endpoint-Independent mapping.
Only the destination IP address is logged for Address-Dependent mapping. T he port is not logged.
Destination IP address and port are logged for Address-Port-Dependent mapping.
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (SESSION)
Whether the DS-Lite session is created or removed
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID
T he following table shows sample DS-Lite log entries of each type stored on the configured log servers. T hese log entries
are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.You can log DS-Lite information to diagnose
or troubleshoot problems, and to meet legal requirements. T he NetScaler appliance supports all LSN logging features for
logging DS-Lite information. For configuring DS-Lite logging, use the procedures for configuring LSN logging, described at
Logging and Monitoring LSN.
A log message for a DS-Lite LSN mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (MAPPING)
Whether the DS-Lite LSN mapping entry was created or deleted
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (SESSION)
Whether the DS-Lite session is created or removed
IPv6 address of B4
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID
T he following table shows sample DS-Lite log entries of each type stored on the configured log servers. T hese log entries
are generated by a NetScaler appliance whose NSIP address is 10.102.37.115.
You can display the current DS-Lite sessions for detecting any unwanted or inefficient sessions on the NetScaler appliance.
To display selected DS-Lite sessions by using the command line interf ace
show lsn session –nattype DS-Lite [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-td
<positive_integer>]] [-natIP <ip_addr> [-natPort <port>]]
Example COPY
The following sample ouput displays all DS-Lite sessions existing on a NetScaler appliance:
B4-Address SubscrIP SubscrPort SubscrTD DstIP DstPort DstTD NatIP NatPort Proto Dir
Done
1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. For displaying DS-Lite sessions on the basis of selection parameters, click Search.
You can remove any unwanted or inefficient DS-Lite sessions from the NetScaler appliance. T he appliance immediately
releases the resources (such as NAT IP address, port, and memory) allocated for these sessions, making the resources
To clear all DS-Lite sessions by using the command line interf ace
To clear selected DS-Lite sessions by using the command line interf ace
f lush lsn session –nattype DS-Lite [-clientname <string>] [-network <ip_addr> [-netmask <netmask>] [-
td <positive_integer>]] [-natIP <ip_addr> [-natPort <port>]]
show lsn session –nattype DS-Lite
1. Navigate to System > Large Scale NAT > Sessions, and click the DS-Lite tab.
2. Click Flush Sessions.
T he NetScaler appliance can log request header information of an HT T P connection that is using the DS-Lite functionality.
T he following header information of an HT T P request packet can be logged:
T he HT T P header logs can be used by ISPs to see the trends related to the HT T P protocol among a set of subscribers. For
example, an ISP can use this feature to find out the most popular website among a set of subscribers.
Configuration Steps
Perform the following tasks for configuring the NetScaler appliance to log HT T P header information:
Create an HTTP header log prof ile. An HT T P header log profile is a collection of HT T P header attributes (for example,
URL and HT T P method) that can be enabled or disabled for logging.
Bind the HTTP header to an LSN group of a DS-Lite LSN conf iguration. Bind the HT T P header log profile to an LSN
group of an LSN configuration by setting the HT T P header log profile name parameter to the name of the created
HT T P header log profile. T he NetScaler appliance then logs HT T P header information of any HT T P requests related to
the LSN group. An HT T P header log profile can be bound to multiple LSN groups, but an LSN group can have only one
HT T P header log profile.
To create an HTTP header log profile by using the command line interf ace
To bind an HTTP header log profile to an LSN group by using the command line interf ace
Sample Configuration
In the following DS-Lite LSN configuration, HT T P header log profile HT T P-Header-LOG-1 is bound to LSN group LSN-
DSLIT E-GROUP-1. T he log profile has all the HT T P attributes (URL, HT T P method, HT T P version, and HOST IP address)
enabled for logging, so that all these attributes are logged for any HT T P requests from B4 devices (in the network
2001:DB8:5001::/96).
Done
Done
Done
Done
Done
Done
> add lsn group LSN-DSLITE-GROUP-1 -clientname LSN-DSLITE-CLIENT-1 -portblocksize 1024 -ip6profile LSN-DSLITE-PROFILE-1
Done
Done
Done
IPFIX Logging
IPFIX based logging is available for the following DS_Lite related events:
You must configure the AppFlow feature and IPFIX collector(s) on the NetScaler appliance. For instructions, see
Configuring the AppFlow feature.
Configuration Steps
Perform the following tasks for logging LSN information in IPFIX format:
Enable LSN logging in the AppFlow conf iguration. Enable the LSN logging parameter as part of AppFlow
configuration.
Create an LSN log prof ile. An LSN log profile includes the IPFIX parameter that enables or disables the log information
in IPFIX format.
Bind the LSN log prof ile to an LSN group of an LSN conf iguration. Bind the LSN log profile to one or multiple LSN
group(s). Events related to the bound LSN group will be logged in IPFIX format.
To enable LSN logging in the AppFlow configuration by using the NetScaler command line
To create an LSN log profile by using the NetScaler command lineAt the command prompt , type:
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler GUI
1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Prof ile to bind the created Log profile to the LSN group.
Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself and/or for other 3rd party
devices. T he large scale NAT device creates an LSN map and sends it to the subscriber. T he subscriber sends the remote
devices on the Internet the NAT IP address:NAT port at which they can connect to the subscriber.
Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN mappings do not
time out. PCP helps reduce the frequency of such keep-alive messages by enabling the applications to learn the timeout
settings of the LSN mappings. T his helps reduce bandwidth consumption on the ISP’s access network and battery
consumption on mobile devices.
PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance implements the PCP server
component and is compliant with RFC 6887.
Configuration Steps
(Optional) Create a PCP profile. A PCP profile includes settings for PCP related parameters (for example, to listen for
mapping and peer PCP requests). A PCP profile can be bound to a PCP server. A PCP profile bound to a PCP server applies
all its settings to the PCP server. A PCP profile can be bound to multiple PCP servers. By default, one PCP profile with
default parameters settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the default
PCP profile settings for that server. A default PCP profile has the following parameter settings:
Mapping: Enabled
Peer: Enabled
Minimum map life: 120 seconds
Maximum max life: 86400 seconds
Announce count: 10
T hird Party: Disabled
Create a PCP server and bind a PCP profile to it. Create a PCP server on the NetScaler appliance to listen for PCP related
requests and messages from the subscribers. A Subnet IP (SNIP) address must be assigned to a PCP server to access it.
By default, a PCP server listens on port 5351.
Bind the PCP server to an LSN group of an LSN configuration. Bind the created PCP server to an LSN group of an LSN
configuration by setting the PCP Server parameter to specify the created PCP server. T he created PCP server can be
accessed only by the subscribers of this LSN group.
Note: A PCP server for a large scale NAT configuration does not serve requests from subscribers that are identified from
ACL rules.
add pcp prof ile <name> [-mapping ( ENABLED | DISABLED )] [-peer ( ENABLED | DISABLED )] [-minMapLif e <secs>] [-
maxMapLif e <secs>] [-announceMultiCount <positive_integer>][-thirdParty ( ENABLED | DISABLED )]
show pcp profile <name>
add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProf ile <string>]
show pcp server <name>
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
A NetScaler appliance implements large scale NAT 64 and DNS64 and is compliant with RFCs 6145, 6146, 6147, 6052, 3022,
2373, 2765, and 2464.
Architecture
T he NAT 64 architecture of an ISP using a NetScaler appliance consists of IPv6 subscribers accessing the IPv4 Internet
through a NetScaler appliance deployed in the ISP’s core network. IPv6 subscribers are connected to the ISP core network
through the ISP’s IPv6-only access network.
T he large scale NAT 64 functionality of a NetScaler appliance enables communication between IPv6 clients and IPv4 servers
through IPv6-to-IPv4 packet translation, and vice versa, while maintaining session information on the NetScaler
appliance. NetScaler DNS64 functionality represents IPv4-only domains to IPv6-subscribers by synthesizing DNS AAAA
records for IPv4-only domains and sending them to the subscribers.
Large scale NAT 64 has two main components: NAT 64 prefix and NAT IPv4 pool. DNS64 has one main component, DNS64
prefix, which has the same value as NAT 64 prefix.
Upon receiving an AAAA request from an IPv6-only subscriber for a domain name that is hosted on an IPv4-only web server
on the Internet, the NetScaler DNS64 functionality synthesizes an AAAA record for the domain name and sends it to
the subscriber. T he AAAA record is synthesized by concatenating the DNS64 prefix (which is set to the NAT 64 prefix) and
the actual IPv4 address of the domain name.
T he subscriber now has an IPv6 destination address that corresponds to the desired domain name. T he subscriber sends
the request to the synthesized IPv6 address. Upon receiving the IPv6 request, the large scale NetScaler NAT 64 functionality
translates the IPv6 request packet to an IPv4 request packet. Large scale NAT 64 sets the IPv4 request’s destination
address to the IPv4 address, which is extracted from the IPv6 request’s destination address by stripping the NAT 64 prefix
from the IPv6 address. T he destination port is retained from the IPv6 request. Large Scale NAT 64 also sets the source IP
T he appliance maintains a record of all active sessions that use the large scale NAT 64 functionality. T hese sessions are
called large scale NAT 64 sessions. T he appliance also maintains the mappings between subscriber IPv6 address and port,
and NAT IPv4 address and port, for each large scale NAT 64 session. T hese mappings are called large scale NAT 64
mappings. From large scale NAT 64 session entries and large scale NAT 64 mapping entries, the NetScaler appliance
recognizes a response packet (received from the Internet) as belonging to a particular NAT 64 session.
When the appliance receives an IPv4 response packet belonging to a particular NAT 64 session, it uses the information
stored in the NAT 64 session to translate the IPv4 packet into an IPv6 packet, and then sends the IPv6 response packet to
the subscriber.
Consider an example of a large scale NAT 64 and DNS64 deployment consisting of NetScaler appliance NS-1 and two local
DNS servers, DNS-1 and DNS-2, in an ISP’s core network, and IPv6 subscriber SUB-1. SUB-1 is connected to NS-1 through
the ISP’s IPv6 access network. NS-1 includes large scale NAT 64 and DNS64 configurations for enabling the communication
between IPv6 subscriber SUB-1 and IPv4 hosts (internal and external).
Large scale NAT 64 configuration includes a NAT 64 prefix (2001:DB8:300::/96) and NAT IPv4 pool for translation of IPv6
requests to IPv4 requests and IPv4 responses to IPv6 responses.
DNS64 configuration includes a DNS load balancing virtual server LBVS-DNS64-1 (2001:DB8:9999::99) and a DNS64 prefix
(2001:DB8:300::/96). LBVS-DNS64-1 represents local DNS server DNS-1 and DNS-2 to ISP's subscribers. T he DNS64 prefix,
which has the same value as the NAT 64 prefix, is used for synthesizing DNS AAAA records from DNS A records received
from DNS servers DNS-1 and DNS-2. NS-1 responds with a synthesized AAAA record to SUB-1 for a DNS request to resolve
an IPv4 host.
1. IPv6 subscriber SUB-1 sends a DNS AAAA request for www.example.com to its designated DNS server
(2001:DB8:9999::99).
2. DNS load balancing virtual server LBVS-DNS64-1 (2001:DB8:9999::99) on NetScaler appliance NS1 receives the AAAA
request. LBVS-DNS64-1's load balancing algorithm selects DNS server DNS-1 and forwards the AAAA request to it.
3. DNS-1 returns an empty record or an error message, because there is no AAAA record available for www.example.com.
4. Because the DNS64 option is enabled on LBVS-DNS64-1 and the AAAA request from CL1 matches the condition
2.IPv6 subscriber SUB-1 sends a request to 2001:DB8:5001:30 (www.example.com). T he IPv6 packet has:
3. When NS-1 receives the IPv6 packet, the large scale NAT 64 module creates a translated IPv4 request packet with:
Source IP address = One of the IPv4 addresses available in the configured NAT pool (203.0.113.61)
Source port = One of ports available with the allocated NAT IPv4 address (3002)
Destination IP address = IPv4 address extracted from the IPv6 request’s destination address by stripping the NAT 64
prefix (2001:DB8:300::/96) from the IPv6 address (192.0.2.60)
Destination port = IPv6 request’s destination port (80)
4. T he large scale NAT 64 module also creates mapping and session entries for this large scale NAT 64 flow. T he session
and mapping entries include the following information:
5. Upon receiving the request packet, the server for www.example.com processes the packet and sends a response
packet to NS-1. T he IPv4 response packet has:
6. Upon receiving the IPv4 response packet, NS-1 examines the large scale NAT 64 mapping and session entries and finds
Large scale NAT 64 on a NetScaler appliance supports the standard LSN feature set. For more information on these LSN
features, see http://docs.citrix.com/en-us/netscaler/11/solutions/netscaler-support-for-telecom-service-providers/lsn-
introduction.html.
Following are some of the large scale NAT 64 features supported on NetScaler appliances:
ALGs. Support of application Layer Gateway (ALG) for SIP, RT SP, FT P, ICMP, and T FT P protocols.
Deterministic/Fixed NAT . Support for pre-allocation of blocks of ports to subscribers to minimize logging.
Mapping. Support of Endpoint-independent mapping (EIM), Address-dependent mapping (ADM), and Address-Port
dependent mapping (APDM).
Filtering. Support of Endpoint-Independent Filtering (EIF), Address-Dependent Filtering (ADF), and Address-Port-
Dependent Filtering (APDF).
Quotas. Configurable limits on number of ports, sessions per subscriber, and sessions per LSN group.
Static Mapping. Support for manually defining a large scale NAT 64 mapping.
Hairpin Flow. Support for communication between subscribers or internal hosts using NAT IP addresses.
464XLAT connections. Support for communication between IPv4-only applications on IPv6 subscriber hosts and IPv4
hosts on the Internet through IPv6 network.
Variable length NAT 64 and DNS64 prefixes. T he NetScaler appliance supports defining NAT 64 and DNS64 prefixes
of lengths of 32, 40, 48, 56, 64, and 96.
Multiple NAT 64 and DNS64 prefix. T he NetScaler appliance supports multiple NAT 64 and DNS64 prefixes.
LSN Clients. Support for specifying or identifying subscribers for large scale NAT 64 by using IPv6 prefixes and extended
ACL6 rules.
Logging. Support for logging NAT 64 sessions for law enforcement. In addition, the following are also supported for
logging.
Reliable SYSLOG. Support for sending SYSLOG messages over T CP to external log servers for a more reliable transport
mechanism.
Load balancing of log servers. Support for load balancing of external log servers for preventing storage of
redundant log messages.
Minimal Logging. Deterministic LSN configurations or Dynamic LSN configurations with port block significantly
reduce the large scale NAT 64 log volume.
Logging MSISDN inf ormation. Support for including subscribers' MSISDN information in large scale NAT 64 logs to
identify and track subscriber activity over the Internet.
1. Make sure you understand the different components of large scale NAT 64, described in RFCs.
2. T he NetScaler appliance supports only the following ALGs for large Scale NAT 64:
FT P
T FT P
ICMP
SIP
RT SP
3. In a high availability setup of two NetScaler appliances, large NAT 64 session synchronization (connection mirroring) is not
supported.
Add DNS services. DNS services are logical representations of DNS servers for which the NetScaler appliance acts as a
DNS proxy server. For more information on setting optional parameters of a service, see "Load Balancing".
Add DNS64 action and DNS64 policy and then bind the DNS64 action to the DNS64 policy. A DNS64 policy specifies
conditions to be matched against traffic for DNS64 processing according to the settings in the associated DNS64
action. T he DNS64 action specifies the mandatory DNS64 prefix and the optional exclude-rule and mapped-rule
settings.
Create a DNS load balancing virtual server and bind the DNS services and the DNS64 policy to it. T he DNS load balancing
virtual server acts as a DNS proxy server for DNS servers represented by the bound DNS services. T raffic arriving at the
virtual server is matched against the bound DNS64 policy for DNS64 processing. For more information on setting
optional parameters of a load balancing virtual server, see "Load Balancing".
Note
T he command line interface has separate commands for these two tasks, but the NetScaler GUI combines them in a single dialog
box.
Enable caching of DNS records. Enable the global parameter for the NetScaler appliance to cache DNS records, which
are obtained through DNS proxy operations. For more information on enabling caching of DNS records, see "Enabling
Caching of DNS Records".
To create a service of type DNS by using the command line interf ace
add dns action64 <actionName> -Prefix <ipv6_addr|*> [-mappedRule <expression>] [-excludeRule <expression>]
To create a DNS load balancing virtual server by using the command line interf ace
add lb vserver <name> DNS <IPAddress> <port> -dns64 (ENABLED | DISABLED) [-bypassAAAA ( YES | NO)] …
Done
Done
Done
Done
Done
Done
Done
Done
Set the global LSN parameters. Global parameters include the amount of NetScaler memory reserved for the LSN
feature and synchronization of LSN sessions in a high availability setup.
Create an LSN client entity for identifying traffic from IPv6 subscribers. T he LSN client entity refers to a set of IPv6
subscribers. T he client entity includes IPv6 addresses or IPv6 network prefixes, or ACL6 rules, for identifying the traffic
from these subscribers. An LSN client can be bound to only one LSN group. T he command line interface has two
commands for creating an LSN client entity and binding a subscriber to the LSN client entity. T he NetScaler GUI
combines these two operations on a single screen.
Create an LSN pool and bind NAT IP addresses to it. An LSN pool defines a pool of NAT IP addresses to be used by the
NetScaler appliance to perform large scale NAT 64. T he command line interface has two commands for creating an LSN
pool and binding NAT IP addresses to the LSN pool. T he GUI combines these two operations on a single screen.
Create an LSN IP6 profile. An LSN IP6 profile defines the NAT 64 prefix for a large scale NAT 64 configuration.
(Optional) Create an LSN T ransport Profile for a specified protocol. An LSN transport profile defines various timeouts
and limits, such as maximum large scale NAT 64 sessions and maximum ports usage that a subscriber can have for a given
protocol. You bind an LSN transport profile for each protocol (T CP, UDP, and ICMP) to an LSN group. A profile can be
bound to multiple LSN groups. A profile bound to an LSN group applies to all subscribers of an LSN client bound to the
same group. By default, one LSN transport profile with default settings for T CP, UDP, and ICMP protocols is bound to an
LSN group during its creation. T his profile is called the default transport profile. An LSN transport profile that you bind to
an LSN group overrides the default LSN transport profile for that protocol.
(Optional) Create an LSN Application Profile for a specified protocol and bind a set of destination ports to it. An LSN
application profile defines the LSN mapping and LSN filtering controls of a group for a given protocol and for a set of
destination ports. For a set of destination ports, you bind an LSN profile for each protocol (T CP, UDP, and ICMP) to an
LSN group. A profile can be bound to multiple LSN groups. An LSN application profile bound to an LSN group applies to all
subscribers of an LSN client bound to the same group. By default, one LSN application profile with default settings for
T CP, UDP, and ICMP protocols for all destination ports is bound to an LSN group during its creation. T his profile is called
a default application profile. When you bind an LSN application profile, with a specified set of destination ports, to an
LSN group, the bound profile overrides the default LSN application profile for that protocol at that set of destination
ports. T he command line interface has two commands for creating an LSN application profile and binding a set of
destination ports to the LSN application profile. T he GUI combines these two operations on a single screen.
Create an LSN Group and bind LSN pools, LSN IPv6 profile, (optional) LSN transport profiles, and (optional) LSN
application profiles to the LSN group. An LSN group is an entity consisting of an LSN client, an LSN IPv6 profile, LSN
pool(s), LSN transport profile(s), and LSN application profiles(s). A group is assigned parameters, such as port block size
and logging of LSN sessions. T he parameter settings apply to all the subscribers of an LSN client bound to the LSN
group. Only one LSN IPv6 profile can be bound to an LSN group, and an LSN IPv6 profile bound to an LSN group cannot
be bound to other LSN groups. Only LSN Pools and LSN groups with the same NAT type settings can be bound
together. Multiples LSN pools can be bound to an LSN group. Only one LSN client entity can be bound to an LSN group,
and an LSN client entity bound to an LSN group cannot be bound to other LSN groups. T he command line interface has
two commands for creating an LSN group and binding LSN pools, LSN transport profiles, and LSN application profiles to
You can create different configurations using the command line interface. Follow the steps given below.
To bind an IPv6 network or an ACL6 rule to an LSN client by using the command line interf ace
To bind NAT IP addresses to an LSN pool by using the command line interf ace
Note
For removing NAT IP (LSN IP addresses) addresses from an LSN pool, use the unbind lsn pool command.
To configure an LSN IPv6 profile by using the command line interf ace
To create an LSN transport profile by using the command line interf ace
add lsn transportprof ile <transportprofilename> <transportprotocol> [-sessiontimeout <secs>] [-finrsttimeout <secs>]
To create an LSN application profile by using the command line interf ace
add lsn appsprof ile <appsprofilename> <transportprotocol> [-ippooling (PAIRED | RANDOM )] [-mapping <mapping>] [-
filtering <filtering>][-tcpproxy ( ENABLED | DISABLED )]
show lsn appsprof ile
To bind an application protocol port range to an LSN application profile by using the command line interf ace
add lsn group <groupname> -clientname <string> [-nattype ( DYNAMIC | DET ERMINIST IC )] [-
portblocksize <positive_integer>] [-logging(ENABLED | DISABLED )] [-sessionLogging ( ENABLED | DISABLED )][-
sessionSync ( ENABLED | DISABLED )] [-snmptraplimit<positive_integer>] [-ftp ( ENABLED | DISABLED )] [-sipalg (
ENABLED | DISABLED )] [-rtspalg ( ENABLED |DISABLED )] [-ip6profile <string>]
show lsn group
To bind LSN protocol profiles and LSN pools to an LSN group by using the command line interf ace
bind lsn group <groupname> (-poolname <string> | -transportprofilename <string> | -httphdrlogprofilename <string> |
-appsprofilename <string> | -sipalgprofilename <string> | rtspalgprofilename <string>)
show lsn group
Done
Done
Done
Done
Done
Done
Done
Done
>apply acl6s
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
> add lsn group LSN-NAT64-GROUP-7 -clientname LSN-NAT64-CLIENT-7 -ip6profile LSN-NAT64-PROFILE-7 -nattype DETERMINISTIC -portbl
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
T he NetScaler appliance supports ALG for the following protocols for large scale NAT 64:
FT P
ICMP
T FT P
SIP
RT SP
ALG for the ICMP protocol is enabled by default, and there is no provision to disable it.
ALG for the T FT P protocol is disabled by default. T FT P ALG is enabled automatically for an large scale NAT 64 configuration
when you bind a UDP LSN application profile, with endpoint-independent-mapping, endpoint-independent filtering, and
destination port as 69 (well-known port for T FT P), to the LSN group.
SIP ALG for large scale NAT 64 has the following limitations:
You need to configure the SIP ALG as part of the LSN configuration. For instructions on configuring LSN, see Configuration
Large Scale NAT 64. While configuring LSN, make sure that you:
To enable SIP ALG f or an LSN configuration by using the NetScaler command line
To enable SIP ALG f or an LSN configuration by using the NetScaler command line
Sample Configuration
T he following sample large scale NAT 64 configuration, SIP ALG is enabled for TCP traffic from subscriber devices in the
network 2001:DB8:1003::/96.
Done
Done
Done
Done
Done
> add lsn appsprofile LSN-NAT64-APPS-PROFILE-9 TCP -ippooling PAIRED –mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPE
Done
Done
> add lsn group LSN-NAT64-GROUP-9 -clientnameLSN-NAT64-CLIENT-9 -ip6profile LSN-NAT64-PROFILE-7 -sipalg ENABLED
Done
Done
Done
Done
Streaming media from a private network to a public network requires translating IP addresses and port numbers over the
network. NetScaler functionality includes an Application Layer Gateway (ALG) for RT SP, which can be used with Large Scale
NAT (LSN) to parse the media stream and make any necessary changes to ensure that the protocol continues to work over
the network.
How IP address translation is performed depends on the type and direction of the message, and the type of media
supported by the client-server deployment. Messages are translated as follows:
Outbound request— Private IP address to NetScaler-owned public IP address called LSN IP address.
Inbound response— LSN IP address to private IP address.
Inbound request— No translation.
Outbound response— Private IP address to LSN pool IP address.
Multicast RT SP sessions
RT SP session over UDP
Admin partitions
NetScaler clusters
RT SP Authentication
HT T P tunneling
Configure RT SP ALG as part of the LSN configuration. For instructions on configuring LSN, see Configuring Large Scale
NAT 64. While configuring, make sure that you:
To enable RTSP ALG f or an LSN configuration by using the NetScaler command line
Done
Done
Done
Done
Done
> add lsn appsprofile LSN-NAT64-APPS-PROFILE-9 TCP -ippooling PAIRED –mapping ENDPOINT-INDEPENDENT -filtering ENDPOINT-INDEPE
Done
Done
Done
Done
Done
Done
Static Large Scale NAT 64 mappings are useful in cases where you want to ensure that the IPv4 connections initiated to a
NAT IP address:port are IPv6 translated and mapped to the subscriber IP address:port (for example, web servers located in
the internal network).
add lsn static <name> <transportprotocol> <subscrIP> <subscrPort> [<natIP> [<natPort>]] [-destIP <ip_addr> [-
dsttd <positive_integer>]]
show lsn static
A static large scale NAT 64 mapping entry is usually a one-to-one mapping between a subscriber IPv6 address:port and a
NAT IPv4 address:port. A one-to-one static large scale NAT 64 mapping entry exposes only one port of the subscriber IP
address to the Internet.
Some situations might require exposing all ports (64K - limited to the maximum number of ports of a NAT IPv4 address) of a
subscriber IP address to the Internet (for example, a server hosted on an internal network and running a different service on
each port). To make these internal services accessible through the Internet, you have to expose all the ports of the server
to the Internet.
One way to meet this requirement is to add 64 thousand one-to-one static mapping entries, one mapping entry for each
port. Creating those entries is very cumbersome and a big task. Also, this large number of configuration entries might lead
to performance issues in the NetScaler appliance.
A simpler method is to use wildcard ports in a static mapping entry. You just need to create one static mapping entry with
NAT -port and subscriber-port parameters set to the wildcard character (*), and the protocol parameter set to ALL, to
expose all the ports of a subscriber IP address for all protocols to the Internet.
For a subscriber's inbound or outbound connections matching a wildcard static mapping entry, the subscriber's port does
not change after the NAT operation. When a subscriber-initiated connection to the Internet matches a wildcard static
mapping entry, the NetScaler appliance assigns a NAT port that has the same number as the subscriber port from which the
connection is initiated. Similarly, an Internet host gets connected to a subscriber's port by connecting to the NAT port that
has the same number as the subscriber's port.
To configure the NetScaler appliance to provide access to all ports of a subscriber IPv6 address, create a wildcard static
map with the following mandatory parameter settings:
Protocol=ALL
In a wildcard static map, unlike in a one-to-one static map, setting the NAT IP parameter is mandatory. Also, the NAT IP
address assigned to a wildcard static map cannot be used for any other subscribers.
add lsn static <name> ALL <subscrIP> * <natIP> * [-td <positive_integer>] [-destIP <ip_addr>
show lsn static
In the following sample configuration of a wildcard static map, all ports of a subscriber whose IP address is
2001:DB8:5001::3 are made accessible through NAT IP 203.0.11.33.
Done
A log message for a large scale NAT 64 mapping entry consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced.
T ime stamp.
Entry type (MAPPING).
Whether the mapping entry was created or deleted.
Subscriber's IP address, port, and traffic domain ID.
NAT IP address and port.
Protocol name.
Destination IP address, port, and traffic domain ID might be present, depending on the following conditions:
Destination IP address and port are not logged for endpoint-independent mapping.
Only the destination IP address is logged for address-dependent mapping. T he port is not logged.
Destination IP address and port are logged for address-port-dependent mapping.
A log message for a large scale NAT 64 session consists of the following information:
NetScaler owned IP address (NSIP address or SNIP address) from which the log message is sourced
T ime stamp
Entry type (SESSION)
Whether the session is created or removed
Subscriber's IP address, port, and traffic domain ID
NAT IP address and port
Protocol name
Destination IP address, port, and traffic domain ID
T he following table displays sample large scale NAT 64 log entries of each type stored on the configured log servers. T he log
entries show that a subscriber whose IPv6 address is 2001:db8:5001::9 was connected to destination IP:port 23.0.0.1:80
through NAT IP:port 203.0.113.63:45195 on April 7, 2016, from 14:07:57 GMT to 14:10:59 GMT.
Log
Entry Sample Log Entry
Type
Session 04/07/2016:14:10:59 GMT 0-PPE-10 : default LSN LSN_SESSION 25012 0 : SESSION DELET ED Client IP-Port:T D
Deletion 2001:db8:5001::9-34 937:0, NatIP:NatPort 203.0.113.63:45195, Destination IP:Port:T D 23.0.0.1:0:80, Protocol: TCP
Mapping 04/07/2016:14:10:59 GMT 0-PPE-10 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM DELET ED Client IP-Port:T D
Deletion 2001:db8:5001::9-34 937:0, NatIP:NatPort 203.0.113.63:45195, Destination IP:Port:T D 23.0.0.1:0:80, Protocol: TCP
Configuration Steps
You can configure logging of large scale NAT 64 information for a large scale NAT 64 configuration by setting the LSN
groups’s logging and session logging parameters. T hese are group level parameters and are disabled by default. T he
NetScaler appliance logs large scale NAT 64 sessions for an LSN group only when both logging and session logging
parameters are enabled.
T he following table displays the logging behavior for an LSN group for various settings of logging and session logging
parameters.
Enabled Disabled Logs LSN mapping entries but not LSN sessions
To log large scale NAT64 inf ormation by using the NetScaler command line
To set the logging and session logging parameters while adding an LSN group, at the command prompt, type:
To set the logging and session logging parameters for an existing LSN group, at the command prompt, type:
Sample Configuration
In this example of large scale NAT 64 configuration, logging and session logging paramters are enabled for LSN group LSN-
NAT 64-GROUP-1.
T he NetScaler appliance logs large scale NAT 64 session and mapping information for connections from subscribers (in the
network 2001:DB8:5001::/96).
Done
Done
Done
Done
Done
> add lsn group LSN-NAT64-GROUP-1 -clientname LSN-NAT64-CLIENT-1 -ip6profile LSN-NAT64-PROFILE-1 -logging ENABLED -sessionLogg
Done
Done
A Mobile Station Integrated Subscriber Directory Number (MSISDN) is a telephone number uniquely identifying a subscriber
across multiple mobile networks. T he MSISDN is associated with a country code and a national destination code identifying
the subscriber's operator.
You can configure a NetScaler appliance to include MSISDNs in large scale NAT 64 LSN log entries for subscribers in mobile
networks. T he presence of MSISDNs in the LSN logs facilitates faster and accurate back tracing of a mobile subscriber who
T he following sample LSN log entries include MSISDN information for a connection from a mobile subscriber in an LSN
configuration. T he log entries show that a mobile subscriber whose MSISDN is E164:5556543210 and IPv6 address is
2001:db8:5001::9 was connected to destination IP:port 23.0.0.1:80 through the NAT IP:port 203.0.113.63:45195 on April 7,
2016, from 14:07:57 GMT to 14:10:59 GMT.
Log
Entry Sample Log Entry
Type
Session 04/07/2016:14:10:59 GMT 0-PPE-10 : default LSN LSN_SESSION 25012 0 : SESSION DELET ED E164 :555654 3210 Client IP-
Deletion Port:T D 2001:db8:5001::9-34 937:0, NatIP:NatPort 203.0.113.63:45195, Destination IP:Port:T D 23.0.0.1:0:80, Protocol: TCP
04/07/2016:14:10:59 GMT 0-PPE-10 : default LSN LSN_ADDR_MAPPING 25013 0 : ADM DELET ED E164 :555654 3210 Client
Mapping
IP-Port:T D 2001:db8:5001::9-34 937:0, NatIP:NatPort 203.0.113.63:45195, Destination IP:Port:T D 23.0.0.1:0:80, Protocol:
Deletion
TCP
Configuration Steps
Perform the following tasks for including MSISDN information in LSN logs:
Create an LSN log prof ile. An LSN log profile includes the log subscriber ID parameter, which specifies whether to or
not to include the MSISDN information in the LSN logs of an LSN configuration.
Bind the LSN log profile to an LSN group of an LSN configuration.Bind the created LSN log profile to an LSN group of an
LSN configuration by setting the log profile name parameter to the created LSN log profile name. MSISDN information
is included in all LSN logs related to mobile subscribers of this LSN group.
To bind an LSN log profile to an LSN group of an NAT64 LSN configuration by using the NetScaler command line
At the command prompt, type:
Sample Configuration
Done
Done
Done
Done
Done
Done
Done
Done
Done
Compact logging is a technique for reducing the log size by using a notational change involving short codes for event and
protocol names. For example, C for client, SC for session created, and T for TCP. Compact logging results in an average of
40 percent reduction in log size.
Configuration Steps
Perform the following tasks for logging LSN information in compact format:
1. Create an LSN log profile. An LSN log profile includes the Log Compact parameter, which specifies whether to or not to
log information in compact format for an LSN configuration.
2. Bind the LSN log profile to an LSN group of an LSN configuration. Bind the created LSN log profile to an LSN group of
an LSN configuration by setting the Log Profile Name parameter to the created LSN log profile name. All sessions and
mappings for this LSN group are logged in compact format.
To bind an LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
Done
Done
Done
Done
Done
Done
Done
Done
Done
T he HT T P header logs can be used by ISPs to see the trends related to the HT T P protocol among a set of subscribers. For
example, an ISP can use this feature to find out the most popular website among a set of subscribers.
Configuration Steps
Perform the following tasks for configuring the NetScaler appliance to log HT T P header information:
Create an HT T P header log profile. An HT T P header log profile is a collection of HT T P header attributes (for example,
URL and HT T P method) that can be enabled or disabled for logging.
Bind the HT T P header to an LSN group of a large scale NAT 64 configuration. Bind the HT T P header log profile to an
LSN group of an LSN configuration by setting the HT T P header log profile name parameter to the name of the created
HT T P header log profile. T he NetScaler appliance then logs HT T P header information of any HT T P requests related to
the LSN group. An HT T P header log profile can be bound to multiple LSN groups, but an LSN group can have only one
HT T P header log profile.
To create an HTTP header log profile by using the the command line interf ace
add lsn httphdrlogprof ile <httphdrlogprofilename> [-logURL ( ENABLED | DISABLED )] [-logMethod ( ENABLED |
DISABLED )] [-logVersion ( ENABLED | DISABLED )] [-logHost ( ENABLED | DISABLED )]
show lsn httphdrlogprof ile
To bind an HTTP header log profile to an LSN group by using the the command line interf ace
At the command prompt, type:
Sample Configuration
Done
Done
Done
Done
Done
Done
Done
Done
Done
Note
When more than a million large scale NAT 64 sessions exist on the NetScaler appliance, Citrix recommends using the selection
parameters to display selected large scale NAT 64 sessions instead of displaying all of them.
To display all large scale NAT64 sessions by using the command line interf ace
To display selective large scale NAT64 sessions by using the command line interf ace
show lsn session –nattype NAT64 [-network6 <ipv6_addr|*>] [-clientname <string>] [-natIP <ip_addr> [-natPort
<port>]]
You can display statistics related to large scale NAT 64 module, and evaluate its performance or troubleshoot problems. You
can display a summary of statistics of all large scale NAT 64 configurations or of a particular large scale NAT 64
configuration. T he statistical counters reflect events since the NetScaler appliance was last restarted. All these counters
are reset to 0 when the NetScaler appliance is restarted.
To display total statistics of large scale NAT64 by using the command line interf ace
To display statistics f or a specified large scale NAT64 configuration by using the command line interf ace
You can remove any unwanted or inefficient large scale NAT 64 sessions from the NetScaler appliance. T he appliance
immediately releases resources (such as NAT IP address, port, and memory) allocated for these sessions, making the
resources available for new sessions. T he appliance also drops all the subsequent packets related to these removed
sessions. You can remove all or selected large scale NAT 64 sessions from the NetScaler appliance.
To clear all large scale NAT64 sessions by using the command line interf ace
At the command prompt, type:
To clear selective large scale NAT64 sessions by using the command line interf ace
At the command prompt, type:
f lush lsn session –nattype NAT64 [-network6 <ipv6_addr|*>] [-clientname <string>] [-natIP <ip_addr> [-natPort
<port>]]
show lsn session –nattype NAT64 [-network6 <ipv6_addr|*>] [-clientname <string>] [-natIP <ip_addr> [-natPort
<port>]]
Done
Clear all large scale NAT64 sessions related to client entity LSN-NAT64-CLIENT-1
Done
Clear all large scale NAT64 sessions related to a subscriber network (2001:DB8:5001::/96) of LSN client entity LSN-NAT64-CLIENT-2
> flush lsn session –nattype NAT64 –network6 2001:DB8:5001::/96 -clientname LSN-NAT64-CLIENT-2
Done
T he NetScaler appliance supports sending information about LSN events in Internet Protocol Flow Information Export
(IPFIX) format to the configured set of IPFIX collector(s). T he appliance uses the existing AppFlow feature to send LSN
events in IPFIX format to the IPFIX collectors.
IPFIX based logging is available for the following NAT 64 related events:
You must configure the AppFlow feature and IPFIX collector(s) on the NetScaler appliance. For instructions, see
Configuring the AppFlow feature.
Configuration Steps
Perform the following tasks for logging LSN information in IPFIX format:
Enable LSN logging in the AppFlow conf iguration. Enable the LSN logging parameter as part of AppFlow
configuration.
Create an LSN log prof ile. An LSN log profile includes the IPFIX parameter that enables or disables the log information
in IPFIX format.
Bind the LSN log prof ile to an LSN group of an LSN conf iguration. Bind the LSN log profile to one or multiple LSN
group(s). Events related to the bound LSN group will be logged in IPFIX format.
To enable LSN logging in the AppFlow configuration by using the NetScaler command line
To create an LSN log profile by using the NetScaler command lineAt the command prompt , type:
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler command line
Navigate to System > Large Scale NAT > Profiles, click Log tab, and then add a log profile.
To bind the LSN log profile to an LSN group of an LSN configuration by using the NetScaler GUI
1. Navigate to System > Large Scale NAT > LSN Group, open the LSN group.
2. In Advanced Settings, click + Log Prof ile to bind the created Log profile to the LSN group.
Port Control Protocol (PCP) enables a subscriber to request specific LSN NAT mappings for itself and/or for other 3rd party
devices. T he large scale NAT device creates an LSN map and sends it to the subscriber. T he subscriber sends the remote
devices on the Internet the NAT IP address:NAT port at which they can connect to the subscriber.
Applications usually send frequent keep-alive messages to the large scale NAT device so that their LSN mappings do not
time out. PCP helps reduce the frequency of such keep-alive messages by enabling the applications to learn the timeout
settings of the LSN mappings. T his helps reduce bandwidth consumption on the ISP’s access network and battery
consumption on mobile devices.
PCP is a client-server model and runs over the UDP transport protocol. A NetScaler appliance implements the PCP server
component and is compliant with RFC 6887.
Configuration Steps
Perform the following tasks for configuring PCP:
(Optional) Create a PCP prof ile. A PCP profile includes settings for PCP related parameters (for example, to listen for
mapping and peer PCP requests). A PCP profile can be bound to a PCP server. A PCP profile bound to a PCP server applies
all its settings to the PCP server. A PCP profile can be bound to multiple PCP servers. By default, one PCP profile with
default parameters settings is bound to all PCP servers. A PCP profile that you bind to a PCP server overrides the default
PCP profile settings for that server. A default PCP profile has the following parameter settings:
Mapping: Enabled
Peer: Enabled
Minimum map life: 120 seconds
Maximum max life: 86400 seconds
Announce count: 10
T hird Party: Disabled
Create a PCP server and bind a PCP prof ile to it. Create a PCP server on the NetScaler appliance to listen for PCP
related requests and messages from the subscribers. A Subnet IP (SNIP) or (SNIP6) address must be assigned to a PCP
server to access it. By default, a PCP server listens on port 5351.
Bind the PCP server to an LSN group of an LSN conf iguration. Bind the created PCP server to an LSN group of an
LSN configuration by setting the PCP Server parameter to specify the created PCP server. T he created PCP server can
be accessed only by the subscribers of this LSN group.
Note
A PCP server for a large scale NAT configuration does not serve requests from subscribers that are identified from ACL rules.
add pcp prof ile <name> [-mapping ( ENABLED | DISABLED )] [-peer ( ENABLED | DISABLED )] [-minMapLif e <secs>]
[-maxMapLif e <secs>] [-announceMultiCount <positive_integer>][-thirdParty ( ENABLED | DISABLED )]
show pcp prof ile <name>
add pcp server <name> <IPAddress> [-port <portNum|*>] [-pcpProf ile <string>]
show pcp server <name>
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
In a MAP-T deployment, the CE device implements a combination of stateful NAPT 44 translation and stateless NAT 46
translation. T he CE device obtains NAT -IP and the port-block to be used for translation through DHCPv6 or any other
method.
When an IPv4 packet from a subscriber device arrives at the CE device, the CE device performs NAPT 44 and stores the
NAPT 44 binding information. After NAT 44 translation, the packet is subjected to NAT 46 translation and then forwarded
to the border router (BR) device located in the ISP’s core network. T he BR device receives the IPv6 packets from the CE
device, extracts and validates the NAT -IP and port-block embedded in the IPv6 header, and forwards the IPv4 packet to
the IPv4 Internet. When the BR receives the IPv4 packet from the Internet, it translates the IPv4 packet to an IPv6 packet
and send the IPv6 packet to the CE device.
MAP-T is stateless on a BR device, so it does not require the BR device to perform NAT on the traffic. Instead, NAT
functionality is delegated to the CE devices. T his delegation and stateless functionality in BR devices allows the BR
deployment to scale in proportion to the volume of traffic.
T he NetScaler appliance implements the BR functionality of a MAP-T solution as described by RFC 7599.
Configuring MAP-T
Configuring MAP-T on a NetScaler appliance consists of the following tasks:
To add a def ault mapping rule by using the NetScaler command line
add MapBmr <name> -RuleIpv6Pref ix <ipv6_addr> | <*> [-psidof f set <positive_integer>] [-EAbitLength
<positive_integer>] [-psidlength <positive_integer>]
show MapBmr <name>
To bind a basic mapping rule to a map domain by using the NetScaler command line
Done
Done
Done
Done
Done
T he NetScaler appliance provides the intelligence to profile subscribers on the basis of their information stored in the Policy
and Charging Rules Function (PCRF). When a mobile subscriber connects to the Internet, the packet gateway associates an
IP address with the subscriber and forwards the data packet to the appliance. T he appliance receives the subscriber
information dynamically, or you can configure static subscribers. T his information enables the NetScaler to apply its rich
traffic management capabilities, such as content switching, integrated caching, rewrite, and responder, on a per-subscriber
basis to manage the traffic.
Before you configure the NetScaler appliance to manage subscribers, you must allocate memory to the module that stores
subscriber sessions. For dynamic subscribers, you must configure an interface through which the appliance receives session
information. Static subscribers must be assigned IDs, and you can associate them with policies.
Each subscriber session entry consumes 1 KB of memory. Storing 500,000 subscriber sessions at any point in time requires
500 MB of memory. T his value must be added to the minimum memory requirement, which is shown as part of the output
of the “show extendedmemoryparam” command. In the following example, the output is for a NetScaler VPX instance with
3 packet engines and 8 GB memory.
To store 500,000 subscriber sessions on this appliance, the configured memory must be 2058+500 MB (500,000 x 1 KB = 500
MB.)
Note
The configured memory must be in multiples of 2 MB and must not exceed the maximum memory usage limit. The appliance must
be restarted for the changes to take effect.
Extended Memory Global Configuration. This memory is utilized by LSN and Subscriber Session Store Modules:
Done
Done
Extended Memory Global Configuration. This memory is utilized by LSN and Subscriber Session Store Modules:
Done
T he NetScaler appliance dynamically receives the subscriber information through any of the following types of interface:
Note
Starting NetScaler release 12.0 build 57.19, Gx interface is supported for a cluster deployment. For more information
see Configuring Gx Interface in a Cluster T opology.
In an HA setup, the subscriber sessions are continually synchronized on the secondary node. In the event of a failover, the
subscriber information is still available on the secondary node.
Gx Interface
A Gx interface (as specified in 3GPP 29.212) is a standard interface based on the Diameter protocol that allows exchange
of policy control and charging rules between a PCRF and a Policy and Charging Enforcement Function (PCEF) entity in a
Telco network.
As soon as an IP-CAN session is established, the packet gateway forwards the subscriber ID, such as the MSISDN, and
Framed-IP address information about the subscriber to the PCRF as a Diameter message. When the data packet arrives at
the appliance from packet gateway (PGW), the appliance uses the subscriber IP address to query the PCRF to get the
subscriber information. T his is also known as secondary PCEF functionality.
T he Policy and Charging Control (PCC) rules received by the appliance over the Gx interface are stored on the appliance for
the duration of the subscriber session, that is, until the PCRF sends a Re-Auth-Request (RAR) message with a Session-
Release-Cause AVP or the subscriber session is terminated from the NetScaler command line or the configuration utility. If
there are any updates to an existing subscriber, the PCRF sends the updates in an RAR message. A subscriber session is
initiated when a subscriber logs on to the network, and terminated when the subscriber logs off.
T he following illustration shows the high-level traffic flow. It assumes that the data plane traffic is HT T P. T he appliance
sends a Credit Control Request (CCR) over a Gx interface to the PCRF server and, in the credit control answer (CCA), receives
the PCC rules and, optionally, other information, such as the Radio Access Technology (RAT ) type, that applies to the
particular subscriber. PCC rules include one or more policy (rule) names and other parameters. T he appliance uses this
information to retrieve the predefined rules stored on the appliance, and to direct the flow of traffic. It also stores this
information in the subscriber policy and enforcement management system for the duration of the subscriber session. After
a subscriber session is terminated, the appliance discards all the information about the subscriber.
2. Add a non-addressable DIAMET ER load balancing virtual sever and bind the services created in step 1 to this virtual server.
For more than one service, specify a persistenceType and the persistAVPno so that specific sessions are handled by the
same PCRF server. For example:
> add lb vserver vdiam DIAMETER 0.0.0.0 0 -persistenceType DIAMETER -persistAVPno 263
3. Configure NetScaler diameter identity and realm. Identity and realm are used as Origin-Host and Origin-Realm AVPs in
diameter messages sent by the Gx client. For example:
4. Configure the Gx interface to use the virtual server created in step 2 as the PCRF virtual server. Specify the PCRF realm to
use as Destination-Realm AVP in diameters messages sent by the Gx client. For example:
> set subscriber gxInterf ace -vServer vdiam -pcrf Realm pcrf.com
Gx Interface parameters:
Done
ARGUMENTS
vServer
Name of the load balancing or content switching virtual server to which the Gx connections are established. T he service
type of the virtual server must be DIAMET ER or SSL_DIAMET ER. T his parameter is mutually exclusive with the service
parameter. T herefore, you cannot set both service and the virtual server in the Gx interface.
Name of DIAMET ER or SSL_DIAMET ER service corresponding to PCRF to which the Gx connection is established. T his
parameter is mutually exclusive with the vserver parameter. T herefore, you cannot set both service and the virtual server in
the Gx Interface.
pcrf Realm
T he realm of PCRF to which the message is to be routed. T his is the realm used in Destination-Realm AVP by NetScaler Gx
client (as a Diameter node).
holdOnSubscriberAbsence
Set to Yes to hold packets until the subscriber session information is fetched from the PCRF server. If set to No, the
default subscriber profile is applied until the subscriber session information is fetched from the PCRF server. If a default
subscriber profile is not configured, an UNDEF is raised for expressions that use subscriber attributes.
requestTimeout
T ime, in seconds, within which the Gx CCR request must complete. If the request does not complete within this time, the
request is retransmitted for the number of times specified in the requestRetryAttempts parameter. If request is not
complete even after retransmitting, then the default subscriber profile is applied to this subscriber. If a default subscriber
profile is not configured, an UNDEF is raised for expressions that use subscriber attributes. Zero disables the timeout.
Default value: 10
requestRetryAttempts
Specify the number of times a request must be retransmitted if the request does not complete within the value specified in
the requestT imeout parameter. Default value: 3
revalidationTimeout
T ime, in seconds, after which the Gx CCR-U request is sent after any PCRF activity on a session. Any RAR or CCA message
resets the timer. Zero value disables the idle timeout.
negativeTTL
T ime, in seconds, after which the Gx CCR-I request is resent for sessions that have not been resolved by PCRF because the
server is down or there is no response or a failed response is received. Instead of polling the PCRF server constantly, a
negative-T T L makes the appliance hold on to an unresolved session. For negative sessions, the appliance inherits the
attributes from the default subscriber profile, if one is configured and from the RADIUS accounting message, if one is
received. Zero value disables the negative sessions. T he appliance does not install negative sessions even if a subscriber
session could not be fetched. Default value: 600
servicePathAVP
T he AVP code in which PCRF sends the service path applicable to a subscriber.
servicePathVendorid
T he vendor id of the AVP in which PCRF sends the service path applicable to a subscriber.
T he NetScaler nodes in the cluster communicate with an external PCRF server through the Gx interface. When a node
receives client traffic, the appliance performs the following:
Each node maintains an independent subscriber store and subscriber sessions are not synchronized to other nodes.
As per the Diameter Base Protocol RFC 6733, each peer must be configured with a unique diameter identity to
communicate with other peers over the diameter protocol. Hence, in a cluster deployment, configuration of diameter
When a node is added to a cluster, it assumes the default diameter parameters (identity=netscaler.com, realm=com,
serverClosePropogation=NO). After the nodes are added, the diameter parameters for each node must be configured.
ARGUMENTS
Identity
Diameter Identity is used to identify a Diameter node uniquely. Before setting up diameter configuration, the NetScaler
appliance (as a Diameter node) must be assigned a unique diameter identity.
For example, set ns diameter -identity netscaler.com -ownerNode 1. So, whenever NetScaler system needs to use identity
in diameter messages, it uses 'netscaler.com' as Origin-Host AVP as defined in RFC3588.
OwnerNode
OwnerNode represents the ID of the cluster node for which the diameter ID is set. OwnerNode can be configured only
through CLIP.
Minimum value: 0
Maximum value: 31
Example
Note:
When the show ns diameter command is executed, it displays the diameter parameters for a given node.
Example
2. Add a DIAMET ER load balancing virtual sever and bind the services created in step 1 to this virtual server.
Example
3. Configure NetScaler diameter identity and realm on all the cluster nodes. Identity and realm are used as Origin-Host
and Origin-Realm AVPs in diameter messages sent by the Gx client.
Example
4. Configure the Gx interface to use the virtual server created in step 2 as the PCRF virtual server and set the PCRF realm
as well.
Example
Example
RADIUS Interface
With a RADIUS interface, the packet gateway forwards the subscriber information in a RADIUS Accounting Start message
to the appliance through the RADIUS interface as soon as an IP-CAN session is established. A service of type
RADIUSListener processes RADIUS Accounting messages. Add a shared secret for the RADIUS client. If a shared secret is
not configured, the RADIUS message is silently dropped. T he following example shows the commands for configuring a
RADIUS interface. T he commands are in boldface.
1. Create a RADIUS listener service at the NetScaler SNIP address where the RADIUS messages are received. For example:
2. Configure the subscriber RADIUS interface to use this service. For example:
4. Add a RADIUS client specifying a subnet and shared secret. For example:
A subnet of 0.0.0.0/0 implies that it is the default shared secret for all clients.To see the RADIUS interface configuration and
status, type:
Done
ARGUMENT S
ListeningService
Name of the RADIUS listening service that will process the RADIUS accounting requests.
svrState
set subscriber gxInterface -vServer vdiam -pcrfRealm testrealm1.net -holdOnSubscriberAbsence YES -revalidationTimeout 60 -negativeTTL 120
You can configure the subscribers manually on the NetScaler appliance by using the command line or the configuration
utility. You create static subscribers by assigning a unique subscriber ID and optionally associating a policy with each
subscriber. T he following examples show the commands for configuring a static subscriber.
In the following examples, subscriptionIdvalue specifies the international telephone number, and subscriptionIdType
(E164 in this example) specifies the general format for international telephone numbers.
add subscriber profile 203.0.113.6 -subscriberRules policy1 policy2 -subscriptionIdType E164 –subscriptionIdvalue 98767543211
add subscriber profile 2002::a66:e8d3/64 -subscriberRules policy1 policy3 -subscriptionIdtype E164 –subscriptionIdvalue 98767543212
Profile Attributes:
Profile Attributes:
Done
A default subscriber profile is used if the subscriber IP address is not found in the subscriber session store on the appliance.
In the following example, a default subscriber profile is added with the subscriber rule policy1.
Use the following command to display all the static and dynamic subscriber sessions.
Session Attributes:
2) Subscriber IP: *
Session Attributes:
Session Attributes:
Session Attributes:
AVP(44): 34 44 32 42 42 38 41 43 2D 30 30 30 30 30 30 31 31
AVP(257): 00 01 C0 A8 0A 02
PCRF-Host: host.pcrf.com
AVP(280): 74 65 73 74 2E 63 6F 6D
Done
Use the following command to clear a single session or the complete session store. If you do not specify an IP address, the
complete subscriber session store is cleared.
T he NetScaler appliance uses the subscriber's IP address as the key to the subscriber policy enforcement and management
system.
You can add subscriber expressions to read the subscriber information available in the Subscriber Policy Enforcement &
Management System. T hese expressions can be used with policy rules and actions that are configured for NetScaler
features, such as integrated caching, rewrite, responder, and content switching.
T he following commands are an example of adding a subscriber-based responder action and policy. T he policy evaluates to
true if the subscriber rule value is“pol1”.
The following example shows the commands to add a subscriber-based rewrite action and policy. The action inserts an HTTP header “X-
Nokia-MSISDN” by using the value of AVP(45) in the subscriber session.
In the following example, two policies are configured on the appliance. When the appliance checks the subscriber information and the
subscriber rule is cache_enable, it performs caching. If the subscriber rule is cache_disable, the appliance does not perform caching.
> add cache policy cachepol -rule "SUBSCRIBER.RULE_ACTIVE(\"cache_enable\")" - action CACHE -storeInGroup cg1
For a complete list of expressions starting with “SUBSCRIBER.” see the Policy Configuration Guide.
A telco user is generally identified by the IPv6 prefix rather than the complete IPv6 address. T he NetScaler appliance now
uses the prefix instead of the complete IPv6 address (/128) to identify a subscriber in the database (subscriber store). For
communicating with the PCRF server (for example, in a CCR-I message), the appliance now uses the framed-IPv6-Prefix AVP
instead of the complete IPv6 address. T he default prefix length is /64, but you can configure the appliance to use a
different value.
T he first example command below sets a single prefix and the second example command sets multiple prefixes.
Subscriber session cleanup on a NetScaler appliance is based on control plane events, such as a RADIUS Accounting Stop
message, a Diameter RAR (session release) message, or a "clear subscriber session" command. In some deployments, the
messages from a RADIUS client or a PCRF server might not reach the appliance. Additionally, during heavy traffic, the
messages might be lost. A subscriber session that is idle for a long time continues to consume memory and IP resources on
the NetScaler appliance. T he idle session management feature provides configurable timers to identify idle sessions, and
cleans up these sessions on the basis of the specified action.
A session is considered idle if no traffic from this subscriber is received on the data plane or the control plane. You can
specify an update, terminate (inform PCRF and then delete the session), or delete (without informing PCRF) action. T he
action is taken only after the session is idle for the time specified in the idle timeout parameter.
To configure the idle session timeout and the associated action by using the command line
To disable the idle session timeout, set the idle timeout to zero.
To configure the idle session timeout and the associated action by using the configuration utility
If you enable subscriber logging, you can track the RADIUS and Gx control plane messages specific to a subscriber, and use
the historical data to analyze subscriber activities. Some of the key attributes are MSISDN and time stamp. T he following
attributes are also logged:
By using these logs, you can track users by IP address and, if available, MSISDN.
You can enable subscriber session logging to a local or remote syslog or nslog server. T he following example shows how to
enable subscriber logging to a remote syslog server.
> add syslogAction sysact1 192.0.2.0 -loglevel EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFORMATIONAL -subscriberlog en
From these logs, you can learn about any activity related to a user, such as the time when a session was updated, deleted, or created
(installed). Additionally, error messages are also logged.
Examples
1. The following log entries are examples of RADIUSandGx session creation, session update, and session deletion.
09/30/2015:16:29:18 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT 147 0 : Session Install, GX
MsgType: CCR-I, RADIUS MsgType: Start, IP: 100.10.1.1, ID: E164 - 30000000001
09/30/2015:16:30:18 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT 148 0 : Session Update, GX
MsgType: CCR-U, IP: 100.10.1.1, ID: E164 - 30000000001
09/30/2015:17:27:56 GMT Informational 0-PPE-0 : default SUBSCRIBER SESSION_EVENT 185 0 : Session Delete, GX
MsgType: CCR-T, RADIUS MsgType: Stop, IP: 100.10.1.1, ID: E164 - 30000000001
2. The following log entries are examples of failure messages, such as when a subscriber is not found on the PCRF server and when the
appliance cannot connect to the PCRF server.
09/30/2015:16:44:15 GMT Error 0-PPE-0 : default SUBSCRIBER SESSION_FAILURE 169 0 : Failure Reason: PCRF failure response, GX
MsgType: CCR-I, IP: 100.10.1.1
Sep 30 13:03:01 09/30/2015:16:49:08 GMT 0-PPE-0 : default SUBSCRIBER SESSION_FAILURE 176 0 : Failure Reason: Unable to
connect to PCRF, GX MsgType: CCR-I, RADIUS MsgType: Start, IP: 100.10.1.1, ID: E164 -
In earlier releases, if a subscriber session is deleted when a RADIUS Accounting STOP or a PCRF-RAR message is received, or
as a result of any other event, such as T T L expiry or flush, the corresponding LSN sessions of the subscriber are removed
only after the configured LSN timeout period. LSN sessions that are kept open until this timeout expires continue to
consume resources on the appliance.
From release 11.1, a new parameter (subscrSessionRemoval) is added. If this parameter is enabled, and the subscriber
information is deleted from the subscriber database, LSN sessions corresponding to that subscriber are also removed. If this
parameter is disabled, the subscriber sessions are timed out as specified by the LSN timeout settings.
To configure subscriber aware LSN session termination by using the NetScaler command line
Done
To configure subscriber aware LSN session termination by using the NetScaler GUI
If your deployment is not working as expected, use the following commands to troubleshoot:
If subscriber logging is enabled, you can get more detailed information from the log files.
T he values shown in the following figure are configured in the CLI procedure that follows the figure. A content switching
virtual server on the NetScaler appliance directs requests to the value added services or skips them, depending on the
defined rule, and then sends the packet out to the Internet after performing LSN.
To configure traf fic steering f or the above deployment by using the NetScaler command line:
Example
2. Add the VLANs. VLANs help the appliance identify the source of the traffic. Bind the VLANs to the interfaces and subnet
Example
add vlan 10
add vlan 20
3. Specify the VLAN on which the subscriber traffic arrives on the appliance. Specify the service path AVP that tells the
appliance where to look for the service path name within the subscriber session. For primary PCEF functionality, specify the
interfaceType as RadiusAndGx.
Example
4. Configure a service and virtual server of type Diameter, and bind the service to the virtual server. T hen, specify the PCRF
realm and subscriber Gx interface parameters. For primary PCEF functionality, configure a RADIUS listener service and
RADIUS interface.
Example
set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf1.net -holdOnSubscriberAbsence YES -idleT T L 1200 -
negativeT T L 120
5. Add service functions to associate a VAS with an ingress VLAN. Add a service path to define the chain, that is, specify the
VAS that the packet must be sent to and the order in which it must go to that VAS. T he service path name is usually sent
T he service path AVP that contains this name must already be configured as part of the global configuration. Bind the
service function to the service path. T he service index specifies the order in which the VAS is added to the chain. T he
highest number (255) indicates the beginning of the chain.
Example
6. Add the LSN configuration. T hat is, define the NAT pool and identify the clients for which the appliance must perform
LSN.
7. T he appliance performs LSN by default. To override LSN, you must create a net profile with the overrideLsn parameter
enabled, and bind this profile to all the load balancing virtual servers that are configured for value added services (VASs).
Example
8. Configure the VAS on the appliance. T his includes creating the services and virtual servers and then binding the services to
the virtual servers.
9. Add the content switching (CS) configuration. T his includes virtual servers, policies, and their associated actions. T he
traffic arrives at the CS virtual server and is then redirected to the appropriate load balancing virtual server. Define
expressions that associate a virtual server with a service function.
Example
add cs policy cspol1 -rule SUBSCRIBER.SERVICEPAT H.IS_NEXT (\"SF1\") && SYS.VSERVER(\"vs1\").STAT E.EQ(UP)" -
action csact1
1. Navigate to System > Network > IPs and add the subnet IP addresses.
2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and subnet IP addresses.
3. Navigate to Traf f ic Management > Service Chaining > Conf igure Service Path Ingress VLAN and specify an ingress
VLAN.
4. Navigate to Traf f ic Management > Subscriber > Parameters > Conf igure Subscriber Parameters and specify the
following:
Interface T ype: Specify RadiusAndGx.
Configure a diameter virtual server, PCRF realm, and the subscriber GX interface parameters.
Specify the RADIUS interface parameters.
5. Navigate to Traf f ic Management > Service Chaining > Service Function and add service functions to associate a
value-added service with an ingress VLAN.
6. Navigate to System > Network > Large Scale NAT. Click Pools and add a pool. Click Clients and add a client. Click
Groups and add a group and specify the client. Edit the group and bind the pool to this group.
7. Navigate to System > Network > Net Prof iles and add a net profile. Select Override LSN. Optionally, navigate to
System > Network > Settings > Conf igure Layer 3 Parameters and verify that Override LSN is not selected.
8. Navigate to Traf f ic Management > Load Balancing > Virtual Servers and configure the virtual servers and value-
added services on the appliance. Bind the services and the net profile to the virtual server.
9. Navigate to Traf f ic Management > Content Switching > Virtual Servers and configure a virtual server, policy, and
action. Specify the target load balancing virtual server.
1. Navigate to System > Network > IPs and add the subnet IP addresses.
2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and subnet IP addresses.
To do the above and more, service providers must be able to provide value-added services on a per-subscriber basis. In other
words, entities in the service provider network must be capable of extracting the subscriber information and intelligently
steering the packet on the basis of this information.
Service chaining determines the set of services through which the traffic from a subscriber must pass before going to the
Internet. Instead of sending all the traffic to all the services, the NetScaler intelligently routes all requests from a subscriber
to a specific set of services on the basis of the policy defined for that subscriber.
T he following figure shows the entities involved in service chaining. T he values shown are configured in the procedure that
follows the figure. A content switching virtual server on the NetScaler appliance directs requests to the value added services
or skips them, depending on the defined rule, and then sends the packet out to the Internet after performing LSN.
To configure service chaining f or the above deployment by using the NetScaler command line:
Example
2. Add the VLANs. VLANs help the appliance identify the source of the traffic. Bind the VLANs to the interfaces and subnet
IP addresses. Add an ingress and an egress VLAN for each VAS.
Example
add vlan 10
add vlan 20
add vlan 30
add vlan 40
add vlan 50
add vlan 60
3. Specify the VLAN on which the subscriber traffic arrives on the appliance. Specify the service path AVP that tells the
appliance where to look for the service path name within the subscriber session. For primary PCEF functionality, specify the
interfaceType as RadiusAndGx.
Example
4. Configure a service and virtual server of type Diameter, and bind the service to the virtual server. T hen, specify the PCRF
realm and subscriber Gx interface parameters. For primary PCEF functionality, configure a RADIUS listener service and
RADIUS interface.
Example
set subscriber gxInterface -vServer vdiam -pcrfRealm pcrf1.net -holdOnSubscriberAbsence YES -idleT T L 1200 -
negativeT T L 120
5. Add service functions to associate a VAS with an ingress VLAN. Add a service path to define the chain, that is, specify the
VAS that the packet must be sent to and the order in which it must go to that VAS. T he service path name is usually sent
by the PCRF. However, the service path of the default subscriber profile (*) applies if any of the following is true:
T he service path AVP that contains this name must be configured as part of the global configuration earlier. Bind the service
function to the service path. T he service index specifies the order in which the VAS is added to the chain. T he highest
number (255) indicates the beginning of the chain.
Example
6. Add the LSN configuration. T hat is, define the NAT pool and identify the clients for which the appliance must perform
LSN.
Example
7. T he appliance performs LSN by default. To override LSN, you must create a net profile with overrideLsn parameter
enabled and bind this profile to all the load balancing virtual servers that are configured for value added services (VASs).
Example
8. Configure the VAS on the appliance. T his includes creating the services and virtual servers and then binding the services to
the virtual servers.
Example
9. Add the content switching (CS) configuration. T his includes virtual servers, policies, and their associated actions. T he
traffic arrives at the CS virtual server and is then redirected to the appropriate load balancing virtual server. Define
expressions that associate a virtual server with a service function.
Example
add cs policy cspol1 -rule "SUBSCRIBER.SERVICEPAT H.IS_NEXT (\"SF1\") && SYS.VSERVER(\"vs1\").STAT E.EQ(UP)" -action
csact1
add cs policy cspol2 -rule "SUBSCRIBER.SERVICEPAT H.IS_NEXT (\"SF2\") && SYS.VSERVER(\"vs2\").STAT E.EQ(UP)" -action
csact2
add cs policy cspol3 -rule "SUBSCRIBER.SERVICEPAT H.IS_NEXT (\"SF3\") && SYS.VSERVER(\"vs3\").STAT E.EQ(UP)" -action
csact3
1. Navigate to System > Network > IPs and add the subnet IP addresses.
2. Navigate to System > Network > VLANs and add VLANs, Bind the VLANs to the interfaces and subnet IP addresses.
3. Navigate to Traf f ic Management > Service Chaining > Conf igure Service Path Ingress VLAN and specify an ingress
VLAN.
4. Navigate to Traf f ic Management > Subscriber > Parameters > Conf igure Subscriber Parameters and specify the
following:
Interface T ype: Specify RadiusAndGx.
Configure a diameter virtual server, PCRF realm, and the subscriber GX interface parameters.
404
© 1999- Citrix Systems, Inc. All rights reserved. | Terms of Use | Cookie Preferences
Create separate TCP profiles for subscribers connecting through a 4G network and for users connecting through any other network. Define
a policy rule that is selected on the basis of a subscriber parameter, such as RAT-type. In the following examples, if RAT-Type is EUTRAN, a
TCP profile that supports a faster connection is selected (Example 1). For all other RAT-Type values, a different TCP profile is selected
(Example 2).
Note
T he RAT -Type AVP (AVP code 1032) is of type Enumerated and is used to identify the radio access technology that is serving the UE.
T he value "1004" indicates that the RAT is EUT RAN. (RFC 29.212).
add ns tcpProfile tcp2 -WS ENABLED -SACK ENABLED -WSVal 8 -initialCwnd 16 - oooQSize 15000 -slowStartIncr 1 -bufferSize 1000000 -flavor
NetScaler enables you to load balance SIP messages over UDP or over TCP (including T LS) to a group of proxy servers.
NetScaler also provides Call-ID based persistence and Call-ID hash load balancing method using which you direct packets
for a particular SIP session to the same load balanced SIP server.
T he NetScaler default expressions language contains a number of expressions that operate on Session Initiation Protocol
(SIP) connections. T hese expressions are intended to be used in policies for SIP protocol that operates on a
request/response basis. T hese expressions can be used in content switching, rate limiting, responder, and rewrite policies.
Millions of short messages are exchanged daily between individuals and value-added service providers, such as banks,
advertisers, and directory services, by using the short message peer to peer (SMPP) protocol. Often, message delivery is
delayed because servers are overloaded and traffic is not optimally distributed among the servers.
T he NetScaler appliance provides optimal distribution of messages across your servers, preventing poor performance and
outages. T he NetScaler appliance:
Load balances messages originating from the server and from the client
Monitors the health of the message centers
Provides content switching support for the message centers
Handles concatenated messages
Limitation: Message IDs, from the message center, longer than 59 bytes are not supported. If the message ID length
returned by the message center is more than 59 bytes, ancillary operations fail and the NetScaler appliance responds with
an error message.
Diameter is a base protocol with more than 50 protocols (also called applications) built over it. T herefore, the diameter
traffic generated in a Telco network is high. To optimally maintain this diameter traffic, the NetScaler appliance performs
load balancing, content switching, and acts as a relay agent. Additionally, the appliance offers rewrite and responder
functionality. T he appliance supports rate limiting of Diameter messages.
For requests for a domain that has been cached earlier, the NetScaler serves the Address record of the domain from the
cache without querying the configured DNS server and hence saves the bandwidth.
From 11.0 release onwards, NetScaler also logs the DNS requests that it receives and also the responses that it sends to
the client. Telecom service providers can use this log to:
If the site loses connectivity to all or part of the public Internet, it will be inaccessible to users and customers, which can
have significant impact on the business.
Users accessing the site from geographically distant locations may experience large and highly variable delays, which are
exacerbated by the large number of round trips that HT T P requires to transfer content.
NetScaler appliance’s Global Server Load Balancing (GSLB) overcomes these problems by distributing traffic among sites
deployed in multiple geographic locations. By serving content from many different points in the Internet, GSLB alleviates
the impact of network bandwidth bottlenecks and provides robustness in case of network failures at a particular site. Users
can be automatically directed to the nearest or least loaded site at the time of the request, minimizing the likelihood of
long download delays and/or service disruptions.
You can use NetScaler appliance’s global server load balancing for:
Disaster recovery or high availability by configuring an Active-standby data center setup that consists of an active and a
standby data center. When a failover occurs as a result of a disaster event, the standby data center becomes
operational.
High availability and speed by configuring an active-active data center setup that consists of multiple active data
centers. Client requests are load balanced across active data centers.
Directing client requests to the data center that is closest in geographical distance or network distance by configuring a
proximity setup.
Full-DNS resolutions, GSLB processes DNS queries of the A, AAAA and CNAME types, and the DNS function option can
process DNS queries of all other types, such as MX and PT R. Also, if the recursive resolution is enabled, the NetScaler will
forward DNS queries for domain names that are not configured on the NetScaler appliance.
Choosing and inserting an appropriate NetScaler T 1000-Series model in a mobile network for T CP optimization
Full configuration instructions related to not only T CP optimization but also for appropriate Layer-2 and Layer-3
configuration of the T 1 device
Getting Started
Managment Network
Licensing
High Availability
Gi-LAN Integration
T CP Optimization Configuration
Optimizing T CP Performance Using T CP NILE
CQA and Adaptive T CP Optimization
Analytics and Reporting
Real-time Statistics
SNMP
T echnical Recipes
T roubleshooting Guidelines
Frequently Asked Questions
Citrix provides a wide breath of NetScaler models that might be loosely based on two factors:
Capacity, currently ranging from hundreds of Mbps for the low-end VPX appliance to 160Gbps for the high-end 25000
MPX series appliance
T elco grade, with the availability of the T 1000 series for T elco datacenters.
Your Citrix Sales or Support representative can help you select the appropriate hardware for your demo, trial, or production
needs.
T he remainder of this section uses a NetScaler T 1200 as a reference hardware. Note that putting aside superficial
differences related to number and notation of available interfaces* or well-documented limitations of NetScaler VPX**
the instructions should apply mostly verbatim regardless of the NetScaler model selected.
Note
* For instance a the T 1010 model only has 12x1GbE typically marked as 1/1-1/12 rather than the 10/x notation used in this
document.
** A NetScaler VPX instance typically doesn’t support LACP aggregation; it might also not support VLAN tagging.
Username: nsroot
Password: nsroot
Once logged in, configure the basic details of the NetScaler appliance as shown in the screen capture below.
> saveconfig
After you restart the appliance, you might use SSH for further configuration of the T 1100 nodes.
Set a static IP on your laptop and plug it directly into the LOM interface with a crossover cable or into a switch in the same
broadcast domain as the LOM interface.
For initial configuration, type the port’s default address: http://192.168.1.3 in a web browser and change the LOM port’s
default IP address.
T he NetScaler TCP optimization for mobile networks is constantly evolving. T he capabilities and tunings outlined in this
document require a NetScaler Telco build. Here is an example showing the NetScaler Telco build.
If the T 1000 has not shipped with the appropriate build revision, contact the NetScaler Customer Support.
Important
Both the appliances should have the same software image.
A NetScaler appliance can be configured by using either the NetScaler CLI or the HT ML5 GUI. However, this section
provides only CLI-based instructions.
While the NetScaler CLI is accessible through the NetScaler serial console, an SSH client is normally recommended to allow
Most NetScaler devices offer redundant 1GbE OAM ports, notated as 0/1 and 0/2. To provide for redundancy in case of a
switch failure, you should connect the relevant ports to different upstream switches.
After the NetScaler appliance is connected to the management network, subsequent configuration steps can be
performed remotely using SSH or web connectivity to the NetScaler CLI and GUI respectively.
T he add route command may be used to configure any routes appropriate to the management network. T he relevant
gateway should be reachable on the NSIP subnet, as shown below.
License files should be copied through an SCP client to the /nsconfig/license of the appliance, as shown in the screen
capture below.
CNS_V3000_SERVER_PLT_Retail.lic ssl
Do a warm restart to apply the new license, as shown in the screen capture below.
Done
After the restart completes, verify that the license has been properly applied, by using the show license CLI.
In the example below a 3Gbps Platinum license has been successfully installed.
License status:
...
Done
While there are multiple connectivity options for a NetScaler HA pair, the most recommended one is depicted in the
following diagram:
In the above diagram, the N+1 red links between each T 1000 and the respective switch imply N+1 redundancy - as explained
in Connectivity. For instance, considering a 45 Gbps Gi-LAN N=5 is an appropriate value, with 6x10GbE LACP channels
between each switch and the respective T 1000 as well as between the two switches.
An extra pair of links is recommended between the NetScaler pair, to provide for HA communication isolation from the
OAM network.
A physical NetScaler connectivity to upstream switches is recommended to provide for sufficient redundancy. For example,
assuming that a NetScaler appliance is inserted in a Gi-LAN that is handling a total (uplink+downlink) of 24Gbps,
connectivity with 4x10GbE or more interfaces is recommended. T his effectively provides for N+1 redundancy in case of a
link failure.
T he relevant ports on the upstream switch should be configured for LACP port aggregation. T he relevant configuration on
NetScaler is outlined below:
You can verify the appropriate functionality of LACP using the “show interface” command:
throughput 0
Disable the remaining unused interfaces and turn off the monitor.
...
...
Configuration of physical interfaces is not shared across the two NetScaler units. Hence, the above commands must be run
All other configuration parameters are shared between the NetScaler nodes of an HA pair. Hence, HA sync should be
enabled prior to any other configuration commands being run. Basic HA configuration involves the following steps:
1. Using the exact same NetScaler hardware, software, and license: HA pairs are not supported between different
models (i.e. a T 1100 and an MPX21550) or same models with different firmware levels. Refer to the appropriate
instructions on upgrading an existing HA pair - Upgrading to Release 11.1.
3. Verify the HA pair establishment running the following command in either node; both nodes should be visible, one of
them as Primary (active), the other as a Secondary (standby).
4. Enable failsafe mode and maxFlips. T his ensures that in case of a route monitor failure on both nodes at least one
node remains active without active/standby status constantly switching.
5. Finally, enable HA sync to occur over the dedicated intra-NetScaler ports rather than the OAM network.
Note
T he VLAN 4080 in the commands in the above example shouldn’t be taken literally. Any unused VLAN-ID might be reserved.
After the physical interfaces have been appropriately configured, you might configure the appropriate Gi-LAN VLANs. For
instance, consider a rather simple Gi-LAN environment with an ingress/egress VLAN pair with 100/101 VLAN-identifier
respectively.
T he following commands configure the relevant VLANs on top of the LACP channel created in the prior step.
Typically, a NetScaler appliance requires one SNIP per VLAN. T he example below assumes that the networks outlined in the
Gi-LAN integration diagram, given in the begining of this page, have a /24 subnet mask:
After the SNIPs have been configured they should be associated with the appropriate VLAN:
T he example outlined in the Management Network section calls for only a couple of static routing rules:
A NetScaler appliance allows for policy-based routing instead of static routing, with routing decisions usually keyed against
the incoming interface and/or VLAN rather than destination IP. Policy-based routing is either a convenient alternative, in
case the client source IP address range is subject to periodic changes, or a mandatory consideration, in case a packet’s
destination IP address is not sufficient by itself to reach a routing decision (i.e. in case of overlapping client IP addresses
across multiple VLANs).
Done
Done
>apply ns pbrs
T he following commands assign IPv6 SNIP per vlan. T he example below assumes that the networks outlined in the "Figure:
A simple depiction of a Gi-LAN" in this page have a /64 subnet mask:
>apply ns pbr6
In case of an HA configuration, it’s recommended to leverage the throughput option to configure a low threshold for the
LACP channel. For instance, consider a 25Gbps Gi-LAN and a 4x10GbE channel between each NetScaler appliance in the HA
pair and the upstream switch to provide N+1 link redundancy:
In case of a double-link failure between the primary NetScaler and the upstream switch the maximum Gi-LAN throughput
that can be supported would fall to 20Gbps. A 29Gbps low threshold per the example above would result in a redundancy
switchover event to the secondary NetScaler (which has not suffered similar link failures) so that Gi-LAN traffic is not
affected.
In addition to LACP redundancy, route monitor checks might be configured and associated with the HA pair configuration.
Route monitor checks can be useful to detect failures between the NetScaler appliance and the next-hop routers,
especially if said routers are not directly connected but through an upstream switch.
A typical HA route monitor configuration per the sample Gi-LAN in section 2.5.1 is outlined below:
> add route 192.168.2.0 255.255.255.0 192.168.2.1 -msr ENABLED -monitor arp
Before configuring TCP optimization, apply the following basic configuration settings on the NetScaler appliance:
Note
Restart the NetScaler appliance if you change the rsskeytype system parameter.
For NetScaler T 1 to apply TCP optimization it needs to first terminate incoming TCP traffic. Towards this end, a wildcard
TCP vserver should be created and configured to intercept ingress traffic and then forward it to the Internet router.
> add lb vserver vsrv-wireless TCP * * -persistenceType NONE -Listenpolicy "CLIENT.VLAN.ID.EQ(100) && SYS.VSERVER(\"vsrv-wireless\").STA
Using Policy Based Routing to route TCP optimized traffic is a new feature added in release 11.1 50.10. For previous releases,
having multiple “mode MAC” vserver entities per VLAN is an alternative solution for multi-VLAN environments. Each vserver
has a bound service representing the internet router for the particular flow.
> add lb vserver vsrv-wireless-1 TCP * * -Listenpolicy "CLIENT.VLAN.ID.EQ(100) && SYS.VSERVER(\"vsrv-wireless-1\").STATE.EQ(UP)" -m MAC
> add lb vserver vsrv-wireless-2 TCP * * -Listenpolicy "CLIENT.VLAN.ID.EQ(101) && SYS.VSERVER(\"vsrv-wireless-2\").STATE.EQ(UP)" -m MAC
> add lb vserver vsrv-wireless-3 TCP * * -Listenpolicy "CLIENT.VLAN.ID.EQ(102) && SYS.VSERVER(\"vsrv-wireless-3\").STATE.EQ(UP)" -m MAC
Out-of-the-box NetScaler TCP termination is configured for TCP pass-through functionality. TCP pass-through essentially
means that NetScaler T 1 may transparently intercept a client-server TCP stream but does not retain separate client/server
buffers or otherwise apply any optimization techniques.
To enable TCP optimization a TCP profile, named as nstcpprofile, is used to specify TCP configurations that is used if no TCP
configurations are provided at the service or virtual server level and it should be modified as follows:
>add ns tcpProfile nstcpprofile -WS ENABLED -SACK ENABLED -WSVal 8 -mss 1460 -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 8
Note
If there is not any profile explicitly created and bound to vserver and service, the profile nstcp_default_profile is bound by default.
In case of multiple TCP profiles requirement, extra TCP profiles can be created and associated with the appropriate virtual server
Note
For deployments with vserver -m MAC and service, same profile should be associated with service.
1. Window Scaling (WS): T CP Window scaling allows increasing the T CP receive window size beyond 65535 bytes. It helps
improving T CP performance overall and specially in high bandwidth and long delay networks. It helps with reducing
latency and improving response time over T CP.
2. Select ive acknowledgment (SACK): T CP SACK addresses the problem of multiple packet loss which reduces the
overall throughput capacity. With selective acknowledgement the receiver can inform the sender about all the segments
which are received successfully, enabling sender to only retransmit the segments which were lost. T his technique helps T 1
improve overall throughput and reduce the connection latency.
3. Window Scaling F act or (WSVal): Factor used to calculate the new window size. It must be configured with a high
value in order to allow the advertised window by NS to be at least equal to the buffer size.
4. Maximum Segment Size (MSS): MSS of a single T CP segment. T his value depends on the MT U setting on
intermediate routers and end clients. A value of 1460 corresponds to an MT U of 1500.
5. maxBurst : Maximum number of T CP segments allowed in a burst.
6. Init ial Congest ion Window size(init ialCwnd): T CP initial congestion window size determines the number of bytes
For the above parameters please consult [1] for guidance on picking the appropriate values. For the remaining ones, the
values outlined in TCP Optimization should apply to most cases.
In a Telco network, almost 50 percent of a NetScaler appliance's TCP connections become idle, and the appliance sends
RST packets to close them. T he packets sent over radio channels activate those channels unnecessarily, causing a flood of
messages that in turn cause the appliance to generate a flood of service-reject messages. T he default TCP profile now
includes DropHalfClosedConnOnT imeout and DropEstConnOnT imeout parameters, which by default are disabled. If you
enable both of them, neither a half closed connection nor an established connection causes a RST packet to be sent to
the client when the connection times out. T he appliance just drops the connection.
inactSvcs
vsrv...eless 0
Vserver hits 0 10
Requests 0 0
Responses 0 0
Labeled Connection -- 0
Deferred Request 0 0
Invalid Request/Response -- 0
T he Total counters should constantly increase for an operational system. In addition, the Rate counters should be non-
zero.
Note
T he preceding output is from an operational yet idle lab system, explaining the zero rate.
Memory
resMemUsage (1.3.6.1.4 .1.5951.4 .1.1.4 1.2)
Throughput
allNicT ot RxMbit s (1.3.6.1.4 .1.5951.4 .1.1.7 1.1)
IP packets received.
Connections
Act ive connect ions:
Server connections, including connections in the Opening, Established, and Closing state.
Client connections, including connections in the Opening, Established, and Closing state.
Client connections that are flushed because the client has been idle for some time.
Server connections that are flushed because there have been no client requests in the queue for some time.
Errors
Number of times NetScaler terminates a connection after retransmitting the packet seven times on that
connection.Retrasnmission happens when recieving end doesn't acknowledges the packet.
if InDiscards (1.3.6.1.2.1.2.2.1.13)
T he number of inbound packets which were chosen to be discarded even though no errors had been detected to prevent
their being deliverable to a higher-layer protocol. One possible reason for discarding such a packet could be to free up
buffer space.
T he number of outbound packets which were chosen to be discarded even though no errors had been detected to prevent
their being transmitted. One possible reason for discarding such a packet could be to free up buffer space.
Number of packets that have passed through the overflow queues, during transmission on the specified interface, since the
NetScaler appliance was started or the interface statistics were cleared. T his gets incremented only on congested ports.
While it is not possible to evaluate all capabilities that are potentially unlocked by the T 1000 features and policy
configuration guide, technical receipes consider implementation of various requirements brought in by Telco operators. Feel
free to re-use the “recipes” as is or adapt to your environment.
T he NetScaler T 1 model can be configured to limit the number of connections per unique subscriber IP. With the below
configuration, N concurrent TCP connections per IP (CLIENT.IP.SRC) is allowed. For every attempt for connection beyond
the configured threshold, T 1 sends an RST. For maximum 2 concurrent connections per user:
Many operators concern about TCP connections disruption when the NetScaler T 1 model is activated inline for TCP
optimization or when it is disabled for maintenance purposes. To avoid breaking existing connections when vserver is
introduced, the following configuration needs to be applied before configuring or activating vserver for TCP optimization:
Forwarding sessions are effective on top of routing (either static or dynamic or PBR) and create session entries for traffic
that is routed (L3 mode). Any existing connection is handled by forwarding session due to corresponding sessions, and upon
vserver introduction it starts capturing only new TCP connections.
ACLs can be configured to capture only specific ports like vserver, in order to avoid creating sessions for unnecessary traffic,
which is memory consuming. Another option is to remove specific configuration after vserver activation.
For maintenance purposes, vserver should be disabled and its state appears as OUT OF SERVICE. When this happens, the
vserver terminates all connections immediately by default. To make vserver to still serve the existing connections and not
accept new, the following configuration should be applied:
New connections go through the routing table, and corresponding session entries are created due to forwarding sessions.
Policy-based TCP Profile selection allows operators to configure TCP profile dynamically for clients coming from different
traffic domains (i.e. 3G or 4G). Some of the QoS metrics are different for these traffic domains, and in order to achieve
better performance, you need to change some of the TCP parameter dynamically. Consider a case where clients coming
from 3G and 4G hit same vserver and use same TCP profile, which have negative impact on some client's performance.
AppQoE functionality can classify these clients and dynamically change TCP profile on vserver.
> add ns tcpProfile nstcpprofile1 -WS ENABLED -SACK ENABLED -WSVal 8 -mss 1460 -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO
> add ns tcpProfile nstcpprofile2 -WS ENABLED -SACK ENABLED -WSVal 8 -mss 1460 -maxBurst 15 -initialCwnd 16 -oooQSize 15000 -minRTO
T he NetScaler T 1 model is capable to receive the subscriber information dynamically through Gx or Radius or Radius and Gx
interface and apply different TCP profile on a per-subscriber basis.
1. All cluster nodes belong to the same network (also known as an L2 cluster).
Not e: T he design depicted in Figure 1 is also applicable to T 1120 and T 1310 appliances. For T 1310 we would use 40GbE
interfaces for the backplane connections, since it lacks 10GbE ports.
Not e: While this document uses Cisco VPC as an example, if working with non-Cisco switches alternate equivalent
solutions could be used, such as Juniper’s MLAG.
Not e: While other topologies such as ECMP instead of CLAG are possible, they are not currently supported for this
particular use case.
After physical installation, physical connectivity, software installation, and licensing are completed, you can proceed with
the actual cluster configuration. T he configurations described below apply to the cluster depicted in Figure 1.
Note: For more information about cluster configuration, see “Setting up a NetScaler Cluster.”
Assume that the four T 1300 nodes in Figure 1 have the following NSIP addresses:
T1300-40-2: 10.102.29.70
T1300-40-3: 10.102.29.80
T1300-40-4: 10.102.29.90
T he cluster will be managed through the cluster IP (CLIP) address, which is assumed to be 10.78.16.61.
To begin configuring the cluster shown in Figure 1, log on to the first appliance that you want to add to the cluster (for
example, T 1300-40-1) and do the following.
2. After the appliance restarts, connect to the Cluster IP (CLIP) address and add the rest of the nodes to the cluster:
3. Connect to the NSIP address of each of the newly added nodes and join the cluster:
4. After the nodes restart, proceed with backplane configuration. On the cluster IP address, enter the following commands
to create an LACP channel for the backplane link of each cluster node:
5. Similarly, configure dynamic LA and VPC on the backplane switches. Make sure the MT U of the backplane switch
interfaces is at least 1578 bytes.
8. Check the cluster status and verify that the cluster is operational:
After you have formed the NetScaler cluster, deploy Cluster Link Aggregation (CLAG) to distribute traffic across cluster
nodes. A single CLAG link will handle both client and server traffic.
On the cluster IP address, execute the following commands to create the Cluster Link Aggregation (CLAG) group shown in
Figure 1:
For more information about cluster link aggregation, see the following topics:
Because we will be using MAC-based forwarding (MBF), configure a linkset and bind it to the CLAG group as follows:
Configuring Linksets
Using Cluster LA Channel with Linksets
We will be using striped IP configuration, which means that IP addresses are active on all nodes (default setting). See
“Striped, Partially Striped, and Spotted Configurations” for more information about this topic.
1. From the CLIP address, enable BGP and dynamic routing on ingress and egress IP addresses:
root@ns# vtysh
ns(config-router)# exit
ns(config)# exit
3. Configure the egress-side BGP peer to advertise the default route to the NetScaler cluster. For example:
network 0.0.0.0/0
5. From vtysh verify that configuration is propagated to all cluster nodes, by entering:
6. Finally, log on to NSIP address of each cluster node and verify routes advertised from BGP peer:
Citrix Systems has developed a new congestion-control algorithm, NILE, a TCP optimization algorithm designed for high-
speed networks such as LT E, LT E advanced and 3G. Nile addresses unique challenges caused by fading, random or
congestive losses, link layer retransmissions and carrier aggregation.
T he NILE algorithm:
T he telecom service providers can use the NILE algorithm in their TCP infrastructure to:
Optimize mobile and long-distance networks— T he NILE algorithm achieves higher throughput compared to standard
T CP. T his feature is especially important for mobile and long-distance networks.
Decrease application perceived latency and enhance subscriber experience— T he Nile algorithm uses packet loss
information to determine whether the transmission-window size should be increased or decreased, and uses queuing
delay information to determine the size of the increment or decrement. T his dynamic setting of transmission-window
size decreases the application latency on the network.
1. Navigate to Syst em > P rof iles > T CP P rof iles and click T CP prof iles .
2. From the T CP F lavor drop-down list, select NILE .
Example
TCP Fast Recovery mechanisms reduce web latency caused by packet losses. T he new Proportional Rate Recovery (PRR)
algorithm is a fast recovery algorithm that evaluates TCP data during a loss recovery. It is patterned after Rate-Halving, by
using the fraction that is appropriate for the target window chosen by the congestion control algorithm. It minimizes
window adjustment, and the actual window size at the end of recovery is close to the Slow-Start threshold (ssthresh).
TCP Fast Open (T FO) is a TCP mechanism that enables speedy and safe data exchange between a client and a server during
TCP’s initial handshake. T his feature is available as a TCP option in the TCP profile bound to a virtual server of a NetScaler
appliance. T FO uses a TCP Fast Open Cookie (a security cookie) that the NetScaler appliance generates to validate and
authenticate the client initiating a T FO connection to the virtual server. By using the T FO mechanism, you can reduce an
application's network latency by the time required for one full round trip, which significantly reduces the delay experienced
in short TCP transfers.
How T F O works
When a client tries to establish a T FO connection, it includes a TCP Fast Open Cookie with the initial SYN segment to
authenticate itself. If authentication is successful, the virtual server on the NetScaler appliance can include data in the SYN-
ACK segment even though it has not received the final ACK segment of the three-way handshake. T his saves up to one full
round-trip compared to a normal TCP connection, which requires a three-way handshake before any data can be
exchanged.
A client and a backend server perform the following steps to establish a T FO connection and exchange data securely
during the initial TCP handshake.
1. If the client does not have a T CP Fast Open Cookie to authenticate itself, it sends a Fast Open Cookie request in the
SYN packet to the virtual server on the NetScaler appliance.
2. If the T FO option is enabled in the T CP profile bound to the virtual server, the appliance generates a cookie (by
encrypting the client’s IP address under a secret key) and responds to the client with a SYN-ACK that includes the
generated Fast Open Cookie in a T CP option field.
3. T he client caches the cookie for future T FO connections to the same virtual server on the appliance.
4. When the client tries to establish a T FO connection to the same virtual server, it sends SYN that includes the cached
Fast Open Cookie (as a T CP option) along with HT T P data.
5. T he NetScaler appliance validates the cookie, and if the authentication is successful, the server accepts the data in the
SYN packet and acknowledges the event with a SYN-ACK, T FO Cookie, and HT T P Response.
Not e: If the client authentication fails, the server drops the data and acknowledges the event only with a SYN
indicating a session timeout.
1. On the server side, if the T FO option is enabled in a T CP profile bound to a service, the NetScaler appliance determines
whether the T CP Fast Open Cookie is present in the service to which it is trying to connect.
2. If the T CP Fast Open Cookie is not present, the appliance sends a cookie request in the SYN packet.
3. When the backend server sends the Cookie, the appliance stores the cookie in the server information cache.
4. If the appliance already has a cookie for the given destination IP pair, it replaces the old cookie with the new one.
5. If the cookie is available in the server information cache when the virtual server tries to reconnect to the same backend
server by using the same SNIP address, the appliance combines the data in SYN packet with the cookie and sends it to
Not e: If the server acknowledges the event with only a SYN segment, the NetScaler appliance immediately resends
the data packet after removing the SYN segment and the TCP options from the original packet.
At the command prompt, type one of the following commands to enable or disable T FO in a new or existing profile.
Examples
To set T CP Fast Open cookie tim eout value by using the com m and line
inter f ace
At the command prompt, type:
Example
To Configure the TCP Fast Cookie timeout value by using the NetScaler GUI
Navigate to Configurat ion > Syst em > Set t ings > Change T CP Paramet ers and then Configure T CP Paramet ers
page to set the TCP Fast Open Cookie timeout value.
A new TCP profile parameter, hystart, enables the Hystart algorithm, which is a slow-start algorithm that dynamically
determines a safe point at which to terminate (ssthresh). It enables a transition to congestion avoidance without heavy
packet losses. T his new parameter is disabled by default.
If congestion is detected, Hystart enters a congestion avoidance phase. Enabling it gives you better throughput in high-
speed networks with high packet loss. T his algorithm helps maintain close to maximum bandwidth while processing
transactions. It can therefore improve throughput.
Examples
1. Navigate to Conf igurat ion > Syst em > P rof iles > and click Edit to modify a T CP profile.
2. On the Conf igure T CP P rof ile page, select the Cubic Hyst art check box.
3. Click OK and then Done .
Optimization Techniques
TCP uses the following optimization techniques and methods for optimized flow controls.
Network traffic today is more diverse and bandwidth-intensive than ever before. With the increased traffic, the effect that
Quality of Service (QoS) has on TCP performance is significant. To enhance QoS, you can now configure AppQoE policies
with different TCP profiles for different classes of network traffic. T he AppQoE policy classifies a virtual server's traffic to
associate a TCP profile optimized for a particular type of traffic, such as 3G, 4G, LAN, or WAN.
To use this feature, create a policy action for each TCP profile, associate an action with AppQoE policies, and bind the
policies to the load balancing virtual servers.
Enabling AppQoE. Before configuring the T CP profile feature, you must enable the AppQoE feature.
Adding AppQoE Action. After enabling the AppQoE feature, configure an AppQoE action with a T CP profile.
Configuring AppQoE based T CP Profile Selection. T o implement T CP profile selection for different classes of traffic, you
must configure AppQoE policies with which your NetScaler ADC can distinguish the connections and bind the correct
At the command prompt, type the following commands to enable the feature and verify that it is enabled:
At the command prompt, type the following AppQoE action command with tcpprofiletobind option.
add appqoe action <name> [-priority <priority>] [-respondWith ( ACS | NS ) [<CustomFile>] [-altContentSvcName <string>] [-altContentPath
add ns tcpProfile tcp1 -WS ENABLED -SACK ENABLED -WSVal 8 -nagle ENABLED -maxBurst 30 -initialCwnd 16 -oooQSize 15000 -minRTO 500
bind lb vserver lb2 -policyName apppol1 -priority 1 -gotoPriorityExpression END -type REQUEST
bind cs vserver cs1 -policyName apppol1 -priority 1 -gotoPriorityExpression END -type REQUEST
6. Click Creat e .
TCP performance slows down when multiple packets are lost in one window of data. In such a scenario, a Selective
Acknowledgement (SACK) mechanism combined with a selective repeat retransmission policy overcomes this limitation. For
every incoming out-of-order packet, you must generate a SACK block.
If the out-of-order packet fits in the reassembly queue block, insert packet info in the block, and set the complete block
info as SACK-0. If an out-of-order packet does not fit into reassembly block, send the packet as SACK-0 and repeat the
earlier SACK blocks. If an out-of-order packet is a duplicate and packet info is set as SACK-0 then D-SACK the block.
Not e: A packet is considered as D-SACK if it is an acknowledged packet, or an out of order packet which is already
received.
A NetScaler appliance can handle client reneging during SACK based recovery.
In a non-endpoint mode, when you send DUPACKS, if SACK blocks are missing for few out of order packets, triggers
additional retransmissions from the server.
T he following SNMP ids have been added to a NetScaler appliance to track number of connections bypassed TCP
optimization due to overload.
Note
If you are interested in using CQA Reporting and Adaptive TCP, please contact Citrix sales team.
Mobile networks have unique characteristics that might affect TCP performance. By leveraging NetScaler Connection
Quality Analytics (CQA) and Adaptive TCP optimization techniques, mobile operators can analyze the overall network
behavior to provide an improved user experience and increased levels of subscriber satisfaction.
When a client sends a TCP request, CQA monitors and extracts a large amount of detailed TCP layer data during an active
connection. With the extracted data, CQA uses a heuristic learning algorithm to derive important characteristics of the
connection, for example, network type (2G, 3G or 4G), congestion level (None, Low, Medium, or High), and signal quality
(Excellent, Good, Fair or Poor) on a per-subscriber basis. NetScaler then stores the information in a subscriber store (so that
it can be available for the next TCP connections from the same subscriber) and exports the data to the AppFlow collectors.
T he stored information is as raw values in a composite format that defines the network type, congestion level, and signal
quality of the subscriber connection. T he detected characteristics can be used for other applications, for example, to
intelligently apply different TCP profiles for different network characteristics. For more information, see Adaptive TCP
topic.
Benefit
Enable mobile operators to:
Prerequisites
T he CQA feature works on Telco platforms with the purchase of a basic CBM license and CBM Premium license and for
other NetScaler platforms, the feature works with the purchase of a CNS Platinum license. Before you configure the TCP
optimization feature, your appliance must have a suitable license installed.
License status:
To configure CQA on a NetScaler appliance, you can perform the following tasks:
1. Enable CQA
2. Enable AppFlow Collector
3. Configure CQA Parameters
4. Verify CQA feature
5. Using CQA-based PI expressions
If you want the NetScaler appliance to extract TCP raw metric and derive CQA parameters, you must enable the CQA
feature and set adaptive TCP to ON. You must also enable the Appflow feature so that the appliance can send the derived
CQA data for network analysis.
To enable CQA
You must have at least one Appflow collector to be running in your appliance. At the command prompt, type the following
command:
For CQA to derive parameters such as network type, signal quality, and congestion level, you must configure CQA settings
on the appliance.
To configure CQA
set ns cqaparam [-harqretxdelay <positive_integer>] [-net1label <string>] [-minRTTNet1 <positive_integer>][-lr1coeflist <string>] [-lr1probthresh
Note
For proper configuration of CQA parameters, please contact Citrix Customer Support.
Where,
net1csqscale is the signal quality score limit, such as Excellent, Good, or Fair. Maximum Length: 63
net1cclscale is the congestion level limit such as None, Low, or Medium. Maximum Length: 63
To verify if the CQA parameters are derived during an active TCP action, execute the following command. Not e : You can
execute the command only if the TCP connection is open and active.
RttMax(ms) : 559
AdaptiveTCP : N/A
T he NetScaler policy infrastructure is enhanced to use the derived CQA parameters (stored in subscriber store) for string
matching operations.
NET WORK_T YPE: String value that matches the detected network type configured through the cqaparam command
interface.
SIGNAL_QUALIT Y: Integer value ranging from 0 to 100 and matching the CQA signal quality parameter stored in the
subscriber store (lower values indicate better signal quality).
CONGEST ION_LEVEL: Integer value ranging from 0 to 100 and matching CQA raw value of congestion level parameter
stored in the subscriber store (lower values indicate lower congestion).
Below are sample PI expressions with CQA parameters such as network type, congestion level, and signal quality, evaluates
an incoming traffic of network type 2G, exhibiting good or excellent signal quality with a high congestion level:
1. Log on to NetScaler and navigate to Conf igurat ion > Syst em > Set t ings .
2. In the details pane, click Conf igure Advanced f eat ures link under Set t ings .
3. In Conf igure Advanced F eat ures page, select CQA and Appf low checkbox.
1. Log on to NetScaler and navigate to Conf igurat ion > Syst em > Appf low .
2. In the details pane, click Change Appf low Set t ing under Set t ings .
3. In the Conf igure Appf low Set t ings page, select CQA Report ing checkbox.
4. Click OK and Close .
As subscribers in a telco network increase in an unprecedented rate, it is important to provide a quality user experience to
each subscriber. To achieve this, NetScaler uses an advanced optimization technique called Adaptive TCP. T he technique
optimizes traffic by independently adapting different TCP profiles for each subscriber based on the information stored in a
subscriber (UX) store. T he UX store contains subscriber’s details (such as network type, signal quality, and congestion level) in
a composite format. When a client sends a TCP request, the appliance queries the store for the subscriber information and
applies a suitable TCP optimization based on subscriber’s network conditions. T he appliance does this by enabling Adaptive
TCP feature on a NetScaler TCP profile.
Benefit
Using Adaptive TCP optimization technique, a mobile operator can:
Extract advanced and detailed insight of network conditions experienced by a mobile subscriber.
Automatically adapt traffic management actions of NetScaler based on the current network conditions.
Prerequisites
T he Adaptive TCP feature works only on telco traffic management platforms (such as NetScaler T 1000 series and VPX-T
platforms) with a Premium license. T he VPX-T software and T 1000 hardware appliances are designed to meet the needs of
telco mobile operators and service providers. Before you configure the TCP optimization feature, your appliance must have
the following license files installed:
1. Adaptive T CP
2. Connection Quality Metrics
License status:
If you want the appliance to optimize TCP traffic, you must enable CQA, AppFlow, and Adaptive TCP features.
A NetScaler appliance uses a TCP load balancing virtual servers for optimizing an adaptive TCP traffic.
A NetScaler appliance uses a HT T P load balancing virtual servers for optimizing HT T P traffic.
You can configure a normal TCP profile to apply Adaptive TCP optimization. T his can done by either adding a new profile or
modifying an existing one.
Note
Before you configure TCP profiles to apply Adaptive TCP optimization, please contact Citrix Customer Support.
To configure a T CP profile
To configuring AppQoE policy-based optimization, you must complete the following tasks:
To bind an AppQoE policy t o a load balancing virt ual server of HT T P and T CP t raf fic
bind lb vserver <name> -policyName <string> -priority <positive_integer> -gotoPriorityExpression <expression> -type (REQUEST | RESPON
bind lb vserver httplb -policyName appqoepol-adtcp -priority 1 -gotoPriorityExpression END -type REQUEST
1. In the navigation pane, expand Syst em, and then click Set t ings .
2. On the Set t ings page, click the Conf igure Advanced F eat ures link.
3. On the Conf igure Advanced F eat ures page, select the CQA and Adapt ive T CP check box.
4. Click OK , and then click Close .
1. Sign in to the NetScaler appliance and navigate to the T raf f ic Management > Load Balancing > Virt ual
Servers page.
2. In the details pane, click Add .
3. On the Load Balancing Virt ual Server screen, set the following parameters:
1. Name . Name of the load balancing virtual server.
2. P rot ocol. Select protocol type as T CP.
3. IP Address T ype . IP address type: IPv4 or IPv6.
4. IP Address . IPv4 or IPv6 address assigned to the virtual server.
5. P ort . Port number of the virtual server.
4. Click OK to continue with configuration of other, optional, parameters. For more information, see Creating a Virtual
Server.
5. Click Creat e and Close .
1. Sign in to the NetScaler appliance and navigate to the T raf f ic Management > Load Balancing > Virt ual
Servers page.
2. In the details pane, click Add .
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > Syst em > P rof iles page.
2. In the Det ails pane, click T CP P rof iles tab.
3. In the Conf igure T CP P rof iles page, select Apply Adapt ive T CP checkbox.
4. Click OK and Close.
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > T raf f ic Management > Virt ual Servers .
2. In the details page, select a virtual server profile for T CP traffic and click Edit .
3. In the Load Balancing Virt ual Server page, go to P rof iles section and click pencil icon.
4. Apply the adaptive T CP profile to the virtual server.
5. Click OK and Done .
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > T raf f ic Management > Virt ual Servers .
2. In the details page, select a virtual server profile for HT T P traffic and click Edit .
3. In the Load Balancing Virt ual Server page, go to P rof iles section and click pencil icon.
4. Apply the adaptive T CP profile to the HT T P virtual server.
5. Click OK and Done .
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > AppExpert > AppQoE > Act ions.
2. In t he det ails pane, click Add t o creat e an act ion.
3. In the Creat e AppQoE Act ion screen, type or select values for the parameters. T he contents of the dialog box
correspond to the parameters described in "Parameters for configuring the AppQoE Action" as follows (asterisk indicates
a required parameter):
1. Name— name
2. Action type— PRIORIT Y_QUEUING
3. T CP Profile— Apply a T CP profile by adding a new one or selecting an existing one.
4. Priority— HIGH
5. Policy Queue Depth— 0
6. Queue Depth— 0
7. Click Creat e and OK .
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > AppExpert > AppQoE > P olicy.
1. Log on to NetScaler appliance and navigate to the Conf igurat ion > T raf f ic Management > Load Balancing >
Virt ual Servers.
2. In t he det ails pane, select a load balancing virtual server of type HT T P or T CP and click Edit .
3. In the Load Balancing Virt ual Server page, go to P olicies section and click the + icon.
4. In the P olicies slider page, do the following:
1. Choose policy. Policy name.
2. Choose type. Policy type as request or response.
5. Click Cont inue to close the slider page and go to the main page.
6. Click Done .
T he TCP Speed Reporting is a NetScaler feature which extracts a rich set of TCP-level statistics, as a measure of TCP
download and upload performance, and is utilized in TCP Insight reports of the NetScaler MAS. To achieve this, NetScaler
monitors each TCP connection, locates packet bursts on an idle time-out basis and reports key metrics (such as byte count,
retransmitted byte count, an duration) for the identified maximum burst. In addition to this, the TCP raw metrics such as
RT T, BIF, receive window and so forth are also measured based on the optimization type (endpoint or transparent) that you
configure. T he TCP Speed Reporting feature is enabled by default, supports both TCP and HT T P vServers and depends on
Appflow/ULFD reporting infrastructure. For more information, see Analytics and Reporting topic.
All troubleshooting and escalation queries require a recent NetScaler techsupport bundle, which captures current
configuration, firmware version installed, log files, outstanding cores, and others.
...
/var/tmp/support/collector_P_192.168.121.117_18Jun2015_09_53
...
After a techsupport bundle has been generated, it might be copied using SCP.
NetScaler TCP optimization issues normally require NetScaler traces to troubleshoot properly. Note that one should try to
capture traces under similar conditions, i.e. on the same cell, during the same time of day, using the same user equipment
and application, and others.
T he start nstrace and stop nstrace commands might be used to capture traces:
After a NetScaler trace has been captured, it might be viewed with Wireshark 1.12 or later. Verify that the captured traces
include the appropriate NetScaler Packet Trace headers, as shown in the screen capture below:
T he additional debug headers are also visible per the illustration below:
When the issue is related to TCP optimization and it can be reproduced or it's on-going, it is best to get also
the connection table when the issue occurs from the primary T 1 node.
To get the table you shall need to switch to the BSD shell and run the following command:
...
Note
T he command might be executed for a longer time and management CPU might be stressed at that time (depends on the number
of connection table entries), but it’s not service affecting.
Important
Before using *any nsapimgr* knob, consult with Citrix Customer Support.
T he following is a list of different idle connection timeouts that can be set on NetScaler T 1 virtual servers and services. Idle
timeout set for client or server connections at the vserver or service level are applicable only for the connections in TCP
ESTABLISHED state and are idle.
Load Balancing virtual server cltT imeout parameter specifies the time in seconds that a connection from a client to a
Load Balancing virtual server must be idle, before the appliance closes the connection.
Service svrT imeout parameter specifies the time in seconds that a connection from the appliance to a service or server
must be idle, before the appliance closes the connection.
Service cltT imeout parameter specifies the time in seconds that a connection from a client to a service must be idle,
before the appliance closes the connection.
When a service is bound to a Load Balancing virtual server, then the cltT imeout for the Load Balancing virtual server takes
precedence, and the service cltT imeout for service is ignored.
In case of there is not service bound to Load Balancing virtual server, global idle timeout, namely tcpServer, is used for server
side connections. It can be configured as follows:
When half-close timeout is triggered, connection is moved to zombie state. When zombie timeout expires, zombie cleanup
kicks in and T 1 sends RST on both client and server side for given connection by default.
Zombie timeout: Interval at which the zombie cleanup process must run to clean up inactive T CP connections. Default
timeout value is 120s and can be configured between 1s and 600s.
A NetScaler T 1 appliance defends against SYN flood attacks by using SYN cookies instead of maintaining half-open
connections on the system memory stack. T he appliance sends a cookie to each client that requests a TCP connection, but
it does not maintain the states of half-open connections. Instead, the appliance allocates system memory for a
connection only upon receiving the final ACK packet, or, for HT T P traffic, upon receiving an HT T P request. T his prevents
SYN attacks and allows normal TCP communications with legitimate clients to continue uninterrupted. Specific function is
enabled by default without option to disable.
However, there is caveat as standard SYN cookies limit connections to the use of only eight Maximum Segment Size (MSS)
values. If connection MMS does not match with any predefined value, it will pick up the next available lower value towards
both client and server side.
T he predefined TCP Maximum Segment Size (MSS) values are the following and can be configured through a new nsapimgr
knob.
Need not contain Jumbo-Frame support. Even though by default 8 values are reserved in the MSS table for jumbo
frames, the table settings can be modified to include standard Ethernet-sized frames only.
Should have 16 values
Should have values in descending order
Should include 128 as the last value
To display the current MSS table in a NetScaler appliance, type the following command.
>shell
#nsapimgr -d mss_table
#nsapimgr -d mss_table
MSS table
{9176,9156,8192,7168,6144,4196,3072,2048,1460,1440,1330,1212,956,536,384,128}
Done.
# nsapimgr -d mss_table
MSS table
{9176,9156,8192,7168,6144,4196,3072,2048,1460,1400,1330,1212,956,536,384,128}
Done.
# nsapimgr -d mss_table
MSS table
{1460,1440,1420,1400,1380,1360,1340,1320,1300,1280,1260,1212,956,536,384,128}
Done.
To make this change permanent even after the NetScaler appliance restarts, include the command "#nsapimgr -ys
mss_table=<16 comma seperated values>" in the "/nsconfig/rc.netscaler" file. If the "rc.netscaler" file doesn't exist, create it
under the "/nsconfig" folder, and then append the command.
A NetScaler Packet Processing Engine (PPE) starts bypassing connections from TCP optimization if the memory in use by
that one PPE is more than a specified high watermark value. If a PPE memory utilization goes above ~2.6GB, then it starts
bypassing *any new* connections from optimization. T he existing connections (ones admitted for optimization previously)
continues getting optimization. T his watermark value has been purposefully selected and is not recommended for tuning.
Note
If you believe that there is a good reason to change that watermark value, contact Customer Support.
If the NetScaler appliance receives a SYN for a destination for which the state is unknown, the appliance first checks the
reachability of the server and then acknowledges the client. T his probing mechanism enables clients with dual IP stacks to
discover the reachability of dual-stack internet servers. If the client discovers that both IPv6 and IPv4 access are available, it
establishes a connection to the server that responds more quickly, and resets the other. For the connection for the
NetScaler appliance receives a reset, it will reset the corresponding server side connection.
Getting Started
Licensing
Configuring Video Optimization over T CP
Configuring Video Optimization over UDP
A NetScaler appliance has unique capabilities to detect incoming video traffic and selectively optimize ABR videos.
Also, the appliance uses the following support domains for detecting video traffic over TCP and QUIC protocols.
Unencrypted ABR videos over T CP. Appliance detects all standard compliant video streaming web sites. T he appliance
detects ABR sessions by inspecting the response video payload header, URL, and HT T P headers.
Encrypted ABR video over T CP. Appliance detects ABR sessions using a generic and heuristic algorithm based on domain,
SSL header and traffic patterns. Using this, the appliance has a built-in support to detect top video web sites, with 95
percent accuracy and we continue to add support for new video types. NetScaler also has a program to provide
additional verification for top encrypted ABR sites for a region or country to ensure network coverage.
Encrypted ABR videos over QUIC. T he appliance detects ABR sessions for QUIC based video provider, such as YouT ube.
T he detection algorithm is on the basis of a heuristic leveraging the QUIC headers and domain. NetScaler will continue to
add support for newer video sites using QUIC.
Benefit s
Optimizing the ABR video traffic can provide the following benefits:
1. HT T P or HT T PS traffic that the appliance receives over T CP is sent to the corresponding load balancing virtual server.
2. T he built-in detection policies bound to the virtual server combined with other proprietary detection algorithms evaluate
the traffic.
3. T he policies use a set of built-in video detection signatures to detect the video type. T he policy that matches traffic
applies an action that categorizes the video type as one of the following:
1. Clear-text PD
2. Clear-text ABR
3. Encrypted ABR
4. Other
4. T he optimization policies bound to the same virtual server evaluate the traffic and determine the optimization bit rate
to apply to the traffic.
5. T he optimization bit rate is applied if the traffic is either clear-text ABR or encrypted ABR.
A mobile service provider can improve the quality of experience (QoE) by setting the download speed for 2G, 3G, and 4G
NetScaler ABR optimization adapts dynamically to changing network conditions. It allows an initial burst rate of 1.3 times
the configured pacing rate for 15 seconds. T he initial burst rate applies to the beginning of every optimized ABR video
session, even when multiple sessions use the same TCP connection or group of TCP connections.
T he appliance also supports recovery bursts in the event that the bit rate supported by the network drops below the
configured pacing rate. For example, if the effective bit rate drops at the 7th second and recovers at 15th second of the
initial burst, the appliance recovers the loss during the next burst cycle. By doing so, the appliance dynamically optimizes the
network bandwidth for all subscribers so that the quality of video remains consistent per pixel.
Note: When a recovery burst happens during an initial burst, the pacing bit rate must not exceed the maximum recovery-
burst and initial-burst rates (you must not add the Recovery Burst factor on top of the Initial Burst factor). Otherwise, it
might be so fast that the media player shifts to a higher quality mode. However, if necessary, you can extend the duration
of the Initial Burst to compensate the unused bandwidth.
To estimate the savings from video optimization, the NetScaler appliance implements random sampling. With this technique,
the appliance randomly selects a configurable percentage of the detected video traffic (the random sampling parameter is
an integer number ranging from 0 to 100, so less than 1 percent is not possible). T hese randomly selected and non-
optimized transactions (and sessions) become a reference group, and they are identified in the transaction logs (along with
other characteristics, such as byte size and timer fields. T he characteristics of the optimized sessions are also logged, and
the reporting engine compares statistics of the optimized and reference groups to estimate the savings from optimization
(including the savings from ABR Optimization).
1. A valid license file should be installed on the NetScaler appliance. The license should support at least as many Gbps as the expected maximum Gi-LAN
throughput.
License files should be copied through an SCP client to the /nsconfig/license of the appliance, as shown in the screen
capture below.
CNS_V3000_SERVER_PLT_Retail.lic ssl
2. Do a warm restart to apply for the new license, as shown in the screen capture below.
Done
3. After the restart completes, verify that the license has been properly applied, by using the show license CLI.
In the example below a premium license with premium edition has been successfully installed.
License status:
...
To configure video optimization on a NetScaler appliance, you perform the following tasks:
You must also enable the load balancing feature, and if you want to use video optimization for HT T PS traffic you must
enable the SSL feature.
Note
If you want to monitor the video optimization performance and video insight reports you must enable the AppFlow feature and then
access the Video Analytics feature on NetScaler MAS. For more information, see Video Insight documentation.
A NetScaler appliance uses different virtual servers for detecting and optimizing the different types of incoming video
traffic. T he appliance supports the following types of virtual servers for TCP traffic.
HT T P Load Balancing virt ual server. For detecting HT T P video traffic, the appliance uses an HT T P load balancing
virtual server. It manages HT T P video requests that the appliance receives from clients.
SSL-Bridge Load Balancing virt ual server. T o detect encrypted video traffic, you must configure an SSL bridge virtual
To add an HT T P Load Balancing virt ual server f or det ect ing HT T P video t raf fic
To add an SSL Bridge virt ual server f or det ect ing HT T P S video t raf fic
To detect video traffic over an HT T P connection, you must bind all the built-in detection policies to a load balancing virtual
server. You must bind the policies to either request-time or response-time processing, depending on the policy type.
To bind det ect ion policies f or dif f erent video t ypes t o an HT T P load balancing virt ual server
At the command prompt, type the appropriate command for each type. T he available commands are:
bind lb vserver <name> -policyName ns_videoopt_http_abr_netflix -priorit y <integer> -t ype (REQUEST | RESPONSE)
bind lb vserver <name> -policyName ns_videoopt_http_abr_netflix2 -priorit y <integer> -t ype (REQUEST | RESPONSE)
bind lb vserver <name> -policyName ns_videoopt_http_abr_generic -priorit y <integer> -t ype (REQUEST | RESPONSE)
To detect video traffic over HT T P, you must bind the body content detection policy to the load balancing virtual server. You
can use the following command:
bind lb vserver <name> -policyName ns_videoopt _ht t p_body_det ect ion -priorit y <integer> -t ype (REQUEST |
RESP ONSE)
To bind a det ect ion policy t o an SSL bridge load balancing virt ual server
At the command prompt, type the appropriate command for each type. T he available commands are:
bind lb vserver <name> -policyName ns_videoopt _ht t ps_abr_yout ube -priorit y <positive_integer> -type (REQUEST |
RESP ONSE )
bind lb vserver <name> -policyName ns_videoopt _ht t ps_abr_generic -priorit y <positive_integer> -t ype (REQUEST |
RESP ONSE )
To optimize ABR traffic, you have to configure optimization policies and the associated actions. You then bind the policies
to the same load balancing virtual servers to which you bound the detection policies. For each policy, create the action first,
so that you can include it when you create the policy.
add videoopt imizat ion pacingact ion <action Name> -rat e <integer> [-comment <string>]
Where the rat e parameter specifies the rate in Kbps at which to send the traffic (the pacing rate).
add videoopt imizat ion pacingpolicy <name> -rule <expression> -act ion <string>
To optimize ABR video traffic over an HT T P connection, you must bind the optimization policies to a load balancing virtual
server to which the detection policies are bound.
To bind an opt imizat ion policy t o a Load Balancing virt ual server
bind lb vserver <name> -policyName <policy_name> -priorit y <positive_integer> -t ype (REQUEST | RESP ONSE )
To optimize ABR video traffic over an HT T PS connection, you must bind the optimization policies to the SSL Bridge virtual
server to which the built-in detection policies are bound.
To bind an opt imizat ion policy t o SSL Bridge virt ual server f or pacing encrypt ed t raf fic
T he NetScaler CLI enables you to set the video optimization pacing parameters, such as random sampling percentage.
1. In the navigation pane, expand Syst em, and then click Set t ings .
2. On the Set t ings page, click the Conf igure Advanced F eat ures link.
3. On the Conf igure Advanced F eat ures page, select the Video Opt imizat ion check box.
1. Sign in to the NetScaler appliance and navigate to the T raf f ic Management > Load Balancing > Virt ual Servers
page.
2. In the details pane, click Add .
3. On the Load Balancing Virtual Server screen, set the following parameters:
1. Name . Name of the load balancing virtual server.
2. P rot ocol. Select protocol type as HT T P
3. IP Address T ype . IP address type: IPv4 or IPv6.
4. IP Address . IPv4 or IPv6 address assigned to the virtual server.
5. P ort . Port number of the virtual server.
4. Click OK to continue with configuration of other, optional, parameters. For more information, see Creating a Virtual
Server.
5. Click Creat e and Close .
1. Sign in to the NetScaler appliance and navigate to the T raf f ic Management > Load Balancing > Virt ual Servers
page.
2. In the details pane, click Add .
3. On the Load Balancing Virt ual Server screen, set the following parameters:
1. Name . Name of the load balancing virtual server.
2. P rot ocol. Select protocol type as SSL-bridge.
3. IP Address T ype . IP address type: IPv4 or IPv6.
4. IP Address . IPv4 or IPv6 address assigned to the virtual server.
5. P ort . Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more information, see Creating a Virtual
Server.
5. Click Creat e and then Close .
To bind a built -in det ect ion policy t o a load balancing virt ual server
1. Sign in to the NetScaler appliance and navigate to T raf f ic Management > Load Balancing > Virt ual Servers screen.
2. In the details pane, select the load balancing virtual server and click Edit .
1. In the Advanced Set t ing section, click P olicies .
2. In the P olicies section, click the + icon to access the P olicies slider.
3. In the P olicies section, set the following parameters.
4. Choose Policy. Select a video optimization detection policy from the drop-down list.
5. Choose T ype. Select the policy type as Request.
6. Click Cont inue .
3. Select the video detection policy from the list and click Close .
To bind a built -in det ect ion policy t o a SSL-bridge load balancing virt ual server
1. Log on to the NetScaler appliance and navigate to the T raf f ic Management > Load Balancing > Virt ual Servers
screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit .
1. Log on to the NetScaler appliance and navigate to Conf igurat ion > Opt imizat ion > Video Opt imizat ion > P acing >
Act ions .
2. In the details pane, click Add .
3. On the Creat e Video Opt imizat ion P acing Act ion page, set the following parameters.
1. Name . Name of the optimization action.
2. ABR Opt imizat ion Rat e (Kbps). Pacing rate at which to send the ABR video traffic. T he default rate for ABR
optimization is 1000 Kbps. T he minimum value is 1, and the maximum value is 2147483647.
3. Comment . A short description of the action.
4. Click Creat e and Close .
1. Log on to the NetScaler appliance and navigate to Conf igurat ion > Opt imizat ion > Video Opt imizat ion > P acing >
P olicies .
2. In the details pane, click Add .
3. On the Creat e Video Opt imizat ion P acing P olicy page, set the following parameters.
1. Name . Name of the optimization policy
2. Expression . Custom regrex expressions that implement the policy.
3. Act ion . Optimization action associated with the policy to handle the incoming video traffic.
4. UNDEF Act ion. Undefined event if the incoming request does not match the optimization policy.
5. Comment . A short description of the policy.
6. Log Act ion. Select the audit log action that creates the desired log messages.
4. Click Creat e , and then click Close.
1. Log on to the NetScaler appliance and navigate to Conf igurat ion > Opt imizat ion > Video Opt imizat ion.
2. In the Video Opt imizat ion page, click Change Video Opt imizat ion Set t ings link.
3. In the Video Opt imizat ion Set t ings page, set the following parameter.
1. Random Sampling P ercent age (% ). Percentage of packets selected for random sampling.
4. Click OK and Close .
To bind a video opt imizat ion policy t o an HT T P load balancing virt ual server
1. Log on to the NetScaler appliance and navigate to Conf igurat ion > Opt imizat ion > Video Opt imizat ion .
2. On the Video Opt imizat ion page, click the Video Opt imizat ion P acing P olicy Manager link.
3. Set the following parameters.
1. Bind P oint . T he point at which to apply the optimization policy during request or response processing.
2. Connect ion T ype . Connection type as Request or Response.
To bind a video opt imizat ion policy t o an SSL-bridge load balancing virt ual server
1. Log on to the NetScaler appliance and navigate to Conf igurat ion > Opt imizat ion > Video Opt imizat ion .
2. On the Video Opt imizat ion page, click the Video Opt imizat ion P acing P olicy Manager link.
3. On the Video Opt imizat ion P olicy Manager page, set the following parameters.
1. Bind Point. T he point at which to apply the optimization policy during request/response processing.
2. Connection T ype. Connection type as Request or Response.
3. Virtual Server. T he SSL-bridge load balancing virtual server to which to bind the policy.
4. Click Cont inue .
5. In the Bind P oint section, do one of the following:
1. Select a policy binding from the list.
2. Click Add Binding to access the P olicies Binding slider.
1. Select an existing policy or add a new policy.
2. Enter binding details and click Bind .
6. Click Close .
To configure video optimization for QUIC video traffic over UDP, you must perform the following tasks:
Note
If you want to use video optimization for QUIC traffic, you must enable the load balancing and AppFlow features.
Note
Currently, dynamic routing is not supported.
Example COPY
Example COPY
add lb vserver vs-quic QUIC * 443 -persistenceType NONE -m MAC -cltTimeout 120
To bind a web service to load balancing virtual server for QUIC video traffic
Example COPY
Where, the rate parameter specifies the rate in Kbps at which to send the traffic (the pacing rate).
Example COPY
Example COPY
To optimize QUIC video traffic over a UDP connection, you must bind the optimization policies to a QUIC load balancing
virtual server.
Note
T he pacing policies must be bound to a QUIC load balancing virtual server only at request time.
To configure the feature on the appliance through the NetScaler GUI, you must perform the following tasks:
1. Log on to the NetScaler appliance and navigate to the Traf f ic Management > Load Balancing > Servers screen.
2. In the details pane, click Add.
3. On the Create Server page, set the following parameters:
1. Name. Name of the QUIC server.
2. IP address. IP address of the QUIC server
3. T raffic Domain. Domain name of the server.
4. Enabling after creating. Initial state of the server.
5. Comments. Brief information about the server.
4. Click Create.
1. Log on to the NetScaler appliance and navigate to the Traf f ic Management > Load Balancing > Services screen.
2. In the details pane, click Add.
3. On the Load Balancing Service page, set the following parameters:
1. Service Name. Name of the QUIC service.
2. IP address. IP address assigned to the QUIC service.
1. Log on to the NetScaler appliance and navigate to the Traf f ic Management > Load Balancing > Virtual Servers
screen.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server page, set the following parameters:
1. Name. Name of the load balancing virtual server.
2. Protocol. T he protocol used by the service to send QUIC requests.
3. IP Address T ype. IP address type: IPv4 or IPv6.
4. IP Address. IP 4 or IP6 IP address assigned to the virtual server.
5. Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more information, see Creating a Virtual
Server.
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click Services and Service Groups to access the Load Balancing Virtual Server Service Binding screen.
3. Select a QUIC based web service and click Bind.
4. Click Done.
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click Services and Service Groups to access the Load Balancing Virtual Server Service Binding screen.
3. Select a QUIC based web service and click Bind.
4. Click Done.
1. Log on to the NetScaler appliance and navigate to Conf iguration > Optimization > Video Optimization > Pacing >
Actions.
2. In the details pane, click Add.
3. On the Create Video Optimization Pacing Action page, set the following parameters.
1. Name. Name of the optimization action.
2. ABR Optimization Rate (Kbps). Pacing rate at which to send the ABR video traffic. T he default rate for ABR
optimization is 1000 Kbps. T he minimum value is 1, and the maximum value is 2147483647.
3. Comment. A short description of the action.
4. Click Create and Close.
1. Log on to the NetScaler appliance and navigate to Conf iguration > Optimization > Video Optimization > Pacing >
Policies.
2. In the details pane, click Add.
3. On the Create Video Optimization Pacing Policy page, set the following parameters.
1. Log on to the NetScaler appliance and navigate to Conf iguration > Optimization > Video Optimization.
2. On the Video Optimization page, click the Video Optimization Pacing Policy Manager link.
3. On the Video Optimization Policy Manager page, set the following parameters.
1. Bind Point. T he point at which to apply the optimization policy during request processing. Note: T he pacing policies
must be bound to a QUIC load balancing virtual server only at request time.
2. Connection T ype. Connection type as Request or Response.
3. Virtual Server. T he load balancing virtual server to which to bind the policy.
4. Click Continue.
5. In the Bind Point section, do one of the following:
1. Select a policy from the list.
2. Click Add Binding to access the Policies Binding slider.
1. Select an existing policy or add a new policy.
2. Enter binding details and click Bind.
6. Click Close.
As an administrator, you can configure a URL filtering policy by using either the URL Categorization feature or the URL List
feature.
URL List. Controls access to blacklisted websites and web pages by denying access to URLs that are in a URL set imported
into the appliance.
URL Categorization. Controls access to websites and web pages by filtering traffic on the basis of a predefined list of
categories.
As an administrator, you must import the URL List into the NetScaler appliance. T his imported list is internally stored as a Policy data set called a URL Set . T he appliance then applies a unique fast URL
matching algorithm to the incoming URL requests. If the incoming URL request matches an entry in the set, the appliance applies the associated policy action to control access.
A NetScaler appliance supports two types of URL lists: Custom (with or without URL metadata) and IWF (Internet Watch Foundation).
Custom URL List . You can create a customized URL set of up to 1,000,000 URL entries and import it as a text file into your appliance. T he list can contain URLs with or without metadata (which could
be like a URL category). T he NetScaler platform automatically detects whether metadata is present. It also supports storing the imported lists securely. For more information, see URL Set.
IWF URL List. You can import an externally managed list maintained by the IWF. To access this list, you need special access credentials, and you have to use a secure procedure. NetScaler has built-in
support for the IWF list, making it simple to use.
You can host the URL list and configure the NetScaler appliance to periodically update the list without requiring manual intervention. Once the URL list is updated, the appliance can automatically
detect the metadata and the categories by using policy expressions to evaluate each incoming URL and then apply actions such as allow, block, redirect, or notify the user.
Expression Operation
<URL expression>.URLSET _MATCHES_ANY(<URLSET >) Evaluates to T RUE if the URL exactly matches any entry in the URL set.
T he GET _URLSET _METADATA() expression returns the associated metadata if the URL exactly matches any pattern within the URL set. An empty string is
<URL expression>.GET _URLSET _METADATA(<URLSET >)
returned if there is no match.
<URL expression>.GET _
Evaluates to T RUE if the matched metadata is equal to <METADATA>.
URLSET _METADATA(<URLSET >).EQ(<METADATA>)
<URLexpression>.
Evaluates to T RUE if the matched metadata is at the beginning of the category. T his pattern can be used to encode separate fields within metadata, but
GET _URLSET _METADATA(<URLSET >)
match only the 1s t field.
.T YPECAST _LIST _T (‘,’).GET (0).EQ(<CAT EGORY>)
HT T P.REQ.HOST NAME.APPEND(HT T P.REQ.URL) Joins the host and URL parameters, which can then be used as a <URL expression> for matching.
REDIRECT Responder Redirect the request to the URL specified as the target.
You must configure a DNS server if you import a URL Set from a hostname URL.
add dns nameServer ((<IP> [-local]) | <dnsVserverName>) [-state (ENABLED | DISABLED )] [-type <type>] [-dnsProfileName <string>]
Example COPY
To set up IWF URL list support, you need access credentials. T he IWF gives each member the unique access credentials required for setup. T he access credentials include a user name password.
Note
If the IWF changes the URL for importing a list, you can contact the NetScaler support team.
T he NetScaler appliance supports HT T P and HT T PS traffic. To configure a load balancing virtual server for HT T P traffic and bind URL list policies to the server, do the following:
add responder action <name> <type> (<target> | <htmlpage>) [-comment <string>] [-responseStatusCode <positive_integer>] [-reasonPhrase <string>]
Example COPY
add responder action act_iwf_url respondwith '"HTTP/1.1 451 Unavailable For Legal Reasons\r\n\r\nURL is IWF NOT authorized\n"'
add responder policy <name> <rule> <action> [<undefAction>] [-comment <string>] [-logAction <string>] [-appflowAction <string>]
Example COPY
Example COPY
Example COPY
T he NetScaler appliance supports HT T P and HT T PS traffic. To configure a SSL-bridge load balancing virtual server for HT T PS traffic and bind URL list policies to the server, do the following:
add videooptimization detectionpolicy <name> -rule <expression> -action <string> [-undefAction <string>] [-comment <string>] [-logAction <string>]
Example COPY
Example COPY
To bind URL List policy with SSL-bridge load balancing by using the NetScaler command interf ace
Example COPY
1. Navigate to the Traf f ic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
1. Name. Name of the load balancing virtual server.
2. Protocol. Choose protocol type as HT T P.
3. IP Address Type. IP addressable type.
To bind a URL List policy to the HTTP load balancing virtual server
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
5. In the Policies section, set the following parameters.
1. Choose Policy. Select a URL categorization policy from the drop-down list.
2. Choose T ype. Select the policy type as Request.
6. Click Continue.
7. Select the URL List policy from the list and click Close.
1. Log on to the NetScaler appliance and navigate to Conf iguration > Optimization > Video Optimization > Detection.
2. On the Detection page, click the Video Optimization Detection Policies link.
3. On the Video Optimization Detection Policies page, click Add.
4. On the Create Video Optimization Detection Policy page, set the following parameters.
1. Name. Name of the optimization policy
2. Expression. Configure policy using custom expressions.
3. Action. Optimization action associated with the policy to handle the incoming video traffic.
4. UNDEF Action. Undefined event if the incoming request does not match the optimization policy.
5. Comment. A short description of the policy.
6. Log Action. Select an audit log action that specifies the action to be performed for the log messages.
5. Click Create and Close.
1. Navigate to the Traf f ic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server screen, set the following parameters:
1. Name. Name of the load balancing virtual server.
2. Protocol. Select protocol type as SSL-bridge.
3. IP Address Type. IP address type: IPv4 or IPv6.
4. IP Address. IPv4 or IP6vIP address assigned to the virtual server.
5. Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters. For more information, see “Creating a Virtual Server” topic.
To bind a URL List Policy to the SSL-bridge load balancing virtual server
1. Navigate to the Traf f ic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
5. Set the following parameters.
1. Choose Policy. Select video detection policy from the drop-down list.
2. Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the video detection policy from the list and click Close.
1. T imestamp.
2. Log message type.
3. T he predefined log levels (Critical, Error, Notice, Warning, Informational, Debug, Alert, and Emergency).
4. Log message information, such as URL set name, policy action, URL.
To configure audit logging for URL List feature, you must complete the following tasks:
domain.com
yourdomain.com
Subdomain matching domain.com www.domain.com
wwwdomain.com
sub.one.domain.com
domain.com/example/bar/index.html
wwwdomaincom/example/bar/index.html
URL matching, exact path domain.com/example/bar/index.html www.domain.com/example/bar/index.html
domain.com/example/bar/index.html/one.jpg
s.domain.com/example/bar/index.html
domain.com/example/bar/index.html?key=value wwwdomaincom/example/bar/index.html
URL matching, exact path domain.com/example/bar/index.html
www.domain.com/example/bar/index.html? s.domain.com/example/bar/index.html domain.com/example/bar/index.html/one.jpg
domain.com/example/bar/
domain.com/example/bar/index.html
URL matching, subpath matching domain.com/example/bar/ wwwdomaincom/example/bar/index.html
www.domain.com/example/bar/index.html
domain.com/example/bar/index.html/one.jpg
For example, you might block access to dangerous sites, such as sites known to be infected with malware, and selectively
restrict access to content such as adult content or entertainment streaming media.
You can use the URL filtering feature to detect sites that violate safe internet usage mandates issued by the government
and implement policies to block these sites. Sites that host adult content, streaming media, or social networking identified
as unsafe for children or banned as illegal.
Prerequisites
T he feature works on Telco platforms with the purchase of a basic CBM license and CBM Premium license and for other
NetScaler platforms, the feature works with the purchase of a CNS Platinum license.
Note: In addition to a Basic CBM license and a CBM Premium license, the appliance must have a URL T hreat Intelligence
feature license with a subscription service for one year or 3 years. Before enabling and configuring the feature, you must
install the following licenses:
CBM_TXXX_SERVER_Retail.lic
CBM_TPRE_SERVER_Retail.lic
CNS_WEBF_SSERVER_Retail.lic
CNS_XXX_SERVER_PLT_Retail.lic
Returns a string identifying the object's category group. T his is a higher level grouping of categories, which is
<url_category>.
useful in operations that require less detailed information about the URL category.
GROUP
If the URL does not have a category, or if the URL is malformed, the returned value is “Uncategorized”.
<url_category>. Returns the reputation score as a number from 1 to 4, where 4 indicates the riskiest reputation.
REPUTAT ION If the category is “Uncategorized”, the reputation value is 2.
Policy to select requests for Search Engine URLs add responder policy p5 ‘CLIENT.SSL.DET ECT ED_DOMAIN.URL_CAT EGORIZE(4,0).
with a reputation score equal to 4. CAT EGORY.EQ(“Search Engine”)
REDIRECT Responder Redirect incoming request to the URL specified as the target.
Note
For encrypted traffic, the VideoOptimization policy includes actions that implement the URL Filtering actions.
To use the NetScaler command line configure URL categorization on a NetScaler appliance, do the following:
To set up the feature, you must enable the URL Categorization feature, configure the filtering parameters and set the
Example COPY
Example COPY
To configure the URL categorization feature for HT T P traffic, you must configure a loading balancing virtual server, add URL
categorization policies and bind the policies to the virtual server. By doing so, the virtual server receives the HT T P traffic and
based on policy evaluation, the system assigns a filtering action.
add responder action <name> <type> (<target> | <htmlpage>) [-comment <string>] [-responseStatusCode
<positive_integer>] [-reasonPhrase <string>]
Example COPY
add responder policy <name> <rule> <action> [<undefAction>] [-comment <string>] [-logAction <string>]
[-appflowAction <string>]
Example COPY
If a virtual server for HT T P traffic is not already configured, at the command prompt, type:
Example COPY
Example COPY
To configure the URL categorization feature for HT T PS traffic, you must configure a SSL-bride loading balancing virtual
server, add URL categorization policies and bind the policies to the SSL-bridge virtual server. By doing so, the server receives
the HT T PS traffic and based on policy evaluation, the system assigns a filtering action.
add videooptimization detectionpolicy <name> -rule <expression> -action <string> [-undefAction <string>] [-comment
<string>] [-logAction <string>]
Example COPY
Example COPY
Example COPY
1. Log on to the NetScaler appliance and navigate to Conf iguration > Optimization > Video Optimization > Detection.
2. On the Detection page, click the Video Optimization Detection Policies link.
3. On the Video Optimization Detection Policies page, click Add.
4. On the Create Video Optimization Detection Policy page, set the following parameters.
1. Name. Name of the optimization policy
2. Expression. Configure policy using custom expressions.
3. Action. Optimization action associated with the policy to handle the incoming video traffic.
4. UNDEF Action. Undefined event if the incoming request does not match the optimization policy.
5. Comment. A short description about the policy.
6. Log Action. Select an audit log action that specifies the action to be performed for the log messages.
5. Click Create and Close.
1. Navigate to the Traf f ic Management > Load Balancing > Virtual Servers page.
2. In the details pane, click Add.
3. On the Load Balancing Virtual Server page set the following parameters:
1. Name. Name of the load balancing virtual server.
2. Protocol. Choose protocol type as HT T P.
3. IP Address Type. IPv4 or IPv6.
4. IP Address. IPv4 or IPv6, VIP address assigned to the virtual server.
5. Port. Port number of the virtual server.
4. Click OK to continue with the configuration of other, optional, parameters.
5. Click Create and Close.
1. Navigate to the Traf f ic Management > Load Balancing > Virtual Servers page.
2. On the details pane, click Add.
3. On the Load Balancing Virtual Server page, set the following parameters:
1. Name. Name of the load balancing virtual server.
2. Protocol. Select protocol type as SSL-bridge.
3. IP Address Type. IP addressable type.
4. IP Address. IP 4 or IP6 IP address assigned to the virtual server.
5. Port. Port number of the virtual server.
4. Choose OK to continue configuration other optional parameters.
5. Click Create and then Close.
To bind a URL categorization policy to the HTTP load balancing virtual server
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers page.
2. On the details pane, select the load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click the + icon to access the Policies slider.
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers screen.
2. In the details pane, select the SSL-bridge load balancing virtual server and click Edit.
3. In the Advanced Setting section, click Policies.
4. In the Policies section, click + icon to access the Policies slider.
5. In the Policies section, set the following parameters.
1. Choose Policy. Select video detection policy from the drop-down list.
2. Choose Type. Select the policy type as Request.
6. Click Continue.
7. Select the video detection policy from the list and click Close.
Source IP address (the IP address of the client that made the request).
To configure audit logging for URL List feature, you must complete the following tasks:
For example, if a failure occurs when you initialize the URL Filtering SDK, the error message is stored in the following
messaging format.
Oct 3 15:43:40 <local0.err> ns URLFiltering[1349]: Error initializing NetStar SDK (SDK error=-1). (status=1).
T he NetScaler appliance stores the error messages under four different failure categories:
Download failure. If an error occurs when you try to download the categorization database.
Integration failure. If an error occurs when you integrate an update into the existing categorization database.
Initialization failure. If an error occurs when you initialize the URL Categorization feature, set categorization parameters,
or end a categorization service.
Retrieval failure. If an error occurs when the appliance retrieves the categorization details of the request.
Upon receiving an incoming URL request, the appliance retrieves the category and reputation score from the URL
categorization database. Based on the reputation score returned by the database, the appliance assigns a reputation
1 Clean site.
2 Unknown site.
4 Malicious site.
NetScaler Gateway. Provides the URL for user access, and provides security by authenticating the users.
NetScaler load balancing virtual server. Load balances the traffic for the Web Interface or StoreFront servers. You
can also deploy a load balancing virtual server in front of the XenApp/XenDesktop servers to load balance key
components such as XML Broker and Desktop Delivery Controller (DDC) server.
Web Interf ace or StoreFront or Web Interf ace on NetScaler. Provides the interface through which you can access
the applications.
Note: Web Interface on NetScaler (WIonNS) is a customization of the Web Interface product, hosted on the NetScaler
appliance.
Prerequisites
XenApp/XenDesktop servers are configured and available.
Web Interface, StoreFront, or Web Interface on NetScaler servers are configured and available.
You have a working knowledge of NetScaler Gateway, NetScaler, XenApp, XenDesktop, and StoreFront/Web
Procedure:
1. Log on to the NetScaler appliance and on the Conf iguration tab click XenApp and XenDesktop.
2. On the Details pane, click Get Started. If the setup exists on the NetScaler, click the Edit link corresponding to each of
the section that you want to modify.
3. Select the product (StoreFront, Web Interface, or Web Interface on NetScaler) that in your deployment provides the
interface for access to the XenApp/XenDesktop applications.
4. Set up secure remote access.
1. In the NetScaler Gateway Settings section, specify the details for the VPN virtual server and click Continue.
2. In the Server Certif icate section, choose an existing certificate or install a new certificate and click Continue.
3. In the Authentication section, configure the primary authentication mechanism to be used and specify the server
details or use an existing server and click Continue.
4. In the StoreFront section, specify the details of the server that provides the interface for accessing the applications
and click Continue.
5. You can use one of the following as your StoreFront server.
1. LB vserver pointing to multiple SF servers.
2. Web Interface or StoreFront server directly reachable from the NetScaler appliance.
3. Web Interface on NetScaler.
5. Click Done to complete the configuration.
In a distributed XenApp/XenDesktop deployment, StoreFront might not select an optimal datacenter when multiple equivalent resources are available from multiple
datacenters. In such cases, StoreFront randomly selects a datacenter. It can send the request to any of the XenApp/XenDesktop servers in any datacenter,
regardless of proximity to the client making the request.
With this enhancement, the client IP address is examined when an HTTP request arrives at the NetScaler Gateway appliance, and the real client IP address is used
to create the datacenter preference list that is forwarded to StoreFront. If the NetScaler appliance is configured to insert the zone preference header, StoreFront 3.5
or later can use the information provided by the appliance to reorder the list of delivery controllers and connect to an optimal delivery controller in the same zone as
the client. StoreFront selects the optimal gateway VPN virtual server for the selected datacenter zone, adds this information to the ICA file with appropriate IP
addresses, and sends it to the client. Storefront then tries to launch applications hosted on the preferred datacenter's delivery controllers before trying to contact
equivalent controllers in other datacenters.
For a video overview about GSLB powered zone preference solution, click https://www.youtube.com/watch?v=Y8DELum0Xp0.
T his solution involves many integration points, such as Windows Azure Pack (WAP) to Cisco APIC, Cisco APIC to System
Center Virtual Machine Manager (SCVMM), and Cisco APIC to NetScaler. As a tenant in the private cloud, you can enable
NAT, provision network services, and add a load balancer.
WAP supports tenant and administrator portals where an administrator can perform administrative tasks such as ACI
registration, VIP range, NetScaler device association with virtual machine cloud, tenant user account creation, and so on.
Tenants can log on to the WAP Tenant Portal and configure the network, bridge domains, and Virtual Routing and
Forwarding (VRFs), and make use of the NetScaler load balancing and RNAT features.
Important
In this solution, the NetScaler appliance provides only basic load balancing.
T enants can deploy multiple VIP addresses with different ports for the same network, but must ensure that the IP and port
combination is unique.
T he NetScaler device package supports only single-context deployment. Each T enant gets a dedicated NetScaler instance.
WAP supports NetScaler MPX appliances and NetScaler VPX virtual appliances, including NetScaler VPX instances deployed on
the NetScaler SDX platform.
You have conceptual knowledge of Cisco ACI components and Citrix NetScaler ADCs.
For more information about Cisco ACI and its components, see the product documentation at:
http://www.cisco.com/c/en/us/support/cloud-systems-management/application-policy-infrastructure-controller-
apic/tsd-products-support-series-home.html.
For more information about the Citrix NetScaler ADCs, see the Citrix NetScaler product documentation at
http://docs.citrix.com/.
All the required components of Cisco ACI, including Cisco APIC in the datacenter, are set up and configured. For more
information about Cisco ACI and its components, see the product documentation at:
http://www.cisco.com/c/en/us/support/cloud-systems-management/application-policy-infrastructure-controller-
apic/tsd-products-support-series-home.html.
You know how to integrate Cisco ACI with Microsoft Windows Azure Pack. See the product documentation at:
http://www.cisco.com/c/en/us/td/docs/switches/datacenter/aci/apic/sw/2-
3. In the plans pane, select the plan that you want to add a load balancer.
5. On the Networking (ACI) pane, in the L4 -L7 SERVICE POOL drop-down list, select the L4-L7 resource pool that you
had created in Cisco APIC.
b. Click NEW.
d. In the BRIDGE DOMAIN field, enter the bridge domain name (for example, BD01).
e. (Optional) In the SUBNET'S GATEWAY field, enter the subnet's gateway (for example, 192.168.1.1/24).
f. In the VRF field, select a VRF that is already part of the subscription or select Create One to create a VRF.
g. Click CREATE.
3. Create a network and associate it with the bridge domain that you created. Do the following:
b. Click NEW.
d. In the NETWORK NAME field, enter the network name (for example, S01).
e. In the BRIDGE DOMAIN drop-down list, select the bridge domain you have created. (for example, BD01).
f. In the subnet's GATEWAY field, enter the subnet’s gateway address (for example, 172.23.2.1/24).
g. (Optional) In the DNS SERVER IP/IPS field, enter the DNS server details.
h. Click CREATE.
a. In the NAME field, enter the name for the load balancer.
b. Optionally, in the VIRTUAL IP ADDRESS field, assign the load balancer a VIP address from the VIP range that you
defined earlier.
8. Click CREATE.
T he NetScaler Load Balancer is displayed in the LOAD BALANCERS tab and the NetScaler Load Balancer is data path
ready.
3. In the ACI pane, on the NETWORKS tab, click the network that you created.
4. In the selected network's pane, select the NetScaler load balancer and click DELETE.
Citrix XenServer
VMWare ESX
Microsoft Hyper-V
Linux KVM
Amazon Web Services
Microsoft Azure
NetScaler Management and Analytics System (NetScaler MAS) is a centralized management solution that simplifies
operations by providing administrators with enterprise-wide visibility and automating management jobs that need to be
executed across multiple instances. You can manage and monitor Citrix application networking products that include Citrix
NetScaler MPX, Citrix NetScaler VPX, Citrix NetScaler Gateway, Citrix NetScaler SDX, Citrix NetScaler CPX, and Citrix
NetScaler SD-WAN. You can use NetScaler MAS to manage, monitor, and troubleshoot the entire global application delivery
infrastructure from a single, unified console.
NetScaler MAS, a virtual appliance that runs on Citrix XenServer, VMware ESXi, and Linux KVM also addresses the
application visibility challenge by collecting detailed information about web-application and virtual-desktop traffic, such as
flow, user-session-level information, web page performance data, and database information flowing through the NetScaler
appliances, NetScaler Gateway appliances, or NetScaler SD-WAN appliances at your site and providing actionable reports. It
enables IT administrators to troubleshoot as well as proactively monitor customer issues in matter of minutes. For more
information, see MAS documentation.
VPX on
VPX on VPX on VPX on VPX on
VPX on VMware ESX Microsoft
XenServer generic KVM AWS Azure
Hyper-V
3620759
5050593 (supported from NetScaler
release 12.0 build 51.x onwards)
Hypervisor 6765062 (supported from NetScaler RHEL 7.3,
6.5, 7.0 2012R2, 2016 N/A N/A
Version Ubuntu 16.04
release 12.0 build 56.20 onwards)
4564106
VPX 10 VPX 10
VPX 10 VPX 10
VPX 25 VPX 25
VPX 25 VPX VPX 10
VPX 200 VPX 200
200
VPX 200
VPX
VPX 1000 VPX 10 VPX 1000
VPX 200
VPX 1000
VPX 3000 VPX 25 VPX 3000 1000
VPX 3000 VPX
VPX 5000 VPX 200 VPX 5000 VPX 1000
VPX 5000 3000
Models
VPX 8000 VPX 1000 VPX 8000 VPX
VPX 8000 VPX 3000
VPX 10G VPX 3000 VPX 10G 5000
VPX 10G VPX
VPX 15G VPX 8000 VPX 15G VPX BYOL
VPX 15G
15G
VPX 25G VPX 25G
VPX 25G
VPX
VPX 40G VPX 40G
VPX 40G BYOL
VPX 100G VPX 100G
Multi-PE
√ √ √ √ √ √ √ √ √ √ √ √
Support
Clustering
√ √1 √ √1 √ √ √ √ √1 √ X X
Support
√ ((Only
VLAN
√ √ √ √ √ √ on √ √ √ X X
T agging
2012R2))
Detecting
X2 √3 X2 √3 X2 √3 X2 X2 √3 √3 X2 X2
Link Events
Interface
Parameter X X X X X √ X X X √ X X
Configuration
Static LA √2 √3 √2 X √2 √3 √2 √2 √3 √3 X X
LACP X √3 √2 X √2 √3 X √2 √3 √3 X X
Static CLAG X X X X X X X X X X X X
LACP CLAG X X √2 X √2 √3 X √2 √3 √3 X X
Hot-Plug X X X X X X X X X X √ X
1
Clustering support is available on SRIOV for client- and server-facing interfaces and not for the backplane.
In case of Static LA, traffic might still be sent on the interface whose physical status is DOWN.
In case of LACP, peer device knows interface DOWN event based on LACP timeout mechanism.
In case of Dynamic routing, convergence timemdepends on the Routing Protocol since link events are not detected.
Monitored static Route functionality fails if monitors are not bound to static routes since Route state is dependent on the VLAN
status. T he VLAN status is dependent on the link status.
3
When any link event (disable/enable, reset) is generated from a NetScaler appliance, the physical status of the link does not
change. In case of static LA, any traffic initiated by the peer gets dropped on the NetScaler appliance.
In case of LACP, peer device knows interface DOWN event based on LACP timeout mechanism.
On the VMware ESX, set the port group’s VLAN ID to 1 - 4095 on the VSwitch of VMware ESX server. For more information
about setting a VLAN ID on the VSwitch of VMware ESX server, see http://www.vmware.com/pdf/esx3_vlan_wp.pdf.
Safari 5.1.3
T he following figure shows the bare-metal solution architecture of NetScaler virtual appliance on XenServer.
Install XenServer version 6.0 or later on hardware that meets the minimum requirements.
Install XenCenter on a management workstation that meets the minimum system requirements.
Obtain virtual appliance license files. For more information about virtual appliance licenses, see the NetScaler VPX
Licensing Guide at http://support.citrix.com/article/ctx122426.
Table 1. Minimum System Requirements f or XenServer Running NetScaler nCore virtual appliance
Component Requirement
CPU 2 or more 64-bit x86 CPUs with virtualization assist (Intel-VT or AMD-V) enabled
Note: T o run NetScaler virtual appliance, hardware support for virtualization must be enabled on the
XenServer host. Make sure that the BIOS option for virtualization support is not disabled. Consult your
BIOS documentation for more details.
Note: XenServer installation creates a 4 GB partition for the XenServer host control domain; the
remaining space is available for NetScaler virtual appliance and other virtual machines.
For information about installing XenServer, see the XenServer documentation at http://support.citrix.com/product/xens/.
T he following table lists the virtual computing resources that XenServer must provide for each NetScaler nCore virtual
appliance .
Table 2. Minimum Virtual Computing Resources Required f or Running NetScaler ncore virtual appliance
Component Requirement
Memory 2 GB
Note: For production use of NetScaler virtual appliance, Citrix recommends that CPU priority (in virtual machine properties)
be set to the highest level, in order to improve scheduling behavior and network latency.
XenCenter System Requirements
XenCenter is a Windows client application. It cannot run on the same machine as the XenServer host. T he following table
describes the minimum system requirements.
Table 3. Minimum System Requirements f or XenCenter Installation
Component Requirement
Operating system Windows 7, Windows XP, Windows Server 2003, or Windows Vista
RAM 1 GB
Network Interface Card (NIC) 100 megabits per second (Mbps) or faster NIC
For information about installing XenCenter, see the XenServer documentation at http://support.citrix.com/product/xens/.
Installing NetScaler Virtual Appliances on XenServer by Using XenCenter
After you have installed and configured XenServer and XenCenter, you can use XenCenter to install virtual appliances on
XenServer. T he number of virtual appliances that you can install depends on the amount of memory available on the
hardware that is running XenServer.
After you have used XenCenter to install the initial NetScaler virtual appliance (.xva image) on XenServer, you have the
option to use Command Center to provision NetScaler virtual appliance. For more information, see the Command Center
documentation.
Note
After the initial configuration of the NetScaler appliance, if you want to upgrade the appliance to the latest software release,
see Upgrading or Downgrading the System Software.
Limitations
L2 mode switching
Clustering
Admin partitioning [Shared VLAN mode]
High Availability [Active - Active mode]
Jumbo frames
IPv6 protocol in Cluster environment
Prerequisites
Add the Intel 82599 Network Interface Card (NIC) to the host.
Blacklist the ixgbevf driver by adding the following entry to the /etc/modprobe.d/blacklist.conf file:
blacklist ixgbevf
Enable SR-IOV Virtual Functions (VFs) by adding the following entry to the /etc/modprobe.d/ixgbe file:
options ixgbe max_vf s= <number_of_VFs>
where <number_VFs> is the number of SR-IOV VFs that you want to create.
Verify that SR-IOV is enabled in BIOS.
1. On the XenServer host, use the following command to assign the SR-IOV VFs to the NetScaler virtual appliance:
xe host-call-plugin plugin=iovirt host-uuid= <Xen host UUID> f n=assign_f ree_vf args:uuid= <Netscalar VM UUID>
args:ethdev= <interface name> args:mac= <mac addr>
Where:
Unassigning SR-IOV VFs to the NetScaler Virtual Appliance by Using the XenServer Host
If you have assigned an incorrect SR-IOV VFs or if you want modify the a assigned SR-IOV VFs, you need to unassign and
reassign the SR-IOV VFs to the Netscaler virtual appliance.
1. On the XenServer host, use the following command to assign the SR-IOV VFs to the NetScaler virtual appliance and
reboot the NetScaler virtual appliance:
Where:
Important
While you are assigning the SR-IOV VFs to the Netscaler virtual appliance, make sure that you specify MAC address
00:00:00:00:00:00 for the VFs.
To use the SR-IOV virtual functions in link aggregation mode, you need to disable spoof checking for virtual functions that
you have created. On the XenServer host, use the following command to disable spoof checking:
Where:
After disabling spoof checking for all the Virtual Function that you have created, restart the NetScaler virtual machine and
configure link aggregation. For instructions, see Configure Link Aggregation.
Important
Make sure that the XenServer host does not contain VLAN settings for the VF interface.
Important
You cannot install standard VMware Tools or upgrade the VMware Tools version available on a NetScaler virtual appliance. VMware
Tools for a NetScaler virtual appliance are delivered as part of the NetScaler software release.
Prerequisites
Table 1. Minimum System Requirements for VMware ESX Servers Running NetScaler nCore virtual appliance
Component Requirement
CPU 2 or more 64-bit x86 CPUs with virtualization assist (Intel-VT or AMD-V) enabled
Note: To run NetScaler virtual appliance, hardware support for virtualization must be enabled on the
VMware ESX host. Make sure that the BIOS option for virtualization support is not disabled. For more
information, see your BIOS documentation.
RAM 3 GB
Network One 1-Gbps NIC; Two 1-Gbps NICs recommended (T he network interfaces must be Intel E1000.)
T he following table lists the virtual computing resources that the VMware ESX server must provide for each NetScaler
ncore virtual appliance.
Table 2. Minimum Virtual Computing Resources Required for Running NetScaler ncore virtual appliance
Component Requirement
Memory 2 GB
Virtual network 1
interfaces
Note: With ESX, you can install a maximum of 10 virtual network interfaces if the VPX hardware is
upgraded version to 7 or higher.
Disk space 20 GB
For production use of NetScaler virtual appliance, the full memory allocation must be reserved. CPU cycles (in MHz) equal to
at least the speed of one CPU core of the ESX should also be reserved.
Operating system For detailed requirements from VMware, search for the "vSphere Compatibility Matrixes" PDF
file at http://kb.vmware.com/.
Component Requirement
Operating system For detailed requirements from VMware, search for the "OVF Tool User Guide" PDF file
at http://kb.vmware.com/.
For information about installing OVF, search for the "OVF Tool User Guide" PDF file at http://kb.vmware.com/.
Once logged on, navigate the following path from the My Citrix home page:
Copy the following files to a workstation on the same network as the ESX server. Copy all three files into the same folder.
After you have installed and configured VMware ESX, you can use the VMware vSphere client to install virtual appliances on
the VMware ESX server. T he number of virtual appliances that you can install depends on the amount of memory available
on the hardware that is running VMware ESX.
To install NetScaler virtual appliances on VMware ESX by using VMware vSphere Client:
Note
By default, the NetScaler Virtual Appliance uses E1000 network interfaces.
After the installation, you can use vSphere client or vSphere Web Client to manage virtual appliances on VMware ESX.
For more information about installing a NetScaler VPX appliance on VMware ESX, see the following video.
To configure NetScaler Virtual Appliances to use VMXNET 3 network interfaces by using the VMware vSphere Web Client:
2. Upgrade the Compatibility setting of the NetScaler virtual machine to ESX, as follows:
b. Right-click the NetScaler virtual machine and select Compatibility > Upgrade VM Compatibility.
c. In the Configure VM Compatibility dialog box, select ESXi 5.5 and later from the Compatible with drop-down list and
click OK.
- Number of CPUs
- Number of Sockets
- Reservations
- Limit
- Shares
a. In the CPU drop-down list, select the number of CPUs to assign to the virtual appliance.
b. In the Cores per Socket drop-down list, select the number of sockets.
c. (Optional) In the CPU Hot Plug field, select or unselect the Enable CPU Hot Add checkbox.
d. In the Reservation drop-down list, select the number that is shown as the maximum value.
f. In the Shares drop-down lists, select Custom and the number that is shown as the maximum value.
- Size of RAM
- Reservations
- Limit
- Shares
a. In the RAM drop-down list, select the size of the RAM. It should be number of vCPUs x 2 GB. For example, if the
number of vCPUs is 4, the RAM should be 4 x 2 GB = 8 GB.
Note: For an Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4 GB of RAM to
each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.
Note: For an Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4 GB of RAM to
each vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.
d. In the Shares drop-down lists, select Custom and the number that is shown as the maximum value.
8. In the New Network section, from the drop-down list, select the network interface, and do the following:
Important
T he default E1000 network interface and VMXNET 3 cannot coexist, make sure that you remove the E1000 network interface and
use VMXNET 3 (0/1) as the management interface.
9. Click OK.
11. Once the NetScaler virtual appliance powers on, you can use the following command to verify the configuration:
command COPY
command COPY
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
Note
After you add a VMXNET 3 interface and restart the NetScaler VPX appliance, the VMWare ESX hypervisor might change the order in
which the NIC is presented to the VPX appliance. So, network adapter 1 might not always remain 0/1, resulting in loss of
management connectivity to the VPX appliance. To avoid this issue, change the virtual network of the network adapter accordingly.
Limitations
A NetScaler VPX configured with SR-IOV network interface has the following limitations:
T he following features are not supported on SR-IOV interfaces using Intel 82599 10G NIC on ESX VPX:
- L2 mode switching
- Static Link Aggregation and LACP
- Clustering
- Admin partitioning [Shared VLAN mode]
- High Availability [Active - Active mode]
- Jumbo frames
- IPv6
T he following features are not supported for on SR-IOV interface with an Intel 82599 10G NIC on KVM VPX:
- Static Link Aggregation and LACP
- L2 mode switching
- Clustering
- Admin partitioning [Shared VLAN mode]
- High Availability [Active – Active mode]
- Jumbo frames
- IPv6
- VLAN configuration on Hypervisor for SR-IOV VF interface through “ip link” command is not supported
Prerequisite
Make sure that you:
- Add the Intel 82599 Network Interface Card (NIC) to the ESX Host. IXGBE driver version 3.7.13.7.14iov is recommended.
2. On the Manage > Networking tab, select Physical adapters. T he SR-IOV Status field shows whether a physical
adapter supports SR-IOV.
6. Click OK.
7. Restart the host.
- Create a Distributed Virtual Switch (DVS) and Portgroups. For instructions, see the VMware Documentation.
Note
Citrix has qualified the SR-IOV configuration on DVS and Portgroups only.
To configure NetScaler Virtual Appliances to use SR-IOV network interf ace by using VMware vSphere Web Client:
2. Upgrade the Compatibility setting of the NetScaler virtual machine to ESX 5.5 or later, as follows:
c. In the Configure VM Compatibility dialog box, select ESXi 5.5 and later from the Compatible with drop-down
list and click OK.
4. In the <virtual_appliance> - Edit Settings dialog box, click the CPU section.
- Number of CPUs
- Number of Sockets
- Reservations
- Limit
- Shares
a. In the CPU drop-down list, select the number of CPUs to assign to the virtual appliance.
b. In the Cores per Socket drop-down list, select the number of sockets.
c. (Optional) In the CPU Hot Plug field, select or clear the Enable CPU Hot Add check box.
d. In the Reservation drop-down list, select the number that is shown as the maximum value.
f. In the Shares drop-down lists, select Custom and the number that is shown as the maximum value.
- Size of RAM
- Reservations
- Limit
- Shares
a. In the RAM drop-down list, select the size of the RAM. It should be number of vCPUs x 2 GB. For example, if the
number of vCPU is 4 then RAM = 4 x 2 GB = 8 GB.
Note: For Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4 GB of RAM to each
vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.
Note: For Enterprise or Platinum edition of the NetScaler VPX appliance, make sure that you allocate 4 GB of RAM to each
vCPU. For example, if the number of vCPU is 4 then RAM = 4 x 4 GB = 16 GB.
d. In the Shares drop-down lists, select Custom, and select the number that is shown as the maximum value.
9. In the <virtual_appliance> - Edit Settings dialog box, click the VM Options tab.
10. On the VM Options tab, select the Advanced section. From the Latency Sensitivity drop-down list, select High.
13. Once the NetScaler virtual appliance powers on, you can use the following command to verify the configuration:
Code COPY
Output COPY
--------------------------------------------------------------------------------
--------------------------------------------------------------------------------
Done
Actual: media FIBER, speed 10000, duplex FULL, fctl NONE, throughput 10000
Done
To configure an existing NetScaler VPX instance to use SR-IOV network interfaces, see Configuring NetScaler Virtual
Appliances to use Single Root I/O Virtualization (SR-IOV) Network Interface.
To configure an existing NetScaler VPX instance to use VMXNET 3 network interfaces, see Configuring NetScaler Virtual
Appliances to use VMXNET 3 Network Interface.
Overview
After you have installed and configured a NetScaler virtual appliance on VMware ESX Server, you can use the vSphere Web
Client to configure the virtual appliance to use PCI passthrough network interfaces.
T he PCI passthrough feature allows a guest virtual machine to directly access physical PCI and PCIe devices connected to a
host.
Prerequisites
Before configuring a passthrough PCI device on a virtual machine, you should configure it on the host machne. Follow these
steps to configure passthrough devices on a host.
1. Select the host from the Navigator panel of the vSphere Web Client.
2. Click Manage > Settings > PCI Devices. All available passthrough devices are displayed.
3. Right-click the device that you want to configure and click Edit.
4. T he Edit PCI Device Availability window appears.
5. Select the devices to be used for passthrough and click OK.
Follow these steps to configure a passthrough PCI device on a NetScaler virtual appliance.
Note
VMXNET 3 network interface and PCI Passthrough Network Interface cannot coexist.
You have completed the steps to configuring NetScaler VPX to use PCI passthrough network interfaces.
After the initial configuration of the NetScaler appliance, if you want to upgrade the appliance to the latest software
release, see "Upgrading or Downgrading the System Software."
Note
Intermediate System-to-Intermediate System (ISIS) protocol is not supported on the NetScaler VPX virtual appliance hosted on the
HyperV-2012 platform.
Component Requirement
RAM 3 GB
T he following table lists the virtual computing resources for each NetScaler virtual appliance.
Table 2. Minimum Virtual Computing Resources Required f or Running NetScaler Virtual Appliance
Component Requirement
RAM 2 GB
Virtual CPU 2
Disk Space 20 GB
3. Click Downloads.
4. In Search Downloads by Product, select NetScaler.
5. Under Virtual Appliances, click NetScaler VPX.
6. Copy the compressed file to your server.
After you have enabled the Hyper-V role on Microsoft Server and extracted the virtual appliance files, you can use Hyper-V
Manager to install NetScaler virtual appliance. After you import the virtual machine, you need to configure the virtual NICs
by associating them to the virtual networks created by Hyper-V.
You can configure a maximum of eight virtual NICs. Even if the physical NIC is DOWN, the virtual appliance assumes that
the virtual NIC is UP, because it can still communicate with the other virtual appliances on the same host (server).
Note
You cannot change any settings while the virtual appliance is running. Shut down the virtual appliance and then make changes.
1. T o start Hyper-V Manager, click Start, point to Administrative Tools, and then click Hyper-V Manager.
2. In the navigation pane, under Hyper-V Manager, select the server on which you want to install NetScaler virtual
appliance.
3. On the Action menu, click Import Virtual Machine.
4. In the Import Virtual Machine dialog box, in Location, specify the path of the folder that contains the NetScaler virtual
appliance software files, and then select Copy the virtual machine (create a new unique ID). T his folder is the parent
folder that contains the Snapshots, Virtual Hard Disks, and Virtual Machines folders.
5. Note: If you received a compressed file, make sure that you extract the files into a folder before you specify the path to
the folder.
6. Click Import.
7. Verify that the virtual appliance that you imported is listed under Virtual Machines.
8. T o install another virtual appliance, repeat steps 2 through 6.
Important
Make sure that you extract the files to a different folder in step 4 .
Auto-provisioning of NetScaler virtual appliance is optional. If auto-provisioning is not done, the virtual appliance provides an
option to configure the IP address and so on.
1. Create an ISO9660 compliant ISO image using the xml file as depicted in the example. Make sure that the name of the
xml file is userdata.
<Environment xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1">
<PlatformSection>
<Kind>HYPER-V</Kind>
<Version>2013.1</Version>
<Vendor>CISCO</Vendor>
<Locale>en</Locale>
</PlatformSection>
</Environment>
3. Select the virtual appliance that you imported, and then on the Action menu, select Settings. You can also select the
virtual appliance and then right click and select Settings. T he Settings window for the selected virtual appliance is
displayed.
4. In the Settings window, under the hardware section, click on IDE Controller.
5. In the right window pane, select DVD Drive and click on Add. T he DVD Drive is added under the IDE Controller section in
the left window pane.
6. Select the DVD Drive added in step 5. In the right window pane, select the Image file radio button and click on Browse
and select the ISO image that you copied on Hyper-V server,
in step 2.
7. Click Apply.
Note
T he virtual appliance instance comes up in the default IP address, when:
1. Select the virtual appliance that you imported, and then on the Action menu, select Settings.
2. In the Settings f or <virtual appliance name> dialog box, click Add Hardware in the left pane.
3. In the right pane, from the list of devices, select Network Adapter.
4. Click Add.
5. Verify that Network Adapter (not connected) appears in the left pane.
6. Select the network adapter in the left pane.
7. In the right pane, from the Network drop-down list, select the virtual network to connect the adapter to.
1. Right-click the virtual appliance that you previously installed, and then select Start.
2. Access the console by double-clicking the virtual appliance.
3. T ype the NetScaler IP address, subnet mask, and gateway for your virtual appliance.
You have completed the basic configuration of your virtual appliance. Type the IP address in a Web browser to access the
virtual appliance.
Note
You can also use virtual machine (VM) template to provision NetScaler virtual appliance using SCVMM.
T he host Linux operating system must be installed on suitable hardware by using virtualization tools such as KVM Module
and QEMU. T he number of virtual machines (VMs) that can be deployed on the hypervisor depends on the application
requirement and the chosen hardware.
After you provision a NetScaler virtual appliance, you can add additional interfaces.
General Recommendations
To avoid unpredictable behavior, apply the following recommendations:
Do not change the MTU of the vnet interface associated with the NetScaler VM. Shut down the NetScaler VM before
modifying any configuration parameters, such as Interface modes or CPU.
Do not force a shutdown of the NetScaler VM. That is, do not use the Force off command.
Any configurations done on the host Linux might or might not be persistent, depending on your Linux distribution settings.
You can choose to make these configurations persistent to ensure consistent behavior across reboots of host Linux
operating system.
T he NetScaler package has to be unique for each of the NetScaler VPX instance provisioned.
Limitations
Live Migration of a VPX instance that runs on KVM is not supported.
Hardware Requirements
T he following table describes the minimum system requirements for Linux-KVM servers running NetScaler VPX.
Component Requirement
CPU 64-bit x86 processors with the hardware virtualization features included in the AMD-V and Intel VT -X
processors.
To test whether your CPU supports Linux host, enter the following command at the host Linux shell
prompt:
.egrep'^flags.*(vmx|svm)'/proc/cpuinfo
If the BIOS settings for the above extension are disabled, you must enable them in BIOS.
Memory Minimum 4 GB for the host Linux kernel. Add additional memory as required by the VMs.
(RAM)
Hard Disk Calculate the space for Host Linux kernel and VM requirements. A single NetScaler VPX VM requires 20
GB of disk space.
T he Host kernel used must be a 64-bit Linux kernel, release 2.6.20 or later, with all virtualization tools. Citrix recommends
newer kernels, such as 3.6.11-4 and later.
Many Linux distributions such as Red Hat, Centos, and Fedora, have tested kernel versions and associated virtualization
tools.
NetScaler VPX supports IDE and virtIO hard disk type. T he Hard Disk Type has been configured in the XML file, which is a
part of the NetScaler package.
Networking Requirements
NetScaler VPX supports virtIO para-virtualized, SR-IOV, and PCI Passthrough network interfaces.
Provisioning the NetScaler Virtual Appliance by using the Virtual Machine Manager
Make sure that you switch off the generic-receive-offload (gro) and large-receive-offload (lro) capabilities of the source
interfaces. To switch off the gro and lro capabilities, run the following commands at the host Linux shell prompt.
Example
command COPY
rx-checksumming: on
tx-checksumming: on
scatter-gather: on
tcp-segmentation-offload: on
udp-fragmentation-offload: off
generic-segmentation-offload: on
generic-receive-offload: off
large-receive-offload: off
rx-vlan-offload: on
tx-vlan-offload: on
ntuple-filters: off
receive-hashing: on
[root@localhost ~]#
Example
If the host Linux bridge is used as a source device, as in the following example, gro and lro capabilities must be switched off
on the vnet interfaces, which are the virtual interfaces connecting the host to the guest VMs.
command COPY
vnet0
vnet2
[root@localhost ~]#
In the above example, the two virtual interfaces are derived from the eth6_br and are represented as vnet0 and vnet2. Run
the following commands to switch off gro and lro capabilities on these interfaces.
command COPY
Promiscuous Mode
T he promiscuos mode has to be enabled for the following features to work:
L2 mode
Multicast traffic processing
Broadcast
IPV6 traffic
VMAC
Dynamic routing
command COPY
collisions:0 txqueuelen:1000
[root@localhost ~]#
Module Required
For better network performance, make sure the vhost_net module is present in the Linux host. To check the existence of
vhost_net module, run the following command on the Linux host :
If vhost_net is not yet running, enter the following command to run it:
modprobe vhost_net
Provisioning a NetScaler instance, optionally involves using data from the config drive. Config drive is a special configuration
drive that attaches to the instance as a CD-ROM device when it boots. T his configuration drive can be used to pass
networking configuration such as management IP address, network mask, default gateway, and to inject customer scripts.
In a NetScaler appliance, the default authentication mechanism is password based. Now, SSH key-pair authentication
mechanism is supported for NetScaler VPX instances on OpenStack environment.
T he key-pair (public key and private key) needs to be generated before using Public Key Cryptography mechanism. You can
use different mechanisms, such as Horizon, Puttygen.exe for Windows, and ssh-keygen for Linux environment, to generate
the key pair. Refer to online documentation of respective mechanisms for more information about generating key pair.
Once a key pair is available, copy the private key to a secure location to which authorized persons will have access. In
OpenStack, public key can be deployed on a VPX instance by using Horizon or Nova boot command. When a NetScaler
instance is provisioned by using OpenStack, it first detects that the instance is booting in an OpenStack environment by
reading a specific BIOS string. T his string is "OpenStack Foundation" and for Red Hat Linux distributions it is stored in
/etc/nova/release. T his is a standard mechanism that is available in all OpenStack implementations based on KVM hyper-
visor platform. T he drive should have a specific OpenStack label.
If the config drive is detected, the instance attempts to read the network configuration, custom scripts, and SSH key pair if
provided.
Userdata File
T he NetScaler appliance uses a customized OVF file, also known as userdata file, to inject network configuration, custom
scripts. T his file is provided as part of config drive. Here is an example of a customized OVF file.
<Environment xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1"
<PlatformSection>
<Kind></Kind>
<Version>2016.1</Version>
<Vendor>VPX</Vendor>
<Locale>en</Locale>
</PlatformSection>
<PropertySection>
</PropertySection>
<cs:ScriptSection>
<cs:Version>1.0</cs:Version>
<Scripts>
<Script>
<Parameter>X Y</Parameter>
<Parameter>Z</Parameter>
<BootScript>before</BootScript>
<Text>
#!/bin/bash
</Text>
</Script>
<Script>
<Type>python</Type>
<BootScript>after</BootScript>
<Text>
#!/bin/python
print("Hello");
</Text>
</Script>
<Script>
<Type>perl</Type>
<BootScript>before</BootScript>
!/usr/bin/perl
my $name = "VPX";
</Text>
</Script>
<Script>
<Type>nscli</Type>
<BootScript>after</BootScript>
<Text>
add vlan 33
</Text>
</Script>
</Scripts>
</ScriptSettingSection>
</cs:ScriptSection>
</Environment>
In the OVF file above "PropertySection" is used for NetScaler networking configuration while <cs:ScriptSection> is used to
a) <Type>: Specifies value for script type. Possible values: Shell/Perl/Python/NSLCI (for NetScaler CLI scripts)
b) <Parameter>: Provides parameters to the script. Each script can have multiple <Parameter> tags.
c) <BootScript>: Specifies script execution point. Possible values for this tag: before/after. “before” specifies script will be
executed before PE comes up. “after” specifies that the script will be executed after PE comes up.
Note
Currently the NetScaler appliance does not take care of sanitization of scripts. As an administrator, you should check the validity of
the script.
Not all sections need to be present. Use an empty "PropertySection" to only define scripts to execute on first boot or an empty
<cs:ScriptSection> to only define networking configuration.
After the required sections of the OVF file (userdata file) are populated, use that file to provision the NetScaler instance.
Network Configuration
Management IP address
Network mask
Default gateway
After the parameters are successfully read, they are populated in the NetScaler configuration, to allow managing the
instance remotely. If the parameters are not read successfully or the config drive is not available, the instance transitions to
the default behavior, which is:
Customer Script
T he NetScaler appliance allows to execute a custom script during initial provisioning. T he appliance supports script of type
Shell, Perl, Python, and NetScaler CLI (NSCLI) commands.
T he NetScaler instance copies public key, available within the configuration drive as part of instance meta data, into its
"authorized_keys" file. T his allows the user to access the instance with private key.
Note
Before you provision a NetScaler instance on OpenStack environment, extract the .qcow2 file from the .tgz file and build
1. Extract the. qcow2 file from the .tqz file by typing the following command.
command COPY
Example COPY
NSVPX-KVM.xml
NSVPX-KVM-12.0-26.2_nc.qcow2
2. Build an OpenStack image using the .qcoz2 file extracted in step 1 by typing the following command.
command COPY
openstack image create --container-format bare --property hw_disk_bus=ide --disk-format qcow2 --file <path to qcow2 file> --public <name of the
Example COPY
Figure 1: T he following illustration provides a sample output for the glance image-create command.
You can provision a NetScaler instance in two ways by using one of the options:
1. Instance Name
2. Instance Flavor
3. Instance Count
4. Instance Boot Source
5. Image Name
5. Deploy a new key pair or an existing key pair through Horizon by completing the following steps:
a) If you don’t have an existing key pair, create the key by using any existing mechanisms. If you’ve an existing key, skip
this step.
e) Click the + sign next to the Key Pair drop-down menu and provide values for shown parameters.
f) Paste public key content in Public key box, give a name to the key and click Import Key Pair.
6. Click the Post Creation tab in the wizard. In Customization Script, add the content of the userdata file. T he userdata file
contains the IP address, Netmask and Gateway details, and customer scripts of the NetScaler instance.
7. After a key pair is selected or imported, check config-drive option and click Launch.
openstack image create --container-format bare --property hw_disk_bus=ide --diskformat qcow2 --file NSVPX-OpenStack.qcow2 --public VPX-To
command COPY
3. To create an instance of a particular flavor, type the following command to choose a flavor ID/Name of from a list:
command COPY
4. To attach a NIC to a particular network, type the following command to choose a network ID from a network list:
command COPY
command COPY
INSTANCE_NAME
VPX-ToT
After installing your preferred Linux distribution, with KVM virtualization enabled, you can proceed with provisioning virtual
machines.
While using the Virtual Machine Manager to provision a NetScaler VPX instance, you have two options:
You can use two kinds of images to provision a NetScaler VPX instance:
RAW
QCOW2
You can convert a NetScaler VPX RAW image to a QCOW2 image and provision the NetScaler VPX instance. To convert the
RAW image to a QCOW2 image, type the following command:
For example:
qemu-img convert -O qcow2 NSVPX-KVM-11.1-12.5_nc.raw NSVPX-KVM-11.1-12.5_nc.qcow
Auto-provisioning is an optional feature, and it involves using data from the CDROM drive. If this feature is enabled, you
need not enter the management IP address, network mask, and default gateway of the NetScaler VPX instance during
initial setup.
You need to complete the following tasks before you can auto-provision a VPX instance:
1. Create a customized Open Virtualization Format (OVF) XML file or userdata file.
2. Convert the OVF file into an ISO image by using an online application (for example PowerISO).
3. Mount the ISO image on the the KVM host by using any secure copy (SCP)-based tools.
<Environment xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1"
xmlns:cs="http://schemas.citrix.com/openstack">
<PlatformSection>
<Kind></Kind>
<Version>2016.1</Version>
<Vendor>VPX</Vendor>
<Locale>en</Locale>
</PlatformSection>
<PropertySection>
</PropertySection>
</Environment>
In the OVF XML file above, "PropertySection" is used for NetScaler networking configuration. When you create the file,
specify values for the parameters that are highlighted at the end of the example:
Management IP address
Netmask
Gateway
Important
If the OVF file is not properly XML formatted, the VPX instance is assigned the default network configuration, not the values
specified in the file.
T he Virtual Machine Manager enables you to provision a NetScaler VPX instancy by using a RAW image.
1. Open the Virtual Machine Manager (Application > System Tools > Virtual Machine Manager) and enter the logon
credentials in the Authenticate window.
2. Click the icon or right-click localhost (QEMU) to create a new NetScaler VPX instance.
3. In the Name text box, enter a name for the new VM (for example, NetScaler-VPX).
4. In the New VM window, under "Choose how you would like to install the operating system," select Import existing disk
image, and then and click Forward.
6. Under Choose Memory and CPU settings select the following settings, and then click Forward:
Memory (RAM)— 2048 MB
CPUs— 2
9. Click Apply.
10. If you want to auto-provision the VPX instance, see the section "Enabling Auto-Provisioning by Attaching a CDROM
Drive" in this document. Otherwise, click Begin Installation. After you have provisioned the NetScaler VPX on KVM, you
can add additional interfaces
Watch the following video for more information about how to provision a NetScaler VPX instancy by using a RAW image.
Using the Virtual Machine Manager, you can provision the NetScaler VPX using a QCOW2 image.
1. Follow step 1 to step 8 in Provisioning the NetScaler Virtual Appliance by using the RAW Image.
4. Click Apply, and then click Begin Installation. After you have provisioned the NetScaler VPX on KVM, you can add
additional interfaces.
1. Click Add Hardware > Storage > Device type > CDROM device.
2. Click Manage and selec the correct ISO file that you mounted in the "Prerequisites for Auto-Provisioning a NetScaler
VPX Instance" section, and click Finish. A new CDROM under Resources on your NetScaler VPX instance is created.
Adding Additional Interf aces to NetScaler VPX Instance by Using Virtual Machine Manager
After you have provisioned the NetScaler VPX instance on KVM, you can add additional interfaces.
4. Select the newly added NIC and select the Source mode for this NIC. T he available modes are VEPA, Bridge, Private,
and Passthrough. For more details on the interface and modes, see Source Interface and Modes.
5. Click Apply.
6. If you want to auto-provision the VPX instance, see the section "Adding a Config Drive to Enable Auto-Provisioning" in
Important
Interface parameter configurations such as speed, duplex, and autonegotiation are not supported.
Limitations
Keep the limitations in mind while using Intel 82599, X710, XL710 NICs. T he following features not supported.
L2 mode switching.
In a cluster, Jumbo Frames are not supported when the XL710 NIC is used as
a data interface.
L2 mode switching. Interface list re-orders when interfaces are disconnected and reconnected.
Admin partitioning (shared VLAN mode). Interface parameter configurations such as speed, duplex, and auto
High availability (active-active mode). negotiations are not supported.
Jumbo Frames. Interface name is 40/X for both XL710 and X710 NICs
IPv6: You can configure only up to 30 unique IPv6 Up to 16 Intel XL710/X710 SRIOV or PCI Passthrough interfaces can be
addresses in a VPX instance if you've alteast one supported on a VPX instance.
SR-IOV interface.
VLAN configuration on Hypervisor for SRIOV VF Note: For IPv6 to work with X710 10G and XL710 40G NICs, you need to
interface through “ip link” command is not enable trust mode on the Virtual Functions (VFs) by typing the following
supported. command on the KVM host:
Interface parameter configurations such as speed,
# ip link set <PNIC> <VF> trust on
duplex, and autonegotiations are not supported.
For example:
Prerequisites
Before you configure a NetScaler VPX instance to use SR-IOV network interfaces, complete the following prerequisite tasks. See the NIC
column for details about about how to complete the corresponding tasks.
2. Download and
install the latest IXGBE driver I40E driver
Intel driver
4. Enable SR-IOV
Virtual Functions If you are using earlier version of kernel 3.8, then add
Important
When you are create the SR-IOV VFs, ensure that you do not assign MAC addresses to the VFs.
Figure 1: Enable SR-IOV VFs on the KVM host for 82599 10G NIC
Figure 2: Enable SR-IOV VFs on the KVM host for X710 10G and XL710 40G NICs.
To configure NetScaler VPX instance to use SR-IOV network interface by using Virtual Machine Manager, complete these steps:
b. In the Host Device section, select the VF you have created and click Finish.
command COPY
Important
When you are creating the SR-IOV VFs, ensure that you do not assign MAC addresses to the VFs.
To use the SR-IOV VFs in link aggregation mode, disable spoof checking for VFs that you have created. On the KVM host, use the following
command to disable spoof checking:
Where:
For example:
You can configure VLAN on SR-IOV VFs. For detailed instructions, see Configuring a VLAN.
Important
Ensure that the KVM host does not contain VLAN settings for the VF interface.
Prerequisites
T he firmware version of the Intel XL710 Network Interface Card (NIC) on the KVM Host is 5.04.
T he KVM Host supports input– output memory management unit (IOMMU) and Intel VT -d, and they are enabled in the
BIOS of the KVM Host. On the KVM Host, to enable IOMMU, add the following entry to the /boot/grub2/grub.cf g
file:
intel_iommu=1
Execute the following command and reboot the KVM Host:
Grub2-mkconf ig –o /boot/grub2/grub.cf g
To conf igure NetScaler virtual appliances to use PCI passthrough network interf aces by using the Virtual
Machine Manager:
1. Power off the NetScaler virtual machine.
b. In the Host Device section, select the Intel XL710 physical function.
c. Click Finish.
8. Once the NetScaler virtual appliance powers on, you can use the following command to verify the configuration:
1. Use the tar command to untar the the NetScaler VPX package. T he NSVPX-KVM-*_nc.tgz package contains following
components:
T he Domain XML file specifying VPX attributes [NSVPX-KVM-*_nc.xml]
Check sum of NS-VM Disk Image [Checksum.txt]
NS-VM Disk Image [NSVPX-KVM-*_nc.raw]
Example:
tar -xvzf NSVPX-KVM-10.1-117_nc.tgz
NSVPX-KVM-10.1-117_nc.xml
NSVPX-KVM-10.1-117_nc.raw
checksum.txt
2. Copy the NSVPX-KVM-*_nc.xml XML file to a file named <DomainName>-NSVPX-KVM-*_nc.xml. T he <DomainName> is
also the name of the virtual machine. Example:
cp NSVPX-KVM-10.1-117_nc.xml NetScaler-VPX-NSVPX-KVM-10.1-117_nc.xml
3. Edit the <DomainName>-NSVPX-KVM-*_nc.xml file to specify the following parameters:
name— Specify the name.
mac— Specify the MAC address.
Note: T he domain name and the MAC address have to be unique.
sourcefile— Specify the absolute disk-image source path. T he file path has to be absolute. You can specify the path
of the RAW image file or a QCOW2 image file.
If you want to specify a RAW image file, specify the disk image source path as shown in the following example:
Example:
<name>NetScaler-VPX</name>
<mac address='52:54:00:29:74:b3'/>
<source file='/root/NSVPX-KVM-10.1-117_nc.raw'/>
Specify the absolute QCOW2 disk-image source path and define the driver type as qcow2, as shown in the
following example:
Example:
<name>NetScaler-VPX</name>
<mac address='52:54:00:29:74:b3'/>
<driver name ='qemu' type='qcow2'/>
<source file='/root/NSVPX-KVM-10.1-117_nc.qcow'/>
Updated: 2015-03-09
After you have provisioned the NetScaler VPX on KVM, you can add additional interfaces.
Set target interface as ethx, Mode as bridge, and model type as virtio
<interface type='direct'>
<mac address='52:54:00:29:74:b3'/>
<source dev='eth1' mode='passthrough'/>
<model type='virtio'/>
</interface>
Here eth1 is the physical interface attached to the VM.
<interface type='bridge'>
<mac address='52:54:00:2d:43:a4'/>
<source bridge='br0'/>
<model type='virtio'/>
</interface>
Updated: 2013-09-04
Rebooting a Guest
You can reboot a VM Guest from the Virtual Machine Manager. T o reboot the VM, right-click the VM Guest entry, and then
Deleting a Guest
Deleting a VM Guest removes its XML configuration by default. You can also delete a guest's storage files. Doing so
completely erases the guest.
1. In the Virtual Machine Manager, right-click the VM Guest entry.
2. Select Delete from the pop-up menu. A confirmation window opens.
Note: T he Delete option is enabled only when the VM Guest is shut down.
3. Click Delete.
4. T o completely erase the guest, delete the associated .raw file by selecting the Delete Associated Storage Files check
box.
Updated: 2013-09-04
Rebooting a Guest
virsh reboot [<DomainID> | <DomainName> | <DomainUUID>]
Example:
Deleting a Guest
T o delete a Guest VM you need to shut-down the Guest and un-define the <DomainName>-NSVPX-KVM-*_nc.xml before
you run the delete command.
virsh shutdown [<DomainID> | <DomainName> | <DomainUUID>]
virsh undefine [<DomainName> | <DomainUUID>]
Example:
virsh shutdown NetScaler-VPX
virsh undefine NetScaler-VPX
Note: T he delete command doesn’t remove disk image file which needs to be removed manually.
You can deploy a NetScaler VPX instance that uses SR-IOV technology, on OpenStack, in three steps:
Prerequisites
Add the Intel 82599 Network Interface Card (NIC) to the host.
Download and Install the latest IXGBE driver from Intel.
Blacklist the IXGBEVF driver on the host. Add the following entry in the /etc/modprobe.d/blacklist.conf file:
blacklist ixgbevf
Note
T he ixgbe driver version should be minimum 5.0.4.
If you are using a kernel version earlier than 3.8, add the following entry to the /etc/modprobe.d/ixgbe file and restart
the host:
If you are using kernel 3.8 version or later, create VFs by using the following command:
command COPY
Where:
Important
While you are creating the SR-IOV VFs, make sure that you do not assign MAC addresses to the VFs.
Make the VFs persistent, add the commands that you used to created VFs to the rc.local file. Here is an example showing
contents of rc.local file.
Follow the steps given at the link below to configure SR-IOV on OpenStack: https://wiki.openstack.org/wiki/SR-IOV-
Passthrough-For-Networking
Provisioning a NetScaler instance, optionally involves using data from the config drive. T he config drive is a special
configuration drive that attaches to the instance when it boots. T his configuration drive can be used to pass networking
configuration information such as management IP address, network mask, and default gateway etc. to the instance before
you configure the network settings for the instance.
When OpenStack provisions a NetScaler instance, it first detects that the instance is booting in an OpenStack
environment, by reading a specific BIOS string (OpenStack Foundation) that indicates OpenStack. For Red Hat Linux
distributions, the string is stored in /etc/nova/release. T his is a standard mechanism that is available in all OpenStack
implementations based on KVM hyper-visor platform. T he drive should have a specific OpenStack label. If the config drive is
detected, the instance attempts to read the following information from the file name specified in the nova boot command.
In the procedures below, the file is called “userdata.txt.”
Management IP address
Network mask
Default gateway
Once the parameters are successfully read, they are populated in the NetScaler stack. T his helps in managing the instance
remotely. If the parameters are not read successfully or the config drive is not available, the instance transitions to the
default behavior, which is:
1. Extract the. qcow2 file from the .tqz file by typing the command:
command COPY
Example COPY
NSVPX-KVM.xml
NSVPX-KVM-12.0-26.2_nc.qcow2
2. Build an OpenStack image using the .qcoz2 file extracted in step 1 by typing the following command:
command COPY
qcow2 file>
Example COPY
hw_disk_bus=ide --is-public=
26.2_nc.qcow2
T he following illustration provides a sample output for the glance image-create command.
Example COPY
02086a6bdee2 NSVPX-10
In the above command, userdata.txt is the file which contains the details like, IP address, netmask, and default gateway for
the NetScaler instance. T he userdata file is a user customizable file. NSVPX-KVM-12.0-26.2 is the name of the virtual
appliance that you want to provision. --nic port-id=218ba819-9f55-4991-adb6-02086a6bdee2 is the OpenStack VF.
T he following illustration shows a sample of the userdata.txt file. T he values within the <PropertySection>
</PropertySection> tags are the values which is user configurable and holds the information like, IP address, netmask,and
default gateway.
<Environment xmlns:oe="http://schemas.dmtf.org/ovf/environment/1"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
oe:id=""
xmlns="http://schemas.dmtf.org/ovf/environment/1">
<PlatformSection>
<Version>2013.1</Version>
<Vendor>Openstack</Vendor>
<Locale>en</Locale>
</PlatformSection>
<PropertySection>
citrix.com 4
<Property oe:key="com.citrix.netscaler.orch_env"
oe:value="openstack-orch-env"/>
<Property oe:key="com.citrix.netscaler.mgmt.ip"
oe:value="10.1.0.100"/>
<Property oe:key="com.citrix.netscaler.mgmt.netmask"
oe:value="255.255.0.0"/>
<Property oe:key="com.citrix.netscaler.mgmt.gateway"
oe:value="10.1.0.1"/>
</PropertySection>
</Environment>
command COPY
command COPY
T hese steps complete the procedure for deploying a NetScaler VPX instance that uses SRIOV technology, on OpenStack.
OVS is a multilayer virtual switch licensed under the open-source Apache 2.0 license. DPDK is a set of libraries and drivers for
fast packet processing.
T he following Fedora, RHOS, OVS, and DPDK versions are qualified for configuring a NetScaler VPX instance:
Prerequisites
Before you install DPDK, make sure the host has 1 GB hugepages.
Here is the summary of the steps required to configuring a NetScaler VPX Instance on KVM to use OVS DPDK-based host
interfaces:
Install DPDK.
Build and Install OVS.
Create an OVS bridge.
Attach a physical interface to the OVS bridge.
Attach vhost-user ports to the OVS data path.
Provision a KVM-VPX with OVS-DPDK based vhost-user ports.
Installing DPDK
To install DPDK, follow the instruction given at this Open vSwitch with DPDK document .
Download OVS from the OVS download page. Next, build and install OVS by using a DPDK datapath. Follow the
instructions given in the Installing Open vSwitch document.
Depending on your need, type the Fedora or RHOS command to create an OVS bridge:
Bind the ports to DPDK and then attach them to the OVS bridge by typing the following Fedora or RHOS commands:
> $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 dpdk0 -- set Interface dpdk0 type=dpdk options:dpdk-devargs=0000:03:00.0
> $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 dpdk1 -- set Interface dpdk1 type=dpdk options:dpdk-devargs=0000:03:00.1
T he dpdk-devargs shown as part of options specifies the PCI BDF of the respective physical NIC.
> $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 vhost-user1 -- set Interface vhost-user1 type=dpdkvhostuser -- set Interface vhost-user1 mtu_re
> $OVS_DIR/utilities/ovs-vsctl add-port ovs-br0 vhost-user2 -- set Interface vhost-user2 type=dpdkvhostuser -- set Interface vhost-user2 mtu_re
ovs-vsctl add-port ovs-br0 vhost-user1 -- set Interface vhost-user1 type=dpdkvhostuser -- set Interface vhost-user1 mtu_request=9000
ovs-vsctl add-port ovs-br0 vhost-user2 -- set Interface vhost-user2 type=dpdkvhostuser -- set Interface vhost-user2 mtu_request=9000
You can provision a NetScaler instance on Fedora KVM with OVS-DPDK-based vhost-user ports only from CLI by using the
following QEMU commands:
-device ide-drive,bus=ide.0,unit=0,drive=drive-ide0-0-0,id=ide0-0-0,bootindex=1 \
-netdev type=tap,id=hostnet0,script=no,downscript=no,vhost=on \
-device virtio-net-pci,netdev=hostnet0,id=net0,mac=52:54:00:3c:d1:ae,bus=pci.0,addr=0x3 \
-chardev socket,id=char0,path=</usr/local/var/run/openvswitch/vhost-user1> \
-chardev socket,id=char1,path=</usr/local/var/run/openvswitch/vhost-user2> \
pci,mac=00:00:00:00:00:02,netdev=mynet2,mrg_rxbuf=on \
--nographic
For RHOS, use the following sample XML file to provision the NetScaler VPX instance, by using virsh.
<domain type='kvm'>
<name>dpdk-vpx1</name>
<uuid>aedb844b-f6bc-48e6-a4c6-36577f2d68d6</uuid>
<memory unit='KiB'>16777216</memory>
<currentMemory unit='KiB'>16777216</currentMemory>
<hugepages>
</hugepages>
</memoryBacking>
<vcpu placement='static'>6</vcpu>
<cputune>
<shares>4096</shares>
<emulatorpin cpuset='0,2,4,6'/>
</cputune>
<numatune>
</numatune>
<resource>
<partition>/machine</partition>
</resource>
<os>
<boot dev='hd'/>
</os>
<features>
<acpi/>
<apic/>
</features>
<vendor>Intel</vendor>
<domain type='kvm'>
<name>dpdk-vpx1</name>
<uuid>aedb844b-f6bc-48e6-a4c6-36577f2d68d6</uuid>
<memory unit='KiB'>16777216</memory>
<currentMemory unit='KiB'>16777216</currentMemory>
<memoryBacking>
<hugepages>
</hugepages>
</memoryBacking>
<vcpu placement='static'>6</vcpu>
<cputune>
<shares>4096</shares>
<emulatorpin cpuset='0,2,4,6'/>
</cputune>
<numatune>
</numatune>
<resource>
<partition>/machine</partition>
</resource>
<os>
<boot dev='hd'/>
</os>
<features>
<acpi/>
<apic/>
</features>
<vendor>Intel</vendor>
<numa>
</numa>
</cpu>
<on_poweroff>destroy</on_poweroff>
<on_reboot>restart</on_reboot>
<on_crash>destroy</on_crash>
<devices>
<emulator>/usr/libexec/qemu-kvm</emulator>
<source file='/home/NSVPX-KVM-12.0-52.18_nc.qcow2'/>
</disk>
</controller>
</controller>
<interface type='direct'>
<mac address='52:54:00:bb:ac:05'/>
<model type='virtio'/>
</interface>
<interface type='vhostuser'>
<mac address='52:54:00:55:55:56'/>
</interface>
<interface type='vhostuser'>
<mac address='52:54:00:2a:32:64'/>
<model type='virtio'/>
</interface>
<interface type='vhostuser'>
<mac address='52:54:00:2a:32:74'/>
<model type='virtio'/>
</interface>
<interface type='vhostuser'>
<mac address='52:54:00:2a:32:84'/>
<model type='virtio'/>
</interface>
<serial type='pty'>
<target port='0'/>
</serial>
<console type='pty'>
</console>
<listen type='address'/>
</graphics>
<video>
</video>
<memballoon model='virtio'>
</memballoon>
</devices>
</domain
Points to note
In the XML file, the hugepage size must be 1 GB, as shown in the sample file.
<memoryBacking>
<hugepages>
</hugepages>
Also, in the sample file vhost-user1 is the vhostuser port bound to ovs-br0.
<interface type='vhostuser'>
<mac address='52:54:00:55:55:56'/>
<model type='virtio'/>
</interface>
AWS T erminology
How a NetScaler VPX Instance on AWS Works
Supported Instance T ype, ENI, and IP Addresses
AWS Terminology
Here is a brief description of the terms used in this document. For more information, see AWS Glossary.
Term Definition
Amazon Machine Image (AMI) A machine image, which provides the information required to launch an
instance, which is a virtual server in the cloud.
Elastic Block Store (EBS) Provides persistent block storage volumes for use with Amazon EC2 instances
in the AWS Cloud.
Simple Storage Service (S3) Storage for the Internet. It is designed to make web-scale computing easier
for developers.
Elastic Compute Cloud (EC2) A web service that provides secure, resizable compute capacity in the cloud. It
is designed to make web-scale cloud computing easier for developers.
Elastic Load Balancing (ELB) Distributes incoming application traffic across multiple EC2 instances, in
multiple Availability Zones. T his increases the fault tolerance of your
applications.
elastic network interface (ENI) A virtual network interface that you can attach to an instance in a VPC.
Elastic IP (EIP) address A static, public IPv4 address that you have allocated in Amazon EC2 or
Amazon VPC and then attached to an instance. Elastic IP addresses are
associated with your account, not a specific instance. T hey are elastic
because you can easily allocate, attach, detach, and free them as your needs
change.
Identity and Access Management An AWS identity with permission policies that determine what the identity
(IAM) role can and cannot do in AWS. You can use an IAM role to enable applications
running on an EC2 instance to securely access your AWS resources.
Internet Gateway Connects a network to the Internet. You can route traffic for IP addresses
outside your VPC to the Internet gateway.
Key pair A set of security credentials that you use to prove your identity electronically.
A key pair consists of a private key and a public key.
Route tables A set of routing rules that controls the traffic leaving any subnet that is
associated with the route table. You can associate multiple subnets with a
single route table, but a subnet can be associated with only one route table
at a time.
Security groups A named set of allowed inbound network connections for an instance.
Subnets A segment of the IP address range of a VPC that EC2 instances can be
attached to. You can create subnets to group instances according to security
and operational needs.
Virtual Private Cloud (VPC) A web service for provisioning a logically isolated section of the AWS cloud
where you can launch AWS resources in a virtual network that you define.
A service for writing or changing templates that create and delete related
CloudFormation
AWS resources together as a unit.
T he NS VPX is available as an AMI in AWS marketplace, and it can be launched as an EC2 instance within an AWS VPC. T he
VPX AMI instance requires a minimum of 2 virtual CPUs and 2 GB of memory. An EC2 instance launched within an AWS VPC
can also provide the multiple interfaces, multiple IP addresses per interface, and public and private IP addresses needed for
Citrix recommends three network interfaces for a standard VPX on AWS installation.
AWS currently makes multi-IP functionality available only to instances running within an AWS VPC. A VPX instance in a VPC
can be used to load balance servers running in EC2 instances. An Amazon VPC allows you to create and control a virtual
networking environment, including your own IP address range, subnets, route tables, and network gateways.
Note: By default, you can create up to 5 VPC instances per AWS region for each AWS account. You can request higher VPC
limits by submitting Amazon's request form (http://aws.amazon.com/contact-us/vpc-request/).
Figure 1 shows a simple topology of an AWS VPC with a NetScaler VPX deployment. T he AWS VPC has:
1. A single Internet gateway to route traffic in and out of the VPC.
2. Network connectivity between the Internet gateway and the Internet.
3. T hree subnets, one each for management, client, and server.
4. Network connectivity between the Internet gateway and the two subnets (management and client).
For more information about Amazon EC2 instances and IP addresses supported per NIC per instance type:
Instance T ypes
IP Addresses Per Network Interface Per Instance T ype
An AWS account: to launch a NetScaler VPX AMI in an Amazon Web Services (AWS) Virtual Private Cloud (VPC). You can
create an AWS account for free at www.aws.amazon.com.
An AWS Identity and Access Management (IAM) user account: to securely control access to AWS services and
resources for your users. For more information about how to create an IAM user account, see the topic Creating IAM
Users (Console).
For releases prior to 12.0 57.19, an IAM role is mandatory for a high availability deployment. T he IAM role must have
the following privileges:
ec2:DescribeInstances
ec2:DescribeNetworkInterfaces
ec2:DetachNetworkInterface
ec2:AttachNetworkInterface
From 12.0 57.19 onwards, an IAM role is mandatory for both standalone and high availability deployments. T he IAM
role must have the following privileges:
ec2:DescribeInstances
ec2:DescribeNetworkInterfaces
ec2:DetachNetworkInterface
ec2:AttachNetworkInterface
ec2:StartInstances
ec2:StopInstances
ec2:RebootInstances
autoscaling:*
sns:*
sqs:*
iam:SimulatePrincipalPolicy
iam:GetRole
If you use the Citrix CloudFormation template, the IAM role is automatically created. T he template does not have the
option to select an already created IAM role.
AWS CLI: to use all of the functionality provided by the AWS Management Console from your terminal program. For
more information, see the AWS CLI user guide. You also need the AWS CLI to change the network interface type to SR-
IOV.
Prerequisites
Limitation and Usage Guidelines
Deploy a NetScaler VPX Instance on AWS by Using the AWS Web Console
You can deploy a NetScaler VPX instance on AWS through the AWS web console. T he deployment process includes the
following steps:
Amazon EC2 uses a key pair to encrypt and decrypt logon information. To log on to your instance, you must create a key
pair, specify the name of the key pair when you launch the instance, and provide the private key when you connect to the
instance.
When you review and launch an instance by using the AWS Launch Instance wizard , you are prompted to use an existing
key pair or create a new key pair. More more information about how to create a key pair, see Amazon EC2 Key Pairs.
A NetScaler VPC instance is deployed inside an AWS VPC. A VPC allows you to define virtual network dedicated to your
AWS account. For more information about AWS VPC, see Getting Started With Amazon VPC.
While creating a VPC for your NetScaler VPX instance, keep the following points in mind.
Use the VPC with a Single Public Subnet Only option to create a new AWS VPC in an AWS availability zone.
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. By
When you used the VPC wizard, only one subnet was created. Depending on your requirement, you might want to create
additional subnets. For more information about how to create additional subnets, see Adding a Subnet to Your VPC.
To control inbound and outbound traffic, create security groups and add rules to the groups. For more information how to
create groups and add rules, see Security Groups for Your VPC.
For NetScaler VPX instances, the EC2 wizard gives default security groups, which are generated by AWS Marketplace and is
based on recommended settings by Citrix. However, you can create additional security groups based on your requirements.
Note
Port 22, 80, 443 to be opened on the Security group for SSH, HT T P, and HT T PS access respectively.
Route table contains a set of rules, called routes, that are used to determine where network traffic is directed. Each subnet
in your VPC must be associated with a route table. For more information about how to create a route table, see Route
Tables.
An internet gateway serves two purposes: to provide a target in your VPC route tables for internet-routable traffic, and to
perform network address translation (NAT ) for instances that have been assigned public IPv4 addresses.
Create an internet gateway for internet traffic. For more information about how to create an Internet Gateway, see the
section Attaching an Internet Gateway.
Step 7: Create a NetScaler VPX instance by using the AWS EC2 service
To create a NetScaler VPX instance by using the AWS EC2 service, complete the following steps.
1. From the AWS dashboard, go to Compute > EC2 > Launch Instance > AWS Marketplace.
2. In the Search AWS Marketplace bar, search with the keyword NetScaler VPX.
3. Select the version you want to deploy and then click Select. For the NetScaler VPX version, you the following options:
A licensed version
NetScaler VPX Express appliance (T his is a free virtual appliance, which is available from NetScaler version 12.0 56.20.)
Bring your own device
T he Launch Instance wizard starts. Follow the wizard to create an instance. T he wizard prompts you to:
Create two additional network interfaces for VIP and SNIP. For more information about how to create additional network
interfaces, see the Creating a Network Interface section.
After you’ve created the network interfaces, you must attach them to the VPX instance. For more information about how
to attach network interfaces, see the Attaching a Network Interface When Launching an Instance section.
If you assign a public IP address to an EC2 instance, it remains assigned only until the instance is stopped. After that, the
address is released back to the pool. When you restart the instance, a new public IP address is assigned.
In contrast, an elastic IP (EIP) address remains assigned until the address is disassociated from an instance.
Allocate and associate an elastic IP for the management NIC. For more information about how to allocate and associate
elastic IP addresses, see these topics:
T hese steps complete the procedure to create a NetScaler VPX instance on AWS. It can take a few minutes for the
instance to be ready. Check that your instance has passed its status checks. You can view this information in the Status
Checks column on the Instances page.
After you’ve created the VPX instance, you connect the instance by using the NetScaler GUI and an SSH client.
NetScaler GUI
T he following are the default administrator credentials to access a NetScaler VPX instance
Password: T he default password for the nsroot account is set to the AWS instance-ID of the NetScaler VPX instance.
SSH client
From the AWS management console, select the NetScaler VPX instance and click Connect. Follow the instructions given
on the Connect to Your Instance page.
For more information about how to deploy a NetScaler VPX standalone instance on AWS by using the AWS web console,
see this video.
You can use the Citrix-provided CloudFormation template to automate NetScaler instance launch. T he template provides
functionality to launch a single NetScaler VPX instance, or to create a high availability environment with a pair of NetScaler
VPX instances.
T he CloudFormation template requires an existing VPC environment, and it launches a NetScaler instance with three elastic
network interfaces (ENIs). Before you start the CloudFormation template, ensure that you complete the following
requirements:
See the "Deploy a NetScaler VPX Instance on AWS by Using the AWS Web Console" section or AWS documentation for
more information about how to complete the prerequisites.
Watch this video to learn about how to configure and launch a NetScaler VPX standalone instance by using the Citrix
CloudFormation template available in the AWS Marketplace.
Further, you configure and launch a NetScaler VPX Express standalone instance by using the Citrix CloudFormation
template available in GitHub:
https://github.com/citrix/netscaler-aws-cloudformation/tree/master/templates/express_single_nic
An IAM role is not mandatory for a standalone deployment. However, Citrix recommends that you create and attach an
IAM role with the required privileges to the instance, for future need. T he IAM role ensures that the standalone instance is
easily converted to a high availability node with SR-IOV, when required.
For more information about the required privileges, see Configuring NetScaler Virtual Appliances to Use SR-IOV Network
Interface.
You can use the AWS CLI to launch instances. For more information, see the AWS Command Line Interface
Documentation.
404
© 1999- Citrix Systems, Inc. All rights reserved. | Terms of Use | Cookie Preferences
If this is a paid marketplace instance, then you do not need to install a license. T he correct feature set and performance
will activate automatically.
If you use a NetScaler VPX instance with a model number higher than VPX 5000, the network throughput might not be the
same as specified by the instance's license. However, other features, such as SSL throughput and SSL transactions per
second, might improve.
T o enable NetScaler to load balance servers running outside the AWS VPC that the NetScaler instance is in, configure the
NetScaler to use EIPs to route traffic through the Internet gateway, as follows:
1. Configure a SNIP on the NetScaler by using the NetScaler CLI or the NetScaler GUI
2. Enable traffic to be routed out of the AZ, by creating a public facing subnet for the server-side traffic.
3. Add an Internet gateway route to the routing table, using the AWS GUI console.
4. Associate the routing table you just updated with the server-side subnet.
5. Associate an EIP with the server-side private IP address that is mapped to a NetScaler SNIP address.
Prerequisites
Limitations and Usage Guidelines
T he 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.
T he CloudFormation template significantly decreases the number of steps involved for creating an HA pair, and it
automatically creates an IAM Role. T his 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.
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).
T he secondary node always has one ENI interface (for management) and the primary node can have up to four ENIs.
T he 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).
T he message AWSCONFIG IOCT L NSAPI_HOT PLUG_INT F 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.
T he heartbeat packets are received only on the management interface.
T he configuration file of the primary and secondary NetScaler appliances is synchronized, including the nsroot password.
T he nsroot password of the secondary node is set to that of the primary node after the HA configuration
synchronization.
T o 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.
T he Citrix CloudFormation template does not create an HA setup between different availability zones.
T he Citrix CloudFormation template does not create an INC mode.
T he 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
T hree subnets within the VPC
A security group with UDP 3003, T CP 3009-3010, HT T P, SSH ports open
A key pair
Note
T he Citrix CloudFormation template automatically creates an IAM Role. T he template has no option to select an existing IAM Role.
7. Click Launch with CloudFormation Console to launch the Citrix CloudFormation template..
Select the VPC that you've already created for VPC ID.
Select the key pair that you've already created from the drop-down menu for Key Pair.
Select Management Subnetwork, Client Subnetwork, and Server Subnetwork. Ensure that you select the
Add Primary Management IP, Secondary Management IP, Client IP, and Server IP. T he IP addresses must belong
to the same subnets of the respective subnetworks. Alternatively, you can let the template assign the IP addresses
automatically.
f. Click Next.
9. T he Review page appears. Take a moment to review the settings and make necessary changes if necessary.
10. Select the I acknowledge that AWS CloudFormation might create IAM resources. check box, and then click Create.
11. T he CREATE-IN-PROGRESS status appears. Wait until the status is CREATE-COMPLETE. If the status does not change
to "COMPLET E," check the Events tab for the reason of failure and recreate the instance with proper configurations.
T he secondary node is created with one private IP address and one network interface.
Note
T he 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. T he NetScaler VPX HA pair appears.
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.
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.
Support for SR-IOV interfaces in a high availability setup is available from NetScaler release 12.0 57.19 onwards. For more
information about how to configure SR-IOV, see Configuring NetScaler Virtual Appliances to Use SR-IOV Network
Integrated with AWS Auto Scaling service, the Citrix NetScaler VPX instance provides the following advantages:
Load balance and management: Auto configures servers to scale up and scale down, depending on demand. T he VPX
instance auto detects Auto Scale groups in the back-end subnet and allows user to select the Auto Scale groups to
balance the load. All of this is done by auto configuring NetScaler virtual and subnet IP addresses on the NetScaler
instance.
High availability: Detects Auto Scale groups that span multiple availability zones and load-balance servers.
Better network availability: T he VPX instance supports:
Back-end servers on different VPCs, by using VPC peering
Back-end servers on same placement groups
Back-end servers on different availability zones
Gracef ul Connection Termination: Removes Auto Scale servers gracefully, avoiding loss of client connections when
scale-down activity occurs, by using the NetScaler Graceful T imeout feature.
T he above diagram illustrates how the AWS Auto Scaling service works with a NetScaler VPX instance (LB virtual server). For
more information, see the following AWS topics.
Before you start using Auto Scaling with your NetScaler VPX instance, you should complete the following tasks.
Prerequisites
Limitation and Usage Guidelines
For more information about how to create a NetScaler VPX standalone instance, see Launching the NetScaler VPX for
AWS AMI.
For more information about how to deploy VPX instances in HA mode, see High Availability.
Citrix recommends CloudFormation template for creating NetScaler VPX instances on AWS.
Note
Citrix recommends you create three interfaces: one for NetScaler management (NSIP), one for client-facing LB virtual server (VIP),
and one for subnet IP (NSIP).
3. Create an AWS Auto Scale group. If you don’t have an existing Auto Scaling configuration, you need to:
You can add the Auto Scaling service to a VPX instance with a single click by using the NetScaler GUI. Complete these steps
to add the Auto Scaling service to the VPX instance:
2. When you log on to the NetScaler VPX instance for the first time, you see the default Cloud Profile page. You can select
the AWS auto scaling group from drop-down menu and click Create to create a cloud profile. Click Skip if you want to
create the cloud profile later.
By default the CloudFormation T emplate creates and attaches the below IAM Role
"Version": "2012-10-17",
"Statement": [
"Action": [
"ec2:DescribeInstances",
"ec2:DescribeNetworkInterfaces",
"ec2:DetachNetworkInterface",
"ec2:AttachNetworkInterface",
"ec2:StartInstances",
"ec2:StopInstances",
"ec2:RebootInstances",
"autoscaling:*",
"sns:*",
"sqs:*"
“iam: SimulatePrincipalPolicy”
“iam: GetRole”
],
"Resource": "*",
"Effect": "Allow"
T he virtual server IP address is autopopulated from the free IP address available to the VPX instance.
http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/MultipleIP.html#ManageMultipleIP
Auto Scale group is prepopulated from the Auto Scale group configured on your AWS
account. http://docs.aws.amazon.com/autoscaling/latest/userguide/AutoScalingGroup.html
While selecting the Auto Scaling Group protocol and port, ensure your servers listen on those protocol and ports and you
bind the correct monitor in the service group. By default, T CP monitor is used.
For SSL Protocol type Autos Scaling, after you create the Cloud Profile the load balance virtual server or service group
3. After first time logon if you want to create Cloud Profile, on the NetScaler GUI go to System > AWS > Cloud Profile
and click Add.
Note
https://docs.citrix.com © 1999-2017 Citrix Systems, Inc. All rights reserved. p.627
To view Auto Scale-related information in the AWS console, go to EC2 > Dashboard > Auto Scaling > Auto Scaling Group.
WARNING]:Force Failover may cause configuration loss, peer health not optimum.
Reason(s):
HA version mismatch
HA heartbeats not seen on some interfaces
At the NetScaler command prompt of the old instance (new secondary node), type:
> remove ha node 30
Done
> save config
Done
At the NetScaler command prompt of the new instance (new primary node), type:
> remove ha node 10
Done
> save config
Done
$rule1 = New-AzureRmNetworkSecurityRuleConfig -Name $rule1Name -Description "Allow HTTP" -Access Allow -Protocol Tcp -Direction Inbound
$rule2 = New-AzureRmNetworkSecurityRuleConfig -Name $rule2Name -Description "Allow HTTPS" -Access Allow -Protocol Tcp -Direction Inbou
$rule3 = New-AzureRmNetworkSecurityRuleConfig -Name $rule3Name -Description "Allow SSH" -Access Allow -Protocol Tcp -Direction Inbound
$nsg = New-AzureRmNetworkSecurityGroup -ResourceGroupName $rgName -Location $locName -Name $nsgName -SecurityRules $rule1,$rul
$vnet =New-AzureRmVirtualNetwork -Name $vNetName -ResourceGroupName $rgName -Location $locName -AddressPrefix $vNetAddressRan
$subnetName ="frontEndSubnet"
$subnetName="backEndSubnet"
$subnetName="mgmtSubnet"
$IpConfigName1 = "IPConfig1"
$IPAddress = "12.5.2.24"
$IPConfigName3="IPConfig-3"
$IPAddress="12.5.1.27"
$IPConfigName4 = "IPConfig-4"
$IPAddress = "12.5.3.24"
$IPAddress="12.5.2.26"
$IPConfigName7="IPConfig-7"
$IPAddress="12.5.1.28"
$IPConfigName8="IPConfig-8"
$IPAddress="12.5.3.28"
$nic1=New-AzureRmNetworkInterface -Name $nicName1 -ResourceGroupName $rgName -Location $locName -IpConfiguration $IpConfig1 -Ne
$nic2=New-AzureRmNetworkInterface -Name $nicName2 -ResourceGroupName $rgName -Location $locName -IpConfiguration $IpConfig3 -Ne
$nic3=New-AzureRmNetworkInterface -Name $nicName3 -ResourceGroupName $rgName -Location $locName -IpConfiguration $IpConfig4 -Ne
$nic5=New-AzureRmNetworkInterface -Name $nicName5 -ResourceGroupName $rgName -Location $locName -IpConfiguration $IpConfig7 -Ne
$nic6=New-AzureRmNetworkInterface -Name $nicName6 -ResourceGroupName $rgName -Location $locName -IpConfiguration $IpConfig8 -Ne
$vmName=$vmNamePrefix + $suffixNumber
$cred=Get-Credential -Message "Type the name and password for VPX login."
$vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName $publisher -Offer $offer -Skus $sku -Version $version
$vmName=$vmNamePrefix + $suffixNumber
$cred=Get-Credential -Message "Type the name and password for VPX login."
$vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName $publisher -Offer $offer -Skus $sku -Version $version
$nic2.IPConfig
$nic3.IPConfig
$nic4.IPConfig
$nic5.IPConfig
$nic6.IPConfig
$nic2.IpConfigurations[0].LoadBalancerBackendAddressPools.Add($lb.BackendAddressPools[0])
$nic5.IpConfigurations[0].LoadBalancerBackendAddressPools.Add($lb.BackendAddressPools[0])
$lb=$lb |Set-AzureRmLoadBalancer
$nic2=$nic2 | Set-AzureRmNetworkInterface
$nic5=$nic5 | Set-AzureRmNetworkInterface
$ipAddress1=$ipAddressPrefix + $suffixNumber
$ipAddress2=$ipAddressPrefix1 + ($suffixNumber)
$ipAddress3=$ipAddressPrefix1 + ($suffixNumber + 1)
nic2=New-AzureRMNetworkInterface -Name $nic2Name -ResourceGroupName $RGName -Location $location -IpConfiguration $IpConfig2, $IpC
$ipAddress4=$ipAddressPrefix2 + ($suffixNumber)
$vmName=$vmNamePrefix
$cred=Get-Credential -Message "Type the name and password for VPX login."
$vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName $publisher -Offer $offer -Skus $sku -Version $version
Bind lb vs v1 s[1-2]
Bind lb vs v1 s[1-2]
add gslb service site1_gslb_http_svc1 10.0.1.11 HTTP 80 -publicIP PIP3 -publicPort 80 -siteName site1
add gslb service site2_gslb_http_svc1 20.0.1.11 HTTP 80 -publicIP PIP6 -publicPort 80 -siteName site2
add gslb service site1_gslb_http_svc1 FrontEndIPofALB1 HTTP 80 -publicIP FrontEndIPofALB1 -publicPort 80 -siteName site1
add gslb service site2_gslb_http_svc1 FrontEndIPofALB2 HTTP 80 -publicIP FrontEndIPofALB2 -publicPort 80 -siteName site2
$rule1=New-AzureRmNetworkSecurityRuleConfig -Name $rule1Name -Description "Allow HTTP" -Access Allow -Protocol Tcp -Direction Inbound
$rule2=New-AzureRmNetworkSecurityRuleConfig -Name $rule2Name -Description "Allow HTTPS" -Access Allow -Protocol Tcp -Direction Inboun
$rule3=New-AzureRmNetworkSecurityRuleConfig -Name $rule3Name -Description "Allow SSH" -Access Allow -Protocol Tcp -Direction Inbound -P
$subnetName="frontEndSubnet"
$IPAddress2="11.6.1.28"
$IPAddress3="11.6.1.29"
$suffixNumber = 1
$cred=Get-Credential -Message "Type the name and password for VPX login."
$vmConfig=Set-AzureRMVMSourceImage -VM $vmConfig -PublisherName $publisher -Offer $offer -Skus $sku -Version $version
$nic.IPConfig
The resource group can include all the resources for the solution, or only those resources that you want to manage as a group. The location specified here is the
default location for resources in that resource group. Make sure all commands to create a load balancer use the same resource group.
For example:
$rgName = "ARM-VPX"
Choose a unique name for your storage account that contains only lowercase letters and numbers.
For example:
$saName="vpxstorage"
$saType="Standard_LRS"
Availability set helps to keep your virtual machines available during downtime, such as during maintenance. A load balancer configured with an availability set
ensures that your application is always available.
Add a new virtual network with at least one subnet, if the subnet was not created previously.
$FrontendAddressPrefix="10.0.1.0/24"
$BackendAddressPrefix="10.0.2.0/24"
$vnetAddressPrefix="10.0.0.0/16"
New-AzureRmVirtualNetwork -Name TestNet -ResourceGroupName $rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet
For example:
New-AzureRmVirtualNetwork -Name TestNet -ResourceGroupName $rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet
5. Creating a NIC
Create a NIC and associate the NIC with the NetScaler VPX instance. The front end Subnet created in the above procedure is indexed at 0 and the back end Subnet
is indexed at 1. Now create NIC in one of the three following ways:
$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -Location $locName -AllocationMethod Dynamic
$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location $locName -SubnetId $vnet.Subnets[$subnetIndex].Id -
PublicIpAddressId $pip.Id
$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -DomainNameLabel $domName -Location $locName -AllocationMethod
Dynamic
$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location $locName -SubnetId $vnet.Subnets[$subnetIndex].Id -
PublicIpAddressId $pip.Id
For example:
$nicName="frontendNIC"
$domName="vpxazure"
$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location $locName -SubnetId $vnet.Subnets[0].Id -PublicIpAddressId
$pip.Id
Make sure that the private (static) IP address you add to the VM should be the same range as that of the subnet specified.
$pip = New-AzureRmPublicIpAddress -Name $nicName -ResourceGroupName $rgName -Location $locName -AllocationMethod Dynamic
$nic = New-AzureRmNetworkInterface -Name $nicName -ResourceGroupName $rgName -Location $locName -SubnetId $vnet.Subnets[$subnetIndex].Id -
PublicIpAddressId $pip.Id -PrivateIpAddress $staticIP
$vmName="<VM name>"
$cred=Get-Credential -Message "Type the name and password of the local administrator account."
$vm=Set-AzureRmVMSourceImage -VM $vm -PublisherName $pubName -Offer $offerName -Skus $skuName -Version "latest"
For example:
$pubName="citrix"
The following command is used for displaying all offers from Citrix:
$offerName="netscalervpx110-6531"
The following command is used to know sku offered by publisher for specific offer name:
For example:
$pubName="citrix"
$offerName="netscalervpx110-6531"
$skuName="netscalerbyol"
When you create VM from Images present in marketplace, use the following command to specify the VM plan:
The location specified here is the default location for resources in that resource group. Make sure that all commands used to create a load balancer use the same
resource group.
For example:
$rgName = "ARM-LB-NS"
Choose a unique name for your storage account that contains only lowercase letters and numbers.
For example:
$saName="vpxstorage"
$saType="Standard_LRS"
A load balancer configured with an availability set ensures that your application is always available.
Add a new virtual network with at least one subnet, if the subnet was not created previously.
$vnetName = "LBVnet"
$vnet=New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName $rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet`
Assign front end and back end subnet to the virtual network that you created earlier in this step.
If the front end subnet is the first element of array vnet, subnetId should be $vnet.Subnets[0].Id.
If the front end subnet is the second element in the array, the subnetId should be $vnet.Subnets[1].Id, and so on..
5) Configuring front end IP address and creating back end address pool
Configure a front end IP address for the incoming load balancer network traffic and create a back end address pool to receive the load balanced traffic.
$pubName="PublicIp1"
$publicIP1 = New-AzureRmPublicIpAddress -Name $pubName -ResourceGroupName $rgName -Location $locName -AllocationMethod Static -DomainNameLabel
nsvpx
$FIPName = "ELBFIP"
$BEPool = "LB-backend-Pool"
Create a TCP health probe with port 9000 and interval 5 seconds.
$healthProbe = New-AzureRmLoadBalancerProbeConfig -Name HealthProbe -Protocol Tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2
Create a LB rule for each service that you are load balancing.
For example:
You can use the following example to load balance http service.
Create NAT rules for services that you are not load balancing.
Note: Protocol-FrontEndPort-BackendPort triplet should not be the same for two NAT rules.
$inboundNATRule2= New-AzureRmLoadBalancerInboundNatRuleConfig -Name SSH2 -FrontendIpConfiguration $frontendIP1 -Protocol TCP -FrontendPort 10022
-BackendPort 22
Create the load balancer adding all objects (NAT rules, load balancer rules, probe configurations) together.
$lbName="ELB"
$NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgName -Name $lbName -Location $locName -InboundNatRule $inboundNATRule1,
$inboundNATRule2 -FrontendIpConfiguration $frontendIP1 -LoadBalancingRule $lbrule1 -BackendAddressPool $beAddressPool1 -Probe $healthProbe
Create two NICs and associate each NIC with each VPX instance
For example:
$nicName="NIC1"
$lbName="ELB"
$bePoolIndex=0
$natRuleIndex=0
$subnetIndex=0
For example:
$nicName="NIC2"
$lbName="ELB"
$bePoolIndex=0
$natRuleIndex=1
$subnetIndex=0
Create two NetScaler VPX instances as part of the same resource group and availability set, and attach it to the external load balancer.
For example:
$vmName="VPX1"
$vmSize="Standard_A3"
$pubName="citrix"
$offerName="netscalervpx110-6531"
$skuName="netscalerbyol"
$cred=Get-Credential -Message "Type Credentials which will be used to login to VPX instance"
$vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer $offerName -Skus $skuName -Version "latest"
$diskName="dynamic"
For example:
$vmName="VPX2"
$vmSize="Standard_A3"
$cred=Get-Credential -Message " Type Credentials which will be used to login to VPX instance "
$vm2=Set-AzureRmVMSourceImage -VM $vm2 -PublisherName $pubName -Offer $offerName -Skus $skuName -Version "latest"
$diskName="dynamic"
When both the NetScaler VPX instances start, then connect to both NetScaler VPX instances using the SSH protocol to configure the virtual machines.
a) Active-Active: Run the same set of configuration commands on the command line of both the NetScaler VPX instances.
b) Active-Passive: Run this command on the command line of both the NetScaler VPX instances.
The location specified here is the default location for resources in that resource group. Make sure all commands to create a load balancer use the same resource
group.
For example:
$rgName = "ARM-LB-NS"
Choose a unique name for your storage account that contains only lowercase letters and numbers.
For example:
$saName="vpxstorage"
$saType="Standard_LRS"
A load balancer configured with an availability set ensures that your application is always available..
Add a new virtual network with at least one subnet, if the subnet was not created previously.
$vnetName = "LBVnet"
$vnet=New-AzureRmVirtualNetwork -Name $vnetName -ResourceGroupName $rgName -Location $locName -AddressPrefix $vnetAddressPrefix -Subnet
$frontendSubnet,$backendSubnet`
Assign front end and back end subnet to the virtual network that you created earlier in this step.
If the front end subnet is the first element of array vnet, subnetId should be $vnet.Subnets[0].Id.
If the front end subnet is the second element in the array, the subnetId should be $vnet.Subnets[1].Id, and so on..
Create NAT rules for services that you are not load balancing.
$inboundNATRule2= New-AzureRmLoadBalancerInboundNatRuleConfig -Name "RDP2" -FrontendIpConfiguration $frontendIP -Protocol TCP -FrontendPort 3442 -
BackendPort 3389
Use front end and back end ports as per your requirement.
Create a TCP health probe with port 9000 and interval 5 seconds.
$healthProbe = New-AzureRmLoadBalancerProbeConfig -Name "HealthProbe" " -Protocol tcp -Port 9000 -IntervalInSeconds 5 -ProbeCount 2
Create a LB rule for each service that you are load balancing.
For example:
You can use the following example to load balance http service.
Use front end and back end ports as per your requirement.
Create the load balancer adding all objects (NAT rules, load balancer rules, probe configurations) together.
$NRPLB = New-AzureRmLoadBalancer -ResourceGroupName $rgname -Name "InternalLB" -Location $locName -FrontendIpConfiguration $frontendIP -
InboundNatRule $inboundNATRule1,$inboundNatRule2 -LoadBalancingRule $lbrule -BackendAddressPool $beAddressPool -Probe $healthProbe
Create two NICs and associate each NIC with each NetScaler VPX instance
$backendnic1= New-AzureRmNetworkInterface -ResourceGroupName $rgName -Name lb-nic1-be -Location $locName -PrivateIpAddress 10.0.2.6 -Subnet
$backendSubnet -LoadBalancerBackendAddressPool $nrplb.BackendAddressPools[0] -LoadBalancerInboundNatRule $nrplb.InboundNatRules[0]
This NIC is for NetScaler VPX 1. The Private IP should be in same subnet as that of subnet added.
$backendnic2= New-AzureRmNetworkInterface -ResourceGroupName $rgName -Name lb-nic2-be -Location $locName -PrivateIpAddress 10.0.2.7 -Subnet
$backendSubnet -LoadBalancerBackendAddressPool $nrplb.BackendAddressPools[0] -LoadBalancerInboundNatRule $nrplb.InboundNatRules[1].
This NIC is for NetScaler VPX 2.The parameter Private IPAddress can have any private IP as per your requirement.
Create two VPX instances part of same resource group and availability set and attach it to the internal load balancer.
For example:
$vmName="VPX1"
$vmSize="Standard_A3"
$cred=Get-Credential -Message "Type Credentials which will be used to login to VPX instance"
$vm1=Set-AzureRmVMSourceImage -VM $vm1 -PublisherName $pubName -Offer $offerName -Skus $skuName -Version "latest"
$diskName="dynamic"
For example:
$vmSize="Standard_A3"
$cred=Get-Credential -Message " Type Credentials which will be used to login to VPX instance "
$vm2=Set-AzureRmVMSourceImage -VM $vm2 -PublisherName $pubName -Offer $offerName -Skus $skuName -Version "latest"
$diskName="dynamic"
When both the NetScaler VPX instances start, then connect to both NetScaler VPX instances using the SSH protocol to configure the virtual machines.
a) Active-Active: Run the same set of configuration commands on the command line of both the NetScaler VPX instances.
b) Active-Passive: Run this command on the command line of both the NetScaler VPX instances.
In the NetScaler GUI, you can use your hardware serial number (HSN) or your license access code to allocate your licenses.
Alternatively, if a license is already present on your local computer, you can upload it to the appliance.
For all other functionality, such as returning or reallocating your license, you must use the licensing portal. Optionally, you
can still use the licensing portal for license allocation. For more information about the licensing portal, see
http://support.citrix.com/article/CT X131110.
Note: You must purchase separate licenses for each appliance in a high availability pair. Ensure that the same types of
licenses are installed on both the appliances. For example, if you purchase a platinum license for one appliance, you must
purchase another platinum license for the other appliance.
T his document includes the following topics:
Prerequisites
Allocating your license by using the GUI
Installing the license
Verifying the licensed features
Enabling or disabling a feature
NetScaler VPX Express license
T o use the hardware serial number or license access code to allocate your licenses:
You must be able to access public domains through the appliance. For example, the appliance should be able to access
www.citrix.com. T he license allocation software internally accesses the Citrix licensing portal for your license. T o access a
public domain, you can either use a proxy server or set up a DNS server and, on your NetScaler appliance, configure a
NetScaler IP (NSIP) address or a subnet IP (SNIP) address.
Your license must be linked to your hardware, or you must have a valid license access code. Citrix sends your license
access code by email when you purchase a license.
If your license is already linked to your hardware, the license allocation process can use the hardware serial number.
Otherwise, you must type the license access code.
You can partially allocate licenses as required for your deployment. For example, if your license file contains 10 licenses, but
your current requirement is for only six licenses, you can allocate six licenses now, and allocate more licenses later. You
cannot allocate more than the total number of licenses present in your license file.
5. Click Get Licenses. Depending on the option that you selected, one of the following dialog boxes appears.
T he following dialog box appears if you selected Hardware Serial Number.
6. Select the license file that you want to use to allocate your licenses.
7. In the Allocat e column, enter the number of licenses to be allocated. T hen click Get .
If you selected Hardware Serial Number, enter the number of licenses, as shown in the following screen shot.
If you downloaded your license file to your local computer by accessing the licensing portal, you must upload the license to
the appliance.
1. Open an SSH connection to the NetScaler by using an SSH client, such as PuT T Y.
2. Log on to the NetScaler by using the administrator credentials.
3. Switch to the shell prompt, create a license subdirectory in the nsconfig directory, if it does not exist, and copy one or
more new license files to this directory.
Example
login: nsroot
Password: nsroot
Last login: Mon Aug 4 03:37:27 2008 from 10.102.29.9
Done
> shell
Last login: Mon Aug 4 03:51:42 from 10.103.25.64
root@ns# mkdir /nsconfig/license
root@ns# cd /nsconfig/license
Copy one or more new license files to this directory.
Note: T he NetScaler appliance does not prompt for a reboot option when you use the command line interface to install
the licenses. Run the reboot -w command to warm restart the system, or run the restart command to restart the system
normally.
Before using a feature, ensure that your license supports the feature.
sh ns license
License status:
Web Logging: YES
Surge Protection: YES
.......
When you use the NetScaler appliance for the first time, you must enable a feature before you can use its functionality. If
you configure a feature before it is enabled, a warning message appears. T he configuration is saved but it applies only after
the feature is enabled.
enable feature lb cs
done
>show feature
Starting with NetScaler release 12.0 56.20, VPX Express for on-premise and cloud deployments does not require a license file
and it comes with the following features:
20 Mbps bandwidth
All NetScaler standard license features, except NetScaler Gateway
Maximum 250 SSL sessions
20 Mbps SSL throughput
You can upgrade the VPX Express License to the following two options:
2. NetScaler Pooled Capacity license for VPX instances. For more information, see NetScaler Pooled Capacity.
If all licenses are occupied, no additional connections can be opened until a user ends a session or the administrator
terminates the session using the configuration utility. When a connection is closed, the license is released and can be used
for a new user.
You need the following information before going to the Citrix Web site for the universal license.
Your user ID and password f or My Cit rix
Register at My Citrix (www.mycitrix.com) to receive your user ID and password.
Note: If you cannot locate either the license code or your user ID and password, contact Citrix Customer Service.
T he host name of t he Net Scaler Gat eway
T he entry field for this name on My Citrix is case-sensitive, so make sure that you copy the host name exactly as it is
configured on the NetScaler.
T he number of licenses you want t o include in t he license f ile
You do not have to download all of the licenses you are entitled to at once. For example, if your company purchased 100
licenses, you can choose to download 50. You can allocate the rest in another license file at a later time. Multiple license
files can be installed on the NetScaler Gateway.
Note: Before obtaining your licenses, make sure you configure the host name of the NetScaler using the Setup Wizard and
then restart the NetScaler.
To obtain your universal license
1. In a Web browser, go to http://www.citrix.com/ and click My Citrix.
2. Enter your user name and password. If this is the first time you are logging on to the site, you are asked for additional
background information.
3. Under My T ools, point to Choose a toolbox, and click Activation System/Manage Assets.
4. In the Current T ool drop-down menu, select Activate/Allocate and follow the directions to obtain your license file.
T o install the license, see "Installing the License". After installation, verify that the license was installed correctly.
T his section provides information about upgrading and downgrading a NetScaler appliance (MPX and VPX) firmware. It
includes the following topics:
For information about upgrading a NetScaler SDX appliance, see Single Bundle Upgrade.
T he licensing framework and types of licenses. A software edition upgrade might require new licenses, such as upgrading
from the standard edition to the enterprise edition, the standard edition to the platinum edition, or the enterprise
edition to the platinum edition. Existing NetScaler licenses continue to work when you upgrade to version 12.0.For more
information, see Licensing.
Check for New and deprecated commands, parameters, and SNMP OIDs.
Check for NetScaler Hardware and Software Compatibility Matrix.
If the NetScaler Gateway logon page is customized, then make sure that the UI theme is set to default.
Review the LOM Firmware Upgrade page, if you are upgrading LOM.
Download the NetScaler firmware from the download page. For the detailed steps to download the NetScaler firmware,
see the "How to download and update the NetScaler Firmware" section in this article CT X205476.
Perform a back up of configuration file, customization file, certificates, monitor scripts, license files, and so on either
manually or refer to the following documentation for back up using NetScaler CLI or GUI - Backing up and Restoring the
NetScaler Appliance.
Validate the integrity of the NetScaler Appliance and check available space before performing an upgrade. For more
information about how to free up storage space, see https://support.citrix.com/article/CT X133588
For more information about prerequisites for upgrading or downgrading the NetScaler firmware, see these support articles:
CT X126793: Best Practices for Upgrading NetScaler or NetScaler Gateway Appliances
CT X220371: Must Read Articles Before and After Upgrading NetScaler
When upgrading from release 10.0, 10.1, 10.5, 11.0, or 11.1, you have the option to use the NetScaler GUI or the CLI.
You cannot upgrade to NetScaler 12.0 from the following builds by using the Upgrade Wizard of the NetScaler GUI:
Note
If your NetScaler appliance runs any 9.x or lower release, visit the Product Matrix site for more information.
Follow these steps to upgrade a standalone NetScaler appliance running release 10.0, 10.1, 10.5, 11.0, or 11.1 to release 12.0
by using the GUI.
1. In a web browser, type the IP address of the NetScaler, for example http://10.102.29.50.
2. In User Name and Password, type the administrator credentials (nsroot/nsroot) and then click Log On .
3. From the GUI, click Syst em Upgrade .
4. From the Choose F ile drop-down menu choose the appropriate option: Local or Appliance . If you want to use the
Appliance option, the firmware needs to be uploaded to the NetScaler appliance first. You can use any file tranfer method
After the upgrade, close all browser instances and clear your computer's cache before accessing the appliance.
Follow these steps to upgrade a standalone NetScaler appliance running release 10.0, 10.1, 10.5, 11.0, or 11.1 to release 12.0:
In the following procedure, <release> and <releasenumber> represent the release version you are upgrading to, and
<targetbuildnumber> represents the build number that you are upgrading to. T he procedure includes optional steps to avoid
losing any updates that are pushed to the /etc directory during the upgrade.
1. Use an SSH client, such as PuT T y, to open an SSH connection to the appliance.
2. Log on to the appliance by using the administrator credentials. Save the running configuration. At the prompt, type:save
config
3. Create a copy of the ns.conf file. At the shell prompt, type:
1. cd /nsconfig
2. cp ns.conf ns.conf.NS<currentreleasenumber><currentbuildnumber>
You should backup the configuration file to another computer.
4. (Optional) If you have modified some of the following files in the /etc directory, and copied them to /nsconfig to
maintain persistency, any updates that are pushed to the /etc directory during the upgrade might be lost:
ttys
resolv.conf
sshd_config
host.conf
newsyslog.conf
host.conf
httpd.conf
rc.conf
syslog.conf
crontab
monitrc
To avoid losing these updates, create a /var/nsconfig_backup directory, and move the customized files to this directory.
T hat is, move any files that you modified in /etc directory and copied to /nsconfig by running the following command:
cp /nsconfig/<filename> /var/nsconfig_backup
Example:
cp /nsconfig/syslog.conf /var/nsconfig_backup
5. Create a location for the installation package. At the shell prompt type:
cd /var/nsinstall
mkdir <releasenumber>nsinstall
6. Copy the already downloaded NetScaler firmware to the directory that you created for it in step 5, by using any file
transferring method such as WinSCP. See the Before You Begin section for more information about downloading the
NetScaler firmware.
8. Run the installns script to install the new version of the system software. T he script updates the /etc directory. Example:
./installns
10. (Optionally) If you've created a copy of the ns.conf file in the Before You Begin section, do the following:
1. Manually compare the files in /var/nsconfig_backup and /etc and make appropriate changes in /etc.
login: nsroot
Password: nsroot
Done
> shell
root@NSnnn# cd /var/nsinstall
root@NSnnn# cd 12.0nsinstall
root@NSnnn# cd build_43.1
ftp> bye
root@NSnnn# ./installns
...
...
...
...
To use NIT RO API to upgrade or downgrade a NetScaler appliance, see Automate NetScaler Upgrade and Downgrade with
a Single API.
In release 10.1 build 122.17, the script files for user monitors are at a new location. If you upgrade an appliance or virtual
appliance to release 10.1 build 122.17 or later, the changes are as follows:
A new directory named conflicts is created in /nsconfig/monitors/ and all the built-in scripts of the previous builds are
moved to this directory.
All new built-in scripts are available in the /netscaler/monitors/ directory. All custom scripts are available in the
/nsconfig/monitors/ directory.
You must save a new custom script in the /nsconfig/monitors/ directory.
After the upgrade is completed, if a custom script is created and saved in the /nsconfig/monitors/ directory with the
same name as that of a built-in script, the script in the /netscaler/monitors/ directory takes priority. T hat is, the custom
script is not run.
If you provision a virtual appliance running release 10.1 build 122.17 or later, the changes are as follows:
For more information about user monitors, see "Understanding User Monitors."
Update the NetScaler software when an update is available, for better performance. A NetScaler update can include
feature improvements, performance fixes, or enhancements. Make sure you read the release notes to see what fixes and
enhancements are available in the update. To check and install a software update, do the following.
1. In the NetScaler home page, click Check f or Updat e from the nsroot drop-down menu at the top right corner of the
page.
2. In the Lat est Syst em Sof t ware Updat es Available page, check the available software update that you can install.
3. Click Download to download the installation package from the Citrix download website.
4. After you have downloaded the software package, install the update through either CLI or GUI procedure. For more
information, see Upgrading a NetScaler standalone appliance.
Note
T he Che ck fo r Upda te link is accessible only if you log into the NetScaler GUI through HT T P protocol and not through HT T PS
protocol.
Note
Loss in configuration might occur when downgrading. You should compare the configurations before and after the downgrade,
and then manually reenter any missing entries.
Follow the steps given below to downgrade a NetScaler standalone appliance running release 12.0 to an earlier release.
In this procedure, <release> and <releasenumber> represent the release version you are downgrading to, and
<targetbuildnumber> represents the build number that you are downgrading to.
1. Open an SSH connection to the NetScaler appliance by using an SSH client, such as PuT T Y.
2. Log on to the NetScaler appliance by using the administrator credentials. Save the running configuration. At the prompt,
type:
save config
Note: ns.conf.NS<releasenumber> is the backup configuration file that is automatically created when the system
software is upgraded from release version <releasenumber> to the current release version. T here may be some loss in
configuration when downgrading. After the appliance restarts, compare the configuration saved in step 3 with the
running configuration, and make any adjustments for features and entities configured before the downgrade. Save the
running configuration after making the changes.
5. If routing is enabled, the ZebOS.conf file will contain the configuration. At the shell prompt, type:
1. cd /nsconfig
2. cp ZebOS.conf ZebOS.conf.NS
3. cp ZebOS.conf.NS<targetreleasenumber> ZebOS.conf
6. Change directory to /var/nsinstall/<releasenumber>nsinstall, or create one if it does not exist.
7. Change directory to build_<targetbuildnumber>, or create one if it does not exist.
8. Download or copy the installation package (build-<release>-<targetbuildnumber>.tgz) to this directory and extract the
contents of the installation package.
1.
If the free space available on the flash drive is insufficient to install the new build, the NetScaler appliance aborts the
installation. Manually clean up the flash drive and restart the installation.
login: nsroot
Password: nsroot
Done
> shell
root@NSnnn# cd /var/nsinstall
root@NSnnn# cd 10.5nsinstall
root@NSnnn# cd build_57
ftp> bye
root@NSnnn# ./installns
...
...
...
Before you start a NetScaler firmware upgrade on an HA pair, read the prerequisites mentioned in the Before You Begin
section. Also, you need to consider a few HA-specific points.
Points to Note
Upgrade an HA Pair to Release 12.0 by Using the GUI
Upgrade an HA Pair Release 12.0 by Using the CLI
First upgrade the secondary node, and then the primary node.
If the two nodes in an HA configuration are running different NetScaler software releases, the following information
does not get synchronized on the primary and secondary nodes:
Configuration propagation and synchronization
States of the services
Connection failover sessions
Persistence sessions
T he above information might not get synchronized on the primary and secondary nodes if the two nodes are running
different builds of the same release. Refer to the Known Issues section of the release notes to check if your NetScaler
build has this issue.
Synchronization of the files in the All mode of the Sync HA files command works successfully if the two nodes in an HA
configuration are running different NetScaler software releases, or the two nodes are running different builds of the
same release. For more information, see Synchronising Configuration Files in High Availability Setup.
When upgrading from release 10.0, 10.1, 10.5, or 11.0 you have the option to use the configuration utility or the command
line interface.
You cannot upgrade to NetScaler 11.1 from the following builds by using the Upgrade Wizard of the NetScaler GUI:
All builds of NetScaler 10.1
Any build before Build 57.x of NetScaler 10.5
If your NetScaler appliance runs any 9.x or lower release, visit the Product Matrix site for more information.
In the following procedure, machine A is the primary node and machine B is the secondary node before the upgrade.
1. Log on to the secondary node and perform the upgrade as described in "To upgrade a standalone NetScaler running
release 10.0, 10.1, 10.5, 11.0, or 11.1 by using the configuration utility."
Note
Before upgrading the primary node (machine A), you have the option to test the new release by entering the force failover
command at the command line interface on the secondary node (machine B). When you do so, machine B becomes the primary
node. If machine B does not function as expected, enter the force failover command at the command line interface on the new
primary node (machine B) forcing it to again become the secondary node, and contact Citrix Customer Service before proceeding. If
machine B properly assumes the role of primary node, proceed with upgrading the former primary node (machine A).
2. Log on to the primary node and perform the upgrade as described in "Upgrade a NetScaler Standalone Appliance to
Release 12.0 by Using the GUI".
1. Follow the procedure for upgrading a standalone node as described in "Upgrade a NetScaler Standalone Appliance to
Release 12.0 by Using the CLI". T he procedure includes optional steps to avoid losing any updates that are pushed to the
/etc directory during the upgrade.
2. After the appliance restarts, log on with the administrator credentials and enter the show ha nodecommand to verify
that the appliance is a secondary node.
3. Test the new build by entering the force failover command on the secondary node (machine B). At the command prompt
type force failover.
4. When you do so, machine B becomes the primary node. If machine B does not function as expected, enter the force
failover command on the new primary node (machine B) forcing it to again become the secondary node, and contact Citrix
Customer Service before proceeding.
Enter the show ha node command to verify that machine B is the new primary node.
Password: nsroot
Done
show ha node
2 nodes:
1) Node ID: 0
IP: 10.0.4.2
Node State: UP
...
...
Done
Note
After machine B is upgraded successfully, both synchronization and propagation are automatically disabled until you upgrade
machine A.
6. After the appliance restarts, log on by using the administrator credentials, and enter the show ha nodecommand to verify
that the appliance is a secondary node and that synchronization is disabled.
Note
After both nodes are upgraded successfully, synchronization and propagation are automatically enabled.
7. After successfully upgrading both the nodes, run the show ha node command to verify that synchronization and
propagation are enabled on the primary node and synchronization is successful and propagation is enabled on the
secondary node.
Here's an example configuration of the new primary node (machine B) and the new secondary node (machine A).
Node ID: 0
IP: 10.0.4.2
Node State: UP
...
...
Propagation: ENABLED
...
...
Done
Node ID: 0
IP: 10.0.4.11
Node State: UP
..
..
Propagation: ENABLED
...
...
Done
Machine B (original secondary node) is now the primary node and machine A (original primary node) is now the secondary
node.
Note
You can enter the force failover command again to make machine A (original primary node) as the primary node and machine B
(original secondary node) as the secondary node.
For additional information, see this support article "How to Upgrade Software on NetScaler Appliances in High Availability
Setup."
To downgrade the system software on NetScaler units in a high availability pair, you need to downgrade the software first
on the secondary node and then on the primary node. For instructions on downgrading each node separately, see
"Downgrading a NetScaler Standalone Appliance".
Important
Loss in configuration might occur when downgrading. You should compare the configurations before and after the downgrade,
and then manually re-enter any missing entries.
For best results, use the following resources to troubleshoot an issue related to installing, upgrading, or downgrading a
NetScaler appliance:
T he configuration files from the appliance. In case of a High Availability pair, the configuration files from both appliances.
T he following files from the appliance(s):
T he relevant newnslog files.
T he ns.log file.
T he messages file.
A network topology diagram.
Following are the most common installation, upgrade, and downgrade issues, and tips for resolving them:
Issue
T he NetScaler appliance is not accessible after the software downgrade
Cause
During the software downgrade process, if the configuration file of the existing release and build does not match the
configuration file of the earlier release and build, the appliance cannot load the configuration, and the default IP address
is assigned to the appliance.
Resolut ion
Cause
Some migration commands are built in for upgrading to the next release. Such commands might not be available across
releases.
Resolut ion
Verify the path of the upgrade process. Citrix recommends upgrading by one release at a time. For example, if the
softer needs to be upgraded from NetScaler release 9.2 to NetScaler release 10.1, the following is the recommended
Command failed on the secondary node but succeeded on the primary node.
Resolut ion
Do not run any dependent commands (set /unset /bind /unbind) when High Availability (HA) synchronization is in
progress.
Issue
During an upgrade process, traffic does not pass through the new primary node when you run the force failover
command.
Resolut ion
Check for problems with the network topology and the switch configurations.
Run the set L2param -garpreply ENABLED command to enable the GARP reply.
T ry using VMAC if not already used.
Run the sendarp – a command from the primary node.
Issue
In an HA pair, after you run the force HA failover command the devices keep rebooting. T he secondary device does not
come up after an upgrade.
Resolut ion
Check to see if the /var directory is full. If so, remove the old installation files. Run the df – h command to show the
available disk space.
Issue
After upgrading an HA pair, one of the nodes is listed as state UNKNOWN.
Resolut ion
Check to see if both nodes are running the same build. If the builds are not same and HA nodes have a version
mismatch, some of the fields are shown as UNKNOWN when you run the show ha node command.
Check to see if the secondary appliance is reachable.
Issue
After you upgrade the NetScaler appliance, the interface shows most of the load balancing virtual servers and services
are DOWN.
Resolut ion
Verify that the SNIP address is active on the secondary appliance. Also, type the show service command to see if the
service is running.
Issue
Resolut ion
Resolut ion
Issue
In an HA pair, some features do not get synchronized after an upgrade is performed.
Resolut ion
Run the sync ha file misc command to synchronize the configurations files from the primary node to secondary node.
Issue
During reboot, the following error message appears:
Resolut ion
Make sure that no command in the ns.conf file exceeds the 255 byte limit. In commands that create policies that are
too long for the 255-byte limit, you can use pattern sets to shorten the policies.
Example:
add cs policy p11 -rule 'HTTP.REQ.URL.ENDSWITH_ANY("ctx_file_extensions")'
Done
ctx_file_extensions is a default patset that covers a large number of extensions. In addition to the default pattern sets,
you can create user-defined pattern sets. Add a patset by running the following command:
add patset <name>
Note: Patsets are supported only in release 9.3 or later.
Issue
When upgrading a NetScaler VPX appliance, I am told to free up space in /var. What files do I remove?
Resolut ion
Remove the old installation files from /var/tmp/ directory. Also remove unwanted files from /flash.
Issue
T here is no connectivity to the graphical user interface (GUI) when you run the force HA failover command on the
secondary appliance.
Resolut ion
Issue
After performing an upgrade, and when I click on any link on the GUI that has to load a java applet (Upgrade Wizard or
license Wizard), the following error message appears: GUI version does not mat ch wit h t he kernel version. P lease
close t his inst ance, clear java plug-in cache and reopen .
Resolut ion
Note
T hese troubleshooting steps also apply to issues with configuration loss when downgrading the software across multiple releases.
For any other issue, see the release notes, Knowledge Center articles, and FAQs.
New Commands
New Parameters
Deprecated Commands
Deprecated Parameters
New SNMP OIDs
Deprecated SNMP OIDs
Co m m a nd Gro up Co m m a nd
Co m m a nd Gro up Co m m a nd
Co m m a nd Gro up addmcluster
Co m a ndinstance [-retainConnectionsOnCluster]
set cluster instance [-retainConnectionsOnCluster]
show cluster instance [-retainConnectionsOnCluster]
add cluster node [-delay]
Clus te r set cluster node [-delay]
show cluster node [-syncState]
show cluster node [-delay]
show cluster node [-curPassiveT imeout]
show cluster node [-isLearnedAsPassive]
login ns [-partitionid]
add ns ip6 [-networkRoute]
add ns ip6 [-tag]
add ns ip6 [-ownerDownResponse]
set ns ip6 [-ownerDownResponse]
set ns ip6 [-networkRoute]
set ns ip6 [-tag]
show ns ip6 [-networkRoute]
show ns ip6 [-tag]
show ns ip6 [-ownerDownResponse]
add ns ip [-networkRoute]
add ns ip [-tag]
add ns ip [-ownerDownResponse]
set ns ip [-networkRoute]
set ns ip [-tag]
set ns ip [-ownerDownResponse]
show ns ip [-networkRoute]
show ns ip [-tag]
show ns ip [-ownerDownResponse]
add ns tcpProfile [-nileD1Percent]
add ns tcpProfile [-nileD2Percent]
add ns tcpProfile [-nileD3Percent]
add ns tcpProfile [-nileAlphaMax]
add ns tcpProfile [-nileAlphaMinPercent]
add ns tcpProfile [-nileBetaMaxPercent]
add ns tcpProfile [-nileBetaMinPercent]
add ns tcpProfile [-nileRttFactor]
add ns tcpProfile [-nileRttFilter]
add ns tcpProfile [-burstRateControl]
add ns tcpProfile [-tcprate]
add ns tcpProfile [-rateqmax]
add ns tcpProfile [-DropHalfClosedConnOnT imeout]
add ns tcpProfile [-DropEstConnOnT imeout]
set ns tcpProfile [-nileD1Percent]
set ns tcpProfile [-nileD2Percent]
set ns tcpProfile [-nileD3Percent]
set ns tcpProfile [-nileAlphaMax]
set ns tcpProfile [-nileAlphaMinPercent]
set ns tcpProfile [-nileBetaMaxPercent]
set ns tcpProfile [-nileBetaMinPercent]
set ns tcpProfile [-nileRttFactor]
set ns tcpProfile [-nileRttFilter]
T he following table lists the commands that are deprecated in version 12.0.
Co m m a nd Gro up Co m m a nd
stat dos
stat dos policy
rm dos policy
DOS set dos policy
show dos policy
stat dos policy
show dos stats
NS clear ns trafficDomain
stat pq
add pq policy
rm pq policy
PQ set pq policy
show pq policy
stat pq policy
show pq stats
stat sc
add sc policy
rm sc policy
T he following table lists the parameters that are deprecated in version 12.0.
Co m m a nd Gro up Co m m a nd
pbrTotNullDrop,1.3.6.1.4.1.5951.4.1.1.22.5.25
pbr6TotNullDrop,1.3.6.1.4.1.5951.4.1.1.22.7.25
tcpOptimizationEnabled,1.3.6.1.4.1.5951.4.1.1.46.131
tcpOptimizationBypassed,1.3.6.1.4.1.5951.4.1.1.46.132
sslTotECDSAAuthorizations,1.3.6.1.4.1.5951.4.1.1.47.366
nsLsnNAT 64GlobalStatsGroup,1.3.6.1.4.1.5951.4.1.1.83.6
ifT xCollisions,1.3.6.1.4.1.5951.4.1.1.54.1.14
ifT xExcessCollisions,1.3.6.1.4.1.5951.4.1.1.54.1.15
ifT xLateCollisions,1.3.6.1.4.1.5951.4.1.1.54.1.16
ifT xMultiCollisionErrors,1.3.6.1.4.1.5951.4.1.1.54.1.17
ifErrT xDeferred,1.3.6.1.4.1.5951.4.1.1.54.1.37
Command:
set httpProfile <profilename> -http2 ENABLED
SPDY HT T P/2
Ref page: https://docs.citrix.com/en-us/netscaler/12/system/http-
configurations/configuring-http2.html
Configuration:
# set session life [Global]
set appqoe parameter -sessionLife 300
SureConnect (SC) AppQoE # bind point is LB vserver only, doesn't work on service level like SC
# AppQoE use case example (traffic classification and loading screen)
Ref page: https://docs.citrix.com/en-us/netscaler/12/appexpert/appqoe.html
For more information, see AppQoE Use Cases topic.
Configuration:
# enable vserver level queueing
set appqoe parameter -avgwaitingclient 10
# setting PQ like actions, qDepth and polqDepth are present as well to configure
add appqoe action PRI_MEDIUM -priority MEDIUM
add appqoe action PRI_HIGH -priority HIGH -priqDepth 1000
add appqoe action PRI_LOW -priority LOW -polqDepth 1000
# four levels of priorities are present : HIGH, LOW, LOWEST, MEDIUM
AppQoE
Priority Queuing (PQ) # bind point LB vserver only
add appqoe policy text_medium -rule "HT T P.REQ.URL.PAT H.CONTAINS(\".html\")"
-action PRI_MEDIUM
add appqoe policy image_medium -rule
"HT T P.REQ.URL.PAT H.CONTAINS(\".jpg\")" -action PRI_MEDIUM
bind lb vserver v2 -policyName text_medium -priority 1
bind lb vserver v2 -policyName image_medium -priority 2
Configuration Steps:
1. enable feature AppFlow
2. add appflow action with clientside measurements enabled
1. add appflow action Appflow_act1 -collectors collector_1 -
AppFlow with Client Side
clientSideMeasurements ENABLED
HT MLInjection Measurements
3. add appflow policy with this action and bind to vserver/AppFlow global.
Ref page:
https://docs.citrix.com/en-us/netscaler/12/ns-ag-appflow-intro-wrapper-
con.html
Filter actions:
1. Use Responder RESET /DROP
1. RESET /DROP on 2. Use Responder RESPONDWIT H or REDIRECT
request side, 3. Use Rewrite RESET /DROP
2. ERRORCODE; 4. Use Rewrite INSERT _HT T P_HEADER/CORRUPT _HT T P_HEADER
3. RESET /DROP on 5. Use CS policy and action that select appropriate LB Vserver that can select that
Filter response side, service.
4. ADD/CORRUPT
5. FORWARD No te : Everything is done using Advanced policies.
Ref pages:
Responder: https://docs.citrix.com/en-
us/netscaler/12/appexpert/responder.html
Rewrite: https://docs.citrix.com/en-us/netscaler/12/appexpert/rewrite.html
Ref pages:
Q and S prefixes in HT T P.REQ and HT T P.RES
https://docs.citrix.com/en-us/netscaler/12/appexpert/policies-and-
Advanced expressions
expressions/ns-pi-adv-expr-ref.html
https://docs.citrix.com/en-us/netscaler/12/netscaler-cache-redirection-
Classic cache redirection
Advanced redirection policies gen-wrapper-10-con/cache-redirection-policies/configure-cache-
policy
redirection-policies.html
https://docs.citrix.com/en-us/netscaler/12/system/audit-
Audit SYSLOG Policy Advanced Audit SYSLOG Policy
logging/configuring-audit-logging.html
https://docs.citrix.com/en-us/netscaler/12/system/audit-
Audit NSLOG policy Advanced Audit NSLOG Policy
logging/configuring-audit-logging.html
https://docs.citrix.com/en-us/netscaler-gateway/12/authentication-
Authorization policy Advanced Authorization policy authorization/configure-authorization/ng-authorize-config-policy-
tsk.html
https://docs.citrix.com/en-us/netscaler-gateway/12/vpn-user-
Tunnel traffic policy Advanced Tunnel Traffic Policy
config/how-traffic-policies-work/ng-create-traffic-policy-tsk.html
https://docs.citrix.com/en-us/netscaler-gateway/12/vpn-user-
VPN traffic policy Advanced VPN Traffic Policy
config/how-session-policies-work.html
https://docs.citrix.com/en-us/netscaler-gateway/12/vpn-user-
VPN Session policy Advanced VPN Session Policy
config/how-session-policies-work.html
https://developer-docs.citrix.com/projects/netscaler-command-
Trace Classic expression Trace Advanced expression
reference/en/12.0/basic/nstrace/nstrace/
You can use the nspepi tool to convert commands, expressions, and configurations. For more information, see Converting
Expressions by Using NSPEPI Tool topic.
When using AppQoE as an alternative for SureConnect feature, you can refer to the following use case configurations.
Use Case 1: To limit simult aneous download of huge files and display loading screen
Use Case 2: To limit simult aneous download of huge files and display loading screen wit h alt ernat e cont ent
add appqoe action ACS_RESP -respondWith ACS -altContentsvcName s2 -altContentPath /netscaler/alt.html -maxConn
50
add appqoe policy POL_CRESP -rule "HT T P.REQ.URL.CONTAINS(\"tar.gz\")" -action CUST _RESP
T he AAA feature supports authentication, authorization, and auditing for all application traffic. To use AAA, you must
configure authentication virtual servers to handle the authentication process and traffic management virtual servers to
handle the traffic to web applications that require authentication. You also configure your DNS to assign FQDNs to each
virtual server. After configuring the virtual servers, you configure a user account for each user that will authenticate via the
NetScaler appliance, and optionally you create groups and assign user accounts to groups. After creating user accounts
and groups, you configure policies that tell the appliance how to authenticate users, which resources to allow users to
access, and how to log user sessions. To put the policies into effect, you bind each policy globally, to a specific virtual server,
or to the appropriate user accounts or groups. After configuring your policies, you customize user sessions by configuring
session settings and binding your session policies to the traffic management virtual server. Finally, if your intranet uses client
certs, you set up the client certificate configuration.
Before configuring AAA, you should be familiar with and understand how to configure load balancing, content switching,
and SSL on the NetScaler appliance.
T o understand how AAA works in a distributed environment, consider an organization with an intranet that its employees
access in the office, at home, and when traveling. T he content on the intranet is confidential and requires secure access.
Any user who wants to access the intranet must have a valid user name and password. T o meet these requirements, the
ADC does the following:
Redirects the user to the login page if the user accesses the intranet without having logged in.
Collects the user's credentials, delivers them to the authentication server, and caches them in a directory that is
accessible through LDAP.
Verifies that the user is authorized to access specific intranet content before delivering the user's request to the
application server.
Maintains a session timeout after which users must authenticate again to regain access to the intranet. (You can
configure the timeout.)
Logs the user accesses, including invalid login attempts, in an audit log.
Authentication requires that several entities: the client, the NetScaler appliance, the external authentication server if one is
used, and the application server, respond to each other when prompted by performing a complex series of tasks in the
correct order. If you are using an external authentication server, this process can be broken down into the following fifteen
steps.
1. T he client sends a GET request for a URL on the application server.
2. T he NetScaler appliance's traffic management virtual server redirects the request to the application server.
3. T he application server determines that the client has not been authenticated, and therefore sends an HT T P 200 OK
response via the T M vserver to the client. T he response contains a hidden script that causes the client to issue a POST
request for /cgi/tm.
4. T he client sends a POST request for /cgi/tm.
5. T he NetScaler appliance's authentication virtual server redirects the request to the authentication server.
6. T he authentication server creates an authentication session, sets and caches a cookie that consists of the initial URL
and the domain of the traffic management virtual server, and then sends an HT T P 302 response via the authentication
virtual server, redirecting the client to /vpn/index.html.
7. T he client sends a GET request for /vpn/index.html.
8. T he authentication virtual server redirects the client to the authentication server login page.
9. T he client sends a GET request for the login page, enters credentials, and then sends a POST request with the
credentials back to the login page.
10. T he authentication virtual server redirects the POST request to the authentication server.
11. If the credentials are correct, the authentication server tells the authentication virtual server to log the client in and
redirect the client to the URL that was in the initial GET request.
12. T he authentication virtual server logs the client in and sends an HT T P 302 response that redirects the client to the
initially requested URL.
If you use local authentication, the process is similar, but the authentication virtual server handles all authentication tasks
instead of forwarding connections to an external authentication server. T he following figure illustrates the authentication
process.
When an authenticated client requests a resource, the ADC, before sending the request to the application server, checks
the user and group policies associated with the client account, to verify that the client is authorized to access that
resource. T he ADC handles all authorization on protected application servers. You do not need to do any special
configuration of your protected application servers.
AAA-T M handles password changes for users by using the protocol-specific method for the authentication server. For most
protocols, neither the user nor the administrator needs to do anything different than they would without AAA-T M. Even
when an LDAP authentication server is in use, and that server is part of a distributed network of LDAP servers with a single
designated domain administration server, password changes are usually handled seamlessly. When an authenticated client
of an LDAP server changes his or her password, the client sends a credential modify request to AAA-T M, which forwards it
to the LDAP server. If the user's LDAP server is also the domain administration server, that server responds appropriately and
AAA-T M then performs the requested password change. Otherwise, the LDAP server sends AAA-T M an LDAP_REFERRAL
response to the domain administration server. AAA-T M follows the referral to the indicated domain administration server,
authenticates to that server, and performs the password change on that server.
When configuring AAA-T M with an LDAP authentication server, the system administrator must keep the following
conditions and limitations in mind:
AAA-T M assumes that the domain administration server in the referral accepts the same bind credentials as the original
server.
AAA-T M only follows LDAP referrals for password change operations. In other cases AAA-T M refuses to follow the
referral.
AAA-T M only follows one level of LDAP referrals. If the second LDAP server also returns a referral, AAA-T M refuses to
T he ADC supports auditing of all states and status information, so you can see the details of what each user did while
logged on, in chronological order. To provide this information, the appliance logs each event, as it occurs, either to a
designated audit log file on the appliance or to a syslog server. Auditing requires configuring the appliance and any syslog
server that you use.
At the command prompt, type the following commands to enable AAA and verify the configuration:
enable ns feature AAA
show ns feature
Example
To set up an aut hent icat ion virt ual server by using t he Net Scaler CLI
2. Configure an authentication virtual server. It must be of type SSL and make sure to bind SSL certificate-key pair to the
virtual server.
ns-cli-prompt> add aut hent icat ion vserver <name> SSL <ipaddress> <port >
3. Specify the FQDN of the domain for the authentication virtual server.
ns-cli-prompt > set aut hent icat ion vserver <name> -aut hent icat ionDomain <FQDN>
4. Associate the authentication virtual server to the relevant traffic management virtual server.
Not e: T he FQDN of the traffic management virtual server must be in the same domain as the FQDN of the
authentication virtual server for the domain session cookie to function correctly.
- Enable authentication.
- Specify the FQDN of the authentication virtual server as the authentication host of the traffic management virtual
server.
- [Optional] Specify the authentication domain on the traffic management virtual server.
Not e: If you do not configure the authentication domain, the appliance assigns an FQDN that consists of the FQDN of
the authentication virtual server without the hostname portion. For example, if domain name of the authentication
virtual server is t m.xyz.bar.com, the appliance assigns xyz.bar.com as the authentication domain.
5. Verify that both the virtual servers are UP and configure correctly.
To set up an aut hent icat ion virt ual server by using t he Net Scaler GUI
Navigate to Syst em > Set t ings , click Conf igure Basic f eat ures , and enable Aut hent icat ion, Aut horizat ion and
Audit ing .
Navigate to Securit y > AAA - Applicat ion T raf f ic > Virt ual Servers , and configure as required (refer to the
configurations provided in the CLI procedure provided above).
Navigate to Securit y > AAA - Applicat ion T raf f ic > Virt ual Servers , and check the details of the relevant
authentication virtual server.
T o configure an authentication virtual server and verify the configuration, at the command prompt type the following
commands in the order shown:
add authentication vserver <name> ssl <ipaddress>
show authentication vserver <name>
bind ssl certkey <certkeyName>
show authentication vserver <name>
set authentication vserver <name> -authenticationDomain <FQDN>
show authentication vserver <name>
Example
At the command prompt, type one of the following sets of commands to configure a T M virtual server and verify the
configuration:
set lb vserver <name> – authentication ON -authenticationhost <FQDN> [-authenticationdomain <authdomain>]
show lb vserver <name>
set cs vserver <name> – authentication ON -authenticationhost <FQDN> [-authenticationdomain <authdomain>]
show cs vserver <name>
Example
T his authentication profile can be associated with the relevant traffic management virtual servers.
For example, to create a profile with an authentication virtual server named "authVS".
Note: T he authentication weight or level will depend on the virtual server to which the traffic will bound. A session
that is created by authenticating against traffic management virtual server at given level cannot be used to access
traffic management virtual server at a higher level.
2. Bind the authentication profile to the relevant traffic management virtual servers.
For example, to bind authProfile1 to a load balancing virtual server named "vserver1".
In the Configuration tab, navigate to Security > AAA - Application Traf fic > Authentication Profile, and configure the
authentication profile as required.
You also create user accounts on the NetScaler appliance if you are using an external authentication server. In this case,
however, each user account must exactly match an account for that user on the external authentication server, and you
do not assign passwords to the user accounts that you create on the NetScaler. T he external authentication server
manages the passwords for users that authenticate with the external authentication server.
If you are using an external authentication server, you can still create local user accounts on the NetScaler appliance if, for
example, you want to allow temporary users (such as visitors) to log in but do not want to create entries for those users on
the authentication server. You assign a password to each local user account, just as you would if you were using local
authentication for all user accounts.
Each user account must be bound to policies for authentication and authorization. To simplify this task, you can create one
or more groups and assign user accounts to them. You can then bind policies to groups instead of individual user accounts.
To create a local AAA user account by using the command line interf ace
At the command prompt, type the following commands to create a local AAA user account and verify the configuration:
add aaa user <username> [– password <password>]
show aaa user
Example
At the command prompt, type the following command and, when prompted, type the new password:
set aaa user <username>
Example
To create AAA local groups and add users to them by using the command line interf ace
At the command prompt, type the following commands. T ype the first command one time, and type the second command
once for each user:
add aaa group <groupname>
show aaa group
Example
UserName: user-2
Done
To remove users f rom an AAA group by using the command line interf ace
At the command prompt, unbind users from the group by typing the following command once for each user account that is
bound to the group:
unbind aaa group <groupname> -username <username>
Example
First remove all users from the group. T hen, at the command prompt, type the following command to remove an AAA group
and verify the configuration:
rm aaa group <groupname>
show aaa group
You must bind each policy to put it into effect. You bind authentication policies to authentication virtual servers,
authorization policies to one or more user accounts or groups, and auditing policies both globally and to one or more user
accounts or groups.
When you bind a policy, you assign a priority to it. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer. In the NetScaler operating system, policy priorities work in reverse
order: the higher the number, the lower the priority. For example, if you have three policies with priorities of 10, 100, and
1000, the policy assigned a priority of 10 is performed first, then the policy assigned a priority of 100, and finally the policy
assigned an order of 1000. T he AAA feature implements only the first of each type of policy that a request matches, not
any additional policies of that type that a request might also match, so policy priority is important for getting the results
you intend.
You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate in the order you
want, by setting priorities with intervals of 50 or 100 between each policy when you bind the policies. You can then add
additional policies at any time without having to reassign the priority of an existing policy.
For additional information about binding policies on the NetScaler, see the Citrix NetScaler Traffic Management Guide at
"Traffic Management."
After a user authenticates to a TACACS server, the NetScaler ADC connects to the same TACACS server for all subsequent authorizations. When a primary TACACS server is unavailable, this feature
prevents delays while the ADC waits for the first TACACS server to time out before resending the authorization request to the second TACACS server.
Note: When authenticating through a T ACACS server, AAA-T M logs only successfully executed T ACACS commands, to prevent the logs from showing T ACACS commands that were entered by users
who were not authorized to execute them.
Starting from NetScaler 12.0 Build 57.x, the T erminal Access Controller Access-Control System (T ACACS) is not blocking the NetScaler AAA daemon while sending the T ACACS request. T he NetScaler
AAA daemon allows LDAP, and RADIUS authentication to proceed with the request. T he T ACACS authentication request resumes once T ACACS server acknowledges the T ACACS request.
CERT
Authenticates to the NetScaler appliance by using a client certificate, without reference to an external authentication server.
NEGOTIATE
Authenticates to a Kerberos authentication server. If there is an error in Kerberos authentication, NetScaler uses NT LM authentication.
SAML
Authenticates to a server that supports the Security Assertion Markup Language (SAML).
SAMLIDP
Configures the NetScaler ADC to serve as a Security Assertion Markup Language (SAML) Identity Provider (IdP).
WEB
Authenticates to a web server, providing the credentials that the web server requires in an HT T P request and analyzing the web server response to determine that user authentication was successful.
An authentication policy is comprised of an expression and an action. Authentication policies use NetScaler expressions.
After creating an authentication action and an authentication policy, bind it to an authentication virtual server and assign a priority to it. When binding it, also designate it as either a primary or a
secondary policy. Primary policies are evaluated before secondary policies. In configurations that use both types of policy, primary policies are normally more specific policies while secondary policies
are normally more general policies intended to handle authentication for any user accounts that do not meet the more specific criteria.
If you do not use LOCAL authentication, you need to add an explicit authentication action. To do this, at the command prompt, type the following command:
add authentication tacacsAction <name> -serverip <IP> [-serverPort <port>] [-authT imeout <positive_integer>] [ ... ]
Example
> add authentication tacacsaction Authn-Act-1 -serverip 10.218.24.65 -serverport 1812 -authtimeout 15 -tacacsSecret "minotaur" -authorization OFF -accounting ON -auditFailedCmds OFF -defau
To configure an authentication action by using the command line interf ace
To configure an existing authentication action, at the command prompt, type the following command:
set authentication tacacsAction <name> -serverip <IP> [-serverPort <port>] [-authT imeout <positive_integer>] [ ... ]
Example
> set authentication tacacsaction Authn-Act-1 -serverip 10.218.24.65 -serverport 1812 -authtimeout 15 -tacacsSecret "minotaur" -authorization OFF -accounting ON -auditFailedCmds OFF -defau
To remove an authentication action by using the command line interf ace
To remove an existing RADIUS action, at the command prompt, type the following command:
Note: In the configuration utility, the term server is used instead of action, but refers to the same task.
1. Navigate to Security > AAA - Application T raffic > Policies > Authentication.
2. In the details pane, on the Servers tab, do one of the following:
T o create a new authentication server, click Add.
T o modify an existing authentication server, select the server, and then click Open.
3. In the Create Authentication Server or Configure Authentication Server dialog box, type or select values for the parameters.
Name*— radiusActionName (Cannot be changed for a previously configured action)
Authentication T ype*— authtype (Set to RADIUS, cannot be changed)
IP Address*— serverip <IP>
To create and bind an authentication policy by using the command line interf ace
At the command prompt, type the following commands in the order shown to create and bind an authentication policy and verify the configuration:
add authentication negotiatePolicy <name> <rule> <reqAction>
show authentication localPolicy <name>
bind authentication vserver <name> -policy <policyname> [-priority <priority>] [-secondary]]
show authentication vserver <name>
Example
> add authentication localPolicy Authn-Pol-1 ns_true Done > show authentication localPolicy 1) Name: Authn-Pol-1 Rule: ns_true Request action: LOCAL Done > bind authentication vserver Auth-V
To modif y an existing authentication policy by using the command line interf ace
At the command prompt, type the following commands to modify an existing authentication policy:
set authentication localPolicy <name> <rule> [-reqaction <action>]
Example
At the command prompt, type the following command to remove an authentication policy:
rm authentication localPolicy <name>
Example
1. Navigate to Security > AAA - Application T raffic > Policies > Authentication, and then select the type of policy that you want to create.
2. In the details pane, on the Policies tab, do one of the following:
T o create a new policy, click Add.
T o modify an existing policy, select the action, and then click Edit.
3. In the Create Authentication Policy or Configure Authentication Policy dialog, type or select values for the parameters.
Name*— policyname (Cannot be changed for a previously configured action)
Authentication T ype*— authtype
Server*— authVsName
Expression*— rule (You enter expressions by first choosing the type of expression in the leftmost drop-down list beneath the Expression window, and then by typing your expression directly
into the expression text area, or by clicking Add to open the Add Expression dialog box and using the drop-down lists in it to construct your expression.)
4. Click Create or OK. T he policy that you created appears in the Policies page.
5. Click the Servers tab, and in the details pane do one of the following:
T o use an existing server, select it, and then click .
T o create a new server, click Add, and follow the instructions.
6. If you want to designate this policy as a secondary authentication policy, on the Authentication tab, click Secondary. If you want to designate this policy as a primary authentication policy, skip
this step.
7. Click Insert Policy.
8. Choose the policy you want to bind to the authentication virtual server from the drop-down list.
9. In the Priority column to the left, modify the default priority as needed to ensure that the policy is evaluated in the proper order.
10. Click OK. A message appears in the status bar, stating that the policy has been configured successfully.
Warning
Classic policy expression is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends you to
use Default (Advanced) policy expressions. You can also use the nspepi utility tool for the conversion.
As with other types of authentication policies, a Lightweight Directory Access Protocol (LDAP) authentication policy is
comprised of an expression and an action. After creating an authentication policy, you bind it to an authentication virtual
server and assign a priority to it. When binding it, you also designate it as either a primary or a secondary policy. In addition
to standard authentication functions, LDAP can search other active directory (AD) servers for user accounts for users that
do not exist locally. T his function is called referral support or referral chasing.
Normally you configure the NetScaler ADC to use the IP address of the authentication server during authentication. With
LDAP authentication servers, you can also configure the ADC to use the FQDN of the LDAP server instead of its IP address
to authenticate users. Using an FQDN can simplify an otherwise much more complex AAA configuration in environments
where the authentication server might be at any of several IP addresses, but always uses a single FQDN. To configure
authentication by using a server's FQDN instead of its IP address, you follow the normal configuration process except
when creating the authentication action. When creating the action, you use the serverName parameter instead of the
serverIP parameter, and substitute the server's FQDN for its IP address.
Before you decide whether to configure the ADC to use the IP or the FQDN of your LDAP server to authenticate users,
consider that configuring AAA to authenticate to an FQDN instead of an IP address adds an extra step to the
authentication process. Each time the ADC authenticates a user, it must resolve the FQDN. If a great many users attempt
to authenticate simultaneously, the resulting DNS lookups might slow the authentication process.
LDAP referral support is disabled by default and cannot be enabled globally. It must be explicitly enabled for each LDAP
action. You must also make sure that the AD server accepts the same binddn credentials that are used with the referring
(GC) server. To enable referral support, you configure an LDAP action to follow referrals, and specify the maximum number
of referrals to follow.
If referral support is enabled, and the NetScaler ADC receives an LDAP_REFERRAL response to a request, AAA follows the
referral to the active directory (AD) server contained in the referral and performs the update on that server. First, AAA looks
up the referral server in DNS, and connects to that server. If the referral policy requires SSL/T LS, it connects via SSL/T LS. It
then binds to the new server with the binddn credentials that it used with the previous server, and performs the operation
which generated the referral. T his feature is transparent to the user.
Note: T hese instructions assume that you are already familiar with the LDAP protocol and have already configured your
chosen LDAP authentication server.
For more information about setting up authentication policies in general, see Authentication Policies. For more information
about NetScaler expressions, which are used in the policy rule, see Policies and Expressions.
To enable LDAP ref erral support by using the command line interf ace
Example
Note: In the configuration utility, the term server is used instead of action, but refers to the same task.
1. Navigate to Security > AAA - Application T raffic > Policies > LDAP.
2. In the details pane, on the Servers tab, select the LDAP server that you want to configure, and then click Edit.
3. In the Configure Authentication Server dialog, scroll down to the Referrals check box, and select it.
4. In the Maximum Referral Level text box, type the maximum number of referrals to allow.
5. Click OK, and then click Close.
With key-based authentication, you can now fetch the list of public keys that are stored on the user object in LDAP server
through SSH. T he NetScaler appliance during role-based authentication (RBA) process must extract public SSH keys from
the LDAP server. T he retrieved public key, which is compatible with SSH, must allow you to log in through RBA method.
A new attribute “sshPublicKey” is introduced in the “add authentication ldapAction” and “set authentication ldapAction”
commands. By using this attribute, you can obtain the following benefits:
Can store the retrieved public key, and the LDAP action uses this attribute to retrieve SSH key information from LDAP
server.
Can extract attribute names of up to 24 KB.
Note: T he external authentication server, such as LDAP is used only to retrieve SSH key information. It is not used for
authentication purpose.
SSH daemon sends an AAA_AUT HENT ICAT E request with password field empty to NetScaler AAA daemon port.
If LDAP is configured to store the SSH public key, NetScaler AAA responds with “sshPublicKey” attribute along with
other attributes.
SSH daemon verifies these keys with the client keys.
SSH daemon passes user name in the request payload, and NetScaler AAA returns the keys specific to this user along
with generic keys.
To configure the sshPublicKey attribute, at the command prompt type the following commands:
With add operation, you can add “sshPublicKey” attribute while configuring ldapAction command.
add authentication ldapAction <name> {-serverIP
<ip_addr|ipv6_addr|*> | {-serverName <string>}} [-serverPort <port>] … [-Attribute1 <string>] … [-Attribute16 <string>] [-
sshPublicKey <string>] [-authentication off]
With set operation, you can configure “sshPublicKey” attribute to an already added ldapAction command.
set authentication ldapAction <name> [-sshPublicKey
<string>] [-authentication off]
Warning
T he authentication negotiate policy is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends
you to use the advanced authentication policy (“add authentication Policy”). You can also use the nspepi utility tool for the
conversion.
As with other types of authentication policies, a Negotiate authentication policy is comprised of an expression and an
action. After creating an authentication policy, you bind it to an authentication virtual server and assign a priority to it.
When binding it, you also designate it as either a primary or a secondary policy.
In addition to standard authentication functions, the Negotiate Action command can now extract user information from a
keytab file instead of requiring you to enter that information manually. If a keytab has more than one SPN, AAA selects the
correct SPN. You can configure this feature at the NetScaler command line, or by using the configuration utility.
Note: T hese instructions assume that you are already familiar with the LDAP protocol and have already configured your
chosen LDAP authentication server.
To configure AAA to extract user inf ormation f rom a keytab file by using the command line interf ace
Example
Note: In the configuration utility, the term server is used instead of action, but refers to the same task.
1. Navigate to Security > AAA - Application T raffic > Policies > Negotiate.
2. In the details pane, on the Servers tab, do one of the following:
If you want to create a new Negotiate action, click Add.
If you want to modify an existing Negotiate action, in the data pane select the action, and then click Edit.
3. If you are creating a new Negotiate action, in the Name text box, type a name for your new action. T he name can be
from one to 127 characters in length and can consist of upper- and lowercase letters, numbers, and the hyphen (-) and
underscore (_) characters. If you are modifying an existing Negotiate action, skip this step. T he name is read-only; you
cannot change it.
4. Under Negotiate, if the Use Keytab file check box is not already checked, check it.
5. In the Keytab file path text box, type the full path and filename of the keytab file that you want to use.
6. In the Default authentication group text box, type the authentication group that you want to set as default for this
user.
7. Click Create or OK to save your changes.
Normally you configure the NetScaler ADC to use the IP address of the authentication server during authentication. With
RADIUS authentication servers, you can now configure the ADC to use the FQDN of the RADIUS server instead of its IP
address to authenticate users. Using an FQDN can simplify an otherwise much more complex AAA configuration in
environments where the authentication server might be at any of several IP addresses, but always uses a single FQDN. To
configure authentication by using a server's FQDN instead of its IP address, you follow the normal configuration process
except when creating the authentication action. When creating the action, you substitute the serverName parameter for
the serverIP parameter.
Before you decide whether to configure the ADC to use the IP or the FQDN of your RADIUS server to authenticate users,
consider that configuring AAA to authenticate to an FQDN instead of an IP address adds an extra step to the
authentication process. Each time the ADC authenticates a user, it must resolve the FQDN. If a great many users attempt
to authenticate simultaneously, the resulting DNS lookups might slow the authentication process.
Note: T hese instructions assume that you are already familiar with the RADIUS protocol and have already configured your
chosen RADIUS authentication server.
For more information about setting up authentication policies in general, see "Authentication Policies." For more
information about NetScaler expressions, which are used in the policy rule, see the Citrix NetScaler Policy Configuration and
Reference Guide at "Policies and Expressions."
To add an authentication action f or a RADIUS server by using the command line interf ace
If you authenticate to a RADIUS server, you need to add an explicit authentication action. To do this, at the command
prompt, type the following command:
add authentication radiusAction <name> [-serverip <IP> | -serverName] <FQDN>] [-serverPort <port>] [-authT imeout
<positive_integer>] {-radKey } [-radNASip ( ENABLED | DISABLED )] [-radNASid <string>] [-radVendorID <positive_integer>]
[-radAttributeT ype <positive_integer>] [-radGroupsPrefix <string>] [-radGroupSeparator <string>] [-passEncoding
<passEncoding>] [-ipVendorID <positive_integer>] [-ipAttributeT ype <positive_integer>] [-accounting ( ON | OFF )] [-
pwdVendorID <positive_integer> [-pwdAttributeT ype <positive_integer>]] [-defaultAuthenticationGroup <string>] [-
callingstationid ( ENABLED | DISABLED )]
Example
T he following example adds a RADIUS authentication action named Authn-Act-1, with the server IP 10.218.24 .65, the
server port 1812, the authentication timeout 15 minutes, the radius key WareTheLorax, NAS IP disabled, and NAS ID NAS1.
To configure an existing RADIUS action, at the NetScaler command prompt, type the following command:
set authentication radiusAction <name> [-serverip <IP> | -serverName] <FQDN>] [-serverPort <port>] [-authT imeout
<positive_integer>] {-radKey } [-radNASip ( ENABLED | DISABLED )] [-radNASid <string>] [-radVendorID <positive_integer>]
[-radAttributeT ype <positive_integer>] [-radGroupsPrefix <string>] [-radGroupSeparator <string>] [-passEncoding
<passEncoding>] [-ipVendorID <positive_integer>] [-ipAttributeT ype <positive_integer>] [-accounting ( ON | OFF )] [-
pwdVendorID <positive_integer> [-pwdAttributeT ype <positive_integer>]] [-defaultAuthenticationGroup <string>] [-
callingstationid ( ENABLED | DISABLED )]
To remove an authentication action f or an external RADIUS server by using the command line interf ace
To remove an existing RADIUS action, at the command prompt, type the following command:
Note: In the configuration utility, the term server is used instead of action, but refers to the same task.
1. Navigate to Security > AAA - Application T raffic > Policies > Authentication > Radius
2. In the details pane, on the Servers tab, do one of the following:
T o create a new RADIUS server, click Add.
T o modify an existing RADIUS server, select the server, and then click Edit.
3. In the Create Authentication RADIUS Server or Configure Authentication RADIUS Server dialog, type or select values for
the parameters. T o fill out parameters that appear beneath Send Calling Station ID, expand Details.
Name*— radiusActionName (Cannot be changed for a previously configured action)
Authentication T ype*— authtype (Set to RADIUS, cannot be changed)
Server Name / IP Address*— Choose either Server Name or Server IP
Server Name*— serverName <FQDN>
IP Address*— serverIp <IP> If the server is assigned an IPv6 IP address, select the IPv6 check box.
Port*— serverPort
T ime-out (seconds)*— authT imeout
Secret Key*— radKey (RADIUS shared secret.)
Confirm Secret Key*— T ype the RADIUS shared secret a second time. (No command line equivalent.)
Send Calling Station ID— callingstationid
Group Vendor Identifier— radVendorID
Group Attribute T ype— radAttributeT ype
IP Address Vendor Identifier— ipVendorID
pwdVendorID— pwdVendorID
Password Encoding— passEncoding
Default Authentication Group— defaultAuthenticationGroup
NAS ID— radNASid
Enable NAS IP address extraction— radNASip
Warning
T he Web authentication policy is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends you
to use the advanced authentication policy (“add authentication Policy”). You can also use the nspepi utility tool for the conversion.
AAA-T M is now able to authenticate a user to a web server, providing the credentials that the web server requires in an
HT T P request and analyzing the web server response to determine that user authentication was successful. As with other
types of authentication policies, a Web authentication policy is comprised of an expression and an action. After creating an
authentication policy, you bind it to an authentication virtual server and assign a priority to it. When binding it, you also
designate it as either a primary or a secondary policy.
To set up web-based authentication with a specific web server, first you create a web authentication action. Since
authentication to web servers does not use a rigid format, you must specify exactly which information the web server
requires and in which format when creating the action. To do this, you create an expression in NetScaler default syntax
that contains the following items:
For all other parameters, follow the normal rules for the add authentication action command.
Next you create a policy associated with that action. T he policy is similar to an LDAP policy, and like LDAP policies uses
NetScaler classic syntax.
Note: T hese instructions assume that you are already familiar with the authentication requirements of the web server(s) to
which you want to authenticate, and have already configured the web authentication server.
To configure a Web authentication action by using the command line interf ace
To create a web authentication action at the command line, at the command line type the following command:
add authentication webAuthAction <name> -serverIP <ip_addr|ipv6_addr|*> -serverPort <port|*> [-fullReqExpr <string>] -
scheme ( http | https ) -successRule <expression> [-defaultAuthenticationGroup <string>] [-Attribute1 <string>] [-
Attribute2 <string>] [-Attribute3 <string>] [-Attribute4 <string>] [-Attribute5 <string>] [-Attribute6 <string>] [-Attribute7
<string>] [-Attribute8 <string>] [-Attribute9 <string>] [-Attribute10 <string>] [-Attribute11 <string>] [-Attribute12 <string>] [-
Attribute13 <string>] [-Attribute14 <string>] [-Attribute15 <string>] [-Attribute16 <string>]
Example
Warning
T he Authentication local policy policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to
use the Advanced Authentication policy (“add authentication Policy”). You can also use the nspepi utility tool for the conversion.
If you know exactly how you want an authentication policy to be configured, you can use the advanced authentication
policy dialog to create the policy quickly.
1. Navigate to Security > AAA - Application T raffic > Policies > Authentication > Advanced Policies, and then select Policy.
2. In the details pane do one of the following:
T o create a new policy, click Add.
T o modify an existing policy, select the policy, and then click Edit.
3. In the Create Authentication Policy or Configure Authentication Policy dialog box, type or select values for the
parameters.
Name*— T he policy name. Cannot be changed for a previously configured policy.
Action T ype*— T he policy type: Cert, Negotiate, LDAP, RADIUS, SAML, SAMLIDP, T ACACS, or WEBAUT H.
Action*— T he authentication action (profile) to associate with the policy. You can choose an existing authentication
action, or click the plus and create a new action of the proper type.
Log Action— T he audit action to associate with the policy. You can choose an existing audit action, or click the plus
and create a new action.
Expression*— T he rule that selects connections to which you want to apply the action that you specified. T he rule
can be simple ("true" selects all traffic) or complex. You enter expressions by first choosing the type of expression in
the leftmost drop-down list beneath the Expression window, and then by typing your expression directly into the
expression text area, or by clicking Add to open Add Expression dialog box and using the drop-down lists in it to
construct your expression.)
Comment— You can type a comment that describes the type of traffic that this authentication policy will apply to.
Optional.
4. Click Create or OK, and then click Close. If you created a policy, that policy appears in the Authentication Policies and
Servers page.
To do this, associate an authorization policy to each of the users, either individually or by associating the policy to a group
of users. T he authorization policy must specify the following:
Rule. T he resource to which access must be authorized. T his can be specified by using basic or advanced expressions.
Action. Whether access to the resource must be allowed or denied.
By default, access to all resources within an application is DENIED to all users. However, you can change this default
authorization action to ALLOW access to all users (by setting the session parameters in session profile or by setting the
global session parameters).
Warning
For optimum security, Citrix recommends that you do not to change the default authorization action from DENY to ALLOW. Instead,
it is advised to create specific authorization policies for users who need access to specific resources.
T he following points explain the behavior of advanced and classic authorization policies for traffic management and VPN
requests:
T he advanced authorization policies can be bound only to the traffic management virtual server (load balancing or
content switching). If you want rules for a specific user or group, you can configure rules accordingly. For example,
HT T P.REQ.USER.NAME.EQ ("user").
T he classic authorization policies can be bound only to AAA users and AAA groups.
For VPN requests, the bind point remains same for both classic and advanced authorization policies (AAA users and AAA
groups).
Navigate to Security > AAA - Application Traf f ic > Policies > Authorization, click Add and then define the policy as
required.
Navigate to Security > AAA - Application Traf f ic > Users or Groups, and edit the relevant user or group to associate
it with the authorization policy.
Here are some example configurations to authorize user access to some application resources. Note that these are CLI
commands. You can do similar configurations using the GUI, although you must not enclose the expression within quotes (").
Example 1: Allow "user1" access to URLs that have the suffix "gif" COPY
Example 2: Deny users of "group1" access to URLs that have the suffix "png" COPY
Log type. T he logs can be stored remotely (syslog) or locally on the NetScaler appliance (nslog).
Rule. T he conditions on which the logs are stored.
Action. Details of the log server and other details for creating the log entries.
T his audit policy can be configured at different levels: user-level, group-level, AAA virtual server, and global system level. T he
policies configured at the user-level have the highest priority.
Note
T his topic details steps for using syslog. Make necessary changes to use nslog.
Navigate to Security > AAA - Application Traf f ic > Policies > Auditing > Syslog, and configure the server and the
policy in the relevant tabs.
Navigate to Security > AAA - Application Traf f ic > Users, and associate the authorization policy with the relevant
user.
Navigate to Security > AAA - Application Traf f ic > Groups, and associate the authorization policy with the
relevant group.
Navigate to Security > AAA - Application Traf f ic > Virtual Servers, and associate the authorization policy with the
relevant virtual server.
Navigate to Security > AAA - Application Traf f ic > Policies > Auditing > Syslog or Nslog, select the
authorization policy, and click Action > Global Bindings to bind the policy globally.
To configure the session settings, you can take one of two approaches. If you want different settings for different user
accounts or groups, you create a profile for each user account or group for which you want to configure custom sessions
settings. You also create policies to select the connections to which to apply particular profiles, and you bind the policies to
users or groups. You can also bind a policy to the authentication virtual server that handles the traffic to which you want to
apply the profile.
If you want the same settings for all sessions, or if you want to customize the default settings for sessions that do not
have specific profiles and policies configured, you can simply configure the global session settings.
At the command prompt, type the following commands to create a session profile and verify the configuration:
add tm sessionAction <name> [-sessT imeout <mins>] [-defaultAuthorizationAction ( ALLOW | DENY )] [-SSO ( ON | OFF
)] [-ssoCredential ( PRIMARY | SECONDARY )] [-ssoDomain <string>] [-httpOnlyCookie ( YES | NO )] [-persistentCookie (
ENABLED | DISABLED )] [-persistentCookieValidity <minutes>]
show tm sessionAction <name>
Example
At the command prompt, type the following commands to modify a session profile and verify the configuration:
set tm sessionAction <name> [-sessT imeout <mins>] [-defaultAuthorizationAction ( ALLOW | DENY )] [-SSO ( ON | OFF
)] [-ssoCredential ( PRIMARY | SECONDARY )] [-ssoDomain <string>] [-httpOnlyCookie ( YES | NO )] [-persistentCookie (
ENABLED | DISABLED )] [-persistentCookieValidity <minutes>]
show tm sessionAction
Example
At the command prompt, type the following command to remove a session profile:
rm tm sessionAction <name>
To configure session profiles by using the configuration utility
Warning
T he Traffic Management session policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you
to use the Advanced Traffic Management Session Policy. You can also use the nspepi utility tool for the conversion.
After you create one or more session profiles, you create session policies and then bind the policies globally or to an
authentication virtual server to put them into effect.
To create a session policy by using the command line interf ace
At the command prompt, type the following commands to create a session policy and verify the configuration:
add tm sessionPolicy <name> <rule> <action>
show tm sessionPolicy <name>
Example
At the command prompt, type the following commands to modify a session policy and verify the configuration:
set tm sessionPolicy <name> [-rule <expression>] [-action <action>]
show tm sessionPolicy <name>
Example
At the command prompt, type the following commands to globally bind a session policy and verify the configuration:
bind tm global -policyName <policyname> [-priority <priority>]
Example
At the command prompt, type the following command to bind a session policy to an authentication virtual and verify the
configuration:
bind authentication vserver <name> -policy <policyname> [-priority <priority>]
Example
At the command prompt, type the following commands to unbind a session policy from an authentication virtual server and
verify the configuration:
unbind authentication vserver <name> -policy <policyname>
Example
At the command prompt, type the following commands to unbind a globally-bound session policy:
unbind tm global -policyName <policyname>
Example
First unbind the session policy from global, and then, at the command prompt, type the following commands to remove a
session policy and verify the configuration:
rm tm sessionPolicy <name>
Example
At the command prompt, type the following commands to configure the global session settings and verify the
configuration:
set tm sessionParameter [-sessT imeout <mins>] [-defaultAuthorizationAction ( ALLOW | DENY )] [-SSO ( ON | OFF )] [-
ssoCredential ( PRIMARY | SECONDARY )] [-ssoDomain <string>] [-httpOnlyCookie ( YES | NO )] [-persistentCookie (
ENABLED | DISABLED )] [-persistentCookieValidity <minutes>]
Example
Forms-based SSO allows you to use a web form of your own design as the sign-on method instead of a generic pop-up
window. You can therefore put you company logo and other information you might want your users to see on the logon
form. SAML SSO allows you to configure one NetScaler appliance or virtual appliance instance to authenticate to another
NetScaler appliance on behalf of users who have authenticated with the first appliance.
To configure either type of SSO, you first create a forms or SAML SSO profile. Next, you create a traffic profile and link it to
the SSO profile you created. Next, you create a policy, link it to the traffic profile. Finally, you bind the policy globally or to
an authentication virtual server to put your configuration into effect.
Note: In this feature, the terms “profile” and “action” mean the same thing.
To create a traf fic profile by using the command line interf ace
add tm trafficAction <name> [-appT imeout <mins>] [-SSO ( ON | OFF ) [-formSSOAction <string>]] [-persistentCookie (
ENABLED | DISABLED )] [-InitiateLogout ( ON | OFF )]
Example
add tm trafficAction Traffic-Prof-1 –appTimeout 10 -SSO ON -formSSOAction SSO-Prof-1
To modif y a session profile by using the command line interf ace
set tm trafficAction <name> [-appT imeout <mins>] [-SSO ( ON | OFF ) [-formSSOAction <string>]] [-persistentCookie (
ENABLED | DISABLED )] [-InitiateLogout ( ON | OFF )]
Example
set tm trafficAction Traffic-Prof-1 –appTimeout 10 -SSO ON -formSSOAction SSO-Prof-1
To remove a session profile by using the command line interf ace
rm tm trafficAction <name>
Example
rm tm trafficAction Traffic-Prof-1
To configure traf fic profiles by using the configuration utility
Example
bind authentication vserver auth-vserver-1 -policyName Traffic-Pol-1 -priority 1000
To unbind a globally bound traf fic policy by using the command line interf ace
Example
unbind authentication vserver auth-vserver-1 -policyName Traffic-Pol-1
To remove a traf fic policy by using the command line interf ace
First unbind the session policy from global, and then, at the command prompt, type:
rm tm trafficPolicy <name>
Example
rm tm trafficPolicy Traffic-Pol-1
To configure and bind traf fic policies by using the configuration utility
Note:
Forms-based single sign-on does not work if the form is customized to include Javascript.
In this feature, the terms “profile” and “action” mean the same thing.
To create a f orm SSO profile by using the command line interf ace
Example
add tm formSSOAction SSO-Prof-1 -actionURL "/logon.php"
-userField "loginID" -passwdField "passwd"
-nameValuePair "loginID passwd" -responsesize "9096"
-ssoSuccessRule "HTTP.RES.HEADER("Set-Cookie").CONTAINS("LogonID")"
-nvtype STATIC -submitMethod GET
–sessTimeout 10 -defaultAuthorizationAction ALLOW
To modif y a f orm SSO by using the command line interf ace
set tm formSSOAction <name> -actionURL <URL> -userField <string> -passwdField <string> -ssoSuccessRule <expression>
[-nameValuePair <string>] [-responsesize <positive_integer>] [-nvtype ( ST AT IC | DYNAMIC )] [-submitMethod ( GET | POST
)
Example
set tm formSSOAction SSO-Prof-1 -actionURL "/logon.php"
-userField "loginID" -passwdField "passwd"
-ssoSuccessRule "HTTP.RES.HEADER("Set-Cookie").CONTAINS("LogonID")"
-nameValuePair "loginID passwd" -responsesize "9096"
-nvtype STATIC -submitMethod GET
–sessTimeout 10 -defaultAuthorizationAction ALLOW
To remove a f orm SSO profile by using the command line interf ace
rm tm formSSOAction <name>
Example
rm tm sessionAction SSO-Prof-1
To configure f orm SSO profiles by using the configuration utility
To create a SAML SSO profile by using the command line interf ace
set tm samlSSOProfile <name> -samlSigningCertName <string> -assertionConsumerServiceURL <URL> -relaystateRule <expression> -sendPassword (ON|OFF) [-samlIssuerName <string>]
Example
set tm samlSSOProfile saml-SSO-Prof-1 -samlSigningCertName "Example, Inc." -assertionConsumerServiceURL "https://service.example.com" -relaystateRule "true" -sendPassword "ON" -samlIssuerName "Exam
To remove a SAML SSO profile by using the command line interf ace
rm tm samlSSOProfile <name>
Example
rm tm sessionAction saml-SSO-Prof-1
To configure a SAML SSO profile by using the configuration utility
1. Navigate to Security > AAA - Application T raffic > Policies > T raffic.
2. In the details pane, click the SAML SSO Profiles tab.
3. On the SAML SSO Profiles tab, do one of the following:
T o create a new SAML SSO profile, click Add.
T o modify an existing SAML SSO profile, select the profile, and then click OpenEdit.
4. In the Create SAML SSO Profiles or the Configure SAML SSO Profiles dialog box, set the following parameters:
Name*
Signing Certificate Name*
ACS URL*
Relay State Rule*
Send Password
Issuer Name
5. Click Create or OK, and then click Close. T he SAML SSO profile that you created appears in the T raffic Policies, Profiles, and SAML SSO Profiles pane.
To f orce OWA 2010 to timeout af ter a specified period by using the command line interf ace
Example
add tm trafficAction act-owa2010timeout -forcedTimeout RESET -forcedTimeoutVal 10
add tm trafficPolicy pol-owa2010timeout true act-owa2010timeout
bind lb vserver vs-owa2010 -policyName pol-owa2010timeout -priority 10
When the user tries to log on to an authentication virtual server for which an authentication policy is not configured, and a
global cascade is not configured, the user name information is extracted from the specified field of the certificate. If the
required field is extracted, the authentication succeeds. If the user does not provide a valid certificate during the SSL
handshake, or if the user name extraction fails, authentication fails. After it validates the client certificate, the ADC
presents a logon page to the user.
T he following procedures assume that you have already created a functioning AAA configuration, and therefore they
explain only how to enable authentication by using client certificates. T hese procedures also assume that you have
obtained your root certificate and client certificates and have placed them on the ADC in the /nsconfig/ssl directory.
To configure the AAA client certificate parameters by using the command line interf ace
At the command prompt, type the following commands, in the order shown, to configure the certificate and verify the
configuration:
add ssl certKey <certkeyName> -cert <certFile> -key <keyFile> -password -inform <inform> -expiryMonitor
<expiryMonitor> -notificationPeriod <notificationPeriod>
bind ssl certKey <certkeyName> -vServer <certkeyName> -CA -crlCheck Mandatory
show ssl certKey [<certkeyName>]
set aaa parameter -defaultAuthT ype CERT
show aaa parameter
set aaa certParams -userNameField "Subject:CN"
show aaa certParams
To configure the AAA client certificate parameters by using the configuration utility
T he exact behavior of this feature when a user presents a client certificate depends upon the configuration of the VPN
virtual server.
If the VPN virtual server is configured to accept client certificates but not require them, the ADC inserts the certificate
into the request and then forwards the request to the protected application.
If the VPN virtual server has client certificate authentication disabled, the ADC renegotiatiates the authentication
protocol and reauthenticates the user before it inserts the client certificate in the header and forwards the request to
the protected application.
If the VPN virtual server is configured to require client certificate authentication, the ADC uses the client certificate to
authenticate the user, then inserts the certificate in the header and forwards the request to the protected application.
To create and configure client certificate pass-through by using the command line interf ace
Example
add vpn vserver vs-certpassthru SSL 10.121.250.75 443
set ssl vserver vs-certpassthru -clientAuth ENABLED -clientCert optional
bind vpn vserver vs-certpassthru -policy local
bind vpn vserver vs-certpassthru -policy cert
bind ssl vserver vs-certpassthru -certkeyName mycertKey
bind ssl vserver vs-certpassthru -certkeyName mycertKey -CA -ocspCheck Optional
add ssl action act-certpassthru -clientCert ENABLED -certHeader CLIENT-CERT
add ssl policy pol-certpassthru -rule true -action act-certpassthru
bind ssl vserver vs-certpassthru -policyName pol-certpassthru -priority 10
For more information about configuring the NetScaler for Kerberos authentication, see Handling Authentication,
Authorization and Auditing with Kerberos/NT LM.
Each entity on the network (client or server) has a secret key that is known only to itself and the KDC. T he knowledge of
this key implies authenticity of the entity. For communication between two entities on the network, the KDC generates a
session key, referred to as the Kerberos ticket or service ticket. T he client makes a request to the AS for credentials for a
specific server. T he client then receives a ticket, referred to as T icket Granting T icket (TGT ). T he client then contacts the
TGS, using the TGT it received from the AS to prove its identity, and asks for a service. If the client is eligible for the service,
the TGS issues a Kerberos ticket to the client. T he client then contacts the server hosting the service (referred to as the
service server), using the Kerberos ticket to prove that it is authorized to receive the service. T he Kerberos ticket has a
configurable lifetime. T he client authenticates itself with the AS only once. If it contacts the physical server multiple times,
it reuses the AS ticket.
Faster authentication. When a physical server gets a Kerberos ticket from a client, the server has enough information to
authenticate the client directly. It does not have to contact a domain controller for client authentication, and therefore
the authentication process is faster.
Mutual authentication. When the KDC issues a Kerberos ticket to a client and the client uses the ticket to access a
service, only authenticated servers can decrypt the Kerberos ticket. If the virtual server on the NetScaler is able to
decrypt the Kerberos ticket, you can conclude that both the virtual server and client are authenticated. T hus, the
authentication of the server happens along with the authentication of the client.
Single sign-on between Windows and other operating systems that support Kerberos.
To use Kerberos authentication, you must configure it on the NetScaler appliance and on each client.
In the Windows 2000 Server or later versions, the Domain Controller and KDC are part of the Windows Server. If the
Windows Server is UP and running, it indicates that the Domain Controller and KDC are configured. T he KDC is also the
Active Directory server.
Note: All Kerberos interactions are validated with the Windows Kerberos Domain Controller.
Authentication Service and Protocol Negotiation
A NetScaler appliance supports Kerberos authentication on the AAA-T M authentication virtual servers. If the Kerberos
authentication fails, the NetScaler uses the NT LM authentication.
By default, Windows 2000 Server and later Windows Server versions use Kerberos for AAA. If you create an authentication
policy with NEGOT IAT E as the authentication type, the NetScaler attempts to use the Kerberos protocol for AAA and if
the client's browser fails to receive a Kerberos ticket, the NetScaler uses the NT LM authentication. T his process is referred
to as negotiation.
T he client may fail to receive a Kerberos ticket in any of the following cases:
Kerberos is not supported on the client.
Kerberos is not enabled on the client.
T he client is in a domain other than that of the KDC.
T he Access Directory on the KDC is not accessible to the client.
For Kerberos/NT LM authentication, the NetScaler does not use the data that is present locally on the NetScaler appliance.
Authorization
T he traffic management virtual server can be a load balancing virtual server or a content switching virtual server.
Auditing
T he NetScaler appliance supports auditing of Kerberos authentication with the following audit logging:
Supported Environment
High Availability
In a high availability setup, only the active NetScaler joins the domain. In case of a failover, the NetScaler lwagent daemon
joins the secondary NetScaler appliance to the domain. No specific configuration is required for this functionality.
T he following figure shows a typical process for Kerberos authentication in the NetScaler environment.
Note: T he above authentication process is not necessary if the client already has a Kerberos ticket whose lifetime has not
expired. In addition, clients such as Web Services, .NET , or J2EE, which support SPNEGO, get a Kerberos ticket for the target
server, create an SPNEGO token, and insert the token in the HT T P header when they send an HT T P request. T hey do not
1. T he client sends the Kerberos ticket containing the SPNEGO token and the HT T P request to the traffic management
virtual server on the NetScaler. T he SPNEGO token has the necessary GSSAPI data.
2. T he NetScaler establishes a security context between the client and the NetScaler. If the NetScaler cannot accept the
data provided in the Kerberos ticket, the client is asked to get a different ticket. T his cycle repeats till the GSSAPI data is
acceptable and the security context is established. T he traffic management virtual server on the NetScaler acts as an
HT T P proxy between the client and the physical server.
1. After the security context is complete, the traffic management virtual server validates the SPNEGO token.
2. From the valid SPNEGO token, the virtual server extracts the user ID and GSS credentials, and passes them to the
authentication daemon.
3. A successful authentication completes the Kerberos authentication.
1. Enable the AAA feature to ensure the authentication of traffic on the appliance.
2. Add the keytab file to the NetScaler appliance. A keytab file is necessary for decrypting the secret received from the
client during Kerberos authentication. A single keytab file contains authentication details for all the services that are
bound to the traffic management virtual server on the NetScaler.
First generate the keytab file on the Active Directory server and then transfer it to the NetScaler appliance.
1. Log on to the Active Directory server and add a user for Kerberos authentication. For example, to add a user named
"Kerb-SVC-Account":
Note: In the User Properties section, ensure that the "Change password at next logon option" is not selected and
the "Password does not expire" option is selected.
2. Map the HT T P service to the above user and export the keytab file. For example, run the following command on the
Active Directory server:
Note: You can map more than one service if authentication is required for more than one service. If you want to map
more services, repeat the above command for every service. You can give the same name or different names for the
output file.
3. T ransfer the keytab file to the NetScaler by using the unix f tp command or any other file transfer utility of your
choice.
4. Log on to the NetScaler appliance, and run the ktutil utility to verify the keytab file. T he keytab file has an entry for
the HT T P service after it is imported.
root@ns# ktutil
ktutil: quit
3. T he NetScaler must obtain the IP address of the domain controller from the fully qualified domain name (FQDN).
T herefore, Citrix recommends configuring the NetScaler with a DNS server.
Note: Alternatively, you can add static host entries or use any other means so that the NetScaler can resolve the FQDN
name of the domain controller to an IP address.
2. Configure the negotiate policy and associate the negotiate action to this policy.
5. Create an authentication virtual server and associate the negotiate policy with it.
Note: Similar configurations can also be done on the content switching virtual server.
1. Access the traffic management virtual server, using the FQDN. For example, http://owa.newacp.com.
Navigate to System > Settings, click Conf igure Basic Features and enable the AAA feature.
2. Add the keytab file as detailed in step 2 of the CLI procedure mentioned above.
Navigate to Traf f ic Management > DNS > Name Servers, and specify the IP address for the DNS server.
Navigate to Security > AAA - Application Traf f ic > Policies > Authentication > Advanced Policies > Policy, and
create a policy with Negotiate as the action type.
Navigate to Security > AAA - Application Traf f ic > Virtual Servers, and associate the Negotiate policy with the
authentication virtual server.
6. Associate the authentication virtual server with the traffic management (load balancing or content switching) virtual
server.
Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and specify the relevant authentication
settings.
Note: Similar configurations can also be done on the content switching virtual server.
7. Verify the configurations as detailed in step 7 of the CLI procedure mentioned above.
1. Make sure that you have Kerberos properly configured on your computer.
2. T ype about:config in the URL bar.
3. In the filter text box, type network.negotiate.
4. Change network.negotiate-auth.delegation-uris to the domain that you want to add.
5. Change network.negotiate-auth.trusted-uris to the domain that you want to add.
Note: If you are running Windows, you also need to enter sspi in the filter text box and change the network.auth.use-
sspi option to False.
T here is no authentication between the NetScaler and the physical server, and the authentication offload is transparent to
the end users. After the initial logon to a Windows computer, the end user does not have to enter any additional
authentication information in a pop-up or on a logon page.
In the current NetScaler release, Kerberos authentication is available only for Authentication, Authorization, and Auditing
(AAA) Traffic Management Virtual Servers. Kerberos authentication is not supported for SSL VPN in the NetScaler Gateway
Enterprise Edition appliance or for NetScaler appliance management.
Kerberos authentication requires configuration on the NetScaler appliance and on client browsers.
1. Create a user account on Active Directory. When creating a user account, verify the following options in the User
Properties section:
Make sure that you do not select the Change password at next logon option.
Be sure to select the Password does not expire option.
2. On the AD server, at the CLI command prompt, type:
ktpass -princ HT T P/kerberos.crete.lab.net@crete.lab.net -ptype KRB5_NT _PRINCIPAL -mapuser
kerbuser@crete.lab.net -mapop set -pass Citrix1 -out C:\kerbtabfile.txt
Note: Be sure to type the above command on a single line. T he output of the above command is written into the
C:\kerbtabfile.txt file.
3. Upload the kerbtabfile.txt file to the /etc directory of the NetScaler appliance by using a Secure Copy (SCP) client.
4. Run the following command to add a DNS server to the NetScaler appliance.
add dns nameserver 1.2.3.4
T he NetScaler appliance cannot process Kerberos requests without the DNS server. Be sure to use the same DNS server
that is used in the Microsoft Windows domain.
5. Switch to the shell prompt and run the following commands from the shell prompt:
ktutil # rkt /etc/kerbtabfile.txt
# wkt /etc/krb5.keytab
# list
T he list command displays the user account details that you created in the Active Directory. A sample screen of the
output of the list command is shown below.
Note: Kerberos authentication requires a specific configuration on the client. Ensure that the client can resolve the
hostname, which results in the Web browser connecting to an HT T P virtual server.
15. Configure Kerberos on the Web browser of the client computer.
For configuring on Internet Explorer, see Configuring Internet Explorer for Kerberos authentication.
For configuring on Mozilla Firefox, see Configuring Internet Explorer for Kerberos authentication
.
16. Verify whether you can access the backend physical server without authentication.
6. Restart Firefox.
T he NetScaler Kerberos SSO implementation requires the user's password for SSO methods that rely on basic, NT LM, or
forms-based authentication. T he user's password is not required for Kerberos SSO, although if Kerberos SSO fails and the
NetScaler appliance has the user's password, it uses the password to attempt NT LM SSO.
If the user's password is available, the KCD account is configured with a realm, and no delegated user information is
present, the NetScaler Kerberos SSO engine impersonates the user to obtain access to authorized resources.
Impersonation is also called unconstrained delegation.
T he NetScaler Kerberos SSO engine can also be configured to use a delegated account to obtain access to protected
resources on the user's behalf. T his configuration requires delegated user credentials, a keytab, or a delegated user
certificate and matching CA certificate. Configuration that uses a delegated account is called constrained delegation.
AAA-T M implements this process as shown in the following diagram. T he diagram illustrates the flow of information
through the NetScaler appliance and AAA-T M, on a secure network with LDAP authentication and Kerberos authorization.
AAA-T M environments that use other types of authentication have essentially the same information flow, although they
might differ in some details.
NetScaler AAA-T M authentication and authorization in a Kerberos environment requires that the following actions take
place.
1. T he client sends a request for a resource to the traffic management virtual server on the NetScaler appliance.
2. T he traffic management virtual server passes the request to the authentication virtual server, which authenticates the
client and then passes the request back to the traffic management virtual server.
3. T he traffic management virtual server sends the client's request to the web application server.
4. T he web application server responds to the traffic management virtual server with a 401 Unauthorized message that
requests Kerberos authentication, with fallback to NT LM authentication if the client does not support Kerberos.
5. T he traffic management virtual server contacts the Kerberos SSO daemon.
T hese steps are transparent to the client, which just sends a request and receives the requested resource.
All AAA-T M authentication mechanisms support NetScaler Kerberos SSO. AAA-T M supports the Kerberos SSO mechanism
with the Kerberos, CAC (Smart Card) and SAML authentication mechanisms with any form of client authentication to the
NetScaler appliance. It also supports the HT T P-Basic, HT T P-Digest, Forms-based, and NT LM (versions 1 and 2) SSO
mechanisms if the client uses either HT T P-Basic or Forms-Based authentication to log on to the NetScaler appliance.
T he following table shows each supported client-side authentication method, and the supported server-side
authentication method for that client-side method.
Forms-Based X X X
(LDAP/RADIUS/T ACACS)
Kerberos X
NT LM v1/v2 X X
SAML X
SAML T wo-Factor X X X
Certificate T wo-Factor X X X
To configure NetScaler SSO by delegation, you must have the delegated user's credentials in one of the following formats:
the user's user name and password, the keytab configuration that includes the user name and an encrypted password, or
the delegated user certificate and the matching CA certificate.
If your network is not already configured in this manner, perform the following configuration tasks:
Following are brief instructions and examples for performing each of these tasks from the NetScaler command line. For
further assistance, see Setting up AAA Virtual Servers and DNS.
For NetScaler SSO to obtain a TGS (service ticket) for a service, either the FQDN assigned to the server entity on the
NetScaler appliance must match the FQDN of the web application server, or the server entity name must match the
NetBios name of the web application server. You can take either of the following approaches:
Configure the NetScaler server entity by specifying the FQDN of the web application server.
Configure the NetScaler server entity by specifying the IP address of the web application server, and assign the server
entity the same name as the NetBios name of the web application server.
serverName— A name for the NetScaler appliance to use to refer to this server.
serverFQDN— T he FQDN of the server. If the server has no domain assigned to it, use the server’s IP address and make
sure that the server entity name matches the NetBios name of the web application server.
serviceName— A name for the NetScaler appliance to use to refer to this service.
type— T he protocol used by the service, either HT T P or MSSQLSVC.
port— T he port on which the service listens. HT T P services normally listen on port 80. Secure HT T PS services normally
listen on port 443.
Example
T he following examples add server and service entries on the NetScaler appliance for the web application server
was1.example.com. T he first example uses the FQDN of the web application server; the second uses the IP address.
To add the server and service using the web application server FQDN, was1.example.com, you would type the following
commands:
T he traffic management virtual server manages traffic between the client and the web application server. You can use
either a load balancing or a content switching virtual server as the traffic management server. T he SSO configuration is the
same for either type.
To create a load balancing virtual server, at the command prompt, type the following command:
vserverName— A name for the NetScaler appliance to use to refer to this virtual server.
type— T he protocol used by the service, either HT T P or MSSQLSVC.
IP— T he IP address assigned to the virtual server. T his would normally be an IANA-reserved, non-public IP address on your
LAN.
port— T he port on which the service listens. HT T P services normally listen on port 80. Secure HT T PS services normally
listen on port 443.
Example
To add a load balancing virtual server called tmvserver1 to a configuration that manages HT T P traffic on port 80, assigning
it a LAN IP address of 10.217.28.20 and then binding the load balancing virtual server to the wasservice1 service, you would
type the following commands:
T he authentication virtual server manages authentication traffic between the client and the authentication (LDAP) server.
To create an authentication virtual server, at the command prompt type the following commands:
authvserverName — A name for the NetScaler appliance to use to refer to this authentication virtual server. Must
begin with a letter, number, or the underscore character (_), and must contain only letters, numbers, and the hyphen (-),
period (.) pound (#), space ( ), at (@), equals (=), colon (:), and underscore characters. Can be changed after the
authentication virtual server is added by using the rename authentication vserver command.
IP— T he IP address assigned to the authentication virtual server. As with the traffic management virtual server, this
address would normally be an IANA-reserved, non-public IP on your LAN.
domain— T he domain assigned to the virtual server. T his would usually be the domain of your network. It is customary,
though not required, to enter the domain in all capitals when configuring the authentication virtual server.
To add an authentication virtual server called authverver1 to your configuration and assign it the LAN IP 10.217.28.21 and
the domain EXAMPLE.COM, you would type the following commands:
T he authentication virtual server can be configured to handle authentication for a single domain or for multiple domains. If
it is configured to support authentication for multiple domains, you must also specify the domain for NetScaler SSO by
creating an authentication profile, and then configuring the traffic management virtual server to use that authentication
profile.
Note: T he traffic management virtual server can be either a load balancing (lb) or content switching (cs) virtual server. T he
following instructions assume that you are using a load balancing virtual server. T o configure a content switching virtual
server, simply substitute set cs vserver for set lb vserver. T he procedure is otherwise the same.
To create the authentication profile, and then configure the authentication profile on a traffic management virtual server,
type the following commands:
authnprof ileName— A name for the authentication profile. Must begin with a letter, number, or the underscore
character (_), and must consist of from one to thirty-one alphanumeric or hyphen (-), period (.) pound (#), space ( ), at (@),
equals (=), colon (:), and underscore characters.
authvserverName— T he name of the authentication virtual server that this profile uses for authentication.
authenticationHost— Host name of the authentication virtual server.
authenticationDomain— Domain for which NetScaler SSO handles authentication. Required if the authentication
virtual server performs authentication for more than one domain, so that the correct domain is included when the
NetScaler appliance sets the traffic management virtual server cookie.
Example
To create an authentication profile named authnProfile1 for authentication of the example.com domain, and to configure
the load balancing virtual server vserver1 to use the authentication profile authnProfile1, you would type the following
commands:
If you do not have the user's password, you can configure NetScaler SSO to authenticate by delegation. Although
somewhat more complex than configuring SSO to authenticate by impersonation, the delegation method provides
flexibility in that a user's credentials might not be available to the NetScaler appliance in all circumstances.
For either impersonation or delegation, you must also enable integrated authentication on the web application server.
Following are instructions for configuring Microsoft Internet Information Server (IIS) to require authentication. If your web
application server uses software other than IIS, consult the documentation for that web server software for instructions.
1. Log on to the IIS server and open Internet Information Services Manager.
2. Select the web site for which you want to enable integrated authentication. T o enable integrated authentication for all
IIS web servers managed by IISM, configure authentication settings for the Default Web Site. T o enable integrated
authentication for individual services (such as Exchange, Exadmin, ExchWeb, and Public), configure these authentication
settings for each service individually.
3. Open the Properties dialog box for the default web site or for the individual service, and click the Directory Security tab.
4. Beside Authentication and Access Control, select Edit.
5. Disable anonymous access.
6. Enable Integrated Windows authentication (only). Enabling integrated Windows authentication should automatically set
protocol negotiation for the web server to Negotiate, NTLM, which specifies Kerberos authentication with fallback to
NT LM for non-Kerberos capable devices. If this option is not automatically selected, manually set protocol negotiation
to Negotiate, NTLM.
When configuring the KCD account, you must set the realm parameter to the realm of the service that the user is
accessing. T he same realm is also used as the user's realm if the user's realm cannot be obtained from authentication with
the Netscaler appliance or from the session profile.
Example:
To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would type the following
command:
If you are configuring delegation by delegated user certificate, install the matching CA certificates on the NetScaler
appliance and add them to the NetScaler configuration.
Create the KCD account on the appliance. T he appliance uses this account to obtain service tickets for your protected
applications.
Configure the Active Directory server.
If you are configuring NetScaler SSO with a client certificate, you must copy the matching CA certificate for the client
certificate domain (the client CA certificate) to the NetScaler appliance, and then install the CA certificate. To copy the
client CA certificate, use the file transfer program of your choice to transfer the certificate and private-key file to the
NetScaler appliance, and store the files in /nsconfig/ssl.
add ssl certKey <certkeyName> -cert <cert> [(-key <key> [-password]) | -fipsKey <fipsKey>] [-inform ( DER | PEM )] [-
expiryMonitor ( ENABLED | DISABLED | UNSET ) [-notificationPeriod <positive_integer>]] [-bundle ( YES | NO )]
For the variables, substitute the following values:
certkeyName— A name for the client CA certificate. Must begin with an ASCII alphanumeric or underscore (_) character,
and must consist of from one to thirty-one characters. Allowed characters include the ASCII alphanumerics, underscore,
hash (#), period(.), space, colon (:), at (@), equals (=), and hyphen (-) characters. Cannot be changed after the certificate-
key pair is created. If the name includes one or more spaces, enclose the name in double or single quotation marks (for
example, "my cert" or 'my cert').
cert— Full path name and file name of the X509 certificate file used to form the certificate-key pair. T he certificate file
must be stored on the NetScaler appliance, in the /nsconfig/ssl/ directory.
key— Full path name and file name of the file that contains the private key to the X509 certificate file. T he key file must
be stored on the NetScaler appliance in the /nsconfig/ssl/ directory.
password— If a private key is specified, the passphrase used to encrypt the private key. Use this option to load
encrypted private keys in PEM format.
f ipsKey— Name of the FIPS key that was created inside the Hardware Security Module (HSM) of a FIPS appliance, or a
key that was imported into the HSM.
Note: You can specify either a key or a fipsKey, but not both.
inf orm— Format of the certificate and private-key files, either PEM or DER.
passplain— Pass phrase used to encrypt the private key. Required when adding an encrypted private-key in PEM format.
expiryMonitor— Configure the NetScaler appliance to issue an alert when the certificate is about to expire. Possible
values: ENABLED, DISABLED, UNSET .
notif icationPeriod— If expiryMonitor is ENABLED, number of days before the certificate expires to issue an alert.
bundle— Parse the certificate chain as a single file after linking the server certificate to its issuer's certificate within the
file. Possible values: YES, NO.
T he following example adds the specified delegated user certificate customer-cert.pem to the NetScaler configuration
along with the key customer-key.pem, and sets the password, certificate format, expiration monitor, and notification period.
To add the delegated user certificate, you would type the following commands:
If you are configuring NetScaler SSO by delegation, you can configure the KCD account to use the user's log-on name and
password, to use the user's log-on name and keytab, or to use the user's client certificate. If you configure SSO with user
name and password, the NetScaler appliance uses the delegated user account to obtain a T icket Granting T icket (TGT ), and
then uses the TGT to obtain service tickets for the specific services that each user requests. If you configure SSO with
keytab file, the NetScaler appliance uses the delegated user account and keytab information. If you configure SSO with a
delegated user certificate, the NetScaler appliance uses the delegated user certificate.
add aaa kcdaccount <accountname> -delegatedUser root -kcdPassword <password> -realmStr <realm>
For the variables, substitute the following values:
To add a KCD account named kcdaccount1 to the NetScaler appliance configuration with a password of password1 and a
realm of EXAMPLE.COM, specifying the delegated user account in UPN format (as root), you would type the following
commands:
To add a KCD account named kcdaccount1 to the NetScaler appliance configuration with a password of password1 and a
realm of EXAMPLE.COM, specifying the delegated user account in SPN format, you would type the following commands:
Log on to the AD server command line and, at the command prompt, type the following command:
ktpass /princ <SPN> /ptype KRB5_NT _PRINCIPAL /mapuser <DOMAIN>\<username> /pass <password> -out <File_Path>
For the variables, substitute the following values:
To use the NetScaler configuration utility to create a script to generate the keytab file.
add aaa kcdaccount <accountname> -realmStr <realm> -delegatedUser <user_name/SPN> -usercert <cert> -cacert
<cacert>
For the variables, substitute the following values:
Example:
To add a KCD account named kcdccount1, and use the keytab named kcdvserver.keytab, you would type the following
command:
When you configure SSO by delegation, in addition to creating the KCDAccount on the NetScaler appliance, you must also
create a matching Kerberos Service Account (KSA) on your LDAP active directory server, and configure the server for SSO. To
create the KSA, use the account creation process on the active directory server. To configure SSO on the active directory
server, open the properties window for the KSA. In the Delegation tab, enable the following options: Trust this user for
delegation to specified services only and Use any Authentication protocol. (T he Kerberos only option does not work,
because it does not enable protocol transition or constrained delegation.) Finally, add the services that NetScaler SSO will
manage.
Note: If the Delegation tab is not visible in the KSA account properties dialog box, before you can configure the KSA as
described, you must use the Microsoft setspn command-line tool to configure the active directory server so that the tab is
visible.
To configure delegation for the Kerberos service account
1. In the LDAP account configuration dialog box for the Kerberos service account that you created, click the Delegation
tab.
2. Choose "T rust this user for delegation to the specified services only".
3. Under "T rust this user for delegation to the specified services only," choose "Use any authentication protocol".
4. Under “Services to which this account can present delegated credentials,” click Add.
5. In the Add Services dialog box, click Users or Computers, choose the server that hosts the resources to be assigned to
the service account, and then click OK.
Note: Constrained delegation does not support services hosted in domains other than the domain assigned to the
account, even though Kerberos might have a trust relationship with other domains
6. Back in the Add Services dialog box, in the Available Services list, choose the services assigned to the service account.
NetScaler SSO supports the HT T P and MSSQLSVC services.
7. Click OK.
Warning
T he SAML authentication policy is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends
you to use the advanced authentication policy (“add authentication Policy”). You can also use the nspepi utility tool for the
conversion.
Security Assertion Markup Language (SAML) is an XML-based authentication mechanism that provides single sign-on
capability and is defined by the OASIS Security Services Technical Committee.
Why SAML?
Consider a scenario in which a service provider (LargeProvider) hosts a number of applications for a customer (BigCompany).
BigCompany has users that must seamlessly access these applications. In a traditional setup, LargeProvider would need to
maintain a database of users of BigCompany. T his raises some concerns for each of the following stakeholders:
T he SAML authentication mechanism provides an alternative approach. T he following deployment diagram shows how
SAML works.
LargeProvider does not have to maintain a database for BigCompany users. Freed from identity management,
LargeProvider can concentrate on providing better services.
BigCompany does not bear the burden of making sure the LargeProvider user database is kept in sync with its own user
database.
A user can log on once, to one application hosted on LargeProvider, and be automatically logged on to the other
T he NetScaler appliance can be deployed as a SAML Service Provider (SP) and a SAML Identity Provider (IdP). Read through
the relevant topics to understand the configurations that must be performed on the NetScaler appliance.
A NetScaler appliance configured as a SAML service provider can now enforce an audience restriction check. T he audience
restriction condition evaluates to “Valid” only if the SAML replying party is a member of at least one of the specified
audiences.
You can configure a NetScaler appliance to parse attributes in SAML assertions as group attributes. Parsing them as group
attributes enables the appliance to bind policies to the groups.
Not e: A NetScaler MPX FIPS appliance used as a SAML service provider now supports encrypted assertions. Also, a
NetScaler MPX FIPS appliance functioning as a SAML service provider or a SAML identity provider can now be configured to
use the SHA2 algorithms on FIPS hardware.
2. Create a CSR and use it at CA server to generate a certificate. You can then copy the certificate in /nsconfig/ssl. Let’s
assume that the file is fips3cert.cer.
add ssl cert Key fips-cert -cert fips3cert .cer -fipsKey fips-key
T he following table lists some articles that are specific to deployments where the NetScaler appliance is used as a SAML SP
or a SAML IdP.
Some
S AMLinformation
SP on other
S AML IdP specific deployments: Info rm a tio n Link
T he SP also validates SAML assertions that are received from the IdP.
When the NetScaler appliance is configured as an SP, all user requests are received by a traffic management virtual server
(load balancing or content switching) that is associated with the relevant SAML action.
T he NetScaler appliance also supports POST and Redirect bindings during logout.
Note
A NetScaler appliance can be used as a SAML SP in a deployment where the SAML IdP is configured either on the appliance or on
any external SAML IdP.
Can extract the user information (attributes) from the SAML token. T his information can then be used in the policies
that are configured on the NetScaler. For example, if you want to extract the GroupMember and emailaddress
attributes, in the SAMLAction, specify the At t ribut e2 parameter as GroupMember and the At t ribut e3 parameter as
emailaddress.
Not e: Default attributes such as username, password, and logout URL must not be extracted in attributes 1 to 16,
because they as are implicitly parsed and stored in the session.
Can extract attribute names of upto 127 bytes from an incoming SAML assertion. T he previous limit was 63 bytes.
Support introduced in NetScaler 11.0 Build 64.x.
Supports post, redirect, and artifact bindings. Support for redirect and artifact bindings is introduced in NetScaler 11.0
Build 55.x.
Not e: Redirect binding should not be used for large amount of data, when the assertion after inflate or decoding is
greater than 10K.
Can extract multi-valued attributes from a SAML assertion. T hese attributes are sent is nested XML tags such as:
<AttributeValue>
<AttributeValue>Value1</AttributeValue>
<AttributeValue>Value2</AttributeValue
</AttributeValue>
If the system time on NetScaler SAML IdP and the peer SAML SP is not in sync, the messages might get invalidated by
either party. T o avoid such cases, you can now configure the time duration for which the assertions will be valid.
T his duration, called the "skew time," specifies the number of minutes for which the message should be accepted. T he
skew time can be configured on the SAML SP and the SAML IdP.
To configure t he Net Scaler appliance as a SAML SP by using t he command line int erf ace
Example: T he following command adds a SAML action that redirects unauthenticated user requests.
> add aut hent icat ion samlAct ion SamlSPAct1 -samlIdPCertName nssp – samlRedirectUrl https://auth1.example.com
Example: T he following command defines a SAML policy that applies the above defined SAML action to all traffic.
> add aut hent icat ion samlP olicy SamlSPPol1 ns_true SamlSPAct1
Example: T he following command binds the SAML policy to a authentication virtual server named "av_saml".
> bind aut hent icat ion vserver av_saml -policy SamlSPPol1
4. Bind the authentication virtual server to the appropriate traffic management virtual server.
Example: T he following command adds a load balancing virtual server named "lb1_ssl" and associates the authentication
virtual server named "av_saml" to the load balancing virtual server.
> add lb vserver lb1_ssl SSL 10.217.28.224 443 -persistenceT ype NONE -cltT imeout 180 -AuthenticationHost
auth1.example.com -Authentication ON -authnVsName av_saml
To configure a Net Scaler appliance as a SAML SP by using t he graphical user int erf ace
Navigate to Securit y > AAA - Applicat ion T raf f ic > P olicies > Aut hent icat ion > Advanced P olicies > P olicy ,
Navigate to Securit y > AAA - Applicat ion T raf f ic > Virt ual Servers , and associate the SAML policy with the
authentication virtual server.
3. Associate the authentication server with the appropriate traffic management virtual server.
Navigate to T raf f ic Management > Load Balancing (or Cont ent Swit ching ) > Virt ual Servers , select the virtual
server, and associate the authentication virtual server with it.
T he SP validates the token, and the user is then granted access to the requested protected application.
When the NetScaler appliance is configured as an IdP, all requests are received by an authentication virtual server that is
associated with the relevant SAML IdP profile.
Note
A NetScaler appliance can be used as a IdP in a deployment where the SAML SP is configured either on the appliance or on any
external SAML SP.
Digitally signs assertions. Support for the SHA256 algorithm is introduced in NetScaler 11.0 Build 55.x.
Supports single-factor and two-factor authentication. SAML must not be configured as the secondary authentication
mechanism.
Can encrypt assertions by using the public key of the SAML SP. T his is recommended when the assertion includes
sensitive information. Support introduced in NetScaler 11.0 Build 55.x.
Can be configured to accept only digitally signed requests from the SAML SP. Support introduced in NetScaler 11.0 Build
55.x.
Can log on to the SAML IdP by using the following 401-based authentication mechanisms: Negotiate, NT LM, and
Certificate. Support introduced in NetScaler 11.0 Build 55.x.
Can be configured to send 16 attributes in addition to the NameId attribute. T he attributes must be extracted from the
appropriate authentication server. For each of them, you can specify the name, the expression, the format, and a
friendly name in the SAML IdP profile. Support introduced in NetScaler 11.0 Build 55.x.
If the NetScaler appliance is configured as a SAML IdP for multiple SAML SP, a user can gain access to applications on
the different SPs without explicitly authenticating every time. T he NetScaler appliance creates a session cookie for the
first authentication, and every subsequent request uses this cookie for authentication. Support introduced in NetScaler
11.0 Build 55.x.
Can send multi-valued attributes in a SAML assertion. Support introduced in NetScaler 11.0 Build 64.x.
Supports post and redirect bindings. Support for redirect bindings is introduced in NetScaler 11.0 Build 64.x.
If the system time on NetScaler SAML IdP and the peer SAML SP is not in sync, the messages might get invalidated by
either party. T o avoid such cases, you can now configure the time duration for which the assertions will be valid.
T his duration, called the "skew time," specifies the number of minutes for which the message should be accepted. T he
skew time can be configured on the SAML SP and the SAML IdP.
Can be configured to serve assertions only to SAML SPs that are pre-configured on or trusted by the IdP. For this
configuration, the SAML IdP must have the service provider ID (or issuer name) of the relevant SAML SPs. Support
introduced in NetScaler 11.0 Build 64.x.
Note
Before proceeding, make sure that you have an authentication virtual server that is linked to an LDAP authentication server.
To configure a Net Scaler appliance as a SAML IdP by using t he command line int erf ace
2. Configure the SAML authentication policy and associate the SAML IdP profile as the action of the policy.
> add aut hent icat ion samlIdP P olicy samlIDPPol1 -rule ns_true -action samlIDPProf1
> bind aut hent icat ion vserver saml-auth-vserver -policy samlIDPPol1 -priority 100
To configure a Net Scaler appliance as a SAML IdP by using t he graphical user int erf ace
Navigate to Securit y > AAA - Applicat ion T raf f ic > P olicies > Aut hent icat ion > Advanced P olicies > P olicy , and
create a policy with SAML IdP as the action type, and associate the required SAML IdP profile with the policy.
Navigate to Securit y > AAA - Applicat ion T raf f ic > Virt ual Servers , and associate the SAML IdP policy with the
Configuring SAML single sign-on by using t he command line int erf ace
Example: In the following command, https://nssp2.example.com is the load balancing virtual server that has a web link
from the SharePoint portal. Nssp.example.com is the T raffic Management virtual server that is load balancing the
SharePoint server.
> add t m samlSSOP rof ile tm-saml-sso -samlSigningCertName nssp -assertionConsumerServiceURL
"https://nssp2.example.com/cgi/samlauth" -relaystateRule "\"https://nssp2.example.com/samlsso.html\"" -sendPassword
ON -samlIssuerName nssp.example.com
Example: T he following command enables SSO and binds the SAML SSO profile created above to a traffic action.
> add t m t raf f icAct ion html_act -SSO ON -samlSSOProfile tm-saml-sso
3. Configure the traffic policy that specifies when the action must be executed.
Example: T he following command associates the traffic action with a traffic policy.
> add t m t raf f icP olicy html_pol "HT T P.REQ.URL.CONT AINS(\"abc.html\")" html_act
4. Bind the traffic policy created above to a traffic management virtual server (load balancing or content switching).
Alternatively, the traffic policy can be associated globally.
Not e: T his traffic management virtual server must be associated with the relevant authentication virtual sever that is
associated with the SAML action.
> bind lb vserver lb1_ssl -policyName html_pol -priority 100 -gotoPriorityExpression END -type REQUEST
Configuring SAML single sign-on by using t he graphical user int erf ace
1. Define the SAML SSO profile, the traffic profile, and the traffic policy.
Navigate to Securit y > AAA - Applicat ion T raf f ic > P olicies > T raf f ic , select the appropriate tab, and configure the
settings.
2. Bind the traffic policy to a traffic management virtual server or globally to the NetScaler appliance.
OAuth subsystem supports both authorization code, implicit, and hybrid flows specified by OpenID specification. NetScaler
supports inline verification of id_token by polling the certificates of the SAML IdP or by using the certificates configured
locally in a file.
A major advantage of using the OAuth and OpenID-Connect mechanisms is that the user information is not sent to the
hosted applications and therefore the risk of identity theft is considerably reduced.
T he NetScaler appliance configured for NetScaler AAA now accepts incoming tokens that are signed using HMAC HS256
algorithm. In addition, the public keys of the SAML Identity Provider (IdP) are read from a file, instead of learning from an
URL endpoint.
In the NetScaler implementation, the application to be accessed is represented by the AAA-T M virtual server. So, to
configure OAuth, you must configure an OAuth policy which must then be associated with a AAA-T M virtual server.
Note
NetScaler also allows for the administrator to specify up to 16 attributes to be extracted from the id_token.
Note
Attributes (1 to 16) can be extracted in the OAuth response. Currently these attributes are not evalauted. T hey are added for the
future reference.
Example
Not e: When a certEndpoint is specified, the NetScaler appliance polls that endpoint at the configured frequency to learn
the keys. To configure a NetScaler to read the local file and parse keys from that file, a new configuration option is
introduced as follows.
set authentication OAuthAction <> -Cert F ilePat h <path to local file with jwks>
Important
Supported from NetScaler 11.0 Build 62.x onwards.
Starting from NetScaler 12.0 Build 51.x, NetScaler appliance used as a SAML Service Provider (SP) with Multi-Factor (nFactor)
authentication now prepopulates the user-name field on the login page. T he appliance sends a NameID attribute as part of a SAML
authorization request, retrieves the NameID attribute value from the NetScaler SAML Identity Provider (IdP), and prepopulates the
user-name field.
Multi-factor authentication enhances the security of an application by requiring users to provide multiple proofs of identify
to gain access. T he NetScaler appliance provides an extensible and flexible approach to configuring multi-factor
authentication. T his approach is called nFactor authentication.
For a nFactor benefit, see One Public IP for AAA-T M Deployments on NetScaler.
A login schema specifies an authentication schema XML file that defines the manner in which the login form will be
rendered. Considering the interaction that the user must have when logging in to the application, you can create a single
file for multiple factors or different files for different factors. View sample XML file.
Single f ile f or mult iple f act ors. User will be provided a single form in which to provide credentials for multiple
authentication factors.
Dif f erent f iles f or dif f erent f act ors. User will be provided a different form for each authentication factor.
Next, you must associate the XML file(s) with login schema(s). You can also specify expressions to extract the user name
and the password from the login form.
Tip
You can configure an authentication factor to be pass-through. T his means that the user is not required to provide credentials
explicitly and there is no login form for that factor. T he credentials are either taken from the previous factor or the user name
and/or password are dynamically extracted by using the username/password expressions that are configured for that login
schema. You must set the login schema to "NOSCHEMA", instead of an XML file.
Now that the login schemas are configured, you must specify the manner in which they must be invoked. A login schema
can be invoked by using either a login schema policy or an authentication policy label. T he decision depends on the
following:
T o summarize, the configurations you must perform to set up nFactor authentication are as follows:
1. Create the authentication schema XML files.
2. Associate each XML file with a login schema.
3. Associate each login schema with a login schema policy or authentication policy label.
4. Bind login schema policy to an authentication virtual server.
1. Checks to determine whether any login schema policies are associated with the authentication virtual server.
- If yes, the user is presented the login form associated with the login schema policy with the highest priority that
evaluates to true.
Not e: T he default login schema files are available in the /nsconfig/loginschema/LoginSchema/ directory of the
NetScaler appliance. Citrix recommends that you copy these files to the /nsconfig/loginschema/ directory before using
them, so that changes made to the files are preserved post reboot.
2. T he authentication policies that are associated with the authentication virtual server are evaluated. For the policies that
are evaluated to true, the actions are executed in order of priority until one of the actions succeeds.
4. T he authentication policies that are associated with the authentication policy label are evaluated. For the policies that
are evaluated to true, the actions are executed in order of priority until one of the actions succeeds.
6. Steps 4 and 5 are performed repetitively till all the configured next factors are executed.
Warning
T he AAA preauthentication policy is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix recommends
you to use the Nfactor authentication (advanced EPA policy). You can also use the nspepi utility tool for the conversion.
To understand the step-wise configurations for nFactor authentication, let us consider a 2-factor authentication
deployment where the 1st factor is LDAP authentication and the 2nd factor is RADIUS authentication.
T his sample deployment requires the user to login to both factors using a single login form. T herefore, we define a single
login form that accepts two passwords. T he first password is used for LDAP authentication and the other for RADIUS
authentication. View XML file.
> add aut hent icat ion vserver auth56 SSL 1.217.193.56 443 -AuthenticationDomain aaatm.com
3. Configure the login schema for the login form and bind it to a login schema policy.
> add aut hent icat ion loginSchema login1 -authenticationSchema login-2passwd.xml -userCredentialIndex 1 -
passwordCredentialIndex 2
> add aut hent icat ion loginSchemaP olicy login1 -rule true -action login1
4. Configure a login schema for the pass-through and bind it to a policy label
> add aut hent icat ion loginSchema login2 -authenticationSchema noschema
> add aut hent icat ion policylabel label1 -loginSchema login2
> add aut hent icat ion ldapAct ion ldapAct1 -serverIP 1.217.28.180 -ldapBase "dc=aaatm, dc=com" -ldapBindDn
administrator@aaatm.com -ldapBindDnPassword
71ca2b11ad800ce2787fb7deb54842875b8f3c360d7d46e3d49ae65c41550519 -encrypted -encryptmethod
ENCMT HD_3 -ldapLoginName samAccountName -groupAttrName memberOf -subAttributeName CN
> add aut hent icat ion P olicy ldap -rule true -action ldapAct1
> add aut hent icat ion radiusAct ion radius -serverIP 1.217.22.20 -radKey
> add aut hent icat ion P olicy radius -rule true -action radius
> bind aut hent icat ion vserver auth56 -policy login1 -priority 1 -gotoPriorityExpression END
7. Bind the LDAP policy (first factor) to the authentication virtual server.
> bind aut hent icat ion vserver auth56 -policy ldap -priority 1 -nextFactor label1 -gotoPriorityExpression next
8. Bind the RADIUS policy (second factor) to the authentication policy label.
> bind aut hent icat ion policylabel label1 -policyName radius -priority 2 -gotoPriorityExpression end
OpenID eliminates overhead of maintaining multiple authentication passwords as the user has a single identity across
organization.
OpenID provides a robust security for your password as the password is shared only with your identity provider and not
with any application you access.
OpenID has vast interoperability with various systems making it easier for the hosted applications to accept OpenID.
OpenID is a simple protocol that enables native clients to easily integrate with servers.
To configure Net Scaler appliance as an IdP using t he OpenID Connect prot ocol wit h t he Net Scaler GUI
1. Navigate to Configurat ion > Securit y > AAA-Applicat ion T raf fic>P olicies>Aut hent icat ion>Advanced
P olicies>OAut h IdP .
On the Creat e Aut hent icat ion OAut h IDP P rofile screen, set values for the following parameters and click Creat e .
4. On the Creat e Aut hent icat ion OAut h IDP P olicy screen, set values for the following parameters and click
Creat e .
1. Navigate to Configurat ion > Securit y > AAA-Applicat ion T raf fic > P olicies >Aut hent icat ion > Advanced
P olicies > Act ions > LDAP .
3. On Creat e Aut hent icat ion LDAP Server screen, set the values for the following parameters, and click Creat e .
4. Navigate to Configurat ion > Securit y > AAA-Applicat ion T raf fic > P olicies >Aut hent icat ion > Advanced
P olicies > P olicy.
6. On Creat e Aut hent icat ion P olicy page, set the values for the following parameters and click Creat e.
To configure t he Net Scaler appliance as an IdP using t he OpenID Connect prot ocol wit h t he command line
[-defaultAuthenticationGroup <string>]
[-logAction <string>]
sAMAccountName
Note
You can bind more than one key. Public parts of certificates bound are sent in response to jwks_uri query
(https://gw/oauth/idp/certs).
For information on how admin partitions can benefit your business, see Benefits and Uses of Admin Partitions.
A partitioned NetScaler appliance has a single default partition and one or more admin partitions. T he following table
provides further details on the two partition types:
Not e : In a partitioned appliance, the mode BridgeBPDUs can be enabled only in the default partition and not in the
administrative partitions.
Reduces the cost of ADC ownership without compromising on performance and ease-of-use.
Safeguards from unwarranted configuration changes. In a non-partitioned NetScaler, authorized users of other
application could intentionally or unintentionally change configurations that are required for your application. T his could
lead to undesirable behavior. T his possibility is reduced in a partitioned NetScaler.
Isolates traffic between different applications by the use of dedicated VLANs for each partition.
Let us analyze a couple of cases to understand the scenarios in which you can use admin partitions.
Important
Only superusers are authorized to create and configure admin partitions.
Unless specified otherwise, configurations to set up an admin partition must be done from the default partition.
By partitioning a NetScaler appliance, you are in-effect creating multiple instances of a single NetScaler appliance. Each
instance has its own configurations and the traffic of each of these partitions is isolated from the other by assigning each
partition a dedicated VLAN or a shared VLAN.
A partitioned NetScaler has one default partition and the admin partitions that are created. To set up an admin partition,
you must first create a partition with the relevant resources (memory, maximum bandwidth, and connections). T hen, specify
the users that can access the partition and the level of authorization for each of the users on the partition.
In a partitioned NetScaler appliance, a network administrator can create a partition with partition resources such as
memory, bandwidth, and connection limit configured as unlimited. T his is done by specifying Zero as the partition resource
value, where Zero indicates the resource is unlimited on the partition and it can be consumed up to system limits. Partition
resource configuration is useful when you migrate a traffic domain deployment to an administrative partition or if you do
not know about resource allocation limit for a partition in a given deployment.
1. Partition memory. T his is the maximum allocated memory for a partition. You must make sure to specify the values when
creating a partition.
Not e : From NetScaler 12.0 onwards, when you create a partition, you must the set the memory limit as Zero or if a
partition is already created with a specific memory limit, you can reduce the limit to any value or set the limit as Zero.
Parameter: maxMemLimit
Maximum memory is allocated in megabytes in a partition. A zero value indicates the memory is unlimited on the partition
and it can consume up to the system limits.
Default value: 10
2. Partition bandwidth. Maximum allocated bandwidth for a partition. If you specify a limit, make sure it is within the
appliance’s licensed throughput. Otherwise, you are not limiting the bandwidth that can be used by the partition. T he
specified limit is accountable for the bandwidth that the application requires. If the application bandwidth exceeds the
specified limit, packets are dropped.
Not e : From NetScaler 12.0 onwards, when you can create a partition, you can set the partition bandwidth limit to Zero or
if a partition is already created with a specific bandwidth, you can reduce bandwidth or set the limit as Zero.
Maximum bandwidth is allocated in Kbps in a partition. A zero value indicates the bandwidth is unrestricted. T hat is, the
partition can consume up to the system limits.
3. Partition connection. Maximum number of concurrent connections that can be open in a partition. T he value must
accommodate the maximum simultaneous flow expected within the partition. T he partition connections are accounted
from the partition quota memory. Previously, the connections were accounted from the default partition quota memory. It
is configured only on the client-side, not on the back-end server-side TCP connections. New connections cannot be
established beyond this configured value.
Not e : From NetScaler 12.0 onwards, you can create a partition with number of open connections set to Zero or if you
have already created a partition with a specific number of open connections, you can reduce the connection limit or set the
limit as Zero.
Parameter: maxConnections
Maximum number of concurrent connections that can be open in the partition. A zero value indicates no limit on number of
open connections.
Minimum value: 0
VLANs can be bound to a partition as a “Dedicated” VLAN or a “Shared” VLAN. Based on your deployment, you can bind a
VLAN to a partition to isolate its network traffic from other partitions.
Dedicated VLAN – A VLAN bound only to one partition with “Sharing” option disabled and must be a tagged VLAN. For
example, in a client-server deployment, for security reasons a system administrator creates a dedicated VLAN for each
partition on the server side.
Shared VLAN – A VLAN bound (shared across) to multiple partitions with “Sharing” option enabled. For example, in a client-
server deployment, if the system administrator does not have control over the client side network, a VLAN is created and
shared across multiple partitions.
A Shared VLAN can be used across multiple partitions. Once created, it can be bound to one or more administrative
partitions. By default, a shared vlan is bound to the default partition. It cannot be bound explicitly. For example, you can
create partition 1, partition 2 and then configure a VLAN as shared across default partition and partition 1 or between
partition 1 and partition 2.
Not e : If a NetScaler Virtual Appliance is deployed on a ESX platform, you must enable the Promiscuous mode for shared
VLANs with partition. Otherwise, if the traffic is through a dedicated VLAN, you must enable the VLAN with Portgroup
properties of the virtual switch.
In a partitioned (multi-tenant) NetScaler appliance, a system administrator can isolate the traffic flowing to a particular
partition or partitions by binding one or more VLANs to each partition. A VLAN can be dedicated to one partition or Shared
across multiple partitions.
Dedicated VLANs
To isolate the traffic flowing into a partition, create a VLAN and associate it with the partition. T he VLAN is then visible
only to the associated partition, and the traffic flowing through the VLAN is classified and processed only in the associated
partition.
Example
add vlan V1
Example
Add ns partition <partition name> [-maxBandwidth <positive_integer>] [-maxConn <positive_integer>] [-maxMemLimit <positive_integer>]
Example
Done
Example
In a shared VLAN configuration, each partition has a MAC address, and traffic received on the shared VLAN is classified by
MAC address. Only a Layer3 VLAN is recommended because it can restrict the subnet traffic. A partition MAC address is
applicable and important only for a shared VLAN deployment.
Note: Shared VLAN in a partitioned appliance does not support dynamic routing protocol.
T he following diagram shows how a VLAN (VLAN 10) is shared across two partitions.
1. Create a VLAN with the sharing option ‘enabled’, or enable the sharing option on an existing VLAN. By default, the
Examples
Example
Add ns partition <partition name> [-maxBandwidth <positive_integer>] [-maxConn <positive_integer>] [-maxMemLimit <positive_integer>] -partitio
Example
Done
Example
Example
In a partitioned NetScaler appliance, similar to configuring a VLAN, you can configure a VXLAN in the default partition. After configuring a VXLAN, you can bind it to
an administrative partition or If a VXLAN is extending a VLAN that is bound to a partition, the appliance binds the VXLAN to the partition under the same
broadcasting domain. This is applicable in unbinding a VLAN that unbinds a VXLAN from the partition.
For more information about how VXLAN works in a NetScaler appliance, see http://docs.citrix.com/en-us/netscaler/11/networking/vxlans.html.
Also, for more information on how VLAN works in a partitioned NetScaler appliance, see http://docs.citrix.com/en-us/netscaler/11-1/admin-partition/admin-partition-
setup.html.
When you extend a VLAN over VXLAN, make sure VLAN is bound to the partition.
Only a partition administrator must configure the IP and dynamic routing for the VXAN in the administrative partition.
A shared VXLAN is not supported in a partitioned appliance and so a VXLAN cannot be tagged to a shared VLAN or you
cannot make a VLAN a shared one when it is tagged to a VXLAN
Follow the steps given below to extend a VLAN over a VXLAN and vice versa within the same broadcast domain:
3. Configure a peer vtep to carry all BUM (broadcast unknown multicast) traffic. Not e : the vtep address can be multicast
addresss.
Case 3: Setting VXLAN and VLAN (bound to a partition) in the same broadcast
domain
Follow the steps given below to set VXLAN and VLAN in the same broadcast domain.
2. Configure the bridge table and vxlan settings in the default partition for multicast tunnel. Note: the vtep address can be
multicast addresss.
Configuration Steps
Configuring a VXLAN on a partitioned appliance consists of the following tasks.
Note
In a partitioned NetScaler appliance, Virtual Router Redundancy Protocol (VRRP) is supported on non-shared VLANs only. T his
protocol is blocked on a shared VLAN (tagged or untagged) bound to a default or any administrative partition.
For shared VLAN to work in a partitioned deployment on a NetScaler SDX platform, you must log on to a Storage
Virtualization Manager (SVM) appliance and assign each partition's MAC (VMAC) to a NetScaler VPX appliance.
1. Create a partition and configure the NetScaler resources for that partition.
Not e: Check the rate limiting content provided above for tips to update the maximum memory limit, maximum
bandwidth, and maximum number of connections.
3. Specify the level of authorization for each user by associating one of the following command policies: partition-
operator, partition-read-only, partition-network, and partition-admin.
bind syst em user <name> <policyName> <priority>
4. Configure the VLAN through which traffic for this partition must be routed. You can use bridgegroups instead of VLANs
to route the traffic.
Not e: When a VLAN is bound to an admin partition, its IP address bindings are lost. To make sure that the VLAN
continues to have the IP address, create the IP address on the admin partition and then bind it to that VLAN.
OR
OR
Note: Use the show vlan or the show bridgegroup command to view the partitions associated with that VLAN or
bridgegroup.
6. Verify the configurations of the partition.
show ns partition <partitionName>
Note: You can also use the stat ns partition command to view partition configurations.
7. Save the configuration.
save ns config
1. Navigate to System > Partition Administration, click Add and do the following:
Note
After creating a partition, inform the users that the NetScaler configurations they perform will be isolated from users who are not
members of the partition.
Make sure the relevant users, command policies, VLANs, and bridgegroups are available on the NetScaler appliance.
For deployments that have large size of NetScaler configuration and large quantum of traffic, Citrix advises that you increase the
default values for the maximum memory limit, maximum bandwidth, and maximum number of connections.
Note
Admin partitions cannot be set up on a NetScaler cluster. T his means that a NetScaler cluster cannot be partitioned.
Admin partitions cannot be set up on a NetScaler MPX-FIPS appliance.
Case 3 lists the NetScaler features that are not supported in admin partitions.
Case 1 (global configurat ions). Configurations that can be performed ONLY in the default partition and which are
available or impact all the admin partitions.
Case 2 (part it ion-specific configurat ions). Configurations that can be performed independently in default and admin
partitions. T hese configurations are applicable only to the partition in which they are performed.
Case 3: Configurations that cannot be performed on admin partitions. T hese features can be configured in the default
partition, but there is no impact on admin partitions.
Not e: Configurations that are supported on admin partitions for a particular release are marked as Yes .
Fe a ture Ne tS ca le r Ne tS ca le r Ne tS ca le r
Ne tS ca le r Fe a ture Ne tS ca le r 11.0
Co m po ne nt 10.5 11.1 12.0
Load
DBS AutoScale No Yes Yes Yes
Balancing
Load
DNSSEC No No No Yes
Balancing
Load
Diameter No No Yes Yes
Balancing
Load
RT SP No No No No
Balancing
Load
Sure Connect No Yes Yes Yes
Balancing
Load
Autoscale Service Group No No Yes Yes
Balancing
Fe a ture Ne tS ca le r Ne tS ca le r Ne tS ca le r
VPN Cloudbridge
Ne tS ca le r Fe
Connector
a ture No No tS ca le r 11.0
Ne No No
Co m po ne nt 10.5 11.1 12.0
SSL SSL-FIPS No No No No
SSL External-HSM No No No No
Network LSN No No No No
Load
Datastream No Yes Yes Yes
Balancing
Loading
Scriptable Monitoring No Yes Yes Yes
Balancing
Load
GSLB No Yes Yes Yes
Balancing
Load
SureConnect No Yes Yes Yes
Balancing
Load
Fe a ture Priority Queuing No tS ca le r
Ne No YestS ca le r
Ne YestS ca le r
Ne
Balancing Ne tS ca le r Fe a ture Ne tS ca le r 11.0
Co m po ne nt 10.5 11.1 12.0
Load
TCP Buffering (Restricted Feature) No No No No
Balancing
SSL SSL-FIPS No No No No
After accessing the appropriate partition, configurations that you perform are saved to that partition and are specific to
that partition.
Note
NetScaler superusers and other non-partition users are taken to the default partition.
Users of all the 512 partitions can log in simultaneously.
Tip
To access a partitioned NetScaler appliance over HT T PS by using the SNIP (with management access enabled), make sure that each
partition has the certificate of its partition administrator. Within the partition, the partition admin must do the following:
2. Bind it to a service named "nskrpcs-<SNIP>-3009", where <SNIP> must be replaced with the SNIP address, in this case 100.10.10.1.
> bind s s l s e rv ice nskrpcs-100.10.10.1-3009 -ce rtke y Na m e ns-server-certificate
To configure in a Net Scaler part it ion by using t he command line int erf ace
2. Check if you are in the correct partition. T he command prompt displays the name of the currently selected partition.
If no, get a list of the partitions with which you are associated and switch over to the appropriate partition.
3. Now, you can perform the required configurations just as a non-partitioned NetScaler.
2. Check if you are in the correct partition. T he top bar of the graphical user interface displays the name of the currently
selected partition.
If no, navigate to Conf igurat ion > Syst em > Administ rat ive P art it ions > P art it ions , right-click the partition to
which you want to switch, and select Swit ch .
3. Now, you can perform the required configurations just as a non-partitioned NetScaler.
In authenticating and authorizating a partitioned NetScaler appliance, a root administrator can assign a partition administrator to one or more partitions. The partition
administrator can authorize users to that partition without affecting other partitions. These are partition users and they are authorized to access only that partition
using SNIP address. Both the root administrator and the partition administrator can configure role based access (RBA by authorizing users to access different
applications.
Root Administrator: Accesses the partitioned appliance through its NSIP address and can grant user access to one or more partitions. The administrator can also
assign partition administrators to one or more partitions. The administrator can create a partition administrator from the default partition using a NSIP address or
switch to a partition and then create a user and assign partition admin access using a SNIP address.
Partition Administrator: Accesses the specified partition through a NSIP address assigned by the root administrator. The administrator can assign role-based access
to partition user access to that partition and also configure external server authentication using partition specific configuration.
System User: Accesses partitions through the NSIP address. Has access to the partitions and resources specified by the root administrator.
Partition User: Accesses a partition through a SNIP address. This user account is created by the partition administrator and the user has access to resources, only
within the partition.
Points to Remember
Following are some points to remember when providing role-based access in a partition.
1. NetScaler users accessing NetScaler GUI through NSIP address will use default partition authentication configuration to
log on to the appliance.
2. Partition system users accessing NetScaler GUI through partition SNIP address will use partition specific authentication
configuration to log on to the appliance.
3. Partition user created in a partition cannot login using NSIP address.
4. NetScaler user bound to a partition cannot login using partition SNIP address.
5. External users accessing a partition through external server configuration as LDAP, Radius, or T ACACS added in the
partition. T he user must access using SNIP address to directly log onto the partition.
John, is the root administrator of a partitioned NetScaler appliance. John manages all user accounts and administrative user
accounts across partitions (for example, P1, P2, P3, P4, and P5) within the appliance. He provides granular role-based access
to entities from the default partition of the appliance. John creates user accounts and assigns partition access to each
account. George being a network engineer within the organization prefers to have a role based access to few applications
running on partition P2. Based on user management, John creates a partition administrator role for George and associates
his user account with partition-admin command policy in P2 partition. Adam being another network engineer prefers to
access an application running on P2. John creates a system user account for Adam and associates his user account to P2
partition. Once his account is created, Adam can log into the appliance to access the NetScaler Management interface
through NSIP address and can switch to partition P2 based on user/group binding.
Suppose, Jane who is another network engineer wants to directly access an application running only on partition P2, George
(partition administrator) can create a partition user account for her and associate her account with command policies for
authorization privileges. Jane’s user account created within the partition is now directly associated with P2. Now Jane can
access the NetScaler Management interface through SNIP address and cannot switch to any other partition.
Note: If Jane’s user account is created by a partition administrator in partition P2, she can access the NetScaler
Management interface only through SNIP address (created within the partition) and not permitted to access the interface
through NSIP address. Similarly, if Adam’s user account is created by a root administrator in the default partition and is
bound to P2 partition, he can access the NetScaler Management interface only through NSIP address or SNIP address
created in the default partition (with management access enabled) and not permitted to access the partition interface
through SNIP address created in the administrative partition.
Creating administrative partitions and system users – A root administrator creates administrative partitions and system
users in the default partition of the appliance. T he administrator then associates the users to different partitions. If you
are bound to one or more partitions, you can switch from one partition to another based on user bindings. Also, your access
to one or more bound partitions is authorized only by the root administrator.
Authorizing system user as partition administrator for a specific partition – Once a user account is created, the root
administrator switches to a specific partition and authorizes the user as the partition administrator. T his is done by
assigning partition-admin command policy to the user account. Now, the user can access the partition as partition
administrator and manage entities within the partition.
Configuring SNIP address in an administrative partition- T he partition administrator logs on to the partition and creates a
SNIP address and provides management access to the address.
Creating and Binding a Partition System User Groups with Partition Command Policy -T he partition administrator creates
partition user groups and defines the scope of user group access. T his is done by binding the user group account to
partition command policies.
Configuring External Server authentication for external users (optional)-T his configuration is done for authenticating
external TACACS users accessing the partition using SNIP address.
1. Creating an Administrative Partition – Before you create partition users in an administrative partition, you must first
create the partition. As a root administrator, you can create a partition from the default partition using the
configuration utility or a command line interface.
2. Switching user access from default partition to partition P2 – If you are partition administrator accessing the appliance
from the default partition, you can switch from default partition to a specific partition (for example, partition P2) based
on user binding.
3. Adding SNIP address to the Partition user account with Management access enabled-Once you have switched your
access to an administration partition, you must create a SNIP address and provide management access to the address.
4. Creating and Binding a Partition System User with Partition Command Policy-If you are a partition administrator, you can
create partition users and define the scope of user access. T his is done by binding the user account to partition
command policies.
5. Creating and Binding Partition user group with Partition Command Policy-If you are a partition administrator, you can
create partition user groups and define the scope of user access control. T his is done by bind the user group account to
partition command policies.
Configuring External Server authentication for external users (optional)-T his configuration is done for authenticating
external TACACS users accessing the partition using SNIP address.
T he root administrator adds an administrative partition from the default partition and binds the partition with VLAN 2.
To creat e an administ rat ive part it ion by using t he command line int erf ace:
Swit ching user access f rom def ault part it ion t o bound admin part it ion
To swit ch a user account f rom def ault part it ion t o an administ rat ive part it ion by using t he command line
int erf ace:
Adding SNIP address t o t he Part it ion user account wit h Management access enabled
To add SNIP address t o t he part it ion user account wit h management access enabled by using t he command
line int erf ace:
Creat ing and Binding a Part it ion Syst em User wit h Part it ion Command P olicy
In partition, create a partition system user and bind the user with partition-admin command policies.
To creat e and bind a part it ion syst em user wit h part it ion command policy by using t he command line
int erf ace:
Done
Creat ing and Binding Part it ion user group wit h Part it ion Command P olicy
To creat e and bind a part it ion user group wit h part it ion command policy by using t he command line
int erf ace:
> bind system user group <groupname> -policyname <cmdpolicy> <priority value>
Configuring Ext ernal Server aut hent icat ion f or ext ernal users
In partition Par1 you can configure an external server authentication to authenticate external TACACS users accessing the
partition through SNIP address.
To configure ext ernal server aut hent icat ion f or ext ernal users by using t he command line int erf ace:
add authentication tacacsaction <name> -serverip <IP> -tacacsSecret <secret key> -authorization ON -accounting ON
To configure a partition user account in an administrative partition, you must create a partition user or a partition user
group and bind it partition command policies. Also, you can configure the external server authentication for an external
user.
To creat e a part it ion user account in a part it ion by using t he Net Scaler GUI
Navigate to System > User Administration, click Users to add a partition system user and bind the user to command policies
(partitionadmin/partitionread-only/partition-operator/partition-network).
Navigate to System > User Administration, click Groups to add a partition system user group and bind the user group to
command policies (partitionadmin/partitionread-only/partition-operator/partition-network).
To configure Ext ernal server aut hent icat ion f or ext ernal users by using t he Net Scaler GUI
Navigate to Syst em > Aut hent icat ion > Basic Act ions and click T ACACS to configure TACACS server for
authenticating external users accessing the partition.
T he following configuration shows how to create a partition user or a partition user group and bind it partition command
policies. Also, how to configure the external server authentication for authenticating an external user.
> bind system group Retail -policyname partition-network 1 (where 1 is the priority number)
> add authentication tacacssaction tacuser –serverip 10.102.29.200 –tacacsSecret Password –authorization ON –accounting ON
T here are three LACP configuration modes that you can enable in the default partition of a NetScaler appliance:
1. Active. A port in active mode sends LACPDUs. Link aggregation is formed if the other end of the Ethernet link is in the
LACP active or passive mode.
2. Passive. A port in passive mode sends LACPDUs only when it receives LACPDUs. T he link aggregation is formed if the
other end of the Ethernet link is in the LACP active mode.
3. Disable. Link aggregation is not formed.
Not e : By default, the link aggregation is disabled in the default partition of the appliance.
LACP exchanges LACPDU between devices connected by an Ethernet link. T hese devices are typically referred as an actor
or partner.
After exchanging LACPDUs, the actor and partner negotiate the settings and decide whether to add the ports to the
aggregation.
To configure and verify LACP on a NetScaler appliance by using the command line
When you enable LACP on an interface, the channels are dynamically created. Additionally, when you enable LACP on an
interface and set lacpKey to 1, the interface is automatically bound to channel LA/1.
Note: When you bind an interface to a channel, the channel parameters take precedence over the interface parameters, so
the interface parameters are ignored. If a channel was created dynamically by LACP, you cannot perform add, bind, unbind,
or remove operations on the channel. A channel dynamically created by LACP is automatically deleted when you disable
LACP on all interfaces of the channel.
show channel
show LACP
Not e : In some versions of Cisco IOS, running the switchport trunk native vlan <VLAN_ID> command causes the Cisco
switch to tag LACP PDUs. T his causes the LACP channel between the Cisco switch and the NetScaler appliance to fail.
However, this issue does not affect the static link aggregation channels configured in the above procedure.
You can use an IP address (for example, 3.3.3.7) as a virtual server IP address in different partitions.
You can use the same name (for example, lbvserver1) for a virtual server in different partitions.
T his is possible as each partition is associated with a different VLAN (or bridgegroup) and therefore traffic destined for
different applications is segregated.
As shown in the following image, the virtual server IP address 3.3.3.7 is used in Partition1, Partition2, and Partition3.
1. On def ault part it ion: Log on to the NetScaler appliance as a super user and configure the three partitions as follows:
shell> ssh 10.102.29.60 -l nsroot
password: ******
Not e: If you encounter any issues during the upgrade, roll back to version 11.0 for services managed by the NetScaler
appliance.
Warning
Any customization within the partitioned appliance might cause an unexpected behavior during or after the upgrade process. T his
might lead to a configuration loss. T herefore, be sure to back up the running configuration of each admin partition and default
partition before you begin the upgrade.
Important
T he deployment described here is applicable when you have untagged VLANs passing through the port interface and bound to
admin partitions.
1. Before you begin the upgrade on the secondary appliance, make a few VLANs tagged members of the port interface. For example:
>bind partition p1 - vlan 10
> unbind vlan 10 -ifnum 1/2
>Done
> bind vlan 10 -ifnum 1/2 -tagged
>Done
2. Access the secondary NetScaler appliance by entering its NSIP address in an SSH utility, such as PuTTY, and use the nsroot credentials to log on to the
appliance.
3. From the command line interface of the appliance, type the "save configuration" command to save the existing configuration.
4. Switch to the shell prompt
login as: username
Using keyboard-interactive authentication.
Password:
Last login: Wed Jun 24 14:59:16 2015 from 10.252.252.65
Done
shell
Copyright (c) 1992-20
5. Run the following command to change to the default installation directory: cd/var/nsinstall
6. Run the following command to create a temporary subdirectory of the nsinstall directory:
# mkdir x.xnsinstall Note: The text x.x is used to name the NetScaler version for future configurations. For example, the directory for the installation files of
NetScaler 11.1 will be called 11.1nsinstall.
This scenario is about untagged VLANs and how to enable it as shared for VLAN deployment from an earlier release to 11.1 release. This is a least preferred
scenario as it involves configuration loss during the software upgrade.
1. Follow steps 2 to 20 of the previous procedure to upgrade the secondary appliance with NetScaler 11.1 software.
2. After you have upgraded the software on the secondary appliance, VLAN bindings to partitions are lost, and the configuration depends on the VLAN inside the
partition during the upgrade process.
3. Now enable the untagged VLANs of any port interface "Shared" and bind the "Shared" VLAN to the partitions and configure the VLAN inside each
partition. Note: Make sure you first enable the untagged VLANs as shared before you bind it to a partition.
unbind partition p1 -vlan 10
Done
set vlan 10 -sharing enabled
Done
bind partition p1 -vlan 10
Done
4. From the command line interface of the appliance, type "save config" command to save the configuration in all the affected partition and the default partition.
5. If the appliance is not a primary appliance, run the "> force failove" command to perform a force failover to ensure that the appliance is a primary appliance.
6. Upgrade the new secondary (formerly the primary) appliance with NetScaler 11.1 software and reboot it to synchronize its configuration from the primary
appliance.
7. From the command line interface of the primary appliance, type the "save config" command to save the configuration in the primary appliance.
8. If the appliance is not a primary appliance, run the "> force failover" command to perform a force failover to ensure that the appliance is a primary appliance.
9. Verify that the appliance is a primary appliance.
1. T he audit logs generated from the partition will be stored as a single log file (/var/log/ns.log).
2. You must configure the audit log server’s (syslog or nslog) subnet address as the source IP address in the partition for
sending the audit-log messages.
3. T he default partition uses the NetScaler IP(NSIP) as the source IP address for the audit log messages by default.
4. You can display the audit-log message by using the “show audit messages” command.
To configure the partition's subnet IP address by using the command line interface
add audit nslogAction <name> <serverIP> [-serverPort <port>] -logLevel <logLevel> [-dateFormat (MMDDYYYY | DDMMYYYY )]
To bind audit-log policy to syslogGlobal entity by using the command line interface.
Example
add audit syslogAction syslog_action1 10.102.1.2 –logLevel INFORMATIONAL –dateFormat MMDDYYYY –transport UDP
Storing Logs
When SYSLOG or NSLOG server collects log information from all partitions, it is stored as log messages in ns.log file. T he log
messages contain the following information:
Partition Name.
T he IP address.
A time stamp.
For more information about how VXLAN works in a NetScaler appliance, see http://docs.citrix.com/en-
us/netscaler/11/networking/vxlans.html.
Also, for more information on how VLAN works in a partitioned NetScaler appliance, see http://docs.citrix.com/en-
us/netscaler/11-1/admin-partition/admin-partition-setup.html.
Remember the following points before you configure a VXLAN in a partitioned NetScaler appliance:
When you extend a VLAN over VXLAN, make sure VLAN is bound to the partition.
Only a partition administrator must configure the IP and dynamic routing for the VXAN in the administrative partition.
A shared VXLAN is not supported in a partitioned appliance and so a VXLAN cannot be tagged to a shared VLAN or you
cannot make a VLAN a shared one when it is tagged to a VXLAN.
Example
Dedicated VLAN – A VLAN bound only to one partition with “Sharing” option disabled and must be a tagged VLAN. For
example, in a client-server deployment, for security reasons a system administrator creates a dedicated VLAN for each
partition on the server side.
Shared VLAN – A VLAN bound (shared across) to multiple partitions with “Sharing” option enabled. For example, in a client-
server deployment, if the system administrator does not have control over the client side network, a VLAN is created and
shared across multiple partitions.
Shared VLAN can be used across multiple partitions. It is created in the default partition and you can bind a shared VLAN to
multiple partitions. By default, a shared VLAN is bound to the default partition implicitly and hence it cannot be bound
explicitly.
Note: If a NetScaler Virtual Appliance is deployed on any hypervisor (ESX, KVM, XEN, or HYPER-V) platform, you must enable
the Promiscuous mode, MAC changes, MAC spoofing or forged transmit for shared VLANs with partition. Otherwise, if the
traffic is through a dedicated VLAN, you must enable the VLAN with Portgroup properties of the virtual switch.
In a partitioned (multi-tenant) NetScaler appliance, a system administrator can isolate the traffic flowing to a particular
partition or partitions by binding one or more VLANs to each partition. A VLAN can be dedicated to one partition or Shared
across multiple partitions.
To isolate the traffic flowing into a partition, create a VLAN and associate it with the partition. T he VLAN is then visible
only to the associated partition, and the traffic flowing through the VLAN is classified and processed only in the associated
partition.
add vlan V1
Done
In a shared VLAN configuration, each partition has a MAC address, and traffic received on the shared VLAN is classified by
MAC address. Only a Layer3 VLAN is recommended because it can restrict the subnet traffic. A partition MAC address is
applicable and important only for a shared VLAN deployment.
Note
Shared VLAN in a partitioned appliance does not support dynamic routing protocol.
T he following diagram shows how a VLAN (VLAN 10) is shared across two partitions.
1. Create a VLAN with the sharing option ‘enabled’, or enable the sharing option on an existing VLAN. By default, the
option is ‘disabled’.
2. Bind partition interface to shared VLAN.
3. Create the partitions, each with its own PartitionMAC address.
4. Bind the partitions to the shared VLAN.
Done
On a partitioned NetScaler appliance, a PART IT ION-RAT E-LIMIT alarm can generate nine SNMP traps for notifying a
partition resource (such as bandwidth, connection, or memory) has reached its limit or returned to normal.
partitionCONNThresholdReached. T he number of active connections for a partition exceeds its high threshold
percentage.
partitionCONNThresholdNormal. T he number of active connections is less than or equal to the normal threshold
percentage.
partitionBWThresholdReached. T he partition's bandwidth usage reaches its high threshold percentage.
partitionMEMThresholdReached. T he current memory usage of the partition exceeds its high threshold percentage.
partitionMEMThresholdNormal. T he current memory usage of the partition becomes less than or equal to the normal
threshold percentage.
partitionMEMLimitExceeded. T he current memory usage of the partition exceeds its memory limit percentage.
partitionCONNLimitExceeded. T he number of active connections for a partition exceeds its configured limit and new
connections are being dropped.
partitionCONNLimitNormal. T he number of active connections for a partition goes below its configured limit and the
partition can now accept a new connection.
partitionBWLimitExceeded. T he current bandwidth usage for a partition has exceeded its configured limit.
T he threshold values for the SNMP traps are non-configurable and are as follows are:
High threshold = 80% (applicable for all partition rate limit traps)
Low threshold = 60 % (applicable for all partition rate limit traps)
Memory limit = 95% (applicable only for partition memory traps)
To configure PART IT ION-RAT E-LIMIT alarm in a specific partition and enable generation of the SNMP trap messages.
set snmp alarm PARTITION-RATE-LIMIT [-state ( ENABLED | DISABLED )] [-severity <severity>] [-logging ( ENABLED | DISABLED )]
add snmp trap <trapClass> <trapDestination> [-version <version>] [-td <positive_integer>] [-destPort <port>] [-communityName <string>] [-
Using SNMP, you can monitor a partition’s resource (such as bandwidth, connection, and memory) utilization details at real
time on a NetScaler appliance. T his is done by sending a SNMP request (such as SNMP GET, SNMP GET BULK, SNMP
GET NEXT, or SNMP WALK) from the SNMP Manager.
Consider a scenario where a NetScaler administrator wants to know the bandwidth usage of partition P1 on the appliance.
T he SNMP Manager retrieves this information by sending an SNMP GET request on the corresponding OID
(partitionCurrentBandwidth) to the NSIP address of the appliance. T he SNMP agent on the default partition retrieves and
sends the current bandwidth usage of P1 to the SNMP Manager through the NSIP address.
T he following table lists the SNMP counters which are part of partitionTable and its description:
How can I get the technical support bundle specific to an admin partition?
Action Collects run-time statistics on the basis of pre-defined criteria. When used with policies, the feature
Analytics also provides you with the infrastructure for automatic, real-time traffic optimization.
Simplify configuration steps for the Citrix® NetScaler® appliance by using applications, application
templates, NetScaler Gateway applications, and entity templates.
AppExpert
Applications
and Templates
Describes how to use entity templates to set up and configure individual NetScaler entities, such as a
policy or virtual server. An entity template provides a specification and a set of defaults for the
Entity
object.
Templates
AppQoE Application level Quality of Experience (AppQoE) integrates several existing policy-based security
features of the NetScaler appliance into a single integrated feature that takes advantage of a new
queuing mechanism, fair queuing.
HT T P Callouts An HT T P request that the NetScaler appliance generates and sends to an external application when
certain criteria are met during policy evaluation.
Pattern Sets Allow string matching during the evaluation of a default syntax policy.
Policies and Rules that determine the operations that the NetScaler appliance must perform.
Expressions
Rate Limiting Defines the maximum load for a given network entity or virtual entity on the NetScaler appliance.
Responder Bases responses on who sends the request, where it is sent from, and other criteria with security and
system management implications.
Rewrite Rewrites information in the requests or responses handled by the NetScaler appliance.
String Maps Perform pattern matching in all NetScaler features that use the default policy syntax.
Note
For information about policy extensions, see Policy Extensions.
If the website or application does not change frequently, you can use products that collect statistical data, and then
manually analyze the statistics and optimize the delivery of content. However, if you do not want to perform manual
optimizations, or if your website or application is dynamic in nature, you need infrastructure that can not only collect
statistical data but can also automatically optimize the delivery of resources on the basis of the statistics. On the
NetScaler appliance, this functionality is provided by the action analytics feature. T he feature operates on a single
NetScaler appliance and collects run-time statistics on the basis of criteria that you define. When used with NetScaler
policies, the feature also provides you with the infrastructure that you need for automatic, real-time traffic optimization.
When configuring the action analytics feature, you specify the request attributes for which you want to collect statistical
data (for example, URLs and HT T P methods) by configuring default syntax expressions in an entity called a selector. T hen,
you configure an identifier to configure settings such as the sampling interval and sample count. You also configure a policy
that enables the appliance to evaluate traffic as specified by the selector-identifier pair. Finally, you bind the policy to a bind
point to begin collecting statistics.
T he appliance also provides you with a set of built-in selectors, identifiers, and responder policies that you can use to get
started with the feature.
You can configure the feature to perform run-time sorting of the records on an attribute of your choice. You can view the
statistical data by using either the command-line interface or the Stream Sessions tool in the configuration utility.
Selectors are used in rate limiting and action analytics configurations. A selector is optional in a rate limiting configuration,
but is required in a action analytics configuration.
T he order in which you specify parameters is significant. For example, if you configure an IP address and a domain (in that
order) in one selector, and then specify the domain and the IP address (in the reverse order) in another selector, the
NetScaler considers these values to be unique. T his can lead to the same transaction being counted twice. Also, if multiple
policies invoke the same selector, the NetScaler, again, can count the same transaction more than once.
If you modify an expression in a selector, you may get an error if any policy that invokes it is bound to a new policy label or
bind point. For example, suppose that you create a selector named myLimitSelector1, invoke it from myLimitID1, and invoke
the identifier from a DNS policy named dnsRateLimit1. If you change the expression in myLimitSelector1, you might receive
an error when binding dnsRateLimit1 to a new bind point. T he workaround is to modify these expressions before creating
the policies that invoke them.
T he NetScaler appliance provides the following built-in selectors for some of the most common use cases:
Top_URL HTTP.REQ.URL
Top_CLIENTS CLIENT.IP.SRC
Top_URL_CLIENTS_LBVSERVER 1. HTTP.REQ.URL
2. CLIENT.IP.SRC
3. HTTP.REQ.LB_VSERVER.NAME
Top_URL_CLIENTS_CSVSERVER 1. HTTP.REQ.URL
2. CLIENT.IP.SRC
3. HTTP.REQ.CS_VSERVER.NAME
Top_MSSQL_QUERY_DB_LBVSERVER 1. MSSQL.REQ.QUERY.TEXT
2. MSSQL.REQ.LB_VSERVER.NAME
You can also configure a selector with expressions that identify the request attributes of your choice. For example, you
might want to create a record for a request that arrives with a specific header. To evaluate the header, you can add
HTTP.REQ.HEADER("<header_name>") to the selector that you intend to use.
At the command prompt, type the following commands to configure a selector and verify the configuration:
Example
> add stream selector myselector HTTP.REQ.URL CLIENT.IP.SRC
Done
> show stream selector myselector
Name: myselector
Expressions:
1) HTTP.REQ.URL
2) CLIENT.IP.SRC
Done
>
T o modify a selector, type the set stream selector command, the name of the selector, and the rule parameter with the
expressions. Enter the existing expressions that you want to retain, along with the new expressions that you want to
add.
T o remove a selector, type the rm stream selector command and the name of the selector.
T he NetScaler appliance includes the following built-in stream identifiers for common use cases. All the built-in identifiers
specify a sample count of 1 and an interval of 1 minute. Additionally, they sort the data on the REQUESTS attribute. T hey
differ only in being associated with different built-in selectors. Each built-in identifier is associated with a built-in selector of
the same name (for example, the built in identifier Top_URL is associated with the built-in selector Top_URL). Following are
the built-in identifiers:
Top_URL
Top_CLIENTS
Top_URL_CLIENTS_LBVSERVER
Top_URL_CLIENTS_CSVSERVER
Top_MSSQL_QUERY_DB_LBVSERVER
Top_MYSQL_QUERY_DB_LBVSERVER
For more information about the built-in selectors, see Configuring a Selector.
Note: T he maximum length for storing string results of selectors (for example, HT T P.REQ.URL) is 60 characters. If the string
(for example, URL) is 1000 characters long, of which 50 characters are enough to uniquely identify a string, use an
expression to extract only the required 50 characters.
You cannot modify a built-in identifier's configuration. However, you can create an identifier with a configuration of your
choice.
At the command prompt, type the following commands to configure a stream identifier and verify the configuration:
add stream identifier <name> <selectorName> [-interval <positive_integer>] [-SampleCount <positive_integer>] [-sort
<sort>]
show stream identifier <name>
Example
> add stream identifier myidentifier Top_URL -interval 10 -sampleCount 100
Done
Number of Req T he number of requests for which records were created in the last <interval>
requests number of minutes.
Bandwidth BandW T he total bandwidth consumed by the requests that were received in the last
consumed <interval> number of minutes. T he total bandwidth of a request is the bandwidth
consumed by the request and its response.
T he value is rounded off to the next higher or next lower integer value.
Consequently, it might differ slightly from the expected value. For example, if a
request's total bandwidth consumption is 2.2 KB, one instance of the request might
be shown as having consumed 2 KB and two instances might be shown as having
consumed 4 KB, but three instances might be shown as having consumed 7 KB.
Response RspTime T he average response time for all the requests received in the last <interval> number
time of minutes.
Concurrent Conn T he total number of concurrent connections that are currently open.
connections
stat stream identifier <name> [<pattern> ...] [-detail] [-fullValues] [-ntimes <positive_integer>] [-logFile <input_filename>] [-
sortBy <sortBy> [<sortOrder>]
Examples
Example 1 sorts the output on the BandW column, in the descending order. Example 2 sorts the output in Example 1, on the
Req column, and in the ascending order
RspTime Conn
User1 5694 0
User2 109 0
User3 3 0
Done
Example 2
RspTime Conn
User1 5694 0
User3 3 0
User2 109 0
Done
In the command-line interface, you can group the output by using patterns of your choice. In the configuration utility, the
pattern depends on the choices you make when drilling down through the values of various selector expressions. For
example, consider a selector that has the expressions HTTP.REQ.URL, CLIENT.IP.SRC, and
HTTP.REQ.LB_VSERVER.NAME, in that order. T he statistics home page displays icons for each of these expressions. If
you click the icon for CLIENT.IP.SRC, the output is based on the patterns * ? *. T he output displays statistics for each
client IP address. If you click an IP address, the output is based on the patterns * <IP address> ? and ? <IP address> *
where <IP address> is the IP address you selected. In the resulting output, if you click a URL, the pattern used is <URL> <IP
address> ?.
At the command prompt, enter the following command to group the records on the basis of a selector expression:
Examples
Each example uses a different pattern to demonstrate the effect of the pattern on the output of the stat stream
identifier command. T he selector expressions are HTTP.REQ.URL and HTTP.REQ.HEADER("UserHeader"), in that order.
T he requests contain a custom header whose name is UserHeader. Note that in the examples, a given statistical value
changes as determined by the grouping, but the sum total of the values for a given field remains the same.
Example 1
In the following command, the pattern used is ? ?. T he appliance groups the output on the values collected for both
selector expressions. T he row headers consist of the expression values separated by a question mark (?). T he row with the
header /mysite/mypage1.html?Ed displays statistics for requests made by user Ed for the URL /mysite/mypage1.html.
RspTime Conn
In the following command, the pattern used is * ?. T he appliance groups the output on the values accumulated for the
second expression HTTP.REQ.HEADER("UserHeader"). T he rows display statistics for all requests made by users Grace,
Ed, and Joe.
In the following command, the pattern used is ? *, which is the default pattern. T he output is grouped on the values
collected for the first selector expression. Each row displays statistics for one URL.
RspTime Conn
/mysite/mypage2.html 0 0
/mysite/mypage1.html 0 0
/mysite/ 6 0
Done
Example 4
In the following command, the pattern used is * *. T he appliance displays one set of collective statistics for all the requests
received, with no row title.
In the following command, the pattern is /mysite/mypage1.html *. T he appliance displays one set of collective statistics for
At the command prompt, enter the following commands to clear a stream session and verify the results:
Example
T his example uses the stat stream identifier command first, so that a comparison can be made with the stat stream
identifier command that is used for verifying the result of the clear stream session command.
T he action analytics feature introduces a set of default syntax expressions and functions for collecting and evaluating
data. T he expression ANALYTICS.STREAM(<identifier_name>) is used for referencing the identifier that you want to use.
T he expression COLLECT_STATS is used to collect statistical data. Functions such as IS_TOP(<uint>) and
IS_TOP_FREQUENTS(<uint>) are used for making automatic, real-time traffic optimization decisions.
IS_TOP(<number>). Finds if a given object is in the top <number> of elements. For example, is the element among the
top 10 elements. When multiple elements have the count, they are considered to be similar in nature. T he sort function
must be turned on to avoid an undef condition.
IS_TOP_FREQUENTS(<frequency>). Finds if a given object is in the top <frequency> of the elements that are in the top
elements. For example, is the element among the top 50% of all the top elements maintained. Elements having the same
values are considered similar in nature. T he sort function must be turned on to avoid an undef condition.
It is your policy configuration that determines whether the NetScaler appliance must only collect data from traffic or also
perform an action. If the appliance must only collect statistical data, you can configure a policy with the rule
ANALYTICS.STREAM(<identifier_name>).COLLECT_STATS and the action NOOP. T he NOOP policy must be the policy
with the highest priority at the bind point. T his policy is sufficient if you are only collecting statistics. Traffic optimization
decisions, such as what to compress or cache, must be based on manual, periodic evaluation of the statistical data.
If, in addition to collecting statistics, the appliance must also perform an action on the traffic, you must configure the
gotoPriorityExpression parameter of the NOOP policy such that another policy that has the desired rule and action is
evaluated subsequently. T his second policy must have a rule that begins with the ANALYTICS.STREAM(<identifier_name>)
prefix and a function that evaluates the data.
Following is an example of two responder policies that are configured and bound globally. T he policy
responder_stat_collection enables the appliance to collect statistics based on the identifier, myidentifier. T he policy
responder_notify evaluates the data that is collected.
> add responder action send_notification respondwith '"You are in the Top 10 list for bandwidth consumption"'
Done
> add responder policy responder_stat_collection' ANALYTICS.STREAM("myidentifier").COLLECT_STATS' NOOP
Done
> add responder policy responder_notify 'ANALYTICS.STREAM("myidentifier").BANDWIDTH.IS_TOP(10)' send_notification
Done
> bind responder global responder_stat_collection 10 NEXT
Done
> bind responder global responder_notify 20 END
In general, you can regulate bandwidth consumption either per client device or per user. T his use case demonstrates how
you can limit bandwidth consumption per client to 100 MB over a time period of one hour. T he use case also demonstrates
how you can regulate bandwidth consumption per user to 100 MB over a time period of one hour, by using a custom
header that provides the user name. In both cases, the tracking of bandwidth consumption over a moving time period of
one hour is achieved by setting the interval parameter in the stream identifier to 60 minutes. T he use cases also
demonstrate how you can import an HT ML page to send to a client that has exceeded the limit. Importing an HT ML page
not only simplifies the configuration of the responder action in these use cases, but also simplifies the configuration of all
responder actions that need the same response.
In the command-line interface, perform the following tasks to configure action analytics for limiting a client’s or user’s
bandwidth consumption. Each step includes sample commands and their output.
1. Set up your load balancing configuration. Configure load balancing virtual server mysitevip, and then configure all the
services that you need. Bind the services to the virtual server. T he following example creates ten services and binds the
services to mysitevip.
> add lb vserver mysitevip HTTP 192.0.2.17 80
Done
> add service service[1-10] 192.0.2.[240-249] HTTP 80
service "service1" added
service "service2" added
service "service3" added
.
.
.
service "service10" added
Done
> bind lb vserver vserver1 service[1-10]
service "service1" bound
service "service2" bound
service "service3" bound
.
.
.
Done
> add responder action crossed_limits respondwithhtmlpage crossed-limits.html
Done
5. Configure the responder policies. Configure responder policy myrespol1 with the rule
ANALYTICS.STREAM("myidentifier").COLLECT_STATS and the action NOOP. T hen, configure policy myrespol2 for
determining whether a client or user has crossed the 100 MB limit. T he policy myrespol2 is configured with the responder
action crossed_limits.
> add responder policy myrespol1 'ANALYTICS.STREAM("myidentifier").COLLECT_STATS' NOOP
Done
> add responder policy myrespol2 'ANALYTICS.STREAM("myidentifier").BANDWIDTH.GT(1048576)' crossed_limits
Done
6. Bind the responder policies to the load balancing virtual server. T he policy myrespol1, which only collects statistical
data, must have the higher priority and a GOT O expression of NEXT.
> bind lb vserver mysitevip -policyName myrespol1 -priority 1 -gotoPriorityExpression NEXT
Done
> bind lb vserver mysitevip -policyName myrespol2 -priority 2 -gotoPriorityExpression END
Done
7. Test the configuration. T est the configuration by sending test HT T P requests, from multiple clients or users, to the load
balancing virtual server and using the stat stream identifier command to view the statistics that are collected for the
specified identifier. T he following output displays statistics for clients.
> stat stream identifier myidentifier -sortBy BandW –fullValues
Stream Session statistics
Req BandW
192.0.2.30 5000 3761
192.0.2.31 29 2602
192.0.2.32 25 51
Prebuilt application templates for widely used Web applications, such as Microsoft Outlook Web Access and Microsoft
SharePoint, are available on the AppExpert Templates page of the Citrix Community website at
"http://community.citrix.com/display/ns/AppExpert+Templates."
Each prebuilt template provides you with an initial configuration for managing the associated Web application. You can
customize prebuilt application templates for your organization. If a prebuilt application template does not suit your
requirements, you can create a custom application without using a template.
Regardless of whether you use a prebuilt application template or you create a custom application, you can export the
configuration to a template file. You can then share the template with other administrators or import the template to
other NetScaler appliances that require a similar AppExpert application configuration.
To get started with an AppExpert application, you must first obtain the appropriate application template and import the
template to the NetScaler appliance. After the AppExpert application is set up, you must verify that the application is
working correctly. If required, you can customize the configuration to suit your requirements.
Periodically, you can verify and monitor the configuration by viewing the hit counters for various application components,
statistics, and the Application Visualizer. You can also configure authentication, authorization, and auditing (AAA) policies for
the application.
Updated: 2013-08-30
Following are the terms used in the AppExpert applications feature and the descriptions of the entities for which the terms
are used:
Public Endpoint. T he IP address and port combination at which the NetScaler appliance receives client requests for the
associated web application. A public endpoint can be configured to receive either HT T P or secure HT T P (HT T PS) traffic. All
client requests for the web application must be sent to a public endpoint. An AppExpert application can be assigned
multiple endpoints. You configure public endpoints after you import a template.
Application Unit. An AppExpert application entity that processes a subset of web application traffic and load balances a
set of services that host the associated content. T he subset of traffic that an application unit must manage is defined by a
rule. Each application unit also defines its own set of traffic optimization and security policies for the requests and
responses that it manages. T he NetScaler services associated with these policies are Compression, Caching, Rewrite,
Responder, and application firewall.
By default, every AppExpert application with at least one application unit includes a default application unit, which cannot
be deleted. T he default application unit is not associated with a rule for identifying requests and is always placed last in the
Application units and their associated rules, policies, and actions are included in AppExpert application templates.
Service. T he combination of the IP address of the server that hosts the web application instance and the port to which
the application is mapped on the server, in the format <IP address>:<Port>. A web application that serves a large number of
requests is usually hosted on multiple servers. Each server is said to host an instance of the web application, and each such
instance of the web application is represented by a service on the NetScaler appliance. Services are deployment-specific,
and are therefore not included in templates. You must configure services after you import a template.
Application Unit Rule. Either a classic expression or a default syntax expression that defines the characteristics of a traffic
subset for an application unit. T he following example rule is a default syntax expression that identifies a traffic subset that
consists of four image types:
For more information about default syntax expressions and classic policy expressions, see Policies and Expressions.
Traffic Subset. A set of client requests that require a common set of traffic optimization and security policies. A traffic
subset is managed by an application unit and is defined by a rule.
If the request does not satisfy the rule, the request is evaluated against the rule for the next topmost application unit. In
this order, the request is evaluated against each application unit rule until the request satisfies a rule. If the request does
not satisfy any of the configured rules, it is processed by the default application unit, which is always the last application
unit.
You can configure multiple public endpoints for an AppExpert application. In such a configuration, by default, each
application unit processes requests received by all the public endpoints and load balances all the services that are
configured for the application. However, you can specify that an application unit processes traffic from only a subset of
the public endpoints and load balances only a subset of the services that are configured for the AppExpert application.
T he following flow diagram illustrates the AppExpert Application flow sequence for using a built-in application template.
If you prefer to create a customized application without using a template, do the following:
Periodically, you can verify and monitor the configuration by viewing the hit counters for various application components. You can also configure authentication,
authorization, and auditing (AAA) policies for the application.
If you prefer to set up the application by using a prebuilt application template, do the following:
Citrix NetScaler's video tutorials enable you to understand NetScaler features in easy and simple way. Watch https://www.youtube.com/watch?v=aqayflvCR_0 video
to learn how to set up an application using AppExpert Application template.
1. Application components (for example, web pages, files, archives, and web services)
2. T raffic management entities (for example, virtual server IP addresses and associated load-balancing algorithms, and SSL
offload settings) for the application components.
3. Netscaler policies used for optimizing the application traffic.
Note: Application templates are available in different versions for configuring different types of NetScaler appliances.
Note: When you import a template from an appliance, you have to provide the variable value available in the template. By
default, the pre-configured value is displayed.
After you import the template files, the application-configuration and deployment information populates the target
application automatically. T he appliance imports all the configuration from the template files through the NIT RO API. If
you do not import the deployment file, the system generates an application populated with content switching virtual server
configuration. For more information about the format of application templates and deployment files, see "Understanding
Netscaler Application Templates and Deployment Files" section.
When you import a template, if you do not include a deployment file, you have to configure the public endpoints in the
application that the system automatically generates from the template. One endpoint for HT T P and another endpoint for
HT T PS. When configuring a public endpoint of type HT T PS, make sure you enable the SSL feature, bind the server
certificate, and include the server-certificate and certificate-key files.
For more information about configuring endpoints after you import a template, see "Configuring Public Endpoints" topic.
Citrix NetScaler's video tutorials enable you to understand NetScaler features in an easy and simply way. Watch
https://www.youtube.com/watch?v=AR9TwSD9uJM video to learn how to import an application template.
Application At least one public endpoint is up. T he application will accept client requests from the public
endpoints that are up.
Application T he application unit is up. T he application unit is up when at least one service or service group is up.
unit
Application T he public endpoint is out of service (disabled). T his indicator is displayed when only one public
endpoint is configured for the AppExpert application.
Application All the endpoints that are configured for the application are out of service. T his indicator is
displayed only when multiple endpoints are configured for the application.
Application All the services configured for the application unit are down.
unit
You must ensure that the icons for each application and its application units are green at all times. If the icon that is
displayed for an application is not green, verify that you have configured the public endpoints correctly. If the icon that is
displayed for an application unit is not green, verify that the services are configured correctly. However, note that a green
indicator does not mean that the state of all associated entities is UP. It only means that the application has sufficient
resources (endpoints and services) to serve client requests. To verify that the state of all associated entities is UP, check the
health of all the entities on the statistics page for the application.
After you verify that the AppExpert application configuration is working correctly, you can configure the application and
the deployment settings to suit your requirements. When you import an application template and deployment file, the
system automatically populates the target application with the available configuration settings (such as application units,
application unit rules, policies, persistence settings, load balancing methods, profiles, and traffic settings). In this application,
you can configure deployment settings such as public endpoints, services, and service groups for each traffic subset. If you
want the AppExpert application to manage a traffic subset that is not included in the template, you can either add an
application unit for a traffic subset or modify the existing application unit. After you customize the configuration, you can
also specify the order of evaluation for each traffic subset that the application manages.
Also, you can configure the policies that the template provided. If the AppExpert application template does not include
policies for a particular NetScaler feature, such as Rewrite or application firewall, you can configure your own policies.
If endpoints are already configured for the application, you can dissociate endpoints from the AppExpert application and
delete any endpoints that you no longer need. Note that when you dissociate a public endpoint from the AppExpert
application, the endpoint is automatically unbound from the associated application unit, but it is not deleted from the
system.
In the Create public endpoint dialog box, you can specify only the name, IP address, port, and protocol for the
endpoint. You can specify additional endpoint settings after you create the public endpoint. To specify additional
endpoint settings, after you create the endpoint, in the Choose Public Endpoints dialog box, click the endpoint, and
then click Open. T hen, in the Configure Public Endpoint dialog box, provide additional settings, and then click OK.
For more information about the parameters in the Create public endpoint and Configure Public Endpoint dialog boxes,
see "Content Switching."
If you want to modify a public endpoint, click the endpoint, and then click Open. T hen, in the Configure Public
Endpoint dialog box, modify settings for the endpoint, and then click OK.
For more information about the parameters in the Configure Public Endpoint dialog box, see "Content Switching."
4. Click Close.
For information about the settings in the Create Service, Configure Service, and Create Service Group dialog boxes, see
"Load Balancing."
When configuring services and service groups for an application unit, you might choose to specify load balancing settings
such as the weights that services must be assigned and the desired load balancing, persistence, and spillover methods. For
more information about these settings, see Load Balancing.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Applications.
2. In the details pane, right-click the application unit for which you want to modify the rule, and then click Open.
3. In the Configure Application Unit dialog box, do the following:
1. T o specify the format of the new expression, do one of the following:
T o specify that you want to configure a classic expression in the Rule box, click Classic Syntax.
T o specify that you want to configure an advanced expression in the Rule box, click Default Syntax.
2. In the Rule box, configure the expression.
4. Click OK.
If you create an AppExpert application without using a template, you must configure all the policies that the web
application needs.
T he GUI uses various icons to indicate whether or not policies are configured for a feature. For an application unit, if a
policy is configured for a given feature, an icon that represents the feature is displayed. For example, if a compression policy
is configured for an application unit, a compression icon is displayed in the Compression column for the application unit. For
features for which no policy is configured, an icon depicting a plus sign (+) is displayed.
Note: When configuring policies for application units, you might need to configure policies and expressions that are either
in the classic or default syntax. Additionally, when you configure default syntax policies, you might need to specify
parameters such as Goto expressions and invoke policy banks. For information about configuring policies and expressions in
both formats, see Policies and Expressions.
Configuring Compression Policies
You can use either classic policies or advanced policies to configure compression, but you cannot bind compression policies
of both types to the same application unit.
T o modify a compression policy that is already bound to the application unit, click the name of the policy, and then
click Modify Policy. T hen, in the Configure Compression Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Compression Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Caching policies.
You can configure both request-time and response-time Caching policies for an application unit. After evaluating all of
the request-time policies, if no match is found, the appliance evaluates response-time policies.
T o modify a Caching policy that is already bound to the application unit, click the name of the policy, and then click
Modify Policy. T hen, in the Configure Cache Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Cache Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Rewrite policies.
You can configure both request-time and response-time Rewrite policies for an application unit. After evaluating all of
the request-time policies, if no match is found, the appliance evaluates response-time policies.
T o modify a Rewrite policy that is already bound to the application unit, click the name of the policy, and then click
Modify Policy. T hen, in the Configure Rewrite Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Rewrite Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Responder policies.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
You can configure both classic and default syntax policies and expressions for Application Firewall. However, if a policy of
one type is already bound globally or to a virtual server that is configured on the appliance, you cannot bind a policy of the
other type to an application unit. For example, if a default syntax policy is already bound either globally or to a virtual server,
you cannot bind a classic policy to an application unit.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Application Firewall Policy dialog box, configure the policy, and then click Create.
For information about modifying a application firewall policy, see "Policies."
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
2. In the Application Unit slider, set the following parameters:
1. Name
2. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next
component. For example, type HTTP and then type a period. A drop-down menu appears. The contents of this menu provide the keywords that can follow the initial keyword that you entered. Select a component from the drop-down menu. The Expression* text box
now displays the components that you have added to the expression (for example, HTTP.REQ). Continue adding components until the complete expression is formed.
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression
on the Application Unit page.
1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
Citrix NetScaler's video tutorials enable you to understand NetScaler features in an easy and simple way. Watch https://www.youtube.com/watch?v=bJ5_i8fV2hc video to learn how configure an application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
b. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
b. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Public Endpoint section, click + to configure a new public endpoint.
3. In the Public Endpoint slider, do one of the following:
1. Click New to create a new endpoint.
2. Click Existing Public Endpoint to select an endpoint from the drop-down list.
4. Set the following endpoint parameters:
1. Name
2. IP address
3. Protocol
4. Port
5. Click Continue to configure additional settings such as application units, GSLB server bindings, policies, profiles, push,
traffic settings, and authentication.
6. Click OK and then Done.
7. Click Continue and then Done.
1. Navigate to AppExpert > Applications, select an application, and click Edit. In the Public Endpoint section, select an endpoint, click the pen icon, and modify the
endpoint settings.
1. Navigate to AppExpert > Applications > Public Endpoint, click the pen icon to view the delete icon next to the entity.
Citrix NetScaler's video tutorials enable you to understand NetScaler features in an easy and simply way. Watch https://www.youtube.com/watch?v=z4v-edQiVpw
video to learn how to configure a public endpoint.
When a request matches the rule that is configured for an application unit, the request is processed by the application unit,
and no further matching is performed. T herefore, the order of evaluation of application units becomes an important factor
if the traffic subsets for two or more application units overlap. If the traffic subsets for two or more application units
overlap, you must specify the order in which an incoming request is matched against the application unit rules.
1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, click the
Pencil icon and then hover the cursor over the check box to the left of the name of the application unit. Click the icon
that appears next to the check box and hold down the mouse to drag the application up or down to a new location in
the priority list.
1. Navigate to AppExpert > Applications, select an application entity, and click Visualizer.
To configure AAA users and AAA user groups for an application by using the configuring utility
1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Advanced Settings section, click Authorization, and configure authorized users and user groups.
3. Click the AAA user section to bind authorized users to the application.
4. In the AAA User slider, set the parameters .
5. Click Continue, and then click Authorization Policies in the Advanced Settings section.
6. In the Authorization Policy slider, bind an authorization policy to the application.
7. Click Continue, and then click the Authorization Group section in the Advanced Settings section.
8. In the AAA Group Binding slider, bind an authorization user group to the application.
9. Click Continue, and then click Policies in the Advanced Settings section.
10. In the Policies slider, bind an Audit Syslog or Audit NSlog policy to the application.
11. Click Continue and then Done.
To edit AAA users and AAA user groups for an application by using the configuration utility
Navigate to AppExpert > Applications > Advanced Settings and click Authorization. T hen click the edit icon and specify
values for user or user-group authorization settings.
To delete AAA users and AAA user groups by using the configuration utility
Navigate to AppExpert > Applications, select an application and click Edit. In the Applications page, click Advanced
Settings and click Authorization. Click the delete icon next to the entity.
You can also view the hit counters for various entities at regular intervals to make sure that counters are being updated.
Updated: 2013-08-30
In the Applications node, you can select an application and view the Statistics page for the application. On the Statistics
page, you can monitor the health and states of public endpoints and application units, and view the following statistical
information:
Requests and responses per second for each of the public endpoints and application units.
Bytes per second, at each endpoint, for incoming and outgoing traffic.
Application unit hit counters and the number of client and server connections for each application unit.
Statistics for the services that are bound to the application units.
On the Statistics page, you can also view CPU usage, memory usage, and system logs.
Updated: 2013-08-30
You can use the Application Visualizer to monitor the number of requests received per second at a given point in time by
the vservers and the number of hits per second at a given point in time for Rewrite, Responder, and Cache policies.
T he statistical information is displayed on the respective nodes in the Visualizer. T his information is not updated in real
time and has to be refreshed manually.
Viewing Hits
T he hit counters that are provided for various AppExpert application entities enable you to monitor the functioning of
public endpoints and application units. For an application, the Hits dialog box displays the total number of requests received
by each configured public endpoint. For an application unit, the Hits dialog box displays the number of requests that the
application unit processed from each of the public endpoints and the total hit count. For instructions on viewing hit
counters, see "Verifying and Testing the Configuration."
When deleting an application, you are also prompted to specify whether you want to delete any bound policies and actions
that are not used elsewhere.
1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, click the
delete icon next to the entity
Authentication policies, authorization policies, and auditing policies can be configured in any order. However, before you
configure AAA for an application, you must configure a public endpoint for the application.
Configuring Authentication
Configuring authentication for an application involves specifying an authentication FQDN, an authentication virtual server,
a server certificate, and authentication and session policies. Authentication policies are automatically bound to the
authentication virtual server specified for the application.
Configuring Authorization
You can configure authorization for users and groups to enable then to access an AppExpert application. If the AAA user or
group for which you want to configure permissions has not already been created, you can create it from AppExpert and
then configure permissions for application access.
T he user or group is created with the permission set to Allow. To change the permission setting, right-click the group
or user, and then click the permission setting.
4. Click Close.
Configuring Auditing
When you configure auditing policies for an application, you must specify the server to which the log messages must be
directed, the format of the messages logged, and the log level. Optionally, you can configure other settings, such as the log
facility and date format. Auditing policies are automatically bound to all the AppExpert application’s public endpoints.
T o modify the priority that is assigned to the policy by default, under Priority, double-click the priority, and then
type a new priority value.
T o modify the settings of the audit server, under Server, double-click the name of the server, and then, in the
Configure Auditing Server dialog box, modify the settings as appropriate. You can modify all the settings in this
dialog box except the name of the audit server and the audit type. For more information about the settings in the
Configure Auditing Server dialog box, see "Auditing Policies."
To create a new auditing policy, under Policy Name, click New Policy, and then, in the Create Auditing Policy dialog
box, do the following:
After you configure AAA for an application, you can disable the AAA configuration for that application. When you disable
AAA for an application, the configuration is not lost. You can enable AAA for the application when you want to reapply the
configuration.
To create an AppExpert application without a template, you must first create an application and application units. T hen,
you configure public endpoints, services, and service groups. Finally, you configure the policies that determine how
application traffic is evaluated and processed.
After you create the application and application units and configure policies, you must verify the configuration and test it
to make sure that it is working correctly, just as you would when you configure an application by using a prebuilt AppExpert
application template. T hen, you must monitor the application to make sure that the application and its entities are working
correctly.
Creating an Application
Updated: 2013-08-30
When you create an AppExpert application, the appliance creates a container to which you can add application units. T he
default application unit is not created until you create the first application unit.
Updated: 2013-08-30
For each subset of traffic associated with your web application, you must create an application unit.
Updated: 2013-08-30
After you have created all the application units that you require, you must configure one or more public endpoints to
enable clients to access the web application through the NetScaler appliance.
In the Create public endpoint dialog box, you can specify only the name, IP address, port, and protocol for the
endpoint. You can specify additional endpoint settings after you create the public endpoint. To specify additional
endpoint settings, after you create the endpoint, in the Choose Public Endpoints dialog box, click the endpoint, and
then click Open. T hen, in the Configure Public Endpoint dialog box, provide additional settings, and then click OK.
For more information about the parameters in the Create public endpoint and Configure Public Endpoint dialog boxes,
see "Content Switching."
If you want to modify a public endpoint, click the endpoint, and then click Open. T hen, in the Configure Public
Endpoint dialog box, modify settings for the endpoint, and then click OK.
For more information about the parameters in the Configure Public Endpoint dialog box, see "Content Switching."
4. Click Close.
Updated: 2013-08-30
For an application unit, you specify public endpoints in the same way as you would specify public endpoints for an
application that is created from an AppExpert application template. For more information about specifying a subset of the
endpoints for an application unit, see "Configuring Endpoints for an Application Unit."
Updated: 2013-08-30
Services and service groups are available for application units only after you configure the services and service groups for
the AppExpert application. T herefore, you must configure services and service groups for the AppExpert application before
you configure the services for the application units. All the services and service groups that you configure for an AppExpert
application must use the same protocol (either HT T P or HT T PS). T he procedure for configuring services and service groups
for an AppExpert application that is not created from a template is the same as that for an application created from a
template.
For information about the settings in the Create Service, Configure Service, and Create Service Group dialog boxes, see
"Load Balancing."
Updated: 2013-08-30
After you configure services and service groups, you must configure services and service groups for each application unit.
However, this step is not necessary if each backend service hosts all the content associated with the web application. You
configure services and service groups for an application unit if the content associated with the application unit is hosted on
only a subset of the backend servers.
Configuring Policies
Updated: 2013-08-30
T he procedures for configuring policies for an AppExpert application that is created without using a template are the same
as those for an AppExpert application that was created from a template. For more information, see "Configuring Policies
for Application Units."
AppExpert application template files can be exported either to the template directory on the NetScaler appliance or to a
folder on your local computer. You can then upload and download the templates to and from the NetScaler appliance and
rename the templates that are stored in the AppExpert application templates directory on your appliance.
AppExpert application template files can be exported either to the template directory on the NetScaler appliance or to a
folder on your local computer. You can then upload and download the templates to and from the NetScaler appliance and
rename the templates that are stored in the AppExpert application templates directory on your appliance.
1. Navigate to AppExpert > Application, select an application entity, and then click Edit.
2. On the Applications page, click the Export as a T emplate link to export the application configuration and deployment
settings as a template.
3. In the Export Application slider, set the following parameters:
1. T emplate Filename
2. Deployment Filename
4. Click Continue and Done.
5. Navigate to AppExpert > Application and click Manage Templates to show the exported configuration as files on the
Template File and Deployment File tabs.
However, if the content switching virtual server is already configured as the public endpoint for an AppExpert application,
you cannot export the configuration to a template file . In this scenario, you must export the associated AppExpert
application to a template. For more information about exporting an AppExpert application to a template file, see Exporting
an AppExpert Application to a Template File.
To export a content switching configuration to an application template file f rom the Content Switching
Visualizer
To export a content switching configuration to an application template file f rom the Content Switching
As an example, consider the following policy expression that is configured to evaluate the value of the Host header in an
HT T P request:
HTTP.REQ.HEADER("Host").CONTAINS("server1")
If you want the server name to be configurable at import time, you can specify the string "server1" as a variable. When
importing the template, you can specify a new value for the variable on the Variables tab.
Assign additional strings to an existing variable. After you create a variable for a string, you can select and assign other
parts of the same or different expression to the variable. T he strings you assign to a variable need not be the same. At
import time, all the strings that are assigned to the variable are replaced with the value that you provide.
View the string or strings that are assigned to the variable.
View a list of all the entities and parameters that use the variable.
In the export application template wizard, you can define variables in certain fields (fields with an adjacent button) for
the following entities:
Cache policies
Rewrite policies
Rewrite actions
Responder policies
Responder actions
If a variable has multiple strings assigned to it, when you specify a new value for the variable during import, all strings
assigned to the variable are replaced with the new value.
7. Click Close.
To download an AppExpert application template f rom the NetScaler appliance to your local computer
NetScaler application template f ile. Contains application-configuration information such as application units, rules,
and configured policies.
Deployment f ile. Contains deployment-specific information such as public endpoints, services, associated IP addresses,
and configured variables.
In a template file or deployment file, each unit of application-configuration information is encapsulated in a specific XML
element that is meant for that unit type. For example, each public endpoint and associated endpoint details are
encapsulated within the <appendpoint> and </appendpoint> tags, and all the endpoint elements are encapsulated within
the <appendpoint_list> and </appendpoint_list> tags.
Note: After you export a NetScaler application, you can add elements, remove elements, and modify existing elements
before importing the application to a NetScaler appliance.
Following is an example of a template file that was created from a NetScaler application called "SharePoint_T eam_Site":
Following is the deployment file associated with the "SharePoint_T eam_Site" application in the preceding example:
<?xml version="1.0" encoding="UTF8" ?>
<template_deployment>
<template_info>
<application_name>SharePoint_Team_Site</application_name>
<templateversion_major>1</templateversion_major>
<templateversion_minor>1</templateversion_minor>
<author>Ed</author>
<introduction>An application for managing a SharePoint team site with images, reports, and, XML content.</introduction>
<summary>This template includes variables</summary>
<version_major>9</version_major>
<version_minor>3</version_minor>
<build_number>38</build_number>
</template_info>
<appendpoint_list>
<appendpoint>
<ipv46>10.111.111.1</ipv46>
<port>80</port>
<servicetype>HTTP</servicetype>
</appendpoint>
</appendpoint_list>
<service_list>
<service>
<ip>10.102.29.5</ip>
<port>80</port>
<servicetype>HTTP</servicetype>
</service>
<service>
.
.
.
</service>
.
.
.
</service_list>
<variable_list>
<variable>
<name>body_size</name>
<description>Evaluation Scope</description>
<value>10000</value>
</variable>
<variable>
.
To delete a template file f rom the application template directory by using the configuration utility
1. Navigate to AppExpert > Applications and then click Manage Template. Select a file from Template Files tab page
or Deployment Files tab page and click Delete.
You can also configure NetScaler Gateway policies for intranet subnets, file shares, and other network resources.
Finally, you can create bookmarks for AppExpert applications and certain resources if you want users to be able to access
them from the NetScaler Gateway home page.
You can configure the entities in the NetScaler Gateway Applications feature only by using the configuration utility.
Updated: 2013-07-17
When you create an AppExpert application in the Applications node in the configuration utility, a corresponding Access
Gateway application is automatically created in the Access Gateway Applications node. Additionally, a rule that uses the
AppExpert application’s configured public endpoint is automatically created for the Access Gateway application entry. If
multiple endpoints are configured for the AppExpert application, the rule includes all the configured public endpoints. T he
NetScaler appliance uses this rule to apply any configured Access Gateway policies to the traffic received at the AppExpert
application's public endpoint. Traffic received at the AppExpert application’s public endpoint is first evaluated against the
NetScaler Gateway policies and then evaluated against the policies configured for AppExpert application’s application units.
T he rule that is created for the Clientless Access policies for an Access Gateway application is an advanced expression that
also uses the public endpoint that is configured for the AppExpert application. T herefore, before you configure NetScaler
Gateway policies for an AppExpert application, you must configure public endpoints for the AppExpert application.
When you include the NetScaler Gateway configuration in an application template, deployment-specific information, such
as IP address and port information, and the rule that is created from this information are not included in the template.
On the NetScaler appliance, you can configure Authorization policies for a file share that is hosted on your organization’s
network.
When you create a file share, you specify a name for the file share and the network path to the file share. In the network
path, you can specify either the name of the server or the server IP address. A rule that uses the components of the file
share path is automatically created for the file share. T his rule enables the appliance to identify requests for files hosted on
the file share server. Any Authorization policies that are configured for the file share are applied to incoming requests.
T he NetScaler configuration for a file share cannot be saved in AppExpert application templates.
For the intranet subnets that form a part of your network, you can configure policies for Authorization, Traffic, and TCP
Compression on the NetScaler appliance. When adding an intranet subnet, you specify the IP address and the netmask of
the intranet subnet. A rule that uses these two parameters is automatically created for the intranet subnet. T he appliance
applies the configured policies to any request that has a destination IP address and netmask set to the subnet’s IP address
and netmask, respectively.
T he NetScaler configuration for an intranet subnet cannot be saved in AppExpert application templates.
Updated: 2013-07-18
T he Other Resources category enables you to configure Access Gateway policies for any network resource by using a rule
of your choice. When you configure the NetScaler appliance to process requests for the network resource, you configure a
classic expression to identify the requests that are associated with the network resource. You can configure Authorization,
Traffic, Clientless Access, and TCP Compression policies for a network resource in Other Resources. T he NetScaler appliance
applies the configured NetScaler Gateway policies to any requests that match the configured rule.
T he NetScaler configuration for a network resource in Other Resources cannot be saved in AppExpert application
templates.
T he NetScaler Gateway Applications feature enforces a naming convention for some of the entities that you create in this
feature. For example, the names of the profiles that you create for Traffic policies for an intranet subnet always begin with
a string that consists of the name of the intranet subnet followed by an underscore (_). T he name that you provide for the
entity is appended to this string. If the name of a subnet is "subnet1," the name of the profile begins with "subnet1_."
When such a naming convention is required (in the text box in which you type the name of an entity, for example), the user
interface automatically inserts the string with which the name of the entity must begin and does not allow you to modify
it.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, do one of the following:
T o add an intranet subnet, click Intranet Subnets, and then click Add.
T o modify an intranet subnet, click an intranet subnet, and then click Open.
3. In the Create Intranet Subnet or Configure Intranet Subnet dialog box, do the following:
1. In the Name box, type a name for the intranet subnet you are adding. T his parameter cannot be changed for an
existing intranet subnet.
2. In the IP Address box, type the IP address of the intranet subnet.
3. In the Netmask box, type the netmask that will be used for the intranet subnet.
4. Click Create or OK, and then click Close.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, do one of the following:
T o add a resource, click Other Resources, and then click Add.
T o modify a resource, click a resource, and then click Open.
3. In the Create Resource or Configure Resource dialog box, do the following:
1. In the Name box, type a name for the resource you are adding. T his parameter cannot be changed for an existing
resource.
2. In the Rule box, type the rule that will identify the subset of traffic that is associated with the resource you are
adding.
Alternatively, click Configure, and then create the rule in the Create Expression dialog box.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, in the Authorization column, click the icon for the application, file share, intranet subnet, or resource
for which you want to configure authorization policies for AAA users and groups.
3. Do one of the following:
If the AAA user or group for which you want to configure permissions is already in the Groups/Users tree, drag the
user or group from the Groups/Users tree to the Users or Groups node in the <application name> tree. T hen, right-click
the user or group and click Allow.
If the AAA user or group for which you want to configure permissions is not configured on the appliance, in the
<application name> tree, right-click Users or Groups, and then click Add. In the Create AAA Group or Create AAA User
dialog box, fill in the values, click Create, and then click Close.
T he user or group is created with the permission set to Allow. To change the permission setting, right-click the group
or user, and then click the permission setting.
4. Click Close.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, in the T raffic column, click the icon provided for the application, file share, intranet subnet, or
resource for which you want to configure traffic policies.
3. In the Configure T raffic Policies dialog box, do the following:
T o specify an existing traffic policy, click Insert Policy, and then, in the Policy Name column, click the name of the
policy.
To configure a new policy, click Insert Policy, and then, in the Policy Name column, click New Policy. In the Create
Traffic Policy dialog box, in the Name box, after the underscore (_), type a name for the policy. T hen, in Request
Profile, either select an existing request profile or click New to configure a new request profile. You can also select an
existing profile and then click Modify to modify the profile.
For more information about configuring a traffic policy or profile, see NetScaler Gateway , Enterprise Edition at
http://edocs.citrix.com/.
T o modify a policy that you have inserted, in the Policy Name column, click the policy name, and then click Modify
Policy. T o modify only the associated profile, in the Profile column, click the name of the profile, and then click Modify
Profile.
T o regenerate the priorities assigned to the policies, click Regenerate Priorities.
T o specify a new priority value for a policy, in the Priority column, double-click the assigned priority, and then enter the
value you want.
T o unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.
To configure a clientless access policy f or a resource in the NetScaler Gateway Applications node
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, in the Clientless Access column, click the icon for the application, file share, intranet subnet, or
resource for which you want to configure a clientless access policy.
3. In the Configure Clientless Access Policies dialog box, do the following:
T o specify an existing clientless access policy, click Insert Policy, and then, in the Policy Name column, click the name
of the policy.
To configure a new clientless access policy, click Insert Policy, and then, in the Policy Name column, click New Policy. In
the Create Clientless Access Policy dialog box, in the Name box, after the underscore (_), type a name for the policy.
T hen, in Profile, either select an existing profile or click New to configure a new profile. You can also select an existing
profile and then click Modify to modify the profile.
For more information about configuring a clientless access policy or profile, see NetScaler Gateway , Enterprise Edition
at http://edocs.citrix.com/.
T o modify a policy that you have inserted, in the Policy Name column, click the policy name, and then click Modify
Policy. T o modify only the associated profile, in the Profile column, click the name of the profile, and then click Modify
Profile.
T o specify a new priority value for a policy, in the Priority column, double-click the assigned priority, and then enter the
value you want.
T o unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.
To configure a TCP compression policy f or a resource in the NetScaler Gateway Applications node
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, in the T CP Compression column, click the icon for the application, file share, intranet subnet, or
resource for which you want to configure a T CP compression policy.
3. In the Configure T CP Compression Policies dialog box, do the following:
T o specify an existing T CP compression policy, click Insert Policy, and then, in the Policy Name column, click the name
of the policy.
To create a new TCP compression policy, click Insert Policy, and then, in the Policy Name column, click New Policy. In
the Create TCP Compression Policy dialog box, in the Policy Name box, after the underscore (“_”), type a name for the
policy. T hen, in Action, either select an existing action or click New and configure a new action. You can also click View
to view the configured compression type.
For more information about configuring a TCP compression policy or action, see NetScaler Gateway , Enterprise
Edition at http://edocs.citrix.com/.
T o modify a policy that you have inserted, in the Policy Name column, click the policy name, and then click Modify
Policy.
T o regenerate the priorities assigned to the policies, click Regenerate Priorities.
T o specify a new priority value for a policy, in the Priority column, double-click the assigned priority, and then enter the
value you want.
T o unbind a policy, click the policy, and then click Unbind Policy.
4. Click Apply Changes, and then click Close.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Access Gateway
Applications.
2. In the details pane, click the application or resource for which you want to configure a bookmark, and then click
Configure Bookmark.
3. In the Create Bookmark dialog box, configure values for the parameters.
For more information about the parameters in the Create Bookmark dialog box, see NetScaler Gateway , Enterprise
Edition at http://edocs.citrix.com/.
After you verify that the AppExpert application configuration is working correctly, you can configure the application and
the deployment settings to suit your requirements. When you import an application template and deployment file, the
system automatically populates the target application with the available configuration settings (such as application units,
application unit rules, policies, persistence settings, load balancing methods, profiles, and traffic settings). In this application,
you can configure deployment settings such as public endpoints, services, and service groups for each traffic subset. If you
want the AppExpert application to manage a traffic subset that is not included in the template, you can either add an
application unit for a traffic subset or modify the existing application unit. After you customize the configuration, you can
also specify the order of evaluation for each traffic subset that the application manages.
Also, you can configure the policies that the template provided. If the AppExpert application template does not include
policies for a particular NetScaler feature, such as Rewrite or application firewall, you can configure your own policies.
If endpoints are already configured for the application, you can dissociate endpoints from the AppExpert application and
delete any endpoints that you no longer need. Note that when you dissociate a public endpoint from the AppExpert
application, the endpoint is automatically unbound from the associated application unit, but it is not deleted from the
system.
In the Create public endpoint dialog box, you can specify only the name, IP address, port, and protocol for the
endpoint. You can specify additional endpoint settings after you create the public endpoint. To specify additional
endpoint settings, after you create the endpoint, in the Choose Public Endpoints dialog box, click the endpoint, and
then click Open. T hen, in the Configure Public Endpoint dialog box, provide additional settings, and then click OK.
For more information about the parameters in the Create public endpoint and Configure Public Endpoint dialog
boxes, see "Content Switching."
If you want to modify a public endpoint, click the endpoint, and then click Open. T hen, in the Conf igure Public
Endpoint dialog box, modify settings for the endpoint, and then click OK.
For more information about the parameters in the Configure Public Endpoint dialog box, see "Content Switching."
4. Click Close.
For information about the settings in the Create Service, Configure Service, and Create Service Group dialog boxes, see
"Load Balancing."
When configuring services and service groups for an application unit, you might choose to specify load balancing settings
such as the weights that services must be assigned and the desired load balancing, persistence, and spillover methods. For
more information about these settings, see Load Balancing.
1. In the navigation pane of the NetScaler configuration utility, expand AppExpert, and then click Applications.
2. In the details pane, right-click the application unit for which you want to modify the rule, and then click Open.
3. In the Configure Application Unit dialog box, do the following:
1. T o specify the format of the new expression, do one of the following:
T o specify that you want to configure a classic expression in the Rule box, click Classic Syntax.
T o specify that you want to configure an advanced expression in the Rule box, click Default Syntax.
2. In the Rule box, configure the expression.
4. Click OK.
If you create an AppExpert application without using a template, you must configure all the policies that the web
application needs.
T he GUI uses various icons to indicate whether or not policies are configured for a feature. For an application unit, if a
policy is configured for a given feature, an icon that represents the feature is displayed. For example, if a compression policy
is configured for an application unit, a compression icon is displayed in the Compression column for the application unit. For
features for which no policy is configured, an icon depicting a plus sign (+) is displayed.
Note: When configuring policies for application units, you might need to configure policies and expressions that are either
in the classic or default syntax. Additionally, when you configure default syntax policies, you might need to specify
parameters such as Goto expressions and invoke policy banks. For information about configuring policies and expressions in
both formats, see "Policies and Expressions."
Configuring Compression Policies
You can use either classic policies or advanced policies to configure compression, but you cannot bind compression policies
of both types to the same application unit.
T o modify a compression policy that is already bound to the application unit, click the name of the policy, and then
click Modify Policy. T hen, in the Configure Compression Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Compression Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Caching policies.
You can configure both request-time and response-time Caching policies for an application unit. After evaluating all of
the request-time policies, if no match is found, the appliance evaluates response-time policies.
T o modify a Caching policy that is already bound to the application unit, click the name of the policy, and then click
Modify Policy. T hen, in the Configure Cache Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Cache Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Rewrite policies.
You can configure both request-time and response-time Rewrite policies for an application unit. After evaluating all of
the request-time policies, if no match is found, the appliance evaluates response-time policies.
T o modify a Rewrite policy that is already bound to the application unit, click the name of the policy, and then click
Modify Policy. T hen, in the Configure Rewrite Policy dialog box, modify the policy, and then click OK.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Rewrite Policy dialog box, configure the policy, and then click Create.
You can use only default syntax policies and expressions to configure Responder policies.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Responder Policy dialog box, configure the policy, and then click Create.
You can configure both classic and default syntax policies and expressions for Application Firewall. However, if a policy of
one type is already bound globally or to a virtual server that is configured on the appliance, you cannot bind a policy of the
other type to an application unit. For example, if a default syntax policy is already bound either globally or to a virtual server,
you cannot bind a classic policy to an application unit.
T o unbind a policy, click the name of the policy, and then click Unbind Policy.
T o modify the priority assigned to a policy, double-click the priority value, and then enter a new value.
T o regenerate assigned priorities, click Regenerate Priorities.
T o insert a new policy, click Insert Policy and, in the list that is displayed in the Policy Name column, click New Policy.
T hen, in the Create Application Firewall Policy dialog box, configure the policy, and then click Create.
For information about modifying a application firewall policy, see "Policies."
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
2. In the Application Unit slider, set the following parameters:
1. Name
2. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next
component. For example, type HTTP and then type a period. A drop-down menu appears. The contents of this menu provide the keywords that can follow the initial keyword that you entered. Select a component from the drop-down menu. The Expression* text box
now displays the components that you have added to the expression (for example, HTTP.REQ). Continue adding components until the complete expression is formed.
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression
on the Application Unit page.
1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
Citrix NetScaler's video tutorials enable you to understand NetScaler features in an easy and simple way. Watch https://www.youtube.com/watch?v=bJ5_i8fV2hc video to learn how configure an application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
b. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
b. Expression
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications > Application Unit section and then click the plus icon to add a new application unit for a traffic subset.
a. Name
You can insert an expression either by adding the expression components manually or by using the Expression Editor link. To manually add an expression, enter a selector component and then type a period (.) to display a list from which you can select the next component. For ex
If you prefer assistance to form the expression, you can use the Expression Editor link. On the Expression Editor page, you can form an expression by selecting components from the drop-down boxes. Select the components and click Done to insert the expression on the
2. Click the Service section to select or add a virtual service and bind it to the application unit.
3. Click Continue and click the Service Group section to select or add a virtual service group and bind it to the application unit.
4. Click Bind and Continue to configure Advanced Settings (such as Policies, Method, Persistence, Protection, Profiles, Push, Authentication, and Traffic Settings) for the application unit.
5. Click the plus icon in each section to set the configuration parameters.
Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, select an entity, click the edit icon and modify the application unit settings.
Note: You cannot modify the name and rule expression for an existing application unit.
1. Navigate to AppExpert > Applications, select an application entity, and then click Edit.
2. In the Public Endpoint section, click + to configure a new public endpoint.
3. In the Public Endpoint slider, do one of the following:
1. Click New to create a new endpoint.
2. Click Existing Public Endpoint to select an endpoint from the drop-down list.
4. Set the following endpoint parameters:
1. Name
2. IP address
3. Protocol
4. Port
5. Click Continue to configure additional settings such as application units, GSLB server bindings, policies, profiles, push,
traffic settings, and authentication.
6. Click OK and then Done.
7. Click Continue and then Done.
1. Navigate to AppExpert > Applications, select an application, and click Edit. In the Public Endpoint section, select an endpoint, click the pen icon, and modify the
endpoint settings.
1. Navigate to AppExpert > Applications > Public Endpoint, click the pen icon to view the delete icon next to the entity.
Citrix NetScaler's video tutorials enable you to understand NetScaler features in an easy and simply way. Watch https://www.youtube.com/watch?v=z4v-edQiVpw
video to learn how to configure a public endpoint.
When a request matches the rule that is configured for an application unit, the request is processed by the application unit,
and no further matching is performed. T herefore, the order of evaluation of application units becomes an important factor
if the traffic subsets for two or more application units overlap. If the traffic subsets for two or more application units
overlap, you must specify the order in which an incoming request is matched against the application unit rules.
1. Navigate to AppExpert > Applications, select an application and click Edit. In the Application Unit section, click the
Pencil icon and then hover the cursor over the check box to the left of the name of the application unit. Click the icon
that appears next to the check box and hold down the mouse to drag the application up or down to a new location in
the priority list.
1. Navigate to AppExpert > Applications, select an application entity, and click Visualizer.
T he features that are integrated into AppQoE are HT T P Denial-of-Service Protection (HDOSP), Priority Queuing (PQ), and
SureConnect. Collectively these services provide protection against a number of problems:
Simple overload. Any server, no matter how robust, can accept only a limited number of connections at one time. When
a protected web site or application receives too many requests at once, the Surge Protection feature detects the
overload and queues the excess connections til the server can accept them. T he Priority Queuing feature ensures that
whoever most needs access to a resource is provided access without having to wait behind other lower-priority requests.
T he SureConnect feature displays an alternate web page that notifies users that the resource that they requested is
not available.
Denial-of -Service (DOS) attacks. Any public-facing resource is vulnerable to attacks whose purpose is to bring that
service down and deny legitimate users access to it. T he Surge Protection, Priority Queuing, and SureConnect features
help manage DOS attacks as well as other types of high load. In addition, the HT T P Denial-of-Service Protection
feature targets DOS attacks against your web sites, sending challenges to suspected attackers and dropping
connections if the clients do not send an appropriate response.
Until the current version of the NetScaler operating system, these features were implemented at the service level, which
means that each service was assigned its own queues. While service-level queues work, they also have some disadvantages,
most of which are due to the NetScaler appliance having to load balance requests before implementing any of the
protection features that rely on queuing. Implementing protection features before queuing has a number of advantages,
some of which are listed below:
Absolute priority of connections as configured in the priority queuing feature can be maintained.
Connections are not flushed if a service transitions state, as they are in a service-level queue.
During periods of high load, such as a denial-of-service attack, HT T P DoS and SureConnect come into play before load
balancing, allowing these features to detect and divert unwanted or lower-priority traffic from the load balancer before
the load balancer must cope with it.
In addition to implementing fair queuing, AppQoE integrates a set of features that each provide a different set of tools to
achieve a common goal: protecting your networked resources from excessive or inappropriate demand. Putting these
features into a common framework enables you to configure and implement them more easily.
Example
Important: No specific individual parameters are required to create an action, but you must include at least one parameter
or you cannot create the action.
To configure an AppQoE action by using the command line
Example
To configure priority queuing with policy queue depths of 10 and 1000 for medium and lowest priority queues, respectively:
2) Name: appqoe-act-basic-prmedium
ActionType: PRIORITY_QUEUING
Priority: MEDIUM
PolicyQdepth: 10
Qdepth: 0
3) Name: appqoe-act-basic-prlow
ActionType: PRIORITY_QUEUING
Priority: LOW
PolicyQdepth: 1000
Qdepth: 0
Done
To modif y an existing AppQoE action by using the command line
name
A name for the new action, or the name of the existing action that you want to modify. T he name can begin with a letter,
number, or the underscore symbol, and can consist of from one to letters, numbers, and the hyphen (-), period (.) pound (#),
space ( ), at sign (@), equals (=), colon (:), and underscore (_) symbols.
priority
T he priority queue to which the request is assigned. When a protected web server or application is heavily loaded and
cannot accept additional requests, specifies the order in which waiting requests are to be fulfilled when resources are
available. T he choices are:
If priority is not configured, then the NetScaler appliance assigns the request to the LOWEST priority queue by default.
respondWith
Configures the NetScaler ADC to take the specified Responder action when the specified threshold is reached. Must be
used with one of the following settings:
ACS: Serves content from an alternate content service. T hreshold: maxConn (maximum connections) or delay.
NS: Serves a built-in response from the NetScaler ADC. T hreshold: maxConn (maximum connections) or delay.
NO ACTION: Serves no alternative content. Assigns connections to the LOWEST priority queue if the maxConn
(maximum connections) or delay threshold is reached.
altContentSvcName
If -responseWith ACS is specified, the name of the alternative content service, usually an absolute URL to the web server
that hosts the alternate content.
altContentPath
If -responseWith ( ACS | NS ) is specified, the path to the alternative content.
polqDepth
Policy queue depth threshold value for the policy queue associated with this action. When the number of connections in
the policy queue associated with this action increases to the specified number, subsequent requests are assigned to the
LOWEST policy queue. Minimum value: 1 Maximum value: 4,294,967,294
priqDepth
T hese values specify HT T P challenge-response methods for validating the authenticity of incoming requests to mitigate an
HT T P-DDoS attack.
In the HT T P challenge-response generation and validation process, AppQoE uses cookies to validate the client's response
and verify that the client seems to be genuine. When sending a challenge, a NetScaler appliance generates two cookies:
Header cookie (_DOSQ). Contains client-specific information, so that the NetScaler appliance can verify the response.
Body cookie (_DOSH). Information used to validate the client machine. T he client's browser (or the user, in the case of HIC)
computes a value for this cookie. T he NetScaler appliance compares that value with the expected value to verify the client.
T he information that the appliance sends to the client for computing the _DOSH value is based on the DoS Action
configuration.
1) SimpleResponse: In this case, a NetScaler appliance splits the value and generates a JavaScript code to combine the final
value. A client machine capable of computing the original value is considered genuine.
2) HICResponse: in this case, a NetScaler appliance generates two single-digit numbers and generates images for those
numbers. T hen, using a backpatch framework, the appliance inserts those images as base64 strings.
Limitations:
1. T his is not a trivial CAPTCHA implementation, which is why that term not used.
2. T he validation number is based on a NetScaler-generated number that does not change for 120s. T his number should be
dynamic or client specific.
sessionLif e
Number of seconds to wait after displaying alternate content before the ADC displays the same content again. Default
value: 300 Maximum Minimum value: 1 Maximum value: 4,294,967,294
avgwaitingclient
T he average number of client requests that can be in the service waiting queue. Default value: 1000000 Maximum value:
4,294,967,294
MaxAltRespBandWidth
T he maximum bandwidth to consume when sending alternate responses. If the maximum is reached, the ADC quits sending
the alternate content til bandwidth consumption drops. Default value: 100 Minimum value: 1 Maximum value: 4,294,967,294
dosAtckThrsh
T he denial-of-service attack threshold. T he number of connections that must be waiting in queues before the ADC
responds with DoS protection measures. Default value: 2000 Minimum value: 0 Maximum value: 4,294,967,294
T he following example selects requests with a User-Agent header that contains "Android", and assigns them to the medium priority
queue. T hese requests come from smartphones and tablets that run the Google Android operating system.
Done
Parameters f or configuring an AppQoE policy
name
A name for the AppQoE policy. T he name can begin with a letter, number, or the underscore symbol, and can consist of from one to
127 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at sign (@), equals (=), colon (:), and underscore (_) symbols. You
should chose a name that helps identify the type of action.
rule
A NetScaler expression that tells the appliance which connections it should handle. For complete information about policy
expressions, see the Citrix NetScaler Policy Configuration and Reference Guide at .
action
T he AppQoE action to perform when a connection matches the policy.
If you are modifying an existing policy, skip this step. You cannot change the name of an existing policy.
Use the Help and Preview Expression areas for assistance when creating the expression. For a complete description of the
available choices, see the Citrix NetScaler Policy Configuration and Reference Guide at .
3. When you have created the expression that you want, click OK. T he expression is added in the Expression text box.
6. Click Create. T he expression appears in the Rule text box.
Entity templates are available only in the configuration utility. You use the NetScaler configuration utility to create, manage,
and use any type of entity template. You can share entity templates with other administrators and manage local folders
that contain the templates. You can also import entity templates from and export entity templates to your local computer.
Before creating a template, you should be familiar with the configuration of the entity.
Note: You use entity templates to configure individual entities. T o configure multiple entities related to a particular Web
application, you must use an application template. For more information, see "AppExpert Applications and T emplates."
How Entity Templates Work
When you create a template for a NetScaler entity, you specify default values for the entity. You specify what values must
be read-only, what values must not be displayed, and what values users can configure. You also configure the pages that
compose the template import wizard. All the information and settings you provide are stored in the template file.
When a user imports the entity template to a NetScaler appliance, a wizard guides the user through the various pages that
you configured for the template. T he wizard displays the read-only parameter values and prompts the user to specify values
for the configurable parameters. After the user follows the instructions in the wizard, the appliance creates the entity with
the configured values.
For example, you can create an entity template for HT T P services that provides a text box for a service name and assigns
preset values for the service protocol, timeouts, thresholds, and monitors. Later, when you use the template to create new
HT T P services, a wizard prompts you for a service name and supplies the preset values that you would otherwise have
configured manually.
T he procedure for creating entity templates for load balancing virtual servers is different than the AppExpert procedure for
creating other entity templates. For more information, see "Creating an Entity Template."
In addition, the procedure for using the template to create the load balancing virtual server entity is different. For more
information, see "Creating an Entity from a Template."
If you create a template that is not based on an existing entity, you can specify the following options and settings for the
template:
For example, when you are creating a cache redirection virtual server template, you can specify the policies that you
want to bind to the cache redirection virtual servers that you create from the template. However, only binding
information is included in the template. T he bound entities are not included. If the entity template is imported to
another NetScaler appliance, the bound entities must exist on the appliance at import time for the binding to succeed. If
none of the bound entities exist on the target appliance, the entity (for which the template was configured) is created
without any bindings. If only a subset of the bound entities exist on the target appliance, they are bound to the entity
that is created from the template.
When you create a template based on an existing entity, the configuration settings of the entity appear in the template.
All bound entities are selected by default, but you can modify bindings as necessary. As in the case of a template that is not
based on an existing entity, only binding information is included and not the entities. You can either save the template with
the existing configuration settings or use the settings as a basis for creating a new configuration for a template.
However, when creating load balancing virtual servers, you do not have the option of specifying parameter values that you
want stored in the template. You create a load balancing virtual server template by selecting an existing load balancing
virtual server and configuring any variables that you might want to create in existing parameters and bound policies. T he
variables can be assigned values when you create a load balancing virtual server from the template. T he template stores
load balancing parameters such as the virtual server's IP address and port number, bound policies, actions, and variable
definitions. A deployment file is also created, automatically, from the load balancing configuration. T he deployment file
stores deployment-specific information, such as information about bound services, service groups, and the name-value pairs
of variables. If the bound entities that are included in the template are already configured on the NetScaler appliance to
which the template is imported, duplicates are created, with names that are generated automatically in a particular format.
T he duplicate entities are based on the parameter information stored in the entity template.
When you create a load balancing virtual server template from the AppExpert node, the template is always saved to the
/nsconfig/nstemplates/entities/lb vserver/ folder. If you want to save the template to a different folder, create the template
from the Virtual Servers pane in the Load Balancing node. T he deployment file is created with the name with which you
save the template file, but with the string _deployment appended to the name. T he deployment file is saved to the
/nsconfig/nstemplates/entities/lb vserver/deployment_files/ folder. For more information about deployment files for load
balancing virtual server templates, see "Understanding Load Balancing Entity Templates and Deployment Files."
Note: You can use either of the first two procedures for creating any template, except for a load balancing virtual server
template. For creating a load balancing virtual server template, use the third or fourth procedure.
To create an entity template by using its corresponding f eature node
1. Navigate to T raffic Management, and select the feature (for example, Content Switching), and then select the entity
(for example, Virtual Servers), for which you want to create the entity template.
2. At the top of the details pane, click Add to create a T emplate.
3. In the Create...T emplate dialog box, follow the instructions to create a template.
4. Click Finish, and then click Exit.
To create a load balancing virtual server template f rom the AppExpert node
5. Click OK.
To create a load balancing virtual server template f rom the Load Balancing Virtual Servers pane
4. Click OK.
As an example, consider the following expression configured for a policy that is bound to a load balancing virtual server for
which you are creating a template. T he expression evaluates the value of the Accept-Language header in an HT T P request.
HTTP.REQ.HEADER("Accept-Language").CONTAINS("en-us")
If you want the value of the header to be configurable at import time, you can specify the string en-us as a variable. When
importing the template, you can specify a new value for the variable on the Specify Variable Values page.
Assign additional strings to an existing variable. After you create a variable for a string, you can select and assign other
parts of the same or different expression to the variable. T he strings you assign to a variable need not be the same. At
import time, all the strings that are assigned to the variable are replaced with the value that you provide.
View the string or strings that are assigned to the variable.
View a list of all the entities and parameters that use the variable.
T he name of the variable, its value, and the description you provided appear in the Available Variables listing in the
dialog box. T he name you provide will be the name of the associated field in the template import wizard, and the
description will appear as alt text when the user positions the mouse pointer over the field.
To modify a variable, in the Available Variables list, click the variable, and then click Open. In the Create Variable dialog
T he new value that you specify will not replace the text selected in the text box that displays the configured
expression or value. However, when you import the template, the new value will be displayed as the default value for
the variable in the template import wizard.
T o view all the strings that are assigned to a given variable, in the Available Variables listing, click the name of the
variable. T he strings that are assigned to the variable are highlighted.
T o view a list of all the parameters, expressions, and actions in which the variable is used, in the Available Variables
listing, click the variable whose references you want to view, and then click Show References.
To assign a string to an existing variable, in the text box that displays the expression you configured, select the string
you want to assign to an existing variable, right-click the selection, click Use existing Variable, and then click the name
of the variable to which you want to assign the string.
If a variable has multiple strings assigned to it, when you specify a new value for the variable during import, all strings
assigned to the variable are replaced with the new value.
7. Click Close.
1. Navigate to T raffic Management, select the feature (for example, Content Switching), and then select the entity (for
example, Virtual Servers) for which you want to modify the entity template.
2. At the top of the details pane, click Entity T emplates, and then click Manage T emplate.
3. In the Manage <feature entity name> Entity T emplates dialog box, select the template that you want to modify, and
then click Modify.
4. In the Modify <template name> T emplate dialog box, follow the instructions to modify a template.
5. Click Finish, and then click Exit.
6. Click Close.
1. Navigate to T raffic Management, and select the feature (for example, Content Switching) and then select the entity
(for example, Virtual Servers), for which you want to delete the entity template.
2. At the top of the details pane, click Entity T emplates, and then click Manage T emplate.
3. In the Manage...Entity T emplates dialog box, select the template that you want to delete, and then click Delete.
T he procedure for creating a load balancing virtual server from a template is different than the AppExpert procedure for
creating other entities from templates.
After you create an instance of an entity using an entity template, you can configure it in the same way that you would
any other object of that type, such as by using the configuration utility or the command line.
1. Navigate to T raffic Management, and expand a feature node (for example, Content Switching), and then click an entity
subnode (for example, Virtual Servers).
2. At the top of the details pane, click Entity T emplates, and then click Use T emplate.
3. Click the name of the template that you want to use.
4. In the Use <template name> T emplate wizard, follow the instructions to create the entity.
Only templates that match the current context are displayed. For example, in the details pane for content switching
virtual servers, only entity templates for content switching virtual servers appear, if configured.
To create a load balancing virtual server by using a load balancing virtual server template
You can also click the folder that you want to rename, and then press F2. You cannot rename the top-level default
folder.
You can also click the folder that you want to remove, and then press the Delete key. You cannot remove the top-
level default folder.
3. Click Close.
Note: You cannot upload or download load balancing virtual server templates.
To upload an entity template to the NetScaler appliance
1. Navigate to T raffic Management, and expand a feature node (for example, Content Switching), and then click a
subnode (for example, Virtual Servers) for which you want to upload an entity template.
2. At the top of the details pane, click Entity T emplates, and then click Manage T emplate.
3. In the Manage...Entity T emplates dialog box, click the top-level folder, and then click Upload.
4. In the Upload Entity T emplate dialog box, navigate to the template file that you want to upload, and then click Select.
5. Click Close.
1. Navigate to T raffic Management, and expand a feature node (for example, Content Switching), and then click a
subnode (for example, Virtual Servers) for which you want to upload an entity template.
2. At the top of the details pane, click Entity T emplates, and then click Manage T emplate.
3. In the Manage...Entity T emplates dialog box, click the template that you want to download, and then click Download.
4. In the Download Entity T emplate dialog box, navigate to the location at which you want to save the template on your
local computer, enter a file name, and then click Save.
5. Click Close.
In the template and deployment files, each unit of configuration information is encapsulated in a specific XML element
that is meant for that unit type. For example, the load balancing method parameter, lbMethod, is encapsulated within the
<lbmethod> and </lbmethod> tags.
Note: After you export a load balancing virtual server, you can add elements, remove elements, and modify existing
elements before importing the configuration information to a NetScaler appliance.
Example of a Load Balancing Virtual Server Template
Following is an example of a template file that was created from a load balancing virtual server called "Lbvip":
Following is the deployment file associated with the virtual server in the preceding example:
An HT T P callout is an HT T P or HT T PS request that the NetScaler appliance generates and sends to an external application
when certain criteria are met during policy evaluation. T he information that is retrieved from the server can be analyzed by
default syntax policy expressions, and an appropriate action can be performed. You can configure HT T P callouts for HT T P
content switching, TCP content switching, rewrite, responder, and for the token-based method of load balancing.
Before you configure an HT T P callout, you must set up an application on the server to which the callout will be sent. T he
application, which is called the HTTP callout agent , must be configured to respond to the HT T P callout request with the
required information. T he HT T P callout agent can also be a Web server that serves the data for which the NetScaler
appliance sends the callout. You must make sure that the format of the response to an HT T P callout does not change
from one invocation to another.
After you set up the HT T P callout agent, you configure the HT T P callout on the NetScaler appliance. Finally, to invoke the
callout, you include the callout in a default syntax policy in the appropriate NetScaler feature and then bind the policy to
the bind point at which you want the policy to be evaluated.
After you have configured the HT T P callout, you must verify the configuration to make sure that the callout is working
correctly.
If the HT T P callout configuration is incorrect or incomplete, or if the callout invokes itself recursively, the appliance raises an
UNDEF condition, and updates the undefined hits counter.
T he following figure illustrates the working of an HT T P callout that is invoked from a globally bound responder policy. T he
HT T P callout is configured to include the IP address of the client that is associated with an incoming request. When the
NetScaler appliance receives a request from a client, the appliance generates the callout request and sends it to the callout
server, which hosts a database of blacklisted IP addresses and an HT T P callout agent that checks whether the client’s IP
address is listed in the database. T he HT T P callout agent receives the callout request, checks whether the client’s IP
address is listed, and sends a response that the NetScaler appliance evaluates. If the response indicates that the client’s IP
address is not blacklisted, the appliance forwards the response to the configured service. If the client’s IP address is
blacklisted, the appliance resets the client connection
An HT T P request contains a series of lines that each end with a carriage return and a line feed, represented as either <CR>
<LF> or \r\n.
T he first line of a request (the message line ) contains the HT T P method and target. For example, a message line for a GET
request contains the keyword GET and a string that represents the object that is to be fetched, as shown in the following
example:
An HT T P response contains a status message, response HT T P headers, and the requested object or, if the requested
object cannot be served, an error message.
For the destination, you either specify the IP address and port of the HT T P callout agent or engage a load balancing,
content switching, or cache redirection virtual server to manage the HT T P callout requests. In the first case, the HT T P
callout requests will be sent directly to the HT T P callout agent. In the second case, the HT T P callout requests will be sent
to the virtual IP address (VIP) of the specified virtual server. T he virtual server will then process the request in the same way
as it processes a client request. For example, if you expect a large number of callouts to be generated, you can configure
instances of the HT T P callout agent on multiple servers, bind these instances (as services) to a load balancing virtual server,
and then specify the load balancing virtual server in the HT T P callout configuration. T he load balancing virtual server then
balances the load on those configured instances as determined by the load balancing algorithm.
For the format of the HT T P callout request, you can specify the individual attributes of the HT T P callout request (an
attribute-based HT T P callout), or you can specify the entire HT T P callout request as a default syntax expression (an
expression-based HT T P callout).
Note: T he appliance does not check for the validity of the request. You must make sure that the request is a valid request.
An incorrect or incomplete HT T P callout configuration results in a runtime UNDEF condition that is not associated with an
action. T he UNDEF condition merely updates the Undefined Hits counter, which enables you to troubleshoot an incorrectly
configured HT T P callout. However, the appliance parses the HT T P callout request to enable you to configure certain
NetScaler features for the callout. T his can lead to an HT T P callout invoking itself. For information about callout recursion
and how you can avoid it, see "Avoiding HT T P Callout Recursion."
Finally, regardless of whether you use HT T P request attributes or an expression to define the format of the HT T P callout
request, you must specify the format of the response from the HT T P callout agent and the portion of the response that
you want to evaluate. T he response can be a Boolean value, a number, or text. T he portion of the response that you want
to evaluate is specified by an expression. For example, if you specify that the response contains text, you can use
HTTP.RES.BODY(<unit>) to specify that the appliance must evaluate only the first <unit> bytes of the response from the
callout agent.
At the command line, you first create an HT T P callout by using the add command. When you add a callout, all parameters
are set to a default value of NONE, except the HT T P method, which is set to a default value of GET . You then configure
the callout’s parameters by using the set command. T he set command is used to configure both types of callouts
(attribute-based and expression-based). T he difference lies in the parameters that are used for configuring the two types
of callouts. Accordingly, the command-line instructions that follow include a set command for configuring an attribute-
based callout and a set command for configuring an expression-based callout. In the configuration utility, all of these
configuration tasks are performed in a single dialog box.
Note: Before you put an HT T P callout into a policy, you can modify all configured parameters except the return type. Once
an HT T P callout is in a policy, you cannot completely modify an expression that is configured in the callout. For example,
you cannot change HTTP.REQ.HEADER("myval") to CLIENT.IP.SRC. However, you can modify the operators and
arguments that are passed to the expression. For example, you can change HTTP.REQ.HEADER("myVal1") to
HTTP.REQ.HEADER("myVal2"), or HTTP.REQ.HEADER("myVal") to
HTTP.REQ.HEADER("myVal").AFTER_STR(<string>). If the set command fails, create a new HT T P callout.
HT T P callout configuration involves configuring default syntax expressions. For more information about configuring default
syntax expressions, see Configuring Default Syntax Expressions: Getting Started.
1. Create a HT T P callout.
add policy httpCallout <name>
Example
> add policy httpCallout mycallout
2. Configure the details of the HT T P callout.
T o configure an attribute-based HT T P callout, type:
set policy httpCallout <name> [-IPAddress <ip_addr|ipv6_addr|*>] [-port <port|*>] [-vServer <string>] [-returnType
<returnType>] [-httpMethod ( GET | POST )] [-hostExpr <string>] [-urlStemExpr <string>] [-headers <name(value)> ...]
[-parameters <name(value)> ...] [-resultExpr <string>]
Example
> set policy httpCallout mycallout -vserver lbv1 -returnType num -httpMethod GET -hostExpr 'http.req.header("Host")'
-urlStemExpr "http.req.url" -parameters Name("My Name") -headers Name("MyHeader")
-resultExpr "http.res.body(10000).length"
T o configure an expression-based HT T P callout, type:
set policy httpCallout <name> [-vServer <string>] [-returnType <returnType>] [-httpMethod ( GET | POST )]
[-fullReqExpr <string>] [-resultExpr <string>]
Example
> set policy httpCallout mycallout1 -vserver lbv1 -returnType num -httpMethod GET
-fullReqExpr q{"GET " + http.req.url + "HTTP/" + http.req.version.major + "." + http.req.version.minor.sub(1)+
"r\nHost:10.101.10.10\r\nAccept: */*\r\n\r\n"}
3. Verify the configurations of the HT T P callout.
show policy httpCallout <name>
Table 1. Icons That Indicate the States of Entities Bound to an HTTP Callout
T he state of the server that hosts the HT T P callout agent, or the load balancing, content switching, or cache
redirection virtual server to which the HT T P callout is sent is UP.
T he state of the server that hosts the HT T P callout agent, or the load balancing, content switching, or cache
redirection virtual server to which the HT T P callout is sent is OUT OF SERVICE.
T he state of the server that hosts the HT T P callout agent, or the load balancing, content switching, or cache
redirection virtual server to which the HT T P callout is sent is DOWN.
For an HT T P callout to function correctly, the icon must be green at all times. If the icon is not green, check the state of
the callout server or virtual server to which the HT T P callout is sent. If the HT T P callout is not working as expected even
though the icon is green, check the parameters configured for the callout.
You can also verify the configuration by sending test requests that match the policy from which the HT T P callout is
invoked, checking the hits counter for the policy and the HT T P callout, and verifying the responses that the NetScaler
appliance sends to the client.
Note: An HT T P callout can sometimes invoke itself recursively a second time. If this happens, the hits counter is
incremented by two counts for each callout that is generated by the appliance. For the hits counter to display the correct
value, you must configure the HT T P callout in such a way that it does not invoke itself a second time. For more information
about how you can avoid HT T P callout recursion, see Avoiding HT T P Callout Recursion.
To view the hits counter f or an HTTP callout
You can use default syntax expression operators with the callout expression to process the response and then perform an
appropriate action. T he return type of the response from the HT T P callout agent determines the set of operators that
you can use on the response. If the part of the response that you want to analyze is text, you can use a text operator to
analyze the response. For example, you can use the CONTAINS(<string>) operator to check whether the specified portion
of the response contains a particular string, as in the following example:
SYS.HTTP_CALLOUT(mycallout).contains("Good IP address")
If you use the preceding expression in a responder policy, you can configure an appropriate responder action.
Similarly, if the part of the response that you want to evaluate is a number, you can use a numeric operator such as GT (int).
If the response contains a Boolean value, you can use a Boolean operator.
Note: An HT T P callout can invoke itself recursively. HT T P callout recursion can be avoided by combining the HT T P callout
expression with a default syntax expression that prevents recursion. For information about how you can avoid HT T P
callout recursion, see Avoiding HT T P Callout Recursion.
You can also cascade HT T P callouts by configuring policies that each invoke a callout after evaluating previously generated
callouts. In this scenario, after one policy invokes a callout, when the NetScaler appliance is parsing the callout before
sending the callout to the callout server, a second set of policies can evaluate the callout and invoke additional callouts,
which can in turn be evaluated by a third set of policies, and so on. Such an implementation is described in the following
example.
First, you could configure an HT T P callout called myCallout1, and then configure a responder policy, Pol1, to invoke
myCallout1. T hen, you could configure a second HT T P callout, myCallout2, and a responder policy, Pol2. You configure Pol2
to evaluate myCallout1 and invoke myCallout2. You bind both responder policies globally.
T o avoid HT T P callout recursion, myCallout1 is configured with a unique custom HT T P header called "Request1." Pol1 is
configured to avoid HT T P callout recursion by using the default syntax expression,
HTTP.REQ.HEADER(\"Request1\").EQ(\"Callout Request\").NOT.
Pol2 uses the same default syntax expression, but excludes the .NOT operator so that the policy evaluates myCallout1
when the NetScaler appliance is parsing it. Note that myCallout2 identifies its own unique header called "Request2," and
Pol2 includes a default syntax expression to prevent myCallout2 from invoking itself recursively.
Example
Done
> set policy httpCallout myCallout1 -IPAddress 10.102.3.95 -port 80 -returnType TEXT -hostExpr
"\"10.102.3.95\"" -urlStemExpr "\"/cgi-bin/check_clnt_from_database.pl\"" -headers Request1
("Callout Request") -parameters cip(CLIENT.IP.SRC) -resultExpr "HTTP.RES.BODY(100)"
Done
Done
Done
Done
> set policy httpCallout myCallout2 -IPAddress 10.102.3.96 -port 80 -returnType TEXT -hostExpr
"\"10.102.3.96\"" -urlStemExpr "\"/cgi-bin/check_clnt_location_from_database.pl\"" -headers Request2
("Callout Request") -parameters cip(CLIENT.IP.SRC) -resultExpr "HTTP.RES.BODY(200)"
Done
Done
Done
However, during this parsing, the HT T P callout request can hit the same policy and therefore invoke itself recursively. T he appliance detects the recursive invocation and raises an undefined (UNDEF)
condition. However, the recursive invocation results in the policy and HT T P callout hit counters being incremented by two counts each instead of one count each.
T o prevent a callout from invoking itself, you must identify at least one unique characteristic of the HT T P callout request, and then exclude all requests with this characteristic from being processed
by the policy rule that invokes the callout. You can do so by including another default syntax expression in the policy rule. T he expression must precede the SYS.HTTP_CALLOUT(<name>) expression
so that it is evaluated before the callout expression is evaluated. For example:
<Expression that prevents callout recursion> && SYS.HTTP_CALLOUT(<name>)
When you configure a policy rule in this way, when the appliance generates the request and parses it, the compound rule evaluates to FALSE, the callout is not generated a second time, and the hit
counters are incremented correctly.
One way by which you can assign a unique characteristic to an HT T P callout request is to include a unique custom HT T P header when you configure the callout. Following is an example of an HT T P
callout called "myCallout." T he callout generates an HT T P request that checks whether a client’s IP address is present in a database of blacklisted IP addresses. T he callout includes a custom header
called "Request," which is set to the value "Callout Request." A globally bound responder policy, "Pol1," invokes the HT T P callout but excludes all requests whose Request header is set to this value,
thus preventing a second invocation of myCallout. T he expression that prevents a second invocation is HTTP.REQ.HEADER(\"Request\").EQ(\"Callout Request\").NOT.
Example
> set policy httpCallout myCallout -IPAddress 10.102.3.95 -port 80 -returnType TEXT -hostExpr "\"10.102.3.95\"" -urlStemExpr "\"/cgi-bin/check_clnt_from_database.pl\"" -headers Request("Callout Request") -param
Done
> add responder policy Pol1 "HTTP.REQ.HEADER(\"Request\").EQ(\"Callout Request\").NOT && SYS.HTTP_CALLOUT(myCallout).CONTAINS(\"IP Matched\")" RESET
Done
Note: T o cache callout responses, make sure that the integrated caching feature is enabled.
To set the cache duration by using the command line interf ace
Example
T he NetScaler appliance checks the IP address of the client against the pre-configured blacklist and blocks the transaction if the IP address
has been blacklisted. If the IP address is not in the list, the appliance processes the transaction.
Enabling Responder
Create an HT T P callout, HT T P-Callout-1, with the parameter settings shown in the following table. For more information about creating an
HT T P callout, see Configuring an HT T P Callout.
Table 1. Parameters and Values f or HTTP-Callout-1
Parameter Value
Name HT T P-Callout-1
IP Address 10.103.9.95
Port 80
Method GET
Headers
Name Request
Parameters
Name Cip
Server Response
After you configure the HT T P callout, verify the callout configuration, and then configure a responder policy to invoke the callout. While you
can create a responder policy in the Policies sub-node and then bind it globally by using the Responder Policy Manager, this demonstration
uses the Responder Policy Manager to create the responder policy and bind the policy globally.
To create a responder policy and bind it globally by using the configuration utility
1. Navigate to AppExpert > Responder.
2. In the details pane, under Policy Manager, click Policy Manager.
3. In the Responder Policy Manager dialog box, click Override Global.
4. Click Insert Policy, and then, under Policy Name, click New Policy.
5. In the Create Responder Policy dialog box, do the following:
1. In Name, type Policy-Responder-1.
2. In Action, select RESET .
3. In Undefined-Result Action, select Global undefined-result action.
4. In Expression, type the following default syntax expression:
"HTTP.REQ.HEADER(\"Request\").EQ(\"Callout Request\").NOT && SYS.HTTP_CALLOUT(HTTP-Callout-1).CONTAINS(\"IP Matched\")"
5. Click Create, and then click Close.
6. Click Apply Changes, and then click Close.
You must now create an HT T P callout agent on the remote callout server that will receive callout requests from the NetScaler appliance and
respond appropriately. T he HT T P callout agent is a script that is different for each deployment and must be written with the server
specifications in mind, such as the type of database and the scripting language supported.
Following is a sample callout agent that verifies whether the given IP address is part of an IP blacklist. T he agent has been written in the Perl
scripting language and uses a MYSQL database.
T he following CGI script checks for a given IP address on the callout server.
#!/usr/bin/perl -w
print "Content-type: text/html\n\n";
use DBI();
use CGI qw(:standard);
#Take the Client IP address from the request query
my $ip_to_check = param('cip');
# Where a MYSQL database is running
my $dsn = 'DBI:mysql:BAD_CLIENT:localhost';
# Database username to connect with
my $db_user_name = ‘dbuser’;
# Database password to connect with
my $db_password = 'dbpassword';
my ($id, $password);
# Connecting to the database
my $dbh = DBI->connect($dsn, $db_user_name, $db_password);
my $sth = $dbh->prepare(qq{ select * from bad_clnt });
$sth->execute();
while (my ($ip_in_database) = $sth->fetchrow_array()) {
Enabling Rewrite
Rewrite must be enabled before it is used on the NetScaler appliance. T he following procedure describes the steps to
enable the rewrite feature.
To enable rewrite by using the configuration utility
1. Make sure that you have installed the rewrite license.
2. In the configuration utility, expand AppExpert, and right-click Rewrite, and then click Enable Rewrite feature.
Create an HT T P callout, HT T P-Callout-2, with the parameter settings shown in the following table. For more information
about creating an HT T P callout, see Configuring an HT T P Callout.
Table 1. Parameters and Values f or HTTP-Callout-2
Parameter Value
Name HT T P-Callout-2
IP Address 10.102.56.51
Port 80
Method GET
Headers
Name Name
Value-expression Callout
Server Response
Create a rewrite action, Action-Rewrite-1, to replace the ESI content with the callout response body. Use the parameter
settings shown in the following table.
Parameter Value
Name Action-Rewrite-1
T ype Replace
Expression to choose target text "HT T P.RES.BODY(500).AFT ER_ST R (\" <example>\").BEFORE_ST R (\"
reference </example>\")"
Create a rewrite policy, Policy-Rewrite-1, with the parameter settings shown in the following table. You can create a
rewrite policy in the Policies subnode and then bind it globally by using the Rewrite Policy Manager. Alternatively, you can
use the Rewrite Policy Manager to perform both these tasks simultaneously. T his demonstration uses the Rewrite Policy
Manager to perform both tasks.
Parameter Value
Name Policy-Rewrite-1
Action Action_Rewrite-1
To configure a rewrite policy and bind it globally by using the configuration utility
1. Navigate to AppExpert > Rewrite.
2. In the details pane, under Policy Manager, click Rewrite Policy Manager.
3. In the Rewrite Policy Manager dialog box, click Override Global.
4. Click Insert Policy, and then, in the Policy Name column, click New Policy.
5. In the Create Rewrite Policy dialog box, do the following:
1. In Name, type Policy-Rewrite-1.
2. In Action, select Action-Rewrite-1.
3. In Undefined-Result Action, select Global undefined-result action.
4. In Expression, type the following default syntax expression:
"HTTP.REQ.HEADER(\"Name\").CONTAINS(\"Callout\").NOT"
5. Click Create, and then click Close.
6. Click Apply Changes, and then click Close.
Enabling Responder
Create an HT T P callout, HT T P-Callout-3, with the parameter settings shown in the following table. For more information about creating an HT T P callout, see
Configuring an HT T P Callout.
Parameter Value
Name HT T P-Callout-3
IP Address 10.103.9.95
Port 80
Method GET
Headers
Name Request
Parameters
Name Username
Value-expression HT T P.REQ.HEADER("Username").VALUE(0)
Name Password
Value-expression HT T P.REQ.HEADER("Password").VALUE(0)
Server Response
Create a responder policy, Policy-Responder-3, that will check the response from the callout server and RESET the connection if the source IP address has
been blacklisted. Create the policy with the parameters settings shown in the following table. While you can create a responder policy in the Policies subnode
and then bind it globally by using the Responder Policy Manager, this demonstration uses the Responder Policy Manager to create the responder policy and
bind the policy globally.
Parameter Value
Name Policy-Responder-3
Action RESET
To create a responder policy and bind it globally by using the configuration utility
1. Navigate to AppExpert > Responder.
2. In the details pane, under Policy Manager, click Responder Policy Manager.
3. In the Responder Policy Manger dialog box, click Override Global.
4. Click Insert Policy, and then, in the Policy Name column, click New Policy.
5. In the Create Responder Policy dialog box, do the following:
1. In Name, type Policy-Responder-3.
2. In Action, select RESET .
3. In Undefined-Result Action , select Global undefined-result action.
4. In the Expression text box, type:
"HTTP.REQ.HEADER(\"Request\").EQ(\"Callout Request\").NOT && SYS.HTTP_CALLOUT(HTTP-Callout-3).CONTAINS(\"Authentication Failed\")"
5. Click Create, and then click Close.
6. Click Apply Changes, and then click Close.
You now need to create an HT T P callout agent on the remote callout server. T he HT T P callout agent receives callout requests from the NetScaler appliance
and responds appropriately. T he callout agent is a script that is different for each deployment and must be written with server specifications in mind, such as
the type of database and the scripting language supported.
Following is sample callout agent pseudo-code that verifies whether the supplied user name and password are valid. T he agent can be implemented in any
programming language of your choice. T he pseudo-code is to be used only as a guideline for developing the callout agent. You can build additional
functionality into the program.
You can use HT T P callouts to extract any portion of the incoming message and check with an external callout server that has been configured with rules that are
meant for determining whether a message is legitimate or spam. In case of spam email, for security reasons, the NetScaler appliance does not notify the sender
that the email is marked as spam.
T he following example conducts a very basic check for various listed keywords in the email subject. T hese checks can be more complex in a production environment.
Enabling Responder
Updated: 2013-08-30
T he responder feature must be enabled before it can be used on the NetScaler appliance.
To enable responder by using the configuration utility
1. Make sure that the responder license is installed.
2. In the configuration utility, expand AppExpert, and right-click Responder, and then click Enable Responder feature.
Create an HT T P callout, HT T P-Callout-4, with the parameter settings shown in the following table. For more information about creating an HT T P callout, see
Configuring an HT T P Callout.
Parameter Value
Name HT T P-Callout-4
IP Address 10.103.56.51
Port 80
Method POST
Headers
Name Request
Parameters
Name Subject
Create a responder action, Action-Responder-4. Create the action with the parameter settings shown in the following table.
Parameter Value
Name Action-Responder-4
T arget "\"HT T P/1.1 200 OK\r\nServer: Microsoft-IIS/6.0\r\nX-Powered-By: ASP.NET \r\nContent-Length: 0\r\nMS-WebStorage: 6.5.6944\r\nCache-
Control: no-cache\r\n\r\n\""
Create a responder policy, Policy-Responder-4, that will check the request body and, if the body contains the word “subject ,” invoke the HT T P callout to verify the
email. Create the policy with the parameter settings shown in the following table. While you can create a responder policy in the Policies subnode and then bind it
globally by using the Responder Policy Manager, this demonstration uses the Responder Policy Manager to create the responder policy and bind it globally.
Parameter Value
Name Policy-Responder-4
Action Action-Responder-4
T he following pseudo-code provides instructions for creating a callout agent that checks a list of words that are generally understood to indicate spam mails. T he
agent can be implemented in any programming language of your choice. T he pseudo-code is to be used only as a guideline for developing the callout agent. You can
build additional functionality into the program.
Depending on the type of patterns that you want to match, you can use one of the following features to implement
pattern matching:
A pattern set is an array of indexed patterns used for string matching during default syntax policy evaluation. Example of
a pattern set: imagetypes {svg, bmp, png, gif, tiff, jpg}.
A data set is a specialized form of pattern set. It is an array of patterns of types number (integer), IPv4 address, or IPv6
address.
In many cases, you can use either pattern sets or data sets. However, in cases where you want specific matches for
numerical data or IPv4 and IPv6 addresses, you must use data sets.
Note: Pattern sets and data sets can be used only in default syntax policies.
To use pattern sets or data sets, first create the pattern set or data set and bind patterns to it. T hen, when you configure
a policy for comparing a string in a packet, use an appropriate operator and pass the name of the pattern set or data set
as an argument.
Note: T his topic explains the working of a pattern set. Data sets work the same way. T he only difference between pattern sets and data
sets is the type of patterns defined in the set.
Consider the following use case to understand how patterns can be used for string matching.
You want to determine whether the URL suffix (target text) contains any of the image file extensions. Without using pattern sets, you
would have to define a complex expression, as follows:
When a compound expression includes hundreds of sub expressions, the above process is resource intensive. A better alternative is an
expression that invokes a pattern set, as shown in the following figure.
During policy evaluation as shown above, the operator (CONTAINS_ANY) compares the string identified in the request with the patterns
defined in the pattern set until a match is found. With the Sample_Patset expression, the multiple iterations through six sub expressions are
reduced to just one.
Note: Pattern sets are case sensitive (unless you specify the expression to ignore case). T herefore, the string pattern
"product1," for example, is not the same as the string pattern "Product1."
Points to remember about index values
You cannot bind the same index value to more than one pattern.
An automatically assigned index value is one number larger than the highest index value of the existing patterns within
the pattern set. For example, if the highest index value of existing patterns in a pattern set is 104, the next
automatically assigned index value will be 105.
If you do not specify an index for the first pattern, index value 1 is automatically assigned to that pattern.
Index values are not regenerated automatically if one or more patterns are deleted or modified. For example, if the set
contains five patterns, with indexes from 1 through 5, and if the pattern with an index of 3 is deleted, the other index
values in the pattern set are not automatically regenerated to produce values from 1 through 4.
T he maximum index value that can be assigned to a pattern is 4294967290. If that value is already assigned to a pattern
in the set, you must manually assign index values to any newly added patterns. An unused index value that is lower than
a currently used value cannot be assigned automatically.
Example:
> add policy patset samplepatset
2. Bind patterns to the pattern set.
bind policy patset <name> <string> [-index <positive_integer>]
Example:
> bind policy patset samplepatset product1 -index 1
Note: Repeat this step for all the patterns you want to bind to the pattern set.
3. Verify the configuration.
show policy patset <name>
Note: Data sets are case sensitive (unless you specify the expression to ignore case). T herefore, the string pattern
"product1," for example, is not the same as the string pattern "Product1."
T he rules applied for index values of data sets are the same as those applied for pattern sets. For information about index
values, see Configuring a Pattern Set.
Example:
> add policy dataset sampledataset ipv4
2. Bind patterns to the data set.
bind policy dataset <name> <value> [-index <positive_integer>]
Example:
> bind policy dataset sampledataset 10.102.29.1 -index 1
Note: Repeat this step for all the patterns you want to bind to the data set.
3. add policy expression sampleexpression client.ip.src.typecast_text_t.equals_any("sampledataset")
4. Verify the configuration.
show policy dataset <name>
Navigate to AppExpert > Data Sets, click Add and specify the relevant details.
T he usage is as follows:
<text>.<operator>("<name>")
where,
Operator Description
<text>.CONTAINS_ANY(<name>) Returns true if the target text contains one or more of the patterns
defined in the specified pattern set or data set.
<text>.SUBSTR_ANY(<name>) Returns the first string that matches any pattern defined in the specified
pattern set or data set.
<text>.BEFORE_STR_ANY(<name>) Returns the text that is present before the first occurrence of any of the
patterns defined in the specified pattern set or data set.
<text>.AFTER_STR_ANY(<name>) Returns the text that is present after the first occurrence of any of the
patterns defined in the specified pattern set or data set.
<text>.EQUALS_ANY (<name>) Returns true if the target text exactly matches any of the patterns
defined in the specified pattern set or data set.
<text>.ENDSWITH_ANY(<name>) Returns true if the target text ends with any of the patterns that are
defined in the specified pattern set or data set.
<text>.STARTSWITH_ANY(<name>) Returns true if the target text starts with any of the patterns that are
defined in the specified pattern set or data set.
<text>.STARTSWITH_INDEX(<name>) Evaluates whether the target text starts with any of the patterns that are
defined in the specified pattern set or data set. If a match is found, the
index of the matching pattern is returned. Otherwise, 0 is returned.
<text>.ENDSWITH_INDEX(<name>) Evaluates whether the target text ends with any of the patterns that are
defined in the specified pattern set or data set. If a match is found, the
index of the matching pattern is returned. Otherwise, 0 is returned.
<text>.CONTAINS_INDEX(<name>) Evaluates whether the target text contains any of the patterns that are
defined in the specified pattern set or data set. If a match is found, the
index of the matching pattern is returned. Otherwise, 0 is returned.
svg 1
bmp 2
png 3
gif 4
tiff 5
jpg 6
Example 1: Determine whether the suffix of an HT T P request is one of the file extensions defined in the "imagetypes"
pattern set.
Expression. HTTP.REQ.URL.SUFFIX.EQUALS_ANY("imagetypes")
Sample URL. http://www.example.com/homepageicon.jpg
Result. T RUE
Example 2: Determine whether the suffix of an HT T P request is one of the file extensions defined in the "imagetypes"
pattern set, and return the index of that pattern.
Expression. HTTP.REQ.URL.SUFFIX.EQUALS_INDEX("imagetypes")
Sample URL. http://www.example.com/mylogo.gif
Result. 4 (T he index value of the pattern "gif".)
Example 3: Use the index value of a pattern to determine whether the URL suffix is within a specified index-value range.
Example 4 : Implement one set of policies for file extensions bmp, jpg, and png, and a different set of policies for gif, tiff,
and svg files.
An expression that returns the index of a matched pattern can be used to define traffic subsets for a web application. T he
following two expressions could be used in content switching policies for a content switching virtual server:
HTTP.REQ.URL.SUFFIX.EQUALS_INDEX("imagetypes").LE(3)
HTTP.REQ.URL.SUFFIX.EQUALS_INDEX("imagetypes").GE(4)
Singleton variables. Can have a single value of one of the following types: ulong and text (max-size). T he ulong type is
an unsigned 64-bit integer, the text type is a sequence of bytes, and max-size is the maximum number of bytes in the
sequence.
Map variables. Maps hold values associated with keys: each key-value pair is called a map entry. T he key for each entry
is unique within the map. Maps are specified as follows:
where,
value_type is the data type of the values of the map. It can be of type ulong or text (max-size).
max-values is the maximum number of entries that the map can contain. It is of type ulong.
Values for these variables are set using assignments which must be invoked on policy actions.
A map variable or a singleton variable can have a global scope. Alternatively, the scope of a singleton variable can be limited
to a single transaction.
Global Scope Variable - A variable with global scope (the default) has only one instance, and that instance has the same
value(s) across all cores of a NetScaler appliance and across all nodes of a cluster or HA configuration. Global variable
values exist until they are explicitly deleted, until they expire, or until a standalone appliance is restarted or all nodes of a
cluster or HA configuration are restarted.
Transaction Scope Variable - A variable with transaction scope has a separate instance, with its own value, for each
transaction processed by the NetScaler appliance. When the transaction processing is complete, the transaction variable
value is deleted.
Note: T ransaction scope variables are available in NetScaler release 10.5.e or later.
Note: Once configured, a variable's settings cannot be modified or reset. If the variable needs to be changed, the variable and all references
to the variable (expressions and assignments) must be deleted. T he variable can then be re-added with new settings, and the references
(expressions and assignments) can be re-added.
To configure variables by using the command line interf ace
1. Create a variable.
add ns variable <name> -type <string> [-scope global] [-ifFull ( undef | lru )] [-ifValueTooBig ( undef | truncate )] [-ifNoValue ( undef | init )]
[-init <string>] [-expires <positive_integer>] [-comment <string>]
Note: Refer to the man page "man add ns variable" for description of the command parameters.
Example 1: Create a ulong variable named "my_counter" and initialize it to 1.
add ns variable my_counter –type ulong -init 1
Example 2: Create a map named "user_privilege_map". T he map will contain keys of maximum length 15 characters and text values of
maximum length 10 characters, with a maximum of 10000 entries.
add ns variable user_privilege_map -type map(text(15),text(10),10000)
Note: If the map contains 10000 unexpired entries, assignments for new keys reuse one of the least recently used entries. By default, an
expression trying to get a value for a non-existent key will initialize an empty text value.
2. Assign the value or specify the operation to be performed on the variable. T his is done by creating an assignment.
add ns assignment <name> -variable <expression> [-set <expression> | -add <expression> | -sub <expression> | -append <expression> |
-clear] [-comment <string>]
Note: A variable is referenced by using the variable selector ($). T herefore, $variable1 is used to refer to text or ulong variables. Similarly,
$variable2[key-expression] is used to refer to map variables.
Example 1: Define an assignment named "inc_my_counter" that automatically adds 1 to the "my_counter" variable.
add ns assignment inc_my_counter -variable $my_counter -add 1
Example 2: Define an assignment named "set_user_privilege" that adds to the "user_privilege_map" variable an entry for the client's IP
address with the value returned by the "get_user_privilege" HT T P callout.
add ns assignment set_user_privilege -variable $user_privilege_map[client.ip.src.typecast_text_t] -set sys.http.callout(get_user_privilege)
Note: If an entry for that key already exists, the value will be replaced. Otherwise a new entry for the key and value will be added. Based on
the previous declaration for user_privilege_map, if the map already has 10000 entries, one of the least recently used entries will be reused
for the new key and value.
3. Invoke the variable assignment in a policy.
T here are two functions that can operate on map variables.
$name.valueExists(key-expression). Returns true if there is a value in the map selected by the key-expression. Otherwise returns false.
T his function will update the expiration and LRU information if the map entry exists, but will not create a new map entry if the value
does not exist.
$name.valueCount . Returns the number of values currently held by the variable. T his is the number of entries in a map. For a singleton
variable, this is 0 if the variable is uninitialized or 1 otherwise.
1. Add a singleton variable of type text. T his variable can hold maximum 100 Bytes data.
2. Add an assignment action, which will be used to store the HT T P request data into the variable.
3. Add a rewrite action to insert HT T P header, whose value will be fetched from the variable.
4. Add a rewrite policy which will evaluate in the request time, and take assignment action to store data. When we hit this policy, we’ll take
assignment action and store the data into the ns variable (http_req_data)
add rewrite policy pol_set_variable true set_http_req_data
5. Add a rewrite policy which will evaluate in the response time, and add an HT T P header in the response.
1. Create an HTTP callout to fetch the user privileges from the external web service.
add policy httpcallout <name> [-IPAddress <ip_addr|ipv6_addr>] [-port <port>] [-vServer <string>] [-returnType <returnType>] [-httpMethod (GET | POST )] [-
hostExpr <string>] [-urlStemExpr <string>] [-headers <name(value)> ...] [-parameters <name(value)> ...] [-bodyExpr <string>][-fullReqExpr <string>] [-scheme (
http | https )] [-resultExpr <string>] [-cacheForSecs <secs>] [-comment <string>]
add policy httpcallout get_user_privilege -ipaddress 10.217.193.84 -port 80 -returnType text -httpMethod GET -hostExpr '"/get_user_privilege"' -resultExpr
'http.res.body(5)'
3. Create a policy to check if there is already a cached entry for the client's IP address; if not, it calls the HTTP callout to set a map entry for the client.
add cmp policy <name> -rule <expression> -resAction <string>
4. Create a policy that compresses if the cached privilege entry for the client is "GOLD".
add cmp policy <name> -rule <expression> -resAction <string>
1. Create a map variable that can store each active session. T he key of the map is the sessionid. T he expiry time for the variable is set to 600 seconds (10 minutes).
> add ns variable session_map -type map(text(10),ulong,100) -expires 600
2. Create the following assignments for the map variable:
Create an entry for the sessionid and set that value to 1 (this value is not actually used).
> add ns assignment add_session -variable '$session_map[http.req.cookie.value("sessionid")]' -set 1
Deallocate the entry for a session ID, which implicitly decrements the value count for session_map.
> add ns assignment delete_session -variable '$session_map[http.req.cookie.value("sessionid")]' -clear
3. Create responder policies for the following:
T o check if a map entry exists for that sessionid in the HT T P request. T he add_session assignment is executed if the map entry does not exist.
> add responder policy add_session_pol 'http.req.url.contains("twbkwbis.P_SabanciLogin") || $session_map.valueExists(http.req.cookie.value("netsuis"))' add_session
Note: T he valueExists() function in the add_session_pol policy counts as a reference to the session's map entry, so each request resets the expiration timeout for
its session. If no requests for a session are received after 10 minutes, the session's entry will be deallocated.
T o check when the session is logged out. T he delete_session assignment is executed.
> add responder policy delete_session_pol "http.req.url.contains(\"Logout\")" delete_session
T o check for login requests and if the number of active sessions exceed 100. If these conditions are satisfied, in order to limit the number of sessions, the user is
redirected to a page that indicates that the server is busy.
> add responder action redirect_too_busy redirect "/too_busy.html"
> add responder policy check_login_pol "http.req.url.contains(\"twbkwbis.P_SabanciLogin\") && $session_map.valueCount > 100" redirect_too_busy
4. Bind the responder policies globally.
> bind responder global add_session_pol 30 next
> bind responder global delete_session_pol 10
> bind responder global check_login_pol 20
You can also download a list of all the expressions supported on the NetScaler appliance and the hierarchical order in which
they can be invoked. T he reference is in a zip file which you can download from:
For NetScaler 10.5: http://support.citrix.com/article/CT X141344
For NetScaler 10.1: http://support.citrix.com/article/CT X137705
Introduction to Policies and Describes the purpose of expressions, policies, and actions, and how different NetScaler
Expressions applications make use of them.
Configuring Advanced Describes the structure of advanced policies and how to configure them individually and
Policies as policy banks.
Configuring Advanced Describes expression syntax and semantics, and briefly introduces how to configure
Expressions: Getting expressions and policies.
Started
Advanced Expressions: Describes expressions that you configure when you want to operate on text (for
Evaluating Text example, the body of an HT T P POST request or the contents of a user certificate).
Advanced Expressions: Describes expressions that you configure when you want to operate on any type of
Working with Dates, T imes, numeric data (for example, the length of a URL, a client's IP address, or the date and
and Numbers time that an HT T P request was sent).
Advanced Expressions: Describes expressions for parsing IP and IPv6 addresses, MAC addresses, and data that is
Parsing HT T P, TCP, and UDP specific to HT T P and TCP traffic.
Data
Advanced Expressions: Describes how to configure expressions for SSL traffic and client certificates, for
Parsing SSL Certificates example, how to retrieve the expiration date of a certificate or the certificate issuer.
Advanced Expressions: IP Describes expressions that you can use to work with any other client- or server-related
and MAC Addresses, data not discussed in other chapters.
T hroughput, VLAN IDs
Typecasting Data Describes expressions for transforming data of one type to another.
Regular Expressions Describes how to pass regular expressions as arguments to operators in advanced
Configuring Classic Policies Provides details on how to configure the simpler policies and expressions known as
and Expressions classic policies and classic expressions.
Summary Examples of Examples of classic and advanced expressions and policies, in both quick reference and
Advanced Expressions and tutorial format, that you can customize for your own use.
Policies
Tutorial Examples of Examples of advanced policies for use in the Rewrite feature.
Advanced Policies for
Rewrite
Tutorial Examples of Classic Examples of classic policies for NetScaler features such as application firewall and SSL.
Policies
Migration of Apache Examples of functions that were written using the Apache HT T P Server mod_rewrite
mod_rewrite Rules to engine, with examples of these functions after translation into Rewrite and Responder
Advanced Policies policies on the NetScaler.
Some NetScaler features use default syntax policies, which provide greater capabilities than do the older, classic, policies. If
you migrated to a newer release of the NetScaler software and have configured classic policies for features that now use
default syntax policies, you might have to manually migrate policies to the default syntax.
Warning
Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix
recommends you to use Advanced policies. For more information, see Advanced Policies topic.
Classic policies evaluate basic characteristics of traffic and other data. For example, classic policies can identify whether an
HT T P request or response contains a particular type of header or URL.
Advanced policies can perform the same type of evaluations as classic policies. In addition, default syntax policies enable
you to analyze more data (for example, the body of an HT T P request) and to configure more operations in the policy rule
(for example, transforming data in the body of a request into an HT T P header).
In addition to assigning a policy an action or profile, you bind the policy to a particular point in the processing associated
with the NetScaler features. T he bind point is one factor that determines when the policy will be evaluated.
Default syntax policies use a powerful expression language that is built on a class-object model, and they offer several
options that enhance your ability to configure the behavior of various NetScaler features. With default syntax policies, you
can do the following:
Perform fine-grained analyses of network traffic from layers 2 through 7.
Evaluate any part of the header or body of an HT T P or HT T PS request or response.
Bind policies to the multiple bind points that the default syntax policy infrastructure supports at the default, override,
and virtual server levels.
Use goto expressions to transfer control to other policies and bind points, as determined by the result of expression
evaluation.
Use special tools such as pattern sets, policy labels, rate limit identifiers, and HT T P callouts, which enable you to
configure policies effectively for complex use cases.
Additionally, the configuration utility extends robust graphical user interface support for default syntax policies and
expressions and enables users who have limited knowledge of networking protocols to configure policies quickly and easily.
T he configuration utility also includes a policy evaluation feature for default syntax policies. You can use this feature to
evaluate a default syntax policy and test its behavior before you commit it, thus reducing the risk of configuration errors.
Name.
Each policy has a unique name.
Rule.
T he rule is a logical expression that enables the NetScaler feature to evaluate a piece of traffic or another object.
For example, a rule can enable the NetScaler to determine whether an HT T P request originated from a particular IP
address, or whether a Cache-Control header in an HT T P request has the value “No-Cache.”
Advanced policies can use all of the expressions that are available in a classic policy, with the exception of classic
expressions for the SSL VPN client. In addition, Advanced policies enable you to configure more complex expressions.
Bindings.
T o ensure that the NetScaler can invoke a policy when it is needed, you associate the policy, or bind it, to one or more bind
points.
You can bind a policy globally or to a virtual server. For more information, see "About Policy Bindings."
For some features, you configure actions as part of a more complex set of instructions known as a profile.
Updated: 2013-09-30
T he NetScaler supports a variety of features that rely on policies for operation. T he following table summarizes how the
NetScaler features use policies.
T able 1. Net Scaler F eat ure, P olicy T ype, and P olicy Usage
F eat ure P olicy T ype How You Use P olicies in t he F eat ure
Name
System Classic For the Authentication function, policies contain authentication schemes for
different authentication methods.
Protection Classic To configure the behavior of the Filter, SureConnect, and Priority Queuing
Features functions.
Content Classic To determine what server or group of servers is responsible for serving
Switching and Advanced responses, based on characteristics of an incoming request.
AAA - Traffic Classic To check for client-side security before users log in and establish a session.
Management
Exceptions: Traffic policies, which determine whether single sign-on (SSO) is required, use
only the default syntax.
T raffic policies
support only Authorization policies authorize users and groups that access intranet
default syntax resources through the appliance.
policies
Authorization
policies support
both classic and
default syntax
policies.
Cache Classic To determine whether responses are served from a cache or from an origin
Redirection server.
Rewrite Advanced To identify HT T P data that you want to modify before serving. T he policies
provide rules for modifying the data.
For example, you can modify HT T P data to redirect a request to a new home
Application Classic To identify characteristics of traffic and data that should or should not be
Firewall and Advanced admitted through the firewall.
NetScaler Advanced To define rewrite rules for general Web access using the NetScaler Gateway.
Gateway,
Clientless
Access
function
Updated: 2013-09-30
Policies do not themselves take action on data. Policies provide read-only logic for evaluating traffic. To enable a feature to
perform an operation based on a policy evaluation, you configure actions or profiles and associate them with policies.
Note: Actions and profiles are specific to particular features. For information about assigning actions and profiles to
features, see the documentation for the individual features.
About Actions
Actions are steps that the NetScaler takes, depending on the evaluation of the expression in the policy. For example, if an
expression in a policy matches a particular source IP address in a request, the action that is associated with this policy
determines whether the connection is permitted.
T he types of actions that the NetScaler can take are feature specific. For example, in Rewrite, actions can replace text in a
request, change the destination URL for a request, and so on. In Integrated Caching, actions determine whether HT T P
responses are served from the cache or an origin server.
In some NetScaler features actions are predefined, and in others they are configurable. In some cases, (for example,
Rewrite), you configure the actions using the same types of expressions that you use to configure the associated policy
rule.
About Profiles
Some NetScaler features enable you to associate profiles, or both actions and profiles, with a policy. A profile is a collection
of settings that enable the feature to perform a complex function. For example, in the application firewall, a profile for
XML data can perform multiple screening operations, such as examining the data for illegal XML syntax or evidence of SQL
T able 2. Use of Act ions and P rof iles in Dif f erent Net Scaler F eat ures
Application Synonymous with a profile All application firewall features use profiles to
firewall define complex behaviors, including pattern-
based learning.
NetScaler T he following features of the NetScaler Gateway use T he following features use a profile:
Gateway actions:
Pre-Authentication
P re-Aut hent icat ion. Uses Allow and Deny Session
actions. You add these actions to a profile. T raffic
Aut horizat ion. Uses Allow and Deny actions. You Clientless Access
add these actions to a policy.
After configuring the profiles, you add them
T CP Compression. Uses various actions. You add
to policies.
these actions to a policy.
Rewrite You configure URL rewrite actions and add them to a Not used.
policy.
Integrated You configure caching and invalidation actions within a Not used.
Caching policy
AAA - Traffic You select an authentication type, set an You can configure session profiles with a
Management authorization action of ALLOW or DENY, or set default timeout and authorization action.
auditing to SYSLOG or NSLOG.
Protection You configure actions within policies for the following Not used.
Features functions:
Filter
Compression
Responder
SureConnect
SSL Offload T he action is implied. It is based on a policy that you Not used.
associate with an SSL virtual server or a service.
Updated: 2013-09-30
A policy is associated with, or bound to, an entity that enables the policy to be invoked. For example, you can bind a policy
to request-time evaluation that applies to all virtual servers. A collection of policies that are bound to a particular bind point
constitutes a policy bank.
For additional information about default syntax policy bindings, see "Binding Policies T hat Use the Default Syntax" and
Configuring a Policy Bank for a Virtual Server. For additional information about classic policy bindings, see "Configuring a
Classic Policy."
For classic policies, policy groups and policies within a group are evaluated in a particular order, depending on the following:
T he bind point for the policy, for example, whether the policy is bound to request-time processing for a virtual server or
global response-time processing. For example, at request time, the NetScaler evaluates all request-time classic policies
before evaluating any virtual server-specific policies.
T he priority level for the policy. For each point in the evaluation process, a priority level that is assigned to a policy
determines the order of evaluation relative to other policies that share the same bind point. For example, when the
NetScaler evaluates a bank of request-time, virtual server-specific policies, it starts with the policy that is assigned to the
lowest priority value. In classic policies, priority levels must be unique across all bind points.
For Advanced policies, as with classic policies, the NetScaler selects a grouping, or bank, of policies at a particular point in
overall processing. Following is the order of evaluation of the basic groupings, or banks, of Advanced policies:
However, within any of the preceding banks of policies, the order of evaluation is more flexible than in classic policies.
Within a policy bank, you can point to the next policy to be evaluated regardless of the priority level, and you can invoke
policy banks that belong to other bind points and user-defined policy banks.
As traffic flows through the NetScaler and is processed by various features, each feature performs policy evaluation.
Whenever a policy matches the traffic, the NetScaler stores the action and continues processing until the data is about to
leave the NetScaler. At that point, the NetScaler typically applies all matching actions. Integrated Caching, which only
applies a final Cache or NoCache action, is an exception.
Some policies affect the outcome of other policies. Following are examples:
If a response is served from the integrated cache, some other NetScaler features do not process the response or the
request that initiated it.
If the Content Filtering feature prevents a response from being served, no subsequent features evaluate the response.
If the application firewall rejects an incoming request, no other features can process it.
An expression matches characteristics of traffic or other data with one or more parameters and values. For example, an
expression can enable the NetScaler to accomplish the following:
Classic expressions enable you to evaluate basic characteristics of data. T hey have a structured syntax that performs string
matching and other operations.
req.ssl.client.cert exists
Updated: 2013-09-02
Any feature that uses default syntax policies also uses Advanced expressions. For information about which features
use Advanced policies, see the table NetScaler Feature, Policy Type, and Policy Usage.
Advanced policy expressions have a few other uses. In addition to configuring Advanced expressions in policy rules, you
configure Advanced
expressions in the following situations:
http.req.url.contains(".html")
T he conversion tool does not convert policies configured for the following features because the features currently support
only classic policies:
Authentication, Pre-authentication
SSL
Cache redirection
VPN (session, traffic, and tunnel traffic)
Content filtering (T he responder feature not only provides you with functionality that is equivalent to that provided by
the content filtering feature but also surpasses the content filtering feature in the use cases that it supports.
Additionally, responder supports the more powerful default syntax for policy expressions.)
T he following NetScaler features support both classic and Advanced policy expression and, therefore, support the
conversion of classic expressions to Advanced policy expressions:
Application firewall policies
Authorization policies
Named expressions
Compression policies
Content switching policies
User-defined, rule-based tokens/persistency (the – rule parameter value that is specified for a load balancing virtual
server)
Updated: 2013-09-02
When parsing a NetScaler configuration file, the conversion tool performs the following actions:
1. In commands that create classic named expressions, the conversion tool replaces the names of the classic expressions
with Advanced policy expression.
2. In commands that support only the classic policy, if classic named expressions are used, the conversion tool replaces the
names of the classic expressions with the actual classic expressions they represent. T his action ensures that the names
of expressions in classic-only features do not reference the Advanced policy expression created from Step 1.
3. In commands associated with entities that support both the classic syntax and the Advanced policies, the conversion
tool replaces all classic expressions in commands with Advanced policy expressions.
Example
T he filter policy command supports only the classic syntax. T herefore, the conversion tool replaces the classic named
expression ne_c1 with the actual classic expression it represents. Note that the tool replaces ne_c1 in the expression for
ne_c2, and then replaces ne_c2 in the filter policy with the classic expression. T his action, which corresponds to Step 2
described earlier, results in the following command:
add filter policy pol1 -rule "METHOD == GET || URL == /*.htm" -reqAction YES
T he compression feature supports both classic and Advanced policy expression. T herefore, in the command that creates
the compression policy pol2, the conversion tool replaces the expression with Advanced policy expression. T his action, which
corresponds to Step 3 described earlier, results in the following command:
T he command that creates the compression policy pol3 is unaffected by the conversion process because, after the
conversion process is complete, ne_c1 and ne_c2 reference the Advanced policy expression that results from Step 1.
Client security messages are not supported in the newer default policy format and, therefore, are lost. T he
SYS.EVAL_CLASSIC_EXPR function is replaced with a Advanced policy expression. T he following entities support the
SYS.EVAL_CLASSIC_EXPR function:
DNS policies
Rate limit selectors
Cache selectors
Cache policies
Content switching policies
Rewrite policies
URL transformation policies
Responder policies
Application firewall policies
Authorization policies
Compression policies
CVPN access policies
After performing the conversion, the tool saves the changes in a new configuration file. T he new configuration file is
created in the directory in which the input file exists. T he name of the new configuration file is the same as the name of
the input configuration file except for the string new_ used as a prefix. Conversion warnings are reported in a warning line
Updated: 2013-09-02
You can use the nspepi tool to convert a single classic expression to the Advanced policy expression. T he nspepi tool must
be run from the shell prompt on the NetScaler appliance.
To convert a classic expression to the Advanced policy by using the command line
interface
At the shell prompt, type:
Updated: 2013-09-02
You can use the nspepi tool to convert all the classic expressions in a NetScaler configuration file to the Advanced policy
(except for those commands that do not support the Advanced policy). T he nspepi tool must be run from the shell prompt
on the NetScaler appliance.
To convert all the classic expressions in a NetScaler configuration file to the default
syntax by using the command line interface
At the shell prompt, type:
When classic expressions that are included in CLI commands are upgraded to the Advanced policy, the number of
characters in the expression might exceed the 1499-character limit. T he commands that include expressions longer than
1499 characters fail when the configuration is being applied. You must manually update these commands.
In addition, multiple classic policies can be bound to a given bind point with priority 0 or with equal priority, but the Advanced
T he line numbers of lines that threw a warning during conversion are listed at the end of the output in a warning line. In
addition, a warning file is created in the same directory as the one in which the old and new configuration files reside. T he
name of the warning file is the same as the name of the input configuration file except that the string warn_ is added as a
prefix.
You may want to run a trace on the type of traffic or content that you want to configure. T his will give you an idea of the
parameters and values, and operations on these parameters and values, that you need to specify in an expression.
Note: T he NetScaler supports either classic or Advanced policy within a feature. You cannot have both types in the same
feature. Over the past few releases, some NetScaler features have migrated from using classic policies and expressions to
Advanced policy and expressions. If a feature of interest to you has changed to the Advanced policy format, you may have
to manually migrate the older information. Following are guidelines for deciding if you need to migrate your policies:
If you configured classic policies in a version of the Integrated Caching feature prior to release 9.0 and then upgrade to
version 9.0 or later, there is no impact. All legacy policies are migrated to the Advanced policy format.
For other features, you need to manually migrate classic policies and expressions to the Advanced syntax if the feature
has migrated to the Advanced policy.
When you create a policy, you assign it a name, a rule (an expression), feature-specific attributes, and an action that is
taken when data matches the policy. After creating the policy, you determine when it is invoked by binding it globally or to
either request-time or response-time processing for a virtual server.
Policies that share the same bind point are known as a policy bank. For example, all policies that are bound to a virtual
server constitute the policy bank for the virtual server. When binding the policy, you assign it a priority level to specify when
it is invoked relative to other policies in the bank. In addition to assigning a priority level, you can configure an arbitrary
evaluation order for policies in a bank by specifying Goto expressions.
In addition to policy banks that are associated with a built-in bind point or a virtual server, you can configure policy labels. A
policy label is a policy bank that is identified by an arbitrary name. You invoke a policy label, and the policies in it, from a
global or virtual-server-specific policy bank. A policy label or a virtual-server policy bank can be invoked from multiple policy
banks.
For some features, you can use the policy manager to configure and bind policies.
T he names of these identifiers must not begin with the following reserved words:
T he words ALT, TRUE, or FALSE or the Q or S one-character identifier.
Additionally, the names of these identifiers cannot be the same as the names of enumeration constants used in the policy
infrastructure. For example, the name of an identifier cannot be IGNORECASE, YEAR, or LATIN2_CZECH_CS (a MySQL
character set).
Note: T he NetScaler appliance performs a case-insensitive comparison of identifiers with these words and enumeration
constants. For example, names of the identifiers cannot begin with TRUE, True, or true.
To create a policy, begin by determining the purpose of the policy. For example, you may want to define a policy that identifies HT T P
requests for image files, or client requests that contain an SSL certificate. In addition to knowing the type of information that you want
the policy to work with, you need to know the format of the data that the policy is analyzing.
Next, determine whether the policy is globally applicable, or if it pertains to a particular virtual server. Also consider the effect that the
order in which your policies are evaluated (which will be determined by how you bind the policies) will have on the policy that you are
about to configure.
At the command prompt, type the following commands to create a policy and verify the configuration:
add responder|dns|cs|rewrite|cache policy <policyName> -rule <expression> [<feature-specific information>]
show rewrite policy <name>
Example 1:
Following is an example of creating a caching policy. Note that actions for caching policies are built in, so you do not need to configure
them separately from the policy.
T he order in which policies are evaluated determines the order in which they are applied, and features typically evaluate the
various policy banks in a particular order. Sometimes, however, other features can affect the order of evaluation. Within a
policy bank, the order of evaluation depends on the values of parameters configured in the policies. Most features apply all
of the actions associated with policies whose evaluation results in a match with the data that is being processed. T he
integrated caching feature is an exception.
You can bind policies to built-in, global bind points (or banks), to virtual servers, or to policy labels.
However, the NetScaler features differ in terms of the types of bindings that are available. T he following table summarizes
how you use policy bindings in various NetScaler features that use policies.
F eat ure Name Virt ual P olicies Bind P oint s Use of P olicies in t he F eat ure
Servers Configured in Configured
Configured t he F eat ure f or t he
in t he P olicies
F eat ure
DNS none DNS policies Global To determine how to perform DNS resolution
for requests.
Content Switching Content Content Content To determine what server or group of servers
Switching Switching switching is responsible for serving responses, based on
Note: T his feature
(CS) policies or cache characteristics of an incoming request.
can support either
redirection
or classic or Request characteristics include device type,
virtual
Advanced policies, language, cookies, HT T P method, content
server
but not both. type, and associated cache server.
Policy label
Rewrite none Rewrite policies Global To identify HT T P data that you want to
override modify before serving. T he policies provide
Global rules for modifying the data.
default
For example, you can modify HT T P data to
Policy label
redirect a request to a selected server based
Load
on the address of the incoming request, or to
balancing,
mask server information in a response for
content
security purposes.
switching,
or SSL
offload
virtual
server
NetScaler Gateway VPN server Clientless VPN To determine how the NetScaler Gateway
Access policies Global performs authentication, authorization,
(clientless VPN
VPN server auditing, and other functions, and to define
Following are the bind points that the NetScaler evaluates, listed in the typical order of evaluation within a policy bank
1. Request -t ime override. When a request flows through a feature, the NetScaler first evaluates request-time override
policies for the feature.
2. Request -t ime Load Balancing virt ual server. If policy evaluation cannot be completed after all the request-time
override policies have been evaluated, the NetScaler processes request-time policies for load balancing virtual servers.
3. Request -t ime Cont ent Swit ching virt ual server. If policy evaluation cannot be completed after all the request-time
policies for load balancing virtual servers have been evaluated, the NetScaler processes request-time policies for content
switching virtual servers.
4. Request -t ime def ault . If policy evaluation cannot be completed after all request-time, virtual server-specific policies
have been evaluated, the NetScaler processes request-time Advanced policies.
5. Response-t ime override. At response time, the NetScaler starts with policies that are bound to the response-time
override bind point.
6. Response-t ime Load Balancing virt ual server. If policy evaluation cannot be completed after all response-time
override policies have been evaluated, the NetScaler process the response-time policies for load balancing virtual servers.
7. Response-t ime Cont ent Swit ching virt ual server. If policy evaluation cannot be completed after all policies have
been evaluated for load balancing virtual servers, the NetScaler process the response-time policies for content switching
virtual servers.
8. Response-t ime def ault . If policy evaluation cannot be completed after all response-time, virtual-server-specific
policies have been evaluated, the NetScaler processes response-time Advanced policies.
In addition to attending to evaluation of policies within a feature, if you have bound policies to a content switching virtual
server, note that these policies are evaluated before other policies. Binding a policy to a content switching vserver produces
a different result in NetScaler versions 9.0.x and later than in 8.x versions. In NetScaler 9.0 and later versions, evaluation
occurs as follows:
Content switching policies are evaluated before other policies. If a content switching policy evaluates to T RUE, the
target load balancing vserver is selected.
If all content switching policies evaluate to FALSE, the default load balancing vserver under the content switching VIP is
selected.
After a target load balancing vserver is selected by the content switching process, policies are evaluated in the following
order:
To be sure that the policies are evaluated in the intended order, follow these guidelines:
Each entry in a policy bank has, at minimum, a policy and a priority level. You can also configure entries that change the
priority-based evaluation order, and you can configure entries that invoke external policy banks.
If the policy evaluates to T RUE, the NetScaler stores the action that is associated with the policy. If the policy evaluates to
FALSE, the NetScaler evaluates the next policy. If the policy is neither T RUE nor FALSE, the NetScaler uses the associated
Undef (undefined) action.
Within a policy bank, the evaluation order depends on the following items:
A priorit y.
T he most minimal amount of information about evaluation order is a numeric priority level. T he lower the number, the higher
the priority.
A Got o expression.
If supplied, the Goto expression indicates the next policy to be evaluated, typically within the same policy bank.. Goto
expressions can only proceed forward in a bank. T o prevent looping, a policy bank configuration is not valid if a Goto
statement points backwards in the bank.
Invocat ion of ot her policy banks.
Any entry can invoke an external policy bank. T he NetScaler provides a built-in entity named NOPOLICY that does not have
a rule. You can add a NOPOLICY entry in a policy bank when you want to invoke another policy bank, but do not want to
process any other rules prior to the invocation. You can have multiple NOPOLICY entries in multiple policy banks.
NEXT .
T his keyword selects the policy with the next higher priority level in the current policy bank.
An int eger.
If you supply an integer, it must match the priority level of another policy in the current policy bank.
END.
T his keyword stops evaluation after processing the current policy, and no additional policies in this bank are processed.
Blank.
If the Goto expression is empty, it is the same as specifying END.
A numeric expression.
T his is an advanced policy expression that resolves to a priority number for another policy in the current bank.
USE_INVOCAT ION_RESULT .
T his phrase can be used only if you are invoking an external policy bank. Entering this phrase causes the NetScaler to
perform one of the following actions:
If the final Goto in the invoked policy bank has a value of END or is empty, the invocation result is END, and evaluation
stops.
If the final Goto expression in the invoked policy bank is anything other than END, the NetScaler performs a NEXT .
T he following table illustrates a policy bank that uses Goto statements and policy bank invocations.
T able 3. Example of a P olicy Bank T hat Uses Got os and Ext ernal Bank Invocat ions
SubnetPolicy (rule: is the client from a private 200 NEXT None None
subnet?)
An external policy bank is invoked, its evaluation returns an END, and the Goto statement uses a value of
USE_INVOCAT ION_RESULT or END.
Evaluation continues with the next policy bank for this feature. For example, if the current bank is the request-time
override bank, the NetScaler next evaluates request-time policy banks for the virtual servers.
T he NetScaler has walked through all the policy banks in this feature, but has not encountered an END.
If this is the last entry to be evaluated in this policy bank, the NetScaler proceeds to the next feature.
After evaluating all relevant policies for a particular data point (for example, an HT T P request), the NetScaler stores all the
actions that are associated with any policy that matched the data.
For most features, all the actions from matching policies are applied to a traffic packet as it leaves the NetScaler. T he
Integrated Caching feature only applies one action: CACHE or NOCACHE. T his action is associated with the policy with the
lowest priority value in the “highest priority” policy bank (for example, request-time override policies are applied before
virtual server-specific policies).
At the command prompt, type the following commands to bind an Integrated Caching policy and verify the configuration:
bind cache global <policy> -priority <positiveInteger> [-type REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE |
RES_DEFAULT ]
show cache global
Example
At the command prompt, type the following commands to bind a Rewrite policy and verify the configuration:
bind rewrite global <policyName> <priority> [-type REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT ]
show rewrite global
Example
Done
T he type argument is optional for globally bound policies, to maintain backward compatibility. If you omit the type, the
policy is bound to REQ_DEFAULT or RES_DEFAULT , depending on whether the policy rule is a response-time or a
request-time expression.
At the command prompt, type the following commands to bind a Responder policy and verify the configuration:
bind responder global <policyName> <priority> [-type OVERRIDE | DEFAULT ]
show responder global
Example
Done
At the command prompt, type the following commands to bind a DNS policy and verify the configuration:
bind dns global <policyName> <priority>
show dns global
Example
1. In the navigation pane, click the name of the feature for which you want to bind the policy.
2. In the details pane, click <Feature Name> policy manager.
3. In the Policy Manager dialog box, select the bind point to which you want to bind the policy (for example, for Integrated
Caching, Rewrite, or Compression, you could select Request and Default Global). T he Responder does not differentiate
between request-time and response-time policies.
4. Click Insert Policy and, from the Policy Name pop-up menu, select the policy name. A priority is assigned automatically to
the policy, but you can click the cell in the Priority column and drag it anywhere within the dialog box if you want the
policy to be evaluated after other policies in this bank. T he priority is automatically reset. Note that priority values within
a policy bank must be unique.
5. Click Apply Changes.
6. Click Close. A message in the status bar indicates that the policy is bound successfully.
Note that when binding a policy to a virtual server, you must identify it as a request-time or a response-time policy.
At the command prompt, type the following commands to bind a policy to a load balancing or content switching virtual
server and verify the configuration:
bind lb|cs vserver <virtualServerName> -policyName <policyName> -priority <positiveInteger> -type
REQUEST |RESPONSE
show lb vserver <name>
Example
At the command prompt, type the following commands to bind a policy to an SSL offload virtual server and verify the
configuration:
bind ssl vserver <vServerName>@ -policyName <policyName> -priority <positiveInteger>
At the command prompt, type the following commands to display policy bindings and verify the configuration:
show rewrite policy <name>
Example
1. In the navigation pane, expand the feature that contains the policy that you want to view, and then click Policies.
2. In the details pane, click the policy. Bound policies have a check mark next to them.
3. At the bottom of the page, under Details, next to Bound to, view the entity to which the policy is bound.
At the command prompt, type the following commands to unbind an integrated caching, rewrite, or compression Advanced
policy globally and verify the configuration:
unbind cache|rewrite|cmp global <policyName> [-type req_override|req_default|res_override|res_default] [-priority
<positiveInteger>]
show cache|rewrite|cmp global
Example
Done
T he priority is required only for the “dummy” policy named NOPOLICY.
At the command prompt, type the following commands to unbind a responder policy globally and verify the configuration:
unbind responder global <policyName> [-type override|default] [-priority <positiveInteger>]
show responder global
Example
At the command prompt, type the following commands to unbind a DNS policy globally and verify the configuration:
unbind responder global <policyName>
unbind responder global
Example
At the command prompt, type the following commands to unbind an Advanced policy from a virtual server and verify the
configuration:
unbind cs vserver <name> -policyName <policyName> [-priority <positiveInteger>] [-type REQUEST |RESPONSE]
show lb vserver <name>
Example
1. In the navigation pane, click the feature with the policy that you want to unbind (for example, Integrated Caching).
2. In the details pane, click <Feature Name> policy manager.
3. In the P olicy Manager dialog box, select the bind point with the policy that you want to unbind, for example,
Advanced Global.
4. Click the policy name that you want to unbind, and then click Unbind Policy.
5. Click Apply Changes .
6. Click Close . A message in the status bar indicates that the policy is unbound successfully.
1. Navigate to T raf f ic Management , and expand Load Balancing or Content Switching, and then click Virt ual Servers .
2. In the details pane, double-click the virtual server from which you want to unbind the policy.
3. On the P olicies tab, in the Act ive column, clear the check box next to the policy that you want to unbind.
4. Click OK . A message in the status bar indicates that the policy is unbinded successfully.
Within a policy label, you bind policies and specify the order of evaluation of each policy relative to others in the bank of
policies for the policy label. T he NetScaler also permits you to define an arbitrary evaluation order as follows:
You can use “goto” expressions to point to the next entry in the bank to be evaluated after the current one.
You can use an entry in a policy bank to invoke another bank.
Each feature determines the type of policy that you can bind to a policy label, the type of load balancing virtual server that
you can bind the label to, and the type of content switching virtual server from which the label can be invoked. For example,
a TCP policy label can only be bound to a TCP load balancing virtual server. You cannot bind HT T P policies to a policy label
of this type. And you can invoke a TCP policy label only from a TCP content switching virtual server.
After configuring a new policy label, you can invoke it from one or more banks for the built-in bind points.
To create a Content Switching policy label by using the command line interface
At the command prompt, type the following commands to create a Content Switching policy label and verify the
configuration:
add cs policylabel <labelName> http|tcp|rtsp|ssl
show cs policylabel <labelName>
As with policy banks that are bound to the built-in bind points, each entry in a policy label is a policy that is bound to the
policy label. As with policies that are bound globally or to a vserver, each policy that is bound to the policy label can also
invoke a policy bank or a policy label that is evaluated after the current entry has been processed. T he following table
summarizes the entries in a policy label.
Name
T he name of a policy, or, to invoke another policy bank without evaluating a policy, the “dummy” policy name NOPOLICY.
You can specify NOPOLICY more than once in a policy bank, but you can specify a named policy only once.
P riorit y
An integer. T his setting can work with the Goto expression.
Got o Expression
Determines the next policy to evaluate in this bank. You can provide one of the following values:
NEXT
Go to the policy with the next higher priority.
END
Stop evaluation.
USE_INVOCAT ION_RESULT
Applicable if this entry invokes another policy bank. If the final Goto in the invoked bank has a value of END, evaluation
stops. If the final Goto is anything other than END, the current policy bank performs a NEXT .
P osit ive number
T he priority number of the next policy to be evaluated.
Numeric expression
An expression that produces the priority number of the next policy to be evaluated.
A policy label consists of a set of policies and invocations of other policy labels and virtual server-specific policy banks. An Invoke parameter enables you to
invoke a policy label or a virtual server-specific policy bank from any other policy bank. A special-purpose NoPolicy entry enables you to invoke an external bank
without processing an expression (a rule). T he NoPolicy entry is a “dummy” policy that does not contain a rule.
For configuring policy labels from the NetScaler command line, note the following elaborations of the command syntax:
gotoPriorityExpression is configured as described in T able 2. Format of Each Entry in a Policy Bank of the section "Entries in a Policy Bank" in Binding Policies
Using Advanced Policy.
T he type argument is required. T his is unlike binding a conventional policy, where this argument is optional.
You can invoke the bank of policies that are bound to a virtual server by using the same method as you use for invoking a policy label.
To invoke a policy label from a Rewrite policy bank with a NOPOLICY entry by using the command line
interface
At the command prompt, type the following commands to invoke a policy label from a Rewrite policy bank with a NOPOLICY entry and verify the
configuration:
bind rewrite global <policyName> <priority> <gotoPriorityExpression> -type REQ_OVERRIDE|REQ_DEFAULT |RES_OVERRIDE|RES_DEFAULT -invoke
reqvserver|resvserver|policylabel <policyLabelName>|<vserverName>
show rewrite global
Example
> bind rewrite global NOPOLICY 100 -type REQ_DEFAULT -invoke policylabel lbl-rewrt-pol
To invoke a policy label from an Integrated Caching policy bank by using the command line interface
At the command prompt, type the following commands to invoke a policy label from an Integrated Caching policy bank and verify the configuration:
bind cache global NOPOLICY -priority <priority> -gotoPriorityExpression <gotopriorityExpression> -type
REQ_OVERRIDE|REQ_DEFAULT |RES_OVERRIDE|RES_DEFAULT -invoke reqvserver|resvserver|policylabel <policyLabelName>|<vserverName>
show cache global
Example
bind cache global NOPOLICY -priority 100 -gotoPriorityExpression END -type REQ_DEFAULT -invoke policylabel lbl-cache-pol
Done
> show cache global
1) Global bindpoint: REQ_DEFAULT
Number of bound policies: 2
Done
To invoke a policy label from a Responder policy bank by using the command line interface
At the command prompt, type the following commands to invoke a policy label from a Responder policy bank and verify the configuration:
bind responder global NOPOLICY <priority> <gotopriorityExpression> -type OVERRIDE|DEFAULT -invoke vserver|policylabel <policyLabelName>|
<vserverName>
show responder global
Example
> bind responder global NOPOLICY 100 NEXT -type DEFAULT -invoke policylabel lbl-respndr-pol
Done
> show responder global
1) Global bindpoint: REQ_DEFAULT
Number of bound policies: 2
Done
5. Click OK . A message in the status bar indicates that the policy label is configured successfully.
Updated: 2013-09-02
You can configure a bank of policies for a virtual server. T he policy bank can contain individual policies, and each entry in the policy bank can optionally invoke a
policy label or a bank of policies that you configured for another virtual server. If you invoke a policy label or policy bank, you can do so without triggering an
expression (a rule) by selecting a NOPOLICY “dummy” entry instead of a policy name.
To add policies to a virtual server policy bank by using the command line interface
At the command prompt, type the following commands to add policies to a virtual server policy bank and verify the configuration:
bind lb|cs vserver <virtualServerName> <serviceT ype> [-policyName <policyName>] [-priority <positiveInteger>] [-gotoPriorityExpression <expression>] [-type
REQUEST |RESPONSE]
show lb|cs vserver <virtualServerName>
Example
To invoke a policy label from a virtual server policy bank with a NOPOLICY entry by using the command
line interface
At the command prompt, type the following commands to invoke a policy label from a virtual server policy bank with a NOPOLICY entry and verify the
configuration:
bind lb|cs vserver <virtualServerName> -policyName NOPOLICY_REWRIT E|NOPOLICY_CACHE|NOPOLICY_RESPONDER -priority <integer> -type
REQUEST |RESPONSE -gotoPriorityExpression <gotopriorityExpression> -invoke reqVserver|resVserver|policyLabel <vserverName>|<labelName>
show lb vserver
Example
> bind lb vserver vs-cont-sw -policyname NOPOLICY-REWRITE -priority 200 -type REQUEST -gotoPriorityExpression NEXT -invoke policyLabel lbl-rewrt-pol
Done
6. Click OK . A message in the status bar indicates that the policy is configured successfully.
T ypically, the policy label must be of the same type as the policy from which it is invoked. For example, you would invoke a
responder policy label from a responder policy.
Note: When binding or unbinding a global NOPOLICY entry in a policy bank at the command line, you specify a priority to
distinguish one NOPOLICY entry from another.
At the command prompt, type the one of the following commands to invoke a rewrite or integrated caching policy label
and verify the configuration:
bind cache global <policy> -priority <positive_integer> [-got oP riorit yExpression <expression>] -t ype
REQ_OVERRIDE |REQ_DEF AULT |RES_OVERRIDE |RES_DEF AULT ] -invoke reqvserver|resvserver|policylabel
<label_name>
bind rewrite global<policy> -priority <positive_integer> [-got oP riorit yExpression <expression>] -t ype
REQ_OVERRIDE |REQ_DEF AULT |RES_OVERRIDE |RES_DEF AULT ] -invoke reqvserver|resvserver|policylabel
<label_name>
show cache global|show rewrite global
Example
> bind cache global _nonPostReq2 -priority 100 -type req_override -invoke
policylabel lbl-cache-pol
Done
> show cache global
1) Global bindpoint: REQ_DEFAULT
Number of bound policies: 2
Done
At the command prompt, type the following commands to invoke a responder policy label and verify the configuration:
bind responder global <policy_Name> <priority_as_positive_integer> [<gotoPriorityExpression>] -type
REQ_OVERRIDE|REQ_DEFAULT|OVERRIDE|DEFAULT -invoke vserver|policylabel <label_name>
show responder global
Done
>
At the command prompt, type the following commands to invoke a Virtual Server Policy Bank and verify the configuration:
bind lb vserver <vserver_name> -policyName <policy_Name> -priority <positive_integer> [-gotoPriorityExpression
<expression>] -type REQUEST|RESPONSE -invoke reqvserver|resvserver|policylabel <policy_Label_Name>
bind lb vserver <vserver_name>
Example
Done
At the command prompt, type the following commands to remove a responder policy label and verify the configuration:
unbind responder global <policyName> -priority <positiveInteger> -t ype OVERRIDE |DEF AULT
show responder global
Example
Done
At the command prompt, type one of the following commands to remove a Virtual Server policy label and verify the
configuration:
unbind lb vserver <virtualServerName> -policyName NOPOLICY-REWRITE|NOPOLICY-RESPONDER|NOPOLICY-
CACHE -type REQUEST|RESPONSE -priority <positiveInteger>
unbind cs vserver <virtualServerName> -policyName NOPOLICY-REWRITE|NOPOLICY-RESPONDER|NOPOLICY-
CACHE -type REQUEST|RESPONSE -priority <positiveInteger>
show lb vserver|show cs vserver
Example
1. Bind a policy, as described in "Binding a Policy Globally", "Binding a Policy to a Virtual Server", or "Binding a Policy to a
Policy Label." Alternatively, you can enter a NOPOLICY “dummy” entry instead of a policy name. You do this if you do not
want to evaluate a policy before evaluating the policy bank.
2. In the Invoke field, select the name of the policy label or virtual server policy bank that you want to evaluate if traffic
matches the bound policy. A message in the status bar indicates that the policy label or virtual server policy bank is
invoked successfully.
1. Open the policy and clear the Invoke field. Unbinding the policy also removes the invocation of the label. A message in
the status bar indicates that the policy label is removed successfully.
Warning
Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix
recommends you to use Advanced policies. For more information, see Advanced Policies topic.
Some applications provide a specialized Policy Manager in the NetScaler configuration utility to simplify configuring policy
banks. It also lets you find and delete policies and actions that are not being used.
T he Policy Manager is currently available for the Rewrite, Integrated Caching, Responder, and Compression features.
Note: Note that when you delete the policy, the NetScaler searches the Goto Expression values of other policies in the
bank. If any of these Goto Expression values match the priority level of the deleted policy, they are removed.
To configure policy bindings by using the Policy Manager
1. In the navigation pane, click the feature for which you want to configure policies. T he choices are Responder, Integrated
Caching, Rewrite or Compression.
2. In the details pane, click Policy Manager.
3. If you are configuring classic policy bindings for compression, in the Compression Policy Manager dialog box, click Switch
to Classic Syntax. T he dialog box switches to the classic syntax view and displays the Switch to Advanced
Policy button. At any time before you complete configuring policy bindings, if you want to configure bindings for policies
that use the Advanced Policy click the Switch to Advanced Policy button.
4. For features other than Responder, to specify the bind point, click Request or Response, and then click one of the
request-time or response-time bind points. T he options are Override Global, LB Virtual Server, CS Virtual Server, Default
Global, or Policy Label. If you are configuring the Responder, the Request and Response flow types are not available.
5. T o bind a policy to this bind point, click Insert Policy, and select a previously configured policy, a NOPOLICY label, or the
New policy option. Depending on the option that you select, you have the following choices:
New policy: Create the policy as described in "Creating or Modifying a Policy," and then configure the priority level,
GoT o expression, and policy invocation as described in the table, "Format of Each Entry in a Policy Bank."
Existing policy, NOPOLICY, or NOPOLICY<f eature name>: Configure the priority level, GoT o expression, and policy
invocation as described in the table, "Format of Each Entry in a Policy Bank." T he NOPOLICY or NOPOLICY<f eature
name> options are available only for policies that use Advanced Policies.
8. T o change the policy, action, or policy bank invocation for an row in the table, click the down arrow to the right of the
entry and do one of the following:
T o change the policy, select another policy name or select New Policy and follow the steps in "Creating or Modifying
a Policy."
T o change the Goto Expression, select Next, End, USE_INVOCAT ION_RESULT , or select more and enter an expression
whose result returns the priority level of another entry in this policy bank.
T o modify an invocation, select an existing policy bank, or click New Policy Label and follow the steps in "Binding a
Policy to a Policy Label."
9. T o unbind a policy or a policy label invocation from this bank, click any field in the row that contains the policy or policy
label, and then click Unbind Policy.
10. When you are done, click Apply Changes. A message in the status bar indicates that the policy is bound successfully.
1. In the navigation pane, click the feature for which you want to configure the policy bank. T he choices are Responder,
Integrated Caching, or Rewrite.
2. In the details pane, click <Feature Name> policy manager.
3. In the <Feature Name> Policy Manager dialog box, click Cleanup Conf iguration.
4. In the Cleanup Conf iguration dialog box, select the items that you want to delete, and then click Remove.
5. In the Remove dialog box, click Yes.
6. Click Close. A message in the status bar indicates that the policy is removed successfully.
To create an Advanced policy expression, you select a prefix that identifies a piece of data that you want to analyze, and
then you specify an operation to perform on the data. For example, an operation can match a piece of data with a text
string that you specify, or it can transform a text string into an HT T P header. Other operations match a returned string
with a set of strings or a string pattern. You configure compound expressions by specifying Boolean and arithmetic
operators, and by using parentheses to control the order of evaluation.
Advanced policy expression can also contain classic expressions. You can assign a name to a frequently used expression to
avoid having to build the expression repeatedly.
Policies and a few other entities include rules that the NetScaler uses to evaluate a packet in the traffic flowing through it,
to extract data from the NetScaler system itself, to send a request (a “callout”) to an external application, or to analyze
another piece of data. A rule takes the form of a logical expression that is compared against traffic and ultimately returns
values of T RUE or FALSE.
T he elements of the rule can themselves return T RUE or FALSE, string, or numeric values.
Before configuring an Advanced policy expression, you need to understand the characteristics of the data that the policy
or other entity is to evaluate. For example, when working with the Integrated Caching feature, a policy determines what
data can be stored in the cache. With Integrated Caching, you need to know the URLs, headers, and other data in the
HT T P requests and responses that the NetScaler receives. With this knowledge, you can configure policies that match the
actual data and enable the NetScaler to manage caching for HT T P traffic. T his information helps you determine the type
of expression that you need to configure in the policy.
where
<pref ix>
is an anchor point for starting an expression.
T he prefix is a period-delimited key that identifies a unit of data. For example, the following prefix examines HT T P requests
for the presence of a header named Content-Type:
http.req.header("Content-Type")
Prefixes can also be used on their own to return the value of the object that the prefix identifies.
<operation>
identifies an evaluation that is to be performed on the data identified by the prefix.
For example, consider the following expression:
http.req.header("Content-Type").eq("text/html")
eq("text/html")
T his operator causes the NetScaler to evaluate any HT T P requests that contain a Content-Type header, and in particular,
to determine if the value of this header is equal to the string “text/html.” For more information, see "Operations."
<compound-operator>
is a Boolean or arithmetic operator that forms a compound expression from multiple prefix or prefix.operation elements.
For example, consider the following expression:
Prefixes
Updated: 2013-09-30
An expression prefix represents a discrete piece of data. For example, an expression prefix can represent an HT T P URL, an
HT T P Cookie header, or a string in the body of an HT T P POST request. An expression prefix can identify and return a wide
In most cases, an expression prefix begins with one of the following keywords:
CLIENT:
Identifies a characteristic of the client that is either sending a request or receiving a response, as in the following examples:
T he prefix client.ip.dst designates the destination IP address in the request or response.
T he prefix client.ip.src designates the source IP address.
HTTP:
Identifies an element in an HT T P request or a response, as in the following examples:
T he prefix http.req.body(integer) designates the body of the HT T P request as a multiline text object, up to the character
position designated in integer.
T he prefix http.req.header("header_name") designates an HT T P header, as specified in header_name.
T he prefix http.req.url designates an HT T P URL in URL-encoded format.
SERVER:
Identifies an element in the server that is either processing a request or sending a response.
SYS:
Identifies a characteristic of the NetScaler that is processing the traffic.
Note: Note that DNS policies support only SYS, CLIENT , and SERVER objects.
In addition, in the NetScaler Gateway, the Clientless VPN function can use the following types of prefixes:
TEXT:
Identifies any text element in a request or a response.
TARGET:
Identifies the target of a connection.
URL:
Identifies an element in the URL portion of an HT T P request or response.
As a general rule of thumb, any expression prefix can be a self-contained expression. For example, the following prefix is a
complete expression that returns the contents of the HT T P header specified in the string argument (enclosed in quotation
marks):
http.res.header.("myheader")
Or you can combine prefixes with simple operations to determine T RUE and FALSE values. For example, the following
returns a value of T RUE or FALSE:
http.res.header.("myheader").exists
You can also use complex operations on individual prefixes and multiple prefixes within an expression, as in the following
example:
NetScaler Gateway, Clientless Access HTTP, SYS, CLIENT, SERVER, URL, TEXT, TARGET, VPN
Note: For details on the permitted expression prefixes in a feature, see the documentation for that feature.
Single-Element Expressions
T he simplest type of Advanced policy expression contains a single element. T his element can be one of the following:
true. An Advanced policy expression can consist simply of the value true. T his type of expression always returns a value of
T RUE. It is useful for chaining policy actions and triggering Goto expressions.
false. An Advanced policy expression can consist simply of the value false. T his type of expression always returns a value
of FALSE.
A prefix for a compound expression. For example, the prefix HTTP.REQ.HOSTNAME is a complete expression that
returns a host name and HTTP.REQ.URL is a complete expression that returns a URL. T he prefix could also be used in
conjunction with operations and additional prefixes to form a compound expression.
Operations
In most expressions, you also specify an operation on the data that the prefix identifies. For example, suppose that you
specify the following prefix:
http.req.url
T his prefix extracts URLs in HT T P requests. T his expression prefix does not require any operators to be used in an
expression. However, when you configure an expression that processes HT T P request URLs, you can specify operations
that analyze particular characteristics of the URL. Following are a few possibilities:
Search for a particular host name in the URL.
Search for a particular path in the URL.
Evaluate the length of the URL.
Search for a string in the URL that indicates a time stamp and convert it to GMT .
http.res.header("Server").contains("IIS")
Following is an example of a prefix that identifies host names and an operation that searches for the string
“www.mycompany.com” as the value of the name:
http.req.hostname.eq("www.mycompany.com")
T he following table describes a few of the basic operations that can be performed on expression prefixes.
http.req.header("Cache-Control").contains("no-cache")
http.res.header("MyHdr").exists
http.req.method.eq(post)
client.ip.dst.eq(10.100.10.100)
http.req.content_length.lt(5000)
http.req.content_length.gt(5)
Operation Description
Type
Text Match individual strings and sets of strings with any portion of a target. T he target can be an entire
operations string, the start of a string, or any portion of text in between the start and the end of the string.
For example, you can extract the string "XYZ" from "XYZSomeText". Or, you can compare an HT T P header
value with an array of different strings.
You can also transform text into another type of data. Following are examples:
Numeric Numeric operations include applying arithmetic operators, evaluating content length, the number of items
operations in a list, dates, times, and IP addresses.
T he following expression adds the value of two targets, and compares the result to a third value:
A compound expression can contain any number of logical and arithmetic operators. T he following expression evaluates
the length of an HT T P request on the basis of its URL and cookie, evaluates text in the header, and performs a Boolean
AND on these two results:
You can use parentheses to control the order of evaluation in a compound expression.
||.
T his operator is a logical OR. If any component of the expression that is joined by the OR evaluates to T RUE, the entire
expression is T RUE.
!.
Performs a logical NOT on the expression.
In some cases, the NetScaler configuration utility offers AND, NOT, and OR operators in the Add Expression dialog box.
However, these are of limited use. Citrix recommends that you use the operators &&, ||, and ! to configure compound
expressions that use Boolean logic.
You can use parentheses to control the order of evaluation of an expression. T he following is an example:
T he following table describes operators that you can use to configure compound operations on string data.
Table 1. String-Based Operations f or Compound Def ault Syntax Expressions
str + Concatenates the value of the expression on the left of the operator with the value on the right. Following is
str an example:
http.req.hostname + http.req.url.protocol
str + Concatenates the value of the expression on the left of the operator with a numeric value on the right.
num Following is an example:
http.req.hostname + http.req.url.content_length
num Concatenates the numeric value of the expression on the left side of the operator with a string value on the
+ str right. Following is an example:
http.req.url.content_length + http.req.url.hostname
str + Concatenates the string value of the expression on the left side of the operator with an IP address value on
ip the right. Following is an example:
http.req.hostname + 10.00.000.00
ip + Concatenates the IP address value of the expression on the left of the operator with a string value on the
str right.Following is an example:
client.ip.dst + http.req.url.hostname
str1 Uses the string1 or string2 value that is derived from the expression on either side of the operator, as long as
ALT neither of these expressions is a compound expressions. Following is an example:
str2
http.req.hostname alt client.ip.src
str Evaluates whether the string on the left side of the operator is the same as the string on the right, or precedes
<= it alphabetically.
str
str Evaluates whether the string on the left side of the operator is the same as the string on the right, or follows it
>= alphabetically.
str
str < Evaluates whether the string on the left side of the operator precedes the string on the right alphabetically.
str
str > Evaluates whether the string on the left side of the operator follows the string on the right alphabetically.
str
str Evaluates whether the strings on either side of the operator are different.
!!=
str
bool T his operator is a logical AND. When evaluating the components of the compound expression, all components
&& that are joined by the AND must evaluate to T RUE. Following is an example:
bool
http.req.method.eq(GET) && http.req.url.query.contains("viewReport && my_pagelabel")
bool T his operator is a logical OR. When evaluating the components of the compound expression, if any component
|| of the expression that is joined by the OR evaluates to T RUE, the entire expression is T RUE. Following is an
bool example:
http.req.url.contains(".js") || http.res.header.("Content-Type").contains("javascript")
Updated: 2013-09-02
You can configure compound numeric expressions. For example, the following expression returns a numeric value that is the
sum of an HT T P header length and a URL length:
T he following tables describes operators that you can use to configure compound expressions for numeric data.
Operator Description
num + Add the value of the expression on the left of the operator to the value of the expression on the right.
num Following is an example:
http.req.content_length + http.req.url.length
num – Subtract the value of the expression on the right of the operator from the value of the expression on the
num left.
num * Multiply the value of the expression on the left of the operator with the value of the expression on the
num right. Following is an example:
client.interface.rxthroughput * 9
num / Divide the value of the expression on the left of the operator by the value of the expression on the right.
num
num % Calculate the modulo, or the numeric remainder on a division of the value of the expression on the left of
num the operator by the value of the expression on the right.
For example, the values "15 mod 4" equals 3, and "12 mod 4" equals 0.
~number Returns a number after applying a bitwise logical negation of the number. T he following example assumes
that numeric.expression returns 12 (binary 1100):
~numeric.expression.
T he result of applying the ~ operator is -11 (a binary 1110011, 32 bits total with all ones to the left).
Note that all returned values of less than 32 bits before applying the operator implicitly have zeros to the
left to make them 32 bits wide.
number ^ Compares two bit patterns of equal length and performs an XOR operation on each pair of corresponding
number bits in each number argument, returning 1 if the bits are different, and 0 if they are the same.
Returns a number after applying a bitwise XOR to the integer argument and the current number value. If
the values in the bitwise comparison are the same, the returned value is a 0. T he following example
assumes that numeric.expression1 returns 12 (binary 1100) and numeric.expression2 returns 10 (binary 1010):
numeric.expression1 ^ numeric.expression2
number | Returns a number after applying a bitwise OR to the number values. If either value in the bitwise
number comparison is a 1, the returned value is a 1. T he following example assumes that numeric.expression1
returns 12 (binary 1100) and numeric.expression2 returns 10 (binary 1010):
numeric.expression1 | numeric.expression2
Note that all returned values of less than 32 bits before applying the operator implicitly have zeros to the
left to make them 32 bits wide.
number & Compares two bit patterns of equal length and performs a bitwise AND operation on each pair of
number corresponding bits, returning 1 if both of the bits contains a value of 1, and 0 if either bits are 0.
T he following example assumes that numeric.expression1 returns 12 (binary 1100) and numeric.expression2
returns 10 (binary 1010):
Note that all returned values of less than 32 bits before applying the operator implicitly have zeros to the
left to make them 32 bits wide.
num << Returns a number after a bitwise left shift of the number value by the right-side number argument number
num of bits.
Note that the number of bits shifted is integer modulo 32. T he following example assumes that
numeric.expression1 returns 12 (binary 1100) and numeric.expression2 returns 3:
Note that all returned values of less than 32 bits before applying the operator implicitly have zeros to the
left to make them 32 bits wide.
num >> Returns a number after a bitwise right shift of the number value by the integer argument number of bits.
num
Note that the number of bits shifted is integer modulo 32. T he following example assumes that
numeric.expression1 returns 12 (binary 1100) and numeric.expression2 returns 3:
Operator Description
num == Determine if the value of the expression on the left of the operator is equal to the value of the expression
num on the right.
num != Determine if the value of the expression on the left of the operator is not equal to the value of the
num expression on the right.
num > Determine if the value of the expression on the left of the operator is greater than the value of the
num expression on the right.
num < Determine if the value of the expression on the left of the operator is less than the value of the
num expression on the right.
num >= Determine if the value of the expression on the left of the operator is greater than or equal to the value
num of the expression on the right.
num <= Determine if the value of the expression on the left of the operator is less than or equal to the value of
num the expression on the right
Simple expressions can return all of these data types. T herefore, you can create compound expressions that use arithmetic
operators and logical operators to evaluate or return values of these data types. Additionally, you can use all of these
values in policy expressions. Literal constants of type unsigned long can be specified by appending the string ul to the
number. Literal constants of type double contain a period (.), an exponent, or both.
In compound expressions, the following standard arithmetic and logical operators can be used for the double and unsigned
long data types:
All of these operators have the same meaning as in the C programming language.
In all cases of mixed operations between operands of type integer, unsigned long, and double, type promotion is performed
so that the operation can be performed on operands of the same type. A type of lower precedence is automatically
promoted to the type of the operand with the highest precedence involved in the operation. T he order of precedence
(higher to lower) is as follows:
Double
Unsigned long
Integer
T herefore, an operation that returns a numeric result returns a result of the highest type involved in the operation.
For example, if the operands are of type integer and unsigned long, the integer operand is automatically converted to type
unsigned long. T his type conversion is performed even in simple expressions in which the type of data identified by the
expression prefix does not match the type of data that is passed as the argument to the function. To illustrate such an
example, in the operation HTTP.REQ.CONTENT_LENGTH.DIV(3ul), the integer returned by the prefix
HTTP.REQ.CONTENT_LENGTH is automatically converted to unsigned long (the type of the data passed as the
argument to the DIV() function), and an unsigned long division is performed. Similarly, the argument can be promoted in an
expression. For example, HTTP.REQ.HEADER("myHeader").TYPECAST_DOUBLE_AT.DIV(5) promotes the integer 5 to
type double and performs double-precision division.
T he following table describes the arithmetic and Boolean functions that can be used with the integer, unsigned long, and
double data types. For information about expressions for casting data of one type to data of another type, see
"Typecasting Data."
HTTP.REQ.BODY(10).SET_CHAR_SET(UTF_8).CONTAINS("ß")
HTTP.RES.BODY(100).SET_CHAR_SET(UTF_8).BEFORE_STR("Bücher").AFTER_STR("Wörterbuch")
In an expression, the SET_CHAR_SET() function must be introduced at the point in the expression after which data processing must be carried out in
the specified character set. For example, in the expression HTTP.REQ.BODY(1000).AFTER_REGEX(re/following example/).BEFORE_REGEX(re/In the
preceding example/).CONTAINS_ANY("Greek_ alphabet"), if the strings stored in the pattern set "Greek_alphabet" are in UT F-8, you must include the
SET_CHAR_SET(UTF_8) function immediately before the CONTAINS_ANY("<string>") function, as follows:
T he SET_CHAR_SET() function sets the character set for all further processing (that is, for all subsequent functions) in the expression unless it is
overridden later in the expression by another SET_CHAR_SET() function that changes the character set. T herefore, if all the functions in a given simple
expression are intended for UT F-8, you can include the SET_CHAR_SET(UTF_8) function immediately after functions that identify text (for example,
the HEADER("<name>") or BODY(<int>) functions). In the second example that follows the first paragraph above, if the ASCII arguments passed to the
AFTER_REGEX() and BEFORE_REGEX() functions are changed to UT F-8 strings, you can include the SET_CHAR_SET(UTF_8) function immediately
after the BODY(1000) function, as follows:
HTTP.REQ.BODY(1000).SET_CHAR_SET(UTF_8).AFTER_REGEX(re/Bücher/).BEFORE_REGEX(re/Wörterbuch/).CONTAINS_ANY("Greek_alphabet")
T he UT F-8 character set is a superset of the ASCII character set, so expressions configured for the ASCII character set continue to work as expected if
you change the character set to UT F-8.
In a compound expression, if one subset of expressions is configured to work with data in the ASCII character set and the rest of the expressions are
configured to work with data in the UT F-8 character set, the character set specified for each individual expression is considered when the expressions
are evaluated individually. However, when processing the compound expression, just before processing the operators, the appliance promotes the
character set of the returned ASCII values to UT F-8. For example, in the following compound expression, the first simple expression evaluates data in the
ASCII character set while the second simple expression evaluates data in the UT F-8 character set:
HTTP.REQ.HEADER("MyHeader") == HTTP.REQ.BODY(10).SET_CHAR_SET(UTF_8)
However, when processing the compound expression, just before evaluating the "is equal to" Boolean operator, the NetScaler appliance promotes the
character set of the value returned by HTTP.REQ.HEADER("MyHeader") to UT F-8.
T he first simple expression in the following example evaluates data in the ASCII character set. However, when the NetScaler appliance processes the
compound expression, just before concatenating the results of the two simple expressions, the appliance promotes the character set of the value
returned by HTTP.REQ.BODY(10) to UT F-8.
HTTP.REQ.BODY(10) + HTTP.REQ.HEADER("MyHeader").SET_CHAR_SET(UTF_8)
Consequently, the compound expression returns data in the UT F-8 character set.
Specif ying the Character Set Based on the Character Set of Traf fic
You can set the character set to UT F-8 on the basis of traffic characteristics. If you are not sure whether the character set of the traffic being
evaluated is UT F-8, you can configure a compound expression in which the first expression checks for UT F-8 traffic and subsequent expressions set the
character set to UT F-8. Following is an example of a compound expression that first checks the value of "charset" in the request's Content-Type header
for "UT F-8" before checking whether the first 1000 bytes in the request contain the UT F-8 string Bücher:
During expression evaluation, even if the current character set is ASCII, character literals and string literals, which are enclosed in single quotation marks
('') and quotation marks (""), respectively, are considered to be literals in the UT F-8 character set. In a given expression, if a function is operating on
character or string literals in the ASCII character set and you include a non-ASCII character in the literal, an error is returned.
When configuring an expression, you can enter values in octal and hexadecimal formats. However, each hexadecimal or octal byte is considered a UT F-8
byte. Invalid UT F-8 bytes result in errors regardless of whether the value is entered manually or pasted from the clipboard. For example, "\xce\x20" is an
invalid UT F-8 character because "c8" cannot be followed by "20" (each byte in a multi-byte UT F-8 string must have the high bit set). Another example of
an invalid UT F-8 character is "\xce \xa9," since the hexadecimal characters are separated by a white-space character.
Only the <text>.XPATH and <text>.XPATH_JSON functions always return UT F-8 strings. T he following MYSQL routines determine at runtime which
character set to return, depending on the data in the protocol:
MYSQL_CLIENT_T.USER
MYSQL_CLIENT_T.DATABASE
MYSQL_REQ_QUERY_T.COMMAND
MYSQL_REQ_QUERY_T.TEXT
MYSQL_REQ_QUERY_T.TEXT(<unsigned int>)
MYSQL_RES_ERROR_T.SQLSTATE
MYSQL_RES_ERROR_T.MESSAGE
MYSQL_RES_FIELD_T.CATALOG
MYSQL_RES_FIELD_T.DB
MYSQL_RES_FIELD_T.TABLE
MYSQL_RES_FIELD_T.ORIGINAL_TABLE
MYSQL_RES_FIELD_T.NAME
MYSQL_RES_FIELD_T.ORIGINAL_NAME
MYSQL_RES_OK_T.MESSAGE
MYSQL_RES_ROW_T.TEXT_ELEM(<unsigned int>)
When you set up a connection to the NetScaler appliance by using a terminal connection (by using PuT T Y, for example), you must set the character set
for transmission of data to UT F-8.
Warning
T he Classic policy expressions are deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to use
Default (Advanced) policy expressions. You should convert the expression to Advanced, replacing SYS.EVAL_CLASSIC_EXPR. You can
also use the nspepi utility tool for the conversion.
Classic expressions describe basic characteristics of traffic. In some cases, you may want to use a classic expression in an
Advanced policy expression are no longer supported from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix
recommends you to use Advanced policies. For more information, see Advanced Policies topic. You can do so with the
Advanced policy expression configuration tool. T his can be helpful when manually migrating the older classic expressions to
the Advanced policy.
Note that when you upgrade the NetScaler to version 9.0 or higher, Integrated Caching policies are automatically upgraded
to Advanced policies, and the expressions in these policies are upgraded to the Advanced policies.
T he following is the syntax for all Advanced policy expressions that use a classic expression:
SYS.EVAL_CLASSIC_EXPR("expression")
Note
T he syntax and the metadata for the SYS.EVAL_CLASSIC_EXPR expression is getting deprecated. You can manually convert or use
nspepi tool to convert the Classic expression to advanced expression.
When configuring expressions on the command line, you delimit the expression by using quotation marks (“. . .” or '. . .').
Within an expression, you escape additional quotation marks by using a back-slash (\). For example, the following are
standard methods for escaping quotation marks in an expression:
"\"abc\""
‘\"abc\"’
You must also use a backslash to escape question marks and other backslashes on the command line. For example, the
expression http.req.url.contains(“\?”) requires a backslash so that the question mark is parsed. Note that the backslash
character will not appear on the command line after you type the question mark. On the other hand, if you escape a
backslash (for example, in the expression 'http.req.url.contains("\\\\http")'), the escape characters are echoed on the command
line.
To make an entry more readable, you can escape the quotation marks for an entire expression. At the start of the
expression you enter the escape sequence “q” plus one of the following special characters: /{<|~$^+=&%@`?.
You enter only the special character at the end of the expression, as follows:
For some features (for example, Integrated Caching and Responder), the policy configuration dialog box provides a
secondary dialog box for configuring expressions. T his dialog enables you to choose from drop-down lists that show the
available choices at each point during expression configuration. You cannot use arithmetic operators when using these
configuration dialogs, but most other advanced policy expression features are available. To use arithmetic operators , write
your expressions in free-form format.
To configure an Advanced policy syntax rule by using the command line interf ace
Note
Default syntax policy is now renamed as Advanced policy.
At the command prompt, type the following commands to configure a default syntax rule and verify the configuration:
1. add cache|dns|rewrite|cs policy policyName -rule expression featureSpecificParameters -action
2. show cache|dns|rewrite|cs policy policyName
Following is an example of configuring a caching policy:
Done
To configure a def ault syntax policy expression by using the configuration utility
1. In the navigation pane, click the name of the feature where you want to configure a policy, for example, you can select
Integrated Caching, Responder, DNS, Rewrite, or Content Switching, and then click Policies.
2. Click Add.
3. For most features, click in the Expression field. For content switching, click Conf igure.
4. Click the Pref ix icon (the house) and select the first expression prefix from the drop-down list. For example, in
Responder, the options are HT T P, SYS, and CLIENT . T he next set of applicable options appear in a drop-down list.
5. Double-click the next option to select it, and then type a period (.). Again, a set of applicable options appears in another
drop-down list.
6. Continue selecting options until an entry field (signalled by parentheses) appears. When you see an entry field, enter an
appropriate value in the parentheses. For example, if you select GT (int) (greater-than, integer format), you specify an
integer in the parentheses. T ext strings are delimited by quotation marks. Following is an example:
HTTP.REQ.BODY(1000).BETWEEN("this","that")
7. T o insert an operator between two parts of a compound expression, click the Operators icon (the sigma), and select the
operator type. Following is an example of a configured expression with a Boolean OR (signalled by double vertical bars,
||):
HTTP.REQ.URL.EQ("www.mycompany.com")||HTTP.REQ.BODY(1000).BETWEEN("this","that")
8. T o insert a named expression, click the down arrow next to the Add icon (the plus sign) and select a named expression.
9. T o configure an expression using drop-down menus, and to insert built-in expressions, click the Add icon (the plus sign).
T he Add Expression dialog box works in a similar way to the main dialog box, but it provides drop-down lists for
selecting options, and it provides text fields for data entry instead of parentheses. T his dialog box also provides a
Frequently Used Expressions drop-down list that inserts commonly used expressions. When you are done adding the
expression, click OK.
10. When finished, click Create. A message in the status bar indicates that the policy expression is configured successfully.
1. In the navigation pane, click the name of the feature for which you want to configure a policy (for example, you can
select Integrated Caching, Responder, DNS, Rewrite, or Content Switching), and then click Policies.
2. Select a policy and click Open.
You can then use these named expressions in a policy expression. For example, the following is a legal expression based on
the preceding examples:
ThisExpression || ThatExpression
You can use the name of an advanced policy expression as the prefix to a function. T he named expression can be either a
simple expression or a compound expression. T he function must be one that can operate on the type of data that is
returned by the named expression.
T he following simple named expression, which identifies a text string, can be used as a prefix to the AFTER_STR("
<string>")function, which works with text data:
HTTP.REQ.BODY(1000)
If the name of the expression is top1KB, you can use top1KB.AFTER_STR("username") instead of
HTTP.REQ.BODY(1000).AFTER_STR("username").
You can create a compound named expression called basic_header_value to concatenate the user name in a request, a
colon (:), and the user's password, as follows:
You can then use the name of the expression in a rewrite action, as shown in the following example:
In the example, in the expression that is used to construct the value of the custom header, the B64 encoding algorithm is
applied to the string returned by the compound named expression.
You can also use a named expression (either by itself or as a prefix to a function) to create the text expression for the
replacement target in a rewrite.
To configure a named def ault syntax expression by using the command line interf ace
At the command prompt, type the following commands to configure a named expression and verify the configuration:
add policy expression <name><value>
To configure an advanced policy expression outside a policy by using the command line interf ace (cache
selector example)
At the command prompt, type the following commands to configure an advanced policy expression outside a policy and
verify the configuration:
add cache selector <selectorName> <rule>
show cache selector <selectorName>
Example
You can use expression prefixes and operators for evaluating HT T P requests, HT T P responses, and VPN and Clientless VPN
data. However, text expression prefixes are not restricted to evaluating these elements of your traffic. For information
about additional default syntax text expression prefixes and operators, see the following topics:
Pattern Sets
Regular Expressions
T ypecasting Data
Default Syntax Expressions: Parsing HT T P, T CP, and UDP Data
Default Syntax Expressions: Parsing SSL Certificates
Expressions for SSL Certificate Dates
Note that there are specialized tools for viewing the data stream for HT T P requests and responses. For example, from the
following URL, you can download a Firefox Web browser plug-in that displays HT T P request and response headers:
"https://addons.mozilla.org/en-US/firefox/addon/3829"
T he following plug-in displays headers, query strings, POST data, and other information:
"https://addons.mozilla.org/en-US/firefox/addon/6647"
After you download these plug-ins, they are accessible from the Firefox Tools menu.
A text-based expression consists of at least one prefix to identify an element of data and usually (although not always) an
operation on that prefix. Text-based operations can apply to any part of a request or a response. Basic operations on text
include various types of string matches.
For example, the following expression compares a header value with a string:
http.req.header("myHeader").contains("some-text")
http.req.url.suffix.contains("jpeg")
http.req.url.suffix.eq("jpeg")
In the preceding examples, the contains operator permits a partial match and the eq operator looks for an exact match.
Other operations are available to format the string before evaluating it. For example, you can use text operations to strip
out quotes and white spaces, to convert the string to all lowercase, or to concatenate strings.
Note: Complex operations are available to perform matching based on patterns or to convert one type of text format to
another type.
You can apply various operators to combine text prefixes or expressions. For example, the following expression
concatenates the returned values of each prefix:
http.req.hostname + http.req.url
Following is an example of a compound text expression that uses a logical AND. Both components of this expression must
be T RUE for a request to match the expression:
Note: For more information on operators for compounding, see "Compound Default Syntax Expressions."
Categories of Text Expressions
T CP payload information.
For more information about TCP payload expressions, see "Default Syntax Expressions: Parsing HT T P, TCP, and UDP
Data."
Note: Parsing a document body, such as the body of a POST request, can affect performance. You may want to test the
performance impact of policies that evaluate a document body.
Guidelines f or Text Expressions
From a performance standpoint, it typically is best to use protocol-aware functions in an expression. For example, the
following expression makes use of a protocol-aware function:
HTTP.REQ.URL.QUERY
T he previous expression performs better than the following equivalent expression, which is based on string parsing:
HTTP.REQ.URL.AFTER_STR("?")
In the first case, the expression looks specifically at the URL query. In the second case, the expression scans the data for
the first occurrence of a question mark.
T here is also a performance benefit from structured parsing of text, as in the following expression:
(For more information on typecasting, see "Typecasting Data.") T he typecasting expression, which collects comma-
delimited data and structures it into a list, typically would perform better than the following unstructured equivalent:
HTTP.REQ.HEADER("Example").AFTER_STR(",").BEFORE_STR(",")
Finally, unstructured text expressions typically have better performance than regular expressions. For example, the
following is an unstructured text expression:
HTTP.REQ.HEADER("Example").AFTER_STR("more")
T he previous expression would generally provide better performance than the following equivalent, which uses a regular
expression:
HTTP.REQ.HEADER("Example").AFTER_REGEX(re/more/)
Warning
T he S and Q prefixes are deprecated from NetScaler release 12.0 and they are replaced with HT T P.REQ and HT T P.RES, respectively. You can also use the nspepi utility tool for
the conversion
An HT T P request or response typically contains text, such as in the form of headers, header values, URLs, and POST body text. You can configure expressions
to operate on one or more of these text-based items in an HT T P request or response.
T he following table describes the expression prefixes that you can configure to extract text from different parts of an HT T P request or response.
Prefix Description
It will return first 100 characters of HT T P Request body. If the length of the body is
less than 100 then the the whole body will result as output.
T he above example returns true if the domain name is foobar.com. It returns Domain
name part of the hostname. If the hostname
is www.foobar.com or www.foobar.com:8080, then the the domain is foobar.com.
T he above example returns true if the port is 80. It returns number on the port part
of the hostname.
If the path is /a/b/c.html then this operation will result in html. It returns filename
suffice of the URL.
T he above example will return list on the Group which is separated by given delimiter
I.e. “:" It returns the AAA User associated with the current HT T P transaction.
T he above example will list external groups which are separated by “,". IT returns a list
If AAA User associated with the current HT T P transaction is part of some external
groups : 123,,24, ,15 then HT T P.REQ.USER.EXT ERNAL_GROUPS.
IGNORE_EMPT Y_ELEMENT S.COUNT gives 4,
whereas HT T P.REQ.USER.EXT ERNAL_GROUPS.COUNT gives 5. It ignores empty
elements in the list.
T he above example will list external groups which are separated by “:” It returns a list
of external groups which are separated by given delimiter.
T he above example will list groups which are separated by “,". IT returns a list of
groups which are separated by “,".
If AAA User associated with the current HT T P transaction is part of some groups :
123,,24, ,15 then HT T P.REQ.USER.GROUPS.
IGNORE_EMPT Y_ELEMENT S.COUNT gives 4,
whereas HT T P.REQ.USER.GROUPS.COUNT gives 5. It ignores empty elements in the
list.
T he above example will list groups which are separated by “:" IT returns a list of
groups which are separated by given delimiter.
T he above example will list internal groups which are separated by “,". IT returns a list
of internal groups which are separated by “,".
If AAA User associated with the current HT T P transaction is part of some internal
groups : 123,,24, ,15
then HT T P.REQ.USER.INT ERNAL_GROUPS.IGNORE_EMPT Y_ELEMENT S.COUNT gives
4, whereas HT T P.REQ.USER.INT ERNAL_GROUPS.COUNT gives 5. It ignores empty
elements in the list.
T he above example will list internal groups which are separated by “:" IT returns
a list of internal groups which are separated by given delimiter.
T he above example returns true is the current AAA user is a member of group grp1. It
returns T RUE if the user is a member of the group group_name.
T he above example will return the name of the user. It returns the name of the user.
T his is the name used by the user for login unless it is overridden by name from the
T he above example will return password of the user. It returns the password of the
user.
It will return first 100 characters of HT T P Response body. If the length of the body is
less than 100 then the whole body will result as output.
T he above example results status message of response. It can be “OK”, some error
etc.
T hese text elements are often URLs and components of URLs. In addition to applying the text-based operations on these elements, you can parse these
elements by using operations that are specific to parsing URLs. For more information, see "Expressions for Extracting Segments of URLs."
T he following table describes the expression prefixes for this type of data.
Table 1. VPN and Clientless VPN Expression Pref ixes That Return Text
VPN.BASEURL.HOSTNAME Extracts the HT T P host name from the host name in the URL.
T his prefix returns incorrect results if the host name is an IP address. For
information on expressions for IP addresses, see "Default Syntax Expressions: IP
and MAC Addresses, T hroughput, VLAN IDs."
VPN.BASEURL.HOSTNAME.EQ (<hostname>) Returns a Boolean T RUE if the host name matches <hostname>. T he comparison is
case insensitive.
For example, if the host name is www.mycompany.com, the following returns T RUE:
vpn.baseurl.hostname.eq("www.mycompany.com")
If the text mode is URLENCODED, the host name is decoded before comparison.
For more information, see "Operations for HT T P, HT ML, and XML Encoding and
“Safe” Characters."
VPN.BASEURL.PATH Extracts a slash- (/) separated list from the path component of the URL. For
example, this prefix extracts /a/b/c/mypage.html from the following URL:
http://www.mycompany.com/a/b/c/mypage.html?a=1
For more information on the GET operation, see "Expressions for Extracting
Segments of URLs."
VPN.BASEURL.PATH.IGNORE_EMPTY_ELEMENTS T his prefix ignores the elements in a list. For example, the following comma-
separated list has an empty element after “a=10”:
a=10,,b=11, ,c=89
http.req.header("Cust_Header").typecase_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecase_list_t(','). count
VPN.BASEURL.PATH_AND_QUERY Evaluates the text in the URL that follows the host name.
VPN.BASEURL.QUERY Extracts a name-value list, using the “=” and “&” delimiters from the query string in a
URL.
VPN.BASEURL.QUERY.IGNORE_EMPTY_ELEMENTS T his method ignores the empty elements in a name-value list. For example, in the
following name-value list, there is an empty element following “a=10”:
a=10;;b=11; ;c=89
http.req.header("Cust_Header").typecast_nvlist_t('=',';').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_nvlist_t('=',';').
VPN.CLIENTLESS_BASEURL.CVPN_DECODE Extracts the original URL from the clientless VPN formatted URL.
T his operation returns incorrect results if the host name is an IP address. For
information on expressions for IP addresses, see "Default Syntax Expressions: IP
and MAC Addresses, T hroughput, VLAN IDs.."
vpn.clientless_baseurl. hostname.eq("www.mycompany.com")
For example, this prefix selects /a/b/c/mypage.html from the following URL:
http://www.mycompany.com/a/b/c/mypage.html?a=1
http.req.url.path.get(1)
For more information on the GET operation, see "Expressions for Extracting
Segments of URLs."
VPN.CLIENTLESS_BASEURL.PATH.IGNORE_EMPTY_ELEMENTS Ignores empty elements in a list. For example, if the list delimiter is a comma (,) the
following list has an empty element following “a=10”:
a=10,b=11, ,c=89
http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').
For example, this prefix selects /a/b/c/mypage.html?a=1 from the following URL:
http://www.mycompany.com/a/b/c/mypage.html?a=1
VPN.CLIENTLESS_BASEURL.QUERY Extracts a name-value list that uses the delimiters “=” and “&” from a URL query
string.
VPN.CLIENTLESS_BASEURL.QUERY.IGNORE_EMPTY_ Ignores empty elements in a name-value list. For example, the following list contains
ELEMENTS an empty element after “a=10”:
a=10;;b=11; ;c=89
http.req.header("Cust_Header").typecast_nvlist_t('=',';').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_nvlist_t('=',';')
VPN.CLIENTLESS_BASEURL.SUFFIX Evaluates the file suffix in a URL. For example, if the URL path is /a/b/c/mypage.html
then this operation selects html.
VPN.CLIENTLESS_HOSTURL.CVPN_DECODE Selects the original URL from the clientless VPN formatted URL.
VPN.CLIENTLESS_HOSTURL.HOSTNAME.DOMAIN Extracts the domain name from the host name. For example, if the host name is
www.mycompany.com or www.mycompany.com:8080, the domain is
mycompany.com.
T his operation returns incorrect results if the host name contains an IP address. For
information on expressions for IP addresses, see "Default Syntax Expressions: IP
and MAC Addresses, T hroughput, VLAN IDs."
vpn.clilentless_hosturl. hostname.eq("www.mycompany.com")
If the text mode is URLENCODED, the host name is decoded before comparison.
For more information, see "Operations for HT T P, HT ML, and XML Encoding and
“Safe” Characters."
T he comparison is case insensitive, and all text operations after this method are
case insensitive.
VPN.CLIENTLESS_HOSTURL.PATH Evaluates a slash- (/) separated list on the path component of the URL.
http://www.mycompany.com/a/b/c/mypage.html?a=1
VPN.CLIENTLESS_HOSTURL.PATH.IGNORE_EMPTY_ELEMENTS T his method ignores the empty elements in a list. For example, if the delimiter in a
list is “,” the following list contains an empty element after the entry “a=10”:
a=10,b=11, ,c=89
http.req.header("Cust_Header").typecast_list_t(','). ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').
VPN.CLIENTLESS_HOSTURL.PATH_AND_QUERY Evaluates the portion of the URL that follows the host name.
http://www.mycompany.com/a/b/c/mypage.html?a=1
VPN.CLIENTLESS_HOSTURL.QUERY Extracts a name-value list, using the “=” and “&” delimiters from a URL query string.
VPN.CLIENTLESS_HOSTURL.QUERY.IGNORE_EMPTY_ Ignores empty elements in a name-value list. For example, the following list uses a
ELEMENTS semicolon (;) delimiter. T his list contains an empty element after “a=10”:
In the preceding example, the element following b=11 is not considered an empty
element.
http.req.header("Cust_Header").typecast_nvlist_t('=',';').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_nvlist_t('=',';')
VPN.HOST.DOMAIN Extracts the domain name part of the host name. For example, if the host name is
www.mycompany.com or www.mycompany.com:8080, the domain is
mycompany.com.
T his prefix returns incorrect results if the host name contains an IP address. For
information on expressions for IP addresses, see "Default Syntax Expressions: IP
and MAC Addresses, T hroughput, VLAN IDs.."
VPN.HOST.EQ(<hostname>) Returns a Boolean T RUE value if the host name matches the <hostname>. T he
comparison is case insensitive.
vpn.host.eq("www.mycompany.com")
If the text mode is URLENCODED the host name is decoded before comparison.
For more information, see "Operations for HT T P, HT ML, and XML Encoding and
“Safe” Characters."
VPN.HOST.SERVER Extracts the server name part of the host name. For example, if the host name is
www.mycompany.com or www.mycompany.com:8080, the server is
www.mycompany.com.
T he following table lists basic string matching operations in which the functions return a Boolean T RUE or FALSE.
Function Description
Following is an example:
http.req.url.contains(".jpeg")
<text>.EQ(<string>) Returns a Boolean T RUE value if the target is an exact match with <string>.
For example, the following expression returns a Boolean T RUE for a URL with a host
name of “myhostabc”:
http.req.url.hostname.eq("myhostabc")
<text>.STARTSWITH(<string>) Returns a Boolean T RUE value if the target begins with <string>.
For example, the following expression returns a Boolean T RUE for a URL with a host
name of “myhostabc”:
http.req.url.hostname.startswith("myhost")
<text>.ENDSWITH(<string>) Returns a Boolean T RUE value if the target ends with <string>.
For example, the following expression returns a Boolean T RUE for a URL with a host
name of “myhostabc”:
http.req.url.hostname.endswith("abc")
<text>.NE(<string>) Returns a Boolean T RUE value if the prefix is not equal to the string argument.
If the prefix returns a non-string value, the function argument is compared to the
string representation of the value returned by the prefix. You can use the functions
with SET _T EXT _MODE(IGNORECASE) or SET _T EXT _MODE(NOIGNORECASE), and
<text>.GT(<string>) Returns a Boolean T RUE value if the prefix is alphabetically greater than the string
argument.
If the prefix returns a non-string value, the function argument is compared to the
string representation of the value returned by the prefix. You can use the functions
with SET _T EXT _MODE(IGNORECASE) or SET _T EXT _MODE(NOIGNORECASE), and
with both ASCII and UT F-8 character sets.
<text>.GE(<string>) Returns a Boolean T RUE value if the prefix is alphabetically greater than or equal to
the string argument.
If the prefix returns a non-string value, the function argument is compared to the
string representation of the value returned by the prefix. You can use the functions
with SET _T EXT _MODE(IGNORECASE) or SET _T EXT _MODE(NOIGNORECASE), and
with both ASCII and UT F-8 character sets.
<text>.LT(<string>) Returns a Boolean T RUE value if the prefix is alphabetically lesser than the string
argument.
If the prefix returns a non-string value, the function argument is compared to the
string representation of the value returned by the prefix. You can use the functions
with SET _T EXT _MODE(IGNORECASE) or SET _T EXT _MODE(NOIGNORECASE), and
with both ASCII and UT F-8 character sets.
<text>.LE(<string>) Returns a Boolean T RUE value if the prefix is alphabetically lesser than or equal to the
string argument.
If the prefix returns a non-string value, the function argument is compared to the
string representation of the value returned by the prefix. You can use the functions
with SET _T EXT _MODE(IGNORECASE) or SET _T EXT _MODE(NOIGNORECASE), and
with both ASCII and UT F-8 character sets.
T he <text>.LENGT H operation returns a numeric value that is equal to the number of characters (not bytes) in a string:
<text>.LENGTH
For example, you may want to identify request URLs that exceed a particular length. Following is an expression that
implements this example:
After taking a count of the characters or elements in a string, you can apply numeric operations to them. For more
information, see Default Syntax Expressions: Working with Dates, T imes, and Numbers.
T he following functions operate on the case (upper-case or lower-case) of the characters in the string.
Function Description
<text>.SET_TEXT_MODE(IGNORECASE| T his function turns case sensitivity on or off for all text operations.
NOIGNORECASE)
<text>.TO_LOWER Converts the target to lowercase for a text block of up to 2 kilobyte (KB).
Returns UNDEF if the target exceeds 2 KB.
<text>.TO_UPPER Converts the target to uppercase. Returns UNDEF if the target exceeds 2
KB.
You can use the STRIP_CHARS(<string>) function to remove specific characters from the text that is returned by a
default syntax expression prefix (the input string). All instances of the characters that you specify in the argument are
stripped from the input string. You can use any text method on the resulting string, including the methods used for
matching the string with a pattern set.
In the following example, the resulting string is compared with a pattern set called "listofdomains":
CLIENT.UDP.DNS.DOMAIN.STRIP_CHARS(".-_").CONTAINS_ANY("listofdomains")
Note: You cannot perform a rewrite on the string that is returned by the STRIP_CHARS(<string>) function.
T he following functions strip matching characters from the beginning and end of a given string input.
Function Description
<text>.STRIP_START_CHARS(s) Strips matching characters from the beginning of the input string until the first
non-matching character is found and returns the remainder of the string. You must
specify the characters that you want to strip as a single string within quotation
marks.
<text>.STRIP_END_CHARS(s) Strips matching characters from the end of the input string to the first non-
matching character is found and returns the remainder of the string. You must
specify the characters that you want to strip as a single string within quotation
marks.
For example, if the name of a header is TestLang and ://_en_us: is its value,
HTTP.RES.HEADER("TestLang").STRIP_START_CHARS(":/_") strips the
specified characters from the end of the value of the header until the first non-
matching character s is found and returns ://_en_us as a string.
You can use the APPEND() function to append the string representation of the argument to the string representation of
the value returned by the preceding function. T he preceding function can be one that returns a number, unsigned long,
double, time value, IPv4 address, or IPv6 address. T he argument can be a text string, number, unsigned long, double, time
value, IPv4 address, or IPv6 address. T he resulting string value is the same string value that is obtained by using the +
operator.
For any operation that takes a string argument, the string cannot exceed 255 characters.
You can include white space when you specify a string in an expression.
<text>.TRUNCATE(<count>) Returns a string after truncating the end of the target by the number of
characters in <count>.
<text>.TRUNCATE(<character>, Returns a string after truncating the text after <character> by the number of
<count>) characters specified in <count>.
<text>.PREFIX(<character>, Selects the longest prefix in the target that has at most <count> occurrences of
<count>) <character>.
JLEwx
http.res.body(100).suffix('L',2)
<text>.SUBSTR(<starting_offset>, Select a string with <length> number of characters from the target object. Begin
<length>) extracting the string after the <starting_offset>. If the number of characters after
the offset are fewer than the value of the <length> argument, select all the
remaining characters.
<text>.SKIP(<character>, Select a string from the target after skipping over the longest prefix that has at
<count>) most <count> occurrences of <character>.
You can extract a subset of a larger string by using one of the operations in the following table.
<text>.BEFORE_STR(<string>) Returns the text that precedes the first occurrence of <string>.
If there is no match for <string>, the expression returns a text object of 0 length.
Following is an example:
http.res.body(1024).after_str("start_string").before_str("end_string").contains("https")
<text>.AFTER_STR(<string>) Returns the text that follows the first occurrence of <string>.
If there is no match for <string>, the expression returns a text object of 0 length.
Following is an example:
http.res.body(1024).after_str("start_string").before_str("end_string").contains("https")
<text>.BETWEEN(<starting Returns a Boolean T RUE value if the length of the text object is greater than or equal
string>, <ending string>) to the sum <starting string>, <ending string> argument lengths, and if a prefix of the
target matches <starting string>, and if the suffix of the target matches <ending
string>.
<text>.PREFIX(<prefix length>) Returns the starting string from a target block of text that contains the number of
characters in the <prefix length> argument.
<text>.SUFFIX(<suffix length>) Returns the ending string from a target block of text that contains the number of
characters in the <suffix length> argument. If the <suffix length> argument exceeds
the number characters in the target, the entire string is selected.
<text>.SUBSTR(<string>) Select the first block of text in the target that matches the <string>.
<text>.SKIP(<prefix length>) Selects the text in the target after skipping over a <prefix length> number of
characters.
If the entire target has fewer characters than <prefix length>, the entire target is
skipped.
<text>.STRIP_END_WS Selects the text after removing white space from the end of the target.
<text>.STRIP_START_WS Selects the text after removing white space from the beginning of the target.
<text>.UNQUOTE(<character>) Selects the <character>, removes white space that immediately precedes and follows
the <character>, and if the remaining text is quoted by <character>, this prefix also
removes the quotes.
For example, the operation UNQUOT E('"') changes the following text:
To the following:
T he COMPARE operation examines the first nonmatching character of two different strings. T his operation is based on
lexicographic order, which is the method used when ordering terms in dictionaries.
T his operation returns the arithmetic difference between the ASCII values of the first nonmatching characters in the
compared strings. T he following differences are examples:
T he difference between “abc” and “abd” is -1 (based on the third pair-wise character comparison).
T he difference between “@” and “abc” is -33.
T he difference between “1” and “abc” is -47.
<text>.COMPARE(<string>)
You can use the following functions to treat a string of bytes that represent text as a sequence of bytes, extract 8, 16, or
32 bits from the sequence, and then convert the extracted bits to an integer.
Table 3. Operations f or Extracting an Integer f rom a String of Bytes That Represent Text
Function Description
<text>.GET_SIGNED8(<n>) Treats the string of bytes represented by text as a sequence of 8-bit signed integers
and returns the integer at byte offset n. If the offset makes all or part of the value
outside of the current text, an UNDEF condition is raised.
<text>.GET_UNSIGNED8(<n>) Treats the string of bytes represented by text as a sequence of 8-bit unsigned
integers and returns the integer at byte offset n. If the offset makes all or part of
the value outside of the current text, an UNDEF condition is raised.
<text>.GET_SIGNED16(<n>, Treats the text string returned by the prefix as a string of bytes, extracts 16 bits
<endianness>) starting at byte offset n, and converts the extracted bit sequence to a 16-bit signed
integer. If the offset makes all or part of the value outside of the current text, an
UNDEF condition is raised.
T he first parameter n is the byte offset from the current position in the text string.
Providing a byte offset enables the function to handle items that are not aligned on
the boundaries that are required by indexes. T he second parameter, endianness,
takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN.
Note: In NetScaler 9.2, the parameter n was an index into an array of 16-bit items. In
NetScaler 9.3, the parameter is a byte offset. T herefore, if you used this function in
NetScaler 9.2, after you upgrade to NetScaler 9.3, you must change n to 2*n to
obtain the same results as you did earlier. For example, if the value of n before the
upgrade was 4, you must change the value of n to 8. T he parameter endianness also
no longer takes the values that it did in NetScaler 9.2, which were 0 and 1. Instead,
endianness accepts the mnemonic values mentioned earlier.
Example
HTTP.REQ.BODY(100).GET_SIGNED16(8, BIG_ENDIAN)
<text>.GET_UNSIGNED16(<n>, Treats the text string returned by the prefix as a string of bytes, extracts 16 bits
<endianness>) starting at byte offset n, and converts the extracted bit sequence to a 16-bit
unsigned integer. If the offset makes all or part of the value outside of the current
text, an UNDEF condition is raised.
T he first parameter n is the byte offset from the current position in the text string.
Providing a byte offset enables the function to handle items that are not aligned on
the boundaries that are required by indexes. T he second parameter, endianness,
takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN.
HTTP.REQ.BODY(100).GET_UNSIGNED16(8, LITTLE_ENDIAN)
<text>.GET_SIGNED32(<n>, Treats the text string returned by the prefix as a string of bytes, extracts 32 bits
<endianness>) starting at byte offset n, and converts the extracted bit sequence to a 32-bit signed
integer. If the offset makes all or part of the value outside of the current text, an
UNDEF condition is raised.
T he first parameter n is the byte offset from the current position in the text string.
Providing a byte offset enables the function to handle items that are not aligned on
the boundaries that are required by indexes. T he second parameter, endianness,
takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN.
Note: In NetScaler 9.2, the parameter n was an index into an array of 32-bit items. In
NetScaler 9.3, the parameter is a byte offset. T herefore, if you used this function in
NetScaler 9.2, after you upgrade to NetScaler 9.3, you must change n to 4*n to
obtain the same results as you did earlier. For example, if the value of n before the
upgrade was 4, you must change the value of n to 16. T he parameter endianness
also no longer takes the values that it did in NetScaler 9.2, which were 0 and 1.
Instead, endianness accepts the mnemonic values mentioned earlier.
Example
HTTP.REQ.BODY(1000).GET_SIGNED32(12, BIG_ENDIAN)
<text>.GET_UNSIGNED32(<n>, Treats the text string returned by the prefix as a string of bytes, extracts 32 bits
<endianness>) starting at byte offset n, and returns the extracted bit sequence as part of a 64-bit
unsigned long integer. If the offset makes all or part of the value outside of the
current text, an UNDEF condition is raised.
T he first parameter n is the byte offset from the current position in the text string.
Providing a byte offset enables the function to handle items that are not aligned on
the boundaries that are required by indexes. T he second parameter, endianness,
takes a mnemonic value of LITTLE_ENDIAN or BIG_ENDIAN.
Example
HTTP.REQ.BODY(1000).GET_UNSIGNED32(30, LITTLE_ENDIAN)
<text>.HASH
T his function ignores case and white spaces. For example, after the operation, the two strings Ab c and a bc would
produce the same hash value.
T he following two functions encode and decode a text string by applying the Base64 encoding algorithm
Table 4 . Functions f or Encoding and Decoding a Text String by Using Base64 Encoding
Function Description
text.B64ENCODE Encodes the text string (designated by text) by applying the Base64 encoding algorithm.
text.B64DECODE Decodes the Base64-encoded string (designated by text) by applying the Base64 decoding
algorithm. T he operation raises an UNDEF if text is not in B64-encoded format.
T he EXTEND function is used in rewrite actions that specify patterns or pattern sets and target the bodies of HT T P
packets. When a pattern match is found, the EXTEND function extends the scope of the search by a predefined number
of bytes on both sides of the matching string. A regular expression can then be used to perform a rewrite on matches in
this extended region. Rewrite actions that are configured with the EXTEND function perform rewrites faster than rewrite
actions that evaluate entire HT T P bodies using only regular expressions.
T he format of the EXTEND function is EXTEND(m,n ), where m and n are the number of bytes by which the scope of the
search is extended before and after the matching pattern, respectively. When a match is found, the new search scope
comprises m bytes that immediately precede the matching string, the string itself, and the n bytes that follow the string. A
regular expression can then be used to perform a rewrite on a portion of this new string.
T he EXTEND function can be used only if the rewrite action in which it is used fulfills the following requirements:
Additionally, the EXTEND function can be used only with the following types of rewrite actions:
replace_all
insert_after_all
delete_all
insert_before_all
For example, you might want to delete all instances of "http://exampleurl.com/" and "http://exampleurl.au/" in the first
1000 bytes of the body. To do this, you can configure a rewrite action to search for all instances of the string exampleurl,
extend the scope of the search on both sides of the string when a match is found, and then use a regular expression to
T he following function converts text to hexadecimal format and extracts the resulting string:
<text>.BLOB_TO_HEX(<string>)
For example, this function converts the byte string “abc” to “61:62:63”.
Updated: 2013-09-02
In default syntax expressions, you can use the ENCRYPT and DECRYPT functions to encrypt and decrypt text. Data
encrypted by the ENCRYPT function on a given NetScaler appliance or high availability (HA) pair is intended for decryption
by the DECRYPT function on the same NetScaler appliance or HA pair. T he appliance supports the RC4, DES3, AES128,
AES192, and AES256 encryption methods. T he key value that is required for encryption is not user-specifiable. When an
encryption method is set, the appliance automatically generates a random key value that is appropriate for the specified
method. T he default method is AES256 encryption, which is the most secure encryption method and the one that Citrix
recommends.
You do not need to configure encryption unless you want to change the encryption method or you want the appliance to
generate a new key value for the current encryption method.
Note: You can also encrypt and decrypt XML payloads. For information about the functions for encrypting and decrypting
XML payloads, see "Encrypting and Decrypting XML Payloads."
Configuring Encryption
Updated: 2013-09-02
During startup, the appliance runs the set ns encryptionParams command with, by default, the AES256 encryption method,
and uses a randomly generated key value that is appropriate for AES256 encryption. T he appliance also encrypts the key
value and saves the command, with the encrypted key value, to the NetScaler configuration file. Consequently, the AES256
encryption method is enabled for the ENCRYPT and DECRYPT functions by default. T he key value that is saved in the
configuration file persists across reboots even though the appliance runs the command each time you restart it.
You can run the set ns encryptionParams command manually, or use the configuration utility, if you want to change the
encryption method or if you want the appliance to generate a new key value for the current encryption method. To use
the CLI to change the encryption method, set only the method parameter, as shown in "Example 1: Changing the
Encryption Method." If you want the appliance to generate a new key value for the current encryption method, set the
method parameter to the current encryption method and the keyValue parameter to an empty string (""), as shown in
"Example 2: Generating a New Key Value f or the Current Encryption Method." After you generate a new key value,
you must save the configuration. If you do not save the configuration, the appliance uses the newly generated key value
only until the next restart, after which it reverts to the key value in the saved configuration.
After you configure policies for encryption and decryption, save the configuration to bring the policies into effect.
In default syntax expressions, you can use ENCRYPT and DECRYPT functions for encrypting and decrypting text in a
request or response. T he data encrypted by the ENCRYPT function on an appliance (standalone, high availability or cluster)
is intended to be decrypted by the DECRYPT function by the same appliance. T he appliance supports RC4, DES, Triple-DES,
AES92, and AES256 encryption methods and each of these methods use a secret key for both encryption and decryption
of data. You can use the any of these methods to encrypt and decrypt data in two ways - self-encryption and third-party
encryption.
T he self-encryption feature in an appliance (standalone, high availability or cluster) encrypts and then decrypts data by
evaluating the header value. One example to understand this is the HT T P Cookie encryption. T he expression evaluates the
header, encrypts the HT T P cookie value in the Set-Cookie header in the outgoing response and then decrypts the cookie
value when it is returned in the cookie header of a subsequent incoming request from the client. T he key value is not user
configurable, instead when an encryption method is configured in the set ns encryptionParams command, the appliance
automatically generates a random key value for the configured method. By default, the command uses the AES256
encryption method, which is the highly secured method and Citrix recommends this method.
T he third-party encryption feature encrypts or decrypts data with a third-party application. For example, a client may
encrypt data in a request and the appliance decrypts the data before sending it the back-end server or vice versa. To
perform this, the appliance and the third party application must share a secret key. On the appliance, you can directly
configure the secret key using an encryption key object and key value is automatically generated by the appliance for a
stronger encryption. T he same key is manually configured on the third-party appliance so that both appliance and third-
party application can use the same key for encrypting and decryption data.
Note: Using third-party encryption, you can also encrypt and decrypt XML payloads. For information about the functions
for encrypting and decrypting XML payloads, see "Encrypting and Decrypting XML Payloads.
Cipher Methods
A good cipher method makes it infeasible to decrypt ("crack") ciphertext if you don’t possess the key. "Infeasible" really
means that cracking the cyphertext would take more time and computing resources than it is worth. As computers become
more powerful and cheaper, ciphers that were formerly infeasible to crack become more feasible. Also, over time, flaws are
found in cipher methods (or their implementations), making cracking easier. Newer cipher methods are therefore preferred
over older ones. In general, longer length keys provide better security than shorter keys, at the cost of longer encryption
and decryption times.
A cipher method can use stream ciphers or block ciphers. RC4 is the mostly secured stream ciphers and it is used only for
legacy application. Block ciphers can include padding.
Stream Ciphers
A stream cipher method operates on individual bytes. Only one stream cipher is available on NetScaler- appliances: RC4,
which uses a 128 bit (16 byte) key length. For a given key, RC4 generates a pseudo-random sequence of bytes, call a
keystream, which is X-ORed with the plaintext to produce the ciphertext. RC4 is no longer considered secure and should be
used only if required by legacy applications.
Block Ciphers
A block cipher method operates on a fixed block of bytes. A NetScaler appliance provides two block ciphers: Data
Encryption Standard (DES) and the Advanced Encryption Standard (AES). DES uses a block size of 8 bytes and (on a
NetScaler appliance) two choices for key length: 64 bits (8 bytes), of which 56 bits are data and 8 bits are parity, and Triple-
DES, a 192 bit (24 byte) key length. AES has a block size of 16 bytes and (on NetScaler) three choices for key length: 128 bits
(16 bytes), 192 bits (24 bytes) and 256 bits (32 bytes).
Padding
If the plaintext for a block cipher is not an integral number of blocks, padding with additional bytes might be required. For
example, suppose the plaintext is “xyzzy” (hex 78797a7a79). For an 8-byte Triple-DES block, this value would have to be
padded to create 8 bytes. T he padding scheme must allow the decryption function to determine the length of the original
plaintext after decryption. Following are some padding schemes currently in use (n is the number of bytes added):
PKCS7: Adds n bytes of value n each. For example, 78797a7a79030303. T his is the padding scheme used by OpenSSL
and ENCRYPT () policy function. T he PKCS5 padding scheme is the same as PKCS7.
ANSI X.923: Adds n-1 zero bytes and a final byte of value n. For example, 78797a7a79000003.
ISO 10126: Adds n-1 random bytes and a final byte of value n. For example, 78797a7a79xxxx03, where xx can be any
byte value. T he DECRYPT () policy function accepts this padding scheme, which also allows it to accept the PKCS7 and
ANSI X.923 schemes.
ISO/IEC 7816-4: Adds a 0x80 byte and n-1 zero bytes. For example, 78797a7a79800000. T his is also call OneAndZeros
padding.
Zero: Adds n zero bytes. Example: 78797a7a79000000. T his can only be used with plaintext that does not include NUL
If padding is used and the plaintext is an integral number of blocks, an additional block is typically added so that the
decryption function can unambiguously determine the original plaintext length. For PCKS7 and 8 byte block, this would be
0808080808080808.
Modes of Operation
T here are a number of different modes of operation for block ciphers, which specify how multiple blocks of plaintext are
encrypted. Some modes use an initialization vector (IV), a block of data apart from the plaintext that is used to start the
encryption process. It is a good practice to use a different IV for each encryption, so that the same plaintext produces
different ciphertext. T he IV does not need to be secret, and so is usually prepended to the ciphertext. Modes include:
Electronic Codebook (ECB): Each block of plaintext is encrypted independently. An IV is not used. Padding is required if
the plaintext is not a multiple of the cipher block size. T he same plaintext and key always produces the same ciphertext.
Because of this, ECB is considered less secure than other modes and should only be used for legacy applications.
Cipher Block Chaining (CBC): Each block of plaintext is XORed with the previous ciphertext block, or the IV for the first
block, before being encrypted. Padding is required if the plaintext is not a multiple of the cipher block size. T his is the
mode used with the Netscaler encryptionParams method.
Cipher Feedback (CFB): T he previous ciphertext block, or the IV for the first block, is encrypted and the output is XORed
with the current plaintext block to create the current ciphertext block. T he feedback can be 1 bit, 8 bits, or 128 bits.
Since the plaintext is XORed with the cipher text, padding is not required.
Output Feedback (OFB): A keystream is generated by applying the cipher successively to the IV and XORing the
keystream blocks with the plaintext. Padding is not required.
1. Adding an encryption key. Configures an encryption key for a specified cipher method with a specified key value.
2. Modifying an encryption key. You can edit parameters for a configured encryption key.
3. Unsetting an encryption key. Sets parameters for a configured encryption key to their default values. An encryptionKey
value with the name must exist. Sets padding to DEFAULT (determined by the method), Deletes an existing IV, which
causes ENCRYPT () to generate a random IV. Deletes an existing comment. T he method and key value cannot be reset.
4. Removing an encryption key. Deletes a configured encryption key. T he key cannot have any references.
5. Show an encryption key. Displays parameters for the configured encryption key or all configured keys. If the name is
omitted, the key value is not displayed.
Where,
command COPY
T he above encryption methods specify the operation mode with CBC as the default mode of operation. T herefore, DES,
DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-CBC, AES128-CBC, AES192-CBC, and
AES256-CBC methods.
command COPY
command COPY
command COPY
rm ns encryptionKey <name>
command COPY
Example COPY
rm ns encryptionKey my_key
Name: my_key
Method: AES256
Padding: DEFAULT
Navigate to System > Encryption Keys and click Add to create an encryption key.
Navigate to System > Encryption Keys and click Edit to modify parameters for a configured encryption key.
command COPY
Where,
encryptionKey: An optional string parameter that specifies the configured encryption key object to provide the encryption
method, secret key value and other encryption parameters. If omitted, the method uses the automatically generated key
value associated with the set ns encryptionParamS command.
out_encoding: T his value specifies how the output is encoded. If omitted, BASE64 encoding is used.
Input COPY
BASE64: original PEM base64-encoding: 6 bits (0..63) encoded as one ASCII character:
0..23 = 'A'..'Z', 24..51 = 'a'..'z', 52..61 = '0'..'9', 62 = '+', 63 = '/', '=' = pad byte.
BASE64URL: URL and Filename safe base64-encoding: same as BASE64 except 62 = '-', 63 = '_'
HEX_COLONS: Hexadecimal with 0..9 = '0'..'9' and 10..15 = 'A'..'F'; ':' between each hex byte. Matches BLOB_TO_HEX() output format
HEX: For input, accepts HEX_UPPER, HEX_LOWER, and HEX_COLONS format. For output, produces HEX_LOWER format
Output: T he output is a text encrypted using the specified method and key and encoded using a specified output encoding.
It inserts a generated IV before the encrypted text for block methods and modes that require an IV, and either no IV is
specified for the encryptionKey or the encryptionKey is omitted.
Where,
Input data is an encrypted text using the specified method and key encoded using the specified input encoding. T his text is
expected to include a generated IV before the encrypted text for block methods and modes that require an IV, and either
no IV is specified for the encryptionKey or the encryptionKey is omitted.
encryptionKey— An optional string parameter that specifies the configured encryptionKey object to provide the encryption
method, secret key and other encryption parameters. If omitted, the method and automatically generated key associated
with the encryptionParams setting will be used
in_encoding— An optional enumeration parameter that specifies how the input is expected to be encoded. T he values are
the same as the out_encoding of ENCRYPT. If omitted, BASE64 encoding will be expected.
Following are the variants of these functions with the optional parameters:
ENCRYPT (encryptionKey, out_encoding) Use the specified encryptionKey and output encoding
parameter.
DECRYPT (encryptionKey, out_encoding) Use the specified encryptionKey and input encoding
parameter.
NetScaler appliances support a Hashed Message Authentication Code (HMAC) function that calculates a digest method or
hash of input text by using a secret key shared between a message sender and message receiver. T he digest method
(derived from an RFC 2104 technique) authenticates the sender and verifies that the message content has not been
altered. For example, when a client sends a message with the shared HMAC key to a NetScaler appliance, advanced (PI)
policy expressions use the HMAC function to compute the hash-based code on the selected text. T hen, when the receiver
receives the message with the secret key, it recomputes the HMAC by comparing it with the original HMAC to determine
whether the message has been altered. T he HMAC function is supported by standalone appliances and by appliances in a
high availability configuration or in a cluster. Using it is similar to configuring an encryption key.
1. Adding an HMAC key. Configures an HMAC key with a specified key value.
2. Modifying an HMAC key. Modifies parameters for a configured HMAC key. T he digest method can be changed without
changing the key value, since the key value length is not determined by the digest. However, it is advisable to specify a
new key when changing the digest.
3. Unsetting an HMAC key. Sets parameters for a configured HMAC key to their default values. An hmacKey object with
the name must exist. T he only parameter that can be unset is the comment, which is deleted.
4. Removing an HMAC key. Deletes a configured key. T he key cannot have any references.
5. Show an HMAC key. Displays parameters for the configured HMAC ac key or all configured keys. If the name is omitted,
the key value is not displayed.
command COPY
Where,
T his command configures a key for the HMAC () function with the specified digest and key value and also validates the
following:
Name syntax is correct and does not duplicate the name of an existing key.
Key value is valid hex. As specified by RFC 2104, the key can any length. On a NetScaler appliance, the key value can
range from 0 to 255 bytes (0 to 510 hex characters). If the key is shorter than the digest block size, a warning is issued
and the key is padded with zeroes. If the key is longer than the block size, it is run through the digest to produce an
effective key that is the same length as the block.
Example COPY
T he above encryption methods specify the operation mode with CBC as the default mode of operation. T herefore, DES,
DES2, AES128, AES192, and AES256 methods are equivalent to DES-CBC, DES3-CBC, AES128-CBC, AES192-CBC, and
AES256-CBC methods.
command COPY
[-comment <string>]
command COPY
command COPY
rm ns hmacKey <name>
command COPY
Example COPY
rm ns hmacKey my_hmac_key
Name: my_hmac_key
Digest: SHA1
A numeric expression consists of an expression prefix that returns a number and sometimes, but not always, an operator
that can perform an operation on the number. Examples of expression prefixes that return numbers are SYS.TIME.DAY,
HTTP.REQ.CONTENT_LENGTH, and HTTP.RES.BODY.LENGTH. Numeric operators can work with any prefix expression
that returns data in numeric format. T he GT (<int>) operator, for example, can be used with any prefix expression, such as
HTTP.REQ.CONTENT_LENGTH, that returns an integer. Numeric expression prefixes and operators are also covered in
"Compound Operations for Numbers" and "Advanced Policy Expressions: Parsing HT T P, TCP, and UDP Data."
Where:
T he following example expression is true if the date is between 2008 Jan and 2009 Jan, based on GMT.
T he following example expression is true for March and all months that follow March in the calendar year, based on GMT :
When you specify a date and time, note that the format is case sensitive and must preserve the exact number of blank
spaces between entries.
Note: In an expression that requires two time values, both must use GMT or both must use LOCAL. You cannot mix the two
in an expression.
Note: Unlike when you use the SYS.T IME prefix in an advanced policy expression, if you specify SYS.T IME in a rewrite action,
the NetScaler returns a string in conventional date format (for example, Sun, 06 Nov 1994 08:49:37 GMT ). For example, the
following rewrite action replaces the http.res.date header with the NetScaler system time in a conventional date format:
add rewrite action sync_date replace http.res.date sys.time
T he following table describes the expressions that you can create by using the SYS.TIME prefix.
SYS.TIME.BETWEEN(<time1>, Returns a Boolean T RUE if the returned value is later than <time1> and earlier than
<time2>) <time2>.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following:
SYS.TIME.DAY Returns the current day of the month as a number from 1 through 31.
SYS.TIME.EQ(<time>) Returns a Boolean T RUE if the current time is equal to the <time> argument.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.GE(<time>) Returns a Boolean T RUE if the current time is later than or equal to <time>.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.GT(<time>) Returns a Boolean T RUE if the time value is later than the <time> argument.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.LE(<time>) Returns a Boolean T RUE if the current time value precedes or is equal to the <time>
argument.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.LT(<time>) Returns a Boolean T RUE if the current time value precedes the <time> argument.
For example, if the current time is GMT 2005 May 1 10h 15m 30s, and it is the first
Sunday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.MONTH Extracts the current month and returns an integer from 1 (January) to 12 (December).
SYS.TIME.RELATIVE_BOOT Calculates the number of seconds to the closest previous or scheduled reboot, and
returns an integer.
If the closest boot time is in the past, the integer is negative. If it is in the future, the
integer is positive.
SYS.TIME.RELATIVE_NOW Calculates the number of seconds between the current NetScaler system time and
the specified time, and returns an integer showing the difference.
If the designated time is in the past, the integer is negative; if it is in the future, the
integer is positive.
SYS.TIME.SECONDS Extracts the seconds from the current NetScaler system time, and returns that value
SYS.TIME.WITHIN (<time1>, If you omit an element of time in <time1>, for example, the day or hour, it is assumed
<time2>) to have the lowest value in its range. If you omit an element in <time2>, it is assumed
to have the highest value of its range.
T he ranges for the elements of time are as follows: month 1-12, day 1-31, weekday
0-6, hour 0-23, minutes 0-59 and seconds 0-59. If you specify the year, you must do
so in both <time1> and <time2>.
For example, if the time is GMT 2005 May 10 10h 15m 30s, and it is the second
Tuesday of the month, you can specify the following (evaluation results are shown in
parentheses):
SYS.TIME.YEAR Extracts the year from the current system time and returns that value as a four-digit
integer.
CLIENT.SSL.CLIENT_CERT
T he following example expression matches a particular time for expiration with the information in the certificate:
client.ssl.client_cert.valid_not_after.eq(GMT 2009)
T he following table describes time-based operations on SSL certificates. To obtain the expression you want, replace
certificate in the expression in the first column with the prefix expression, “CLIENT.SSL.CLIENT_CERT”.
For example, if it is GMT 2005 May 1 10h 15m 30s, and the
first Sunday of the month, you can specify the following
(evaluation results are in parentheses).
<certificate>.VALID_NOT_AFTER.DAY Extracts the last day of the month that the certificate is
valid, and returns a number from 1 through 31, as
appropriate for the date.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify
the following (evaluation results for this example are in
parentheses):
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
<certificate>.VALID_NOT_AFTER.HOURS Extracts the last hour that the certificate is valid and
returns that value as an integer from 0 to 23.
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify
the following:
<certificate>.VALID_NOT_AFTER.MINUTES Extracts the last minute that the certificate is valid and
returns that value as an integer from 0 to 59.
<certificate>.VALID_NOT_AFTER.MONTH Extracts the last month that the certificate is valid and
returns that value as an integer from 1 (January) to 12
(December).
<certificate>.VALID_NOT_AFTER.SECONDS Extracts the last second that the certificate is valid and
returns that value as an integer from 0 to 59.
<certificate>.VALID_NOT_AFTER.WITHIN(<time1>, Returns a Boolean T RUE if the time lies within all the ranges
<time2>) defined by the elements in <time1> and <time2>.
For example, if time is GMT 2005 May 10 10h 15m 30s, and it
is the second Tuesday of the month, you can specify the
following (evaluation results are in parentheses):
<certificate>.VALID_NOT_AFTER.YEAR Extracts the last year that the certificate is valid and returns
a four-digit integer.
<certificate>.VALID_NOT_BEFORE Returns the date that the client certificate becomes valid.
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
<certificate>.VALID_NOT_BEFORE.DAY Extracts the last day of the month that the certificate is
valid and returns that value as a number from 1 through 31
representing that day.
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results are in
parentheses):
<certificate>.VALID_NOT_BEFORE.GT(<time>) Returns a Boolean T RUE if the time occurs after the <time>
argument.
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results are in
parentheses):
<certificate>.VALID_NOT_BEFORE.HOURS Extracts the last hour that the certificate is valid and
returns that value as an integer from 0 to 23.
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
For example, if the time value is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month of May in 2005,
you can specify the following (evaluation results for this
example are in parentheses):
<certificate>.VALID_NOT_BEFORE.MINUTES Extracts the last minute that the certificate is valid. Returns
the current minute as an integer from 0 to 59.
<certificate>.VALID_NOT_BEFORE.MONTH Extracts the last month that the certificate is valid. Returns
the current month as an integer from 1 (January) to 12
(December).
<certificate>.VALID_NOT_BEFORE.SECONDS Extracts the last second that the certificate is valid. Returns
the current second as an integer from 0 to 59.
For example, if the time is GMT 2005 May 10 10h 15m 30s,
and it is the second Tuesday of the month, you can specify
the following (evaluation results are in parentheses):
<certificate>.VALID_NOT_BEFORE.YEAR Extracts the last year that the certificate is valid. Returns
the current year as a four-digit integer.
As a number. T he numeric value of an HT T P Date header is returned in the form of the number of seconds since Jan 1,
1970.
For example, the expression http.req.date.mod(86400) returns the number of seconds since the beginning of the day.
T hese values can be evaluated using the same operations as other non-date-related numeric data. For more information,
see "Expression Prefixes for Numeric Data Other T han Date and T ime."
As an HT T P header. Date headers can be evaluated using the same operations as other HT T P headers.
For more information, see "Advanced Policy Expressions: Parsing HT T P, TCP, and UDP Data."
As text. Date headers can be evaluated using the same operations as other strings.
Prefix Description
HTTP.REQ.DATE Returns the contents of the HT T P Date header as text or as a date object. T he date formats
recognized are:
HTTP.RES.DATE Returns the contents of the HT T P Date header as text or as a date object. T he date formats
recognized are:
T able 1. F unct ions t hat Generat e t he Day of t he Week, as a St ring, in Short and Long F ormat s
<prefix>.WEEKDAY_STRING_SHORT Returns the day of the week in short format. T he short form is always 3
characters long with an initial capital and the remaining characters in lower
case. For example, SYS.TIME.WEEKDAY.WEEKDAY_STRING_SHORT
returns Sun if the value returned by the WEEKDAY function is 0 and Sat if
the value returned by the prefix is 6.
<prefix>.WEEKDAY_STRING Returns the day of the week in long format. T he long form always has an
initial capital, with the remaining characters in lower case. For example,
SYS.TIME.WEEKDAY.WEEKDAY_STRING returns Sunday if the value
returned by the WEEKDAY function is 0 and Saturday if the value returned by
the prefix is 6.
Client and server data in regard to interface IDs and transaction throughput rate.
For more information, see "Expressions for Numeric Client and Server Data."
All the functions return a value of type text. T he endianness that some of the functions accept as a parameter is either LIT T LE_ENDIAN or BIG_ENDIAN.
<number>.SIGNED8_STRING Produces an 8-bit signed binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).GET_SIGNED8(16).SUB(3).SIGNED8_STRING
<number>.UNSIGNED8_STRING Produces an 8-bit unsigned binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).GET_UNSIGNED8(31).ADD(3).UNSIGNED8_STRING
<number>.SIGNED16_STRING(<endianness>) Produces a 16-bit signed binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).SKIP(12).GET_SIGNED16(0, BIG_ENDIAN).SUB(4).SIGNED16_STRING(BIG_ENDIAN)
<number>.UNSIGNED16_STRING(<endianness>) Produces a 16-bit unsigned binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).GET_UNSIGNED16(47,
LITTLE_ENDIAN).ADD(7).UNSIGNED16_STRING(LITTLE_ENDIAN)
Example
HTTP.REQ.BODY(100).AFTER_STR("delim").GET_SIGNED32(0,
BIG_ENDIAN).SUB(1).SIGNED32_STRING(BIG_ENDIAN)
<unsigned_long_number>.UNSIGNED8_STRING Produces an 8-bit unsigned binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).GET_UNSIGNED8(24).TYPECAST_UNSIGNED_LONG_AT.ADD(12).UNSIGNED8_STRING
<unsigned_long_number>.UNSIGNED16_STRING(<endianness>) Produces a 16-bit unsigned binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).GET_UNSIGNED16(23,
LITTLE_ENDIAN).TYPECAST_UNSIGNED_LONG_AT.ADD(10).UNSIGNED16_STRING(LITTLE_ENDIAN)
<unsigned_long_number>.UNSIGNED32_STRING(<endianness>) Produces a 32-bit unsigned binary string representing the number. If the value is out of range, an undef condition is
raised.
Example
HTTP.REQ.BODY(100).AFTER_STR("delim2").GET_UNSIGNED32(0,
BIG_ENDIAN).ADD(2).UNSIGNED32_STRING(BIG_ENDIAN)
CONNECTIONS. Returns the number of connections being managed by the virtual server. T he value returned is an
unsigned long number.
Usage: SYS.VSERVER("vserver").CONNECTIONS
STATE. Returns the state of the virtual server. T he value returned is UP, DOWN, or OUT_OF_SERVICE. One of these
values can therefore be passed as an argument to the EQ() operator to perform a comparison that results in a Boolean
TRUE or FALSE.
Usage: SYS.VSERVER("vserver").STATE
HEALTH. Returns the percentage of services in an UP state for the specified virtual server. T he value returned is an
integer.
Usage: SYS.VSERVER("vserver").HEALTH
RESPTIME. Returns the response time as an integer representing the number of microseconds. Response time is the
average T T FB (T ime T o First Byte) from all the services bound to the virtual server.
Usage: SYS.VSERVER("vserver").RESPTIME
SURGECOUNT. Returns the number of requests in the surge queue of the virtual server. T he value returned is an
integer.
Usage: SYS.VSERVER("vserver").SURGECOUNT
Example 1
T he following rewrite policy aborts rewrite processing if the number of connections at the load balancing virtual server
LBvserver exceeds 10000:
Example 2
T he following rewrite action inserts a custom header, TP, whose value is the throughout at the virtual server LBvserver:
Example 3
T he following audit log message action writes the average T T FB of the services bound to a virtual server, to the newnslog
log file:
You can configure expressions to transform the URL encoding and apply HT ML or XML “safe” coding for subsequent
evaluation. You can also use XPAT H and JSON prefixes to evaluate date in XML and JSON files, respectively.
You can also use text-based and numeric Advanced policy expressions to evaluate HT T P request and response data. For
more information, see "Advanced Policy Expressions: Evaluating Text" and "Advanced Policy Expression: Working with Dates,
T imes, and Numbers."
For example, you use the following expression, which includes the http.req.header(“<header_name>“) prefix and the exists
operator, if you want to determine whether an HT T P connection includes a custom header named “myHeader”:
http.req.header("myHeader").exists
You can also combine multiple Advanced policy expressions with Boolean and arithmetic operators. For example, the
following compound expression could be useful with various NetScaler features, such as Integrated Caching, Rewrite, and
Responder. T his expression first uses the && Boolean operator to determine whether an HT T P connection includes the
Content-Type header with a value of "text/html." If that operation returns a value of FALSE, the expression determines
whether the HT T P connection includes a "Transfer-Encoding" or "Content-Length" header.
T he payload of a TCP or UDP packet is the data portion of the packet. You can configure Advanced policy expressions to
examine features of a TCP or UDP packet, including the following:
T he following expression prefixes extract text from the body of the payload:
HT T P.REQ.BODY(integer). Returns the body of an HT T P request as a multiline text object, up to the character position
designated in the integer argument. If there are fewer characters in the body than is specified in the argument, the
entire body is returned.
HT T P.RES.BODY(integer). Returns a portion of the HT T P response body. T he length of the returned text is equal to the
number in the integer argument. If there are fewer characters in the body than is specified in integer, the entire body is
returned.
CLIENT .T CP.PAYLOAD(integer). Returns T CP payload data as a string, starting with the first character in the payload and
continuing for the number of characters in the integer argument.
Following is an example that evaluates to T RUE if a response body of 1024 bytes contains the string “https”, and this string
occurs after the string “start string” and before the string “end string”:
http.res.body(1024).after_str("start_string").before_str("end_string").contains("https")
Note: You can apply any text operation to the payload body. For information on operations that you can apply to text, see
"Advanced Policy Expressions: Evaluating T ext."
CLIENT .IP.PROT OCOL Identifies the protocol in IPv4 packets sent by clients.
CLIENT .IPV6.PROT OCOL Identifies the protocol in IPv6 packets sent by clients.
You can pass the Internet Assigned Numbers Authority (IANA) protocol number to the PROTOCOL function. For example, if
you want to determine whether the protocol in an incoming packet is TCP, you can use CLIENT.IP.PROTOCOL.EQ(6),
where 6 is the IANA-assigned protocol number for TCP. For some protocols, you can pass an enumeration value instead of
the protocol number. For example, instead of CLIENT.IP.PROTOCOL.EQ(6), you can use CLIENT.IP.PROTOCOL.EQ(TCP).
T he following table lists the protocols for which you can use enumeration values, and the corresponding enumeration
values for use with the PROTOCOL function.
IP Authentication Header (AH), for providing authentication services in IPv4 and IPv6 AH
Note
If an operation is used to evaluate both header and text data, the header-based operation always overrides the text-based operation. For
example, the AFT ER_ST R operation, when applied to a header, overrides text-based AFT ER_ST R operations for all instances of the current
header type.
Note that this prefix returns the value from the Host header by default. To use
this value as a hostname you need to typecast it as follows:
http.req.header("host").typecast_http_hostname_t
HTTP.REQ.FULL_HEADER Returns the contents of the complete set of HT T P header fields including the
request line (for example, "GET /brochures/index.html HT T P/1.1") and the
terminating \r\n\r\n sequence.
HTTP.REQ.DATE Returns the contents of the HT T P Date header. T he following date formats
are recognized:
HTTP.RES.FULL_HEADER Returns the contents of the complete set of HT T P header fields including the
status line (for example, "HT T P/1.1 200 OK") and the terminating \r\n\r\n
sequence.
or
HTTP.RES.SET_COOKIE2
HTTP.RES.SET_COOKIE("<name>") Returns the cookie of the specified name if it is present. If it is not present,
returns a text object of length 0. Returns UNDEF if more than 15 Set-Cookie
or
headers are present and the specified cookie was not found in these headers.
HTTP.RES.SET_COOKIE2("<name>")
HTTP.RES.SET_COOKIE("<name>").DOMAIN Returns the value of the first Domain field in the cookie. For example, if the
cookie is Set-Cookie : Customer = "ABC"; DOMAIN=".abc.com";
or
DOMAIN=.xyz.com, the following expression returns .abc.com:
HTTP.RES.SET_COOKIE2("<name>").DOMAIN
http.res.set_cookie.cookie("customer").domain
A string of zero length is returned if the Domain field or its value is absent.
HTTP.RES.SET_COOKIE.EXISTS("<name>") Returns a Boolean T RUE if a Cookie with the name specified in the <name>
argument exists in the Set-Cookie header.
or
T his prefix returns UNDEF if more than 15 Set-Cookie headers are present and
HTTP.RES.SET_COOKIE2.EXISTS("<name>")
the named cookie is not in the first 15 headers.
HTTP.RES.SET_COOKIE.COOKIE(" Returns the Expires field of the cookie. T his is a date string that can be
<name>").EXPIRES evaluated as a number, as a time object, or as text. If multiple Expires fields are
present, the first one is returned. If the Expires field is absent, a text object of
or
length zero is returned.
HTTP.RES.SET_COOKIE2.COOKIE(" To evaluate the returned value as a time object, see "Advanced Policy
<name>").EXPIRES Expressions: Working with Dates, T imes, and Numbers."
HTTP.RES.SET_COOKIE.COOKIE(" Returns the value of Path field of the cookie as a slash- (“/”) separated list.
<name>").PATH|PATH.GET(n) Multiple instances of a slash are treated as single slash. If multiple Path fields
are present, the value of the first instance is returned.
or
http.res.set_cookie.cookie("Customer").path
http.res.set_cookie.cookie("Customer").path.get(2)
Quotes are stripped from the returned value. A string of zero length is returned
if the Path field or its value is absent.
HTTP.RES.SET_COOKIE.COOKIE(" Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89,
<name>").PATH.IGNORE_EMPTY_ELEMENTS the element delimiter in the list is , and the list has an empty element following
a=10. T he element following b=11 is not considered an empty element.
or
As another example, in the following expression, if a request contains
HTTP.RES.SET_COOKIE2.COOKIE("
Cust_Header : 123,,24, ,15 the following expression returns a value of 4:
<name>").PATH.IGNORE_EMPTY_ELEMENTS
http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').count
HTTP.RES.SET_COOKIE.COOKIE(" Returns the value of Port field of the cookie. Operate as a comma-separated
<name>").PORT list.
or For example, the following expression returns 80. 2580 from Set-Cookie :
Customer = "ABC"; PAT H="/a/b/c"; PORT = "80, 2580":
HTTP.RES.SET_COOKIE2.COOKIE("
<name>").PORT http.res.set_cookie.cookie("ABC").port
HTTP.RES.SET_COOKIE.COOKIE(" Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89,
<name>").PORT.IGNORE_EMPTY_ELEMENTS the element delimiter in the list is , and the list has an empty element following
a=10. T he element following b=11 is not considered an empty element.
or
HTTP.RES.SET_COOKIE2.COOKIE(" As another example, in the following expression, if a request contains
<name>").PORT.IGNORE_EMPTY_ELEMENTS Cust_Header : 123,,24, ,15 the following expression returns a value of 4:
http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').count
HTTP.RES.SET_COOKIE.COOKIE(" Returns the value of the first Version field in the cookie as a decimal integer.
<name>").VERSION
For example, the following expression returns 1 from the cookie Set-Cookie :
or Customer = "ABC"; VERSION = "1"; VERSION = "0"
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the nth instance (0-based) of the cookie with the specified name. If
<integer>) the cookie is absent, returns a text object of length 0.
or Returns UNDEF if more than 15 Set-Cookie headers are present and the
cookie is not found.
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
<integer>)
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the value of the Domain field of the first cookie with the specified
<integer>).DOMAIN name. For example, the following expression returns a value of abc.com from
the cookie Set-Cookie : Customer = "ABC"; DOMAIN=".abc.com";
or
DOMAIN=.xyz.com
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
http.res.set_cookie.cookie("CUSTOMER").domain
<integer>).DOMAIN
A string of zero length is returned if the Domain field or its value is absent.
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the nth instance (0-based) of the Expires field of the cookie with the
<integer>).EXPIRES specified name as a date string. T he value can be operated upon as a time
object that supports a number of date formats. If the Expires attribute is
or
absent a string of length zero is returned.
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
<integer>).EXPIRES
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the value of the Path field of the nth cookie, as a '/' separated list.
<integer>).PATH | PATH.GET(i) Multiple /s are treated as a single /.
or For example, the following expression returns /a//b/c from the cookie Set-
T he following returns b:
http.res.set_cookie.cookie("CUSTOMER").path.get(2)
A string of zero length is returned if the Path field or its value is absent.
HTTP.RES.SET_COOKIE.COOKIE("<name>", Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89,
<integer>).PATH.IGNORE_EMPTY_ELEMENTS the element delimiter in the list is , and the list has an empty element following
a=10. T he element following b=11 is not considered an empty element.
or
As another example, in the following expression, if a request contains
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
Cust_Header : 123,,24, ,15 the following expression returns a value of 4:
<integer>).PATH.IGNORE_EMPTY_ELEMENTS
http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').count
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the value or values of the Port field of the named cookie as a ','
<integer>).PORT separated list. For example, the following expression returns 80, 2580 from the
cookie Set-Cookie : Customer = "ABC"; PAT H="/a/b/c"; PORT = "80, 2580"
or
http.res.set_cookie.cookie("ABC").port
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
<integer>).PORT A string of zero length is returned if the Port field or its value is absent.
HTTP.RES.SET_COOKIE.COOKIE("<name>", Ignores the empty elements in the list. For example, in the list a=10,b=11, ,c=89,
<integer>).PORT.IGNORE_EMPTY_ELEMENTS the element delimiter in the list is , and the list has an empty element following
a=10. T he element following b=11 is not considered an empty element.
or
As another example, in the following expression, if a request contains
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
Cust_Header : 123,,24, ,15 the following expression returns a value of 4:
<integer>).PORT.IGNORE_EMPTY_ELEMENTS
http.req.header("Cust_Header").typecast_list_t(',').ignore_empty_elements.count
http.req.header("Cust_Header").typecast_list_t(',').count
HTTP.RES.SET_COOKIE.COOKIE("<name>", Returns the value of Version field of the nth cookie as a decimal integer.
<integer>).VERSION
A string of zero length is returned if the Port field or its value is absent.
or
HTTP.RES.SET_COOKIE2.COOKIE("<name>",
<integer>).VERSION
T he following table describes operations that you can specify with the prefixes for HT T P headers.
http header .EXISTS Returns a Boolean T RUE if an instance of the specified header type exists.
Following is an example:
http.req.header("Cache-Control").exists
http header.CONTAINS" http Returns a Boolean T RUE if the <string> argument appears in any instance of the header value.
header . CONTAINS("
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n
http.res.header("MyHeader"). contains("de")
T he following returns FALSE. Note that the NetScaler does not concatenate the different values.
http.res.header("MyHeader"). contains("bcd")
http header .COUNT Returns the number of headers in a request or response, to a maximum of 15 headers of the same
type. T he result is undefined if there are more than 15 instances of the header.
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n
http.res.header("MyHeader").count
http header.AFTER_STR(" Extracts the text that follows the first occurrence of the <string> argument. T he headers are
<string>") evaluated from the last instance to the first.
MyHeader: 111abc\r\n
Content-Length: 200\r\n
MyHeader: 111def\r\n
\r\n
T he following extracts the string "def " from the last instance of MyHeader. T his is value "111def."
T he following extracts the string "c" from the first instance of MyHeader. T his is the value
"abc111."
http.res.header("MyHeader").after_str("1ab")
http header.BEFORE_STR(" Extracts the text that appears prior to the first occurrence of the input <string> argument. T he
<string>") headers are evaluated from the last instance to the first.
MyHeader: abc111\r\n
Content-Length: 200\r\n
MyHeader: def111\r\n
\r\n
T he following extracts the string "def " from the last instance of MyHeader. T his is the value
"def111."
http.res.header("MyHeader").before_str("111")
T he following extracts the string "a" from the first instance of MyHeader. T his is the value
"abc111."
http.res.header("MyHeader").before_str("bc1")
http An HT T P header can occur multiple times in a request or a response. T his operation returns the
header.INSTANCE(<instance header that occurs <instance number> of places before the final instance. For example,
number>) instance(0) selects the last instance of the current type, instance(1) selects the next-to-last
instance, and so on. T his prefix cannot be used in bidirectional policies.
T he <instance number> argument cannot exceed 14. Following is an example of a request with
two headers:
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n
http.res.header("MyHeader").instance(1)
http header.SUBSTR(" Extracts the text that matches the <string> argument. T he headers are evaluated from the last
<string>") instance to the first. Following is an example of a request with two headers that contain the
MyHeader: abc111\r\n
Content-Length: 200\r\n
MyHeader: 111def\r\n
\r\n
T he following returns "111" from the last instance of MyHeader. T his is the header with the value
"111def."
http.res.header("MyHeader").substr("111")
http An HT T P header can occur multiple times in a request or a response. VALUE(0) selects the value in
header.VALUE(<instance the last instance, VALUE(1) selects the value in the next-to-last instance, and so on. T he <instance
number>) number> argument cannot exceed 14.
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n
http.res.header("MyHeader").value(1)
You can apply any of the operations for HT T P headers to Cache-Control headers. For more information, see "Operations for HT T P
Headers."
In addition, the following operations identify specific types of Cache-Control headers. See RFC 2616 for information about these
Cache-Control Returns as a text value the name of the Cache-Control header that corresponds to the nth
header.NAME(<integer>) component in a name-value list, as specified by <integer>.
T he index of the name-value component is 0-based. If the <integer> that is specified by the
integer argument is greater than the number of components in the list, a zero-length text
object is returned.
Following is an example:
http.req.cache_control.name(3).contains("some_text")
Cache-Control Returns a Boolean T RUE if the Cache-Control header is not present in the request or
header.IS_INVALID response.
Following is an example:
http.req.cache_control.is_invalid
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Private.
header.IS_PRIVATE
Following is an example:
http.req.cache_control.is_private
Cache-Control header.IS_PUBLIC Returns a Boolean T RUE if the Cache-Control header has the value Private.
Following is an example:
http.req.cache_control.is_public
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value No-Store.
header.IS_NO_STORE
Following is an example:
http.req.cache_control.is_no_store
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value No-Cache.
header.IS_NO_CACHE
Following is an example:
http.req.cache_control.is_no_cache
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Max-Age.
header.IS_MAX_AGE
Following is an example:
http.req.cache_control.is_max_age
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Min-Fresh.
header.IS_MIN_FRESH
Following is an example:
http.req.cache_control.is_min_fresh
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Max-Stale.
header.IS_MAX_STALE
Following is an example:
http.req.cache_control.is_max_stale
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Must-Revalidate.
header.IS_MUST_REVALIDATE
Following is an example:
http.req.cache_control.is_must_revalidate
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value No-Transform.
header.IS_NO_TRANSFORM
Following is an example:
http.req.cache_control.is_no_transform
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Only-If-Cached.
header.IS_ONLY_IF_CACHED
Following is an example:
http.req.cache_control.is_only_if_cached
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value Proxy-Revalidate.
header.IS_PROXY_REVALIDATE
Following is an example:
http.req.cache_control.is_proxy_revalidate
Cache-Control Returns a Boolean T RUE if the Cache-Control header has the value S-Maxage.
header.IS_S_MAXAGE
Following is an example:
http.req.cache_control.is_s_maxage
http.req.cache_control.is_unknown
Cache-Control header.MAX_AGE Returns the value of the Cache-Control header Max-Age. If this header is absent or invalid, 0
is returned.
Cache-Control Returns the value of the Cache-Control header Max-Stale. If this header is absent or invalid, 0
header.MAX_STALE is returned.
Following is an example:
http.req.cache_control.max_stale.le(3)
Cache-Control Returns the value of the Cache-Control header Min-Fresh. If this header is absent or invalid, 0
header.MIN_FRESH is returned.
Following is an example:
http.req.cache_control.min_fresh.le(3)
Cache-Control Returns the value of the Cache-Control header S-Maxage. If this header is absent or invalid, 0
header.S_MAXAGE is returned.
Following is an example:
http.req.cache_control.s_maxage.eq(2)
http.req.url.suffix.eq("jpeg") || http.req.url.suffix.eq("gif")
Most expressions for URLs operate on text and are described in "Expression Prefixes for Text in HT T P Requests and
Responses." T his section discusses the GET operation. T he GET operation extracts text when used with the following
prefixes:
HTTP.REQ.URL.PATH
VPN.BASEURL.PATH
VPN.CLIENTLESS_BASEURL.PATH
HTTP.REQ.URL.PATH.GET(<n>) Returns a slash- (“/”) separated list from the URL path. For example,
consider the following URL:
http://www.mycompany.com/dir1/dir2/dir3/index.html?a=1
http.req.url.path.get(1)
http.req.url.path.get(2)
HTTP.REQ.URL.PATH.GET_REVERSE(<n>) Returns a slash- (“/”) separated list from the URL path, starting from
the end of the path. For example, consider the following URL:
http://www.mycompany.com/dir1/dir2/dir3/index.html?a=1
http.req.url.path.get_reverse(0)
http.req.url.path.get_reverse(1)
Following is an example:
Following is an example:
HTTP.RES.IS_REDIRECT Returns a Boolean TRUE if the response code is associated with a redirect.
Following are the redirect response codes:
300 (Multiple Choices)
301 (Moved Permanently)
302 (Found)
303 (See Other)
305 (Use Proxy)
307 (T emporary Redirect)
Note: Status code 304 is not considered a redirect HT T P response status code.
Status code 306 is unused.
In the following example, the rewrite action replaces http in the Location header of
an HT T P response with https if the response is associated with an HT T P redirect.
T he NetScaler Advanced policy expressions language contains a number of expressions that operate on Session Initiation Protocol (SIP)
connections. T hese expressions are intended to be used in policies for any supported protocol that operates on a request/response basis.
T hese expressions can be used in content switching, rate limiting, responder, and rewrite policies.
Certain limitations apply to SIP expressions used with responder policies. Only the DROP, NOOP or RESPONDWIT H actions are allowed on a
SIP load balancing virtual server. Responder policies can be bound to a load balancing virtual server, an override global bind point, a default
global bind point, or a sip_udp policy label.
T he header format used by the SIP protocol is similar to that used by the HT T P protocol, so many of the new expressions look and function
much like their HT T P analogs. Each SIP header consists of a line that includes the SIP method, the URL, and the version, followed by a series
of name-value pairs that look like HT T P headers.
Following is a sample SIP header that is referred to in the expressions tables beneath it:
T he following tables contain lists of expressions that operate on SIP headers. T he first table contains expressions that apply to request
headers. Most response-based expressions are nearly the same as the corresponding request-based expressions. To create a response
expression from the corresponding request expression, you change the first two sections of the expression from SIP.REQ to SIP.RES, and
make other obvious adjustments. T he second table contains those response expressions that are unique to responses and have no request
equivalents. You can use any element in the following tables as a complete expression on its own, or you can use various operators to
combine these expression elements with others to form more complex expressions.
SIP.REQ.METHOD Operates on the method of the SIP request. T he supported SIP request methods
are ACK, BYE, CANCEL, INFO, INVIT E, MESSAGE, NOT IFY, OPT IONS, PRACK,
PUBLISH, REFER, REGIST ER, SUBSCRIBE, and UPDAT E. T his expression is a derivative
of the text class, so all operations that are applicable to text are applicable to this
SIP.REQ.URL Operates on the SIP request URL. T his expression is a derivative of the text class, so
all operations that are applicable to text are applicable to this method. For example,
for a SIP request of INVITE sip:16@10.102.84.181:5060;transport=udp SIP/2.0, this
expression returns sip:16@10.102.84.181:5060;transport=udp.
SIP.REQ.URL.PROTOCOL Returns the URL protocol. For example, for a SIP URL of
sip:16@www.sip.com:5060;transport=udp, this expression returns sip.
SIP.REQ.URL.HOSTNAME Returns the hostname portion of the SIP URL. For example, for a SIP URL of
sip:16@www.sip.com:5060;transport=udp, this expression returns www.sip.com:5060.
SIP.REQ.URL.HOSTNAME.PORT Returns the port portion of the SIP URL hostname. If no port is specified, this
expression returns the default SIP port, 5060. For example, for a SIP hostname of
www.sip.com:5060, this expression returns 5060.
SIP.REQ.URL.HOSTNAME.DOMAIN Returns the domain name portion of the SIP URL hostname. If the host is an IP
address, then this expression returns an incorrect result. For example, for a SIP
hostname of www.sip.com:5060, this expression returns sip.com. For a SIP
hostname of 192.168.43.15:5060, this expression returns an error.
SIP.REQ.URL.HOSTNAME.SERVER Returns the server portion of the host. For example, for a SIP hostname of
www.sip.com:5060, this expression returns www.
SIP.REQ.URL.USERNAME Returns the username that precedes the @ character. For example, for a SIP URL of
sip:16@www.sip.com:5060;transport=udp, this expression returns 16.
SIP.REQ.VERSION Returns the SIP version number in the request. For example, for a SIP request of
INVITE sip:16@10.102.84.181:5060;transport=udp SIP/2.0, this expression returns
SIP/2.0.
SIP.REQ.VERSION.MAJOR Returns the major version number (the number to the left of the period). For
example, for a SIP version number of SIP/2.0, this expression returns 2.
SIP.REQ.VERSION.MINOR Returns the minor version number (the number to the right of the period). For
example, for a SIP version number of SIP/2.0, this expression returns 0.
SIP.REQ.CONTENT_LENGTH Returns the contents of the Content-Length header. T his expression is a derivative
of the sip_header_t class, so all operations that are available for SIP headers can be
used. For example, for a SIP Content-Length header of Content-Length: 277, this
expression returns 277.
SIP.REQ.TO Returns the contents of the To header. For example, for a SIP To header of To: "16"
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185, this
expression returns "16"
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185.
SIP.REQ.TO.DISPLAY_NAME Returns the display name portion of the To header. For example, for a SIP To header
of To: "16" <sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185,
this expression returns 16.
SIP.REQ.TO.TAG Returns the “tag” vale from the “tag” name value pair in the TO header. For example,
for a SIP To header of To: "16"
<sip:16@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185, this
expression returns 00127f54ec85a6d90cc14f45-53cc0185.
SIP.REQ.FROM Returns the contents of the From header. For example, for a SIP From header of
From: "12" <sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185,
this expression returns sip:12@sip_example.com.
SIP.REQ.FROM.ADDRESS Returns the SIP URI, which is found in the sip_url object. All operations that are
available for SIP URIs can be used. For example, for a SIP From header of From: "12"
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185, this
expression returns sip:12@sip_example.com.
SIP.REQ.FROM.DISPLAY_NAME Returns the display name portion of the To header. For example, for a SIP From
header of From: "12" <sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-
53cc0185, this expression returns 12.
SIP.REQ.FROM.TAG Returns the “tag” value from the “tag” name/value pair in the TO header. For
example, for a SIP From header of From: "12"
<sip:12@sip_example.com>;tag=00127f54ec85a6d90cc14f45-53cc0185, this
expression returns 00127f54ec85a6d90cc14f45-53cc0185.
SIP.REQ.VIA Returns the complete Via header. If there are multiple Via headers in the request,
returns the last Via header. For example, for the two Via headers in the sample SIP
header, this expression returns Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160.
SIP.REQ.VIA.SENTBY_ADDRESS Returns the address that sent the request. For example, for the Via header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
this expression returns 10.102.84.180.
SIP.REQ.VIA.SENTBY_PORT Returns the port that sent the request. For example, for the Via header Via:
SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
this expression returns 5060.
SIP.REQ.VIA.BRANCH Returns the value from the branch name/value pair. For example, for the Via header
Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
this expression returns z9hG4bK03e76d0b.
SIP.REQ.VIA.RECEIVED Returns the value from the received name/value pair. For example, for the Via header
Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
this expression returns 10.102.84.160.
SIP.REQ.CALLID Returns the contents of the Callid header. T his expression is a derivative of the
sip_header_t class, so all operations that are available for SIP headers can be used.
For example, for a SIP Callid header of Call-ID: 00127f54-ec850017-0e46f5b9-
5ec149c2@10.102.84.180, this expression returns 00127f54-ec850017-0e46f5b9-
5ec149c2@10.102.84.180.
SIP.REQ.CSEQ Returns the CSEQ number from the CSEQ, as an integer. For example, for a SIP
CSEQ header of CSeq: 101 INVITE, this expression returns 101.
SIP.REQ.HEADER("<header_name>") Returns the specified SIP header. For <header_name>, substitute the name of the
header that you want. For example, to return the SIP From header, you would type
SIP.REQ.HEADER("From").
SIP.REQ.HEADER(" Returns the specified instance of the specified SIP header. Multiple instances of the
<header_name>").INSTANCE(<line_number>) same SIP header can occur. Where you want a specific instance of such a SIP
header (for example, a specific Via header), you can specify that header by typing a
number as the <line_number>. Header instances are matched from last (0) to first. In
other words, SIP.REQ.HEADER("Via").INSTANCE(0) returns the last instance of
the Via header, while SIP.REQ.HEADER("Via").INSTANCE(1) returns the last
instance but one of the Via header, and so on.
SIP.REQ.HEADER(" Returns the contents of the specified instance of the specified SIP header. T he
<header_name>").VALUE(<line_number>) usage is nearly the same as the previous expression. For example, if used on the SIP
header example in the preceding table entry, SIP.REQ.HEADER(“Via”).VALUE(1)
returns SIP/2.0/UDP 10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060.
SIP.REQ.HEADER("<header_name>").COUNT Returns the number of instances of a particular header as an integer. For example, if
used on the SIP header example above, SIP.REQ.HEADER(“Via”).COUNT returns 2.
SIP.REQ.HEADER("<header_name>").EXISTS Returns a boolean value of true or false, depending upon whether the specified
header exists or not. For example, if used on the SIP header example above,
SIP.REQ.HEADER("<header_name>").LIST Returns the comma-separated parameter list in the specified header. For example, if
used on the SIP header example above, SIP.REQ.HEADER(“Allow”).LIST returns
ACK,BYE,CANCEL,INVIT E,NOT IFY,OPT IONS,REFER,REGIST ER,UPDAT E.
You can append the string .GET (<list_item_number>) to select a specific list item. For
example, to get the first item (ACK) from the above list, you would type
SIP.REQ.HEADER(“Allow”).LIST.GET (0). To extract the second item (BYE), you would
type SIP.REQ.HEADER(“Allow”).LIST.GET (1).
Note: If the specified header contains a list of name/value pairs, the entire
name/value pair is returned.
SIP.REQ.HEADER(" Returns boolean true if the specified text string is present in any instance of the
<header_name>").CONTAINS("<string>"). specified header. Operates on all the instances of the specified header. Header
instances are matched from last (0) to first.
SIP.REQ.HEADER(" Returns boolean true if any pattern associated with <patset> matches any content
<header_name>").EQUALS_ANY(<patset>) in any instance of the specified header. Operates on all the instances of the
specified header. Header instances are matched from last (0) to first.
SIP.REQ.HEADER(" Returns Boolean true if any pattern associated with <patset> matches any content
<header_name>").CONTAINS_ANY(<patset>) in any instance of the specified header. Operates on all the instances of the
specified header. Header instances are matched from last (0) to first.
SIP.REQ.HEADER(" Returns the index of the matching pattern associated with <patset> if that pattern
<header_name>").CONTAINS_INDEX(<patset>) matches any content in any instance of the specified header. Operates on all the
instances of the specified header. Header instances are matched from last (0) to
first.
SIP.REQ.HEADER(" Returns the index of the matching pattern associated with <patset> if that pattern
<header_name>").EQUALS_INDEX(<patset>) matches any instance of the specified header. Operates on all the instances of the
specified header. Header instances are matched from last (0) to first.
SIP.REQ.HEADER("<header_name>").SUBSTR(" If the specified string is present in any instance of the specified header, this
<string>") expression returns that string. For example, for the SIP header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160”,
SIP.REQ.HEADER("Via").SUBSTR("rport=5060") returns “rport=5060”.
SIP.REQ.HEADER("Via").SUBSTR("rport=5061") returns an empty string.
SIP.REQ.HEADER(" Returns boolean true if the specified regular expression (regex) matches any
<header_name>").REGEX_MATCH(<regex>) instance of the specified header. You must specify the regular expression in the
following format:
SIP.REQ.HEADER(" If the specified regex matches any text in any instance of the specified header, this
<header_name>").REGEX_SELECT(<regex>) expression returns the text. For example, for the SIP header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
the expression SIP.REQ.HEADER("Via").REGEX_SELECT("received=[0-9]{1,3}\.[0-
9]{1,3}\.[0-9]{1,3}\.[0-9]{1,3}") returns received=10.102.84.160.
SIP.REQ.HEADER(" If the specified regex matches any text in any instance of the specified header, this
<header_name>").AFTER_REGEX(<regex>) expression returns the string immediately after that text. For example, for the SIP
header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
the expression SIP.REQ.HEADER("Via").AFTER_REGEX("received=") returns
10.102.84.160.
SIP.REQ.HEADER(" If the specified regex matches any text in any instance of the specified header, this
<header_name>").BEFORE_REGEX(<regex>) expression returns the string immediately before that text. For example, for the SIP
header Via: SIP/2.0/UDP
10.102.84.180:5060;branch=z9hG4bK03e76d0b;rport=5060;received=10.102.84.160,
the expression SIP.REQ.HEADER("Via").BEFORE_REGEX("[0-9]{1,3}\.[0-9]{1,3}\.[0-
9]{1,3}\.[0-9]{1,3}") returns received=.
SIP.REQ.FULL_HEADER Returns the entire SIP header, including the terminating CR/LF.
SIP.REQ.BODY(<length>) Returns the request body, up to the specified length. If the specified length is
greater than the length of the request body, this expression returns the entire
request body.
SIP.REQ.CS_VSERVER Returns the name of the content switching virtual server (CS vserver) that is serving
the current request.
SIP.RES.STATUS Returns the SIP response status code. For example, if the first line of the response is SIP/2.0 100 Trying, this
expression returns 100.
SIP.RES.STATUS_MSG Returns the SIP response status message. For example, if the first line of the response is SIP/2.0 100 Trying,
this expression returns Trying.
SIP.RES.METHOD Returns the response method extracted from the request method string in the CSeq header.
http.req.url.query.html_xml_safe.
contains("myQueryString")
<text>.HTTP_HEADER_SAFE Converts all new line ('\n') characters in the input text to
'%0A' to enable the input to be used safely in HT T P
headers.
http.req.url.hostname.prefix(3)
http.req.url.hostname.set_text_mode(urlencoded).prefix(3)
For expression prefixes that return numeric value, such as a source port, you can apply an arithmetic operation. For more
information, see "Basic Operations on Expression Prefixes" and "Compound Operations for Numbers."
T he following table describes prefixes that extract TCP and UDP data.
CLIENT.TCP.PAYLOAD(<integer>) Returns TCP payload data as a string, starting with the first character in
the payload and continuing for the number of characters in the
<integer> argument.
CLIENT.TCP.OPTIONS Returns the TCP options set by the client. Examples of TCP options are
Maximum Segment Size (MSS), Window Scale, Selective
Acknowledgements (SACK), and T ime Stamp Option. T he COUNT,
TYPE(<type>), and TYPE_NAME(<m>) operators can be used with this
prefix. For the TCP options set by the server, see the
SERVER.TCP.OPTIONS prefix.
CLIENT.TCP.OPTIONS.COUNT Returns the number of TCP options that the client has set.
CLIENT.TCP.OPTIONS.TYPE(<type>) Returns the value of the TCP option whose type (or option kind) is
specified as the argument. T he value is returned as a string of bytes in
big endian format (or network byte order).
Paramet ers:
CLIENT.TCP.OPTIONS.TYPE_NAME(<m>) Returns the value of the TCP option whose enumeration constant is
specified as the argument. T he enumeration constants that you can
Paramet ers:
CLIENT.TCP.REPEATER_OPTION.IP Returns the branch repeater's IPv4 address from the Repeater TCP
options.
CLIENT.TCP.REPEATER_OPTION.MAC Returns the branch repeater's MAC address from the Repeater TCP
options.
CLIENT.UDP.DNS.DOMAIN.EQ(" Returns a Boolean T RUE if the domain name matches the <hostname>
<hostname>") argument. T he comparison is case insensitive.
Following is an example:
client.udp.dns.domain.eq("www.mycompany.com")
CLIENT.UDP.DNS.IS_AAAAREC Returns a Boolean T RUE if the record type is AAAA. T hese types of
records indicate an IPv6 address in forward lookups.
CLIENT.UDP.DNS.IS_AREC Returns a Boolean T RUE if the record is type A. Type A records provide
the host address.
CLIENT.UDP.DNS.IS_NSREC Returns a Boolean T RUE if the record is of type NS. T his is a name
server record that includes a host name with an associated A record.
T his enables locating the domain name that is associated with the NS
record.
CLIENT.UDP.DNS.IS_SOAREC Returns a Boolean T RUE if the record is of type SOA. T his is a start of
authority record.
CLIENT.UDP.DNS.IS_SRVREC Returns a Boolean T RUE if the record is of type SRV. T his is a more
general version of the MX record.
CLIENT.UDP.DSTPORT Returns the numeric ID of the current packet's UDP destination port.
CLIENT.UDP.SRCPORT Returns the numeric ID of the current packet's UDP source port.
CLIENT.UDP.RADIUS.ATTR_TYPE(<type>) Returns the value for the attribute type specified as the argument.
CLIENT.TCP.MSS Returns the maximum segment size (MSS) for the current connection
as a number.
CLIENT.VLAN.ID Returns the numeric ID of the VLAN through which the current packet
entered the NetScaler.
SERVER.TCP.OPTIONS Returns the TCP options set by the server. Examples of TCP options are
Maximum Segment Size (MSS), Window Scale, Selective
Acknowledgements (SACK), and T ime Stamp Option. T he COUNT,
TYPE(<type>), and TYPE_NAME(<m>) operators can be used with this
SERVER.TCP.OPTIONS.COUNT Returns the number of TCP options that the server has set.
SERVER.TCP.OPTIONS.TYPE(<type>) Returns the value of the TCP option whose type (or option kind) is
specified as the argument. T he value is returned as a string of bytes in
big endian format (or network byte order).
Paramet ers:
SERVER.TCP.OPTIONS.TYPE_NAME(<m>) Returns the value of the TCP option whose enumeration constant is
specified as the argument. T he enumeration constants that you can
pass as the argument are REPEAT ER, T IMESTAMP, SACK_PERMIT T ED,
WINDOW, and MAXSEG. To specify the TCP option kind instead of
these enumeration constants, use
CLIENT.TCP.OPTIONS.TYPE(<type>). For other TCP options, you
must use CLIENT.TCP.OPTIONS.TYPE(<type>).
Paramet ers:
SERVER.VLAN Operates on the VLAN through which the current packet entered the
NetScaler.
SERVER.VLAN.ID Returns the numeric ID of the VLAN through which the current packet
entered the NetScaler.
T able 1. F unct ions t hat ret urn t he cont ent s of a DNS query
DNS.REQ.QUESTION.DOMAIN Return the domain name (the value of the QNAME field) in the question section of
the DNS query. T he domain name is returned as a text string, which can be passed to
EQ(), NE(), and any other functions that work with text.
DNS.REQ.QUESTION.TYPE Return the query type (the value of the QTYPE field) in the DNS query. T he field
indicates the type of resource record (for example, A, NS, or CNAME) for which the
name server is being queried. T he returned value can be compared to one of the
following values by using the EQ() and NE() functions:
A
AAAA
NS
SRV
PT R
CNAME
SOA
MX
ANY
Note: You can use only the EQ() and NE() functions with the TYPE function.
Example:
DNS.REQ.QUESTION.TYPE.EQ(MX)
T able 2. F unct ions t hat ret urn t he cont ent s of a DNS response
DNS.RES.HEADER.RCODE Return the response code (the value of the RCODE field) in the header section of
the DNS response. You can use only the EQ() and NE() functions with the RCODE
DNS.RES.QUESTION.DOMAIN Return the domain name (the value of the QNAME field) in the question section of
the DNS response. T he domain name is returned as a text string, which can be
passed to EQ(), NE(), and any other functions that work with text.
DNS.RES.QUESTION.TYPE Return the query type (the value of the QTYPE field) in the question section of the
DNS response. T he field indicates the type of resource record (for example, A, NS, or
CNAME) that is contained in the response. T he returned value can be compared to
one of the following values by using the EQ() and NE() functions:
A
AAAA
NS
SRV
PT R
CNAME
SOA
MX
ANY
You can use only the EQ() and NE() functions with the TYPE function.
Example:
DNS.RES.QUESTION.TYPE.EQ(SOA)
T able 3. F unct ions t hat ret urn t he t ransport layer prot ocol name
DNS.REQ.TRANSPORT Return the name of the transport layer protocol that was used to send the DNS query.
Possible values returned are TCP and UDP. You can use only the EQ() and NE() functions
with the T RANSPORT function.
Example:
DNS.REQ.TRANSPORT.EQ(TCP)
DNS.RES.TRANSPORT Return the name of the transport layer protocol that was used for the DNS response.
Example:
DNS.RES.TRANSPORT.EQ(TCP)
T he Advanced policy expression implementation for XPath comprises an Advanced policy expression prefix (such as
“HTTP.REQ.BODY”) that designates HT ML or XML text, and the XPAT H operator that takes the XPath expression as its argument.
HT ML files are a largely free-form collection of tags and text elements. You can use the XPAT H_HT ML operator, which takes an
XPath expression as its argument, to process HT ML files. JSON files are either a collection of name/value pairs or an ordered list of
values. You can use the XPAT H_JSON operator, which takes an XPath expression as its argument, to process JSON files.
T able 1. XP at h and JSON Expression P ref ixes T hat Ret urn T ext
For example, the following expression returns a Boolean T RUE if a node called
“creator” exists under the node “Book” within the first 1000 bytes of the XML
file.
HTTP.REQ.BODY(1000).XPATH(xp%boolean(//Book/creator)%)
Parameters:
<text>.XPATH(xpathex) Operate on an XML file and return a value of data type “double.”
For example, the following expression converts the string “36” (a price value) to
a value of data type “double” if the string is in the first 1000 bytes of the XML
file:
HTTP.REQ.BODY(1000).XPATH(xp%number(/Book/price)%)
Parameters:
<text>.XPATH(xpathex) Operate on an XML file and return a node-set or a string. Node-sets are
converted to corresponding strings by using the standard XPath string
conversion routine.
For example, the following expression selects all the nodes that are enclosed
by “/Book/creator” (a node-set) in the first 1000 bytes of the body:
HTTP.REQ.BODY(1000).XPATH(xp%/Book/creator%)
Parameters:
HTTP.REQ.BODY(1000).XPATH_HTML(xp%/html/head/title%)
Parameters:
<text>.XPATH_HTML_WITH_MARKUP(xpathex) Operate on an HT ML file and return a string that contains the entire selected
portion of the document, including markup such as including the enclosing
element tags.
HTTP.REQ.BODY(1000).XPATH_HTML_WITH_MARKUP(
xp%/html/head/title%)
Parameters:
HTTP.REQ.BODY(1000).XPATH_JSON(xp%boolean(/Book/creator)%)
Parameters:
<text>.XPATH_JSON(xpathex) Operate on a JSON file and return a value of data type “double.”
HTTP.REQ.BODY(1000).XPATH_JSON(xp%number(/Book/price)%)
Parameters:
<text>.XPATH_JSON(xpathex) Operate on a JSON file and return a node-set or a string. Node-sets are
converted to corresponding strings by using the standard XPath string
conversion routine.
T he following expression selects all the nodes that are enclosed by “/Book" (a
node-set) in the first 1000 bytes of the body of the JSON file and returns the
corresponding string value, which is "<name><title>":
HTTP.REQ.BODY(1000).XPATH_JSON(xp%/Book%)
Parameters:
<text>.XPATH_JSON_WITH_MARKUP(xpathex) Operate on an XML file and return a string that contains the entire portion of
the document for the result node, including markup such as including the
enclosing element tags.
T he following expression operates on the JSON file and selects all the nodes
that are enclosed by “/Book/creator" in the first 1000 bytes of the body,
which is “creator:{ person:{ name:'<name>' } }.”
HTTP.REQ.BODY(1000).XPATH_JSON_WITH_MARKUP(xp%/Book/creator%)
T he portion of the JSON body that is selected by the expression is marked for
further processing.
Parameters:
<text>.XPATH_WITH_MARKUP(xpathex) Operate on an XML file and return a string that contains the entire portion of
the document for the result node, including markup such as including the
enclosing element tags.
For example, the following expression operates on an XML file and selects all
the nodes enclosed by “/Book/creator" in the first 1000 bytes of the body.
Parameters:
Note: If you want to encrypt and decrypt text in a payload, you must use the ENCRYPT and DECRYPT functions. For
more information about these functions, see "Encrypting and Decrypting T ext."
T he XML_ENCRYPT() and XML_DECRYPT() functions are not dependent on the encryption/decryption service that is
used by the ENCRYPT and DECRYPT commands for text. T he cipher method is specified explicitly as an argument to the
XML_ENCRYPT() function. T he XML_DECRYPT() function obtains the information about the specified cipher method
from the <xenc:EncryptedData> element. Following are synopses of the XML encryption and decryption functions:
XML_ENCRYPT(<certKeyName>, <method> [, <flags>]). Returns an <xenc:EncryptedData> element that contains the
encrypted input text and the encryption key, which is itself encrypted by using RSA.
XML_DECRYPT(<certKeyName>). Returns the decrypted text from the input <xenc:EncryptedData> element, which
includes the cipher method and the RSA-encrypted key.
met hod
Specifies which cipher method to use for encrypting the XML data. Possible values: RC4, DES3, AES128, AES192, AES256.
f lags
A bitmask specifying the following optional key information (<ds:KeyInfo>) to be included in the <xenc:EncryptedData>
element that is generated by XML_ENCRYPT():
1 - Include a KeyName element with the certKeyName. T he element is <ds:KeyName>.
2 - Include a KeyValue element with the RSA public key from the certificate. T he element is <ds:KeyValue>.
4 - Include an X509IssuerSerial element with the certificate serial number and issuer DN. T he element is
<ds:X509IssuserSerial>.
8 - Include an X509SubjectName element with the certificate subject DN. T he element is <ds:X509SubjectName>.
XML_ENCRYPT() XML_DECRYPT()
T he XML encryption feature uses SSL certificate-key pairs to provide X.509 certificates (with RSA public keys) for key
encryption and RSA private keys for key decryption. T herefore, before you use the XML_ENCRYPT() function in an
expression, you must create an SSL certificate-key pair. T he following command creates an SSL certificate-key pair, my-
add ssl certKey my-certkey -cert my-cert.pem -key my-key.pem -passcrypt kxPeMRYnitY=
T he following CLI commands create rewrite actions and policies for encrypting and decrypting XML content.
In the above example, the rewrite action my-xml-encrypt-action encrypts the entire XML document (
XPATH_WITH_MARKUP(xp%/%)) in the request by using the AES-256 bulk encryption method and the RSA public key from
my-certkey to encrypt the bulk encryption key. T he action replaces the document with an <xenc:EncryptedData> element
containing the encrypted data and an encrypted key. T he flags represented by 31 include all of the optional <ds:KeyInfo>
elements.
T he my-xml-decrypt-action action uses the RSA private key in my-certkey to decrypt the encrypted key and then uses the
bulk encryption method specified in the element to decrypt the encrypted contents. Finally, the action replaces the
encrypted data element with the decrypted content.
T he rewrite policy my-xml-encrypt-policy applies my-xml-encrypt-action to requests for URLs containing xml-encrypt. T he
action encrypts the entire response from a service configured on the NetScaler appliance.
You can examine both SSL connections and data in client certificates. For example, you may want to send SSL requests that use low-strength ciphers to a particular load balancing virtual server farm.
T he following command is an example of a Content Switching policy that parses the cipher strength in a request and matches cipher strengths that are less than or equal to 40:
As another example, you can configure a policy that determines whether a request contains a client certificate:
Or, you might want to configure a policy that examines particular information in a client certificate. For example, the following policy verifies that the certificate has one or more days before
expiration:
Note: For information on parsing dates and times in a certificate, see "Format of Dates and T imes in an Expression" and "Expressions for SSL Certificate Dates."
T his document includes the following details:
Prefixes for T ext-Based SSL and Certificate Data
Prefixes for Numeric Data in SSL Certificates
Expressions for SSL Certificates
T he following table describes expression prefixes that identify text-based items in SSL transactions and client certificates.
T able 1. P ref ixes T hat Ret urn T ext or Boolean Values f or SSL and Client Cert if icat e Dat a
CLIENT.SSL.CLIENT_CERT Returns the SSL client certificate in the current SSL transaction.
CLIENT.SSL.CIPHER_EXPORTABLE Returns a Boolean T RUE if the SSL cryptographic SSL cryptographic cipher is exportable.
CLIENT.SSL.CIPHER_NAME Returns the name of the SSL Cipher if invoked from an SSL connection, and a NULL string if invoked from a non-SSL connection.
Updated: 2015-06-17
T he following table describes prefixes that evaluate numeric data other than dates in SSL certificates. T hese prefixes can be used with the operations that are described in "Basic Operations on
Expression Prefixes" and "Compound Operations for Numbers."
T able 2. P ref ixes T hat Evaluat e Numeric Dat a Ot her T han Dat es in SSL Cert if icat es
CLIENT.SSL.CLIENT_CERT.DAYS_TO_EXPIRE Returns the number of days that the certificate is valid, or returns -1 for expired certificates.
CLIENT.SSL.CLIENT_CERT.PK_SIZE Returns the size of the public key used in the certificate.
CLIENT.SSL.CLIENT_CERT.VERSION Returns the version number of the certificate. If the connection is not SSL-based, returns zero (0).
CLIENT.SSL.CIPHER_BITS Returns the number of bits in the cryptograhic key. Returns 0 if the connection is not SSL-based.
CLIENT.SSL.VERSION Returns a number that represents the SSL protocol version, as follows:
Updated: 2013-09-02
You can parse SSL certificates by configuring expressions that use the following prefix:
CLIENT.SSL.CLIENT_CERT
T his section discusses the expressions that you can configure for certificates, with the exception of expressions that examine certificate expiration. T ime-based operations are described in "Default
Syntax Expressions: Working with Dates, T imes, and Numbers."
T he following table describes operations that you can specify for the CLIENT.SSL.CLIENT_CERT prefix.
T able 3. Operat ions T hat Can Be Specif ied wit h t he CLIENT .SSL.CLIENT _CERT P ref ix
<certificate>.ISSUER Returns the Distinguished Name (DN) of the Issuer in the certificate as a name-value list. An equals sign (“=”) is the
delimiter for the name and the value, and the slash (“/”) is the delimiter that separates the name-value pairs.
/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com
<certificate>.ISSUER. IGNORE_EMPTY_ELEMENTS Returns the Issuer and ignores the empty elements in a name-value list. For example, consider the following:
T he following Rewrite action returns a count of 6 based on the preceding Issuer definition:
Name: insert_ssl
Value:CLIENT.SSL.CLIENT_CERT.ISSUER.COUNT
However, if you change the value to the following, the returned count is 9:
CLIENT.SSL.CLIENT_CERT.ISSUER.IGNORE_EMPTY_ELEMENTS.COUNT
<certificate>.AUTH_KEYID Returns a string that contains the Authority Key Identifier extension of the X.509 V3 certificate.
<certificate>.AUTH_KEYID.CERT_SERIALNUMBER Returns the SerialNumber field of the Authority Key Identifier as a blob.
<certificate>.AUTH_KEYID.EXISTS Returns a Boolean T RUE if the certificate contains an Authority Key Identifier extension.
<certificate>.AUTH_KEYID.ISSUER_NAME Returns the Issuer Distinguished Name in the certificate as a name-value list. An equals sign (“=”) is the delimiter for the
name and the value, and the slash (“/”) is the delimiter that separates the name-value pairs.
Following is an example:
/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com
<certificate>.AUTH_KEYID.ISSUER_NAME.IGNORE_EMPTY_ELEMENTS Returns the Issuer Distinguished Name in the certificate as a name-value list and ignores the empty elements in the list.
For example, the following name-value list has an empty element following “a=10”:
a=10;;b=11; ;c=89
<certificate>.AUTH_KEYID.KEYID Returns the keyIdentifier field of the Authority Key Identifier as a blob.
<certificate>.CERT_POLICY Returns a string that contains the client certificate policy. Note that this represents a sequence of certificate policies.
<certificate>.KEY_USAGE(string) Returns a Boolean value to indicate whether the specified key usage extension bit value in the
X.509 certificate is set. T he string argument specifies which bit is checked. Following are valid arguments:
DIGITAL_SIGNATURE. Returns T RUE if the digital signature bit is set; otherwise, it returns FALSE.
NONREPUDIATION. Returns T RUE if the nonrepudiation bit is set; otherwise, it returns FALSE.
KEYENCIPHERMENT. Returns T RUE if the key encipherment bit is set; otherwise, it returns FALSE.
<certificate>.PK_ALGORITHM Returns the name of the public key algorithm used by the certificate.
<certificate>.PK_SIZE Returns the size of the public key used in the certificate.
<certificate>.SERIALNUMBER Returns the serial number of the client certificate. If this is a non-SSL transaction or there is an error in the certificate,
this operation returns an empty string.
<certificate>.SIGNATURE_ALGORITHM Returns the name of the cryptographic algorithm used by the CA to sign this certificate.
<certificate>.SUBJECT Returns the Distinguished Name of the Subject as a name-value. An equals sign (“=”) separates names and values and a
slash (“/”) delimits name-value pairs.
Following is an example:
/C=US/O=myCompany/OU=www.mycompany.com/CN=www.mycompany.com/emailAddress=myuserid@mycompany.com
<certificate>.SUBJECT.IGNORE_EMPTY_ELEMENTS Returns the Subject as a name-value list, but ignores the empty elements in the list. For example, consider the following:
T he following Rewrite action returns a count of 6 based on the preceding Issuer definition:
Name: insert_ssl
Value:CLIENT.SSL.CLIENT_CERT.ISSUER.COUNT
However, if you change the value to the following, the returned count is 9:
CLIENT.SSL.CLIENT_CERT.ISSUER.IGNORE_EMPTY_ELEMENTS.COUNT
<certificate>.SUBJECT_KEYID Returns the Subject KeyID of the client certificate. If there is no Subject KeyID, this operation returns a zero-length text
object.
Updated: 2013-09-02
You can use Advanced policy expressions to evaluate addresses and subnets that are in Internet Protocol version 4 (IPv4) or Internet Protocol version 6
(IPv6) format. Expression prefixes for IPv6 addresses and subnets include IPv6 in the prefix. Expression prefixes for IPv4 addresses and subnets include IP
in the prefix. Following is an example of an expression that identifies whether a request has originated from a particular IPv4 subnet.
client.ip.src.in_subnet(147.1.0.0/16)
Following are two examples of Rewrite policies that examine the subnet from which the packet is received and perform a rewrite action on the Host
header. With these two policies configured, the rewrite action that is performed depends on the subnet in the request. T hese two policies evaluate IP
addresses that are in the IPv4 address format.
T he following table describes prefixes that return IPv4 addresses and subnets, and segments of IPv4 addresses. You can use numeric operators and
operators that are specific to IPv4 addresses with these prefixes. For more information about numeric operations, see "Basic Operations on Expression
Prefixes" and "Compound Operations for Numbers."
<ip address>.EQ(<address>) Returns a Boolean T RUE if the IP address value is same as the <address> argument. T he following
example checks whether the client's destination IP address is equal to 10.100.10.100:
client.ip.dst.eq(10.100.10.100)
<ip address>.GET1. . .GET4 Returns a portion of an IP address as a numeric value. For example, if the IP address value is
10.100.200.1, the following is returned:
client.ip.src.get1 Returns 10
<ip address>.IN_SUBNET(<subnet>) Returns a Boolean T RUE if the <subnet> argument matches the subnet of the IP address value. For
example, the following determines whether the client's destination IP address subnet is
10.100.10.100/18:
client.ip.dst.eq(10.100.10.100/18)
<ip address>.SUBNET(<n>) Returns the IP address after applying the subnet mask specified as the argument. T he subnet mask
can take values between 0 and 32.
For example:
<ip address>.IS_IPV6 Returns a Boolean T RUE if this is an Internet Protocol version 6 (IPv6) host for the client or server.
Following is an example:
client.ip.src.is_ipv6
<ip address>.MATCHES(<hostname>) Returns a Boolean T RUE if the IP address for the host specified in <hostname> matches the current
IP address. T he <hostname> cannot exceed 255 characters.
<ip Returns a Boolean T RUE if the location of the IP address matches the <location> argument. T he
address>.MATCHES_LOCATION(<location>) Location string can take the following form: qual1.qual2.qual3.qual4.qual5.qual6,
Following is an example:
client.ip.src.matches_location(\"Europe.GB.17.London.*.*\")
Example 1:
9901:0ab1:22a2:88a3:3333:4a4b:5555:6666
Example 2:
http://[9901:0ab1:22a2:88a3:3333:4a4b:5555:6666]/
Note that you can only use the '+' operator to combine IPv6 expressions with other expressions. T he output is a concatenation of the string values that
are returned from the individual expressions. You cannot use any other arithmetic operator with an IPv6 expression. T he following syntax is an example:
client.ipv6.src + server.ip.dst
For example, if the client source IPv6 address is ABCD:1234::ABCD, and the server destination IPv4 address is 10.100.10.100, the preceding expression
returns "ABCD:1234::ABCD10.100.10.100".
Note that when the NetScaler appliance receives an IPv6 packet, it assigns a temporary IPv4 address from an unused IPv4 address range and changes
the source address of the packet to this temporary address. At response time, the outgoing packet's source address is replaced with the original IPv6
address.
Note: You can combine an IPv6 expression with any other expression except an expression that produces a Boolean result.
Expression Prefixes for IPv6 Addresses
T he IPv6 addresses that are returned by the expression prefixes in the following table can be treated as text data. For example, the prefix client.ipv6.dst
returns the destination IPv6 address as a string that can be evaluated as text.
CLIENT.IPV6.DST Returns the IPv6 address in the destination field of the IP header.
CLIENT.IPV6.SRC Returns the IPv6 address in the source field of the IP header. Following are examples:
client.ipv6.src.in_subnet(2007::2008/64)
client.ipv6.src.get1.le(2008)
SERVER.IPV6.DST Returns the IPv6 address in the destination field of the IP header.
SERVER.IPV6.SRC Returns the IPv6 address in the source field of the IP header. Following are examples:
server.ipv6.src.in_subnet(2007::2008/64)
server.ipv6.src.get1.le(2008)
<ipv6>.EQ(<IPv6_address> ) Returns a Boolean T RUE if the IP address value is same as the <IPv6_address> argument.
Following is an example:
client.ipv6.dst.get5 extracts 0000, which is the fifth set of bits in the address.
client.ipv6.dst.get6 extracts 89AB.
client.ipv6.dst.get7 extracts 4567.
You can perform numeric operations on these segments. Note that you cannot perform numeric operations when
you retrieve an entire IPv6 address. T his is because expressions that return an entire IPv6 address, such as
CLIENT.IPV6.SRC, return the address in text format.
<ipv6>.IN_SUBNET(<subnet>) Returns a Boolean T RUE if the IPv6 address value is in the subnet specified by the <subnet> argument.
Following is an example:
client.ipv6.dst.eq(1000:1001:CD10:0000:0000:89AB:4567:CDEF/60)
<ipv6>.IS_IPV4 Returns a Boolean T RUE if this is an IPv4 client, and returns a Boolean FALSE if it is not.
<ipv6>.SUBNET(<n>) Returns the IPv6 address after applying the subnet mask specified as the argument. T he subnet mask can take
values between 0 and 128.
For example:
CLIENT.IPV6.SRC.SUBNET(24)
A MAC address consists of colon-delimited hexadecimal values in the format ##:##:##:##:##:##, where each “#” represents either a number from 0
through 9 or a letter from A through F. Default syntax expression prefixes and operators are available for evaluating source and destination MAC
addresses.
client.ether.dstmac Returns the MAC address in the destination field of the Ethernet header.
client.ether.srcmac Returns the MAC address in the source field of the Ethernet header.
<mac address>.EQ(<address>) Returns a Boolean T RUE if the MAC address value is same as the <address> argument.
For example, if the MAC address is 12:34:56:78:9a:bc, the following returns 34:
client.ether.dstmac.get2
T he following table describes prefixes for working with numeric client and server data, including throughput, port numbers, and VLAN IDs.
T able 7 . P ref ixes T hat Evaluat e Numeric Client and Server Dat a
client.interface.rxthroughput Returns an integer representing the raw received traffic throughput in kilobytes per second (KBps) for the previous
seven seconds.
client.interface.txthroughput Returns an integer representing the raw transmitted traffic throughput in KBps for the previous seven seconds.
client.interface.rxtxthroughput Returns an integer representing the raw received and transmitted traffic throughput in KBps for the previous seven
seconds.
server.interface.rxthroughput Returns an integer representing the raw received traffic throughput in KBps for the previous seven seconds.
server.interface.txthroughput Returns an integer representing the raw transmitted traffic throughput in KBps for the previous seven seconds.
server.interface.rxtxthroughput Returns an integer representing the raw received and transmitted traffic throughput in KBps for the previous seven
seconds.
server.vlan.id Returns a numeric ID of the VLAN through which the current packet entered the NetScaler.
client.vlan.id Returns a numeric ID for the VLAN through which the current packet entered the NetScaler.
COLLECT_STATS
Collect statistical data from the requests that are evaluated against the policy and create a record for each request.
REQUESTS
Return the number of requests that exist for the specified record grouping. T he value returned is of type unsigned long.
BANDWIDTH
Return the bandwidth statistic for the specified record grouping. T he value returned is of type unsigned long.
RESPTIME
Return the response time statistic for the specified record grouping. T he value returned is of type unsigned long.
CONNECTIONS
Return the number of concurrent connections that exist for the specified record grouping. T he value returned is of type
unsigned long.
IS_TOP(n)
Return a Boolean TRUE if the statistical value for the specified record grouping is one among the top n groups. Otherwise,
return a Boolean FALSE.
CHECK_LIMIT
Return a Boolean TRUE if the statistic for the specified record grouping has hit the preconfigured limit. Otherwise, return a
Boolean FALSE.
T he following expressions evaluate traffic associated with MySQL database servers. You can use the request-based
expressions (expressions that begin with MYSQL.CLIENT and MYSQL.REQ) in policies to make request switching decisions
at the content switching virtual server bind point and the response-based expressions (expressions that begin with
MYSQL.RES) to evaluate server responses to user-configured health monitors.
i - Number of rows
MYSQL.RES.ERROR. Identifies the MySQL error object. T he error object includes the error number and the error
message.
MYSQL.RES.ERROR.MESSAGE. Returns the error message that is retrieved from the server's error response.
MYSQL.RES.ERROR.NUM. Returns the error number that is retrieved from the server's error response.
MYSQL.RES.ERROR.SQLSTATE. Returns the value of the SQLSTATE field in the server's error response. T he MySQL
server translates error number values to SQLSTATE values.
MYSQL.RES.FIELD(<i>). Identifies the packet that corresponds to the i th individual field in the server's response. Each
field packet describes the properties of the associated column. T he packet count (i) begins at 0.
Paramet ers:
i - Packet number
i - Row number
MYSQL.RES.ROW(<i>).DOUBLE_ELEM(<j>). Checks whether the j th column of the i th row of the table is NULL.
Following C conventions, both indexes i and j start from 0. T herefore, row i and column j are actually the (i+1)th row and
the (j+1)th column, respectively.
Paramet ers:
i - Row number
j - Column number
MYSQL.RES.ROW(<i>).IS_NULL_ELEM(j). Checks whether the j th column of the i th row of the table is NULL. Following
C conventions, both indexes i and j start from 0. T herefore, row i and column j are actually the (i+1)th row and the (j+1)th
i - Row number
j - Column number
MYSQL.RES.ROW(<i>).NUM_ELEM(<j>). Returns an integer value from the j th column of the i th row of the table.
Following C conventions, both indexes i and j start from 0. T herefore, row i and column j are actually the (i+1)th row and
the (j+1)th column, respectively.
Paramet ers:
i - Row number
j - Column number
MYSQL.RES.ROW(<i>).TEXT_ELEM(j). Returns a string from the j th column of the i th row of the table. Following C
conventions, both indexes i and j start from 0. T herefore, row i and column j are actually the (i+1)th row and the (j+1)th
column, respectively.
Paramet ers:
i - Row number
j - Column number
MYSQL.RES.TYPE. Returns an enumeration constant for the response type. Its values can be ERROR, OK, and
RESULT_SET. T he EQ(<m>) and NE(<m>) operators, which return Boolean values to indicate the result of a
comparison, are used with this prefix.
T he following expressions evaluate traffic associated with Microsoft SQL Server database servers. You can use the
request-based expressions (expressions that begin with MSSQL.CLIENT and MSSQL.REQ) in policies to make request
switching decisions at the content switching virtual server bind point and the response-based expressions (expressions that
begin with MSSQL.RES) to evaluate server responses to user-configured health monitors.
MSSQL.CLIENT.DATABASE Returns the name of the client database. T he value returned is of type
text.
MSSQL.CLIENT.USER Returns the user name with which the client authenticated. T he value
returned is of type text.
MSSQL.REQ.QUERY.COMMAND Returns the first keyword in the SQL query. T he value returned is of
type text.
MSSQL.REQ.QUERY.SIZE Returns the size of the SQL query in the request. T he value returned is
a number.
MSSQL.REQ.QUERY.TEXT Returns the entire SQL query as a string. T he value returned is of type
text.
MSSQL.REQ.QUERY.TEXT(<n>) Returns the first n bytes of the SQL query. T he value returned is of
type text.
Paramet ers:
n - Number of bytes
MSSQL.REQ.RPC.NAME Returns the name of the procedure that is being called in a remote
procedure call (RPC) request. T he name is returned as a string.
MSSQL.REQ.RPC.IS_PROCID Returns a Boolean value that indicates whether the remote procedure
call (RPC) request contains a procedure ID or an RPC name. A return
value of TRUE indicates that the request contains a procedure ID and
a return value of FALSE indicates that the request contains an RPC
name.
MSSQL.REQ.RPC.PROCID Returns the procedure ID of the remote procedure call (RPC) request as
an integer.
MSSQL.REQ.RPC.BODY Returns the body of the SQL request as a string in the form of
Note: Not available for releases before 10.1. parameters represented as "a=b" clauses separated by commas, where
"a" is the RPC parameter name and "b" is its value.
MSSQL.REQ.RPC.BODY(n) Returns part of the body of the SQL request as a string in the form of
Note: Not available for releases before 10.1. parameters represented as "a=b" clauses separated by commas, where
MSSQL.RES.ATLEAST_ROWS_COUNT(i) Checks whether the response has at least i number of rows. T he value
returned is a Boolean TRUE or FALSE value.
Paramet ers:
i - Number of rows
MSSQL.RES.DONE.STATUS Returns the status field from the DONE token sent by a Microsoft SQL
Server database server. T he value returned is a number.
MSSQL.RES.ERROR.MESSAGE Returns the error message from the ERROR token sent by a Microsoft
SQL Server database server. T his is the value of the MsgText field in the
ERROR token. T he value returned is of type text.
MSSQL.RES.ERROR.NUM Returns the error number from the ERROR token sent by a Microsoft
SQL Server database server. T his is the value of the Number field in the
ERROR token. T he value returned is a number.
MSSQL.RES.ERROR.STATE Returns the error state from the ERROR token sent by a Microsoft
SQL Server database server. T his is the value of the State field in the
ERROR token. T he value returned is a number.
MSSQL.RES.FIELD(<i>).DATATYPE Returns the data type of the i th field in the server response. T he
EQ(<m>) and NE(<m>) functions, which return Boolean values to
indicate the result of a comparison, are used with this prefix.
MSSQL.RES.FIELD(<2>).DATATYPE.EQ(datetime)
Paramet ers:
i - Row number
MSSQL.RES.FIELD(<i>).LENGTH Returns the maximum possible length of the i th field in the server
i - Row number
MSSQL.RES.FIELD(<i>).NAME Returns the name of the i th field in the server response. T he value
returned is of type text.
Paramet ers:
i - Row number
MSSQL.RES.ROW(<i>).DOUBLE_ELEM(<j>) Returns a value of type double from the j th column of the i th row of the
table. If the value is not a double value, an UNDEF condition is raised.
Following C conventions, both indexes i and j start from 0 (zero).
T herefore, row i and column j are actually the (i + 1)th row and the (j +
1)th column, respectively.
Paramet ers:
i - Row number
j - Column number
MSSQL.RES.ROW(<i>).NUM_ELEM(j) Returns an integer value from the j th column of i th row of the table. If
the value is not an integer value, an UNDEF condition is raised.
Following C conventions, both indexes i and j start from 0 (zero).
T herefore, row i and column j are actually the (i + 1)th row and the (j +
1)th column, respectively.
Paramet ers:
i - Row number
j - Column number
MSSQL.RES.ROW(<i>).IS_NULL_ELEM(j) Checks whether the j th column of the i th row of the table is NULL and
returns a Boolean TRUE or FALSE to indicate the result. Following C
conventions, both indexes i and j start from 0 (zero). T herefore, row i
and column j are actually the (i + 1)th row and the (j + 1)th column,
respectively.
Paramet ers:
i - Row number
j - Column number
th th
Paramet ers:
i - Row number
j - Column number
After typecasting the data, you can apply any operation that is appropriate for the new data type. For example, if you typecast text to an HT T P
header, you can apply any operation that is applicable to HT T P headers to the returned value.
Function Description
<text>.TYPECAST_LIST_T(<separator>) Treats the text in an HT T P request or response body as a list whose elements are
delimited by the character in the <separator> argument. Index values in the list that is
created start with zero (0).
Text mode settings have no effect on the separator. For example, even if you set the
text mode to IGNORECASE, and the separator is the letter “p,” an uppercase “P” is not
treated as a separator.
<text>.TYPECAST_ NVLIST_T(<separator>, Treats the text as a name-value list. T he <separator> argument identifies the character
<delimiter>) and separates the name and the value. T he <delimiter> argument identifies the
character that separates each name-value pair. T he <quote> character is required
or
when typecasting text into a name-value list that supports quoted strings. Any
text.TYPECAST_ NVLIST_T(<separator>, <delimiter>, delimiters that appear within the quoted string are ignored.
<quote>)
T he text mode has no effect on the delimiters. For example, if the current text mode is
IGNORECASE and you specify “p” as the delimiter, an uppercase “P” is not treated as a
delimiter.
For example, the following policy counts the number of name-value pairs and inserts
<text>.TYPECAST_TIME_T Treats the designated text as a date string. T he following formats are supported:
For example, the following policy converts the string to a time value and then extracts
the day. T his policy matches all requests that have a day value lesser than or equal to
10.
For example, the following policy matches HT T P requests that contains Cookie
headers with a value of: 12.34.56.78\r\n.
0000:0000:CD00:0000:0000:00AB:0000:CDEF
<text>.TYPECAST_HTTP_ URL_T Treats the designated text as the URL in the first line of an HT T P request header. T he
supported format is [<protocol>://<hostname>]<path>?<query>, and the text mode is
set to URLENCODED by default.
T his policy would replace the preceding header with the value ABC%string123\r\n.
<text>.TYPECAST_HTTP_ HOSTNAME_T Provides operations for parsing an HT T P host name as it appears in HT T P data. T he
format for a host name is abc.def.com:8080.
For example, the following policy matches any HT T P request that contains a Host
header with a value equal to POST :
<text>.TYPECAST_DNS_ DOMAIN_T Enables the designated text to be parsed like a DNS domain name in the format
ab.def.com.
<text>.TYPECAST_HTTP_ HEADER_T("<name>") Converts the designated text to a multi-line HT T P header that you specify in a <name>
argument.
http.req.header("MyHeader").typcast_http_header_t("InHeader")
Typically, text operations that you specify in this type of expression apply to only the
last line of this header, with some exceptions. For example, the CONTAINS operation
operates on values in all the lines in instances of this header type.
cookie1=value1;version=n.n;value;domain=value;path=value
If the same attribute appears more than once in a cookie, the value for the first
instance of the attribute is returned.
<number>.TYPECAST_TIME_AT.BETWEEN(<time1>, Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
<time2>) designated by <number> is between the lower and upper time value arguments
<time1> and <time2>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the first Sunday of the month of May in 2005. T he result
of the evaluation is given after each example.
<number>.TYPECAST_TIME_AT.DAY Extracts the day of the month from the current system time and returns the value as a
number that corresponds to the day of the month. T he returned value ranges from 1
to 31.
<number>.TYPECAST_TIME_AT.EQ(<t>) Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
designated by <number> is equal to the time value argument <t>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the 1st Sunday of the month of May in 2005. T he result of
the evaluation is given after each example.
<t> - T ime
<number>.TYPECAST_TIME_AT.GE(<t>) Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
designated by <number> is greater than or equal to the time value argument <t>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the 1st Sunday of the month of May in 2005. T he result of
<t> - T ime
<number>.TYPECAST_TIME_AT.GT(<t>) Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
designated by <number> is greater than the time value argument <t>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the 1st Sunday of the month of May in 2005. T he result of
the evaluation is given after each example.
<t> - T ime
<number>.TYPECAST_TIME_AT.HOURS Extracts the hour from the current system time and returns the corresponding value as
an integer that can range from 0 to 23.
<number>.TYPECAST_TIME_AT.LE(<t>) Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
designated by <number> is lesser than or equal to the time value argument <t>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the 1st Sunday of the month of May in 2005. T he result of
the evaluation is given after each example.
<number>.TYPECAST_TIME_AT.LT(<t>) Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
designated by <number> is lesser than the time value argument <t>.
T he following examples assume that the current time value is GMT 2005 May 1 10h
15m 30s and that the day is the 1st Sunday of the month of May in 2005. T he result of
the evaluation is given after each example.
<t> - T ime
<number>.TYPECAST_TIME_AT.MINUTES Extracts the minute from the current system time and returns the value as an integer
that can range from 0 to 59.
<number>.TYPECAST_TIME_AT.MONTH Extracts the month from the current system time and returns the value as an integer
that can range from 1 (January) to 12 (December).
<number>.TYPECAST_TIME_AT.RELATIVE_BOOT Calculates the number of seconds that have elapsed after the most recent reboot or
the number of seconds to the next scheduled reboot, depending on which is closer to
the current time, and returns an integer. If the closest boot time is in the past, the
integer is negative. If the closest boot time is in the future (scheduled reboot time), the
integer is positive.
<number>.TYPECAST_TIME_AT.RELATIVE_NOW Calculates the number of seconds between the current system time and the specified
time, and returns the value as an integer. If the designated time is in the past, the
integer is negative. If it is in the future, the integer is positive.
<number>.TYPECAST_TIME_AT.SECONDS Extracts the seconds from the current system time and returns the value as an integer
that can range from 0 to 59.
<number>.TYPECAST_TIME_AT.WEEKDAY Returns an integer that corresponds to the day of the week; 0 for Sunday and 6 for
Saturday.
<number>.TYPECAST_TIME_AT.WITHIN(<time1>, Returns a Boolean value (T RUE or FALSE) that indicates whether the time value
<time2>) designated by <number> lies within all the ranges defined by lower and upper time value
arguments <time1> and <time2>.
If an element of time such as the day or the hour is left unspecified in the lower
argument, <time1>, then it is assumed to have the lowest value possible for its range.
month: 1-12
day: 1-31
weekday: 0-6
hour: 0-23
minutes: 0-59
seconds: 0-59.
Each element of time in the lower time value argument defines a range in combination
with the corresponding element in the upper time value argument. For the result to be
T RUE, each element of time in the time value designated by <number> must lie in the
corresponding range specified by the lower and upper arguments.
T he following examples assume that the current time value is GMT 2005 May 10 10h
15m 30s.and that the day is the second Tuesday of the month. T he result of the
evaluation is given after each example.
<number>.TYPECAST_TIME_AT.YEAR Extracts the year from the current system time and returns the value as a four-digit
integer.
<prefix>.TYPECAST_NUM_T(<type>) Casts numeric string data to a signed 32-bit number. T he argument <type> can be one
of the following:
DECIMAL. T reat the string as a decimal number and cast to a signed 32-bit number.
HEX. T reat the string as a hexadecimal number and cast to a signed 32-bit number.
DECIMAL_PREFIX. Consider the part of the string up to the first occurrence of a
character that is not a valid decimal character and cast to a signed 32-bit number.
HEX_PREFIX. Consider the part of the string up to the first occurrence of a
character that is not a valid hexadecimal character and cast to a signed 32-bit
number.
For example, the following policy extracts a numeric portion of a query string, adds 4 to
the number, and inserts an HT T P header named Company with the resulting decimal
value.
/test/file.html?4444
T he action that is associated with the policy would insert the following HT T P response
header:
Company: 4448\r\n
<prefix>.TYPECAST_NUM_AT Casts a number of any data type to a number of data type integer.
<prefix>.TYPECAST_DOUBLE_AT Casts a number of any data type to a number of data type double.
<prefix>.TYPECAST_UNSIGNED_LONG_AT Casts a number of any data type to a number of data type unsigned long.
<prefix>.TYPECAST_NUM_T(<type>,<default>) Casts string data to a signed 32-bit number. If the typecasting operation raises an
undefined ( UNDEF) condition, the function returns the value specified for default. T he
type argument takes the values specified for TYPECAST_NUM_T(<type>).
<prefix>.TYPECAST_UNSIGNED_LONG_T(<type>) Casts string data to data of type unsigned long. T he argument can be one of the
following:
DECIMAL. T reat the string as a decimal number and cast to unsigned long.
HEX. T reat the string as a hexadecimal number and cast to unsigned long.
DECIMAL_PREFIX. Consider the part of the string up to the first occurrence of a
character that is not a valid decimal character and cast to unsigned long.
HEX_PREFIX. Consider the part of the string up to the first occurrence of a
character that is not a valid hexadecimal character and cast to unsigned long.
<prefix>.TYPECAST_UNSIGNED_LONG_T(<type>, Casts string data to data of type unsigned long. If the typecasting operation raises an
<default>) undefined (UNDEF) condition, the function returns the value specified for default. T he
type argument takes the values specified for
TYPECAST_UNSIGNED_LONG_T(<type>).
T he target text for an operator that works with regular expressions can be either text or the value of an HT T P header.
Following is the format of a default syntax expression that uses a regular expression operator to operate on text:
<text>.<regex_operator>(re<delimiter><regex_pattern><delimiter>)
T he string <text> represents the default syntax expression prefix that identifies a text string in a packet (for example,
HT T P.REQ.URL). T he string <regex_operator> represents the regular expression operator. T he regular expression always
begins with the string re. A pair of matching delimiters, represented by <delimiter>, enclose the string <regex_pattern>,
which represents the regular expression.
T he following example expression checks whether the URL in an HT T P packet contains the string *.jpeg (where * is a
wildcard) and returns a Boolean T RUE or FALSE to indicate the result. T he regular expression is enclosed within a pair of
slash marks (/), which act as delimiters.
http.req.url.regex_match(re/*.jpeg/)
Regular expression operators can be combined to define or refine the scope of a search. For example,
<text>.AFTER_REGEX(re/regex_pattern1/).BEFORE_REGEX(re/regex_pattern2/) specifies that the target for string
matching is the text between the patterns regex_pattern1 and regex_pattern2. You can use a text operator on the scope
that is defined by the regular expression operators. For example, you can use the CONTAINS(“<string>”) operator to check
whether the defined scope contains the string abc:
<text>.AFTER_REGEX(re/regex_pattern1/).BEFORE_REGEX(re/regex_pattern2/).CONTAINS(“abc”)
Note: T he process of evaluating a regular expression inherently takes more time than that for an operator such as
CONT AINS(“<string>”) or EQ(“<string>”), which work with simple string arguments. You should use regular expressions only if
your requirement is beyond the scope of other operators.
A regular expression always begins with the string “re” followed by a pair of delimiting characters (called delimiters) that
enclose the regular expression that you want to use.
For example, re#<regex_pattern># uses the number sign (#) as a delimiter.
Following are the differences between the NetScaler syntax and the PCRE syntax:
Table 1. Def ault Syntax Expression Operators That Work with Regular Expressions
<text>.BEFORE_REGEX(<regular Selects the text that precedes the string that matches the <regular expression>
expression>) argument. If the regular expression does not match any data in the target, the
expression returns a text object of length 0.
http.res.header("content-type").before_regex(re#/#)
<text>.AFTER_REGEX(<regular Selects the text that follows the string that matches the <regular expression>
expression>) argument. If the regular expression does not match any text in the target, the
expression returns a text object of length 0.
http.req.header("etag").after_regex(re/my/)
<text>.REGEX_SELECT(<regular Selects a string that matches the <regular expression> argument. If the regular
expression>) expression does not match the target, a text object of length 0 is returned.
T he following example extracts the string "NS-CACHE-9.0: 90" from a Via header:
http.req.header("via").regex_select(re!NS-CACHE-\d\.\d:\s*\d{1,3}!)
Both delimiters must be the same. Additionally, the regular expression must
conform to the Perl-compatible (PCRE) regular expression library syntax. For more
information, go to http://www.pcre.org/pcre.txt. In particular, see the pcrepattern
man page. However, note the following:
http.req.hostname.regex_match(re/[[:alpha:]]+(abc){2,3}/)
http.req.url.set_text_mode(urlencoded).regex_match(re#(a*b+c*)#)
T he following example matches ab and aB:
http.req.url.regex_match(re/a(?i)b/)
http.req.url.set_text_mode(ignorecase).regex_match(re/ab/)
Warning
T he Compression Classic policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to use
the Compression Advanced policy. You can also use the nspepi. utility tool for the conversion
Some NetScaler features use classic policies and classic expressions. As with default syntax policies, classic policies can be
either global or specific to a virtual server. However, to a certain extent, the configuration method and bind points for
classic policies are different from those of default syntax policies. As with default syntax expressions, you can configure
named expressions and use a named expression in multiple classic policies.
T he following table summarizes NetScaler features that can be configured by using classic policies.
Table 1. Policy Type and Bind Points f or Policies in Features That Use Classic Policies
Feature Virtual Supported Policy Bind Points How You Use the Policies
Servers Policies
Protection None Priority Load Balancing To configure the behavior of the Priority
features, Queuing virtual server Queuing function.
Priority policies SSL Offload
Queuing virtual server
AAA - Traffic None Authentication, Authentication To configure rules for user access to specific
Management Authorization, virtual server sessions and auditing of user access.
Auditing, and (authentication,
Session policies session, and
NetScaler VPN server Pre- AAA Global To determine how the NetScaler Gateway
Gateway Authentication VPN vserver performs authentication, authorization,
policies auditing, and other functions, and to define
rewrite rules for general Web access using the
NetScaler Gateway.
Authentication System Global
policies AAA Global
VPN vserver
Auditing User
policies User group
VPN vserver
Note that there are small variations in the policy configuration methods for various NetScaler features.
Note: You can embed a classic expression in a default syntax expression by using the syntax
SYS.EVAL_CLASSIC_EXPR(classic_expression), specifying the classic_expression as the argument.
To create a classic policy by using the command line interf ace
At the command prompt, type the following commands to set the parameters and verify the configuration:
Example
T he following commands first create a compression action and then create a compression policy that applies the action:
1. In the navigation pane, expand the feature for which you want to configure a policy and, depending on the feature, do
the following:
For Content Switching, Cache Redirection, and the application firewall, click Policies.
For SSL, click Policies, and then in the details pane, click the Policies tab.
For System Authentication, click Authentication, and then in the details pane, click the Policies tab.
For Filter, SureConnect, and Priority Queuing, expand Protection Features, select the desired function, and then in the
details pane, click the Policies tab.
For the NetScaler Gateway, expand NetScaler Gateway, expand Policies, select the desired function, and then in the
details pane, click the Policies tab.
2. For most features, click the Add button.
3. In the Create <feature name> Policy dialog box, in the Name* text box, enter a name for the policy.
Depending on the type of policy you want to create, you can choose a predefined expression, or you can create a new
expression. For instructions on how to create an expression for most types of classic policies, see "Configuring a Classic
Expression."
Named expressions are predefined expressions that you can reference by name in a policy rule. For more information
about named expressions, see "Creating Named Classic Expressions." For a list of all the default named expressions and a
definition of each, see "Expressions Reference."
Flow Type. Specifies whether the connection is incoming or outgoing. T he flow type is REQ for incoming connections
and RES for outgoing connections.
Protocol. Specifies the protocol, the choices for which are HT T P, SSL, T CP, and IP.
Qualif ier. T he protocol attribute, which depends on the selected protocol.
Operator. T he type of test you want to perform on the connection data. Your choice of operator depends upon the
connection information you are testing. If the connection information you are testing is text, you use text operators. If
it is a number, you use standard numeric operators.
Value. T he string or number against which the connection data element— defined by the flow type, protocol, and
qualifier— is tested. T he value can be either a literal or an expression. T he literal or expression must match the data type
of the connection data element.
In a policy, classic expressions can be combined to create more complex expressions using Boolean and comparative
operators.
Expression elements are parsed from left to right. T he leftmost element is either REQ or RES and designates a request or a
response, respectively. Successive terms define a specific connection type and a specific attribute for that connection type.
Each term is separated from any preceding or following term by a period. Arguments appear in parentheses and follow the
expression element to which they are passed.
T he following classic expression fragment returns the client source IP for an incoming connection.
REQ.IP.SOURCEIP
T he example identifies an IP address in a request. T he expression element SOURCEIP designates the source IP address. T his
expression fragment may not be useful by itself. You can use an additional expression element, an operator, to determine
whether the returned value meets specific criteria. T he following expression tests whether the client IP is in the subnet
200.0.0.0/8 and returns a Boolean T RUE or FALSE:
At the command prompt, type the following commands to set the parameters and verify the configuration:
Example
> set appfw policy GenericApplicationSSL_ 'HTTP.REQ.METHOD.EQ("get")' APPFW_DROP
Done
> show appfw policy GenericApplicationSSL_
Name: GenericApplicationSSL_ Rule: HTTP.REQ.METHOD.EQ("get")
Profile: APPFW_DROP Hits: 0
Undef Hits: 0
Policy is bound to following entities
T his procedure documents the Add Expression dialog box. Depending on the feature for which you are configuring a policy,
the route by which you arrive at this dialog box may be different.
1. Perform steps 1-4 in "T o create a policy with classic expressions by using the configuration utility."
2. In the Add Expression dialog box, in Expression T ype, click the type of expression you want to create.
3. Under Flow T ype, click the down arrow and choose a flow type.
T he flow type is typically REQ or RES. T he REQ option specifies that the policy applies to all incoming connections or
requests. T he RES option applies the policy to all outgoing connections or responses.
For Application Firewall policies, you should leave the expression type set to General Expression, and the flow type set to
REQ. T he Application Firewall treats each request and response as a single paired entity, so all Application Firewall policies
begin with REQ.
4. Under Protocol, click the down arrow and choose the protocol you want for your policy expression. Your choices are:
HT T P. Evaluates HT T P requests that are sent to a Web server. For classic expressions, HT T P includes HT T PS requests.
SSL. Evaluates SSL data associated with the current connection.
T CP. Evaluates the T CP data associated with the current connection.
IP. Evaluates the IP addresses associated with the current connection.
5. Under Qualifier, click the down arrow and choose a qualifier for your policy.
T he qualifier defines the type of data to be evaluated. T he list of qualifiers that appears depends on which protocol you
selected in step 4.
T he following list describes the qualifier choices for the HT T P protocol. For a complete list of protocols and qualifiers,
see "Classic Expressions."
Operator Description
== Matches the specified value exactly or is exactly equal to the specified value.
CONTENTS Returns the contents of the designated header, URL, or URL query.
7. If a Value text box appears, type a string or numeric value, as appropriate. For example, chose REQ as the Flow T ype,
HT T P as the Protocol, and HEADER as the qualifier, and then type the value of the header string in the Value field and
the header type for which you want to match the string in the Header Name text box.
8. Click OK.
9. T o create a compound expression, click Add. Note that the type of compounding that is done depends on the following
choices in the Create Policy dialog box:
Match Any Expression. T he expressions are in a logical OR relationship.
Match All Expressions. T he expressions are in a logical AND relationship.
Tabular Expressions. Click the AND, OR, and parentheses buttons to control evaluation.
Advanced Free-Form. Enter the expressions components directly into the Expression field, and click the AND, OR, and
parentheses buttons to control evaluation.
At the command prompt, type the following commands to set the parameters and verify the configuration:
Example
> bind cmp global cmp-pol-compress -priority 2
Done
> show cmp global
1) Policy Name: cmp-pol-compress Priority: 2
2) Policy Name: ns_nocmp_xml_ie Priority: 8700
3) Policy Name: ns_nocmp_mozilla_47 Priority: 8800
4) Policy Name: ns_cmp_mscss Priority: 8900
5) Policy Name: ns_cmp_msapp Priority: 9000
6) Policy Name: ns_cmp_content_type Priority: 10000
Done
>
To bind a classic policy to a virtual server by using the command line interf ace
At the command prompt, type the following commands to set the parameters and verify the configuration:
Example
> bind lb vserver lbtemp -policyName cmp-pol-compress -priority 1
Done
> show lb vserver lbtemp
lbtemp (10.102.29.101:80) - HTTP Type: ADDRESS
State: UP
Last state change was at Tue Oct 27 06:40:38 2009 (+557 ms)
Time since last state change: 0 days, 02:00:40.330
Effective State: UP
Client Idle Timeout: 180 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
Port Rewrite : DISABLED
No. of Bound Services : 1 (Total) 1 (Active)
Note: T his procedure documents the Global Bindings dialog box. Depending on the feature for which you want to globally
bind a policy, the route by which you arrive at this dialog box may be different.
1. In the navigation pane, expand the feature for which you want to globally bind a classic policy, and then locate the
policy that you want to bind globally.
Note: You cannot globally bind policies for Content Switching, Cache Redirection, SureConnect, Priority Queuing, or
NetScaler Gateway Authorization.
2. In the details pane, click Global Bindings.
3. In the Bind/Unbind <feature name> Policy(s) to Global dialog box, click Insert Policy.
4. In the Policy Name column, click the name of an existing policy that you want to globally bind, or click New Policy to
open the Create <feature name> Policy dialog box.
5. After you have selected the policy or created a new policy, in the Priority column, type the priority value.
T he lower the number, the sooner this policy is applied relative to other policies. For example, a policy assigned a priority
of 10 is applied before a policy with a priority of 100. You can use the same priority for different policies. All features that
use classic policies implement only the first policy that a connection matches, so policy priority is important for getting
the results you intend.
As a best practice, leave room to add policies by setting priorities with intervals of 50 (or 100) between each policy.
6. Click OK.
1. In the navigation pane, expand the feature that contains the virtual server to which you want to bind a classic policy (for
example, if you want to bind a classic policy to a content switching virtual server, expand T raffic Management > Content
Switching), and then click Virtual Servers.
2. In the details pane, select the virtual server, and then click Open.
3. In the Configure <Feature> Virtual Server dialog box, on the Policies tab, click the feature icon for the type policy that
you want, and then click Insert Policy.
4. In the Policy Name column, click the name of an existing policy that you want to bind to a virtual server, or click A to
open the Create <feature name> Policy dialog box.
5. After you have selected the policy or created a new policy, in the Priority column, set the priority.
6. Click OK.
To view a classic policy and its binding inf ormation by using the command line interf ace
At the command prompt, type the following commands to view a classic policy and its binding information:
1. In the navigation pane, expand the feature whose policies you want to view, (for example, if you want to view
application firewall policies, expand Application Firewall), and then click Policies.
2. In the details pane, do one or more of the following:
T o view details for a specific policy, click the policy. Details appear in the Details area of the configuration pane.
T o view bindings for a specific policy, click the policy, and then click Show Bindings.
T o view global bindings, click the policy, and then click Global Bindings. Note that you cannot bind a Content
Switching, Cache Redirection, SureConnect, Priority Queuing, or NetScaler Gateway Authorization policy globally.
Some named expressions are built-in, and a subset of these are read-only. Built-in named expressions are divided into four categories:
General, Anti-Virus, Personal Firewall, and Internet Security. General named expressions have a wide variety of uses. For example, from
the General category, you can use the expressions ns_true and ns_false to specify a value of T RUE or FALSE, respectively, to be
returned for all traffic. You can also identify data of a particular type (for example, HT M, DOC, or GIF files), determine whether caching
headers are present, or determine whether the round trip time for packets between a client and the NetScaler is high (over 80
milliseconds).
Anti-Virus, Personal Firewall, and Internet Security named expressions test clients for the presence of a particular program and version
and are used primarily in NetScaler Gateway policies.
At the command prompt, type the following commands to set the parameters and verify the configuration:
Example
> add expression classic_ne "REQ.HTTP.URL CONTAINS www.example1.com" -comment "Checking the URL for www.example1.com"
Done
> show expression classic_ne
1) Name: classic_ne Expr: REQ.HTTP.URL CONTAINS www.example1.com Hits: 0 Type : CLASSIC
Comment: "Checking the URL for www.example1.com"
Done
>
To create a named classic expression by using the configuration utility
1. In the navigation pane, expand AppExpert, expand Expressions, and then click Classic Expressions.
2. In the details pane, click Add.
Note: Some of the built-in expressions in the Expressions list are read-only.
3. In the Create Policy Expression dialog box, specify values for the following parameters:
Warning
Q and S prefixes are deprecated from NetScaler 12.0 and should be replaced with HT T P.REQ and HT T P.RES, respectively. You can
also use the nspepi utility tool for the conversion
Note
For more information about Advanced Policy Expressions and prefixes, see Advanced Policy Expression Reference Guide.
T he following table is a listing of default syntax expression prefixes, with cross-references to descriptions of these prefixes
and the operators that you can specify for them. Note that some prefixes can work with multiple types of operators. For
example, a cookie can be parsed by using operators for text or operators for HT T P headers.
You can use any element in the following tables as a complete expression on its own, or you can use various operators to
combine these expression elements with others to form more complex expressions.
Note: T he Description column in the following table contains cross-references to additional information about prefix usage
and applicable operators for the prefix.
CLIENT.INTERFACE.ID.EQ("1/1")
CLIENT.TCP.[DSTPORT | MSS | SRCPORT] "Expressions for TCP, UDP, and VLAN Data."
CLIENT.UDP.DNS. [IS_AAAAREC | IS_ANYREC | IS_AREC | "Expressions for TCP, UDP, and VLAN Data."
IS_CNAMEREC | IS_MXREC | IS_NSREC | IS_PTRREC | IS_SOAREC
"Booleans in Compound Expressions."
| IS_SRVREC]
Also see:
SERVER.INTERFACE.ID.EQ("LA/1")
SERVER.TCP.[DSTPORT | MSS | SRCPORT] "Expressions for TCP, UDP, and VLAN Data."
SYS.TIME.[BETWEEN(time1, time2) | EQ(time) | GE(time) | GT(time) | "Expressions for the NetScaler System T ime."
LE(time) | LT(time) | WITHIN(time1, time2)]
"Booleans in Compound Expressions."
SYS.TIME.[DAY | HOURS | MINUTES | MONTH | RELATIVE_BOOT | "Expressions for the NetScaler System T ime."
RELATIVE_NOW SECONDS | WEEKDAY | YEAR]
"Compound Operations for Numbers."
Warning
Classic policy expressions are no longer supported from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix
recommends you to use Advanced policies. For more information, see Advanced Policies topic.
T he subtopics listed in the table of contents on the left side of your screen contain tables listing the NetScaler classic
expressions.
In the table of operators, the result type of each operator is shown at the beginning of the description. In the other tables,
the level of each expression is shown at the beginning of the description. For named expressions, each expression is shown
as a whole.
Operators
Expression Definition
Element
== Boolean.
Returns T RUE if the current expression equals the argument. For text operations, the items being
compared must exactly match one another. For numeric operations, the items must evaluate to the
same number.
!= Boolean.
Returns T RUE if the current expression does not equal the argument. For text operations, the items
being compared must not exactly match one another. For numeric operations, the items must not
evaluate to the same number.
Returns T RUE if the current expression contains the string that is designated in the argument.
NOTCONTAINS Boolean.
Returns T RUE if the current expression does not contain the string that is designated in the
argument.
EXIST S Boolean.
Returns T RUE if the item designated by the current expression does not exist.
> Boolean.
Returns T RUE if the current expression evaluates to a number that is greater than the argument.
< Boolean.
Returns T RUE if the current expression evaluates to a number that is less than the argument.
>= Boolean.
Returns T RUE if the current expression evaluates to a number that is greater than or equal to the
argument.
<= Boolean.
Returns T RUE if the current expression evaluates to a number that is less than or equal to the
argument.
General Expressions
REQ.HTTP Protocol
Operates on HT T P requests.
REQ.HTTP.METHOD Qualifier
REQ.HTTP.URL Qualifier
REQ.HTTP.URLTOKENS Qualifier
REQ.HTTP.VERSION Qualifier
REQ.HTTP.HEADER Qualifier
REQ.HTTP.URLLEN Qualifier
REQ.HTTP.URLQUERY Qualifier
REQ.HTTP.URLQUERYLEN Qualifier
REQ.SSL Protocol
REQ.SSL.CLIENT.CERT Qualifier
REQ.SSL.CLIENT.CERT.ISSUER Qualifier
REQ.SSL.CLIENT.CERT.SIGALGO Qualifier
REQ.SSL.CLIENT.CERT.VERSION Qualifier
REQ.SSL.CLIENT.CERT.VALIDFROM Qualifier
Designates the date before which the client certificate is not valid.
REQ.SSL.CLIENT.CERT.VALIDTO Qualifier
Designates the date after which the client certificate is not valid.
REQ.SSL.CLIENT.CERT.SERIALNUMBER Qualifier
REQ.SSL.CLIENT.CIPHER.TYPE Qualifier
REQ.SSL.CLIENT.CIPHER.BITS Qualifier
REQ.SSL.CLIENT.SSL.VERSION Qualifier
REQ.TCP Protocol
REQ.TCP.SOURCEPORT Qualifier
REQ.TCP.DESTPORT Qualifier
REQ.IP Protocol
REQ.IP.SOURCEIP Qualifier
REQ.IP.DESTIP Qualifier
RES.HTTP Protocol
Operates on HT T P responses.
RES.HTTP.VERSION Qualifier
RES.HTTP.HEADER Qualifier
RES.HTTP.STATUSCODE Qualifier
RES.TCP Protocol
RES.TCP.SOURCEPORT Qualifier
RES.TCP.DESTPORT Qualifier
RES.IP Protocol
RES.IP.SOURCEIP Qualifier
RES.IP.DESTIP Qualifier
Updated: 2013-10-21
T he expressions to configure client settings on the Access Gateway with the following software:
Antivirus
Personal firewall
Antispam
Internet Security
CLIENT.APPLICATION.AV(<NAME>.VERSION Checks whether the client is not running the designated anti-virus
!= <VERSION>) program and version.
CLIENT.APPLICATION.PF(<NAME>.VERSION Checks whether the client is running the designated personal firewall
== <VERSION>) program and version.
CLIENT.APPLICATION.IS(<NAME>.VERSION Checks whether the client is running the designated internet security
== <VERSION>) program and version.
CLIENT.APPLICATION.IS(<NAME>.VERSION Checks whether the client is not running the designated internet
!= <VERSION>) security program and version.
CLIENT.APPLICATION.AS(<NAME>.VERSION Checks whether the client is not running the designated anti-spam
!= <VERSION>) program and version.
Network-Based Expressions
Expression Definition
REQ.VLANID Qualifier.
REQ.INTERFACE.ID Qualifier.
REQ.INTERFACE.RXTHROUGHPUT Qualifier.
REQ.INTERFACE.TXTHROUGHPUT Qualifier.
REQ.INTERFACE.RXTXTHROUGHPUT Qualifier.
REQ.ETHER.SOURCEMAC Qualifier.
REQ.ETHER.DESTMAC Qualifier.
RES.VLANID Qualifier.
RES.INTERFACE.ID Qualifier.
RES.INTERFACE.RXTHROUGHPUT Qualifier.
RES.INTERFACE.TXTHROUGHPUT Qualifier.
RES.INTERFACE.RXTXTHROUGHPUT Qualifier.
RES.ETHER.SOURCEMAC Qualifier.
RES.ETHER.DESTMAC Qualifier.
Expression Definition
T IME Qualifier.
DAT E Qualifier.
Updated: 2013-09-30
You can specify file system expressions in authorization policies for users and groups who access file sharing through the
NetScaler Gateway file transfer utility (the VPN portal). T hese expressions work with the NetScaler Gateway file transfer
authorization feature to control user access to file servers, folders, and files. For example, you can use these expressions in
authorization policies to control access based on file type and size.
Expression Definition
FS.COMMAND Qualifier.
Operates on a file system command. T he user can issue multiple commands on a file transfer
portal. (For example, ls to list files or mkdir to create a directory). T his expression returns the
current action that the user is taking.
Possible values: Neighbor, login, ls, get, put, rename, mkdir, rmdir, del, logout, any.
Following is an example:
Add authorization policy pol1 “fs.command eq login && (fs.user eq administrator || fs.serverip
eq 10.102.88.221 –netmask 255.255.255.252)” allow
FS.SERVER Returns the host name of the target server. In the following example, the string win2k3-88-
22 is the server name:
fs.server eq win2k3-88-221
FS.SERVICE Returns a shared root directory on the file server. If a particular folder is exposed as shared, a
user can directly log on to the specified first level folder. T his first level folder is called a
service. For example, in the path \\hostname\SERVICEX\ETC, SERVICEX is the service. As
another example, if a user accesses the file \\hostname\service1\dir1\file1.doc, FS.SERVICE
will return service1.
Following is an example:
FS.PATH Returns the complete path of the file being accessed. For example, if a user accesses the file
\\hostname\service1\dir1\file1.doc, FS.PATH will return \service\dir1\file1.doc.
Following is an example:
FS.FILE Returns the name of the file being accessed. For example, if a user accesses the file
\\hostname\service1\dir1\file1.doc, FS.FILE will return file1.doc.
FS.DIR Returns the directory being accessed. For example, if a user accesses the file
\\hostname\service1\dir1\file1.doc, FS.DIR will return \service\dir1.
FS.FILE.ACCESSTIME Returns the time at which the file was last accessed. T his is one of several options that
provide you with granular control over actions that the user performs. (See the following
entries in this table.)
FS.FILE.WRITETIME Returns the time of the most recent change in the status of the file.
FS.DIR.ACCESSTIME Returns the time at which the directory was last accessed.
FS.DIR.WRITETIME Returns the time at which the directory status last changed.
Expression Definition
ns_all_apps_ncomp Tests for connections with destination ports between 0 and 65535. In other words, tests
for all applications.
ns_cachecontrol_nocache Tests for connections with an HT T P Cache-Control header that contains the value “no-
cache”.
ns_cachecontrol_nostore Tests for connections with an HT T P Cache-Control header that contains the value “no-
store”.
ns_content_type Tests for connections with an HT T P Content-Type header that contains “text”.
ns_css Tests for connections with an HT T P Content-Type header that contains “text/css”.
ns_ext_asp Tests for HT T P connections to any URL that contains the string .asp— in other words, any
connection to an active server page (ASP).
ns_ext_cfm Tests for HT T P connections to any URL that contains the string .cfm
ns_ext_cgi Tests for HT T P connections to any URL that contains the string .cgi— in other words, any
connection to a common gateway interface (CGI) script.
ns_ext_ex Tests for HT T P connections to any URL that contains the string .ex
ns_ext_exe Tests for HT T P connections to any URL that contains the string .exe— in other words, any
connection to a executable file.
ns_ext_htx Tests for HT T P connections to any URL that contains the string .htx
ns_ext_not_jpeg Tests for HT T P connections to any URL that does not contain the string .jpeg— in other
words, any connection to a URL that is not a JPEG image.
ns_ext_shtml Tests for HT T P connections to any URL that contains the string .shtml— in other words,
any connection to a server-parsed HT ML page.
ns_farclient Client is in a different geographical region from the NetScaler, as determined by the
geographical region in the client’s IP address. T he following regions are predefined:
ns_mozilla_47 Tests for HT T P connections whose User-Agent header contains the string Mozilla/4.7— in
other words, any connection from a client using the Mozilla 4.7 Web browser.
ns_msexcel Tests for HT T P connections whose Content-Type header contains the string
application/vnd.msexcel— in other words, any connection transmitting a Microsoft Excel
spreadsheet.
ns_msie Tests for HT T P connections whose User-Agent header contains the string MSIE— in other
words, any connection from a client using any version of the Internet Explorer Web
browser.
ns_msword Tests for HT T P connections whose Content-Type header contains the string
application/vnd.msword— in other words, any connection transmitting a Microsoft Word
file.
ns_non_get Tests for HT T P connections that use any HT T P method except for GET.
ns_slowclient Returns T RUE if the average round trip time between the client and the NetScaler is more
than 80 milliseconds.
ns_url_path_bin Tests the URL path to see if it points to the /bin/ directory.
ns_url_path_cgibin Tests the URL path to see if it points to the CGI-BIN directory.
/exec/
directory.
Expression Definition
McAfee Virus Scan 11 Tests to determine whether the client is running the latest version of
McAfee VirusScan.
McAfee Antivirus Tests to determine whether the client is running any version of McAfee
Antivirus.
Symantec AntiVirus 10 (with Updated Tests to determine whether the client is running the most current version of
Definition File) Symantec AntiVirus.
Symantec AntiVirus 7.5 Tests to determine whether the client is running Symantec AntiVirus 7.5.
TrendMicro OfficeScan 7.3 Tests to determine whether the client is running Trend Microsystems’
OfficeScan, version 7.3.
TrendMicro AntiVirus 11.25 Tests to determine whether the client is running Trend Microsystems’
AntiVirus, version 11.25.
Sophos Antivirus 4 Tests to determine whether the client is running Sophos Antivirus, version 4.
Sophos Antivirus 5 Tests to determine whether the client is running Sophos Antivirus, version 5.
Sophos Antivirus 6 Tests to determine whether the client is running Sophos Antivirus, version 6.
Expression Definition
TrendMicro OfficeScan 7.3 Tests to determine whether the client is running Trend Microsystems’ OfficeScan,
version 7.3.
Sygate Personal Firewall 5.6 Tests to determine whether the client is running the Sygate Personal Firewall, version
5.6.
ZoneAlarm Personal Firewall Tests to determine whether the client is running the ZoneAlarm Personal Firewall,
6.5 version 6.5.
Expression Definition
Norton Internet Security Tests to determine whether the client is running any version of Norton Internet Security.
http.req.method.eq(get)
http.req.header("Cache-Control").contains("no-
cache")
http.req.header("Pragma").contains("no-cache")
http.res.header("Cache-
Control").contains("private")
http.res.header("Cache-Control").contains("public")
http.res.header("Cache-Control").contains("must-
revalidate")
http.res.header("Cache-Control").contains("proxy-
revalidate")
http.res.header("Cache-Control").contains("max-
age")
Look for a particular file type in an HT T P request based on the file http.req.url.contains(".html")
extension.
http.req.url.contains(".cgi")
http.req.url.contains(".asp")
http.req.url.contains(".ex")
http.req.url.contains(".shtml")
http.req.url.contains(".htx")
http.req.url.contains("/cgi-bin/")
http.req.url.contains("/exec/")
http.req.url.contains("/bin/")
Look for anything that is other than a particular file type in an http.req.url.contains(".gif").not
HT T P request.
http.req.url.contains(".jpeg").not
http.res.header("Content-Type").contains("vnd.ms-
excel")
http.res.header("Content-
Type").contains("application/vnd.ms-powerpoint")
http.res.header("Content-
Type").contains("text/css")
http.res.header("Content-
Type").contains("text/xml")
http.res.header("Content-Type").contains("image/")
http.res.header("User-Agent").contains("MSIE")
Check if the first 1024 bytes of the body of a request starts with http.req.body(1024).contains("some text")
T he following table shows examples of policy configurations and bindings for commonly used functions.
Purpose Example
Use the rewrite feature to replace occurrences of http:// with add rewrite action httpRewriteAction replace_all
https:// in the body of an HT T P response. http.res.body(50000) "\"https://\"" -pattern http://
Replace all occurrences of “abcd” with “1234” in the first 1000 add rewrite action abcdTo1234Action replace_all
bytes of the HT T P body. "http.req.body(1000)" "\"1234\"" -pattern abcd
Downgrade the HT T P version to 1.0 to prevent the server add rewrite action downgradeTo1.0Action replace
from chunking HT T P responses. http.req.version.minor "\"0\""
Remove references to the HT T P or HT T PS protocol in all add rewrite action remove_http_https replace_all
responses, so that if the user's connection is HT T P, the link is "http.res.body(1000000).set_text_mode(ignorecase)"
opened by using HT T P, and if the user's connection is HT T PS, "\"//\"" -pattern "re~https?://|HTTPS?://~"
the link is opened by using HT T PS.
add rewrite policy remove_http_https true
remove_http_https
Modify a URL to redirect from URL A to URL B. In this example, add responder action appendFile5Action redirect
“file5.html” is appended to the path. "\"http://\" + http.req.hostname + http.req.url +
\"/file5.html\"" -bypassSafetyCheck YES
T his policy uses the responder functionality.
add responder policy appendFile5Policy
"http.req.url.eq(\"/testsite\")" appendFile5Action
Redirect an external URL to an internal URL. add rewrite action act_external_to_internal REPLACE
'http.req.hostname.server' '"www.my.host.com"'
Redirect requests to www.example.com that have a query add rewrite action act_redirect_query REPLACE
string to www.Webn.example.com. T he value n is derived from q#http.req.header("Host").before_str(".example.com")'
a server parameter in the query string, for example, server=5. '"Web" + http.req.url.query.value("server")#
Limit the number of requests per second from a URL. add ns limitSelector ip_limit_selector http.req.url
"client.ip.src"
Check the client IP address but pass the request without add rewrite policy check_client_ip_policy
modifying the request. 'HTTP.REQ.HEADER("x-forwarded-for").EXISTS ||
HTTP.REQ.HEADER("client-ip").EXISTS'
NOREWRITE
Remove old headers from a request and insert an NS-Client add rewrite action del_x_forwarded_for
header. delete_http_header x-forwarded-for
Remove old headers from a request, insert an NS-Client add rewrite action del_x_forwarded_for
header, and then modify the “insert header” action so that the delete_http_header x-forwarded-for
value of the inserted header contains the client IP values from
add rewrite action del_client_ip delete_http_header
the old headers and the NetScaler appliance's connection IP
client-ip
In the following examples, you first create a rewrite action and a rewrite policy. T hen you bind the policy globally.
For more information about the commands and syntax descriptions, see Rewrite Command Reference page.
Updated: 2013-10-29
T his example describes how to create a rewrite action and rewrite policy that redirects an external URL to an internal URL.
You create an action, called act_external_to_internal, that performs the rewrite. T hen you create a policy called
pol_external_to_internal.
To redirect an external URL to an internal URL by using the command line interface
T o create the rewrite action, at the command prompt, type:
HTTP.REQ.HOSTNAME.SERVER.EQ("www.example.com")
13. Bind your new policy globally.
Redirecting a Query
T his example describes how to create a rewrite action and rewrite policy that redirects a query to the proper URL. T he
example assumes that the request contains a Host header set to www.example.com and a GET method with the string
/query.cgi?server=5. T he redirect extracts the domain name from the host header and the number from the query string,
and redirects the user’s query to the server Web5.example.com, where the rest of the user’s query is processed.
Note: Although the following commands appears on multiple lines, you should enter them on a single line without line
breaks.
To redirect a query to the appropriate URL using the command line
T o create a rewrite action named act_redirect_query that replaces the HT T P server host name with the internal server
name, type:
T o create a rewrite policy named pol_redirect_query, type the following commands at the NetScaler command prompt..
T his policy detects connections, to the Web server, that contain a query string. Do not apply this policy to connections
that do not contain a query string:
Because this rewrite policy is highly specific and should be run before any other rewrite policies, it is advisable to assign it a
high priority. If you assign it a priority of 1, it will be evaluated first.
Updated: 2014-09-17
T his example describes how to rewrite Web server responses to find all URLs that begin with the string “http” and replace
that string with “https.” You can use this to avoid having to update Web pages after moving a server from HT T P to HT T PS.
T o create a rewrite policy named pol_replace_http_with_https that detects connections to the Web server, enter the
following command:
add rewrite policy pol_replace_http_with_https T RUE act_replace_http_with_https NOREWRIT E
To troubleshoot this rewrite operation, see "Case Study: Rewrite Policy for Converting HT T P Links to HT T PS not Working."
Updated: 2013-09-02
T his example explains how to use a Rewrite policy to remove unwanted headers. Specifically, the example shows how to
remove the following headers:
Accept Encoding header. Removing the Accept Encoding header from HT T P responses prevents compression of the
response.
Content Location header. Removing the Content Location header from HT T P responses prevents your server from
providing a hacker with information that might allow a security breach.
To delete headers from HT T P responses, you create a rewrite action and a rewrite policy, and you bind the policy globally.
To create the appropriate Rewrite action by using the command line interface
At the command prompt, type one of the following commands to either remove the Accept Encoding header and prevent
response compression or remove the Content Location header:
To create the appropriate Rewrite policy by using the command line interface
At the command prompt, type one of the following commands to remove either the Accept Encoding header or the
Content Location header:
T his example explains how to use a Rewrite policy to modify connections to your home page and other URLs that end with
a forward slash (/) to the default index page for your server, preventing redirects and reducing load on your server.
T o create a Rewrite policy named policy-default-homepage that detects connections to your home page and applies
your new action, type:
T his example explains how to use a Rewrite policy to mask the information in the Server header in HT T P responses from
your Web server. T hat header contains information that hackers can use to compromise your Web site. While masking the
header will not prevent a skilled hacker from finding out information about your server, it will make hacking your Web server
more difficult and encourage hackers to choose less well protected targets.
2. T o create a Rewrite policy named pol_mask-server that detects all connections, type:
Updated: 2014-09-25
T he following policies enable the NetScaler to ensure that a client presents a valid certificate before establishing a
connection to a company’s SSL VPN.
To check for a valid client certificate by using the command line interface
Add an action to perform client certificate authentication.
add ssl policy pol1 -rule "REQ.HT T P.MET HOD == GET " -action act1
Add a rewrite action to insert the certificate issuer details into the HT T P header of the requests being sent to web
server.
Create a rewrite policy to insert the certificate issuer details, if the client certificate exists.
Bind these new policies to the NetScaler VIP to put them into effect.
Updated: 2013-09-02
Shopping cart applications handle sensitive customer information, for example, credit card numbers and expiration dates,
and they access back-end database servers. Many shopping cart applications also use legacy CGI scripts, which can contain
security flaws that were unknown at the time they were written, but are now known to hackers and identity thieves.
Cookie tampering. If a shopping cart application uses cookies, and does not perform the appropriate checks on the
T he following configuration will protect a shopping cart application against these and other attacks.
Note that if you are using the command line, you configure these settings by typing the following at the prompt, and
pressing ENT ER:
2. For the Cookie Consistency check and Form Field Consistency checks, disable blocking, and enable learning, logging,
statistics, using a similar method to the Modify Start URL Check configuration.
If you are using the command line, you configure these settings by typing the following commands:
3. For the SQL Injection check, disable blocking, and enable learning, logging, statistics, and transformation of special
characters in the Modify SQL Injection Check dialog box, General tab, Check Actions section.
If you are using the command line, you configure these settings by typing the following at the prompt, and pressing
ENT ER:
4. For the Credit Card check, disable blocking; enable logging, statistics, and masking of credit card numbers; and enable
protection for those credit cards you accept as forms of payment.
If you are using the configuration utility, you configure blocking, logging, statistics, and masking (or x-out) in the
Modify Credit Card Check dialog box, General tab, Check Actions section. You configure protection for specific
credit cards in the Settings tab of the same dialog box.
For <name> you substitute the name of the credit card you want to protect. For Visa, you substitute VISA. For
Master Card, you substitute MasterCard. For American Express, you substitute Amex. For Discover, you substitute
Discover. For Diners Club, you substitute DinersClub. For JCB, you substitute JCB.
8. Create a policy named shopping_cart that detects connections to your shopping cart application and applies the
shopping_cart profile to those connections.
To detect connections to the shopping cart, you examine the URL of incoming connections. If you host your shopping
cart application on a separate host (a wise measure for security and other reasons), you can simply look for the presence
of that host in the URL. If you host your shopping cart in a directory on a host that handles other traffic, as well, you
must determine that the connection is going to the appropriate directory and/or HT ML page.
T he process for detecting either of these is the same; you create a policy based on the following expression, and
substitute the proper host or URL for <string>.
Because you want to ensure that this policy will match all connections to the shopping cart, and not be preempted by
another more general policy, you should assign a high priority to it. If you assign one (1) as the priority, no other policy can
preempt this one.
Updated: 2013-11-14
Web pages with embedded scripts, especially legacy JavaScripts, often violate the “same origin rule,” which does not allow
scripts to access or modify content on any server but the server where they are located. T his security vulnerability is called
cross-site scripting. T he application firewall Cross-Site Scripting rule normally filters out requests that contain cross-site
scripting.
Unfortunately, this can cause Web pages with older JavaScripts to stop functioning, even when your system administrator
has checked those scripts and knows that they are safe. T he example below explains how to configure the application
firewall to allow cross-site scripting in Web pages from trusted sources without disabling this important filter for the rest of
your Web sites.
To protect Web pages with cross-site scripting by using the command line
interface
At the command line, to create an advanced profile, type:
set appfw profile pr_xssokay -startURLAction NONE -startURLClosure OFF -cookieConsistencyAction LEARN LOG
STAT S -fieldConsistencyAction LEARN LOG STAT S -crossSiteScriptingAction LEARN LOG STAT S$"
Create a policy that detects connections to your scripted Web pages and applies the pr_xssokay profile, type:
add appfw policy pol_xssokay "REQ.HT T P.HEADER URL CONTAINS ^\.pl\?$ || REQ.HT T P.HEADER URL CONTAINS ^\.js$"
pr_xssokay
To protect Web pages with cross-site scripting by using the configuration utility
1. Navigate to Security > Application Firewall > Profiles.
2. In the details view, click Add.
3. In the Create Application Firewall Profile dialog box, create a Web Application profile with advanced defaults and name it
pr_xssokay. Click Create and then click Close.
4. In the details view, click the profile, click Open, and in the Configure Web Application Profile dialog box, configure the
pr_xssokay profile as shown below.
Updated: 2013-09-02
T he following example describes how to create a DNS action and DNS policy that detects connections from unwanted IPs
or networks, such as those used in a DDOS attack, and drops all packets from those locations. T he example shows
networks within the IANA reserved IP block 192.168.0.0/16. A hostile network will normally be on publicly routable IPs.
To drop packets from specific IPs by using the command line interface
T o create a DNS policy named pol_ddos_drop that detects connections from hostile networks and drops those packets,
For the example networks in the 192.168.0.0/16 range, you substitute the IP and netmask in ###.###.###.###/##
format of each network you want to block. You can include as many networks as you want, separating each
CLIENT.IP.SRC.IN_SUBNET(###.###.###.###./##) command with the OR operator.
Globally bind your new policy to put it into effect.
Updated: 2013-09-02
T he following example shows an SSL policy that checks the user's client certificate validity before initiating an SSL
connection with a client.
Create an SSL action named act_current_client_cert that requires that users have a current client certificate to
establish an SSL connection with the NetScaler.
Create an SSL policy named pol_current_client_cert that detects connections to the Web server that contain a query
string.
add ssl policy pol_current_ client_cert 'REQ.SSL.CLIENT.CERT.VALIDFROM >= "Mon, 01 Jan 2007 00:00:00 GMT "'
act_block_ssl
Because this SSL policy should apply to any user’s SSL connection unless a more specific SSL policy applies, you may want
to assign it a low priority. If you assign it a priority of one thousand (1000), that should ensure that other SSL policies are
evaluated first, meaning that this policy will apply only to connections that do not match more specific policy criteria.
Following are examples of mod_rewrite functions, and translations of these functions into Rewrite and Responder policies on the NetScaler.
On some Web servers you can have multiple URLs for a resource. Although the canonical URLs should be used and distributed, other URLs can exist as shortcuts or internal URLs. You can make sure
that users see the canonical URL regardless of the URL used to make an initial request.
You can enforce the use of a particular host name for reaching a site. For example, you can enforce the use of www.example.com instead of example.com.
Apache mod_rewrite solution f or enf orcing a particular host name f or sites running on a port other than 80
Usually the document root of a Web server is based on the URL “/”. However, the document root can be any directory. You can redirect traffic to the document root if it changes from the top-level
“/” directory to another directory.
In the following examples, you change the document root from / to /e/www. T he first two examples simply replace one string with another. T he third example is more universal because, along with
replacing the root directory, it preserves the rest of the URL (the path and query string), for example, redirecting /example/file.html to /e/www/example/file.html.
You may want to redirect requests that are sent to home directories on a Web server to a different Web server. For example, if a new Web server is replacing an old one over time, as you migrate
home directories to the new location you need to redirect requests for the migrated home directories to the new Web server.
In the following examples, the host name for the new Web server is newserver.
Typically, a site with thousands of users has a structured home directory layout. For example, each home directory may reside under a subdirectory that is named using the first character of the user
name. For example, the home directory for jsmith (/~jsmith/anypath) might be /home/j/smith/.www/anypath, and the home directory for rvalveti (/~rvalveti/anypath) might be
/home/r/rvalveti/.www/anypath.
add rewrite action act1 replace 'HTTP.REQ.URL' '"/home/"+ HTTP.REQ.URL.AFTER_STR("~").PREFIX(1)+"/"+ HTTP.REQ.URL.AFTER_STR("~").BEFORE_STR("/")+"/.www"+HTTP.REQ.URL.SKIP(\'/\',1)' -byp
add rewrite policy pol1 'HTTP.REQ.URL.PATH.STARTSWITH("/~")' act1
bind rewrite global pol1 100
Redirecting Invalid URLs to Other Web Servers
If a URL is not valid, it should be redirected to another Web server. For example, you should redirect to another Web server if a file that is named in a URL does not exist on the server that is named in
the URL.
On Apache, you can perform this check using mod_rewrite. On the NetScaler, an HT T P callout can check for a file on a server by running a script on the server. In the following NetScaler examples, a
script named file_check.cgi processes the URL and uses this information to check for the presence of the target file on the server. T he script returns T RUE or FALSE, and the NetScaler uses the value
that the script returns to validate the policy.
In addition to performing the redirection, the NetScaler can add custom headers or, as in the second NetScaler example, it can add text in the response body.
You can rewrite a URL based on the time. T he following examples change a request for example.html to example.day.html or example.night.html, depending on the time of day.
If you rename a Web page, you can continue to support the old URL for backward compatibility while preventing users from recognizing that the page was renamed.
In the first two of the following examples, the base directory is /~quux/. T he third example accommodates any base directory and the presence of query strings in the URL.
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^foo\.html$ bar.html
NetScaler solution f or managing a file name change in a fixed location
If you rename a Web page, you may want to continue to support the old URL for backward compatibility and allow users to see that the page was renamed by changing the URL that is displayed in
the browser.
In the first two of the following examples, redirection occurs when the base directory is /~quux/. T he third example accommodates any base directory and the presence of query strings in the URL.
Apache mod_rewrite solution f or changing the file name and the URL displayed in the browser
RewriteEngine on
RewriteBase /~quux/
RewriteRule ^old\.html$ new.html [R]
NetScaler solution f or changing the file name and the URL displayed in the browser
To accommodate browser-specific limitations— at least for important top-level pages— it is sometimes necessary to set restrictions on the browser type and version. For example, you might want to
set a maximum version for the latest Netscape variants, a minimum version for Lynx browsers, and an average feature version for all others.
T he following examples act on the HT T P header "User-Agent", such that if this header begins with "Mozilla/3", the page MyPage.html is rewritten to MyPage.NS.html. If the browser is "Lynx" or
"Mozilla" version 1 or 2, the URL becomes MyPage.20.html. All other browsers receive page MyPage.32.html.
You can block a robot from retrieving pages from a specific directory or a set of directories to ease up the traffic to and from these directories. You can restrict access based on the specific location
or you can block requests based on information in User-Agent HT T P headers.
In the following examples, the Web location to be blocked is /~quux/foo/arc/, the IP addresses to be blocked are 123.45.67.8 and 123.45.67.9, and the robot’s name is NameOfBadRobot.
If you find people frequently going to your server to copy inline graphics for their own use (and generating unnecessary traffic), you may want to restrict the browser’s ability to send an HT T P Referer
header.
To prevent users from knowing application or script details on the server side, you can hide file extensions from users. To do this, you may want to support extensionless links. You can achieve this
behavior by using rewrite rules to add an extension to all requests, or to selectively add extensions to requests.
T he first two of the following examples show adding an extension to all request URLs. In the last example, one of two file extensions is added. Note that in the last example, the mod_rewrite module
can easily find the file extension because this module resides on the Web server. In contrast, the NetScaler must invoke an HT T P callout to check the extension of the requested file on the Web
server. Based on the callout response, the NetScaler adds the .html or .php extension to the request URL.
Note: In the second NetScaler example, an HT T P callout is used to query a script named file_check.cgi hosted on the server. T his script checks whether the argument that is provided in the callout is a
valid file name.
Apache mod_rewrite solution f or adding a .php extension to all requests
RewriteCond %{REQUEST_FILENAME}.php -f
RewriteRule ^/?([a-zA-Z0-9]+)$ $1.php [L]
RewriteCond %{REQUEST_FILENAME}.html –f
RewriteRule ^/?([a-zA-Z0-9]+)$ $1.html [L]
NetScaler policy f or adding either .html or .php extensions to requests
Suppose that you have a set of working URLs that resemble the following:
/index.php?id=nnnn
To change these URLs to /nnnn and make sure that search engines update their indexes to the new URI format, you need to do the following:
Redirect the old URIs to the new ones so that search engines update their indexes.
Rewrite the new URI back to the old one so that the index.php script runs correctly.
To accomplish this, you can insert marker code into the query string (making sure that the marker code is not seen by visitors), and then removing the marker code for the index.php script.
T he following examples redirect from an old link to a new format only if a marker is not present in the query string. T he link that uses the new format is re-written back to the old format, and a
marker is added to the query string.
To make sure that only secure servers are used for selected Web pages, you can use the following Apache mod_rewrite code or NetScaler Responder policies.
You can monitor and control the rate of traffic that is associated with virtual and user-defined entities, including virtual
servers, URLs, domains, and combinations of URLs and domains. You can throttle the rate of traffic if it is too high, base
information caching on the traffic rate, and redirect traffic to a given load balancing virtual server if the traffic rate exceeds
a predefined limit. You can apply rate-based monitoring to HT T P, TCP, and DNS requests.
To monitor the rate of traffic for a given scenario, you configure a rate limit identifier. A rate limit identifier specifies numeric
thresholds such as the maximum number of requests or connections (of a particular type) that are permitted in a specified
time period called a time slice.
Optionally, you can configure filters, known as stream selectors, and associate them with rate limit identifiers when you
configure the identifiers. After you configure the optional stream selector and the limit identifier, you must invoke the limit
identifier from a default syntax policy. You can invoke identifiers from any feature in which the identifier may be useful,
including rewrite, responder, DNS, and integrated caching.
You can globally enable and disable SNMP traps for rate limit identifiers. Each trap contains cumulative data for the rate
limit identifier's configured data collection interval (time slice), unless you specified multiple traps to be generated per time
slice. For more information about configuring SNMP traps and managers, see "SNMP."
A stream selector consists of individual default syntax expressions called selectlets. Each selectlet is a non-compound
default syntax expression. A traffic stream selector can contain up to five non-compound expressions called selectlets.
Each selectlet is considered to be in an AND relationship with the other expressions. Following are some examples of
selectlets:
http.req.url
http.res.body(1000>after_str(\"car_model\").before_str(\"made_in\")"
"client.ip.src.subnet(24)"
T he order in which you specify parameters is significant. For example, if you configure an IP address and a domain (in that
order) in one selector, and then specify the domain and the IP address (in the reverse order) in another selector, the
NetScaler considers these values to be unique. T his can lead to the same transaction being counted twice. Also, if multiple
policies invoke the same selector, the NetScaler, again, can count the same transaction more than once.
Note: If you modify an expression in a stream selector, you may get an error if any policy that invokes it is bound to a new
policy label or bind point. For example, suppose that you create a stream selector named myStreamSelector1, invoke it from
myLimitID1, and invoke the identifier from a DNS policy named dnsRateLimit1. If you change the expression in
myStreamSelector1, you might receive an error when binding dnsRateLimit1 to a new bind point. T he workaround is to
modify these expressions before creating the policies that invoke them.
To configure a traf fic stream selector by using the command line interf ace
Navigate to AppExpert > Rate Limiting > Selectors, click Add and specify the relevant details.
Note: T he maximum length for storing string results of selectors (for example, HT T P.REQ.URL) is 60 characters. If the string (for example, URL) is 1000 characters long, of which 50
characters are enough to uniquely identify a string, use an expression to extract only the required 50 characters.
To configure a traf fic limit identifier f rom the command line interf ace
add ns limitIdentifier <limitIdentifier> -threshold <positive_integer> -timeSlice <positive_integer> -mode <mode> -limitT ype ( BURST Y | SMOOT H ) -selectorName <string>
-maxBandwidth <positive_integer> -trapsInT imeSlice <positive_integer>
Argument description
limitIdentifier. Name for a rate limit identifier. Must begin with an ASCII letter or underscore (_) character, and must consist only of ASCII alphanumeric or underscore characters.
Reserved words must not be used. T his is a mandatory argument. Maximum Length: 31
threshold. A maximum number of requests that are allowed in the given timeslice when requests (mode is set as REQUEST _RAT E) are tracked per timeslice. When connections
(mode is set as CONNECT ION) are tracked, it is the total number of connections that would be let through. Default value: 1 Minimum value: 1 Maximum Value: 4294967295
timeSlice. T ime interval, in milliseconds, specified in multiples of 10, during which requests are tracked to check if they cross the threshold. T his argument is needed only when the
mode is set to REQUEST _RAT E. Default value: 1000 Minimum value: 10 Maximum Value: 4294967295
mode. Defines the type of traffic to be tracked. * REQUEST _RAT E - Tracks requests/timeslice. * CONNECT ION - Tracks active transactions.
selectorName. Name of the rate limit selector. If this argument is NULL, rate limiting will be applied on all traffic received by the virtual server or the NetScaler (depending on
whether the limit identifier is bound to a virtual server or globally) without any filtering. Maximum Length: 31
maxBandwidth. Maximum bandwidth permitted, in kbps. Minimum value: 0 Maximum value: 4294967287
Example
> add ns limitIdentifier 100_request_limit -threshold 100 -timeSlice 1000 -mode REQUEST_RATE -limitType BURSTY -selectorName limit_100_requests_selector -trapsInTimeSlice 30
Configuring traffic rate limit identifier in SMOOT H mode:
> add ns limitidentifier limit_req -mode request_rate -limitType smooth -timeslice 1000 -Threshold 2000 -trapsInTimeSlice 200
To configure a traf fic limit identifier by using the configuration utility
Navigate to AppExpert > Rate Limiting > Limit Identifiers, click Add and specify the relevant details.
sys.check_limit(<limit_identifier>)
T he policy expression must be a compound expression that contains at least two components:
An expression that identifies traffic to which the rate limit identifier is applied. For example:
http.req.url.contains("my_aspx.aspx").
An expression that identifies a rate limit identifier, for example, sys.check_limit("my_limit_identifier"). T his must be the last expression in the
policy expression.
At the command prompt, type the following command to configure a rate-based policy and verify the configuration:
1. In the navigation pane, expand the feature in which you want to configure a policy (for example, Integrated Caching, Rewrite, or Responder),
and then click Policies.
2. In the details pane, click Add. In Name, enter a unique name for the policy.
3. Under Expression, enter the policy rule, and make sure that you include the sys.check_limit parameter as the final component of the
expression. For example:
For example, you may be required to associate the policy with an action or a profile. For more information, see the feature-specific
documentation.
To view the traf fic rate by using the command line interf ace
At the command prompt, type the following command to view the traffic rate:
sh limitsession myLimitSession
To view the traf fic rate by using the configuration utility
1. Configure a stream selector (optional) and a rate limit identifier (required). For example:
http://<IP of a vserver>/testsite/test.txt
6. At the NetScaler command prompt, type:
Example
Purpose Example
Limit the number of requests per add stream selector ipStreamSelector http.req.url "client.ip.src"
second from a URL add ns limitIdentifier ipLimitIdentifier -threshold 4 -timeSlice 1000
-mode request_rate -limitType smooth -selectorName ipStreamSelector
Drop a DNS packet if the add stream selector dropDNSStreamSelector client.udp.dns.domain client.ip.src
requests from a particular client add ns limitIdentifier dropDNSRateIdentifier -timeslice 20000 -mode request_rate
IP address and DNS domain -selectorName dropDNSStreamSelector -maxBandwidth 1 -trapsintimeslice 20
exceed the rate limit
Limit the number of HT T P add stream selector ipv6_sel "CLIENT.IPv6.src.subnet(32)" CLIENT.IPv6.dst Q.URL
requests that arrive from the add ns limitIdentifier ipv6_id -imeSlice 20000 -selectorName ipv6_sel
same host (with a subnet mask add lb vserver ipv6_vip HTTP 3ffe::209 80 -persistenceType NONE -cltTimeout 180
of 32) and that have the same add responder action redirect_page redirect "\"http://redirectpage.com/\""
destination IP address. add responder policy ipv6_resp_pol "SYS.CHECK_LIMIT(\"ipv6_id\")" redirect_page
bind responder global ipv6_resp_pol 5 END -type DEFAULT
T he first scenario describes the use of a rate-based policy that sends traffic to a new data center if the rate of DNS
requests exceed 1000 per second.
In the second scenario, if more than five DNS requests arrive for a local DNS (LDNS) client within a particular period, the
additional requests are dropped.
In this scenario, you configure a proximity-based load balancing method, and a rate-limiting policy that identifies DNS
requests for a particular region. In the rate-limiting policy, you specify a threshold of 1000 DNS requests per second. A DNS
policy applies the rate limiting policy to DNS requests for the region "Europe.GB.17.London.UK-East.ISP-UK." In the DNS
policy, DNS requests that exceed the rate limiting threshold, starting with request 1001 and continuing to the end of the
one-second interval, are to be forwarded to the IP addresses that are associated with the region "North
America.US.T X.Dallas.US-East.ISP-US."
In the following example of global server load balancing, you configure a rate limiting policy that permits a maximum of five
DNS requests in a particular interval, per domain, to be directed to an LDNS client for resolution. Any requests that exceed
this rate are dropped. T his type of policy can help protect the NetScaler from resource exploitation. For example, in this
scenario, if the time to live (T T L) for a connection is five seconds, this policy prevents the LDNS from requerying a domain.
Instead, it uses data that is cached on the NetScaler.
client.traffic_domain.id
You can configure rate limiting for traffic associated with a particular traffic domain, a set of traffic domains, or all traffic
domains.
For configuring rate limiting for traffic domains, you perform the following steps on a NetScaler appliance by using the
configuration utility or the NetScaler command line:
1. Configure a stream selector that uses the client.traffic_domain.id expression for identifying the traffic, associated with
traffic domains, to be rate limited.
2. Configure a rate limit identifier that specifies parameters such as maximum threshold for traffic to be rate limited. You
also associate a stream selector to the rate limiter in this step.
3. Configure an action that you want to associate with the policy that uses the rate limit identifier.
4. Configure a policy that uses the sys.check_limit expression prefix to call the rate limit identifier, and associate the action
with this policy.
5. Bind the policy globally.
Consider an example in which two traffic domains, with IDs 10 and 20, are configured on NetScaler ADC NS1. On traffic
domain 10, LB1-T D-1 is configured to load balance servers S1 and S2; LB2-T D1 is configured to load balance servers S3 and
S4.
On traffic domain 20, LB1-T D-2 is configured to load balance servers S5 and S6; LB2-T D2 is configured to load balance
servers S7 and S8.
T he following table lists some examples of rate limiting policies for traffic domains in the example setup.
Limit the number of requests add stream selector tdratelimit-1 CLIENT .T RAFFIC_DOMAIN.ID add ns limitIdentifier
to 10 per second for each of limitidf-1 -threshold 10 -selectorName tdratelimit-1 -trapsInT imeSlice 0 add responder
the traffic domains. policy ratelimit-pol "sys.check_limit(\"limitidf-1\")" DROP bind responder global
ratelimit-pol 1
Limit the number of requests add stream selector tdandclientip CLIENT .IP.SRC,CLIENT .T RAFFIC_DOMAIN.ID add ns
to 5 per client per second for limitIdentifier td_limitidf -threshold 5 -selectorName tdandclientip -trapsInT imeSlice 5
each of the traffic domains. add responder policy tdratelimit-pol "sys.check_limit(\"td_limitidf\")" DROP bind
responder global tdratelimit-pol 2
Limit the number of requests add stream selector tdratelimit CLIENT .T RAFFIC_DOMAIN.ID add ns limitIdentifier
sent for a particular traffic td10_limitidf -threshold 30 -timeSlice 3000 -selectorName tdratelimit -
domain (for example traffic trapsInT imeSlice 5 add responder policy td10ratelimit "client.traffic_domain.id==10 &&
domain 10) to 30 requests sys.check_limit(\"td10_limitidf\")" DROP bind responder global td10ratelimit 3
every 3 seconds.
You can collect statistics at the packet level to determine bad/attack prone packets flowing through all the connections
identified by the selector. At any point, if the percentage of bad or attack-prone packets exceed the configured threshold,
a corrective action (RESET or DROP) is triggered as per the configuration. T his functionality can be used to address DDoS
attacks involving small TCP packets in which PUSH flag is enabled.
T he following configuration demonstrates this functionality. T his configuration tracks packet credits for all the TCP
connections flowing through the system. T his creates a session and associates on pcb/natpcb and the performs the per
packet check.
Example COPY
After the configuration is complete, we must bind this responder policy globally.
Example COPY
With the Responder feature, responses can be based on who sends the request, where it is sent from, and other criteria
with security and system management implications. T he feature is simple and quick to use. By avoiding the invocation of
more complex features, it reduces CPU cycles and time spent in handling requests that do not require complex processing.
For handling sensitive data such as financial information, if you want to ensure that the client uses a secure connection to
browse a site, you can redirect the request to secure connection by using https:// instead of http://.
You can specify a default action for requests that do not match any policy, and you can bypass the safety check for
actions that would otherwise generate error messages.
T he Rewrite feature of NetScaler helps in rewriting some information in the requests or responses handled by NetScaler.
T he following section shows some differences between the two features.
T he main difference between the rewrite feature and the responder feature is as follows:
Responder cannot be used for response or server-based expressions. Responder can be used only for the following
scenarios depending on client parameters:
Redirecting a http request to new Web sites or Web pages
Responding with some custom response
Dropping or resetting a connection at request level
In case of a responder policy, the NetScaler examines the request from the client, takes action according to the applicable
policies, sends the response to the client, and closes the connection with the client.
In case of a rewrite policy, the NetScaler examines the request from the client or response from the server, takes action
according to the applicable policies, and forwards the traffic to the client or the server.
In general, it is recommended to use responder if you want the NetScaler to reset or drop a connection based on a client or
request-based parameter. Use responder to redirect traffic, or respond with custom messages. Use rewrite for manipulating
data on HT T P requests and responses.
At the command prompt, type the following commands to enable the responder feature and verify the configuration:
enable ns feature<feature>
show ns feature
Example
Redirect
Redirects the request to a different web page or web server. A Redirect action can redirect requests originally sent to a "dummy" web site that exists
in DNS, but for which there is no actual web server, to an actual web site. It can also redirect search requests to an appropriate URL. Normally, the
redirection target for a Redirect action consists of a complete URL.
Displays the current settings for the specified responder action. If no action name is provided, displays a list of all responder actions currently
configured on the NetScaler appliance, with abbreviated settings.
At the command prompt, type the following commands to configure a responder action and verify the configuration:
Arguments
bypassSaf etyCheck. T he safety check to allow unsafe expressions. NOT E: T his attribute is deprecated.
Example
To create a responder action that displays a “Not Found” error page for URLs that do not exist:
add responder action act404Error respondWith '"HT T P/1.1 404 Not Found\r\n\r\n"+ "HT T P.REQ.URL.HT T P_URL_SAFE" + "does not exist on the web
1) Name: act404Error
Operation: respondwith
Target: "HT T P/1.1 404 Not Found
"+ "HT T P.REQ.URL.HT T P_URL_SAFE" + "does not exist on the web server."
BypassSafetyCheck : NO
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
To create a responder action that displays a “Not Found” error page for URLs that do not exist:
add responder action act404Error respondWith '"HT T P/1.1 404 Not Found\r\n\r\n"+ "HT T P.REQ.URL.HT T P_URL_SAFE" + "does not exist on the web
server."'
Done
> show responder action
1) Name: act404Error
Operation: respondwith
Target: "HT T P/1.1 404 Not Found
"+ "HT T P.REQ.URL.HT T P_URL_SAFE" + "does not exist on the web server."
BypassSafetyCheck : NO
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
To modif y an existing responder action by using the command line interf ace
At the command prompt, type the following command to modify an existing responder action and verify the configuration:
set responder action <name> -target <string> [-bypassSafetyCheck ( YES | NO )]
show responder action
Example
set responder action act404Error -target '"HTTP/1.1 404 Not Found\r\n\r\n"+ "HTTP.REQ.URL.HTTP_URL_SAFE" + "does not exist on the web server."'
Done
> show responder action
1) Name: act404Error
Operation: respondwith
Target: "HTTP/1.1 404 Not Found
At the command prompt, type the following command to remove a responder action and verify the configuration:
rm responder action <name>
show responder action
1. In the Create Responder Action or Configure Responder Action dialog box, click Add.
2. In the Add Expression dialog box, in the first list box choose the first term for your expression.
HTTP
T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the HT T P protocol.
SYS
T he protected web site(s). Choose this if you want to examine some aspect of the request that pertains to the recipient of the request.
CLIENT
T he computer that sent the request. Choose this if you want to examine some aspect of the sender of the request.
ANALYTICS
T he analytics data associated with the request. Choose this if you want to examine request metadata.
SIP
A SIP request. Choose this if you want to examine some aspect of a SIP request.
When you make your choice, the rightmost list box lists appropriate terms for the next part of your expression.
3. In the second list box, choose the second term for your expression. T he choices depend upon which choice you made in the previous step, and are
appropriate to the context. After you make your second choice, the Help window below the Construct Expression window (which was blank)
displays help describing the purpose and use of the term you just chose.
4. Continue choosing terms from the list boxes that appear to the right of the previous list box, or typing strings or numbers in the text boxes that
appear to prompt you to enter a value, until your expression is finished.
You can configure the global HT T P action to invoke a responder action when an HT T P request times out. To configure this feature, you must first
create the responder action that you want to invoke. T hen, you configure the global HT T P timeout action to respond to a timeout with that
responder action.
To configure the global HTTP action by using the command line interface
At the command prompt, type the following command:
For <responder action name>, substitute the name of the responder action.
Note: For creating and managing responder policies, the configuration utility provides assistance that is not available at the
NetScaler command prompt.
To configure a responder policy by using the command line interf ace
At the command prompt, type the following command to add a new responder policy and verify the configuration:
add responder policy <name> <expression> <action> [<undefaction>]-appFlowaction<actionName>
show responder policy <name>
Example
Name: policyThree
Rule: CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)
Responder Action: RESET
UndefAction: Use Global
Hits: 0
Undef Hits: 0
Done
To modif y an existing responder policy by using the command line interf ace
At the command prompt, type the following command to modify an existing responder policy and verify the configuration:
set responder policy <name> [-rule <expression>] [-action <string>] [-undefAction <string>]
show responder policy <name>
At the command prompt, type the following command to remove a responder policy and verify the configuration:
rm responder policy <name>
show responder policy
Example
When you bind a policy, you assign a priority to it. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer.
In the NetScaler operating system, policy priorities work in reverse order— the higher the number, the lower the priority. For
example, if you have three policies with priorities of 10, 100, and 1000, the policy assigned a priority of 10 is performed first,
then the policy assigned a priority of 100, and finally the policy assigned an order of 1000. T he responder feature
implements only the first policy that a request matches, not any additional policies that it might also match, so policy
priority is important for getting the results you intend.
You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate in the order you
want, by setting priorities with intervals of 50 or 100 between each policy when you globally bind it. You can then add
additional policies at any time without having to reassign the priority of an existing policy.
For additional information about binding policies on the NetScaler, see "Policies and Expressions."
Note: Responder policies cannot be bound to T CP-based virtual servers.
To globally bind a responder policy by using the command line interf ace
At the command prompt, type the following command to globally bind a responder policy and verify the configuration:
bind responder global <policyName> <priority> [<gotoPriorityExpression [-type <type>] [-invoke (<labelT ype>
<labelName>)]
show responder global
Example
Done
To bind responder policy to a specific virtual server by using the command line interf ace
At the command prompt, type the following command to bind responder policy to a specific virtual server and verify the
configuration:
bind lb vserver <name> -policyname <policy_name> -priority <priority>
Example
To bind a responder policy to a specific virtual server by using the configuration utility
If the Web site(s) your NetScaler appliance protects receive a significant number of invalid or malicious requests, however,
you may want to change the default action to either reset the client connection or drop the request. In this type of
configuration, you would write one or more responder policies that would match any legitimate requests, and simply
redirect those requests to their original destinations. Your NetScaler appliance would then block any other requests as
specified by the default action you configured.
You can assign any one of the following actions to an undefined event:
NOOP
T he NOOP action aborts responder processing but does not alter the packet flow. T his means that the appliance
continues to process requests that do not match any responder policy, and eventually forwards them to the requested URL
unless another feature intervenes and blocks or redirects the request. T his action is appropriate for normal requests to your
Web servers and is the default setting.
RESET
If the undefined action is set to RESET , the appliance resets the client connection, informing the client that it must re-
establish its session with the Web server. T his action is appropriate for repeat requests for Web pages that do not exist, or
for connections that might be attempts to hack or probe your protected Web site(s).
DROP
If the undefined action is set to DROP, the appliance silently drops the request without responding to the client in any
way. T his action is appropriate for requests that appear to be part of a DDoS attack or other sustained attack on your
servers.
Note: UNDEF events are triggered only for client requests. No UNDEF events are triggered for responses.
To set the undefined action by using the command line interf ace
At the command prompt, type the following command to set the undefined action and verify the configuration:
set responder param -undefAction (RESET |DROP|NOOP)
show responder param
Example
1. Navigate to AppExpert > Responder, and then under Settings, click the Change Responder Settings link.
2. In the Set Responder Params dialog box, under Global Undefined-Result Action, select NOOP, RESET , or DROP.
3. Click OK. A message appears in the status bar, stating that the Responder Parameters have been configured.
T he following procedures block access to your protected Web site(s) by clients originating from the CIDR 222.222.0.0/16.
T he responder sends an error message stating that the client is not authorized to access the URL requested.
To block access by using the command line interface
At the command prompt, type the following commands to block access:
add responder action act_unauthorized respond with "HT T P/1.1 403 Forbidden\r\n\r\n" + "Client: " + CLIENT .IP.SRC + "
is not authorized to access URL:" + "HT T P.REQ.URL.HT T P_URL_SAFE"'
add responder policy pol_un "CLIENT .IP.SRC.IN_SUBNET (222.222.0.0/16)" act_unauthorized
bind responder global pol_un 10
T he following procedures redirect clients who access your protected Web site(s) from within the CIDR 222.222.0.0/16 to a
specified URL.
To redirect clients by using the command line interface
At the command prompt, type the following commands to redirect clients and verify the configuration:
add responder action act_redirect redirect '"http://www.example.com/404.html"'
show responder action act_redirect
add responder policy pol_redirect "CLIENT .IP.SRC.IN_SUBNET (222.222.0.0/16)" act_redirect
Example
> add responder action act_redirect redirect '" http ://www.example.com/404.html "'
> add responder policy pol_redirect "CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16)" act_redirect
To redirect clients by using the configuration utility
1. Navigate to AppExpert > Responder > Actions.
2. In the details pane, click Add.
3. In the Create Responder Action dialog box, do the following:
1. In the Name text box, type act_redirect.
2. Under T ype, select Redirect.
3. In the T arget text area, type the following string: "http://www.example.com/404.html"
4. Click Create, then click Close.
T he responder action you configured, named act_redirect, now appears in the Responder Actions page.
4. In the navigation pane, click Policies.
5. In the details pane, click Add.
6. In the Create Responder Policy dialog box, do the following:
1. In the Name text box, type pol_redirect.
2. Under Action, select act_redirect.
3. In the Expression window, type the following rule: CLIENT .IP.SRC.IN_SUBNET (222.222.0.0/16)
4. Click Create, then click Close.
T he responder policy you configured, named pol_redirect, now appears in the Responder Policies page.
7. Globally bind your new policy, pol_redirect, as described in "Binding a Responder Policy".
To configure the Responder feature to send a response to a diameter request, at the command prompt, type the following
commands:
Example
To create a Responder action and policy to respond to Diameter requests that originate from "host1.example.net" with a
redirect to "host.example.com", you could add the following action and policy, and bind the policy as shown.
Done
You can use RADIUS expressions to construct simple responses that do not require communication with the RADIUS server
to which the request was sent. When a responder policy matches a connection, the NetScaler ADC constructs and sends
the appropriate RADIUS response without contacting the RADIUS authentication server. For example, if the source IP
address of a RADIUS request is from a subnet that is specified in the responder policy, the NetScaler ADC can reply to that
request with an access-reject message, or can simply drop the request.
You can also create policy labels to route specific types of RADIUS requests through a series of policies that are
appropriate to those requests.
Note: T he current RADIUS expressions do not work with RADIUS IPv6 attributes.
T he NetScaler documentation for expressions that support RADIUS assumes familiarity with the basic structure and
purpose of RADIUS communications. If you need more information about RADIUS, see your RADIUS server documentation
or search online for an introduction to the RADIUS protocol.
T he following procedure uses the NetScaler command line to configure a responder action and policy, and bind the policy
to a RADIUS-specific global bind point.
In a responder configuration, you can use the following NetScaler expressions to refer to various portions of a RADIUS
request.
RADIUS.IS_CLIENT
Returns T RUE if the connection is a RADIUS client (request) message.
RADIUS.IS_SERVER
Returns T RUE if the connection is a RADIUS server (response) message.
RADIUS.REQ.CODE
Returns the number that corresponds to the RADIUS request type. A derivative of the num_at class. For example, a RADIUS
access request would return 1 (one). A RADIUS accounting request would return 4.
RADIUS.REQ.LENGTH
Returns the length of the RADIUS request, including the header. A derivative of the num_at class.
RADIUS.REQ.IDENTIFIER
Returns the RADIUS request identifier, a number assigned to each request that allows the request to be matched to the
corresponding response. A derivative of the num_at class.
RADIUS.REQ.AVP(<AVP Code No>).VALUE
Returns the value of first occurrence of this AVP as a string of type text_t.
RADIUS.REQ.AVP(<AVP code no>).INSTANCE(instance number)
Returns the specified instance of the AVP as a string of type RAVP_t. A specific RADIUS AVP can occur multiple times in a
RADIUS message. INST ANCE (0) returns the first instance, INST ANCE (1) returns second instance, and so on, up to sixteen
instances.
RADIUS.REQ.AVP(<AVP code no>).VALUE(instance number)
Returns the value of specified instance of the AVP as a string of type text_t.
RADIUS.REQ.AVP(<AVP code no>).COUNT
Returns the number of instances of a specific AVP in a RADIUS connection, as an integer.
RADIUS.REQ.AVP(<AVP code no>).EXISTS
Returns T RUE if the specified type of AVP exists in the message, or FALSE if it does not.
Response Expressions
RADIUS response expressions are identical to RADIUS request expressions, except that RES replaces REQ.
T he ADC supports expressions to typecast RADIUS AVP values to the text, integer, unsigned integer, long, unsigned long,
ipv4 address, ipv6 address, ipv6 prefix and time data types. T he syntax is the same as for other NetScaler typecast
expressions.
Example
T he ADC supports expressions to typecast RADIUS AVP values to the text, integer, unsigned integer, long, unsigned long,
ipv4 address, ipv6 address, ipv6 prefix and time data types. T he syntax is the same as for other NetScaler typecast
expressions.
RADIUS.REQ.AVP(8).VALUE(0).typecast_ip_address_at
AVP Type Expressions
T he NetScaler ADC supports expressions to extract RADIUS AVP values by using the assigned integer codes described in
RFC2865 and RFC2866. You can also use text aliases to accomplish the same task. Some examples follow.
T he values of most commonly-used RADIUS AVPs can be extracted in the same manner.
Four global bind points are available for policies that contain RADIUS expressions.
RADIUS_REQ_OVERRIDE
Priority/override request policy queue.
RADIUS_REQ_DEFAULT
Standard request policy queue.
RADIUS_RES_OVERRIDE
Priority/override response policy queue.
RADIUS_RES_DEFAULT
Standard response policy queue.
RADIUS_RESPONDWITH
Respond with the specified RADIUS response. T he response is created with NetScaler expressions, both RADIUS
expressions and any others that are applicable.
RADIUS.NEW_ANSWER
Sends a new RADIUS answer to the user.
RADIUS.NEW_ACCESSREJECT
Rejects the RADIUS request.
RADIUS.NEW_AVP
Adds the specified new AVP to the response.
Use Cases
To configure the responder feature to block authentication requests from a specific network, begin by creating a responder
action that rejects requests. Use the action in a policy that selects requests from the networks that you want to block.
Bind the responder policy to a RADIUS-specific global bind point, specifying:
T he priority
END as the nextExpr value, to ensure that policy evaluation stops when this policy is matched
RADIUS_REQ_OVERRIDE as the queue to which you assign the policy, so that it is evaluated before policies assigned
to the default queue
Example
add responder action rspActRadiusReject respondwith radius.new_accessreject
add responder policy rspPolRadiusReject client.ip.src.in_subnet(10.224.85.0/24) rspActRadiusReject
bind responder global rspPolRadiusReject 1 END -type RADIUS_REQ_OVERRIDE
DNS Expressions
In a responder configuration, you can use the following NetScaler expressions to refer to various portions of a DNS
request:
Expressions Descriptions
DNS.NEW_RESPONSE <AA, T C, rcode> Creates a new DNS response based on the specified parameters.
T he following global bind points are available for policies that contain DNS expressions.
In addition to the default bind points, you can create policy labels of type DNS and bind DNS policies to them.
T he following procedure uses the NetScaler command line to configure a responder action and policy and bind the policy to
a responder-specific global bind point.
Example
To enforce all the DNS requests over TCP, create a responder action that will set the TC bit and rcode as NOERROR.
Resources f or Troubleshooting
Updated: 2013-07-22
For best results, use the following resources to troubleshoot an integrated cache issue on a NetScaler appliance:
T he ns.conf file
T he relevant trace files from the client and the NetScaler appliance
Updated: 2013-07-29
Issue
T he Responder feature is configured, but the responder action is not working.
Resolution
Verify that the feature is enabled.
Check the hit counters of any of the policies to see if the counters are getting incremented.
Verify that the policies and actions are configured correctly.
Verify that the actions and policies are bound appropriately.
Record the packet traces on the client and the NetScaler appliance, and analyze the them to get some pointer to the
issue.
Record the iehttpHeaters packet traces on the client and verify the HT T P requests and responses to get some
pointer to the issue.
Issue
You need to create a maintenance page.
Resolution
1. Configure the services and virtual Server.
2. Configure a backup virtual server with a service bound to it. T his ensures that the status of the Web site is always
displayed as UP.
3. Configure the primary virtual server to use the backup virtual server as a backup.
4. Create a responder action with an appropriate target. Following is an example for your reference:
add responder action sorry_page respondwith q{"HTTP/1.0 200 OK" +"\r\n\r\n" + "<html><body>Sorry, this page is not
available</body></html>" + "\r\n"} .
T o improve security, the NetScaler can rewrite all the http:// links to https:// in the response body.
In the SSL offload deployment, the insecure links in the response have to be converted into secure links. Using the
rewrite option, you can rewrite all the http:// links to https:// for making sure that the outgoing responses from
NetScaler to the client have the secured links.
If a Web site has to show an error page, you can show a custom error page instead of the default 404 Error page. For
example, if you show the home page or site map of the Web site instead of an error page, the visitor remains on the site
instead of moving away from the Web site.
If you want to launch a new Web site, but use the old URL, you can use the Rewrite option.
When a topic in a site has a complicated URL, you can rewrite it with a simple, easy-to-remember URL (also referred to as
'cool URL').
You can append the default page name to the URL of a Web site. For example, if the default page of a company's Web
site is 'http://www.abc.com/index.php', when the user types 'abc.com' in the address bar of the browser, you can rewrite
the URL to 'abc.com/index.php'.
When you enable the rewrite feature, NetScaler can modify the headers and body of HT T P requests and responses.
T o rewrite HT T P requests and responses, you can use protocol-aware NetScaler policy expressions in the rewrite policies
you configure. T he virtual servers that manage the HT T P requests and responses must be of type HTTP or SSL. In HT T P
traffic, you can take the following actions:
Modify the URL of a request
Add, modify or delete headers
Add, replace, or delete any specific string within the body or headers.
To rewrite TCP payloads, consider the payload as a raw stream of bytes. Each of the virtual servers that managing the TCP
connections must be of type TCP or SSL_TCP. T he term TCP rewrite is used to refer to the rewrite of TCP payloads that
are not HT T P data. In TCP traffic, you can add, modify, or delete any part of the TCP payload.
For examples to use the rewrite feature, see Rewrite Action and Policy Examples.
T he main difference between the rewrite feature and the responder feature is as follows:
Responder cannot be used for response or server-based expressions. Responder can be used only for the following
scenarios depending on client parameters:
Redirecting a http request to new Web sites or Web pages
Responding with some custom response
Dropping or resetting a connection at request level
In case of a responder policy, the NetScaler examines the request from the client, takes action according to the applicable
policies, sends the response to the client, and closes the connection with the client.
In general, it is recommended to use responder if you want the NetScaler to reset or drop a connection based on a client or
request-based parameter. Use responder to redirect traffic, or respond with custom messages. Use rewrite for manipulating
data on HT T P requests and responses.
A bind point refers to a point in the traffic flow at which the NetScaler examines the traffic to verify whether any rewrite
policy can be applied to it. You can bind a policy to a specific load balancing or content switching virtual server, or make the
policy global if you want the policy to be applied to the entire traffic handled by the NetScaler. T hese policies are referred
to as global policies.
In addition to the user-defined policies, the NetScaler has some default policies. You cannot modify or delete a default
policy.
For evaluating the policies, NetScaler follows the order mentioned below:
Global policies
Policies bound to specific virtual servers
Default policies
Note: NetScaler can apply a rewrite policy only when it is bound to a point.
NetScaler implements the rewrite feature in the following steps:
T he NetScaler appliance checks for global policies and then checks for policies at individual bind points.
If multiple policies are bound to a bind point, the NetScaler evaluates the policies in the order of their priority. T he policy
with the highest priority is evaluated first. After evaluating each policy, if the policy is evaluated to T RUE (the traffic
matches the rule), it adds the action associated with the policy to a list of actions to be performed. A match occurs
when the characteristics specified in the policy rule match the characteristics of the request or response being
evaluated.
For any policy, in addition to the action, you can specify the policy that should be evaluated after the current policy is
evaluated. T his policy is referred to as the 'Go to Expression'. For any policy, if a Go to Expression (gotoPriorityExpr) is
specified, the NetScaler evaluates the Go to Expression policy; it ignores policy with the next highest priority.
You can specify the priority of the policy to indicate the Go to Expression policy; you cannot use the name of the policy.
If you want the NetScaler to stop evaluating other policies after evaluating a particular policy, you can set the Go to
Expression to 'END'.
After all the policies are evaluated or when a policy has the Go to Expression set as END, the NetScaler starts
performing the actions according to the list of actions.
For more information about configuring rewrite policies, see "Configuring a Rewrite Policy" and about binding rewrite
policies, see "Binding a Rewrite Policy."
T he following figure illustrates how NetScaler processes a request or response when the rewrite feature is used.
T he policy with the highest priority is evaluated first. NetScaler does not stop the evaluation of rewrite policies when it
finds a match; it evaluates all the rewrite policies configured on the NetScaler.
INVOCAT ION_LIST Goto NEXT or END is applied based on the result of the invocation list.
If a policy evaluates to FALSE, the NetScaler continues the evaluation in the order of priority.
If a policy evaluates to UNDEFINED (cannot be evaluated on the received traffic due to an error), the NetScaler
performs the action assigned to the UNDEFINED condition (referred to as undefAction) and stops further evaluation of
polices.
T he NetScaler starts the actual rewriting only after the evaluation is complete. It refers to the list of actions identified by
policies that are evaluated to T RUE, and starts the rewriting. After implementing all the actions in the list, the NetScaler
forwards the traffic as required.
On the NetScaler appliance, specify the actions to be taken such as adding, replacing, or deleting text within the body, or
adding, modifying or deleting headers, or any changes in the TCP payload as rewrite actions. For more information about
rewrite actions, see "Configuring a Rewrite Action."
T he following table describes the steps the NetScaler can take when a policy evaluates to T RUE.
Action Result
NOREWRIT E T he request or response is not rewritten. NetScaler forwards the traffic without rewriting any part of
the message.
Note: For any policy, you can configure the undefaction (action to be taken when the policy evaluates to UNDEFINED) as
NOREWRIT E, RESET , or DROP.
T o use the Rewrite feature, take the following steps:
Enable the feature on the NetScaler.
Define rewrite actions.
Define rewrite policies.
Bind the policies to a bind point to bring a policy into effect.
At the command prompt, type the following commands to enable the rewrite feature and verify the configuration:
enable ns feature REWRIT E
show ns feature
Example
Warning
T he Pattern function in a rewrite action is deprecated from NetScaler 12.0 build 56.20 onwards and as an alternative, Citrix
recommends you to use the Search rewrite action parameter.
After enabling the rewrite feature, you need to configure one or more actions unless a built-in rewrite action is sufficient.
All of the built-in actions have names beginning with the string ns_cvpn, followed by a string of letters and underscore
characters. Built-in actions perform useful and complex tasks such as decoding parts of a clientless VPN request or
response or modifying JavaScript or XML data. T he built-in actions can be viewed, enabled, and disabled, but cannot be
modified or deleted.
T arget expressions in actions for T CP rewrite must begin with one of the following expression prefixes:
CLIENT.TCP.PAYLOAD. For rewriting T CP payloads in client requests. For example,
CLIENT.TCP.PAYLOAD(10000).AFTER_STR("string1").
SERVER.TCP.PAYLOAD. For rewriting T CP payloads in server responses. For example,
SERVER.TCP.PAYLOAD(1000).B64DECODE.BETWEEN("string1","string2").
You can use all types of existing string manipulation functions with these prefixes to identify the strings that you want to
rewrite. T o configure a rewrite action, you assign it a name, specify an action type, and add one or more arguments
specifying additional data. T he following table describes the action types and the arguments you use with them.
Note: Action types that can be used only for HT T P rewrite are identified in the Rewrite Action Type column.
Table 1. Rewrite Action Types and Their Arguments
INSERT_HTTP_HEADER: Inserts the HT T P T he HT T P header you want to insert. A string expression that
header you specify into the HT T P request or describes the contents of
response. T his is the default choice. T his For example, if you want to insert the
the header you want to
action type can be used only with HT T P client IP from which a request is sent,
insert.
requests and responses. type Client-IP.
For example, if you want
to insert the Client IP
from which a request is
sent, type CLIENT.IP.SRC.
INSERT_BEFORE: Inserts a new string before A string expression that describes the A string expression that
the designated string. string before which you want to insert a describes the new string
new string. you want to insert.
For example, if you want to find the For example, if you want
hostname www.example.com and insert to insert the new string
a string before the example.com portion, en. before the string
INSERT_AFTER: Inserts a new string after the A string expression that describes the A string expression that
designated string. string after which you want to insert a describes the new string
new string. you want to insert.
For example, if you want to find the For example, if you want
hostname www.example.com, and insert to insert the new string
a string after the www. portion, type the en. after the string www.
following: in the hostname, type en
HT T P.REQ.HOST NAME.AFT ER_ST R followed by a period.
("www.")
REPLACE: Replaces the designated string with A string expression that describes the A string expression that
a different string. string you want to replace with a new describes the new string
string. you want to insert.
For example, if you want to replace the For example, if you want
entire hostname in the Host header, to replace the current
type HT T P.REQ.HOST NAME.SERVER. host header with the
string web01.example.net,
type web01.example.net.
DELETE: Deletes the designated string. A string expression that describes the
string you want to delete.
REPLACE_ALL: Will replace all occurrences of a T he part of either the HT T P request or A string expression that
pattern in the target text reference with the response where you want to carry out describes the new string
value specified in the string builder expression. the replacement. you want to insert.
DELETE_ALL: Delete every occurrence of the T he part of either the HT T P request or A string pattern after
pattern specified in the target text reference. response where you want the deletion which the deletion should
to occur. occur.
INSERT_AFTER_ALL: Inserts the value T he part of either the HT T P request or A string expression that
specified by string builder expression after response where you want the insertion describes the new string
each occurrence of a specified pattern in the to occur. you want to insert.
target text reference.
INSERT_BEFORE_ALL: Inserts the value you T he part of either the HT T P request or A string expression that
specify before each occurrence of the response that you want to delete. describes the new string
pattern you specify. you want to insert.
To create a new rewrite action by using the command line interf ace
At the command prompt, type the following commands to create a new rewrite action and verify the configuration:
add rewrite action <name> <type> <target> [<stringBuilderExpr>] [(-pattern <expression> | -patset <string>)] [-
bypassSafetyCheck (YES|NO)]
show rewrite action <name>
Name: insertact
Operation: insert_http_header Target:Client-IP
Value:CLIENT.IP.SRC
BypassSafetyCheck : NO
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
Example 2: Replacing Strings in a TCP Payload (TCP Rewrite)
Name: client_tcp_payload_replace_all
Operation: replace_all
Target:client.tcp.payload(1000)
Value:"new-string"
Search: text("old-string")
BypassSafetyCheck : NO
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
>
To modif y an existing rewrite action by using the command line interf ace
At the command prompt, type the following commands to modify an existing rewrite action and verify the configuration:
set rewrite action <name> [-target <string>] [-stringBuilderExpr <string>] [(-pattern <expression> | -patset <string>)] [-
bypassSafetyCheck (YES|NO)]
show rewrite action <name>
Name: insertact
Operation: insert_http_header Target:Client-IP
Value:CLIENT.IP.SRC
BypassSafetyCheck : NO
Hits: 0
Undef Hits: 0
Action Reference Count: 0
Done
To remove a rewrite action by using the command line interf ace
At the command prompt, type the following commands to remove a rewrite action :
rm rewrite action <name>
Example
1. In the Create Rewrite Action or Configure Rewrite Action dialog box, under the text area for the type argument you
want to enter, click Add.
2. In the Add Expression dialog box, in the first list box choose the first term for your expression.
HTTP
T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the HT T P
protocol.
SYS
T he protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to the
recipient of the request.
CLIENT
T he computer that sent the request. Choose this if you want to examine some aspect of the sender of the request.
When you make your choice, the rightmost list box lists appropriate terms for the next part of your expression.
For more information about the PI expressions language and creating expressions for responder policies, see "Policies
and Expressions."
If you want to test the effect of a rewrite action when used on sample HT T P data, you can use the Rewrite Expression
Evaluator.
Note: T he Rewrite Expression Evaluator is only available in the configuration utility. T here is no NetScaler command line
version.
To evaluate a rewrite action by using the Rewrite Action Evaluator dialog box
1. In the Rewrite Actions details pane, select the rewrite action that you want to evaluate, and then click Evaluate.
2. In the Rewrite Expression Evaluator dialog box, specify values for the following parameters. (An asterisk indicates a
required parameter.)
Rewrite Action*— If the rewrite action you want to evaluate is not already selected, select it from the drop-down list.
After you select a Rewrite action, the Details section displays the details of the selected Rewrite action.
New*— Select New to open the Create Rewrite Action dialog box and create a new rewrite action.
Modify*— Select Modify to open the Configure Rewrite Action dialog box and modify the selected rewrite action.
Flow T ype*— Specifies whether to test the selected rewrite action with HT T P Request data or HT T P Response
data. T he default is Request. If you want to test with Response data, select Response.
HT T P Request/Response Data*— Provides a space for you to provide the HT T P data that the Rewrite Action
Evaluator will use for testing. You can paste the data directly into the window, or click Sample to insert some sample
HT T P headers.
Show end-of-line— Specifies whether to show UNIX-style end-of-line characters (\n) at the end of each line of
sample HT T P data.
Sample— Inserts sample HT T P data into the HT T P Request/Response Data window. You can choose either GET or
POST data.
Browse— Opens a local browse window so that you can choose a file containing sample HT T P data from a local or
network location.
Clear— Clears the current sample HT T P data from the HT T P Request/Response Data window.
3. Click Evaluate. T he Rewrite Action Evaluator evaluates the effect of the Rewrite action on the sample data that you
chose, and displays the results as modified by the selected Rewrite action in the Results window. Additions and deletions
are highlighted as indicated in the legend in the lower left-hand corner of the dialog box.
4. Continue evaluating Rewrite actions until you have determined that all of your actions have the effect that you wanted.
You can modify the selected rewrite action and test the modified version by clicking Modify to open the Configure
Rewrite Action dialog box, making and saving your changes, and then clicking Evaluate again.
You can evaluate a different rewrite action using the same request or response data by selecting it from the Rewrite
Action drop-down list, and then clicking Evaluate again.
5. Click Close to close the Rewrite Expression Evaluator and return to the Rewrite Actions pane.
To delete a rewrite action, select the rewrite action you want to delete, then click Remove and, when prompted, confirm
your choice by clicking OK.
A rewrite policy consists of a rule, which itself consists of one or more expressions, and an associated action that is
performed if a request or response matches the rule. Policy rules for evaluating HT T P requests and responses can be based
on almost any part of a request or response.
Even though you cannot use TCP rewrite actions to rewrite data other than the TCP payload, you can base the policy rules
for TCP rewrite policies on the information in the transport layer and the layers below the transport layer.
If a configured rule matches a request or response, the corresponding policy is triggered and the action associated with it is
carried out.
Note: You can use either the command line interface or the configuration utility to create and configure rewrite policies.
Users who are not thoroughly familiar with the command line interface and the NetScaler Policy expression language will
usually find using the configuration utility much easier.
To add a new rewrite policy by using the command line interf ace
At the command prompt, type the following commands to add a new rewrite policy and verify the configuration:
add rewrite policy <name> <expression> <action> [<undefaction>]
show rewrite policy <name>
Done
Example 2: Rewriting a TCP Payload (TCP Rewrite)
Done
>
To modif y an existing rewrite policy by using the command line interf ace
At the command prompt, type the following commands to modify an existing rewrite policy and verify the configuration:
set rewrite policy <name> -rule <expression> -action <action> [<undefaction>]
show rewrite policy <name>
Example
Done
To remove a rewrite policy by using the command line interf ace
At the command prompt, type the following command to remove a rewrite policy:
rm rewrite policy <name>
Example
Rewrite policies for evaluating HT T P requests and responses can be bound to virtual servers of type HT T P or SSL, or they
can be bound to the REQ_OVERRIDE, REQ_DEFAULT, RES_OVERRIDE, and RES_DEFAULT bind points. Rewrite
policies for T CP rewrite can be bound only to virtual servers of type TCP or SSL_TCP, or to the
OTHERTCP_REQ_OVERRIDE, OTHERTCP_REQ_DEFAULT, OTHERTCP_RES_OVERRIDE, and
OTHERTCP_RES_DEFAULT bind points.
Note: T he term OTHERTCP is used in the context of the NetScaler appliance to refer to all TCP or SSL_TCP requests
and responses that you want to treat as a raw stream of bytes regardless of the protocols that the T CP packets
encapsulate.
When you bind a policy, you assign it a priority. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer.
In the NetScaler operating system, policy priorities work in reverse order - the higher the number, the lower the priority. For
example, if you have three policies with priorities of 10, 100, and 1000, the policy assigned a priority of 10 is applied first, then
the policy assigned a priority of 100, and finally the policy assigned an order of 1000.
Unlike most other features in the NetScaler operating system, the rewrite feature continues to evaluate and implement
policies after a request matches a policy. However, the effect of a particular action policy on a request or response will
often be different depending on whether it is performed before or after another action. Priority is important to get the
results you intended.
You can leave yourself plenty of room to add other policies in any order, and still set them to evaluate in the order you
want, by setting priorities with intervals of 50 or 100 between each policy when you bind it. If you do this, you can add
additional policies at any time without having to reassign the priority of an existing policy.
When binding a rewrite policy, you also have the option of assigning a goto expression (gotoPriorityExpression) to the
policy. A goto expression can be any positive integer that matches the priority assigned to a different policy that has a
higher priority than the policy that contains the goto expression. If you assign a goto expression to a policy, and a request
or response matches the policy, the NetScaler will immediately go to the policy whose priority matches the goto
expression. It will skip over any policies with priority numbers that are lower than that of the current policy, but higher than
the priority number of the goto expression, and not evaluate those policies.
To globally bind a rewrite policy by using the command line interf ace
At the command prompt, type the following commands to globally bind a rewrite policy and verify the configuration:
bind rewrite global <policyName> <priority> [<gotoPriorityExpression>] [-type <type>] [-invoke (<labelT ype>
<labelName>) ]
show rewrite global
Example
Done
To bind rewrite policy to a specific virtual server by using the command line interf ace
At the command prompt, type the following commands to bind rewrite policy to a specific virtual server and verify the
configuration:
bind lb vserver <name>@ (<serviceName>@ [-weight <positive_integer>]) | <serviceGroupName>@ | (-policyName
<string>@ [-priority <positive_integer>] [-gotoPriorityExpression <expression>] [-type ( REQUEST | RESPONSE )] [-invoke
(<labelT ype> <labelName>) ] )
show lb vserver <name>
Example
To bind a rewrite policy to a specific virtual server by using the configuration utility
A rewrite policy label consists of a name, a transform name that describes the type of policy included in the policy label, and
a list of policies bound to the policy label. Each policy that is bound to the policy label contains all of the elements described
in "Configuring a Rewrite Policy."
Note: You can use either the command line interface or the configuration utility to create and configure rewrite policy
labels. Users who are not thoroughly familiar with the command line interface and the NetScaler Policy Infrastructure (PI)
language will usually find using the configuration utility much easier.
To configure a rewrite policy label by using the command line interf ace
To add a new rewrite policy label, at the command prompt, type the following command:
For example, to add a rewrite policy label named polLabelHTTPResponses to group all policies that work on HT T P
responses, you would type the following:
To modify an existing rewrite policy label, at the NetScaler command prompt, type the following command:
Note: T he set rewrite policy command takes the same options as the add rewrite policy command.
To remove a rewrite policy label, at the NetScaler command prompt, type the following command:
rm rewrite policy<name>
For example, to remove a rewrite policy label named polLabelHTTPResponses, you would type the following:
To remove a policy label, select it, and then click Remove. To rename a policy label, select it and then click Rename. Edit
the name of the policy, and then click OK to save your changes.
Note: Undefined events can be triggered for both request and response flow specific policies.
To configure the def ault action by using the command line interf ace
At the command prompt, type the following commands to configure the default action and verify the configuration:
set rewrite param -undefAction ( NOREWRIT E | RESET | DROP )
show rewrite param
Example
In some cases, the expressions may be safe. For example, the NetScaler cannot validate an expression that contains a URL
that does not resolve, even if the URL does not resolve because the Web server is temporarily unavailable. You can manually
bypass the Safety Check to allow these expressions.
To bypass the saf ety check by using the command line interf ace
At the command prompt, type the following commands to bypass the safety check and verify the configuration:
set rewrite action <name> -bypassSafetyCheck YES
show rewrite action <name>
Example
Name: insertact
Operation: insert_http_header Target:Client-IP
Value:CLIENT.IP.SRC
BypassSafetyCheck : YES
Hits: 0
Undef Hits: 0
Action Reference Count: 2
Done
To bypass saf ety check by using the configuration utility
Example Manufacturing has two domains: example.com for its Web site and email to customers, and example.net for its
intranet. Customers use the Example Web site to place orders, request quotes, research products, and contact customer
service and technical support.
As an important part of Example's revenue stream, the Web site must respond quickly and keep customer data confidential.
Example therefore has several Web servers and uses Citrix NetScaler appliances to balance the Web site load and manage
traffic to and from its Web servers.
T he Example system administrators use the rewrite features to perform the following tasks:
Example Inc. removes old X-Forwarded-For and Client-IP HT T P headers from incoming requests.
Example Inc. tags incoming requests with a header that indicates whether the connection is a secure connection.
Example Inc. modifies the HT T P Server: header so that unauthorized users and malicious code cannot use that header to
determine the HT T P server software it uses.
Example Inc. hides information about the actual names of its Web servers and the configuration of its server room from
users, to make URLs on its Web site shorter and easier to remember and to improve security on its site.
Example Inc. moved its Apache rewrite rules to a NetScaler appliance, translating the Apache PERL-based script syntax to
the NetScaler rewrite rule syntax.
T he marketing department at Example Inc. sets up simplified URLs for certain predefined keyword searches on the
company’s Web site.
Example Inc. recently acquired a smaller competitor, and it now redirects requests to the acquired company’s home page to
a page on its own Web site.
Example Inc. encrypt HT T P predefined and user-defined header or body content by using PEM RSA public key.
Each of these tasks requires that the system administrators create rewrite actions and policies and bind them to a valid
bind point on the NetScaler.
T he examples below demonstrate how to perform each configuration with both the CLI and the configuration utility. T he
procedures are abbreviated on the assumption that users will already know the basics of creating rewrite actions, creating
rewrite policies, and binding policies.
For more detailed information about creating rewrite actions, see Configuring a Rewrite Action.
For more detailed information about creating rewrite policies, see Configuring a Rewrite Policy.
For more detailed information about binding rewrite policies, see Binding a Rewrite Policy.
To delete old X-Forwarded and Client-IP headers f rom a request by using the command line interf ace
At the command prompt, type the following commands in the order shown:
In the Create Rewrite Action dialog box, create two rewrite actions with the following descriptions.
In the Create Rewrite Policy dialog box, create two rewrite policies with the following descriptions.
Bind both policies to global, assigning the priorities and goto expression values shown below.
All old X-Forwarded-For and Client-IP HT T P headers are now deleted from incoming requests.
To add a local Client-IP header by using the command line interf ace
At the command prompt, type the following commands in the order shown:
In the Create Rewrite Action dialog box, create a rewrite action with the following description.
In the Create Rewrite Policy dialog box, create a rewrite policy with the following description.
Bind policy to global, assigning the priorities and goto expression values shown below.
A local Client-IP HT T P header is now added to incoming requests. You can also modify the configuration above to append all IPs from X-
Forwarded-For headers to the new Client-IP header, as shown below.
T o implement this configuration, you would begin by creating rewrite actions with the values shown in the following tables.
T hese actions label connections to port 80 as insecure connections, and connections to port 443 as secure connections.
You would then create a rewrite policy with the values shown in the following tables. T hese policies check incoming
requests to determine which requests are directed to port 80 and which are directed to port 443. T he policies then add the
correct SSL header.
Finally, you would bind the rewrite policies to NetScaler, assigning the first policy a priority of 200, and the second a priority
of 300, and setting the goto expression of both policies to END.
Each incoming connection to port 80 now has an SSL:NO HT T P header added to it and each incoming connection to port
443 has an SSL:YES HT T P header added to it.
To modify the HT T P Server: header, you would create a rewrite action and a rewrite policy with the values in the following
tables.
You would then globally bind the rewrite policy, assigning a priority of 100 and setting the Goto Priority Expression of the
policy to END.
T he HT T P Server: header is now modified to read “Web Server 1.0,” masking the actual HT T P server software used by the
Example Inc. Web site.
To do this, you would create a rewrite action with the values as shown in the following tables. For request headers, the action in the
table modifies www.example.com to web.hq.example.net. For response headers, the action does the opposite, translating
web.hq.example.net to www.example.com.
Next, you would create rewrite policies using the values shown in the following tables. T he first policy checks incoming requests to see
if they are valid, and if they are, it performs the Action-Rewrite-Request_Server_Replace action. T he second policy checks responses to
see if they originate at the server web.hq.example.net. If they do, it performs the Action-Rewrite-Response_Server_Replace action.
Finally, you would bind the rewrite policies, assigning each a priority of 500 because they are in different policy banks and therefore will
not conflict. You should set the goto expression to NEXT for both bindings.
All instances of www.example.com in the request headers are now changed to web.hq.example.net, and all instances of
web.hq.example.net in response headers are now changed to www.example.com.
Several Apache rewrite rules that Example currently uses are shown below. T hese rules redirect search requests to a special results page if they do not have a SiteID string or if
they have a SiteID string equal to zero (0), or to the standard results page if these conditions do not apply.
To implement these Apache rewrite rules on the NetScaler, you would create rewrite actions with the values in the following tables.
Action Name Type of Rewrite Action Expression to choose target ref erence String expression f or replacement text
You would then create rewrite policies with the values as shown in the tables below.
Finally, you would bind the rewrite policies, assigning the first a priority of 600 and the second a priority of 700, and then set the goto expression to NEXT for both bindings.
T he NetScaler now handles these search requests exactly as the Web server did before the Apache rewrite module rules were migrated.
To set up redirection for marketing keywords, you would create a rewrite action with the values in the following table.
You would then create a rewrite policy with the values in the following table.
Finally, you would bind the rewrite policy, assigning it a priority of 800. Unlike the previous rewrite policies, this policy should
be the last to be applied to a request that matches its criteria. For this reason, NetScaler administrator sets its Goto Priority
Expression to END.
Any request using a marketing keyword is redirected to the keyword search CGI page, whereupon a search is performed and
all remaining policies are skipped.
To implement this redirection, you would first create a rewrite action with the values in the following table.
Action Name Type of Expression to choose target ref erence String expression f or
Rewrite replacement text
Action
You would then create a rewrite policy with the values in the following table.
Finally, you would bind the rewrite policy, assigning it a priority of 900. Because this policy should be the last policy applied to a request
that matches its criteria, you set the goto expression to END.
Incoming requests to any URL that begins with http://www.example.com/query.cgi?server= are redirected to the server number in the
query.
To redirect requests to the Purchased Company home page, you would create rewrite actions with the values in the
following table.
You would then create rewrite policies with the values in the following table.
Finally, you would bind the rewrite policies globally, assigning the first a priority of 100, the second a priority of 200, and the
third a priority of 300. T hese policies should be the last policies applied to a request that matches the criteria. For this
reason, set the goto expression to END for the first and third policies, and to 300 for the second policy. T his ensures that
all remaining requests are processed correctly.
Requests to the acquired company's old Web site are now redirected to the correct page on the New Company home
page.
In a sample scenario, the function can be used with B64ENCODE() function in a rewrite action to replace an HT T P header
value with a value encrypted by an RSA public key. T he data being encrypted is then decrypted by the recipient using the
RSA private key.
You can implement the feature by using a rewrite policy. To do this, you must complete the following tasks:
To add RSA public key as a policy expression by using the NetScaler command interf ace
Code COPY
T he PEM RSA_Public_Key format that use the following header and footer works correct with pkey_encrypt_pem method.
Note
RSA public key should have RSA keyword in header and footer both.
Note
If the size of the RSA public key is greater than 1024 bits it might not fit into one string (maximum 255 bytes allowed). In such
scenarios, you must use a string concatenation to append more string literals.
To add rewrite an action to encrypt an HT T P header request by using the NetScaler command interface
Code COPY
'HTTP.REQ.HEADER("data_to_encrypt").PKEY_ENCRYPT_PEM(pubkey).B64ENCODE'
Code COPY
Code COPY
Code COPY
>curl -v -H "data_to_encrypt: Now is the time that tries men's souls" http://10.217.24.7/
* Trying 10.217.24.7...
* connected
>
< Content-Length: 44
<
Subsequent execution of this curl command with the same data to encrypt shows that the encrypted data is different
each execution. T his is because the padding inserts random bytes at the beginning of the data to encrypt, causing the
encrypted data to be different each time.
>curl -v -H "data_to_encrypt: Now is the time that tries men's souls" http://10.217.24.7/
...
>curl -v -H "data_to_encrypt: Now is the time that tries men's souls" http://10.217.24.7/
...
To add RSA public key as a policy expression by using the NetScaler GUI
1. Sign into the NetScaler appliance and navigate to Conf igurations > AppExpert > Advanced Expressions.
2. In the details pane, click Add to define an RSA public key as an advanced policy expression.
3. In Create Expression page, set the following parameters:
1. Expression name. Name of the advanced expression.
2. Expression. Define RSA public key as an advanced expression using the Expression Editor.
3. Comments. A brief description of the expression.
4. Click Create.
To add rewrite an action to encrypt an HT T P header request by using the NetScaler GUI
1. Sign into the NetScaler appliance and navigate to Conf igurations > AppExpert > Rewrite > Actions.
2. In the details pane, click Add to add a rewrite action.
3. In the Create Rewrite Action screen, set the following parameters:
1. Name. Name of the rewrite action.
1. Sign into the NetScaler appliance and navigate to Conf igurations > AppExpert > Rewrite > Policies.
2. In the Rewrite Policies page, click Add to add a rewrite policy.
3. In the Create Rewrite Policy page, set the following parameters:
1. Name. Name of the rewrite policy.
2. Action. Name of the rewrite action to perform if the request or response matches this rewrite policy.
3. Log Action. Name of message log action to use when a request matches this policy.
4. Undefined-Result Action. Action to perform if the result of policy evaluation is undefined.
5. Expression. Name of the advanced policy expression that triggers the action.
6. Comments. A brief description of the rewrite action.
4. Click Create.
1. Sign into the NetScaler appliance and navigate to Conf igurations > AppExpert > Rewrite > Policies.
2. In the Rewrite Policies screen, select a rewrite policy that you want to bind and click Policy Manager.
3. In the Rewrite Policy Manager page, in the Bind Points section, set the following parameters:
1. Bind Point. Select the binding point as Default Global.
2. Protocol. Select the protocol type as HT T P.
3. Connection T ype. Select the connection type as Request.
4. Click Continue to view the Policy Binding section.
5. In the Policy Binding section, select the rewrite policy and set the bind parameters.
4. Click Bind.
Note
Before you can use the URL transformation feature, you must enable the Rewrite feature. To enable the Rewrite feature, see
Enabling the Rewrite Feature.
URL transform feature rewrites URLs in HT ML response body and is not applied to JavaScript and other variables.
To begin configuring URL transformation, you create profiles, each describing a specific transformation. Within each profile,
you create one or more actions that describe the transformation in detail. Next, you create policies, each of which
identifies a type of HT T P request to transform, and you associate each policy with an appropriate profile. Finally, you
globally bind each policy to put it into effect.
You cannot create actions and then add them to a profile. You must create the profile first, and then add actions to it. In the CLI, creating an action and configuring the action are separate steps.
Creating a profile and configuring the profile are separate steps in both the CLI and the configuration utility.
To create a URL transf ormation profile by using the NetScaler command line
At the NetScaler command prompt, type the following commands, in the order shown, to create a URL transformation profile and verify the configuration. You can then repeat the second and third
commands to configure additional actions:
add transform profile <profileName> -type URL [-onlyT ransformAbsURLinBody (ON|OFF)] [-comment <comment>]
add transform action <name> <profileName> <priority>
set transform action <name> [-priority <priority>] [-reqUrlFrom <expression>] [-reqUrlInto <expression>] [-resUrlFrom <expression>] [-resUrlInto <expression>] [-cookieDomainFrom <expression>] [-
cookieDomainInto <expression>] [-state (ENABLED|DISABLED)] [-comment "<string>"]
show transform profile <name>
Example
At the NetScaler command prompt, type the following commands to modify an existing URL transformation profile or action and verify the configuration:
Note: Use a set transform profile or set transform action command, respectively. T he set transform profile command takes the same arguments as does the add transform profile command, and set
transform action is the same command that was used for initial configuration.
set transform action <name> [-priority <priority>] [-reqUrlFrom <expression>] [-reqUrlInto <expression>] [-resUrlFrom <expression>] [-resUrlInto <expression>] [-cookieDomainInto <expression>] [-
state (ENABLED|DISABLED)] [-comment "<string>"]
show transform profile <name>
Example
> set transform action actshopping -priority 1000 -reqUrlFrom 'searching.example.net' -reqUrlInto 'www.example.net/searching' -resUrlFrom 'www.example.net/searching' -resUrlInto 'searching.example.com' -cookie
Done
> show transform profile shoppingcart
Name: shoppingcart
Type: URL onlyTransformAbsURLinBody: OFF
Comment:
Actions:
First remove all actions associated with that profile by typing the following command once for each action:
rm transform action <name> After you have removed all actions associated with a profile, remove the profile as shown below.
rm transform profile <name>
1. In the navigation pane, expand Rewrite, expand URL T ransformation, and then click Profiles.
2. In the details pane, click Add.
3. In the Create URL T ransformation Profile dialog box, type or select values for the parameters. T he contents of the dialog box correspond to the parameters described in "Parameters for
configuring URL transformation profiles" as follows (asterisk indicates a required parameter):
Name*— name
Comment— comment
Only transform absolute URLs in response body— onlyT ransformAbsURLinBody
4. Click Create, and then click Close. A message appears in the status bar, stating that the Profile has been configured successfully.
To configure a URL transf ormation profile and actions by using the configuration utility
1. In the navigation pane, expand Rewrite, expand URL T ransformation, and then click Profiles.
2. In the details pane, select the profile you want to configure, and then click Open.
3. In the Configure URL T ransformation Profile dialog box, do one of the following.
You must create a new policy. On the command line, an existing policy can only be removed. At the NetScaler command
prompt, type the following commands to configure a URL transformation policy and verify the configuration:
add transform policy <name> <rule> <profileName>
show transform policy <name>
Example
At the NetScaler command prompt, type the following command to remove a URL transformation policy:
rm transform policy <name>
Example
1. In the navigation pane, expand Rewrite, expand URL T ransformation, and then click Policies.
2. In the details pane, do one of the following:
T o create a new policy, click Add.
T o modify an existing policy, select the policy, and then click Open.
3. In the Create URL T ransformation Policy or Configure URL T ransformation Policy dialog box, type or select values for the
parameters. T he contents of the dialog box correspond to the parameters described in "Parameters for configuring URL
transformation policies" as follows (asterisk indicates a required parameter):
Name*— name (Cannot be changed for a previously configured policy.)
Profile*— profileName
Expression— rule
HT T P— T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the
HT T P protocol.
SYS— T he protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to
the recipient of the request.
CLIENT — T he computer that sent the request. Choose this if you want to examine some aspect of the sender of
the request.
SERVER— T he computer to which the request was sent. Choose this if you want to examine some aspect of the
recipient of the request.
URL— T he URL of the request. Choose this if you want to examine some aspect of the URL to which the request
was sent.
T EXT — Any text string in the request. Choose this if you want to examine a text string in the request.
T ARGET — T he target of the request. Choose this if you want to examine some aspect of the request target.
After you choose a prefix, the NetScaler displays a two-part prompt window that displays the possible next
choices at the top, and a brief explanation of what the selected choice means at the bottom. T he choices depend
on which prefix you chose.
When you are certain which choice you want, double-click it to insert it into the Expression window.
3. T ype a period, and then continue selecting terms from the list boxes that appear to the right of the previous list box.
You type the appropriate text strings or numbers in the text boxes that appear to prompt you to enter a value, until
your expression is finished.
4. Click Create or OK, depending on whether you are creating a new policy or modifying an existing policy.
5. Click Close. A message appears in the status bar, stating that the Policy has been configured successfully.
1. In the Create Responder Action or Configure Responder Action dialog box, click Add.
2. In the Add Expression dialog box, in the first list box choose the first term for your expression.
HTTP
T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the HT T P
protocol.
SYS
T he protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to the
recipient of the request.
CLIENT
T he computer that sent the request. Choose this if you want to examine some aspect of the sender of the request.
When you make your choice, the rightmost list box lists appropriate terms for the next part of your expression.
3. In the second list box, choose the second term for your expression. T he choices depend upon which choice you made in
the previous step, and are appropriate to the context. After you make your second choice, the Help window below the
Construct Expression window (which was blank) displays help describing the purpose and use of the term you just chose.
4. Continue choosing terms from the list boxes that appear to the right of the previous list box, or typing strings or
numbers in the text boxes that appear to prompt you to enter a value, until your expression is finished.
When you bind a policy, you assign a priority to it. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer. In the NetScaler OS, policy priorities work in reverse order - the
higher the number, the lower the priority.
Because the URL transformation feature implements only the first policy that a request matches, not any additional
policies that it might also match, policy priority is important for achieving the results that you intend. If you give your first
policy a low priority (such as 1000), you tell the NetScaler to perform it only if other policies with a higher priority do not
match a request. If you give your first policy a high priority (such as 1), you tell the NetScaler to perform it first, and skip any
other policies that might also match. You can leave yourself plenty of room to add other policies in any order, without
having to reassign priorities, by setting priorities with intervals of 50 or 100 between each policy when you globally bind your
policies.
At the NetScaler command prompt, type the following commands to globally bind a URL transformation policy and verify
the configuration:
bind transform global <policyName> <priority>
show transform global
Example
Done
1. In the navigation pane, expand Rewrite, then expand URL T ransformation, and then click Policies.
2. In the details pane, click Policy Manager.
3. In the T ransform Policy Manager dialog box, choose the bind point to which you want to bind the policy. T he choices
are:
Override Global. Policies that are bound to this bind point process all traffic from all interfaces on the NetScaler
appliance, and are applied before any other policies.
LB Virt ual Server. Policies that are bound to a load balancing virtual server are applied only to traffic that is
processed by that load balancing virtual server, and are applied before any Default Global policies. After selecting LB
Virtual Server, you must also select the specific load balancing virtual server to which you want to bind this policy.
You can use the new RADIUS expressions in Rewrite rules for a number of purposes. For example, you could:
Remove the domain\ portion of the RADIUS user-name AVP to simplify single sign-on (SSO).
Insert a vendor-specific AVP, such as the MSISDN field used in telephone company operations to contain subscriber information.
You can also create policy labels to route specific types of RADIUS requests through a series of policies that are appropriate to those requests.
T he NetScaler documentation for expressions that support RADIUS assumes familiarity with the basic structure and purpose of RADIUS communications. If you need more information
about RADIUS, see your RADIUS server documentation or search online for an introduction to the RADIUS protocol.
T he following procedure uses the NetScaler command line to configure a rewrite action and policy and bind the policy to a rewrite-specific global bind point.
In a rewrite configuration, you can use the following NetScaler expressions to refer to various portions of a RADIUS request or response.
RADIUS.IS_CLIENT
Returns T RUE if the connection is a RADIUS client (request) message.
RADIUS.IS_SERVER
Returns T RUE if the connection is a RADIUS server (response) message.
Request Expressions
RADIUS.REQ.CODE
Returns the number that corresponds to the RADIUS request type. A derivative of the num_at class. For example, a RADIUS access request would return 1 (one). A RADIUS accounting
request would return 4.
RADIUS.REQ.LENGT H
Returns the length of the RADIUS request, including the header. A derivative of the num_at class.
RADIUS.REQ.IDENT IF IER
Returns the RADIUS request identifier, a number assigned to each request that allows the request to be matched to the corresponding response. A derivative of the num_at class.
RADIUS.REQ.AVP (<AVP Code No>).VALUE
Returns the value of first occurrence of this AVP as a string of type text_t.
RADIUS.REQ.AVP (<AVP code no>).INST ANCE(inst ance number)
Returns the specified instance of the AVP as a string of type RAVP_t. A specific RADIUS AVP can occur multiple times in a RADIUS message. INST ANCE (0) returns the first instance,
INST ANCE (1) returns second instance, and so on, up to sixteen instances.
RADIUS.REQ.AVP (<AVP code no>).VALUE(inst ance number)
Returns the value of specified instance of the AVP as a string of type text_t.
RADIUS.REQ.AVP (<AVP code no>).COUNT
Returns the number of instances of a specific AVP in a RADIUS connection, as an integer.
RADIUS.REQ.AVP (<AVP code no>).EXIST S
Returns T RUE if the specified type of AVP exists in the message, or FALSE if it does not.
Response Expressions
RADIUS response expressions are identical to RADIUS request expressions, except that RES replaces REQ.
Example
T he ADC supports expressions to typecast RADIUS AVP values to the text, integer, unsigned integer, long, unsigned long, ipv4 address, ipv6 address, ipv6 prefix and time data types. T he
syntax is the same as for other NetScaler typecast expressions.
RADIUS.REQ.AVP(8).VALUE(0).typecast_ip_address_at
AVP T ype Expressions
T he NetScaler ADC supports expressions to extract RADIUS AVP values by using the assigned integer codes described in RFC2865 and RFC2866. You can also use text aliases to
accomplish the same task. Some examples follow.
T he values of most commonly-used RADIUS AVPs can be extracted in the same manner.
Four global bind points are available for policies that contain RADIUS expressions.
RADIUS_REQ_OVERRIDE
Priority/override request policy queue.
RADIUS_REQ_DEF AULT
Standard request policy queue.
RADIUS_RES_OVERRIDE
Priority/override response policy queue.
RADIUS_RES_DEF AULT
Standard response policy queue.
RADIUS.NEW_AVP
Returns the specified RADIUS AVP as a string.
RADIUS.NEW_AVP _INT EGER32
Returns the specified RADIUS AVP as an integer.
RADIUS.NEW_AVP _UNSIGNED32
Returns the specified RADIUS AVP as an unsigned integer.
RADIUS.NEW_VENDOR_SP EC_AVP (<ID>, <def init ion>)
Adds the specified extended vendor specific AVPs to the connection. For <ID>, substitute a long number. For <definition>, substitute a string that contains the data for the AVP.
RADIUS.REQ.AVP _ST ART
Returns the location between the end of the RADIUS header and the start of the AVPs. Used in rewrite actions.
Example:
Example:
Example:
add rewrite action insert3 insert_before_all radius.req.avp_list "radius.new_avp(33, \"NEW AVP\")" -search "avp(33)"
T he Rewrite action types that can be used with RADIUS expressions are:
INSERT _AFT ER
INSERT _BEFORE
INSERT _AFT ER_ALL
INSERT _BEFORE_ALL
All INSERT _ actions can be used to insert a RADIUS AVP into a RADIUS connection.
To configure the rewrite feature to remove the Domain\ string from the RADIUS user-name AVP, begin by creating a rewrite REPLACE action as shown in the example below. Use the
action in a Rewrite policy that selects all RADIUS requests. Bind the policy to a global bind point. When you do so, set the priority the appropriate level to allow any block or reject
policies to take effect first, but ensure that all requests that are not blocked or rejected are rewritten. Set the Goto Expression (gotoPriorityExpr) to NEXT to continue policy
evaluation, and attach the policy to the RADIUS_REQ_DEFAULT queue.
Example:
To configure Rewrite action to insert a Vendor-Specific AVP containing the contents of the MSISDN field, begin by creating a rewrite INSERT action that inserts the MSISDN field into
the request. Use the action in a Rewrite policy that selects all RADIUS requests. bind the policy to global, setting the priority to an appropriate level and the other parameters as shown
in the following example.
Example:
add rewrite action rwActRadiusInsMSISDN insert_after radius.req.avp_start RADIUS.NEW_VENDOR_SPEC_AVP(<VENDOR ID>, "RADIUS.NEW_AVP(<Attribute Code>, <MSISDN>)")
add rewrite policy rwPolRadiusInsMSISDN true rwActRadiusInsMSISDN
bind rewrite global rwPolRadiusInsMSISDN 100 NEXT -type RADIUS_REQ_DEFAULT
To configure the Rewrite feature to replace the Origin-Host in a diameter request with a different value, at the command
prompt, type the following commands:
Example
To create a Rewrite action and policy to modify all Diameter Host-Origins of "host.example.com" to
"netscaler.example.net", you could add the following action and policy, and bind the policy as shown.
Done
DNS Expressions
In a rewrite configuration, you can use the following NetScaler expressions to refer to various portions of a DNS request or
response:
DNS.REQ.HEADER.FLAGS.IS_SET <FLAG> Returns T rue if any of the following flags are set in the
DNS request.
QR
AA
TC
RD
RA
AD
CD
DNS.REQ.HEADER.OPCODE.EQ <pcode types> Checks the opcode type in the DNS request. Returns
T rue or False, indicating whether the opcode type in the
DNS request matches the specified opcode type.
DNS.RES.HEADER.FLAGS.IS_SET <FLAG> Returns T rue if any of the following specified flags are
set in the DNS response.
QR
AA
TC
RD
RA
AD
CD
DNS.REQ.HEADER.OPCODE.NE <opcode type> Checks the opcode type in the DNS request. Returns
T rue or False, indicating whether the opcode type in the
DNS request matches the specified opcode type.
DNS.REQ.HEADER.OPCODE.SET <opcode type> Sets the specified opcode type in the DNS request.
DNS.RES.HEADER.RCODE.SET <rcode type> Sets the rcode type in the DNS response.
DNS.NEW_RRSET _A <ip_add, ttl> Replaces the Answer section in the DNS response with
the specified IPv4 address and T T L value.
DNS.NEW_RRSET _AAAA <ipv6, ttl> Replaces the Answer section in the DNS response with
the specified IPv6 address and T T L value.
DNS.REQ.HEADER.FLAGS.GET _ST RING_REPRESENT AT ION Returns the DNS flags in string format that can be used
for audit logging.
DNS.RES.HEADER.FLAGS.GET _ST RING_REPRESENT AT ION Returns the DNS flags in string format that can be used
for audit logging.
T he following global bind points are available for policies that contain DNS expressions.
In addition to the default bind points, you can create policy labels of type DNS_REQ or DNS_RES and bind DNS policies
to them.
replace_dns_answer_sect ion — T his action replaces the DNS answers section with the defined expression in the DNS
policy.
replace_dns_header_f ield — Checks the opcode type in the DNS request. Returns T rue or False, indicating whether
the opcode type in the DNS request matches the specified opcode type. T his action replaces the DNS header section
with the defined expression in the DNS policy.
The following procedure uses the NetScaler command line to configure a rewrite action and policy and bind the policy to a rewrite-specific global bind point.
To configure Rewrite action and policy, and bind the policy for DNS
Example
The following commands configure the NetScaler appliance to act as an authoritative DNS server for all the queries that it serves.
If the server responds with an NX domain, you can set the rewrite action to replace the response with specified IP address. A NOPOLICY-REWRITE enables you to
invoke an enternal bank without processing an expression (a rule). This entry is a dummy policy that does not contain a rule but directs the entry to a policy label or
virtual server specific policy banks.
A policy configuration that uses string maps performs better than one that does string matching through policy expressions, and you need fewer
policies to perform string matching with a large number of key-value pairs. String maps are also intuitive, simple to configure, and result in a smaller
configuration.
String maps are similar in structure to pattern sets (a pattern set defines a mapping of index values to strings; a string map defines a mapping of
strings to strings) and the configuration commands for string maps (commands such as add, bind, unbind, remove, and show) are syntactically
similar to configuration commands for pattern sets. Also, as with index values in a pattern set, each key in a string map must be unique across the
map. T he following table illustrates a string map called url_string_map, which contains URLs as keys and values.
Key Value
/url_1.html http://www.redirect_url_1.com/url_1.html
/url_2.html http://www.redirect_url_2.com/url_2.html
/url_3.html http://www.redirect_url_1.com/url_1.html
T he following table describes the two functions that have been introduced to enable string matching with keys in a string map. String matching is
always performed with the keys. Additionally, the following functions perform a comparison between the keys in the string map and the complete
string that is returned by the expression prefix. T he examples in the descriptions refer to the preceding example.
<TEXT>.MAP_STRING(<string_map_name>) Checks whether the value returned by the expression prefix TEXT matches any of the
keys in the string map, and returns the value that corresponds to the key. If no key in
the string map matches the value returned by the expression prefix, the function
returns a null string. T he IGNORECASE and NOIGNORECASE functions can be used
for case-insensitive and case-sensitive comparison, respectively.
Example 2:
HTTP.REQ.URL.SET_TEXT_MODE(IGNORECASE).MAP_STRING("url_string_map")
checks whether the string returned by HTTP.REQ.URL is a key in the string map
url_string_map. T he comparison does not consider case. If the string returned by
HTTP.REQ.URL is /URL_1.html, the function returns
http://www.redirect_url_1.com/url_1.html.
Paramet ers:
<TEXT>.IS_STRINGMAP_KEY(<string_map_name>) Returns TRUE if the string returned by the expression prefix TEXT is a key in the
string map. T he IGNORECASE and NOIGNORECASE functions can be used for
case-insensitive and case-sensitive string matching, respectively.
Example 1:
Example 2: HTTP.REQ.URL.SET_TEXT_MODE(IGNORECASE).
IS_STRINGMAP_KEY("url_string_map") returns TRUE if the value of
HTTP.REQ.URL is one of the keys in url_string_map. In this case, key lookup does
not consider case. T herefore, the function returns TRUE even if the value of
HTTP.REQ.URL is /URL_3.html.
Paramet ers:
You first create a string map and then bind key-value pairs to it. You can create a string map from the command line interface (CLI) or the
configuration utility.
Example:
Create a string map and bind the key-value pair to the created entity.
Navigate to AppExpert > St ring Maps , click Add and specify the relevant details.
T he following use case involves a responder policy with a redirect action. In the example below, the first four commands create the string map
url_string_map and bind the three key-value pairs used in the earlier example. After creating the map and binding the key-value pairs, you create a
responder action (act_url_redirects) that redirects the client to the corresponding URL in the string map or to www.default.com. You also configure
a responder policy (pol_url_redirects) that checks whether requested URLs match any of the keys in url_string_map and then performs the
configured action. Finally, you bind the responder policy to the content switching virtual server that receives the client requests that are to be
evaluated.
You can configure a stream selector and a responder policy to collect statistics at the packet level and identify defective or
attack-prone packets flowing through all the connections identified by the selector. If, at any point, the percentage of
defective or attack-prone packets exceeds the configured threshold, the policy applies a corrective action (RESET or
DROP). You can use this functionality to address DDoS attacks involving small TCP packets in which the PUSH flag is
enabled.
T he following example demonstrates this functionality. T his configuration tracks packet credits for all the TCP connections
flowing through the system. T his creates a session and associates on pcb or natpcb and checks each packet.
Where <max_threshold_percentage> is any value from 0 to 100 and <action> can be either DROP or RESET.
After the selector and the responder policy are configured, the policy is bound globally.
Getting Started
Using Advanced Policy Expressions for URL Evaluation
Configuring a URL Set
URL Pattern Semantics
Blacklisted URL Categories
T he NetScaler appliance uses advanced policies to determine whether an incoming URL should be blocked, allowed, or
redirected. T hese policies use advanced expressions to evaluate incoming URLs against blacklisted entries. An entry can
include metadata. For entries that have no metadata, you might want to use an expression that evaluates the URL on the
basis of an exact string match. For other URLs, you might want to use an expression that evaluates the URL’s metadata, in
addition to an expression that checks for an exact string match.
A URL set enables an Internet Service Provider (ISP) or a Telco customer to enforce government mandated safe internet
access policies such as:
1. Block access to illegal internet sites (child abuse, drugs, and so on)
2. Safe browsing for children
A NetScaler appliance enables you to periodically download URL sets managed by internet enforcement agencies or
independent internet organizations such as IWF (Internet Watch Foundation). T he appliance periodically downloads the list
and updates it securely. T he list is stored as confidential URL sets so that it is not tampered or human readable. T he
periodically downloaded URL set functions as a blacklisted set for URL evaluation purposes.
If you have a private URL set and the contents of the list are kept confidential and the network administrator does not
know about the blacklisted URLs present in the list. To make sure if the policy is configured correctly and the correct list is
referenced to evaluate an incoming URL, you configure an internal URL called Canary URL and add it to the URL set. Using
the Canary URL, the administrator can request through the appliance use the private URL set to ensure it is looked up for
every URL request.
Evaluates to T RUE if the URL exactly matches any entry in the URL
<URL expression>.URLSET _MAT CHES_ANY
set.
<URL
expression>.GET _URLSET _METADATA(<URLSET >). Evaluates to T RUE if the matched metadata is at the beginning of
the category. T his pattern can be used to encode separate fields
T YPECAST _LIST _T (‘,’).GET (0).EQ(<CAT EGORY>) within metadata, but match only the 1st field.
Joins the host and URL parameters, which can then be used as a
HT T P.REQ.HOST NAME.APPEND(HT T P.REQ.URL)
<URL expression> for matching.
1. Import a URL set (download and encrypt it). Importing a URL set in a NetScaler appliance allows you to download the URL
file, adding the file to the appliance, and then encrypting the file. Until you add the URL set to the system, it will not be
visible to the user.
1. Download a URL set once from a specific URL using HT T P and HT T PS supported for the file download.
3. Downloading a URL set periodically, using a scheduler that periodically downloads or imports URL sets for
example, IWF URL set. T he time interval is set in seconds for example, http://10.29.102.200/urls.txt -interval 3600.
http://10.102.145.135/top10k
http://10.102.145.135/blacklists/audio-video/categorized_av
T he imported URL set is further categorized into different categories and category groups in the database. T his is valid only
if categories exist in the metadata of the URL set file.
Not e : T here can be a chance that you might have URL patterns without metadata.
Once you have downloaded the file, it is pushed into the appliance and at this point of interval, you can update, delete or
display file properties. After the file is pushed into the appliance, you can modify the entries by adding further rows as it
remains static.
T he imported set is then stored in an encrypted file format on the NetScaler directory. T he imported list contains millions of
URL entries. Otherwise, the appliance returns an error message saying that the value exceeds the limit. If the imported URL
set has blacklisted entries with metadata, the metadata it is detected by the appliance when it is imported.
Once you import a URL set and add it into the appliance, the URL set is available for advanced policies to identify the
correct URL set during incoming URL evaluation.
HT T P.REQ.HOST NAME.APPEND(HT T P.REQ.URL).URLSET _MATCHES_ANY(<URL set name>)
2. Updating a URL set on the NetScaler appliance. Once you have pushed the file into the appliance, at this interval you can
manually update a URL file by using command line interface.
3. Exporting a URL set. If you prefer a backup of the URL set, you can export the list of URL patterns and save a copy of it
to a destination URL. Before you export, check whether the URL set is marked as private. If is marked private, the URL set
cannot be exported.
4. Removing a URL set. If you want to delete a URL set of blacklisted entries, you can use the remove command to delete
5. Displaying a URL set. You can display the properties of a URL set by using the show command.
Example:
Done
import urlset <name> [-overwrite] [–delimiter <character>] [-rowSeparator <character>] [-url] <url> [-interval <seconds>] [-privateSet] [-
Where,
rowSeparator is a CSV file row separator with default value set as 10.
Interval is the time interval in secs, rounded to the nearest 15 minutes at which the update of urlset occurs.
CanaryURL is a URL used for testing when contents of the urlset is kept confidential.
Example
sh policy urlset
Navigate to AppExpert > URL Set s , click Import to download the URL set.
Navigate to AppExpert > URL Set s , click Add to create a URL set file for the downloaded URL set.
Navigate to AppExpert > URL Sets, select a URL set and click Edit to modify.
Navigate to AppExpert > URL Sets, select a URL set and click Export URL Set to export the URL patterns in a set to a
destination URL and save it in that location.
Following the semantics for a URL pattern to match the metadata mapping.
domain.com
yourdomain.com
Subdomain www.domain.com
domain.com
matching wwwdomain.com
sub.one.domain.com
domain.com/example/bar/index.html
URL wwwdomaincom/example/bar/index.html
www.domain.com/example/bar/index.html
matching domain.com/example/bar/index.html
domain.com/example/bar/index.html/one.jpg
exact path
s.domain.com/example/bar/index.html
domain.com/example/bar/index.html?
URL key=value wwwdomaincom/example/bar/index.html
domain.com/example/bar/index.html
matching
www.domain.com/example/bar/index.html? domain.com/example/bar/index.html/one.jpg
exact path
s.domain.com/example/bar/index.html
domain.com/example/bar/
URL domain.com/example/bar/index.html
matching,
domain.com/example/bar/ wwwdomaincom/example/bar/index.html
subpath www.domain.com/example/bar/index.html
matching
domain.com/example/bar/index.html/one.jpg
1 Illegal Activities
2 Illegal Drugs
3 Medication
4 Marijuana
5 T errorism/Extremists
6 Weapons
7 Hate/Slander
8 Violence/Suicide
9 Advocacy in general
10 Adult/Porn
11 Nudity
12 Sexual Services
13 Adult Search/Links
14 Hacking/Cracking
15 Malware
16 Remote Proxies
18 T ranslators
19 Dating
20 Weddings/Matrimony
21 Market Rates
22 Online T rading
24 Financial Products
25 Gambling in general
26 Lottery
27 Online games
28 Games
29 Auctions
30 Shopping/Retail
31 Real Estate
32 IT Online Shopping
34 Instant Messages
36 E-Mail Subscriptions
37 Bulletin Boards
38 IT Bulletin Boards
40 Downloads
41 Program Downloads
42 Storage Services
Streaming Media
43
Employment
44
45 Career Advancement
Side Business
46
47 Grotesque
Popular Topics
49
50 Adult Magazine/News
Smoking
51
Drinking
52
53 Alcoholic Products
Fetish
54
55 Sexual Expression(text)
Costume Play/Enjoyment
56
Occult
57
Professional Sports
59
60 Sports in general
Life Events
61
Public Transit
64
Accommodations
65
Music
66
Entertainer/Celebrity
68
Dining/Gourmet
69
Entertainment/Venues/Activities
70
71 Traditional Religions
Religions
72
Politics
73
74 Advertisements/Banners
Sweepstakes/Prizes
75
SPAM
76
77 News
Automotive
78
Education
81
Government
82
Health
83
84 Internet Telephony
Military
85
Reference
88
Sex Education
90
Spyware
93
Kids Sites
95
Hosting Sites
98
Ringtones
101
Mobile Operators
106
107 Botnets
Infected Sites
108
Phishing Sites
109
110 Keyloggers
Mobile Malware
111
No Content
112
Agriculture
113
114 Architecture
Associations/Trade Groups/Unions
115
Books/eBooks
116
DDNS
118
Unsupported URL
119
120 Law
Local Communities
121
122 Miscellaneous
Online Magazines
123
Private IP Addresses
126
Recycling/Environment
127
Science
128
eLearning
133
135 Facebook
Facebook: Posting
136
Facebook: Commenting
137
Facebook: Friends
138
Facebook: Events
140
Facebook: Apps
141
Facebook: Groups
145
Facebook: Games
146
LinkedIn
147
LinkedIn: Updates
148
LinkedIn: Mail
149
LinkedIn: Connections
150
LinkedIn: Jobs
151
Twitter
152
Twitter: Posting
153
Twitter: Mail
154
Twitter: Follow
155
156 YouTube
YouTube: Commenting
157
YouTube: Sharing
159
Instagram
160
Instagram: Upload
161
Tumblr
164
Tumblr: Posting
165
Tumblr: Commenting
166
Google+
168
Google+: Posting
169
Google+: Commenting
170
Pinterest
174
Pinterest: Pin
175
Vine: Commenting
177
Vine: Message
178
Ask.fm
179
Ask.fm: Ask
180
182 YikYak
185 Wordpress
T he Citrix NetScaler appliance is a central point of control for all application traffic in the data center. It collects flow and
user-session level information valuable for application performance monitoring, analytics, and business intelligence
applications. It also collects web page performance data and database information. AppFlow transmits the information by
using the Internet Protocol Flow Information eXport (IPFIX) format, which is an open Internet Engineering Task Force
(IET F) standard defined in RFC 5101. IPFIX (the standardized version of Cisco's NetFlow) is widely used to monitor network
flow information. AppFlow defines new Information Elements to represent application-level information, web page
performance data, and database information.
Using UDP as the transport protocol, AppFlow transmits the collected data, called flow records, to one or more IPv4
collectors. T he collectors aggregate the flow records and generate real-time or historical reports.
AppFlow provides visibility at the transaction level for HT T P, SSL, TCP, and SSL_TCP flows. You can sample and filter the flow
types that you want to monitor.
AppFlow use actions and policies to send records for a selected flow to specific set of collectors. An AppFlow action
specifies which set of collectors will receive the AppFlow records. Policies, which are based on Advanced expressions can be
configured to select flows for which flow records will be sent to the collectors specified by the associated AppFlow action.
To limit the types of flows, you can enable AppFlow for a virtual server. AppFlow can also provide statistics for the virtual
server.
You can also enable AppFlow for a specific service, representing an application server, and monitor the traffic to that
application server.
Updated: 2015-05-28
In the most common deployment scenario, inbound traffic flows to a Virtual IP address (VIP) on the NetScaler appliance
and is load balanced to a server. Outbound traffic flows from the server to a mapped or subnet IP address on the NetScaler
and from the VIP to the client. A flow is a unidirectional collection of IP packets identified by the following five tuples:
sourceIP, sourcePort, destIP, destPort, and protocol.
To help the collector link all four flows in a transaction, AppFlow adds a custom transactionID element to each flow. For
application-level content switching, such as HT T P, it is possible for a single client TCP connection to be load balanced to
different backend TCP connections for each request. AppFlow provides a set of records for each transaction.
Flow Records
Updated: 2013-08-20
AppFlow records contain standard NetFlow or IPFIX information, such as time stamps for the beginning and end of a flow,
packet count, and byte count. AppFlow records also contain application-level information (such as HT T P URLs, HT T P
request methods and response status codes, server response time, and latency), web page performance data (such as page
load time, page render time, and time spent on the page), and database information (such as database protocol, database
response status and database response size). IPFIX flow records are based on templates that need to be sent before
sending flow records.
Templates
t ransact ionID
An unsigned 32-bit number identifying an application-level transaction. For HT T P, this corresponds to a request and
response pair. All flow records that correspond to this request and response pair have the same transaction ID. In the most
common case, there are four uniflow records that correspond to this transaction. If the NetScaler generates the response
by itself (served from the integrated cache or by a security policy), there may be only two flow records for this transaction.
connect ionID
An unsigned 32-bit number identifying a layer-4 connection (T CP or UDP). T he NetScaler flows are usually bidirectional, with
two separate flow records for each direction of the flow. T his information element can be used to link the two flows.
For the NetScaler, connectionID is an identifier for the connection data structure to track the progress of a connection. In
an HT T P transaction, for instance, a given connectionID may have multiple transactionID elements corresponding to
multiple requests that were made on that connection.
t cpRT T
T he round trip time, in milliseconds, as measured on the T CP connection. T his can be used as a metric to determine the
client or server latency on the network.
ht t pRequest Size
An unsigned 32-bit number indicating the request payload size.
ht t pRequest URL
T he HT T P URL requested by the client.
ht t pUserAgent
T he source of incoming requests to the Web server.
ht t pResponseSt at us
An unsigned 32-bit number indicating the response status code.
ht t pResponseSize
An unsigned 32-bit number indicating the response size.
dbReqT ype
An unsigned 8-bit number indicating the database request method used in the transaction. For MS SQL, valid values are 1 is
for QUERY, 2 is for T RANSACT ION, and 3 is for RPC. For valid values for MySQL, see the MySQL documentation.
dbReqSt ring
Indicates the database request string without the header.
dbRespSt at us
An unsigned 64-bit number indicating the status of the database response received from the web server.
dbRespLengt h
An unsigned 64-bit number indicating the response size.
dbRespSt at St ring
T he response status string received from the web server.
You can further set AppFlow parameters to specify the template refresh interval and to enable the exporting of httpURL,
httpCookie, and httpReferer information. On each collector, you must specify the NetScaler IP address as the address of
the exporter.
Note: For information about configuring the NetScaler as an exporter on the collector, see the documentation for the
specific collector.
T he configuration utility provides tools that help users define the policies and actions that determine exactly how the
NetScaler appliance export records for a particular flow to a set of collectors(action.) T he command line interface provides
a corresponding set of CLI-based commands for experienced users who prefer a command line.
Updated: 2014-08-07
To be able to use the AppFlow feature, you must first enable it.
Updated: 2014-08-07
A collector receives AppFlow records generated by the NetScaler appliance. T o send the AppFlow records, you must specify
add appflow collector <name> -IPAddress <ipaddress> -port <port_number> -netprofile <netprofile_name>
show appflow collector <name>
> add appflow collector col1 -IPaddress 10.102.29.251 -port 8000 -netprofile n2
To specify multiple collectors by using the command line interface
At the command prompt, type the following commands to add multiple collectors:
Updated: 2014-08-07
An AppFlow action is a set collectors, to which the flow records are sent if the associated AppFlow policy matches.
Updated: 2014-08-07
Note: For creating and managing AppFlow policies, the configuration utility provides assistance that is not available at the
command line interface.
To configure an AppFlow policy by using the command line interface
At the command prompt, type the following command to add an AppFlow policy and verify the configuration:
add appflow policy <name> <rule> <action>
show appflow policy <name>
When you make your choice, the rightmost list box lists appropriate terms for the next part of your expression.
2. In the second list box, choose the second term for your expression. T he choices depend upon which choice you made in
the previous step, and are appropriate to the context. After you make your second choice, the Help window below the
Construct Expression window (which was blank) displays help describing the purpose and use of the term you just chose.
3. Continue choosing terms from the list boxes that appear to the right of the previous list box, or typing strings or
numbers in the text boxes that appear to prompt you to enter a value, until your expression is finished.
Updated: 2014-08-07
To put a policy into effect, you must bind it either globally, so that it applies to all traffic that flows through the NetScaler,
or to a specific virtual server, so that the policy applies only to the traffic related to that virtual server.
When you bind a policy, you assign it a priority. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer.
In the NetScaler operating system, policy priorities work in reverse order— the higher the number, the lower the priority. For
example, if you have three policies with priorities of 10, 100, and 1000, the policy assigned a priority of 10 is performed first,
then the policy assigned a priority of 100, and finally the policy assigned an order of 1000.
bind appflow global af_policy_lb1_10.102.71.190 1 NEXT -type REQ_OVERRIDE -invoke vserver google
To bind an AppFlow policy to a specific virtual server by using the command line
interface
At the command prompt, type the following command to bind an appflow policy to a specific virtual server and verify the
configuration:
bind lb vserver <name> -policyname <policy_name> -priority <priority>
Updated: 2014-08-12
If you want to monitor only the traffic through certain virtual servers, enable AppFlow specifically for those virtual servers.
You can enable AppFlow for load balancing, content switching, cache redirection, SSL VPN, GSLB, and authentication virtual
servers.
To enable AppFlow for a virtual server by using the command line interface
At the command prompt, type:
Updated: 2014-08-07
You can enable AppFlow for services that are to be bound to the load balancing virtual servers.
To enable AppFlow for a service by using the command line interface
At the command prompt, type:
Updated: 2014-08-08
You can set AppFlow parameters to customize the exporting of data to the collectors.
To set the AppFlow Parameters by using the command line interface
At the command prompt, type the following commands to set the AppFlow parameters and verify the settings:
set appflow param [-templateRefresh <secs>] [-appnameRefresh <secs>] [-flowRecordInterval <secs>] [-udpPmtu
<positive_integer>] [-httpUrl ( ENABLED | DISABLED )] [-httpCookie ( ENABLED | DISABLED )] [-httpReferer (
ENABLED | DISABLED )] [-httpMethod ( ENABLED | DISABLED )] [-httpHost ( ENABLED | DISABLED )] [-
httpUserAgent ( ENABLED | DISABLED )] [-httpXForwardedFor ( ENABLED | DISABLED )][-clientT rafficOnly ( YES |
NO )]
show appflow Param
> set appflow Param -templateRefresh 240 -udpPmtu 128 -httpUrl enabled
To set the AppFlow parameters by using the configuration utility
Navigate to System > AppFlow, click Change AppFlow Settings, and specify relevant AppFlow parameters.
Updated: 2013-08-20
T he following example illustrates the procedure for configuring AppFlow for DataStream using the command line interface.
You can configure both load balancing and content switching virtual servers to export EdgeSight Monitoring data to
AppFlow collectors. Before configuring a virtual server for AppFlow export, associate an Appflow action with the EdgeSight
Monitoring responder policy.
AppFlow transmits the performance data by using the Internet Protocol Flow Information eXport (IPFIX) format, which is
an open Internet Engineering Task Force (IET F) standard defined in RFC 5101. T he AppFlow templates use the following
enterprise-specific Information Elements (EIEs) to export the information:
Client Load End T ime . T ime at which the browser received the last byte of a response to load all the objects of the
page such as images, scripts, and stylesheets.
Client Load St art T ime .T ime at which the browser receives the first byte of the response to load any objects of the
page such as images, scripts, and stylesheets.
Client Render End T ime . T ime at which browser finished rendering the entire page, including the embedded objects.
Client Render St art T ime . T ime at which the browser started rendering the page.
Updated: 2013-09-13
Before associating the AppFlow action with the AppFlow policy, verify that the following prerequisites have been met:
T he AppFlow feature has been enabled and configured. For instructions, see "Configuring the AppFlow feature".
T he Responder feature has been enabled. For instructions, see "Enabling a Responder Feature".
T he EdgeSight Monitoring feature has been enabled. For instructions, see "Enabling an Application for EdgeSight
Monitoring."
EdgeSight Monitoring has been enabled on the load balancing or content switching virtual servers bound to the services
of applications for which you want to collect the performance data. For instructions, see "Enabling an Application for
Updated: 2013-10-31
To export the web page performance data to the AppFlow collector, you must associate an AppFlow action with the
EdgeSight Monitoring responder policy. An AppFlow action specifies which set of collectors receive the traffic.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers or T raffic Management > Content Switching >
Virtual Servers.
2. In the details pane, select a virtual server, or multiple virtual servers, and then click Enable EdgeSight Monitoring.
3. In the Enable EdgeSight Monitoring dialog box, select the Export EdgeSight statistics to Appflow check box.
4. From the Appflow Action drop-down list, select the AppFlow action. T he AppFlow action defines the list of AppFlow
collectors to which it exports EdgeSight Monitoring statistics. If you have selected multiple load balancing virtual servers,
the same AppFlow Action will be associated with the responder policies bound to them. You can later change the
AppFlow Action configured for each of the selected Load Balancing virtual server individually, if required.
5. Click OK.
Session Reliabilit y , the preferred mode, is a seamless experience for the user. T he disruption is barely noticeable for brief
network interruptions.
Aut o Client Reconnect , the fallback option, involves restarting the client. T his mechanism is disruptive for the user and is
not always supported.
Receivers can now reconnect their ICA sessions seamlessly using the ICA Session Reliability feature when HDX Insight is
enabled. T his feature works both in standalone and in a NetScaler high availability pair configuration, and even when a
NetScaler failover happens.
Note
NetScaler appliances should be running on software version 11.1 build 49.16 or later.
You should not Enable or disable Session Reliability mode when the NetScaler appliances have active connections.
Enabling or Disabling the feature when connections are still active causes HDX Insight to stop parsing those sessions after a
failover occurs and result in loss of information about the sessions.
Session reliability is supported on a high availability setup only if both the nodes of the setup run the same build (for example,
release 11.1 build 53). In other words, session reliability is not supported on a high availability setup if both the nodes run different
builds (for example, one node has release 11.1 build 53 whereas the other has release 11.1 build 56).
Session Reliability on high availability setup is enabled by default from NetScaler software version 11.1 build 49.16 or later.
Ena ble S Ro nHAFa ilo v e r YES (de fa ult) Ena ble S Ro nHAFa ilo v e r NO
HDX Insight Enabled Session reconnect for ICA sessions works Session reconnect for ICA Sessions does not work
HDX Insight Disabled Session reconnect for ICA sessions works Session reconnect for ICA sessions works
Note
Session Reliability for ICA sessions works out of the box with NetScaler Gateway appliance.
Session Reliability for ICA sessions does not work ONLY when both the following conditions are met:
HDX Insight is enabled
EnableSRonHAFailover is set to NO.
Setting EnableSRonHAFailover knob to either YES or NO does not make any difference when HDX Insight is disabled.
1. At the command line, use the default system administrator credentials to log on to the system.
2. T o enable Session Reliability on HA failover, at the prompt, type: set ica parameter EnableSRonHAFailover YES
3. T o disable Session Reliability on HA failover, at the prompt, type: set ica parameter EnableSRonHAFailover NO
1. In a web browser, type the IP address of the primary NetScaler instance in the HA pair (for example,
http://192.168.100.1).
2. In User Name and P assword , enter the administrator credentials.
3. On the Conf igurat ion tab, navigate to Syst em > Set t ings , and click Change ICA P aramet ers .
4. In in the Change ICA parameters section, select Session Reliabilit y on HA F ailover.
5. Click OK .
Enabling this feature will result in increased bandwidth consumption which is due to ICA compression being turned off by
the feature, and the extra traffic between the primary and secondary nodes to keep them in sync.
T his feature is supported in Active-Passive mode only. Active-Active mode is not currently supported.
When HDX Insight is enabled, and Session Reliability on HA knob is set to NO, only ACR reconnect mode is supported in
NetScaler high availability failover scenario. T he HA knob does not disable Session Reliability if HDX Insight is disabled.
Introduction An overview of web application security and how the application firewall works.
Configuration How to configure the application firewall to protect a web site, a web service, or a Web 2.0 site.
Signatures A detailed description of the signatures feature and how to configure the signatures, add signatures
from a supported vulnerability scanning tool, and define your own signatures, with examples.
Overview of A detailed description of all of the application firewall security checks, with configuration information
Security and examples.
Checks
Profiles A description of how profiles are configured and used in the application firewall.
Policies A description of how policies are used when configuring the application firewall, with examples of
useful policies.
Imports A description of how the application firewall uses different types of imported files, and how to import
and export files.
Global A description of application firewall features that apply to all profiles, and how to configure them.
Configuration
Use Cases Extended examples that demonstrate how to set up the application firewall to best protect specific
types of more complex web sites and web services.
Logs, How to access and use the application firewall logs, the statistics, and the reports to assist in
Statistics, configuring the application firewall.
and Reports
T he Citrix application firewall offers easy to configure options to meet a wide range of application security requirements.
Application firewall profiles, which consist of sets of security checks, can be used to protect both the requests and the
responses by providing deep packet-level inspections. Each profile includes an option to select basic protections or
advanced protections. Some protections might require use of other files. For example, xml validation checks might require
WSDL or schema files. T he profiles can also use other files, such as signatures or error objects. T hese files can be added
locally, or they can be imported ahead of time and saved on the appliance for future use. T hey can be shared by multiple
profiles.
Profiles work in conjunction with the application firewall policies. Each policy identifies a type of traffic, and that traffic is
inspected for the security check violations specified in the profile that is associated with the policy. T he policies can have
different bind points, which determine the scope of the policy. For example, a policy that is bound to a specific virtual server
is invoked and evaluated for only the traffic flowing through that virtual server. T he policies are evaluated in the order of
their designated priorities, and the first one that matches the request or response is applied.
P rofile — An application firewall profile specifies what to look for and what to do. It inspects both the request and the
response to determine which potential security violations should be checked and what actions should be taken when
processing a transaction. A profile can protect an HT ML, XML or HT ML and XML payload. Depending on the security
requirements of the application, you can create either a basic or an advanced profile. A basic profile can protect against
known attacks. If higher security is required, you can deploy an advanced profile to allow controlled access to the
application resources, blocking zero day attacks. However, a basic profile can be modified to offer advanced protections,
and vice versa. Multiple action choices (for example, block, log, learn, and transform) are available. Advanced security checks
might use session cookies and hidden form tags for controlling and monitoring the client connections. Application firewall
profiles can learn the triggered violations and suggest the relaxation rules.
Basic P rot ect ions — A basic profile includes a preconfigured set of Start URL and Deny URL relaxation rules. T hese
relaxation rules determine which requests should be allowed and which should be denied. Incoming requests are matched
against these lists and the configured actions are applied. T his allows the user to be able to secure applications with
minimal configuration for relaxation rules. T he Start URL rules protect against forceful browsing. Known web server
vulnerabilities that are exploited by hackers can be detected and blocked by enabling a set of default Deny URL rules.
Commonly launched attacks, such as Buffer Overflow, SQL, or Cross-site scripting can also be easily detected.
Advanced P rot ect ions — As the name indicates, advanced protections are used for applications that have higher security
requirements. Relaxation rules are configured to allow access to only specific data and block the rest. T his positive security
model mitigates unknown attacks, which might not be detected by basic security checks. In addition to all the basic
protections, an advanced profile keeps track of a user session by controlling the browsing, checking for cookies, specifying
input requirements for various form fields, and protecting against tampering of forms or cross-site request forgery attacks.
Learning, which observes the traffic and deploys the appropriate relaxations, is enabled by default for many security checks.
Although easy to use, advanced protections require due consideration, because they offer tighter security but also require
more processing and do not allow use of caching, which can affect performance.
Import — Import functionality is useful when application firewall profiles need to use external files, that is, files hosted on
an external or internal web server, or that have to be copied from a local machine. Importing a file and storing it on the
appliance is very useful, especially in situations where you have to control access to external websites, or where compilation
takes a long time, large files have to be synced across HA deployments, or you can reuse a file by copying it across multiple
devices. For example:
WSDLs hosted on external web servers can be imported locally before blocking access to external websites.
Large signature files generated by an external scan tool such as Cenzic can be imported and precompiled, using schema
on the Citrix appliance.
A customized HT ML or XML error page can be imported from an external web server or copied from a local file.
Signat ures — Signatures are very powerful, because they use pattern matching to detect malicious attacks and can be
P olicies — Application Firewall Policies are used to filter and separate the traffic into different types. T his provides the
flexibility to implement different levels of security protections for the application data. Access to highly sensitive data can
be directed to advanced security-check inspections, while less sensitive data is protected by basic-level security inspections.
Policies can also be configured to bypass security-check inspection for harmless traffic. Higher security requires more
processing, so careful design of the policies can provide desired security along with optimized performance. T he priority of
the policy determines the order in which it is evaluated, and its bind point determines the scope of its application.
1. Ability to secure a wide range of applications by protecting different types of data, implementing the right level of
security for different resources, and still getting maximum performance.
2. Flexibility to add or modify a security configuration. You can tighten or relax security checks by enabling or disabling basic
and advanced protections.
3. Option to convert an HT ML profile to an XML or Web2.0 (HT ML+XML) profile and vice-versa, providing the flexibility to
add security for different types of payload.
4. Easily deployed actions to block attacks, monitor them in logs, collect statistics, or even transform some attack strings
to render them harmless.
5. Ability to detect attacks by inspecting incoming requests, and to prevent leakage of sensitive data by inspecting the
responses sent by the servers.
6. Capability to learn from the traffic pattern to get recommendations for easily editable relaxation rules that can be
deployed to allow exceptions.
7. Hybrid security model that applies the power of customizable signatures to block attacks that match specified patterns,
and provides the flexibility to use the positive-security-model checks for basic or advanced security protections.
8. Availability of comprehensive configuration reports, including information about PCI-DSS compliance.
With the following features, the Citrix NetScaler application firewall offers a comprehensive security solution:
Hybrid securit y model: NetScaler hybrid security model allows you to take advantage of both a positive security
model and a negative security model to come up with a configuration ideally suited for your applications.
P osit ive securit y model protects against Buffer Overflow, CGI-BIN Parameter Manipulation, Form/Hidden Field
Manipulation, Forceful Browsing, Cookie or Session Poisoning, Broken ACLs, Cross-Site Scripting (XSS), Command
Injection, SQL Injection, Error T riggering Sensitive Information Leak, Insecure Use of Cryptography, Server
Misconfiguration, Back Doors and Debug Options, Rate-Based Policy Enforcement, Well Known Platform
Vulnerabilities, Zero-Day Exploits, Cross Site Request Forgery (CSRF), and leakage of Credit Card and other sensitive
data.
Negat ive securit y model uses a rich set signatures to protect against L7 and HT T P application vulnerabilities. T he
application firewall is integrated with several third party scanning tools, such as those offered by Cenzic, Qualys,
Whitehat, and IBM. T he built-in XSLT files allow easy importation of rules, which can be used in conjunction with the
native-format Snort based rules. An auto-update feature gets the latest updates for new vulnerabilities.
T he positive security model might be the preferred choice for protecting applications that have a high need for
security, because it gives you the option to fully control who can access what data. You allow only what you
want and block the rest. T his model includes a built-in security check configuration, which is deployable with few
clicks. However, keep in mind that the tighter the security, the greater the processing overhead.
T he negative security model might be preferable for customized applications. T he signatures allow you to
combine multiple conditions, and a match and the specified action are triggered only when all the conditions are
satisfied. You block only what you don’t want and allow the rest. A specific fast-match pattern in a specified
location can significantly reduce processing overhead to optimize performance. T he option to add your own
signature rules, based on the specific security needs of your applications, gives you the flexibility to design your
own customized security solutions.
Request as well as response side det ect ion and prot ect ion: You can inspect the incoming requests to detect any
suspicious behavior and take appropriate actions, and you can check the responses to detect and protect against
leakage of sensitive data.
Rich set of built -in prot ect ions f or HT ML, XML and JSON payloads: T he application firewall offers 19 different
security checks. Six of them (such as Start URL and Deny URL) apply to both HT ML and XML data. Five checks (such as
Field Consistency and Field Format) are specific to HT ML, and eight (such as XML Format and Web Service
Interoperability) are specific to XML payloads. T his feature includes a rich set of actions and options. For example, URL
Closure enables you to control and optimize the navigation through your website, to safeguard against forceful
browsing without having to configure relaxation rules to allow each and every legitimate URL. You have the option to
remove or x-out the sensitive data, such as credit-card numbers, in the response. Be it SOAP Array attack protection,
XML denial of Service (XDoS), WSDL scan prevention, Attachment check, or any number of other XML attacks, you have
the comfort of knowing that you have an ironclad shield protecting your data when your applications are protected by
the application firewall. T he signatures allow you to configure rules using XPAT H-Expressions to detect violations in the
body as well as the header of a JSON payload.
GWT : Support for protecting Google Web T oolkit applications to safeguard against SQL, XSS and Form Field
Do the following:
Add an application firewall profile and select the appropriate type (html, xml, web2.0) for the security requirements of the
application.
Select the required level of security (basic or advanced).
Add or import the required files, such as signatures or WSDL.
Configure the profile to use the files, and make any other necessary changes to the default settings.
Add an application firewall policy for this profile.
Bind the policy to the target bind point and specify the priority.
T he application firewall profile offers protection for both HT ML and XML payloads. Depending on the need of your
application, you can choose either a HT ML profile or XML profile. If your application supports both HT ML and XML data,
you can choose a Web2.0 profile.
T he decision to use a basic or an advance profile depends on the security need of your application. A basic profile includes a
preconfigured set of Start URL and Deny URL relaxation rules. T hese relaxation rules determine which requests are allowed
and which are denied. Incoming requests are matched with the preconfigured rules, and the configured actions are applied.
T he user can secure applications with minimal configuration of relaxation rules. T he Start URL rules protect against forceful
browsing. Known web server vulnerabilities that are exploited by hackers can be detected and blocked by enabling a set of
default Deny URL rules. Commonly launched attacks, such as Buffer Overflow, SQL, or Cross-Site Scripting can also be easily
detected.
As the name indicates, advanced protections are for applications that have higher security requirements. Relaxation rules
are configured to allow access to only specific data and block the rest. T his positive security model mitigates unknown
attacks, which might not be detected by basic security checks. In addition to all the basic protections, an advanced profile
keeps track of a user session by controlling the browsing, checking for cookies, specifying input requirements for various
form fields, and protecting against tampering of forms or Cross-Site Request Forgery attacks. Learning, which observes the
traffic and recommends the appropriate relaxations, is enabled by default for many security checks. Although easy to
use, advanced protections require due consideration, because they offer tighter security but also require more processing.
Some advance security checks do not allow use of caching, which can affect performance.
Keep the following points in mind when deciding whether to use basic or advanced profiles:
Basic and advanced profiles are just starting templates. You can always modify the basic profile to deploy advanced
security features, and vice versa.
Advanced security checks require more processing and can affect performance. Unless your application needs advanced
security, you might want to start with a basic profile and tighten the security as required for your application.
You do not want to enable all security checks unless your application needs it.
Careful assignment of priorities can enhance the traffic processing. You want to assign higher priorities to more specific
policies and lower priorities to generic policies. Note that the higher the number, the lower the priority. A policy with a
priority of 10 is evaluated before a policy that has a priority of 15.
You can apply different levels of security for different kinds of contents, e.g. requests for static objects like images and
text can be by-passed by using one policy and requests for other sensitive contents can be subjected to a much stringent
check by using a second policy.
T he application firewall makes it very easy to design the right level of security for your web-site. You can have multiple
application firewall policies, bound to different application firewall profiles, to implement different levels of security-check
inspections for your applications. You can initially monitor the logs to observe what security threats are being detected and
which violations are being triggered. You can either manually add the relaxation rules or take advantage of the application
firewall's recommended learned rules to deploy the required relaxations to avoid false positives.
T he Citrix application firewall offers visualizer support in GUI, which makes rule management very easy. You can easily view
all the data on one screen, and take action on several rules with one click. T he biggest advantage of the visualizer is that it
recommends regular expressions to consolidate several rules. You can select a subset of the rules, basing your selection on
the delimiter and Action URL. Visualizer support is available for viewing 1) learned rules and 2) relaxation rules.
1) T he visualizer for learned rules offers the option to edit the rules and deploy them as relaxations. You can also skip
(ignore) rules.
2) T he visualizer for deployed relaxations offers you the option to add a new rule or edit an existing one. You can also
enable or disable a group of rules by selecting a node and clicking the Enable or Disable button in the relaxation
visualizer.
A signature is an object that can have multiple rules. Each rule consists of one or more patterns that can be associated with
a specified set of actions. T he application firewall has a built-in default signature object consisting of more than 1,300
signature rules, with an option to get the latest rules by using the aut o-updat e feature to get protection against new
vulnerabilities. Rules created by other scan tools can also be imported.
Signatures are very powerful because they use pattern matching to detect malicious attacks and can be configured to
check both the request and the response of a transaction. T hey are a preferred option when a customizable security
solution is needed. Multiple action choices (for example, block, log, learn, and transform) are available for when a signature
match is detected. T he default signatures cover rules to protect different types of applications, such as web-cgi, web-
coldfusion, web-frontpage, web-iis, web-php, web-client, web-activex, web-shell-shock, and web-struts. To match the
needs of your application, you can select and deploy the rules belonging to a specific category.
You can just make a copy of the default signature object and modify it to enable the rules you need and configure the
actions you want.
T he signature object can be customized by adding new rules, which can work in conjunction with other signature rules.
T he signature rules can also be configured to work in conjunction with the security checks specified in the application
firewall profile. If a match indicating a violation is detected by a signature as well as a security check, the more restrictive
action is the one that gets enforced.
A signature rule can have multiple patterns and be configured to flag a violation only when all the patterns are matched,
thereby avoiding false positives.
Careful selection of a literal fast-match pattern for a rule can significantly optimize processing time.
T he application firewall is fully integrated into the NetScaler appliance and works seamlessly with other features. You can
configure maximum security for your application by using other NetScaler security features in conjunction with the
application firewall. For example, AAA-T M can be used to authenticate the user, check the user's authorization to access
the content, and log the accesses, including invalid login attempts. Rewrit e can be used to modify the URL or to add,
modify or delete headers, and Responder can be used to deliver customized content to different users. You can define
the maximum load for your website by using Rat e Limit ing to monitor the traffic and throttle the rate if it is too high.
HT T P Denial-of-Service (DoS) protection can help distinguish between real HT T P clients and malicious DoS clients. You
can narrow the scope of security-check inspection by binding the application firewall policies to virtual servers, while still
optimizing the user experience by using the Load Balancing feature to manage heavily used applications. Requests for
static objects such as images or text can bypass security check inspection, taking advantage of int egrat ed caching or
compression to optimize the bandwidth usage for such content.
A diagram showing details of the L7 packet flow in a NetScaler appliance is available in the Processing Order of Features
section at http://docs.citrix.com/en-us/netscaler/11/getting-started-with-netscaler.html.
Now that you know the advantages of using the state-of-the-art security protections of the Citrix application firewall, you
might want to collect additional information that can help you design the optimal solution for your security needs. Citrix
recommends that you do the following:
Know your environment : Knowing your environment will help you to identify the best security protection solution
(signatures, security checks, or both) for your needs. Before you begin configuration, you should gather the following
information.
OS: What kind of OS (MS Windows, Linux, BSD, Unix, others) do you have?
Web Sever: What web server (IIS, Apache or NetScaler Enterprise Server) are you running?
Applicat ion: What type of applications are running on your application server (for example, ASP.NET , PHP, Cold
Fusion, ActiveX, FrontPage, Struts, CGI, Apache T omcat, Domino, and WebLogic)?
Do you have customized applications or off-the-shelf (for example, Oracle, SAP) applications? What version you are
using?
SSL: Do you require SSL? If so, what key size (512, 1024, 2048, 4096) is used for signing certificates?
T raf f ic Volume: What is the average traffic rate through your applications? Do you have seasonal or time-specific
spikes in the traffic?
Server F arm: How many servers do you have? Do you need to use load balancing?
https://www.citrix.com/content/dam/citrix/en_us/documents/products-solutions/netscaler-data-sheet.pdf?
accessmode=direct
Deploy t he applicat ion f irewall: Use the application firewall wizard to proceed with a simple security configuration.
T he wizard walks you through several screens and prompts you to add a profile, policy, signature, and security checks.
P rof ile: Select a meaningful name and the appropriate type (HT ML, XML or WEB 2.0) for your profile. T he policy and
signatures will be auto-generated using the same name.
P olicy: T he auto-generated policy has the default Expression (true), which selects all traffic and is bound globally. T his
is a good starting point unless you have in mind a specific policy that you want to use.
P rot ect ions: T he wizard helps you take advantage of the hybrid security model, in which you can use the default
signatures offering a rich set of rules to protect different types of applications. Simple edit mode allows you to view
the various categories (CGI, Cold Fusion, PHP, etc.). You can select one or more categories to identify a specific set of
rules applicable to your application. Use the Act ion option to enable all the signature rules in the selected categories.
Make sure that blocking is disabled, so that you can monitor the traffic before tightening the security. Click
Cont inue . In the Specif y Deep prot ect ions pane, you can make changes as needed to deploy the security check
protections. In most cases, basic protections are sufficient for initial security configuration. Run the traffic for a while
to collect a representative sample of the security-inspection data.
T ight ening t he securit y: After deploying application firewall and observing the traffic for a while, you can start
tightening the security of your applications by deploying relaxations and then enabling blocking. Learning , Visualizer,
and Click t o deploy rules are useful features that make it very easy to tweak your configuration to come up with
just the right level of relaxation. At this point, you can also change the policy expression and/or configure additional
policies and profiles to implement desired levels of security for different types of content.
Debugging: If you see unexpected behavior of your application, the application firewall offers various options for
easy debugging:
Log . If legitimate requests are getting blocked, your first step is to check the ns.log file to see if any unexpected
security-check violation is being triggered.
Disable f eat ure. If you do not see any violations but are still seeing unexpected behavior, such as an application
T he NetScaler Application Firewall is available as a stand-alone appliance, or as a feature on a Citrix NetScaler application
delivery controller (ADC) or Citrix NetScaler virtual appliance (VPX). In the application firewall documentation, the term
NetScaler ADC refers to the platform on which the application firewall is running, regardless of whether that platform is a
dedicated firewall appliance, a NetScaler ADC on which other features have also been configured, or a NetScaler VPX.
To use the application firewall, you must create at least one security configuration to block connections that violate the
rules that you set for your protected web sites. T he number of security configurations that you might want to create
depends on the complexity of your web site. In some cases, a single configuration is sufficient. In other cases, particularly
those that include interactive web sites, web sites that access database servers, online stores with shopping carts, you
might need several different configurations to best protect sensitive data without wasting significant effort on content
that is not vulnerable to certain types of attacks. You can often leave the defaults for the global settings, which affect all
security configurations, unchanged. However, you can change the global settings if they conflict with other parts of your
configuration or you prefer to customize them.
In the past, a breach in security was often just an annoyance, but today that is seldom the case. For example, attacks in
which a hacker gained access to a web server and made unauthorized modifications to (defaced) a web site used to be
common. T hey were usually launched by hackers who had no motivation beyond demonstrating their skills to fellow hackers
or embarrassing the targeted person or company. Most current security breaches, however, are motivated by a desire for
money. T he majority attempt to accomplish one or both of the following goals: to obtain sensitive and potentially valuable
private information, or to obtain unauthorized access to and control of a web site or web server.
Certain forms of web attacks focus on obtaining private information. T hese attacks are often possible even against web
sites that are secure enough to prevent an attacker from taking full control. T he information that an attacker can obtain
from a web site can include customer names, addresses, phone numbers, social security numbers, credit card numbers,
medical records, and other private information. T he attacker can then use this information or sell it to others. Much of the
information obtained by such attacks is protected by law, and all of it by custom and expectation. A breach of this type
can have extremely serious consequences for customers whose private information is compromised. At best, these
customers will have to exercise vigilance to prevent others from abusing their credit cards, opening unauthorized credit
accounts in their name, or appropriating their identities outright (identity theft). At worst, the customers may face ruined
credit ratings or even be blamed for criminal activities in which they had no part.
Other web attacks are aimed at obtaining control of (or compromising) a web site or the server on which it operates, or
both. A hacker who gains control of a web site or server can use it to host unauthorized content, act as a proxy for
content hosted on another web server, provide SMT P services to send unsolicited bulk email, or provide DNS services to
support such activities on other compromised web servers. Most web sites that are hosted on compromised web servers
promote questionable or outright fraudulent businesses. For example, the majority of phishing web sites and child
exploitation web sites are hosted on compromised web servers.
Protecting your web sites and web services against these attacks requires a multilayered defense capable of both blocking
known attacks with identifiable characteristics and protecting against unknown attacks, which can often be detected
because they look different from the normal traffic to your web sites and web services.
Updated: 2014-10-08
T he first line of defense for your web sites is protection against the large number of attacks that are known to exist and
have been observed and analyzed by web security experts. Common types of attacks against HT ML-based web sites
include:
Buf f er overf low at t acks. Sending an extremely long URL, extremely long cookie, or other extremely long bit of
information to a web server in hopes of causing it or the underlying operating system to hang, crash, or provide the
Two specialized types of attacks on web form security deserve special mention:
SQL inject ion at t acks. Sending an active SQL command or commands in a web form or as part of a URL, with the goal
of causing an SQL database to execute the command or commands. SQL injection attacks are normally used to obtain
unauthorized information.
Cross-sit e script ing at t acks. Using a URL or a script on a web page to violate the same-origin policy, which forbids any
script from obtaining properties from or modifying any content on a different web site. Since scripts can obtain
information and modify files on your web site, allowing a script access to content on a different web site can provide an
attacker the means to obtain unauthorized information, to compromise a web server, or both.
Attacks against XML-based web services normally fall into at least one of the following two categories: attempts to send
inappropriate content to a web service, or attempts to breach security on a web service. Common types of attacks against
XML-based web services include:
Malicious code or object s. XML requests that contain code or objects that can either directly obtain sensitive
information or can give an attacker control of the web service or underlying server.
Badly-f ormed XML request s. XML requests that do not conform to the W3C XML specification, and that can
therefore breach security on an insecure web service.
Denial of service (DoS) at t acks. XML requests that are sent repeatedly and in high volume, with the intent of
overwhelming the targeted web service and denying legitimate users access to the web service.
In addition to standard XML-based attacks, XML web services and Web 2.0 sites are also vulnerable to SQL injection and
cross-site scripting attacks, as described below:
SQL inject ion at t acks. Sending an active SQL command or commands in an XML-based request, with the goal of
causing an SQL database to execute that command or commands. As with HT ML SQL injection attacks, XML SQL
injection attacks are normally used to obtain unauthorized information.
Cross-sit e script ing at t acks. Using a script included in an XML based application to violate the same-origin policy,
which does not allow any script to obtain properties from or modify any content on a different application. Since scripts
can obtain information and modify files by using your XML application, allowing a script access to content belonging to a
different application can give an attacker the means to obtain unauthorized information, to compromise the
Known web attacks can usually be stopped by filtering web site traffic for specific characteristics (signatures) that always
appear for a specific attack and should never appear in legitimate traffic. T his approach has the advantages of requiring
relatively few resources and posing relatively little risk of false positives. It is therefore a valuable tool in fighting attacks on
web sites and web services, and configuring basic signature protections that intercept most known web attacks is easy to
do.
T he greatest threat against web sites and applications does not come from known attacks, but from unknown attacks.
Most unknown attacks fall into one of two categories: newly-launched attacks for which security firms have not yet
developed an effective defense (zero-day attacks), and carefully-targeted attacks on a specific web site or web service
rather than many web sites or web services (spear attacks). T hese attacks, like known attacks, are usually intended to
obtain sensitive private information, compromise the web site or web service and allow it to be used for further attacks, or
both of those goals.
Zero-day attacks are a major threat to all users. T hese attacks are usually of the same types as known attacks; zero-day
attacks often involve injected SQL, a cross-site script, a cross-site request forgery, or another type of attack similar to
known attacks. In most cases, they target vulnerabilities that the developers of the targeted software, web site, or web
service either are unaware of or have just learned about. Security firms have therefore usually not developed defenses
against these attacks, and even if they have, users have usually not obtained and installed the patches or performed the
workarounds necessary to protect against these attacks. T he time between discovery of a zero-day attack and availability
of a defense (the vulnerability window) is shrinking, but perpetrators can still count on hours or even days in which many
web sites and web services lack any specific protection against the attack.
Spear attacks are a major threat, but to a more select group of users. A common type of spear attack, a spear phish, is
usually targeted at customers of a specific bank or financial institution, or (less commonly) at employees of a specific
company or organization. Unlike other phishes, which are often crudely written forgeries that a user with any familiarity
with the actual communications of that bank or financial institution can recognize, spear phishes are letter perfect and
extremely convincing. T hey can contain information specific to the individual that, at first look, no stranger should know or
be able to obtain. T he spear phisher is therefore able to convince his or her target to provide the requested information,
which the phisher can then use to loot accounts, to process illegitimately obtained money from other sources, or to gain
access to other, even more sensitive information.
Both of these types of attack have certain characteristics that can usually be detected, although not by using static
patterns that look for specific characteristics, as do standard signatures. Detecting these types of attacks requires more
sophisticated and more resource-intensive approaches, such as heuristic filtering and positive security model systems.
Heuristic filtering looks, not for specific patterns, but for patterns of behaviors. Positive security model systems model the
normal behavior of the web site or web service that they are protecting, and then block connections that do not fit within
that model of normal use. URL based and web-form based security checks profile normal use of your web sites, and then
control how users interact with your web sites, using both heuristics and positive security to block anomalous or
unexpected traffic. Both heuristic and positive security, properly designed and deployed, can catch most attacks that
signatures miss. However, they require considerably more resources than do signatures, and you must spend some time
configuring them properly to avoid false positives. T hey are therefore usually used, not as the primary line of defense, but as
backups to signatures or other less resource-intensive approaches.
By configuring these advanced protections in addition to signatures, you create a hybrid security model, which enables the
application firewall to provide comprehensive protection against both known and unknown attacks.
A signature is a string or pattern that matches a known type of attack. T he application firewall contains over a thousand
signatures in seven categories, each directed at attacks on specific types of web servers and web content. Citrix updates
the list with new signatures as new threats are identified. During configuration, you specify the signature categories that
are appropriate for the web servers and content that you need to protect. Signatures provide good basic protection with
low processing overhead. If your applications have special vulnerabilities or you detect an attack against them for which no
signature exists, you can add your own signatures.
T he more advanced protections are called security checks. A security check is a more rigorous, algorithmic inspection of a
request for specific patterns or types of behavior that might indicate an attack or constitute a threat to your protected
web sites and web services. It can, for example, identify a request that attempts to perform a certain type of operation
that might breach security, or a response that includes sensitive private information such as a social security number or
credit card number. During configuration, you specify the security checks that are appropriate for the web servers and
content that you need to protect. T he security checks are restrictive. Many of them can block legitimate requests and
responses if you do not add the appropriate exceptions (relaxations) when configuring them. Identifying the needed
exceptions is not difficult if you use the adaptive learning feature, which observes normal use of your web site and creates
recommended exceptions.
T he application firewall can be installed as either a Layer 3 network device or a Layer 2 network bridge between your
servers and your users, usually behind your company’s router or firewall. It must be installed in a location where it can
intercept traffic between the web servers that you want to protect and the hub or switch through which users access
those web servers. You then configure the network to send requests to the application firewall instead of directly to your
web servers, and responses to the application firewall instead of directly to your users. T he application firewall filters that
traffic before forwarding it to its final destination, using both its internal rule set and your additions and modifications. It
blocks or renders harmless any activity that it detects as harmful, and then forwards the remaining traffic to the web server.
T he following figure provides an overview of the filtering process.
Note: T he figure omits the application of a policy to incoming traffic. It illustrates a security configuration in which the
policy is to process all requests. Also, in this configuration, a signatures object has been configured and associated with the
profile, and security checks have been configured in the profile.
Figure 1. A Flowchart of Application Firewall Filtering
If a request passes signature inspection, the application firewall applies the request security checks that have been enabled.
T he request security checks verify that the request is appropriate for your web site or web service and does not contain
material that might pose a threat. For example, security checks examine the request for signs indicating that it might be of
an unexpected type, request unexpected content, or contain unexpected and possibly malicious web form data, SQL
commands, or scripts. If the request fails a security check, the application firewall either sanitizes the request and then
sends it back to the NetScaler appliance (or NetScaler virtual appliance), or displays the error object. If the request passes
the security checks, it is sent back to the NetScaler appliance, which completes any other processing and forwards the
request to the protected web server.
When the web site or web service sends a response to the user, the application firewall applies the response security checks
that have been enabled. T he response security checks examine the response for leaks of sensitive private information, signs
of web site defacement, or other content that should not be present. If the response fails a security check, the application
firewall either removes the content that should not be present or blocks the response. If the response passes the security
checks, it is sent back to the NetScaler appliance, which forwards it to the user.
Updated: 2013-09-03
T he imports feature manages files that you upload to the application firewall. T hese files are then used by the application
firewall in various security checks, or when responding to a connection that matches a security check.
You can use the logs, statistics, and reports features to evaluate the performance of the application firewall and identify
possible needs for additional protections.
T he command line interface is a modified UNIX shell based on the FreeBSD bash shell. To configure the application firewall
from the command line interface, you type commands at the prompt and press the Enter key, just as you do with any other
Unix shell. For instructions for using the command line interface, see "Command Reference."
T he configuration utility is a web-based GUI interface to the ADC. T he application firewall configuration section is found
under Security > Application Firewall. Figure 1 shows the navigation pane expanded to display the application firewall
screens, and in the detail pane the main application firewall screen.
T he configuration utility has two main areas on all screens. T he panel on the left, called the navigation pane, contains a
navigation tree, with which you navigate to the screens on which you configure the features that are installed on your
appliance. T he screens to which you navigate appear to the right of the navigation pane, in the details pane.
When you access the configuration utility, the details pane displays the System Overview screen. If, in the navigation pane,
If, instead of expanding the application firewall node, you click the node itself, the details pane displays different options,
one of which is the application firewall wizard, as shown in Figure 1. Citrix recommends that you use the wizard for initial
configuration, and many users use it almost exclusively. It includes most of the functionality that is available elsewhere in
the configuration utility.
For information and instructions on accessing the configuration utility, see "Citrix NetScaler Getting Started Guide."
Warning
T he Application Firewall policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to use the
Application Firewall advanced policies. You can also use the nspepi utility tool for the conversion.
You can configure the Citrix Application Firewall (application firewall) by using any of the following methods:
Application Firewall Wizard. A dialog box consisting of a series of screens that step you through the configuration
process.
Citrix Web Interf ace AppExpert Template. A NetScaler AppExpert template (a set of configuration settings) that are
designed to provide appropriate protection for web sites. T his AppExpert template contains appropriate Application
Firewall configuration settings for protecting many web sites.
Citrix NetScaler Conf iguration Utility. T he NetScaler web-based configuration interface.
Citrix NetScaler Command Line Interf ace. T he NetScaler command line configuration interface.
Citrix recommends that you use the Application Firewall Wizard. Most users will find it the easiest method to configure the
application firewall, and it is designed to prevent mistakes. If you have a new Citrix NetScaler ADC or VPX that you will use
primarily to protect web sites, you may find the Web Interface AppExpert template a better option because it provides a
good default configuration, not just for the application firewall, but for the entire appliance. Both the configuration utility
and the command line interface are intended for experienced users, primarily to modify an existing configuration or use
advanced options.
T he application firewall wizard is a dialog box that consists of several screens that prompt you to configure each part of a
simple configuration. T he application firewall then creates the appropriate configuration elements from the information
that you give it. T his is the simplest and, for most purposes, the best way to configure the application firewall.
To use the wizard, connect to the configuration utility with the browser of your choice. When the connection is
established, verify that the application firewall is enabled, and then run the application firewall wizard, which prompts you
for configuration information. You do not have to provide all of the requested information the first time you use the
wizard. Instead, you can accept default settings, perform a few relatively straightforward configuration tasks to enable
important features, and then allow the application firewall to collect important information to help you complete the
configuration.
For example, when the wizard prompts you to specify a rule for selecting the traffic to be processed, you can accept the
default, which selects all traffic. When it presents you with a list of signatures, you can enable the appropriate categories
of signatures and turn on the collection of statistics for those signatures. For this initial configuration, you can skip the
advanced protections (security checks). T he wizard automatically creates the appropriate policy, signatures object, and
profile (collectively, the security configuration), and binds the policy to global. T he application firewall then begins filtering
connections to your protected websites, logging any connections that match one or more of the signatures that you
enabled and collecting statistics about the connections that each signature matches. After the application firewall
processes some traffic, you can run the wizard again and examine the logs and statistics to see if any of the signatures
You may need additional protection if, for example, your website is dynamic. Content that uses scripts may need protection
against cross-site scripting attacks. Web content that uses SQL— such as shopping carts, many blogs, and most content
management systems— may need protection against SQL injection attacks. Websites and web services that collect
sensitive private information such as social security numbers or credit card numbers may require protection against
unintentional exposure of that information. Certain types of web-server or XML-server software may require protection
from types of attacks tailored to that software. Another consideration is that specific elements of your websites or web
services may require different protection than do other elements. Examining the application firewall logs and statistics can
help you identify the additional protections that you might need.
After deciding which advanced protections are needed for your websites and web services, you can run the wizard again to
configure those protections. Certain security checks require that you enter exceptions (relaxations) to prevent the check
from blocking legitimate traffic. You can do so manually, but it is usually easier to enable the adaptive learning feature and
allow it to recommend the necessary relaxation. You can use the wizard as many times as necessary to enhance your basic
security configuration and/or create additional security configurations.
T he wizard automates some tasks that you would have to perform manually if you did not use the wizard. It automatically
creates a policy, a signatures object, and a profile, and assigns them the name that you provided when you were prompted
for the name of your configuration. T he wizard also adds your advanced-protection settings to the profile, binds the
signatures object to the profile, associates the profile with the policy, and puts the policy into effect by binding it to Global.
A few tasks cannot be performed in the wizard. You cannot use the wizard to bind a policy to a bind point other than
Global. If you want the profile to apply to only a specific part of your configuration, you must manually configure the
binding. You cannot configure the engine settings or certain other global configuration options in the wizard. While you can
configure any of the advanced protection settings in the wizard, if you want to modify a specific setting in a single security
check, it may be easier to do so on the manual configuration screens in the configuration utility.
For more information on using the Application Firewall Wizard, see "T he Application Firewall Wizard."
AppExpert Templates are a different and simpler approach to configuring and managing complex enterprise applications.
T he AppExpert display in the configuration utility consists of a table. Applications are listed in the left-most column, with
the NetScaler features that are applicable to that application appearing each in its own column to the right. (In the
AppExpert interface, those features that are associated with an application are called application units.) In the AppExpert
interface, you configure the interesting traffic for each application, and turn on rules for compression, caching, rewrite,
filtering, responder and the application firewall, instead of having to configure each feature individually.
T he Web Interface AppExpert Template contains rules for the following application firewall signatures and security checks:
"Deny URL check." Detects connections to content that is known to pose a security risk, or to any other URLs that you
designate.
"Buf f er Overf low check." Detects attempts to cause a buffer overflow on a protected web server.
"Cookie Consistency check." Detects malicious modifications to cookies set by a protected web site.
"Form Field Consistency check." Detects modifications to the structure of a web form on a protected web site.
"CSRF Form Tagging check." Detects cross-site request forgery attacks.
For information on installing and using an AppExpert Template, see "AppExpert Applications and Templates."
T he NetScaler configuration utility is a web-based interface that provides access to all configuration options for the
application firewall feature, including advanced configuration and management options that are not available from any
other configuration tool or interface. Specifically, many advanced Signatures options can be configured only in the
configuration utility. You can review recommendations generated by the learning feature only in the configuration utility.
You can bind policies to a bind point other than Global only in the configuration utility.
For a description of the configuration utility, see "T he Application Firewall Configuration Interfaces." For more information
on using the configuration utility to configure the application firewall, see "Manual Configuration By Using the
Configuration Utility."
For instructions on configuring the application firewall by using the configuration utility, see "Manual Configuration By Using
the Configuration Utility." For information on the Citrix NetScaler Configuration Utility, see "T he Application Firewall
Configuration Interfaces."
T he Citrix NetScaler command line interface is a modified UNIX shell based on the FreeBSD bash shell. To configure the
Application Firewall from the command line interface, you type commands at the prompt and press the Enter key, just as
you do with any other Unix shell. You can configure most parameters and options for the application firewall by using the
NetScaler command line. Exceptions are the signatures feature, many of whose options can be configured only by using
the configuration utility or the Application Firewall wizard, and the learning feature, whose recommendations can only be
reviewed in the configuration utility.
For instructions on configuring the application firewall by using the NetScaler command line, see "Manual Configuration By
Using the Command Line Interface."
If you are configuring a dedicated Citrix Application Firewall ADC or are upgrading an existing Citrix NetScaler ADC or
VPX, the feature is already enabled. You do not have to perform either of the procedures described here.
If you have a new NetScaler ADC or VPX, you need to enable the application firewall feature before you configure it.
If you are upgrading a NetScaler ADC or VPX from a previous version of the NetScaler operating system to the current
version, you might need to enable the application firewall feature before you configure it.
Note: If you are upgrading a NetScaler ADC or VPX from a previous version, you might also need to update the licenses on
your ADC or VPX before you can enable the application firewall. Check with your Citrix representative or reseller to obtain
the correct license.
You can enable the application firewall by using the command line or the configuration utility.
To enable the application firewall by using the command line interf ace
To run the Application Firewall Wizard, open the configuration utility and follow these steps:
For more information about the configuration utility, see "T he Application Firewall Configuration Interfaces."
1. Specif y Name: on this screen, when creating a new security configuration, specify a meaningful name and the
appropriate type (HT ML, XML or WEB 2.0) for your profile. T he default policy and signatures are auto-generated by using
the same name.
Profile Name
T he name can begin with a letter, number, or the underscore symbol, and can consist of from 1 to 31 letters, numbers, and
the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=), colon (:), and underscore (_) symbols. Choose a name that
makes it easy for others to tell what content your new security configuration protects.
Note: Because the wizard uses this name for both the policy and the profile, it is limited to 31 characters. Manually created
policies can have names up to 127 characters in length.
When modifying an existing configuration, you select Modify Existing Configuration and then, in the Name drop-down list,
select the name of the existing configuration that you want to modify.
Note: Only policies that are bound to global or to a bind point appear in this list; you cannot modify an unbound policy by
using the Application Firewall wizard. You must either manually bind it to Global or a bind point, or modify it manually. (For
manual modification, in the configuration utility Application Firewall > Policies > Firewall pane, select the policy and click
Open).
Profile Type
You also select a profile type on this screen. T he profile type determines the types of advanced protection (security checks)
that can be configured. Because certain kinds of content are not vulnerable to certain types of security threats, restricting
the list of available checks saves time during configuration. T he types of Application Firewall profiles are:
Web Application (HT ML). Any HT ML-based Web site that does not use XML or Web 2.0 technologies.
XML Application (XML, SOAP). Any XML-based Web service.
Note: If you are unsure which type of content is used on your website, you can choose Web 2.0 Application to ensure that
you protect all types of web application content.
2. Specif y Rule: on this screen, you specify the policy rule (expression) that defines the traffic the current configuration
examines. If you create an initial configuration to protect your websites and web services, you can accept the default
value, true, which selects all web traffic .
If you want this security configuration to examine, not all HT T P traffic that is routed through the appliance, but specific
traffic, you can write a policy rule specifying the traffic that you want it to examine. Rules are written in Citrix NetScaler
expressions language, which is a fully functional object-oriented programming language. For more information,
see Configure a Custom Policy Expression.
Note: In addition to the default expressions syntax, for backward compatibility the NetScaler operating system supports
the NetScaler classic expressions syntax on NetScaler Classic and nCore appliances and virtual appliances. Classic
expressions are not supported on NetScaler Cluster appliances and virtual appliances. Current users who want to migrate
their existing configurations to the NetScaler cluster must migrate any policies that contain classic expressions to the
default expressions syntax.
For a simple description of using the NetScaler expressions syntax to create Application Firewall rules, and a list of useful
rules, see "Firewall Policies."
For a detailed explanation of how to create policy rules in NetScaler expressions syntax, see "Policies and Expressions."
4 . Select Signatures: on this screen, you select the categories of signatures that you want to use to protect your web
sites and web services.
T his is not a mandatory step, and you can skip it if you want to and go to the Specif y Deep Protections screen. If the
Select Signatures screen is skipped, only a profile and associated policies are created, and the signatures are not created.
If you are creating a new security configuration, the signature categories that you select are enabled, and by default they
are recorded in a new signatures object. T he new signatures object is assigned the same name that you entered on the
Specify name screen as the name of the security configuration.
If you have previously configured signatures objects and want to use one of them as the signatures object associated with
the security configuration that you are creating, click Select Existing Signature and select a signatures object from the
Signatures list.
If you are modifying an existing security configuration, you can click Select Existing Signature and assign a different
signatures object to the security configuration.
If you click Create New Signature, you can choose the edit mode as Simple or Advanced.
T he simple mode allows for easy configuration of the signature, with a preset list of protection definitions for common
applications such as IIS (Internet Information Server), PHP and ActiveX. T he default categories in Simple mode are:
CGI. Protection against attacks on web sites that use CGI scripts in any language, including PERL scripts, Unix shell scripts,
Cold Fusion. Protection against attacks on web sites that use the Adobe Systems® ColdFusion® Web development
platform.
FrontPage. Protection against attacks on web sites that use the Microsoft® FrontPage® Web development platform.
PHP. Protection against attacks on web sites that use the PHP open-source Web development scripting language.
Client side. Protection against attacks on client-side tools used to access your protected web sites, such as Microsoft
Internet Explorer, Mozilla Firefox, the Opera browser, and the Adobe Acrobat Reader.
Microsoft IIS. Protection against attacks on Web sites that run the Microsoft Internet Information Server (IIS).
Miscellaneous. Protection against attacks on other server-side tools, such as Web servers and database servers.
On this screen, you select the actions associated with the signature categories that you selected on the Select Signatures
screen. T he actions that you can configure are:
Block
Log
Stats
By default the Log and Stats actions are enabled but not the Block action. To configure actions, click Settings. You can
change the action settings of all the selected categories by using the Action drop-down menu.
T he advanced mode allows for more granular control over the signature definitions and provides significantly more
information. Use the advanced mode if you want complete control over signature definition.
T he contents of this screen are the same as the contents of the Modify Signatures Object dialog box, as described in
"Configuring or Modifying a Signatures Object." In this screen, you can configure actions either by clicking the Actions drop-
down menu or the actions menu, which appears as a cirle with three dots.
7. Specif y Deep Protections: on this screen, you choose the advanced protections (also called security checks or simply
checks) that you want to use to protect your web sites and web services. Which checks are available depends on the profile
type that you chose on the Specify Name screen. All checks are available for Web 2.0 Application profiles.
For more information, see Overview of Security Checks and see "Advanced Form Protections Checks."
You configure the actions for the advanced protections that you have enabled.T he actions that you can configure are:
To view all logs for a specific check, select that check, and then click Logs to display the Syslog Viewer, as described in
"Application Firewall Logs." If a security check is blocking legitimate access to your protected web site or web service, you
can create and implement a relaxation for that security check by selecting a log that shows the unwanted blocking, and
then clicking Deploy.
After you completing specifying Action Settings, click Finish to complete the wizard.
Following are four procedures that show how to perform specific types of configuration by using the Application Firewall
wizard.
Follow these steps to create a new firewall configuration and signature objects, by using the Applicaiton Firewall Wizard.
1. Navigate to Security > Application Firewall.
2. In the details pane, under Getting Started, click Application Firewall Wizard.T he wizard opens.
3. On the Specif y Name screen, select Create New Conf iguration.
4. In the Name field, type a name, and then click Next.
5. In the Specif y Rule screen, click Next again.
6. In the Select Signatures screen, select Create New Signature and Simple as the edit mode, and then click Next.
7. In the Specif y Signature Protections screen, configure the required settings. For more information about which
signatures to consider for blocking and how to determine when you can safely enable blocking for a signature, see
"Signatures."
8. In the Specif y Deep Protections screen configure the required actions and parameters in Action Settings.
9. When you complete, click Finish to close the Application Firewall Wizard.
Follow these steps to modify an existing configuration and existing signature categories.
1. Navigate to Security > Application Firewall.
2. In the details pane, under Getting Started, click Application Firewall Wizard. T he wizard opens.
3. On the Specify Name screen, select Modify Existing Configuration and, in the Name drop-down list, choose the security
configuration that you created during new configuration, and then click Next.
4. In the Specify Rule screen, click Next to keep the default value "true." If you want to modify the rule, follow the steps
described in "Configure a Custom Policy Expresssion."
5. In the Select Signatures screen, click Select Existing Signature. From the Existing Signature drop-down menu, select
the appropriate option, and then click Next. T he advanced signature protection screen appears.
Note: If you select an existing signature, the default edit mode for signature protected is advanced.
6. In the Specify Signature Protections screen, configure the required settings and click Next. For more information about
which signatures to consider for blocking and how to determine when you can safely enable blocking for a signature, see
"Signatures."
7. In the Specify Deep Protections screen, configure the settings and click Next.
8. After you complete, click Finish to close the Application Firewall Wizard.
Follow these steps to use the Application Firewall Wizard to skip the Select Signatures screen and create a new
configuration with just the profile and the associated policies but without any signatures.
Follow these steps to use the Application Firewall Wizard to create a specialized security configuration to protect only
specific content. In this case, you create a new security configuration instead of modifying the initial configuration. T his
type of security configuration requires a custom rule, so that the policy applies the configuration to only the selected Web
traffic.
If you are familiar with how the application firewall works and prefer manual configuration, you can manually configure a
signatures object and a profile, associate the signatures object with the profile, create a policy with a rule that matches the
web traffic that you want to configure, and associate the policy with the profile. You then bind the policy to Global, or to a
bind point, to put it into effect, and you have created a complete security configuration.
For manual configuration, you can use the configuration utility (a graphical interface) or the command line. Citrix
recommends that you use the configuration utility. Not all configuration tasks can be performed at the command line.
Certain tasks, such as enabling signatures and reviewing learned data, must be done in the configuration utility. Most other
tasks are easier to perform in the configuration utility.
Replicating Configuration
When you use the configuration utility (GUI) or the command line interface (CLI) to manually configure the application
firewall, the configuration is saved in the /nsconfig/ns.conf file. You can use the commands in that file to replicate the
configuration on another appliance. You can cut and paste the commands into the CLI one by one, or you can save multiple
commands in a text file in the /var/tmp folder and run them as a batch file. Following is an example of running a batch file
containing commands copied from the /nsconfig/ns.conf file of a different appliance:
Warning
Import commands are not saved in the ns.conf file. Before running commands from the ns.conf file to replicate the configuration
on another appliance, you must import all the objects used in the configuration (for example, signatures, error page, WSDL, and
Schema) to the appliance on which you will replicate the configuration. T he add command to add an application firewall profile
saved in an ns.conf file might include the name of an imported object, but such a command might fail when executed on another
appliance if the referenced object does not exist on that appliance.
Before you can configure the signatures, you must create a new signatures object from the appropriate default signatures
object template. Assign the copy a new name, and then configure the copy. You cannot configure or modify the default
signatures objects directly. T he following procedure provides basic instructions for configuring a signatures object. For more
detailed instructions, see "Manually Configuring the Signatures Feature." If you need to create your own, user-defined
signatures, see "T he Signatures Editor."
* Def ault Signatures. Contains the signatures rules, the SQL injection rules, and the cross-site scripting rules.
* XPath Injection. Contains all of the items in the * Default Signatures, and in addition, contains the XPath injection
rules.
3. In the Add Signatures Object dialog box, type a name for your new signatures object, click OK, and then click Close. T he
name can begin with a letter, number, or the underscore symbol, and can consist of from one to 31 letters, numbers, and
the hyphen (-), period (.) pound (#), space ( ), at (@), equals (=), and underscore (_) symbols.
4. Select the signatures object that you created, and then click Open.
5. In the Modify Signatures Object dialog box, set the Display Filter Criteria options at the left to display the filter items
that you want to configure.
As you modify these options, the results that you specify are displayed in the Filtered Results window at the right. For
more information about the categories of signatures, see "Signatures."
6. In the Filtered Results area, configure the settings for a signature by selecting and clearing the appropriate checkboxes.
7. When finished, finished, click Close.
Creating an application firewall profile requires that you specify only a few configuration details.
T o review learned exceptions or rules for a check, select the check, and then click Learned Violations. In the Manage
Learned Rules dialog box, select each learned exception or rule in turn.
T o edit the exception or rule, and then add it to the list, click Edit & Deploy.
T o accept the exception or rule without modification, click Deploy.
T o remove the exception or rule from the list, click Skip.
T o refresh the list of exceptions or rules to be reviewed, click Refresh.
T o open the Learning Visualizer and use it to review learned rules, click Visualizer.
T o review the log entries for connections that matched a check, select the check, and then click Logs. You can use
this information to determine which checks are matching attacks so that you can enable blocking for those checks.
You can also use this information to determine which checks are matching legitimate traffic, so that you can
configure an appropriate exemption to allow those legitimate connections. For more information about the logs, see
"Logs, Statistics, and Reports."
T o completely disable a check, in the list, clear all of the checkboxes to the right of that check.
4. On the Settings tab, configure the profile settings.
T o associate the profile with the set of signatures that you previously created and configured, under Common
Settings, choose that set of signatures in the Signatures drop-down list.
Note: You may need to use the scroll bar on the right of the dialog box to scroll down to display the Common
Settings section.
T o configure an HT ML or XML Error Object, select the object from the appropriate drop-down list.
Note: You must first upload the error object that you want to use in the Import pane.
T o configure the default XML Content T ype, type the content type string directly into the Default Request and
Default Response text boxes, or click Manage Allowed Content T ypes to manage the list of allowed content types.
5. If you want to use the learning feature, click Learning, and configure the learning settings for the profile.. For more
information, see Configure and Learning feature.
6. Click OK to save your changes and return to the Profiles pane.
Updated: 2014-06-12
You configure two different types of information in this dialog box, depending upon which security check you are
configuring. In the majority of cases, you configure an exception (or relaxation) to the security check. If you are configuring
the Deny URL check or the Field Formats check, you configure an addition (or rule). T he process for either of these is the
same.
6. Fill in the dialog box as described below. T he dialog boxes for each check are different; the list below covers all elements
that might appear in any dialog box.
Enabled check box— Select to place this relaxation or rule in active use; clear to deactivate it.
Attachment Content Type— T he Content-Type attribute of an XML attachment. In the text area, enter a regular
expression that matches the Content-Type attribute of the XML attachments to allow.
Action URL— In the text area, enter a PCRE-format regular expression that defines the URL to which data entered
into the web form is delivered.
Cookie— In the text area, enter a PCRE-format regular expression that defines the cookie.
Field Name— A web form field name element may be labeled Field Name, Form Field, or another similar name. In the
text area, enter a PCRE-format regular expression that defines the name of the form field.
Form Origin URL— In the text area, enter a PCRE-format regular expression that defines the URL that hosts the web
form.
Form Action URL— In the text area, enter a PCRE-format regular expression that defines the URL to which data
entered into the web form is delivered.
Name— An XML element or attribute name. In the text area, enter a PCRE-format regular expression that defines the
name of the element or attribute.
URL— A URL element may be labeled Action URL, Deny URL, Form Action URL, Form Origin URL, Start URL, or simply
URL. In the text area, enter a PCRE-format regular expression that defines the URL.
Format— T he format section contains multiple settings that include list boxes and text boxes. Any of the following
can appear:
Type— Select a field type in the T ype drop-down list. T o add a new field type definition, click Manage—
Minimum Length— T ype a positive integer that represents the minimum length in characters if you want to force
users to fill in this field. Default: 0 (Allows field to be left blank.)
Percentage of times threshold. Depending on which security check’s learning settings you are configuring, the
percentage of times threshold might refer to the percentage of total observed user sessions that violated the
security check, the percentage of requests, or the percentage of times a form field matched a particular field type,
before a learned relaxation is generated. Default: 0
5. T o remove all learned data and reset the learning feature, so that it must start its observations again from the beginning,
click Remove All Learned Data.
Note: T his button removes only learned recommendations that have not been reviewed and either approved or skipped.
If you are configuring an existing firewall policy, this field is read-only. You cannot modify it.
4. Select the profile that you want to associate with this policy from the Profile drop-down list. You can create a new
profile to associate with your policy by clicking New, and you can modify an existing profile by clicking Modify.
5. In the Expression text area, create a rule for your policy.
You can type a rule directly into the text area.
You can click Prefix to select the first term for your rule, and follow the prompts. See "T o Create an Application
Firewall Rule (Expression)" for a complete description of this process.
You can click Add to open the Add Expression dialog box, and use it to construct the rule. See "T he Add Expression
Dialog Box" for a complete description of this process.
6. Click Create or OK, and then click Close.
T he policy rule, also called the expression, defines the web traffic that the application firewall filters by using the profile
associated with the policy. Like other NetScaler policy rules (or expressions), application firewall rules use NetScaler
expressions syntax. T his syntax is powerful, flexible, and extensible. It is too complex to describe completely in this set of
instructions. You can use the following procedure to create a simple firewall policy rule, or you can read it as an overview of
the policy creation process.
When you have decided which term you want, double-click it to insert it into the Expression window.
4. T ype a period after the term you just chose. You are then prompted to choose your next term, as described in the
previous step. When a term requires that you type a value, fill in the appropriate value. For example, if you choose
HTTP.REQ.HEADER(""), type the header name between the quotation marks.
5. Continue choosing terms from the prompts and filling in any values that are needed, until your expression is finished.
Following are some examples of expressions for specific purposes.
HTTP.REQ.HEADER("Host").EQ("shopping.example.com")
For shopping.example.com, substitute the name of the web host that you want to match.
Specific web f older or directory. To match traffic from a particular folder or directory on a Web host:
HTTP.REQ.URL.STARTSWITH("https//www.example.com/folder")
For www.example.com, substitute the name of the web host. For folder, substitute the folder or path to the content
that you want to match. For example, if your shopping cart is in a folder called /solutions/orders, you substitute that
string for folder.
HTTP.REQ.URL.ENDSWITH(".gif")
To match other format images, substitute another string in place of .gif.
HTTP.REQ.URL.STARTSWITH("https//www.example.com/CGI-BIN")
To match all JavaScripts with .js extensions:
HTTP.REQ.URL.ENDSWITH(".js")
For more information about creating policy expressions, see "Policies and Expressions."
Note: If you use the command line to configure a policy, remember to escape any double quotation marks within
NetScaler expressions. For example, the following expression is correct if entered in the configuration utility:
HTTP.REQ.HEADER("Host").EQ("shopping.example.com")
If entered at the command line, however, you must type this instead:
HTTP.REQ.HEADER(\"Host\").EQ(\"shopping.example.com\")
To add a firewall rule (expression) by using the Add Expression dialog box
T he Add Expression dialog box (also referred to as the Expression Editor) helps users who are not familiar with the
NetScaler expressions language to construct a policy that matches the traffic that they want to filter.
1. If you have not already done so, navigate to the appropriate location in the Application Firewall wizard or the NetScaler
configuration utility:
If you are configuring a policy in the Application Firewall wizard, in the navigation pane, click Application Firewall, then
in the details pane click Application Firewall Wizard, and then navigate to the Specify Rule screen.
If you are configuring a policy manually, in the navigation pane, expand Application Firewall, then Policies, and then
Firewall. In the details pane, to create a new policy, click Add. T o modify an existing policy, select the policy, and then
click Open.
2. On the Specify Rule screen, in the Create Application Firewall Profile dialog box, or in the Configure Application Firewall
Profile dialog box, click Add.
3. In the Add Expression dialog box, in the Construct Expression area, in the first list box, choose one of the following
prefixes:
HTTP. T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the
HT T P protocol. T he default choice.
SYS. T he protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to the
recipient of the request.
CLIENT. T he computer that sent the request. Choose this if you want to examine some aspect of the sender of the
request.
SERVER. T he computer to which the request was sent. Choose this if you want to examine some aspect of the
recipient of the request.
4. In the second list box, choose your next term. T he available terms differ depending on the choice you made in the
previous step, because the dialog box automatically adjusts the list to contain only those terms that are valid for the
context. For example, if you selected HTTP in the previous list box, the only choice is REQ, for requests. Because the
application firewall treats requests and associated responses as a single unit and filters both, you do not need to specific
responses separately. After you choose your second term, a third list box appears to the right of the second. T he Help
window displays a description of the second term, and the Preview Expression window displays your expression.
5. In the third list box, choose the next term. A new list box appears to the right, and the Help window changes to display a
description of the new term. T he Preview Expression window updates to display the expression as you have specified it
to that point.
To manually configure the application firewall by using the NetScaler command line, use a telnet or secure shell client of
your choice to log on to the NetScaler command line.
Example
T he following example adds a profile named pr-basic, with basic defaults, and assigns a profile type of HTML. T his is the
appropriate initial configuration for a profile to protect an HT ML Web site.
set appfw profile <name> <arg1> [<arg2> ...] where <arg1> represents a parameter and <arg2> represents either another
parameter or the value to assign to the parameter represented by <arg1>. For descriptions of the parameters to use
when configuring specific security checks, see Advanced Protections and its subtopics. For descriptions of the other
parameters, see "Parameters for Creating a Profile."
save ns config
Example
T he following example shows how to configure an HT ML profile created with basic defaults to begin protecting a simple
HT ML-based Web site. T his example turns on logging and maintenance of statistics for most security checks, but enables
blocking only for those checks that have extremely low false positive rates and require no special configuration. It also
turns on transformation of unsafe HT ML and unsafe SQL, which prevents attacks but does not block requests to your
Web sites. With logging and statistics enabled, you can later review the logs to determine whether to enable blocking for a
Example
T he following example adds a policy named pl-blog, with a rule that intercepts all traffic to or from the host
blog.example.com, and associates that policy with the profile pr-blog. T his is an appropriate policy to protect a blog hosted
on a specific hostname.
Example
T he following example binds the policy named pl-blog and assigns it a priority of 10.
Done
You can create your own signatures or use the signatures in the built-in templates. T he application firewall has two built-in
templates:
*Def ault Signatures: T his template contains a preconfigured list of over 1,300 signatures, in addition to a complete list
of SQL injection keywords, SQL special strings, SQL transform rules, and SQL wildchar characters. It also contains denied
patterns for cross-site scripting, and allowed attributes and tags for cross-site scripting. T his is a read-only template. You
can view the contents, but you cannot add, edit, or delete anything in this template. T o use it, you must make a copy. In
your own copy, you can enable the signature rules that you want to apply to your traffic, and specify the actions to be
taken when the signature rules match the traffic.
T he application firewall signatures are derived from the rules published by Snort, which is an open source intrusion
prevention system capable of performing real-time traffic analysis to detect a variety of attacks and probes.
*Xpath Injection Patterns: T his template contains a preconfigured set of literal and PCRE keywords and special strings
that are used to detect XPath (XML Path Language) injection attacks.
Blank Signatures: In addition to making a copy of the built-in *Default Signatures template, you can use a blank
signatures template to create a new signature object. T he signature object that you create with the blank signatures
option does not have any native signature rules, but, just like the *Default template, it has all the SQL/XSS built-in entities.
External-Format Signatures: T he application firewall also supports the use of external format signatures. You can import
the scan files of the third party scan tools by using the XSLT files that are supported by the Citrix application firewall. A set
of built-in XSLT files are available for the following scan tools to translate these external format files to the Native format:
Cenzic
Deep Security for Web Apps
IBM AppScan Enterprise
IBM AppScan Standard.
Qualys
Whitehat
Hewlett Packard Enterprise WebInspect
T ighter security increases processing overhead. Signatures provide the following deployment options to help you to
optimize the protection of your applications:
Negative Security Model: With the negative security model, you use a rich set of preconfigured signature rules to
leverage the power of pattern matching to detect attacks and protect against application vulnerabilities. You block only
what you don’t want and allow the rest.[DR1] You can add your own signature rules, based on the specific security
needs of your applications, to design your own customized security solutions.
To protect your application by using signatures, you must configure one or more profiles to use your signatures object. In a
hybrid security configuration, the SQL injection and Cross-Site scripting patterns, and the SQL transformation rules, in your
signatures object are used not only by the signature rules, but also by the positive security checks configured in the
application firewall profile that is using the signatures object.
T he application firewall examines the traffic to your protected web sites and web services to detect traffic that matches a
signature. A match is triggered only when every pattern in the rule matches the traffic. When a match occurs, the specified
actions for the rule are invoked. You can display an error page or error object when a request is blocked. Log messages can
help you to identify attacks being launched against your application. If you enable statistics, the application firewall
maintains data about requests that match an application firewall signature or security check.
If the traffic matches both a signature and a positive security check, the more restrictive of the two actions is enforced.
For example, if a request matches a signature rule for which the block action is disabled, but the request also matches an
SQL Injection positive security check for which the action is block, the request is blocked. In this case, the signature
violation might be logged as <not blocked>, although the request is blocked by the SQL injection check.
Customization: If necessary, you can add your own rules to a signatures object. You can also customize the SQL/XSS
patterns. T he option to add your own signature rules, based on the specific security needs of your applications, gives you
the flexibility to design your own customized security solutions. You block only what you don’t want and allow the rest. A
specific fast-match pattern in a specified location can significantly reduce processing overhead to optimize performance.
You can add, modify, or remove SQL injection and cross-site scripting patterns. Built-in RegEx and expression editors help
you configure your patterns and verify their accuracy.
Auto-update: You can manually update the signature object to get the latest signature rules, or you can leverage the
auto-update feature so that the application firewall can automatically update the signatures from the cloud-based
application firewall updates service.
Note
If new signature rules are added during auto-update, they are disabled by default. You should periodically review the updated
signatures and enable the newly added rules that are pertinent for protecting your applications.
Getting Started
Using Citrix signatures to protect your application is quite easy and can be accomplished in a few simple steps:
You can use the Wizard that prompts you to create the entire application firewall configuration, including adding the
profile and policy, selecting and enabling signatures, and specifying actions for signatures and positive security checks.
T he signatures object is created automatically.
You can create a copy of the signatures object from the *Default Signatures template, use a blank template to create a
new signature with your own customized rules, or add an external format signature. Enable the rules and configure the
actions that you want to apply.
Highlights:
T he *Default signatures object is a template. It cannot be edited or deleted. T o use it, you must create a copy. In your
own copy, you can enable the rules and the desired action for each rule as required for your application. T o protect the
application, you must configure the target profile to use this signature.
Processing signature patterns has overhead. T ry to enable only those signatures that are applicable for protecting your
application, rather than enabling all signature rules.
Every pattern in the rule must match to trigger a signature match.
You can add your own customized rules to inspect incoming requests to detect various types of attacks, such as SQL
injection or cross-site scripting attacks. You can also add rules to inspect the responses to detect and block leakage of
sensitive information such as credit card numbers.
You can make a copy of an existing signatures object and tweak it, by adding or editing rules and SQL/XSS patterns, to
protect another application.
You can use auto-update to download the latest version of the application firewall default rules without need for
ongoing monitoring to check for the availability of the new update.
A signature object can be used by more than one profile. Even after you have configured one or more profile(s) to use a
signature object, you can still enable or disable signatures or change the action settings. You can manually create and
modify your own custom signature rules. T he changes will apply to all the profiles that are currently configured to use
this signature object.
You can configure signatures to detect violations in various types of payloads, such as HT ML, XML, JSON, and GWT .
You can export a configured signatures object and import it to another NetScaler appliance for easy replication of your
customized signature rules.
Signatures are patterns that are associated with a known vulnerability. You can use signature protection to identify the
traffic that attempts to exploit these vulnerabilities, and take specific actions.
Signatures are organized into categories. You can optimize the performance and reduce the processing overhead by
enabling only the rules in the categories that are appropriate for protecting your application.
To manually configure the signatures feature, use a browser to connect to the configuration utility. T hen, create a
signatures object from a built-in template, an existing signatures object, or by importing a file. Next, configure the new
signatures object as explained in Configuring or Modifying a Signatures Object.
You must use the configuration utility to copy a template or existing signatures object. You can use either the configuration
utility or the command line to import a signatures object. You can also use either the configuration utility or the command
line to remove a signatures object.
* Def ault Signatures. Contains the signatures rules, the SQL injection rules, and the cross-site scripting rules.
* XPath Injection. Contains the XPath injection patterns.
Any existing signatures object.
Attention: If you do not choose a signatures type to use as a template, the application firewall will prompt you to
create signatures from scratch.
3. Click Add.
4. In the Add Signatures Object dialog box, type a name for your new signatures object, and then click OK. T he name can
begin with a letter, number, or the underscore symbol, and can consist of from one to 31 letters, numbers, and the
hyphen (-), period (.) pound (#), space ( ), at (@), equals (=), and underscore (_) symbols.
5. Click Close.
Example #1
T he following example creates a new signatures object from a file named signatures.xml and assigns it the name
MySignatures.
T o display only selected categories of signatures, check or clear the appropriate signature-category check boxes. T he
signature categories are:
coldfusion Web sites that use the Adobe Systems ColdFusion application server.
iis Web sites that use the Microsoft Internet Information Server (IIS).
web-struts Web sites that contain Apache struts, which are java-ee based applets.
T o display only signatures that have specific check actions enabled, select the ON check box for each of those
actions, clear the ON check boxes for the other actions, and clear all of the OFF check boxes. T o display only
signatures that have a specific check action disabled, select their respective OFF check boxes and clear all of the ON
check boxes. T o display signatures regardless of whether they have a check action enabled or disabled, select or clear
both the ON and the OFF check boxes for that action. T he check actions are:
Criterion Description
Enabled T he signature is enabled. T he application firewall checks only for signatures that are enabled when it
processes traffic.
Stats T he application firewall includes any connection that matches this signature in the statistics that it
generates for that check.
T o display only signatures that contain a specific string, type the string into the text box under the filter criteria, and
then click Search.
T o reset all display filter criteria to the default settings and display all signatures, click Show All.
4. For information about a specific signature, select the signature, and then click the blue double arrow in the More field.
T he Signature Rule Vulnerability Detail message box appears. It contains information about the purpose of the signature
and provides links to external web-based information about the vulnerability or vulnerabilities that this signature
addresses. T o access an external link, click the blue double arrow to the left of the description of that link.
5. Configure the settings for a signature by selecting the appropriate check boxes.
6. If you want to add a local signature rule to the signatures object, or modify an existing local signature rule, see "T he
Signatures Editor."
7. If you have no need for SQL injection, cross-site scripting, or Xpath injection patterns, click OK, and then click Close.
Otherwise, in the lower left-hand corner of the details pane, click Manage SQL/XSS Patterns.
8. In the Manage SQL/XSS Patterns dialog box, Filtered Results window, navigate to the pattern category and pattern
that you want to configure. For information about the SQL injection patterns, see "HT ML SQL Injection Check." For
information about the cross-site scripting patterns, see "HT ML Cross-Site Scripting Check."
9. T o add a new pattern:
1. Select the branch to which you want to add the new pattern.
2. Click the Add button directly below the lower section of the Filtered Results window.
3. In the Create Signature Item dialog box, fill in the Element text box with the pattern that you want to add. If you are
adding a transformation pattern to the transform rules branch, under Elements, fill in the From text box with the
pattern that you want to change and the T o text box with the pattern to which you want to change the previous
pattern.
4. Click OK.
10. T o modify an existing pattern:
1. In the Filtered Results window, select the branch that contains the pattern that you want to modify.
2. In the detail window beneath the Filtered Results window, select the pattern that you want to modify.
3. Click Modify.
4. In the Modify Signature Item dialog box, Element text box, modify the pattern. If you are modifying a transformation
pattern, you can modify either or both patterns under Elements, in the From and the T o text boxes.
5. Click OK.
11. T o remove a pattern, select the pattern that you want to remove, then click the Remove button below the details pane
beneath the Filtered Results window. When prompted, confirm your choice by clicking Close.
12. T o add the patterns category to the XSS branch:
1. Select the branch to which you want to add the patterns category.
2. Click the Add button directly below the Filtered Results window.
Note: Currently you can add only one category, named patterns, to the XSS branch, so after you click Add, you must
accept the default choice, which is patterns.
3. Click OK.
13. T o remove a branch, select that branch, and then click the Remove button directly below the Filtered Results window.
When prompted, confirm your choice by clicking OK.
Note: If you remove a default branch, you remove all of the patterns in that branch. Doing so can disable the security
T he JSON payload is typically sent with the MIME type specified as application/json. T he other “standard” content types
for JSON are:
application/x-javascript
text/javascript
text/x-javascript
text/x-json
To allow JSON requests, the appliance is preconfigured with the JSON content type as shown in the following show-
command output:
T he Citrix application firewall processes the post body for the following content-types only:
application/x-www-f orm-urlencoded
multipart/f orm-data
text/x-gwt-rpc
T he requests that are received with other content-type headers including application/json (or any other allowed content
type) are forwarded to the backend after header inspection. T he post body in such requests is not inspected for security
check violations even when the profile’s security checks such as SQL or XSS are enabled.
In order to protect JSON applications and detect violations, application firewall signatures can be used. All requests that
contain the allowed content-type header are processed by the application firewall for signature match. You can add your
own customized signature rules to process JSON payload to perform various security check inspections (for example, XSS,
SQL, and Field Consistency), to detect violations in the headers as well as the post body, and take specified actions.
Tip
Unlike the other built-in defaults, the preconfigured JSON content type can be edited or removed by using the CLI or the
configuration utility (GUI). If legitimate requests for JSON applications are getting blocked and triggering content-type violations,
check to make sure that the content type value is configured accurately. For additional details regarding how application firewall
processes content-type header, see http://docs.citrix.com/en-us/netscaler/11/security/application-firewall/content-type-
protection.html
Navigate to Security > Application Firewall and, in the Settings section, select Manage JSON Content Types.
In the Configure Application Firewall JSON Content Type panel, add, edit, or delete JSON content types to suit the
needs of your applications.
In addition to a valid JSON content type, you need to configure signatures to specify the pattern(s) that, when detected in
a JSON request, indicate a security breach. T he specified actions, such as block and log, are taken when an incoming request
triggers a match for all the target patterns in the signature rule.
To add a customized signature rule, Citrix recommends that you use the configuration utility. Navigate to System >
Security > Application Firewall > Signatures. Double click the target signature object to access the Edit Application
Firewall Signatures panel. Click on the Add button to configure the actions, category, log string, rule patterns and so on.
Although application firewall inspects all allowed content-type payload for signature match, you can optimize the
processing by specifying the JSON expression in the rule. When you Add a new rule pattern, select Expression in the drop-
down options for Match and provide the target match expression from your JSON payload to identify the specific requests
that need to be inspected. An expression must begin with a TEXT. prefix. You can add other rule patterns to specify
additional match patterns to identify the attack.
T he following example shows a signature rule. If any cross-site script tag is detected in the POST body of the JSON
payload that matches the specified XPAT H_JSON expression, a signature match is triggered.
<PatternList>
<RequestPatterns>
<Pattern>
</Pattern>
<Pattern>
</Pattern>
<Pattern>
<Match type="CrossSiteScripting"/>
</Pattern>
</RequestPatterns>
</PatternList>
<Comment/>
</SignatureRule>
T he following payload triggers the signature match, because it includes the cross-site scripting tag <Gotcha!!>.
Aug 21 12:21:42 <local0.info> 10.217.31.239 08/21/2015:23:21:42 GMT ns 0-PPE-1 : APPFW APPFW_SIGNAT URE_MATCH
1471 0 : 10.217.253.62 990-PPE0 NtJnVMNnvPeQJnaUzXYW/GTvAQsA010 prof1 http://10.217.31.212/FFC/login_post.php
Signature violation rule ID 1000001: cross-site scripting violation detected in json payload <not blocked>
Note
If you send the same payload after removing the cross-site script tag (<Gotcha!!>), the signature rule match is not triggered.
Highlights:
T o protect JSON payload, use application firewall signatures to detect XSS, SQL and other violations.
Verify that the JSON content type is configured on the appliance as the allowed content type.
Make sure that the content type in the payload matches the configured JSON content type.
Make sure that all the patterns configured in the signature rule match for the signature violation to be triggered.
When you add a signature rule, it MUST have at least one Rule pattern to match the Expression in the JSON payload. All
the PI expressions in signature rules must start with the prefix T EXT . and must be Boolean.
Code COPY
Citrix regularly updates the default signatures for the application firewall. You can update the default signatures manually
or automatically. In either case, ask your Citrix representative or Citrix reseller for the URL to access the updates. You can
enable automatic updates of the Citrix native format signatures in the "Engine Settings" and "Signature Auto Update
Settings" dialog boxes.
Most makers of vulnerability scanning tools regularly update the tools. Most web sites also change frequently. You should
update your tool and rescan your web sites regularly, exporting the resulting signatures to a file and importing them into
your application firewall configuration.
Tip
When you update the application firewall signatures from the NetScaler command line, you must first update the default signatures,
and then issue additional update commands to update each custom signatures file that is based on the default signatures. If you do
not update the default signatures first, a version mismatch error prevents updating of the custom signatures files.
Note
T he following applies to merging a third-party signature object with a user-defined signature object with Native rules and user-
added rules:
When a version 0 signatures is merged with a new imported file, the resultant signatures will remain as version 0.
T his means all native (or built-in) rules in the imported file will be ignored after the merge. T his is to ensure that the version
0 signatures are maintained as is after a merge.
In order to include the native rules in the imported file for merge, you should update the existing signatures from version 0 first
before the merge. T his means you need to abandon the version 0 nature of the existing signatures.
To update the application firewall signatures f rom the source by using the command line
Example
T he following example updates the signatures object named MySignatures from the default signatures object, merging
new signatures in the default signatures object with the existing signatures. T his command does not overwrite any user-
Updated: 2014-10-06
Citrix regularly updates the signatures for the Application Firewall. You should regularly update the signatures on your
Application Firewall to ensure that your Application Firewall is using the most current list. Ask your Citrix representative or
Citrix reseller for the URL to access the updates.
To update a signatures object from a Citrix format file by using the command line
At the command prompt, type the following commands:
To update a signatures object from a Citrix format file by using the configuration
utility
1. Navigate to Security > Application Firewall > Signatures.
2. In the details pane, select the signatures object that you want to update.
3. In the Action drop-down list, select Merge.
4. In the Update Signatures Object dialog box, choose one of the following options.
Import f rom URL— Choose this option if you download signature updates from a web URL.
Import f rom Local File— Choose this option if you import signature updates from a file on your local hard drive,
network hard drive, or other storage device.
5. In the text area, type the URL, or type or browse to the local file.
6. Click Update. T he update file is imported, and the Update Signatures dialog box changes to a format nearly identical to
that of the Modify Signatures Object dialog box. T he Update Signatures Object dialog box displays all branches with
new or modified signature rules, SQL injection or cross-site scripting patterns, and XPath injection patterns if there are
any.
7. Review and configure the new and modified signatures.
8. When you are finished, click OK, and then click Close.
Updated: 2014-01-17
Note: Before you update a signatures object from a file, you must create the file by exporting signatures from the
vulnerability scanning tool.
To import and update signatures from a vulnerability scanning tool
1. Navigate to Security > Application Firewall > Signatures.
2. In the details pane, select the signatures object that you want to update, and then click Merge.
3. In the Update Signatures Object dialog box, on the External Format tab, Import section, choose one of the following
options.
Add a local rule if you need to protect your web sites and services from a known attack that the existing signatures do not
match. For example, you might discover a new type of attack and determine its characteristics by examining the logs on
your web server, or you might obtain third-party information about a new type of attack.
At the heart of a signature rule are the rule patterns, which collectively describe the characteristics of the attack that the
rule is designed to match. Each pattern can consist of a simple string, a PCRE-format regular expression, or the built-in SQL
injection or cross-site scripting patterns.
You might want to modify a signature rule by adding a new pattern or modifying an existing pattern to match an attack.
For example, you might find out about changes to an attack, or you might determine a better pattern by examining the
logs on your web server, or from third-party information.
6. In the LogString text box, type a brief description of the signature rule to be used in the logs.
7. In the Comment text box, type a comment. (Optional)
8. Click More..., and modify the advanced options.
1. T o strip HT ML comments before applying this signature rule, in the Strip Comments drop-down list choose All or
Ease of selection. For example, assume that all of signature rules in a particular group protect against attacks on a
specific type of web server software or technology. If your protected web sites use that software or technology, you
want to enable them all. If they do not, you do not want to enable any of them.
Ease of initial conf iguration. It is easiest to set defaults for a group of signatures as a category, instead of one-by-
one. You can then make any changes to individual signatures as needed.
Ease of ongoing conf iguration. It is easier to configure signatures if you can display only those that meet specific
criteria, such as belonging to a specific category.
Caution: Any new pattern that you add to a signature rule is in an AND relationship with the existing patterns. Do not add
a new pattern to an existing signature rule if you do not want a potential attack to have to match all of the patterns in
order to match the signature.
Each pattern can consist of a simple string, a PCRE-format regular expression, or the built-in SQL injection or cross-site
scripting pattern. Before you attempt to add a pattern that is based on a regular expression, you should make sure that
you understand PCRE-format regular expressions. PCRE expressions are complex and powerful; if you do not understand
how they work, you can unintentionally create a pattern that matches something that you did not want (a false positive)
or that fails to match something that you did want (a false negative).
If you are not already familiar with PCRE-format regular expressions, you can use the following resources to learn the
basics, or for help with some specific issue:
If you need to encode non-ASCII characters in a PCRE-format regular expression, the NetScaler platform supports
encoding of hexadecimal UT F-8 codes. For more information, see "PCRE Character Encoding Format."
In addition, as you choose a value from the Area drop-down list, the remaining parts of the Location area change
interactively. Following are all configuration items that might appear in this section.
Area
Drop-down list of elements that describe a particular portion of the HT T P connection. T he choices are as follows:
HTTP_ANY. All parts of the HT T P connection.
HTTP_COOKIE. All cookies in the HT T P request headers after any cookie transformations are performed.
Note: Does not search HT T P response "Set-Cookie:" headers.
HTTP_FORM_FIELD. Form fields and their contents, after URL decoding, percent decoding, and removal of excess
whitespace. You can use the <Location> tag to further restrict the list of form field names to be searched.
HTTP_HEADER. T he value portions of the HT T P header after any cross-site scripting or URL decoding
transformations.
HTTP_METHOD. T he HT T P request method.
HTTP_ORIGIN_URL. T he origin URL of a web form.
HTTP_POST_BODY. T he HT T P post body and the web form data that it contains.
HTTP_RAW_COOKIE. All HT T P request cookie, including the "Cookie:" name portion.
Note: Does not search HT T P response "Set-Cookie:" headers.
HTTP_RAW_HEADER. T he entire HT T P header, with individual headers separated by linefeed characters (\n) or carriage
return/line-feed strings (\r\n).
HTTP_RAW_RESP_HEADER. T he entire response header, including the name and value parts of the response header
after URL transformation has been done, and the complete response status. As with HT T P_RAW_HEADER, individual
headers are separated by linefeed characters (\n) or carriage return/line-feed strings (\r\n).
HTTP_RAW_SET_COOKIE. T he entire Set-Cookie header after any URL transformations have been performed.
Note: URL transformation can change both the domain and path parts of the Set-Cookie header.
HTTP_RAW_URL. T he entire request URL before any URL transformations are performed, including any query or
fragment parts.
HTTP_RESP_HEADER. T he value part of the complete response headers after any URL transformations have been
performed.
HTTP_RESP_BODY. T he HT T P response body.
HTTP_SET_COOKIE. All "Set-Cookie" headers in the HT T P response headers.
HTTP_STATUS_CODE. T he HT T P status code.
HTTP_STATUS_MESSAGE. T he HT T P status message.
HTTP_URL. T he value portion of the URL in the HT T P headers, excluding any query or fragment ports, after
conversion to the UT F-* character set, URL decoding, stripping of whitespace, and conversion of relative URLs to
absolute. Does not include HT ML entity decoding.
URL
Examines any URLs found in the elements specified by the Area setting. Select one of the following settingss.
Any. Checks all URLs.
Literal. Checks URLs that contain a literal string. After you select Literal, a text box is displayed. T ype the literal string
that you want in the text box.
PCRE. Checks URLs that match a PCRE-format regular expression. After you select this choice, the regular expression
7. In the Pattern area, define the pattern. A pattern is a literal string or PCRE-format regular expression that defines the
pattern that you want to match. T he Pattern area contains the following elements:
Match
A drop-down list of search methods that you can use for the signature. T his list differs depending on whether the
pattern type is Request or Response.
Request Match Types
Injection. Directs the application firewall to look for injected SQL in the specified location. T he Pattern window
disappears, because the application firewall already has the patterns for SQL injection.
CrossSiteScripting. Directs the application firewall to look for cross-site scripts in the specified location. T he Pattern
window disappears, because the application firewall already has the patterns for cross-site scripts.
Expression. An expression in the NetScaler default expressions language. T his is the same expressions language that
is used to create application firewall policies and other policies on the NetScaler appliance. Although the NetScaler
expressions language was originally developed for policy rules, it is a highly flexible general purpose language that can
also be used to define a signature pattern.
When you choose Expression, the NetScaler Expression Editor appears beneath Pattern window. For more
information about the Expression Editor and instructions on how to use it, see "To add a firewall rule (expression) by
using the Add Expression dialog box." For more information about NetScaler expressions, see "Policies and
Expressions."
Credit Card. A built-in pattern to match one of the six supported types of credit card number.
8. Click OK.
9. Repeat the previous four steps to add or modify additional patterns.
10. When finished adding or modifying patterns, click OK to save your changes and return to the Signatures pane.
Caution: Until you click OK in the Add Local Signature Rule or Modif y Local Signature Rule dialog box, your changes
are not saved. Do not close either of these dialog boxes without clicking OK unless you want to discard your changes.
1. New Rules
2. Updated Rules
3. Duplicate Rules
4. Invalid Rules
T he output of the New Rules Only and Updated Rules Only filters also appears in the Category filter pane of the Edit
window in signature editor.
You will need to import the files from GUI to see the corresponding links for New, duplicate, invalid and updated rules.
For example, you can use GUI to import the following signature files:
http://10.217.30.16/testsite/signatures/sig-3100000.xml.
1. In the NetScaler web GUI, go to Configuration > Security > Application Firewall > Signatures. In the Signatures window,
click Add. T hen select File Format > Native, Import From > URL and in the URL field, add the above link. For
example; http://10.217.30.16/testsite/signatures/sig-3100000.xml.
2. After you click Open, the signature file will open and you can see links for New Rule and Invalid Rules.
3. If you import a 3rd party signature rule from the following site, for example;
http://10.217.30.16/FFC/sig_validation/trendmicro_sample2.xml as shown below, you can see 90 new Rules and 9 duplicate
Rules in the imported .xml file.
T he *Default signature is always updated first and then the rest of the user-defined signatures are updated.
T he default route NSIP is used to connect to the Amazon AWS. If there is a specific use case scenario where SNIP is used,
and if there are multiple SNIPs, the first one to receive the ARP response from the hosting site will hold the route.
In case of an upgrade, if the NS has an older base version for the signatures, *Default signature is automatically updated if
a newer signature version is available.
If the schema has changed, the schema version of all the signature objects gets updated when the version is upgraded.
However, for the base version of the user-defined signatures, the behavior is different in release 10.5 versus release 11.0.
In release 10.5, only the default signature was updated and the base version of the rest of the signatures remained
unchanged after the build upgrade.
In release 11.0, this behavior has changed. When the appliance is upgraded to install a new build, not only the *Default
signature object but all the other user-defined signatures that currently exist in the appliance are also updated and will have
the same version after the build upgrade.
In both 10.5 and 11.0 release builds, if auto-update is configured, the *Default Signatures as well as all non-zero version
signatures get auto-updated to the latest released signature version and will have the same base version.
T he application firewall provides twenty security checks, which differ widely in the types of attacks that they target and
how complex they are to configure. T he security checks are organized into the following categories:
Common securit y checks. Checks that apply to any aspect of web security that either does not involve content or is
equally applicable to all types of content.
HT ML securit y checks. Checks that examine HT ML requests and responses. T hese checks apply to HT ML-based web
sites and to the HT ML portions of Web 2.0 sites, which contain mixed HT ML and XML content.
XML securit y checks. Checks that examine XML requests and responses. T hese checks apply to XML-based web
services and to the XML portions of Web 2.0 sites.
T he security checks protect against a wide range of types of attack, including attacks on operation system and web server
software vulnerabilities, SQL database vulnerabilities, errors in the design and coding of web sites and web services, and
failures to secure sites that host or can access sensitive information.
All security checks have a set of configuration options, the check actions, which control how the application firewall
handles a connection that matches a check. T hree check actions are available for all security checks. T hey are:
A fourth check action, Learn , is available for more than half of the check actions. It observes traffic to a protected Web
site or web service and uses connections that repeatedly violate the security check to generate recommended exceptions
(relaxations) to the check, or new rules for the check. In addition to the check actions, certain security checks have
parameters that control the rules that the check uses to determine which connections violate that check, or that configure
the application firewall's response to connections that violate the check. T hese parameters are different for each check,
and they are described in the documentation for each check.
To configure security checks, you can use the application firewall wizard, as described in "T he Application Firewall Wizard," or
you can configure the security checks manually, as described in "Manual Configuration By Using the Configuration Utility."
Some tasks, such as manually entering relaxations or rules or reviewing learned data, can be done only by using the
configuration utility, not the command line. Using the wizard is usually best configuration method, but in some cases manual
configuration might be easier if you are thoroughly familiar with it and simply want to adjust the configuration for a single
security check.
Regardless of which method you use to configure the security checks, each security check requires that certain tasks be
performed. Many checks require that you specify exceptions (relaxations) to prevent blocking of legitimate traffic before
Application Firewall uses packet engines (PE) during processing the transactions. Each packet engine has a limit of 100K
sessions which is sufficient for most deployment scenarios. However, when Application Firewall is processing heavy traffic
and the session timeout is configured at a higher value, the sessions might get accumulated. If the number of alive
Application Firewall sessions exceed the 100K per PE limit, the Application Firewall security check violations might not be
sent to the Security Insight appliance. Lowering the session timeout to a smaller value, or using sessionless mode for the
security checks with sessionless URL closure or sessionless field consistency might help in preventing the sessions getting
accumulated. If this is not a viable option in scenarios where transactions might require longer sessions, upgrading to a
higher-end platform with more packet engine is recommended.
Support for cached AppFirewall is added, and the max session setting through the CLI per core is set to 50K sessions.
HT ML Cross-Sit e Script ing. Examines requests and responses for scripts that attempt to access or modify content
on a different Web site than the one on which the script is located. When this check finds such a script, it either renders
the script harmless before forwarding the request or response to its destination, or it blocks the connection.
HT ML SQL Inject ion. Examines requests that contain form field data for attempts to inject SQL commands into an
SQL database. When this check detects injected SQL code, it either blocks the request or renders the injected SQL code
harmless before forwarding the request to the Web server.
Note: If both of the following conditions apply to your configuration, you should make certain that your Application
Firewall is correctly configured:
If you enable the HT ML Cross-Site Scripting check or the HT ML SQL Injection check (or both), and
Your protected Web sites accept file uploads or contain Web forms that can contain large POST body data.
For more information about configuring the Application Firewall to handle this case, see "Configuring the Application
Firewall."
Buf f er Overf low. Examines requests to detect attempts to cause a buffer overflow on the Web server.
Cookie Consist ency. Examines cookies returned with user requests to verify that they match the cookies your Web
server set for that user. If a modified cookie is found, it is stripped from the request before the request is forwarded to
the Web server.
T he Buffer Overflow check is simple; you can usually enable blocking for it immediately. T he other three top-level checks are
considerably more complex and require configuration before you can safely use them to block traffic. Citrix strongly
recommends that, rather than attempting to configure these checks manually, you enable the learning feature and allow it
to generate the necessary exceptions.
To prevent misuse of the scripts on your protected web sites to breach security on your web sites, the HT ML Cross-Site Scripting check blocks scripts that violate the same origin rule, which states
that scripts should not access or modify content on any server but the server on which they are located. Any script that violates the same origin rule is called a cross-site script, and the practice of
using scripts to access or modify content on another server is called cross-site scripting. T he reason cross-site scripting is a security issue is that a web server that allows cross-site scripting can be
attacked with a script that is not on that web server, but on a different web server, such as one owned and controlled by the attacker.
Unfortunately, many companies have a large installed base of JavaScript-enhanced web content that violates the same origin rule. If you enable the HT ML Cross-Site Scripting check on such a site,
you have to generate the appropriate exceptions so that the check does not block legitimate activity.
T he application firewall offers various action options for implementing HT ML Cross-Site Scripting protection. In addition to the Block , Log , St at s and Learn actions, you also have the option to
T ransf orm cross-sit e script s to render an attack harmless by entity encoding the script tags in the submitted request. You can configure Check complet e URL’s f or cross-sit e script ing
parameter to specify if you want to inspect not just the query parameters but the entire URL to detect XSS attack.
You can deploy relaxations to avoid false positives. T he application firewall learning engine can provide recommendations for configuring relaxation rules.
Following options are available for configuring an optimized HT ML Cross-Site Scripting protection for your application:
Block — If you enable block, the block action is triggered if the XSS tags are detected in the request.
Log — If you enable the log feature, the HT ML Cross-Site Scripting check generates log messages indicating the actions that it takes. If block is disabled, a separate log message is generated for
each header or form field in which the XSS violation was detected. However, only one message is generated when the request is blocked. Similarly, one log message per request is generated for
the transform operation, even when XSS tags are transformed in multiple fields. You can monitor the logs to determine whether responses to legitimate requests are getting blocked. A large
increase in the number of log messages can indicate attempts to launch an attack.
St at s — If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in the stats counter might indicate that your application is under attack. If legitimate
requests are getting blocked, you might have to revisit the configuration to see if you need to configure new relaxation rules or modify the existing ones.
Learn — If you are not sure which relaxation rules might be ideally suited for your application, you can use the learn feature to generate HT ML Cross-Site Scripting rule recommendations based on
the learned data. T he application firewall learning engine monitors the traffic and provides learning recommendations based on the observed values. T o get optimal benefit without compromising
performance, you might want to enable the learn option for a short time to get a representative sample of the rules, and then deploy the rules and disable learning.
T ransf orm cross-sit e script s — If enabled, the application firewall makes the following changes to requests that match the HT ML Cross-Site Scripting check:
Left angle bracket (<) to HT ML character entity equivalent (<)
Right angle bracket (>) to HT ML character entity equivalent (>)
T his ensures that browsers do not interpret unsafe html tags, such as <script>, and thereby execute malicious code. If you enable both request-header checking and transformation, any special
characters found in request headers are also modified as described above. If scripts on your protected web site contain cross-site scripting features, but your web site does not rely upon those
scripts to operate correctly, you can safely disable blocking and enable transformation. T his configuration ensures that no legitimate web traffic is blocked, while stopping any potential cross-
site scripting attacks.
Check complet e URLs f or cross-sit e script ing — If checking of complete URLs is enabled, the application firewall examines entire URLs for HT ML cross-site scripting attacks instead of
checking just the query portions of URLs.
Check Request headers — If Request header checking is enabled, the application firewall examines the headers of requests for HT ML cross-site scripting attacks, instead of just URLs. If you use
the configuration utility, you can enable this parameter in the Settings tab of the application firewall profile.
Important
As part of the streaming changes, the application firewall processing of the Cross-site Scripting tags has changed. T his change is applicable to 11.0 builds onwards. T his change is also pertinent for the enhancement
builds of 10.5.e that support request side streaming. In earlier releases, presence of either open bracket (<), or close bracket (>), or both open and close brackets (<>) was flagged as Cross-site Scripting Violation. T he
behavior has changed in the builds that include support for request side streaming. Only the close bracket character (>) is no longer considered as an attack. Requests are blocked even when an open bracket character
(<) is present, and is considered as an attack. T he Cross-site scripting attack gets flagged.
T he application firewall gives you an option to exempt a specific form field, header, or Cookie from cross-site scripting inspection check. You can completely bypass the inspection for one or more of
these fields by configuring relaxation rules.
T he application firewall allows you to implement tighter security by fine tuning the relaxation rules. An application might require the flexibility to allow specific patterns, but configuring a relaxation
rule to bypass the security inspection might make the application vulnerable to attacks, because the target field is exempted from inspection for any cross-site scripting attack patterns. Cross-site
scripting fine grained relaxation provides the option to allow specific attributes, tags, and patterns. T he rest of the attributes, tags and patterns are blocked. For example, the application firewall
currently has a default set of more than 125 denied patterns. Because hackers can use these patterns in Cross-site script attacks, the application firewall flags them as potential threats. You can
relax one or more pattern(s) that are considered safe for the specific location. T he rest of the potentially dangerous XSS patterns are still checked for the target location and continue to trigger the
security check violations. You now have much tighter control.
T he commands used in relaxations have optional parameters for Value T ype and Value Expression . T he value type can be left blank or you have an option to select T ag or At t ribut e or Pat t ern .
If you leave the value type blank, the configured field of the specified URL is exempted from the Cross-Site Scripting check inspection. If you select a value type, you must provide a value expression.
You can specify whether the value expression is a regular expression or a literal string. When the input is matched against the allowed and denied list, only the specified expressions configured in the
relaxation rules are exempted.
1. XSS Allowed At t ribut es : T here are 52 default allowed attributes, such as, abbr, accesskey , align , alt , axis , bgcolor, border, cellpadding , cellspacing , char, charof f , charset etc.
2. XSS Allowed T ags : T here are 47 default allowed tags, such as, address , basef ont , bgsound , big , blockquot e , bg , br, capt ion , cent er, cit e , dd , del etc.
3. XSS Denied P at t erns : T here are 129 default denied patterns, such as, F SCommand , javascript : , onAbort , onAct ivat e etc.
P oint s t o Consider:
Value expression is an optional argument. A field name might not have any value expression.
A field name can be bound to multiple value expressions.
Value expressions should be assigned a value type. T he XSS value type can be: 1) T ag, 2) Attribute, or 3) Pattern.
You can have multiple relaxation rules per field name/URL combination
T he form field names and the action URL’s are not case sensitive.
To configure HT ML Cross-Sit e Script ing check act ions and ot her paramet ers by using t he command line
If you use the command-line interface, you can enter the following commands to configure the HT ML Cross-Site Scripting Check:
set appf w prof ile <name> -crossSit eScript ingAct ion (([block ] [learn ] [log ] [st at s ]) | [none ])
set appf w prof ile <name> -crossSit eScript ingT ransf ormUnsaf eHT ML (ON | OF F )
set appf w prof ile <name> -crossSit eScript ingCheckComplet eURLs (ON | OF F )
set appf w prof ile <name> -checkRequest Headers (ON | OF F )
To configure a HT ML Cross-Sit e Script ing check relaxat ion rule by using t he command line
bind appf w prof ile <name> -crossSit eScript ing <String> [isRegex (REGEX | NOT REGEX )] <formActionURL> [-locat ion <location>] [-valueT ype (T ag |At t ribut e |P at t ern )
[<valueExpression>] [-isValueRegex (REGEX | NOT REGEX ) ]]
unbind appf w prof ile <name> -crossSit eScript ing <String> <formActionURL> [-locat ion <location>] [-valueT ype (T ag |At t ribut e |P at t ern ) [<valueExpression>]]
In the configuration utility, you can configure the HT ML Cross-Site Scripting check in the pane for the profile associated with your application.
To configure or modif y t he HT ML Cross-Sit e Script ing check by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2 options for configuration:
a. If you just want to enable or disable Block , Log , St at s , and Learn actions for the HT ML Cross-Site Scripting, you can select or clear check boxes in the table, click OK , and then click Save
and Close to close the Security Check pane.
b. If you want to configure additional options for this security check, double click HT ML Cross-Sit e Script ing , or select the row and click Act ion Set t ings , to display the following options:
Check complet e URLs f or Cross-sit e script ing — Instead of checking just the query part of the URL, check the complete URL for cross-site script violations.
After changing any of the above settings, click OK to save the changes and return to the Security Checks table. You can proceed to configure other security checks if needed. Click OK to save
all the changes you have made in the Security Checks section, and then click Save and Close to close the Security Check pane.
To enable or disable the Check request Header setting, in the Advanced Set t ings pane, click P rofile Set t ings . In Common Set t ings , Select or clear the Check Request Headers check box.
Click OK . You can either use the X icon at the top right hand side of the Profile Settings pane to close this section or, if you have finished configuring this profile, you can click Done to return to
the Applicat ion F irewall > P rofile .
To configure a HT ML Cross-Sit e Script ing relaxat ion rule by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Relaxat ion Rules .
3. In the Relaxation Rules table, double-click the HT ML Cross-Sit e Script ing entry, or select it and click Edit .
4. In the HT ML Cross-Sit e Script ing Relaxat ion Rules dialogue box, perform Add , Edit , Delet e , Enable , or Disable operations for relaxation rules.
Note
When you add a new rule, the Va lue Expre s s io n field is not displayed unless you select T a g or Attribute or Pa tte rn option in the Va lue T y pe Field.
For a consolidated view of all the relaxation rules, you can highlight the HT ML Cross-Sit e Script ing row in the Relaxation Rules table, and click Visualizer. T he visualizer for deployed relaxations
offers you the option to Add a new rule or Edit an existing one. You can also Enable or Disable a group of rules by selecting a node and clicking the corresponding buttons in the relaxation
visualizer.
To view or cust omize t he Cross-Sit e Script ing pat t erns by using t he configurat ion ut ilit y
T he default lists are specified in Applicat ion F irewall > Signat ures > Def ault Signat ures . If you do not bind any signature object to your profile, the default XSS allowed and denied list specified
in the Default Signatures object will be used by the profile for the Cross-Site Scripting security check processing. T he Tags, Attributes, and Patterns, specified in the default signatures object, are read-
only. You cannot edit or modify them. If you want to modify or change these, make a copy of the Default Signatures object to create a User-Defined signature object. Make changes in the allowed
or denied lists in the new User-defined signature object and use this signature object in your profile that is processing the traffic for which you want to use these customized allowed and denied lists.
http://docs.citrix.com/en-us/netscaler/11/security/application-firewall/signatures.html.
a. Navigate to Applicat ion firewall > Signat ures , select *Def ault Signat ures , and click Edit . T hen click Manage SQL/XSS Pat t erns .
T he Manage SQL/XSS Pat hs table shows following three rows pertaining to XSS :
xss/allowed/at t ribut e
xss/allowed/t ag
xss/denied/pat t ern
b. Select a row and click Manage Element s to display the corresponding XSS Elements (Tag, Attribute, Pattern) used by the application firewall Cross-Sit e Script ing check.
2. To cust omize XSS Element s : You can edit the User-Defined signature object to customize the allowed Tag, allowed Attributes and denied Patterns. You can add new entries or remove the
existing ones.
a. Navigate to Applicat ion firewall > Signat ures , highlight the target User-defined signature, and click Edit . Click Manage SQL/XSS Pat t erns to display the Manage SQL/XSS
pat hs table.
i. Click Manage Element s , to Add , Edit or Remove the corresponding XSS element.
Warning
You must be very careful before you remove or modify any default XSS element, or delete the XSS path to remove the entire row. T he signature rules as well as the Cross-Site Scripting security check rely on these
elements for detecting attacks to protect your applications. Customizing the XSS Elements can make your application vulnerable to Cross-Site Scripting attacks if the required pattern is removed during editing.
When the learn action is enabled, the application firewall learning engine monitors the traffic and learns the triggered violations. You can periodically inspect these learned rules. After due
consideration, you can deploy the learned rule as a HT ML Cross-Site Scripting relaxation rule.
HT ML Cross-Sit e Script ing Learning enhancement — An application firewall learning enhancement was introduced in release 11.0 of the NetScaler software. To deploy fine grained HT ML Cross-
Site Scripting relaxation, the application firewall offers fine grained HT ML Cross-Site Scripting learning. T he learning engine makes recommendations regarding the observed Value Type (Tag,
Attribute, Pattern) and the corresponding Value expression observed in the input fields. In addition to checking the blocked requests to determine whether the current rule is too restrictive and needs
to be relaxed, you can review the rules generated by the learning engine to determine which value type and value expressions are triggering violations and need to be addressed in relaxation rules.
Note
T he application firewall’s learning engine can distinguish only the first 128 bytes of the name. If a form has multiple fields with names that match for the first 128 bytes, the learning engine might not be able to distinguish
between them. Similarly, the deployed relaxation rule might inadvertently relax all such fields from HT ML Cross-Site Scripting inspection.
Tip
XSS tags which are longer than 12 characters are not learned or logged correctly.
If you need a larger taglength for learning, you can add a large non-appearing tag in the AS _XS S _ALLOWED_T AGS _LIS T for length 'x'.
To view or use learned dat a by using t he command line int erf ace
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Learned Rules . You can select the HT ML Cross-Sit e Script ing entry in the Learned Rules table and double-click it to access the learned rules. T he table
displays the F ield Name , Act ion URL , Value T ype , Value and Hit s columns. You can deploy the learned rules or edit a rule before deploying it as a relaxation rule. T o discard a rule, you can select
it and click the Skip button. You can edit only one rule at a time, but you can select multiple rules to deploy or skip.
You also have the option to show a summarized view of the learned relaxations by selecting the HT ML Cross-Sit e Script ing entry in the Learned Rules table and clicking Visualizer to get a
When the log action is enabled, the HT ML Cross-Site Scripting security check violations are logged in the audit log as AP P F W_XSS violations. T he application firewall supports both Native and CEF
log formats. You can also send the logs to a remote syslog server.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the HT ML Cross-Site Scripting violations:
> Shell
Example of a Cross-Sit e Script ing securit y check violat ion log message in CEF log f ormat
Jul 11 00:45:51 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11.0|APPFW|AP P F W_XSS |6|src=10.217.253.62 geolocation=Unknown spt=4840 method=GET
request=http://aaron.stratum8.net/FFC/CreditCardMind.html?abc\=%3Cdef%3E msg=Cross-sit e script check f ailed f or field abc\= "Bad t ag: def " cn1=133 cn2=294 cs1=pr_ffc cs2=PPE1
cs3=eUljypvLa0BbabwfGVE52Sewg9U0001 cs4=ALERT cs5=2015 act=not blocked
Example of a Cross-Sit e Script ing securit y check violat ion log message in Nat ive log f ormat showing t ransf orm act ion
Jul 11 01:00:28 <local0.info> 10.217.31.98 07/11/2015:01:00:28 GMT ns 0-PPE-0 : default APPFW AP P F W_XSS 132 0 : 10.217.253.62 392-PPE0 eUljypvLa0BbabwfGVE52Sewg9U0001 pr_ffc
http://aaron.stratum8.net/FFC/login.php?login_name=%3CBOB%3E&passwd=&drinking_pref=on
&text_area=&loginButton=ClickToLogin&as_sfid=AAAAAAVFqmYL68IGvkrcn2pzehjfIkm5E6EZ9FL8YLvIW_41AvAATuKYe9N7uGT hSpEAxbb0iBx55jyvqOZNiVK_XwEPstMYvWHxfUWl62WINwRMrKsEDil-
FC4llF Cross-sit e script special charact ers seen in fields <t ransf ormed>
T he Citrix configuration utility includes a useful tool (Syslog Viewer) for analyzing the log messages. You have multiple options for accessing the Syslog Viewer:
Navigate to the Applicat ion F irewall > P rof iles , select the target profile, and click Securit y Checks . Highlight the HT ML Cross-Sit e Script ing row and click Logs . When you access the logs
directly from the HT ML Cross-Site Scripting check of the profile, the configuration utility filters out the log messages and displays only the logs pertaining to these security check violations.
You can also access the Syslog Viewer by navigating to Net Scaler > Syst em > Audit ing . In the Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which
displays all log messages, including other security check violation logs. T his is useful for debugging when multiple security check violations might be triggered during request processing.
Navigate to Applicat ion F irewall > policies > Audit ing . In the Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which displays all log messages, including
other security check violation logs.
T he HT ML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to you. To select log messages for the HT ML Cross-Sit e Script ing
check, filter by selecting AP P F W in the dropdown options for Module . T he Event T ype list offers a rich set of options to further refine your selection. For example, if you select the
AP P F W_XSS check box and click the Apply button, only log messages pertaining to the HT ML Cross-Site Scripting security check violations appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module , Event T ype , Event ID , Client IP etc. appear below the log message. You can select any of
these options to highlight the corresponding information in the log message.
Click t o Deploy functionality is available only in the configuration utility. You can use the Syslog Viewer to not only view the logs but also to deploy HT ML Cross-Site Scripting relaxation rules based
on the log messages for the application firewall security check violations. T he log messages must be in CEF log format for this operation. Click to deploy functionality is available only for log messages
that are generated by the block (or not block) action. You cannot deploy a relaxation rule for a log message about the transform operation.
To deploy a relaxation rule from the Syslog Viewer, select the log message. A check box appears in the upper right corner of the Syslog Viewer box of the selected row. Select the check box, and then
select an option from the Act ion list to deploy the relaxation rule. Edit & Deploy , Deploy , and Deploy All are available as Act ion options.
T he HT ML Cross-Site Scripting rules that are deployed by using the Click t o Deploy option do not include the fine grain relaxation recommendations.
When the stats action is enabled, the counter for the HT ML Cross-Site Scripting check is incremented when the application firewall takes any action for this security check. T he statistics are
collected for Rate and Total count for Traffic, Violations, and Logs. T he size of an increment of the log counter can vary depending on the configured settings. For example, if the block action is
enabled, the request for a page that contains 3 HT ML Cross-Site Scripting violations increments the stats counter by one, because the page is blocked as soon as the first violation is detected.
However, if block is disabled, processing the same request increments the statistics counter for violations and the logs by three, because each violation generates a separate log message.
To display HT ML Cross-Sit e Script ing check st at ist ics by using t he command line
> sh appf w st at s
To display HT ML Cross-Sit e Script ing st at ist ics by using t he configurat ion ut ilit y
Built -in Support f or HT ML Cross-Sit e Script ing at t ack P rot ect ion — T he NetScaler application firewall protects against Cross-Site Scripting attacks by monitoring a combination of allowed
attributes and tags, as well as denied patterns in the received payload. All the built-in default allowed tags, allowed attributes and denied patterns used by the XSS check are specified in the
/netscaler/default_custom_settings.xml file.
Cust omizat io n— You can change the default list of tags, attributes, and patterns to customize the Cross-Site Scripting security check inspection for the specific needs of your application. Make
a copy of the default signature object, modify existing entries, or add new ones. Bind this signature object to your profile to make use of the customized configuration.
Hybrid Securit y Model— Both signatures and deep security protections use the SQL/XSS patterns specified in the signature object that is bound to the profile. If no signature object is bound to
the profile, the SQL/XSS patterns present in the default signature object are used.
T ransf orm— Note the following about the transform operation:
T he transform operation works independently of the other Cross-Site Scripting action settings. If transform is enabled and block, log, stats, and learn are all disabled, XSS tags will be
transformed.
If the block action is enabled, it takes precedence over the transform action.
F ine Grained Relaxat ion and Learning — Fine tune the relaxation rule to relax a subset of XSS elements from security check inspection but detect the rest. T he learning engine recommends a
specific value type and value expressions based on the observed data.
Click t o Deplo y— Select one, or multiple XSS violation log messages in the syslog viewer and deploy them as relaxation rules.
Charset — T he default charset for the profile should be set based on the need of the application. By default, the profile charset is set to English US (ISO-8859-1). If a request is received without
the specified charset, the application firewall processes the request as if it is ISO-8859-1. T he open bracket character (<) or the close bracket character (>) will not get interpreted as XSS tags if
these characters are encoded in other charsets. For example, if a request contains a UT F-8 character string “% uf f 1cscript % uf f 1e ” but the charset is not specified on the request page, the XSS
violation might not get triggered unless the default charset for the profile is specified as Unicode.
Warning
HT MLInjection is now deprecated and as an alternative, Citrix recommends you to use AppFlow with Client Side Measurements. For more information, see AppFlow topic.
Many web applications have web forms that use SQL to communicate with relational database servers. Malicious code or a hacker can use an insecure web form
to send SQL commands to the web server. T he application firewall HT ML SQL Injection check provides special defenses against injection of unauthorized SQL
code that might break security. If the application firewall detects unauthorized SQL code in a user request, it either transforms the request, to render the SQL
code inactive, or blocks the request. T he application firewall examines the request payload for injected SQL code in three locations: 1) POST body, 2) headers, and
3) cookies.
A default set of keywords and special characters provides known keywords and special characters that are commonly used to launch SQL attacks. You can add
new patterns, and you can edit the default set to customize the SQL check inspection. T he application firewall offers various action options for implementing
SQL Injection protection. In addition to the Block , Log , St at s and Learn actions, the application firewall profile also offers the option to t ransf orm SQL
special charact ers to render an attack harmless.
In addition to actions, there are several parameters that can be configured for SQL injection processing. You can check for SQL wildcard charact ers . You can
change the SQL Injection type and select one of the 4 options (SQLKeyword , SQLSplChar, SQLSplCharANDKeyword , SQLSplCharORKeyword ) to indicate
how to evaluate the SQL keywords and SQL special characters when processing the payload. T he SQL Comment s Handling paramet er gives you an option to
specify the type of comments that need to be inspected or exempted during SQL Injection detection.
You can deploy relaxations to avoid false positives. T he application firewall learning engine can provide recommendations for configuring relaxation rules.
Following options are available for configuring an optimized SQL Injection protection for your application:
Block — If you enable block, the block action is triggered only if the input matches the SQL injection type specification. For example, if
SQLSplCharANDKeyword is configured as the SQL injection type, a request is not blocked if it contains no key words, even if SQL special characters are
detected in the input. Such a request is blocked if the SQL injection type is set to either SQLSplChar, or SQLSplCharORKeyword .
Log — If you enable the log feature, the SQL Injection check generates log messages indicating the actions that it takes. If block is disabled, a separate log
message is generated for each input field in which the SQL violation was detected. However, only one message is generated when the request is blocked. Similarly,
one log message per request is generated for the transform operation, even when SQL special characters are transformed in multiple fields. You can monitor the
logs to determine whether responses to legitimate requests are getting blocked. A large increase in the number of log messages can indicate attempts to launch
an attack.
St at s — If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in the stats counter might indicate that your application is
under attack. If legitimate requests are getting blocked, you might have to revisit the configuration to see if you need to configure new relaxation rules or modify
the existing ones.
Learn — If you are not sure which SQL relaxation rules might be ideally suited for your application, you can use the learn feature to generate recommendations
based on the learned data. T he application firewall learning engine monitors the traffic and provides SQL learning recommendations based on the observed values.
To get optimal benefit without compromising performance, you might want to enable the learn option for a short time to get a representative sample of the
rules, and then deploy the rules and disable learning.
T ransf orm SQL special charact ers — T he application firewall considers three characters, Single straight quote ('), Backslash (\), and Semicolon (;) as special
characters for SQL security check processing. T he SQL Transformation feature modifies the SQL Injection code in an HT ML request to ensure that the request is
rendered harmless. T he modified HT ML request is then sent to the server. All default transformation rules are specified in the
/netscaler/default_custom_settings.xml file.
T he transform operation renders the SQL code inactive by making the following changes to the request:
T hese three characters (special strings) are necessary to issue commands to an SQL server. Unless an SQL command is prefaced with a special string, most SQL
servers ignore that command. T herefore, the changes that the application firewall performs when transformation is enabled prevent an attacker from injecting
active SQL. After these changes are made, the request can safely be forwarded to your protected web site. When web forms on your protected web site can
legitimately contain SQL special strings, but the web forms do not rely on the special strings to operate correctly, you can disable blocking and enable
transformation to prevent blocking of legitimate web form data without reducing the protection that the application firewall provides to your protected web
T he transform operation works independently of the SQL Injection Type setting. If transform is enabled and the SQL Injection type is specified as SQL keyword,
SQL special characters are transformed even if the request does not contain any keywords.
Tip
You normally enable either transformation or blocking, but not both. If the block action is enabled, it takes precedence over the transform action. If you have blocking enabled,
enabling transformation is redundant.
Check f or SQL Wildcard Charact ers — Wild card characters can be used to broaden the selections of a structured query language (SQL-SELECT ) statement.
T hese wild card operators can be used in conjunction with LIKE and NOT LIKE operators to compare a value to similar values. T he percent (%), and underscore (_)
characters are frequently used as wild cards. T he percent sign is analogous to the asterisk (*) wildcard character used with MS-DOS and to match zero, one, or
multiple characters in a field. T he underscore is similar to the MS-DOS question mark (?) wildcard character. It matches a single number or character in an
expression.
For example, you can use the following query to do a string search to find all customers whose names contain the D character.
T he following example combines the operators to find any salary values that have 0 in the second and third place.
Different DBMS vendors have extended the wildcard characters by adding extra operators. T he NetScaler application firewall can protect against attacks that
are launched by injecting these wildcard characters. T he 5 default Wildcard characters are percent (%), underscore (_), caret (^), opening square bracket ([), and
closing square bracket (]). T his protection applies to both HT ML and XML profiles.
T he default wildcard chars are a list of literals specified in the *Def ault Signat ures :
Wildcard characters in an attack can be PCRE, like [^A-F]. T he application firewall also supports PCRE wildcards, but the literal wildcard chars above are sufficient
to block most attacks.
Note
T he SQL wildcard character check is different from the SQL special character check. T his option must be used with caution to avoid false positives.
Check Request Cont aining SQL Inject ion T ype — T he application firewall provides 4 options to implement the desired level of strictness for SQL Injection
inspection, based on the individual need of the application. T he request is checked against the injection type specification for detecting SQL violations. T he 4 SQL
injection type options are:
SQL Special Charact er and Keyword — Both an SQL keyword and an SQL special character must be present in the input to trigger SQL violation. T his least
restrictive setting is also the default setting.
SQL Special Charact er— At least one of the special characters must be present in the input to trigger SQL violation.
SQL key word — At least one of the specified SQL keywords must be present in the input to trigger an SQL violation. Do not select this option without due
consideration. T o avoid false positives, make sure that none of the keywords are expected in the inputs.
SQL Special Charact er or Keyword — Either the key word or the special character string must be present in the input to trigger the security check violation.
Tip
If you configure the application firewall to check for inputs that contain an SQL special character, the application firewall skips web form fields that do not contain any special
characters. Since most SQL servers do not process SQL commands that are not preceded by a special character, enabling this option can significantly reduce the load on the
application firewall and speed up processing without placing your protected web sites at risk.
SQL comment s handling — By default, the application firewall checks all SQL comments for injected SQL commands. Many SQL servers ignore anything in a
ANSI — Skip ANSI-format SQL comments, which are normally used by UNIX-based SQL databases. For example:
-- (T wo Hypens) - T his is a comment that begins with two hyphens and ends with end of line.
{} - Braces (Braces enclose the comment. T he { precedes the comment, and the } follows it. Braces can delimit single- or multiple-line comments, but
comments cannot be nested)
/* */ : C style comments (Does not allow nested comments). Please note /*! <comment that begin with slash followed by asterisk and exclamation mark is
not a comment > */
MySQL Server supports some variants of C-style comments. T hese enable you to write code that includes MySQL extensions, but is still portable, by using
comments of the following form: /*! MySQL-specific code */
. # : Mysql comments : T his is a comment that begins with # character and ends with end of the line
Nest ed — Skip nested SQL comments, which are normally used by Microsoft SQL Server. For example; -- (T wo Hypens), and /* */ (Allows nested comments)
A NS I/Ne s te d —Skip comments that adhere to both the ANSI and nested SQL comment standards. Comments that match only the ANSI standard, or only the nested standard, are still checked for injected
SQL.
Check all Comment s — Check the entire request for injected SQL without skipping anything. T his is the default setting.
Tip
In most cases, you should not choose the Nested or the ANSI/Nested option unless your back-end database runs on Microsoft SQL Server. Most other types of SQL server
software do not recognize nested comments. If nested comments appear in a request directed to another type of SQL server, they might indicate an attempt to breach security
on that server.
Check Request headers — Enable this option if, in addition to examining the input in the form fields, you want to examine the request headers for HT ML SQL
Injection attacks. If you use the configuration utility, you can enable this parameter in the Advanced Set t ings -> P rofile Set t ings pane of the application
firewall profile.
Note
If you enable the Check Request header flag, you might have to configure relaxation rule for the Us e r-Age nt header. Presence of the SQL keyword like and SQL special
character semi-colon (; ) might trigger false positive and block requests that contain this header.
Warning
If you enable both request header checking and transformation, any SQL special characters found in headers are also transformed. T he Accept, Accept-Charset, Accept-
Encoding, Accept-Language, Expect, and User-Agent headers normally contain semicolons (;). Enabling both Request header checking and transformation simultaneously might
cause errors.
T he application firewall gives you an option to exempt a specific form field, header, or Cookie from SQL Injection inspection check. You can completely bypass the
inspection for one or more of these fields by configuring relaxation rules for the SQL Injection check.
T he application firewall allows you to implement tighter security by fine tuning the relaxation rules. An application might require the flexibility to allow specific
patterns, but configuring a relaxation rule to bypass the security inspection might make the application vulnerable to attacks, because the target field is exempted
from inspection for any SQL attack patterns. SQL fine grained relaxation provides the option to allow specific patterns and block the rest. For example, the
application firewall currently has a default set of more than 100 SQL keywords. Because hackers can use these keywords in SQL Injection attacks, the application
firewall flags them as potential threats. You can relax one or more keyword(s) that are considered safe for the specific location. T he rest of the potentially
dangerous SQL keywords are still checked for the target location and continue to trigger the security check violations. You now have much tighter control.
T he commands used in relaxations have optional parameters for Value T ype and Value Expression . You can specify whether the value expression is a regular
expression or a literal string. T he value type can be left blank or you have an option to select Keyword or SpecialSt ring or WildChar.
Warning
Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular expressions, double-check any regular expressions you write. Make
P oint s t o Consider:
Value expression is an optional argument. A field name might not have any value expression.
A field name can be bound to multiple value expressions.
Value expressions should be assigned a value type. T he SQL value type can be: 1) Keyword, 2) SpecialString, or 3) WildChar.
You can have multiple relaxation rules per field name/URL combination.
To configure SQL Inject ion act ions and ot her paramet ers by using t he command line
In the command line interface, you can use either the set appf w profile command or the add appf w profile command to configure the SQL Injection
protections. You can enable the block, learn, log, stats action(s) and specify whether you want to transform the special characters used in SQL Injection attack
strings to disable the attack. Select the type of SQL attack pattern (key words, wildcard characters, special strings) you want to detect in the payloads, and
indicate whether you want the application firewall to also inspect the request Headers for SQL Injection violations. Use the unset appf w profile command to
revert the configured settings back to their defaults. Each of the following commands sets only one parameter, but you can include multiple parameters in a single
command:
set appf w prof ile <name> -SQLInject ionAct ion (([block ] [learn ] [log ] [st at s ]) | [none ])
set appf w prof ile <name> -SQLInject ionT ransf ormSpecialChars (ON | OF F )
set appf w prof ile <name> -SQLInject ionCheckSQLWildChars (ON |OF F )
set appf w prof ile <name> -SQLInject ionT ype ([SQLKeyword ] | [SQLSplChar] | [SQLSplCharANDKeyword ] | [SQLSplCharORKeyword ])
set appf w prof ile <name> -SQLInject ionP arseComment s ([checkall] | [ansi|nest ed ] | [ansinest ed ])
set appf w prof ile <name> -CheckRequest Headers (ON | OF F )
To configure a SQL Inject ion relaxat ion rule by using t he command line
bind appf w profile <name> -SQLInject ion <String> [isRegex (REGEX | NOT REGEX )] <formActionURL> [-locat ion <location>] [-valueT ype
(Keyword |SpecialSt ring |Wildchar) [<valueExpression>][-isValueRegex (REGEX | NOT REGEX ) ]]
unbind appf w profile <name> -SQLInject ion <String> <formActionURL> [-locat ion <location>] [-valueT ype (Keyword |SpecialSt ring |Wildchar)
[<valueExpression>]]
Note
You can find the list of SQL keywords from default signature file contents by viewing the view signature object, which has list of sql key words and sql special characters.
In the configuration utility, you can configure the SQL Injection security check in the pane for the profile associated with your application.
To configure or modif y t he SQL Inject ion check by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2 options for configuration:
a. If you just want to enable or disable Block, Log, Stats, and Learn actions for HT ML SQL Injection, you can select or clear check boxes in the table,
click OK, and then click Save and Close to close the Security Check pane.
b. If you want to configure additional options for this security check, double click HT ML SQL Injection, or select the row and click Action Settings, to
display the following options:
T ransf orm SQL Special charact er— Transform any SQL Special characters in the request.
Check f or SQL Wildcard Charact ers — Consider SQL Wildcard characters in the payload to be attack patterns.
Check Request Cont aining — Type of SQL injection (SQLKeyword, SQLSplChar, SQLSplCharANDKeyword, or SQLSplCharORKeyword) to check.
After changing any of the above settings, click OK to save the changes and return to the Security Checks table. You can proceed to configure other
security checks if needed. Click OK to save all the changes you have made in the Security Checks section, and then click Save and Close to close the
Security Check pane.
3. To enable or disable the Check request Header setting, in the Advanced Settings pane, click P rofile Set t ings . In Common Set t ings , Select or clear the
Check Request Headers check box. Click OK. You can either use the X icon at the top right hand side of the Profile Settings pane to close this section or,
if you have finished configuring this profile, you can click Done to return to the Applicat ion F irewall > P rofile .
To configure an SQL Inject ion relaxat ion rule by using t he configurat ion ut ilit y
Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
In the Advanced Set t ings pane, click Relaxat ion Rules .
In the Relaxation Rules table, double-click the HT ML SQL Inject ion entry, or select it and click Edit .
In the HT ML SQL Inject ion Relaxat ion Rules dialogue box, perform Add , Edit , Delet e , Enable , or Disable operations for relaxation rules.
Note
When you add a new rule, the Va lue Expre s s io n field is not displayed unless you select Ke y wo rd or S pe cia lS tring or WildCha r option in the Va lue T y pe Field.
For a consolidated view of all the relaxation rules, you can highlight the HT ML SQL Inject ion row and click Visualizer. T he visualizer for deployed relaxations
offers you the option to Add a new rule or Edit an existing one. You can also Enable or Disable a group of rules by selecting a node and clicking the
corresponding buttons in the relaxation visualizer.
To view or cust omize t he SQL Inject ion pat t erns by using t he configurat ion ut ilit y
You can use the configuration utility to view or customize the SQL patterns.
T he default SQL patterns are specified in Application Firewall > Signatures > Default Signatures. If you do not bind any signature object to your profile, the
default SQL patterns specified in the Default Signatures object will be used by the profile for the SQL Injection security check processing. T he rules and patterns,
specified in the default signatures object, are read-only. You cannot edit or modify them. If you want to modify or change these patterns, make a copy of the
Default Signatures object to create a User-Defined signature object. Make changes in the SQL patterns in the new User-defined signature object and use this
signature object in your profile that is processing the traffic for which you want to use these customized SQL patterns.
a. Navigate to Applicat ion firewall > Signat ures , select *Def ault Signat ures , and click Edit .
T he Manage SQL/XSS pat hs table shows following four rows pertaining to SQL Injection:
b. Select a row and click Manage Element s to display the corresponding SQL patterns (keywords, special strings, transformation rules or the wildcard
characters) used by the application firewall SQL injection check.
2. To cust omize SQL pat t erns: You can edit the User-Defined signature object to customize the SQL key words, special strings, and wildcard characters. You
can add new entries or remove the existing ones. You can modify the transformation rules for the SQL special strings.
a. Navigat e t o Applicat ion firewall > Signat ures , highlight the target User-defined signature, and click Edit . Click Manage SQL/XSS pat t erns to
display the Manage SQL/XSS pat hs table.
i. Click Manage Element s , to Add , Edit or Remove the corresponding SQL element.
Warning
You must be very careful before you remove or modify any default SQL element, or delete the SQL path to remove the entire row. T he signature rules as well as the SQL Inject
security check rely on these elements for detecting SQL Injection attacks to protect your applications. Customizing the SQL patterns can make your application vulnerable to SQL
attacks if the required pattern is removed during editing.
When the learn action is enabled, the application firewall learning engine monitors the traffic and learns the triggered violations. You can periodically inspect these
learned rules. After due consideration, you can deploy the learned rule as an SQL Injection relaxation rule.
SQL Inject ion Learning enhancement — An application firewall learning enhancement was introduced in release 11.0 of the NetScaler software. To deploy fine
grained SQL Injection relaxation, the application firewall offers fine grained SQL Injection learning. T he learning engine makes recommendations regarding the
observed Value Type (keyword, SpecialString, Wildchar) and the corresponding Value expression observed in the input fields. In addition to checking the blocked
requests to determine whether the current rule is too restrictive and needs to be relaxed, you can review the rules generated by the learning engine to determine
which value type and value expressions are triggering violations and need to be addressed in relaxation rules.
Important
T he application firewall’s learning engine can distinguish only the first 128 bytes of the name. If a form has multiple fields with names that match for the first 128 bytes, the
learning engine might not be able to distinguish between them. Similarly, the deployed relaxation rule might inadvertently relax all such fields from SQL Injection inspection.
Note
To bypass SQL check in User-Agent header, use the following relaxation rule:
bind appfw profile your_profile_name -SQLInjection User-Agent " .*" -location HEADER
To view or use learned dat a by using t he command line int erf ace
1. Navigate to Applicat ion F irewall > P rofiles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Learned Rules . You can select the HT ML SQL Inject ion entry in the Learned Rules table and double-click it to
access the learned rules. You can deploy the learned rules or edit a rule before deploying it as a relaxation rule. To discard a rule, you can select it and click the Skip
button. You can edit only one rule at a time, but you can select multiple rules to deploy or skip.
You also have the option to show a summarized view of the learned relaxations by selecting the HT ML SQL Inject ion entry in the Learned Rules table and
clicking Visualizer to get a consolidated view of all the learned violations. T he visualizer makes it very easy to manage the learned rules. It presents a
comprehensive view of the data on one screen and facilitates taking action on a group of rules with one click. T he biggest advantage of the visualizer is that it
recommends regular expressions to consolidate multiple rules. You can select a subset of these rules, based on the delimiter and Action URL. You can display 25, 50,
or 75 rules in the visualizer, by selecting the number from a drop-down list. T he visualizer for learned rules offers the option to edit the rules and deploy them as
relaxations. Or you can skip the rules to ignore them.
When the log action is enabled, the HT ML SQL Injection security check violations are logged in the audit log as AP P F W_SQL violations. T he application firewall
supports both Native and CEF log formats. You can also send the logs to a remote syslog server.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the SQL Injection violations:
Example of a HT ML SQL Inject ion log message when t he request is t ransf ormed
Example of a HT ML SQL Inject ion log message when t he post request is blocked
Note
As part of the streaming changes in 10.5.e build (enhancement builds) as well as 11.0 build onwards, we now process the input data in blocks. RegEx pattern matching is now
restricted to 4K for contiguous character string matching. With this change, the SQL violation log messages might include different information compared to the earlier builds.
T he keyword and special character in the input could be separated by a large number of bytes. We now keep track of the SQL keywords and special strings when processing the
data, instead of buffering the entire input value. In addition to the field name, the log message now includes the SQL keyword, or the SQL special character, or both the SQL
keyword and the SQL special character, as determined by the configured setting. T he rest of the input is no longer included in the log message, as shown in the following
example:
Exa m ple :
In 10.5, when the application firewall detects the SQL violation, the entire input string might be included in the log message, as shown below:
SQL Keyword check failed for field te xt=\"s e le ct a na m e fro m te s tbe d1\;\\(\;\\)\".*\<blo cke d\>
In enhancement builds of 10.5.e that support request side streaming as well as 11.0 build onwards, we log only the field name, keyword and special character (if applicable) in
the log message, as shown below:
SQL Keyword check failed for field te xt="s e le ct(;)" <blo cke d>
T his change is applicable to requests that contain a pplica tio n/x-www-fo rm -urle nco de d , or m ultipa rt/fo rm -da ta , or te xt/x-gwt-rpc content-types. Log messages
generated during processing of JS ON or XML payloads are not affected by this change.
T he Citrix configuration utility includes a useful tool (Syslog Viewer) for analyzing the log messages. You have multiple options for accessing the Syslog Viewer:
Navigate to the Applicat ion F irewall > P rof iles , select the target profile, and click Securit y Checks . Highlight the HT ML SQL Inject ion row and click
Logs . When you access the logs directly from the HT ML SQL Injection check of the profile, the configuration utility filters out the log messages and displays
only the logs pertaining to these security check violations.
You can also access the Syslog Viewer by navigating to Net Scaler > Syst em > Audit ing . In the Audit Messages section, click the Syslog messages link to
display the Syslog Viewer, which displays all log messages, including other security check violation logs. T his is useful for debugging when multiple security check
violations might be triggered during request processing.
Navigate to Applicat ion F irewall > policies > Audit ing . In the Audit Messages section, click the Syslog messages link to display the Syslog Viewer, which
displays all log messages, including other security check violation logs.
T he HT ML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to you. To select log messages for the
HT ML SQL Inject ion check, filter by selecting AP P F W in the dropdown options for Module . T he Event T ype list offers a rich set of options to further refine
your selection. For example, if you select the AP P F W_SQL check box and click the Apply button, only log messages pertaining to the SQL Inject ion security
check violations appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module , Event T ype , Event ID , Client IP etc. appear below the log
message. You can select any of these options to highlight the corresponding information in the log message.
Click t o Deploy functionality is available only in the configuration utility. You can use the Syslog Viewer to not only view the logs but also to deploy HT ML SQL
Injection relaxation rules based on the log messages for the application firewall security check violations. T he log messages must be in CEF log format for this
operation. Click to deploy functionality is available only for log messages that are generated by the block (or not block) action. You cannot deploy a relaxation rule
To deploy a relaxation rule from the Syslog Viewer, select the log message. A check box appears in the upper right corner of the Syslog Viewer box of the selected
row. Select the check box, and then select an option from the Action list to deploy the relaxation rule. Edit & Deploy , Deploy , and Deploy All are available as
Act ion options.
T he SQL Injection rules that are deployed by using the Click to Deploy option do not include the fine grain relaxation recommendations.
When the stats action is enabled, the counter for the SQL Injection check is incremented when the application firewall takes any action for this security check.
T he statistics are collected for Rate and Total count for Traffic, Violations, and Logs. T he size of an increment of the log counter can vary depending on the
configured settings. For example, if the block action is enabled, the request for a page that contains 3 SQL Injection violations increments the stats counter by
one, because the page is blocked as soon as the first violation is detected. However, if block is disabled, processing the same request increments the statistics
counter for violations and the logs by three, because each violation generates a separate log message.
To display SQL Inject ion check st at ist ics by using t he command line
> sh appf w st at s
To display HT ML SQL Inject ion st at ist ics by using t he configurat ion ut ilit y
Built -in Support f or SQL Inject ion P rot ect ion — T he NetScaler application firewall protects against SQL Injection by monitoring a combination of SQL
keywords and special characters in the form parameters. All SQL keywords, special characters, wildcard characters, and default transformation rules are
specified in the /netscaler/default_custom_settings.xml file.
Cust omizat ion — You can change the default key words, special characters, wildcard characters and transformation rules to customize the SQL security check
inspection for the specific needs of your application. Make a copy of the default signature object, modify existing entries, or add new ones. Bind this signature
object to your profile to make use of the customized configuration.
Hybrid Securit y Model— Both signatures and deep security protections use the SQL/XSS patterns specified in the signature object that is bound to the
profile. If no signature object is bound to the profile, the SQL/XSS patterns present in the default signature object are used.
T ransf orm— Note the following about the transform operation:
T he transform operation works independently of the other SQL Injection action settings. If transform is enabled and block, log, stats, and learn are all
disabled, SQL special characters will be transformed.
When SQL T ransformation is enabled, user requests are sent to the backend servers after the SQL special characters are transformed in non-block mode. If
the block action is enabled, it takes precedence over the transform action. If the injection type is specified as SQL special character and block is enabled, the
request is blocked despite the transform action.
F ine Grained Relaxat ion and Learning — Fine tune the relaxation rule to relax a subset of SQL elements from security check inspection but detect the rest.
T he learning engine recommends a specific value type and value expressions based on the observed data.
Click t o Deploy — Select one, or multiple SQL violation log messages in the syslog viewer and deploy them as relaxation rules.
T he Buffer Overflow check prevents attacks against insecure operating-system or web-server software that can crash or
behave unpredictably when it receives a data string that is larger than it can handle. Proper programming techniques
prevent buffer overflows by checking incoming data and either rejecting or truncating overlong strings. Many programs,
however, do not check all incoming data and are therefore vulnerable to buffer overflows. T his issue especially affects older
versions of web-server software and operating systems, many of which are still in use.
T he Buffer Overflow security check allows you to configure the Block , Log , and St at s actions. In addition, you can also
configure the following parameters:
Maximum URL Lengt h. T he maximum length the application firewall allows in a requested URL. Requests with longer
URLs are blocked. P ossible Values : 0-65535. Def ault : 1024
Maximum Cookie Lengt h. T he maximum length the application firewall allows for all cookies in a request. Requests
with longer cookies trigger the violations. P ossible Values : 0-65535. Def ault : 4096
Maximum Header Lengt h. T he maximum length the application firewall allows for HT T P headers. Requests with
longer headers are blocked. P ossible Values : 0-65535. Def ault : 4096
To configure Buf f er Overflow securit y check act ions and ot her paramet ers by using t he command line
If you use the command-line interface, you can add the following Buffer Overflow Check arguments to the set appfw
profile <profileName> command:
In the configuration utility, you can configure the Buffer Overflow security check in the pane for the profile associated with
your application.
To configure or modif y t he Buf f er Overflow securit y check by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2
options for configuration:
a. If you just want to enable or disable Block , Log , and St at s actions for Buf f er Overflow , you can select or
clear check boxes in the table, click OK , and then click Save and Close to close the Security Check pane.
After changing any of the above settings, click OK to save the changes and return to the Security Checks table.
You can proceed to configure other security checks if needed. Click OK to save all the changes you have made in
the Security Checks section, and then click Save and Close to close the Security Check pane.
When the log action is enabled, the Buffer Overflow security check violations are logged in the audit log as
AP P F W_BUF F EROVERF LOW_URL , AP P F W_BUF F EROVERF LOW_COOKIE , and
AP P F W_BUF F EROVERF LOW_HDR violations. T he application firewall supports both Native and CEF log formats. You
can also send the logs to a remote syslog server.
If you use the configuration utility to review the logs, you can use the click-to-deploy feature to apply relaxations indicated
by the logs.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the Buffer overflow
violations:
> Shell
Example of a CEF log message showing buf f erOverflowMaxCookieLengt h violat ion in non-block mode
Example of a CEF log message showing buf f erOverflowMaxURLLengt h violat ion in non-block mode
Example of a Nat ive F ormat Log message showing buf f erOverflowMaxHeaderLengt h violat ion in block mode
T he Citrix configuration utility includes a useful tool (Syslog Viewer) for analyzing the log messages. You have multiple
options for accessing the Syslog Viewer:
Navigate to the Applicat ion F irewall > P rof iles , select the target profile, and click Securit y Checks . Highlight the
Buf f er Overf low row and click Logs . When you access the logs directly from the Buffer Overflow Security Check of
the profile, the configuration utility filters out the log messages and displays only the logs pertaining to these security
check violations.
You can also access the Syslog Viewer by navigating to Net Scaler > Syst em > Audit ing . In the Audit Messages
section, click the Syslog messages link to display the Syslog Viewer, which displays all log messages, including other
security check violation logs. T his is useful for debugging when multiple security check violations might be triggered
during request processing.
Navigate to Applicat ion F irewall > policies > Audit ing . In the Audit Messages section, click the Syslog messages
link to display the Syslog Viewer, which displays all log messages, including other security check violation logs.
T he XML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to you.
To select log messages for the Buf f er Overflow check, filter by selecting AP P F W in the dropdown options for Module .
T he Event T ype list offers three options, AP P F W_BUF F EROVERF LOW_URL ,
AP P F W_BUF F EROVERF LOW_COOKIE , and AP P F W_BUF F EROVERF LOW_HDR , to view all the log messages
pertaining to buffer overflow security check. You can select one or more options to further refine your selection. For
example, if you select the AP P F W_BUF F EROVERF LOW_COOKIE check box and click the Apply button, only log
messages pertaining to the Buffer Overflow security check violations for the Cookie header appear in the Syslog Viewer. If
you place the cursor in the row for a specific log message, multiple options, such as Module , Event T ype , Event ID , and
Client IP , appear below the log message. You can select any of these options to highlight the corresponding information in
the log message.
Click-t o-Deploy : T he configuration utility provides click-to-deploy functionality, which is currently supported only for the
buffer overflow log messages pertaining to the URL Lengt h violations. You can use the Syslog Viewer to not only view the
triggered violations, but also execute informed decisions based on the observed lengths of the blocked messages. If the
current value is too restrictive and is triggering false positives, you can select a message and deploy it to replace the current
value with the URL length value seen in the message. T he log messages must be in CEF log format for this operation. If the
relaxation can be deployed for a log message, a check box appears at the right edge of the Syslog Viewer box in the row.
Select the check box, and then select an option from the Act ion list to deploy the relaxation. Edit & Deploy , Deploy , and
Deploy All are available as Act ion options. You can use the AP P F W_BUF F EROVERF LOW_URL filter to isolate all the
log messages pertaining to the configured URL length violations.
If you select an individual log message, all three action options Edit & Deploy , Deploy , and Deploy All are available. If you
select Edit & Deploy , the Buf f er Overflow set t ings dialogue is displayed. T he new URL length that was observed in the
request is inserted into the Maximum URL length input field. If you click Close without any edits, the current configured
values remain unchanged. If you click the OK button, the new value of the Maximum URL length replaces the previous
value.
If you select the check boxes for multiple log messages, you can use the Deploy or Deploy All option. If the deployed log
messages have different URL lengths, the configured value gets replaced by the highest URL Length value observed in the
selected messages. Deploying the rule results only in changing the buf f erOverflowMaxURLLengt h value. Configured
actions are retained and remain unchanged.
When the stats action is enabled, the counter for the Buffer Overflow Security Check is incremented when the application
firewall takes any action for this security check. T he statistics are collected for Rate and Total count for Traffic, Violations,
and Logs. T he size of an increment of the log counter can vary depending on the configured settings. For example, if the
block action is enabled, a request for a page that contains three Buffer Overflow violations increments the stats counter
by one, because the page is blocked as soon as the first violation is detected. However, if block is disabled, processing the
same request increments the statistics counter for violations and the logs by three, because each violation generates a
separate log message.
To display Buf f er Overflow Securit y Check st at ist ics by using t he command line
> sh appf w st at s
Block , Log and St at s actions enable you to monitor the traffic and configure optimal protection for your application.
Syslog viewer enables you to filter and view all the log messages pertaining to buffer overflow violations.
Click-t o-Deploy functionality is supported for the buf f erOverf lowMaxURLLengt h violations. You can select and
deploy an individual rule, or you can select multiple log messages to tweak and relax the current configured value of the
maximum allowed length of the URL. T he highest value of the URL from the selected group is set as the new value, to
allow all these requests that are currently flagged as violations.
T he application firewall now evaluates individual cookies when inspecting the incoming request. If length of any one
cookie received in the Cookie header exceeds the configured Buf f erOverf lowMaxCookieLengt h , the Buffer
Overflow violation is triggered.
Important
In release 10.5.e (in a few interim enhancement builds prior to 59.13xx.e build) as well as in the 11.0 release (in builds prior to 65.x), application firewall
processing of the Cookie header was changed. In those releases, every cookie is evaluated individually, and if the length of any one cookie received in
the Cookie header exceeds the configured BufferOverflowMaxCookieLength, the Buffer Overflow violation is triggered. As a result of this change,
requests that were blocked in 10.5 and earlier release builds might be allowed, because the length of the entire cookie header is not calculated for
determining the cookie length. In some situations, the total cookie size forwarded to the server might be larger than the accepted value, and the server
might respond with "400 Bad Request".
Note that this change has been reverted. The behavior in the 10.5.e ->59.13xx.e and subsequent 10.5.e enhancement builds as well as in the 11.0
release 65.x and subsequent builds is now similar to that of the non-enhancement builds of release 10.5. The entire raw Cookie header is now
considered when calculating the length of the cookie. Surrounding spaces and the semicolon (;) characters separating the name-value pairs are
also included in determining the cookie length.
An attacker would normally modify a cookie to gain access to sensitive private information by posing as a previously
authenticated user, or to cause a buffer overflow. T he Buffer Overflow check protects against attempts to cause a buffer
overflow by using a very long cookie. T he Cookie Consistency check focuses on the first scenario.
If you use the wizard or the configuration utility, in the Modify Cookie Consistency Check dialog box, on the General tab
you can enable or disable the following actions:
Block
Log
Learn
Statistics
T ransform. If enabled, the T ransform action modifies all cookies as specified in the following settings:
Encrypt Server Cookies. Encrypt cookies set by your web server, except for any listed in the Cookie Consistency
check relaxation list, before forwarding the response to the client. Encrypted cookies are decrypted when the client
sends a subsequent request, and the decrypted cookies are reinserted into the request before it is forwarded to the
protected web server. Specify one of the following types of encryption:
None. Do not encrypt or decrypt cookies. T he default.
Decrypt only. Decrypt encrypted cookies only. Do not encrypt cookies.
Encrypt session only. Encrypt session cookies only. Do not encrypt persistent cookies. Decrypt any encrypted
cookies.
Encrypt all. Encrypt both session and persistent cookies. Decrypt any encrypted cookies.
Note: When encrypting cookies, the application firewall adds the Ht t pOnly flag to the cookie. T his flag prevents
scripts from accessing and parsing the cookie. T he flag therefore prevents a script-based virus or trojan from
accessing a decrypted cookie and using that information to breach security. T his is done regardless of the Flags to
Add in Cookies parameter settings, which are handled independently of the Encrypt Server Cookies parameter
settings.
P roxy Server Cookies. Proxy all non-persistent (session) cookies set by your web server, except for any listed in the
Cookie Consistency check relaxation list. Cookies are proxied by using the existing application firewall session cookie. T he
application firewall strips session cookies set by the protected web server and saves them locally before forwarding the
response to the client. When the client sends a subsequent request, the application firewall reinserts the session cookies
into the request before forwarding it to the protected web server. Specify one of the following settings:
None. Do not proxy cookies. T he default.
Session only. Proxy session cookies only. Do not proxy persistent cookies.
Note: If you disable cookie proxying after having enabled it (set this value to None after it was set to Session only),
cookie proxying is maintained for sessions that were established before you disabled it. You can therefore safely
disable this feature while the application firewall is processing user sessions.
F lags t o Add in Cookies . Add flags to cookies during transformation. Specify one of the following settings:
None. Do not add flags to cookies. T he default.
HT T P only. Add the HttpOnly flag to all cookies. Browsers that support the HttpOnly flag do not allow scripts to
If you use the command-line interface, you can enter the following commands to configure the Cookie Consistency Check:
set appfw profile <name> -cookieConsistencyAction [block ] [learn ] [log ] [st at s ] [none ]
set appfw profile <name> -cookieT ransforms ([ON ] | [OF F ])
set appfw profile <name> -cookieEncryption ([none ] | [decrypt Only ] | [encrypt Session ] | [encrypt All])
set appfw profile <name> -cookieProxying ([none ] | [sessionOnly ])
set appfw profile <name> -addCookieFlags ([none ] | [ht t pOnly ] | [secure ] | [all])
To specify relaxations for the Cookie Consistency check, you must use the configuration utility. On the Checks tab of the
Modify Cookie Consistency Check dialog box, click Add to open the Add Cookie Consistency Check Relaxation dialog box,
or select an existing relaxation and click Open to open the Modify Cookie Consistency Check Relaxation dialog box. Either
dialog box provides the same options for configuring a relaxation.
Logon F ields. T he following expression exempts all cookie names beginning with the string logon_ followed by a string
of letters or numbers that is at least two characters long and no more than fifteen characters long:
^logon_[0-9A-Za-z]{2,15}$
Logon F ields (special charact ers). T he following expression exempts all cookie names beginning with the string
türkçe-logon_ followed by a string of letters or numbers that is at least two characters long and no more than fifteen
characters long:
^t\xC3\xBCrk\xC3\xA7e-logon_[0-9A-Za-z]{2,15}$
Arbit rary st rings. Allow cookies that contain the string sc-item_, followed by the ID of an item that the user has added
to his shopping cart ([0-9A-Za-z]+), a second underscore (_), and finally the number of these items he wants ([1-9][0-9]?),
to be user-modifiable:
^sc-item_[0-9A-Za-z]+_[1-9][0-9]?$
Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write. Make sure that they define exactly the URL you want to add
as an exception, and nothing else. Careless use of wildcards, and especially of the dot-asterisk (.*) metacharacter/wildcard
combination, can have results you do not want or expect, such as blocking access to web content that you did not intend
to block or allowing an attack that the Cookie Consistency check would otherwise have blocked.
Important
In release 10.5.e (in a few interim enhancement builds prior to 59.13xx.e build) as well as in the 11.0 release (in builds prior to 65.x),
application firewall processing of the Cookie header was changed. In those releases, every cookie is evaluated individually, and if
the length of any one cookie received in the Cookie header exceeds the configured BufferOverflowMaxCookieLength, the Buffer
Overflow violation is triggered. As a result of this change, requests that were blocked in 10.5 and earlier release builds might be
allowed, because the length of the entire cookie header is not calculated for determining the cookie length. In some situations, the
total cookie size forwarded to the server might be larger than the accepted value, and the server might respond with "400 Bad
Request".
Note
S e s s io nle s s Co o kie Co ns is te ncy : T he cookie consistency behavior has changed in release 11.0. In earlier releases, the cookie
consistency check invokes sessionization. T he cookies are stored in the session and signed. A "wlt_" suffix is appended to transient
cookies and a "wlf_" suffix is appended to the persistent cookies before they are forwarded to the client. Even if the client does not
return these signed wlf/wlt cookies, the application firewall uses the cookies stored in the session to perform the cookie
consistency check.
In release 11.0, the cookie consistency check is sessionless. T he application firewall now adds a cookie that is a hash of all the
cookies tracked by the application firewall. If this hash cookie or any other tracked cookie is missing or tampered with, the
application firewall strips the cookies before forwarding the request to the back end server and triggers a cookie-consistency
violation. T he server treats the request as a new request and sends new Set-Cookie header(s).
Web servers following Google Web Toolkit (GWT ) Remote Procedure Call (RPC) mechanisms can be secured by the NetScaler application firewall without a need
for any specific configuration to enable the GWT support.
T he GWT is used for building and optimizing complex high-performance web applications by people who do not have expertise in XMLHttpRequest, and
JavaScript. T his open source, free development toolkit is used extensively for developing small and large scale applications and is quite frequently used for
displaying browser based data such as search results for flights, hotels, and so on. T he GWT provides a core set of Java APIs and widgets for writing optimized
JavaScript scripts that can run on most browsers and mobile devices. T he GWT RPC framework makes it easy for the client and server components of the web
application to exchange Java objects over HT T P. GWT RPC services are not the same as web services based on SOAP or REST. T hey are simply a lightweight
method for transferring data between the server and the GWT application on the client. GWT handles serialization of the Java objects exchanging the
arguments in the method calls and the return value.
https://www.quora.com/What-web-applications-use-Google-Web-Toolkit-%28GWT %29
T he GWT RPC request is pipe delimited and has variable number of arguments. It is carried as a payload of HT T P POST and has the following values:
1. Content-type = text/x-gwt-rpc. Charset can be any value.
2. Method = POST .
5|0|8|http://localhost:8080/test/|16878339F02B83818D264AE430C20468| com.test.client.TestService|testMethod|java.lang.String|java.lang.Integer|
myInput1|java.lang.Integer/3438268394|1|2|3|4|2|5|6|7|8|1|
a) Header: 5|0|8|
T he first 3 digits “5|0|8|” in the above request, represent “version, subversion, and size of table”, respectively. T hese must be positive integers.
b) St ring T able:
http://localhost:8080/test/|16878339F02B83818D264AE430C20468| com.test.client.TestService|testMethod|java.lang.String|java.lang.Integer|myInput1|
java.lang.Integer/3438268394|
T he members of the above pipe delimited string table contain the user-provided inputs. T hese inputs are parsed for the application firewall checks and are
identified as follows:
1st : http://localhost:8080/test/
T his is the Request URL. It should not contain the query part, because the GET method is not allowed.
2nd : 16878339F02B83818D264AE430C20468
Unique HEX identifier. A request is considered malformed if this string has non-hex characters.
4th : testMethod
Service method name
<container>.<sub-cntnr>.name/<integer_identifier>
T he payload consists of references to the elements in the string table. T hese integer values cannot be larger than the number of elements in the string table.
T he application firewall headers and cookies checks for GWT requests are similar to those for other request formats. After appropriate URL decoding and
charset conversion, all the parameters in the string table are inspected. T he GWT request body does not contain field names, just the field values. T he input
values can be validated against the specified format by using the application firewall Field Format check, which can also be used to control the length of the
input. T he Cross-sit e Script ing and SQL Inject ion attacks in the inputs can be easily detected and thwarted by the application firewall.
Learning and relaxat ion rules : Learning and deployment of relaxation rules are supported for GWT requests. Application firewall rules are in the form of
<actionURL> <fieldName> mapping. T he GWT request format does not have the field names and thus requires special handling. T he application firewall inserts
dummy field names in the learned rules that can be deployed as relaxation rules. T he -isRegex flag works as it does for non-GWT rules.
Act ion URL:
Multiple services responding to an RPC can be configured on the same web server. T he HT T P request has the URL of the web server, not of the actual service
handling the RPC. T herefore, relaxation is not applied on the basis of the HT T P request URL, because that would relax all the services on that URL for the target
field. For GWT requests, the application firewall uses the URL of the actual service found in the GWT payload, in the fourth field in the string table.
F ield name:
Since the GWT request body contains only field values, the application firewall inserts dummy field names such as 1, 2, and so on when recommending learned
rules.
Example of a GWT learned rule
5|0|8|http://localhost:8080/acdtest/|16878339F02Baf83818D264AE430C20468|
com.test.client.TestService|testMethod|java.lang.String%3b|java.lang.Integer|onblur|
Log Messages : T he application firewall generates log messages for the security check violations that are detected in the GWT requests. A log message
generated by a malformed GWT request contains the string “GWT ” for easy identification.
Dec 5 21:48:02 <local0.notice> 10.217.31.247 12/05/2014:21:48:02 GMT ns 0-PPE-0 : APPFW Message 696 0 : "GWT RPC request with malformed payload.
<blocked>”
T he same payload can trigger different application firewall security check violations for different Content-types. Consider the following example:
5|0|8|http://localhost:8080/acdtest/|16878339F02Baf83818D264AE430C20468|com.test.client.TestService|testMethod|java.lang.String%3b|java.lang.Integer|select|
A request sent with this content type results in a SQL violation if the SQL Injection Type is configured to use any of the four available options:
SQLSplCharANDKeyword, SQLSplCharORKeyword, SQLKeyword, or SQLSplChar. T he application firewall considers '&' to be the field separator and '=' to be the
name-value separator when processing the above payload. Since neither of these characters appears anywhere in the post body, the entire content is treated
as a single field name. T he field name in this request contains both an SQL special character (;) and an SQL Keyword (select). T herefore violations are caught for
all four SQL Injection type options.
A request sent with this content type triggers an SQL violation only if the SQL injection type is set to one of the following three
options:SQLSplCharORKeyword,SQLKeyword, or SQLSplChar. No violation is triggered if the SQL injection type is set to SQLSplCharANDKeyword, which is the
As a result, when SQL Injection Type is set to SQLSplChar, field 8 indicates the SQL violation. For SQLKeyword , field 10 indicates the violation. Either of these
two fields can indicate a violation if the SQL Inject type is configured with the SQLSplCharORKeyword option, which looks for the presence of either a
keyword or a special character. No violation is caught for the default SQLSplCharANDKeyword option, because there is no single field that has a value that
contains both SQLSplChar and SQLKeyword together.
T ips :
No special application firewall configuration is needed to enable GWT support.
T he Content-type must be text/x-gwt-rpc.
Learning and deploying of the relaxation rules for all the pertinent application firewall security checks applied to GWT payload works the same as it does for
the other supported content-types.
Only POST requests are considered valid for GWT . All other request methods are blocked if the content-type is text/x-gwt-rpc.
GWT requests are subject to the configured POST body limit of the profile.
T he sessionless setting for the security checks is not applicable and will be ignored.
CEF log format is supported for the GWT log messages.
T he NetScaler application firewall Credit Card check prevents attackers from exploiting Data Leak Prevention flaws to
obtain credit card numbers of your customers. By following simple configuration steps, you can enforce protection of one
or more of the following credit cards: 1) Visa, 2) Master Card, 3) Discover, 4) American Express (Amex), 5) JCB, and 6) Diners
Club.
T he Credit Card security check examines server responses to identify instances of the target credit card numbers, and
applies a specified action when such a number is found. T he action can be to transform the response by X’ing out all but
the last group of digits in the credit card number, or to block the response if it contains more than a specified number of
credit card numbers. If you specify both, the block action takes precedence. T he Maximum credit cards allowed per page
setting determines when the block action is invoked. T he default setting, 0 (no credit card numbers allowed on the page), is
the safest, but you can allow up to 255. Depending on where the violation is detected in the response and the block action
gets triggered, you might get fewer than the maximum allowed number of credit cards in the response.
To avoid false positives, you can apply relaxations to exempt specific numbers from the Credit Card check. For example, a
social security number, purchase order number, or Google account number might be similar to a credit card number. You can
specify individual numbers or use a regular expression to indicate the string of digits to be bypassed when processing the
response URL for credit card inspection.
If you’re not sure which credit card numbers to exempt, you can use the learn feature to generate recommendations based
on the learned data. To get optimal benefit without compromising performance, you might want to enable this option for a
short time to get a representative sample of the rules, and then deploy the relaxations and disable learning.
If you enable the log feature, the Credit Card check generates log messages indicating the actions that it takes. You can
monitor the logs to determine whether responses to legitimate requests are getting blocked. A large increase in the number
of log messages can indicate thwarted attempts to gain access. By default, the doSecureCreditCardLogging parameter is
ON, so the credit card number is not included in the log message generated by the safe commerce (Credit Card) violation.
T he stats feature gathers statistics about violations and logs. An unexpected surge in the stats counter might indicate that
your application is under attack.
To configure the Credit Card security check for protecting your application, configure the profile that governs inspecting
the traffic to and from this application.
Not e : A website that does not access a SQL database usually does not have access to sensitive private information such
as credit card numbers.
In the command line interface, you can use either the set appfw profile command or the add appfw profile command to
activate credit-card checking and specify which actions to perform. You can use the unset appfw profile command to
revert back to the default settings. To specify relaxations, use the bind appfw command to bind credit card numbers to the
profile.
Use either the set appfw profile command or the add appfw profile command, as follows:
set appfw profile <name> -creditCardAction ( ([block ] [learn ] [log ] [st at s ]) | [none ])
set appfw profile <name> -creditCard (VISA | MAST ERCARD | DISCOVER | AMEX | JCB | DINERSCLUB )
set appfw profile <name> -creditCardMaxAllowed <integer>
set appfw profile <name> -creditCardXOut ([ON ] | [OF F ])
set appfw profile <name> -doSecureCreditCardLogging ([ON ] | [OF F ])
T o conf igure a Credit Card relaxat ion rule by using t he command line
Use the bind command to bind the credit card number to the profile. T o remove a credit card number from a profile, use the
unbind command, with the same arguments that you used for the bind command. You can use the show command to
display the credit card numbers bound to a profile.
T o bind a credit card number a prof ile
bind appfw profile <profile-name> -creditCardNumber <any number/regex> “<url>”
In the configuration utility, you configure the Credit Card security check in the pane for the profile associated with your
application.
T o add or modify the Credit Card security check by using the Configuration Utility
1. Navigate to Application Firewall > Profiles, highlight the target profile, and click Edit.
2. In the Advanced Settings pane, click Security Checks.
T he security check table displays the currently configured action settings for all the security checks. You have 2 options
for configuration:
1. If you just want to enable or disable Block, Log, Stats, and Learn actions for Credit Card, you can select or clear check
boxes in the table, Click OK, and then click Save and Close to close the Security Check pane.
2. If you want to configure additional options for this security check, double click Credit Card, or select the row and click
Action Settings to display additional options as follows:
X-Out— Mask any credit card number detected in a response by replacing each digit, except the digits in the final
group, with the letter “X.”
Maximum credit cards allowed per page— Specify the number of credit cards that can be forwarded to the client
without triggering a block action.
Protected Credit Cards. Select or clear a check box to enable or disable protection for each type of credit card.
You can also edit the Block, Log, Stats and Learn actions in the Credit Card Settings pane.
After making any of the above changes, click OK to save the changes and return to the Security Checks table. You
can proceed to configure other security checks if needed. Click OK to save all the changes you have made in the
Security Checks section and then click Save and Close to close the Security Check pane.
T o conf igure a Credit Card relaxat ion rule by using t he Conf igurat ion Ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Relaxation Rules. T he Relaxation Rules table has a Credit Card entry. You can double
click, or select this row and click the Edit button to access the Credit Card Relaxation Rules dialogue. You can perform
Add, Edit, Delete, Enable, or Disable operations for relaxation rules.
When the learn action is enabled, the application firewall learning engine monitors the traffic and learns the triggered
violations. You can periodically inspect these learned rules. After due consideration, if you want to exempt a specific string
of digits from the Credit Card security check, you can by deploy the learned rule as a relaxation rule.
T o view or use learned dat a by using t he command line int erf ace
show appfw learningdata <profilename> creditCardNumber
rm appfw learningdata <profilename> -creditcardNumber <credit card number> “<url>”
You also have the option to show a summarized view of the learned relaxations by selecting the Credit Card entry in the
Learned Rules table and clicking Visualizer to get a consolidated view of all the learned violations. T he visualizer makes it
very easy to manage the learned rules. It presents a comprehensive view of the data on one screen and facilitates taking
action on a group of rules with one click. T he biggest advantage of the visualizer is that it recommends regular expressions
to consolidate multiple rules. You can select a subset of these rules, based on the delimiter and Action URL. You can display
25, 50, or 75 rules in the visualizer, by selecting the number from a drop-down list. T he visualizer for learned rules offers the
option to edit the rules and deploy them as relaxations. Or you can skip the rules to ignore them.
When the log action is enabled, the Credit Card security check violations are logged in the audit log as
APPFW_SAFECOMMERCE or APPFW_SAFECOMMERCE_XFORM violations. T he application firewall supports both Native
and CEF log formats. You can also send the logs to a remote syslog server.
T he default setting for doSecureCreditCardLogging is ON. If you change it to OFF, both credit card number and type are
included in the log message.
Depending on the settings configured for the Credit Card checks, the application-firewall generated log messages might
include the following information:
Response was blocked or not blocked.
Credit card numbers were transformed (X’d out). A separate log message is generated for each transformed credit card
If you place the cursor in the row for a specific log message, multiple options, such as Module and EventType, appear
below the log message. You can select any of these options to highlight the corresponding information in the logs.
Example of a Native format log message when the response is not blocked
When the stats action is enabled, the corresponding counter for the Credit Card check is incremented when the application
firewall takes any action for this security check. T he statistics are collected for Rate and Total count for Traffic, Violations,
and Logs. T he increment of the log counter can vary depending on the configured settings. For example, if the block action
is enabled and the Max Allowed credit card setting is 0, the request for a page that contains 20 credit card numbers
increments the stats counter by one when the page is blocked as soon as the first credit card number is detected. However,
if block is disabled and transform is enabled, processing the same request increments the statistics counter for logs by 20,
because each credit card transformation generates a separate log message.
Note the following points about the Credit Card security check:
T he application firewall enables you to protect credit card information and detect any attempts to access this sensitive
data.
T o use the Credit Card protection check, you must specify at least one type of credit card and an action. T he check is
then applied to HT ML, XML, and Web 2.0 profiles.
You can pipe the output of sh appfw profile command and grep for CreditCard to see all the Credit Card specific
configuration. For example, sh appfw profile my_profile | grep CreditCard displays the configured settings of various
parameters as well as the relaxation rules pertaining to the Credit Card check for the application firewall profile named
my_profile.
You can exclude specific numbers from Credit Card inspection without bypassing the security check inspection for the
rest of the credit card numbers.
Relaxation is available for all application firewall protected credit card patterns. In the configuration utility, you can use
the visualizer to specify Add, Edit, Delete, Enable, or Disable operations on relaxation rules.
T he application firewall learning engine can monitor the outgoing traffic to recommend rules based on observed
violations. Visualizer support is also available for managing the learned credit card rules in the configuration utility. You
can edit and deploy the learned rules, or skip them after careful inspection.
T he setting for number of allowed credit cards applies to each response. It does not pertain to the cumulative total of
credit card numbers observed during the entire user session.
T he number of X’d out digits depends on the length of the credit card numbers. T en digits are X’d out for credit cards
that have 13 through 15 digits. T welve digits are X’d out for credit cards that have 16 digits. If your application does not
require sending the entire credit card number in the response, Citrix recommends that you enable this action to mask the
T he Safe Object check prevents attackers from exploiting a security flaw in your web server software or on your web site
to obtain sensitive private information, such as company credit card numbers or social security numbers. If your web sites do
not have access to these types of information, you do not need to configure this check. If you have a shopping cart or
other application that can access such information, or your web sites have access to database servers that contain such
information, you should configure protection for each type of sensitive private information that you handle and store.
Note: A web site that does not access an SQL database usually does not have access to sensitive private information.
T he Safe Object Check dialog box is unlike that for any other check. Each safe object expression that you create is the
equivalent of a separate security check, similar to the Credit Card check, for that type of information. If you use the wizard
or the configuration utility, you add a new expression by clicking Add and configuring the expression in the Add Safe Object
dialog box. You modify an existing expression by selecting it, then clicking Open, and then configuring the expression in the
Modify Safe Object dialog box.
In the Safe Object dialog box for each safe object expression, you can configure the following:
Saf e Object Name. A name for your new safe object. T he name can begin with a letter, number, or the underscore
symbol, and can consist of from one to 255 letters, numbers, and the hyphen (-), period (.) pound (#), space ( ), at sign (@),
equals (=), colon (:), and underscore (_) symbols.
Act ions. Enable or disable the Block, Log, and Statistics actions, and the following actions:
X-Out . Mask any information that matches the safe object expression with the letter “X”.
Remove. Remove any information that matches the safe object expression.
Regular Expression. Enter a PCRE-compatible regular expression that defines the safe object. You can create the
regular expression in one of three ways: by typing the regular expression directly into the text box, by using the Regex
T okens menu to enter regular expression elements and symbols directly into the text box, or by opening the Regular
Expressions Editor and using it to construct the expression. T he regular expression must consist of ASCII characters only.
Do not cut and paste characters that are not part of the basic 128-character ASCII set. If you want to include non-
ASCII characters, you must manually type those characters in PCRE hexadecimal character encoding format.
Note: Do not use start anchors (^) at the beginning of Safe Object expressions, or end anchors ($) at the end of Safe
Object expressions. T hese PCRE entities are not supported in Safe Object expressions, and if used, will cause your
expression not to match what it was intended to match.
Maximum Mat ch Lengt h. Enter a positive integer that represents the maximum length of the string that you want to
match. For example, if you want to match U.S. social security numbers, enter the number eleven (11) in this field. T hat
allows your regular expression to match a string with nine numerals and two hyphens. If you want to match California
driver’s license numbers, enter the number eight (8).
Caution: If you do not enter a maximum match length in this field, the application firewall uses a default value of one (1)
when filtering for strings that match your safe object expressions. As a result, most safe object expressions fail to match
their target strings.
Look for strings that appear to be U.S. social security numbers, which consist of three numerals (the first of which must
not be zero), followed by a hyphen, followed by two more numerals, followed by a second hyphen, and ending with a
string of four more numerals:
[1-9][0-9]{2,2}-[0-9]{2,2}-[0-9]{4,4}
Look for strings that appear to be California driver’s license IDs, which start with a letter and are followed by a string of
exactly seven numerals:
[A-Za-z][0-9]{7,7}
Look for strings that appear to be Example Manufacturing customer IDs which, consist of a string of five hexadecimal
characters (all the numerals and the letters A through F), followed by a hyphen, followed by a three-letter code, followed
by a second hyphen, and ending with a string of ten numerals:
[0-9A-Fa-f]{5,5}-[A-Za-z]{3,3}-[0-9]{10,10}
Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write to ensure that they define exactly the type of string you want
to add as a safe object definition, and nothing else. Careless use of wildcards, and especially of the dot-asterisk (.*)
metacharacter/wildcard combination, can have results you did not want or expect, such as blocking access to web content
that you did not intend to block.
Note
SQL, XSS, FFC, and FieldFormat protection checks are applied if the Exclude Uplo a d File s Fro m S e curity Che cks is unset.
A file upload is also a form element that has control-name name field that is submitted as part of form submission.
By preventing an attacker from sending inappropriate web form data to your web site, the Field Formats check prevents
certain types of attacks on your web site and database servers. For example, if a particular field expects the user to enter a
phone number, the Field Formats check examines the user-submitted input to ensure that the data matches the format of
a phone number. If a particular field expects a first name, the Field Formats check ensures that the data in that field is of a
type and length appropriate for a first name. It does the same thing for each form field that you configure it to protect.
T his check applies to HT ML requests only. It does not apply to XML requests. You can configure Field Format Checks in
HT ML profiles or Web 2.0 profiles to inspect HT ML payload for protecting your applications. T he application firewall also
supports Field Format Check protection for Google Web Toolkit (GWT ) applications.
T he Field Formats check requires that you enable one or more actions. T he application firewall examines the submitted
inputs and applies the specified actions.
Note
Field format rules are tightening rules. Adding them to relaxation list from learned data acts as a blocking rule.
To relax field format rules, please remove particular “fieldname” from the fieldformat relaxations list.
You have the option to set the default field formats to specify Field Type and the minimum and maximum length of data
expected in each form field on each web form that you want to protect. You can deploy relaxation rules to configure a
Field Format for an individual field of a specific form. Multiple rules can be added to specify the field name, the action URL,
and Field Formats. Specify Field Formats to accept different types of inputs in different form fields. T he learning feature
can provide recommendations for the relaxation rules.
F ield F ormat Act ions — You can enable Block, Log, Stats, and Learn actions. At least one of these actions must be
enabled to engage the Field Format Check protection.
Block . If you enable block, the block action is triggered if the input does not conform to the specified Field Format. If a
rule was configured for the target field, the input is checked against the specified rule. Otherwise, it is checked against
the default field format specification. Any mismatch in the Field T ype or min/max length specification results in blocking
the request.
Log . If you enable the log feature, the Field Format check generates log messages indicating the actions that it takes.
You can monitor the logs to determine whether responses to legitimate requests are getting blocked. A large increase in
the number of log messages can indicate malicious attempts to launch an attack.
St at s . If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in the stats
counter might indicate that your application is under attack, or you might have to revisit the configuration to see if the
specified field format is too restrictive.
Learn . If you are not sure which Field T ypes or minimum and maximum length values might be ideally suited for your
application, you can use the learn feature to generate recommendations based on the learned data. T he application
Def ault F ield F ormat — In addition to configuring the actions, you can configure the default Field Format to specify the
type of data expected in all the form fields for your application. A Field T ype can be selected as the Field Format type.
Minimum length and Maximum length parameters can be used to specify the length of the allowed inputs. As an alternative
to Field T ypes, you can use Character Maps to specify what’s allowed in a field (except in cluster deployments).
F ield T ype — Field T ypes are named expression to which you assign assigned priority values. Field T ype expressions
specify the allowed inputs and are matched against the submitted data to determine whether the received values are
consistent with the allowed values. T he Field T ypes are checked in the order of their priority numbers. A lower number
indicates a higher priority. T he application firewall gives you the option to add your own Field T ypes and assign them the
priorities you want. T he priority value can range from 0 through 64000. T he following built-in Field T ypes are provided to
help simplify the configuration process:
> sh appfw fieldtype
1) Name: integer Regex: "^[+-]?[0-9]+$"
Priority: 30 Comment: Integer
Builtin: IMMUTABLE
2) Name: alpha Regex: "^[a-zA-Z]+$"
Priority: 40 Comment: "Alpha characters"
Builtin: IMMUTABLE
3) Name: alphanum Regex: "^[a-zA-Z0-9]+$"
Priority: 50 Comment: "Alpha-numeric characters"
Builtin: IMMUTABLE
4) Name: nohtml Regex: "^[^&<>]*$"
Priority: 60 Comment: "Not HTML"
Builtin: IMMUTABLE
5) Name: any Regex: "^.*$"
Priority: 70 Comment: Anything
Builtin: IMMUTABLE
Done
>
Note: T he built-in Field T ypes are IMMUT ABLE. T hey cannot be modified or removed. Any Field T ypes that you add are
MODIFIABLE. You can edit them or remove them.
Configuring a Field Type as a default Field Format might be useful when you have a PCRE expression that can identify
the valid inputs in all or most of the form fields for your application and exclude the invalid inputs. For example, if all the
inputs in your application forms are expected to contain only numbers and letters, you might want to use the built-in
Field Type alphanum as the default Field Type. Any non-alphanumeric character such as a backslash (\) or semicolon (;) in
the input will trigger a violation. You can also add your own customized Field Types and use them to configure default
Field Formats. For example, if you want to make the lowercase “x”, “y”, and “z” the only allowed alpha characters, you
can configure a customized Field Type with regular expression "^[x-z]+$". You could assign it a higher priority (lower
priority number) then the built-in Field Types and use it as the default Field Type.
Minimum Lengt h — T he default minimum data length assigned to form fields in web forms that do not have an explicit
Maximum Lengt h — T he default maximum data length assigned to form fields in web forms that do not have an
explicit setting. T his parameter is set to 65535 by default.
Note: Characters vs bytes. T he minimum and the maximum lengths for the field formats represent the number of bytes,
not the number of characters. Languages that have greater than one-byte character representation can cause the limit
to be exceeded with fewer characters than the number configured for the maximum value. For example, with double-
byte character representation, the maximum value of 9 allows no more than 4 characters.
T ip: T he configuration utility allows you to cut and paste UT F-8 characters directly into the GUI without having to
convert them to hex.
Charact er Maps : In addition to recommending the Field T ypes, the application firewall learning engine offers you an
additional option, Use Character Maps, to deploy the Format Check rules. A Character Map is a set of all the characters
allowed in a particular form field. You can fine tune the Field format specification to allow or disallow specific characters
by using Character Maps. A separate Character Map is generated for each form field. T he alpha and numeric characters
are treated differently in Character Maps. If any alpha character is seen in the input, all alpha characters [A-Za-z] will be
allowed by the recommended PCRE expression in the Character Map. Similarly, if any digit is included, all digits [0-9] will be
allowed. Non-printable characters are specified by using the \x construct. Only single Byte characters with values
between 0-255 are considered for Character Map recommendations.
A Character Map can be more specific than the corresponding Field Type recommendation. In some situations, Character
Maps might be a better option, because they give you tighter control over the set of characters allowed as inputs. T he
deployed character maps are displayed as strings that start with prefix “CM” followed by digits. T he priority for the
Character Maps starts at 10000. As with user-added Field Types, you can add, edit or remove a Character Map. Character
Maps that are currently used in deployed rules cannot be modified or removed.
Note
When you add a field formats rule with any built-in Field Type and use character map instead of Field Type and save it, the changes
do not get saved and rule still shows with Field Type.
When the character map matches one of the built-in type, the field type is reused instead of creating a new character map.
In the command line interface, you can use the add appfw fieldtype command to add a new Field Type. You can use either
the set appfw profile command or the add appfw profile command to configure the Field Format check and specify which
actions to perform. You can use the unset appfw profile command to revert the configured settings back to their defaults.
To specify a Field Format rule, use the bind appfw command to bind a Field Type to a form Field and the action URL, along
with the minimum and maximum length specifications.
Use the add command to add a Field Type. You must specify the Name, Regular expression and Priority when adding a new
Field Type. You also have the option to add a Comment. You can use the show command to display the configured Field
Types. You can also delete a Field Type by using the remove command, which requires only the Name of the Field Type.
<priority> is a positive_integer
sh appfw fieldtype
Note: As shown above, use of “appfw” in the command is optional. For example, “Add FieldT ype” or “Add appfw fieldT ype”
are both valid options. T he names of the Field T ypes are case insensitive due to normalization. As shown in the above
examples, Cust_Zipcode, cust_zipcode, and cUsT _ziPcode refer to the same Field T ype.
To configure a Field Format check by using the command line
Use either the set appfw profile command or the add appfw profile command, as follows:
set appfw profile <name> -fieldFormatAction (([block] [learn] [log] [stats]) | [none])
set appfw profile <name> -defaultFieldFormatT ype <string>
set appfw profile <name> -defaultFieldFormatMinLength <integer>
set appfw profile <name> -defaultFieldFormatMaxLength <integer>
bind appfw profile pr_ffc -fieldFormat "login_name" ".*/login.php" integer -fieldformatMinLength 3 -FieldformatMaxlength 6
In the configuration utility, you can manage the Field Types. You can also configure the Field Formats security check in the
pane for the profile associated with your application.
T o add or modify the Field Formats security check by using the Configuration Utility
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2 options
for configuration:
1. If you just want to enable or disable Block , Log , St at s , and Learn actions for Field Formats, you can select or clear
check boxes in the table, click OK , and then click Save and Close to close the Security Check pane.
2. If you want to configure additional options for this security check, double click Field Formats, or select the row and
click Action Settings, to display the following options for Def ault F ield F ormat :
F ield T ype — Select the Field T ype that you want to configure as the default Field T ype. You can select the built-
in and user-defined Field T ypes. T he deployed Character Maps are also included in the list and can be selected.
Minimum Lengt h — Specify the minimum number of characters that must be in each field. Possible values: 0-
65535.
Maximum Lengt h — Specify the maximum number of characters that must be in each field. Possible values: 1-
65535.
You can also edit the Block , Log , St at s and Learn actions in the Field Formats Settings pane.
After making any of the above changes, click OK to save the changes and return to the Security Checks table. You can
proceed to configure other security checks if needed. Click OK to save all the changes you have made in the Security
Checks section, and then click Save and Close to close the Security Check pane.
T o conf igure a F ield F ormat s relaxat ion rule by using t he Conf igurat ion Ut ilit y
1. Navigate to Applicat ion F irewall > Profiles, highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Relaxat ion Rules . T he Relaxation Rules table has a Field Formats entry. You can
double click, or select this row and click the Edit button, to access the Field Formats Relaxation Rules dialogue. You can
perform Add , Edit , Delet e , Enable , or Disable operations for relaxation rules.
For a consolidated view of all the relaxation rules, you can highlight the Field Formats row and click Visualizer. T he
visualizer for deployed relaxations offers you the option to Add a new rule or Edit an existing one. You can also Enable or
Disable a group of rules by selecting a node and clicking the corresponding buttons in the relaxation visualizer.
When the learn action is enabled, the application firewall learning engine monitors the traffic and learns the triggered
violations. You can periodically inspect these learned rules. After due consideration, you can deploy the learned rule as a
Field Format relaxation rule.
F ield F ormat s Learning enhancement — An application firewall learning enhancement was introduced in release 11.0. In
the previous releases, once the learned field format recommendation is deployed, the application firewall learning engine
stops monitoring the valid requests for the purpose of recommending new rules on the basis of the new data points. T his
limits the configured security protection, because the learning database does not include any representations of the new
data seen in the valid requests processed by the security check.
Violations are no longer coupled with learning. T he learning engine learns and makes recommendations for the field formats
regardless of the violations. In addition to checking the blocked requests to determine whether the current field format is
No F ield f ormat is bound — T he behavior remains unchanged in this scenario. All learn data is sent to the aslearn engine.
T he learning engine suggests a field format rule based on the data set.
F ield f ormat is bound : In the previous releases, observed data is sent to the aslearn engine only in the case of a violation.
T he learning engine suggests a field format rule based on the data set. In the 11.0 release, all data is sent to aslearn engine
even if no violation is triggered. T he learning engine suggests a field format rule based on the entire data set of all received
inputs.
If the initial field format learned rules are based on a small sample of data, a few non typical values might result in a
recommendation that is too lenient for the target field. T he ongoing learning allows the application firewall to observe
data points from every request to collect a representative sample for the learned recommendations. T his is helpful in
further tightening the security to deploy the optimal input format with an adequate range value.
T he field format learning makes use of the priority of the Field T ypes as well as the configured settings of the following
learning thresholds:
F ieldF ormat MinT hreshold — Minimum number of times a specific form field must be observed before a learned
relaxation is generated. Default: 1.
F ieldF ormat P ercent T hreshold — Percentage of times a form field matched a particular Field T ype, before a learned
relaxation is generated. Default: 0.
When the log action is enabled, the Field Formats security check violations are logged in the audit log as
APPFW_FIELDFORMAT violations. T he application firewall supports both Native and CEF log formats. You can also send
the logs to a remote syslog server.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the Field Formats
violations:
Shell
tail -f /var/log/ns.log | grep APPFW_FIELDFORMAT
T he Citrix configuration utility includes a very useful tool (Syslog Viewer) for analyzing the log messages. You have multiple
options for accessing the Syslog Viewer:
Navigate to the Application Firewall > Profiles, select the target profile, and click Security Checks. Highlight the Field
Formats row and click Logs. When you access the logs directly from the Field Formats security check of the profile, it
filters out the log messages and displays only the logs pertaining to these security check violations.
You can also access the Syslog Viewer by navigating to NetScaler > System > Auditing. In the Audit Messages section,
click the Syslog messages link to display the Syslog Viewer, which displays all log messages, including other security check
violation logs. T his is useful for debugging when multiple security check violations might be triggered during request
processing.
Navigate to Application Firewall > policies > Auditing. In the Audit Messages section, click the Syslog messages link to
display the Syslog Viewer, which displays all log messages, including other security check violation logs.
T he HT ML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to
you. To access Field Formats security check violation log messages, filter by selecting APPFW in the dropdown options
for Module. T he Event Type displays a rich set of options to further refine your selection. For example, if you select the
APPFW_FIELDFORMAT check box and click the Apply button, only log messages pertaining to the Field Formats security
check violations appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module and EventType, appear below
the log message. You can select any of these options to highlight the corresponding information in the logs.
Example of a Native format log message when the request is not blocked
Jun 10 22:32:26 <local0.info> 10.217.31.98 06/10/2015:22:32:26 GMT ns 0-PPE-0 :
default APPFW APPFW_FIELDFORMAT 97 0 : 10.217.253.62 562-PPE0
x1MV+YnNGzQFM3Bsy2wti4bhXio0001 pr_ffc http://aaron.stratum8.net/FFC/login_post.php
Field format check failed for field passwd="65568888sz-*_" <not blocked>
Example of a CEF format log message when the request is blocked
Jun 11 00:03:51 <local0.info> 10.217.31.98
CEF:0|Citrix|NetScaler|NS11.0|APPFW|APPFW_FIELDFORMAT|6|src=10.217.253.62 spt=27076
method=POST requet=http://aaron.stratum8.net/FFC/maxlen_post.php msg=Field format check
failed for field text_area\="" cn1=108 cn2=644 cs1=pr_ffc cs2=PPE0
cs3=GaUROfl1Nx1jJTvja5twH5BBqI0000 cs4=ALERT cs5=2015 act=blocked
sh appfw stats
Note: You can fine tune your configuration by getting new learning recommendations.
Note the following points about the Field Format security check:
P rot ect ion — By configuring optimal field format rules, you can protect against many attacks. For example, if you
specify that a field can only have integers, hackers will not be able to launch SQL Injection or XSS attacks by using this
field, because the inputs required to launch such attacks will not meet the configured field format requirement.
P erf ormance — You can limit the minimum and the maximum allowed length for the inputs in the field format rules. T his
can prevent a malicious user from entering excessively large input strings in an attempt to add processing overhead to
the server, or worse, cause the server to dump core because of stack overflow. By limiting the input size, you can shorten
the time required for processing legitimate requests.
Conf iguring F ield F ormat s — You must enable one of the actions (block, log, stats, learn) to engage the field Format
T he Form Field Consistency check prevents clients from making unauthorized changes to the structure of the web forms
on your web site when they fill out and submit a form. It also ensures that the data a user submits meets the HT ML
restrictions for length and type, and that data in hidden fields is not modified. T his prevents an attacker from tampering
with a web form and using the modified form to gain unauthorized access to web site, redirect the output of a contact
form that uses an insecure script and thereby send unsolicited bulk email, or exploit a vulnerability in your web server
software to gain control of the web server or the underlying operating system. Web forms are a weak link on many web
sites and attract a wide range of attacks.
If a field is sent to the user, the check ensures that it is returned by the user.
T he check enforces HT ML field lengths and types.
Note: T he Form Field Consistency check enforces HT ML restrictions on data type and length but does not otherwise
validate the data in web forms. You can use the Field Formats check to set up rules that validate data returned in
specific form fields on your web forms.
If your web server does not send a field to the user, the check does not allow the user to add that field and return data
in it.
If a field is a read-only or hidden field, the check verifies that the data has not changed.
If a field is a list box or radio button field, the check verifies that the data in the response corresponds to one of the
values in that field.
If a web form returned by a user violates one or more of the Form Field consistency checks, and you have not configured
the application firewall to allow that web form to violate the Form Field Consistency checks, the request is blocked.
If you use the wizard or the configuration utility, in the Modify Form Field Consistency Check dialog box, on the General tab
you can enable or disable the Block, Log, Learn, and Statistics actions.
You also configure Sessionless Field Consistency in the General tab. If Sessionless Field Consistency is enabled, the
application firewall checks only the web form structure, dispensing with those parts of the Form Field Consistency check
that depend upon maintaining session information. T his can speed the Form Field Consistency check with little security
penalty for web sites that use many forms. To use Sessionless Field Consistency on all web forms, select On. To use it only
for forms submitted with the HT T P POST method, select postOnly
If you use the command-line interface, you can enter the following command to configure the Form Field Consistency
Check:
set appfw profile <name> -fieldConsistencyAction [block ] [learn ] [log ] [st at s ] [none ]
To specify relaxations for the Form Field Consistency check, you must use the configuration utility. On the Checks tab of
the Modify Form Field Consistency Check dialog box, click Add to open the Add Form Field Consistency Check Relaxation
dialog box, or select an existing relaxation and click Open to open the Modify Form Field Consistency Check Relaxation
^UserType$
Choose form fields with names that begin with UserType_ and are followed by a string that begins with a letter or
number and consists of from one to twenty-one letters, numbers, or the apostrophe or hyphen symbol:
^UserType_[0-9A-Za-z][0-9A-Za-z'-]{0,20}$
Choose form fields with names that begin with Turkish-UserType_ and are otherwise the same as the previous
expression, except that they can contain Turkish special characters throughout:
^T\xC3\xBCrk\xC3\xA7e-UserType_([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])+$
Note: See "PCRE Character Encoding Format" for a complete description of supported special characters and how to
encode them properly.
Choose form field names that begin with a letter or number, consist of a combination of letters and/or numbers only,
and that contain the string Num anywhere in the string:
^[0-9A-Za-z]*Num[0-9A-Za-z]*$
Choose URLs beginning with http://www.example.com/search.pl? and containing any string after the query except for a
new query:
^http://www[.]example[.]com/search[.]pl\?[^?]*$
Choose URLs that begin with http://www.example-español.com and have paths and filenames that consist of upper-
case and lower-case letters, numbers, non-ASCII special characters, and selected symbols in the path. T he ñ character
and any other special characters are represented as encoded UT F-8 strings containing the hexadecimal code assigned to
each special character in the UT F-8 charset:
^http://www[.]example-espa\xC3\xB1ol[.]com/(([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)*([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*[.](asp|htp|php|s?html?)$
Choose all URLs that contain the string /search.cgi?:
^[^?<>]*/search[.]cgi\?[^?<>]*$
Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write. Make sure that they define exactly the URL you want to add
as an exception, and nothing else. Careless use of wildcards, and especially of the dot-asterisk (.*) metacharacter/wildcard
combination, can have results you do not want or expect, such as blocking access to web content that you did not intend
to block or allowing an attack that the Cookie Consistency check would otherwise have blocked.
T he CSRF Form Tagging check prevents attackers from using their own web forms to send high volume form responses
with data to your protected web sites. T his check requires relatively little CPU processing capacity compared to certain
other security checks that analyze web forms in depth. It is therefore able to handle high volume attacks without seriously
degrading the performance of the protected web site or the application firewall itself.
Before you enable the CSRF Form Tagging check, you should be aware of the following:
You need to enable form tagging. T he CSRF check depends on form tagging and does not work without it.
You should disable the Citrix NetScaler Integrated Caching feature for all web pages containing forms that are
protected by that profile. T he Integrated Caching feature and CSRF form tagging are not compatible.
You should consider enabling Referer checking. Referer checking is part of the Start URL check, but it prevents cross-site
request forgeries, not Start URL violations. Referer checking also puts less load on the CPU than does the CSRF Form
T agging check. If a request violates Referer checking, it is immediately blocked, so the CSRF Form T agging check is not
invoked.
T he CSRF Form T agging check does not work with web forms that use different domains in the form-origin URL and
form-action URL. For example, CSRF Form T agging cannot protect a web form with a form-origin URL of
http://www.example.com/ and a form action URL of http://www.example.org/form.pl, because example.com and
example.org are different domains.
If you use the wizard or the configuration utility, in the Modify CSRF Form Tagging Check dialog box, on the General tab
you can enable or disable the Block, Log, Learn and Statistics actions.
If you use the command-line interface, you can enter the following command to configure the CSRF Form Tagging Check:
set appfw profile <name> -fieldConsistencyAction [block ] [log ] [learn ] [st at s ] [none ]
To specify relaxations for the CSRF Form Tagging check, you must use the configuration utility. On the Checks tab of the
Modify CSRF Form Tagging Check dialog box, click Add to open the Add CSRF Form Tagging Check Relaxation dialog box, or
select an existing relaxation and click Open to open the Modify CSRF Form Tagging Check Relaxation dialog box. Either
dialog box provides the same options for configuring a relaxation.
An alert is generated when you set the NetScaler Appfirewall session limit to a value of 0 or lower, because such a setting
affects advanced protection check functionality that requires a properly functioning application firewall session.
Note: T he following expressions are URL expressions that can be used in both the Form Origin URL and Form Action URL
roles.
Choose URLs beginning with http://www.example.com/search.pl? and containing any string after the query, except for a
new query:
^http://www[.]example-espa\xC3\xB1ol[.]com/(([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)*([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*[.](asp|htp|php|s?html?)$
Choose all URLs that contain the string /search.cgi?:
^[^?<>]*/search[.]cgi\?[^?<>]*$
Important
Regular expressions are powerful. If you are not thoroughly familiar with PCRE-format regular expressions, double-check any
regular expressions you write. Make sure that they define exactly the URL that you want to add as an exception, and nothing else.
Careless use of wildcards, and especially of the dot-asterisk (.*) metacharacter/wildcard combination, can have results you do not
want, such as blocking access to web content that you did not intend to block or allowing an attack that the check would otherwise
have blocked.
Tip
When enableValidate referrer header is enabled under the Start URL Action, ensure that the Referrer Header URL is added to StartURL
as well.
Note
When NetScaler reaches the appfw_session_limit and CSRF checks are enabled, the web application freezes.
To prevent web application freeze, decrease the session timeout and increase the session limit by using the following commands:
Logging and generating SNMP alarms when appfw_session_limit is reached assists you in troubleshooting and debugging issues.
F orm Origin URL — In the text area, enter a PCRE-format regular expression that defines the URL that hosts the
form.
F orm Act ion URL — In the text area, enter a PCRE-format regular expression that defines the URL to which data
entered into the form is delivered.
T he primary purpose of the Start URL check is to prevent repeated attempts to access random URLs on a Web site, (forceful
browsing) through bookmarks, external links, or jumping to pages by manually typing in the URLs to skip the pages required to
reach that part of the website. Forceful browsing can be used to trigger a buffer overflow, find content that users were not
intended to access directly, or find a back door into secure areas of your Web server. T he application firewall enforces a
website's given traversal or logic path by allowing access to only the URL's that are configured as start URLs.
If you use the wizard or the configuration utility, in the Modify Start URL Check dialog box, on the General tab you can
enable or disable Block, Log, Statistics, Learn actions, and the following parameters:
Enf orce URL Closure. Allow users to access any web page on your web site by clicking a hyperlink on any other page on
your web site. Users can navigate to any page on your web site that can be reached from the home page or any
designated start page by clicking hyperlinks.
Note: T he URL closure feature allows any query string to be appended to and sent with the action URL of a web form
submitted by using the HT T P GET method. If your protected web sites use forms to access an SQL database, make sure
that you have the SQL injection check enabled and properly configured.
Sessionless URL Closure. From the client's point of view, this type of URL closure functions in exactly the same way as
standard, session-aware URL Closure, but uses a token embedded in the URL instead of a cookie to track the user's
activity, which consumes considerably fewer resources. When sessionless URL closure is enabled, the application firewall
appends a "as_url_id" tag to all the URL's that are in URL closure.
Note: When enabling sessionless (Sessionless URL Closure), you must also enable regular URL closure (Enforce URL Closure)
or sessionless URL closure does not work.
Validat e Ref erer Header. Verify that the Referer header in a request that contains web form data from your protected
web site instead of another web site. T his action verifies that your web site, not an outside attacker, is the source of the
web form. Doing so protects against cross-site request forgeries (CSRF) without requiring form tagging, which is more
CPU-intensive than header checks. T he application firewall can handle the HT T P Referer header in one of the following
four ways, depending on which option you select in the drop-down list:
Of f — Do not validate the Referer header.
If -P resent — Validate the Referer header if a Referer header exists. If an invalid Referer header is found, the request
generates a referer-header violation. If no Referer header exists, the request does not generate a referer-header
violation. T his option enables the application firewall to perform Referer header validation on requests that contain a
Referer header, but not block requests from users whose browsers do not set the Referer header or who use web
proxies or filters that remove that header.
Always Except St art URLs — Always validate the Referer header. If there is no Referer header and the requested URL
is not exempted by the startURL relaxation rule, the request generates a referer-header violation. If the Referer header
is present but it is invalid, the request generates a referer-header violation.
Always Except F irst Request — Always validate the referer header. If there is no referer header, only the URL that is
accessed first is allowed. All other URL's are blocked without a valid referer header. If the Referer header is present but
it is invalid, the request generates a referer-header violation.
One Start URL setting, Exempt Closure URLs f rom Securit y Checks , is not configured in the Modify Start URL
Note
Although the referer header check and Start URL security check share the same action settings, it is possible to violate the referer
header check without violating the Start URL check. T he difference is visible in the logs, which log referer header check violations
separately from Start URL check violations.
T he Referer header settings (OFF, if-Present, AlwaysExceptStartURLs, and AlwaysExceptFirstRequest) are arranged in order
of least restrictive to most restrictive and work as follows:
OF F :
If-P resent :
If you use the command-line interface, you can enter the following commands to configure the Start URL Check:
set appfw profile <name> -startURLAction [block ] [learn ] [log ] [st at s ] [none ]
set appfw profile <name> -startURLClosure ([ON ] | [OF F ])
set appfw profile <name> -sessionlessURLClosure ([ON ] | [OF F ])
set appfw profile <name> -exemptClosureURLsFromSecurityChecks ([ON ] | [OF F ])
set appfw profile <name> -RefererHeaderCheck ([OF F ] | [if -present ] | [AlwaysExcept St art URLs ] |
[AlwaysExcept F irst Request ])
To specify relaxations for the Start URL check, you must use the configuration utility. On the Checks tab of the Modify Start
URL Check dialog box, click Add to open the Add Start URL Check Relaxation dialog box, or select an existing relaxation and
click Open to open the Modify Start URL Check Relaxation dialog box. Either dialog box provides the same options for
configuring a relaxation.
^http://www[.]example[.]com$
Allow users to access all static HT ML (.htm and .html), server-parsed HT ML (.htp and .shtml), PHP (.php), and Microsoft ASP
(.asp) format web pages at www.example.com:
^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
[0-9A-Za-z][0-9A-Za-z_.-]*[.](asp|htp|php|s?html?)$
Allow users to access web pages with pathnames or file names that contain non-ASCII characters at www.example-
español.com:
^http://www[.]example-espa\xC3\xB1ol[.]com/(([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)*
([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*[.](asp|htp|php|s?html?)$
Note: In the above expression, each character class has been grouped with the string \\x[0-9A-Fa-f][0-9A-Fa-f], which
matches all properly-constructed character encoding strings but does not allow stray backslash characters that are not
associated with a UT F-8 character encoding string. T he double backslash (\\) is an escaped backslash, which tells the
application firewall to interpret it as a literal backslash. If you included only one backslash, the application firewall would
instead interpret the following left square bracket ([) as a literal character instead of the opening of a character class,
which would break the expression.
Allow users to access all GIF (.gif), JPEG (.jpg and .jpeg), and PNG (.png) format graphics at www.example.com:
^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
[0-9A-Za-z][0-9A-Za-z_.-]*[.](gif|jpe?g|png)$
Allow users to access CGI (.cgi) and PERL (.pl) scripts, but only in the CGI-BIN directory:
^http://www[.]example[.]com/CGI-BIN/[0-9A-Za-z][0-9A-Za-z_.-]*[.](cgi|pl)$
Allow users to access Microsoft Office and other document files in the docsarchive directory:
^http://www[.]example[.]com/docsarchive/[0-9A-Za-z][0-9A-Za-z_-.]*[.](doc|xls|pdf|ppt)$
Note
By default, all application firewall URLs are considered to be regular expressions.
Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular expressions,
double-check any regular expressions that you write. Make sure that they define exactly the URL you want to add as an
exception, and nothing else. Careless use of wildcards, and especially of the dot-asterisk (.*) metacharacter/wildcard
combination, can have results you do not want, such as blocking access to web content that you did not intend to block or
allowing an attack that the Start URL check would otherwise have blocked.
Tip
You can add the -and- to the allowed list of SQL keywords for URL naming scheme. For example, example https://FQDN/bread-and-butter.
T he Deny URL check takes priority over the Start URL check, and thus denies malicious connection attempts even when a
Start URL relaxation would normally allow a request to proceed.
In the Modify Deny URL Check dialog box, on the General tab you can enable or disable the Block, Log, and Statistics
actions.
If you use the command-line interface, you can enter the following command to configure the Deny URL Check:
To create and configure your own deny URLs, you must use the configuration utility. On the Checks tab of the Modify
Deny URL Check dialog box, click Add to open the Add Deny URL dialog box, or select an existing user-defined deny URL and
click Open to open the Modify Deny URLdialog box. Either dialog box provides the same options for creating and
configuring a deny URL.
^http://images[.]example[.]com$
Do not allow users to access CGI (.cgi) or PERL (.pl) scripts directly:
^http://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-]*/)*
[0-9A-Za-z][0-9A-Za-z_.-]*[.](cgi|pl)$
Here is the same deny URL, modified to support non-ASCII characters:
^http://www[.]example[.]com/(([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*/)*([0-9A-Za-z]|\\x[0-9A-Fa-f][0-9A-Fa-f])
([0-9A-Za-z_-]|\\x[0-9A-Fa-f][0-9A-Fa-f])*[.](cgi|pl)$
Caution: Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular
expressions, double-check any regular expressions you write. Make sure that they define exactly the URL or pattern that
you want to block, and nothing else. Careless use of wildcards, and especially of the dot-asterisk (.*)
metacharacter/wildcard combination, can have results that you do not want, such as blocking access to web content that
you did not intend to block.
Caution: T he XML security checks apply only to content that is sent with an HT T P content-type header of text/xml. If the
content-type header is missing, or is set to a different value, all XML security checks are bypassed. If you plan to protect
XML or Web 2.0 web applications, the webmasters of each web server that hosts those applications should ensure that
the proper HT T P content-type header is sent.
An XML document must contain only properly-encoded Unicode characters that match the Unicode specification.
No special XML syntax characters— such as < , > and &— can be included in the document except when used in XML
markup.
All begin, end, and empty-element tags must be correctly nested, with none missing or overlapping.
XML element tags are case-sensitive. All beginning and end tags must match exactly.
A single root element must contain all the other elements in the XML document.
A document that does not meet the criteria for well-formed XML does not meet the definition of an XML document.
Strictly speaking, it is not XML. However, not all XML applications and web services enforce the XML well-formed standard,
and not all handle poorly-formed or invalid XML correctly. Inappropriate handling of a poorly-formed XML document can
cause security breaches. T he purpose of the XML Format check is to prevent a malicious user from using a poorly-formed
XML request to breach security on your XML application or web service.
If you use the wizard or the configuration utility, in the Modify XML Format Check dialog box, on the General tab you can
enable or disable the Block, Log, and Statistics actions.
If you use the command-line interface, you can enter the following command to configure the XML Format Check:
You cannot configure exceptions to the XML Format check. You can only enable or disable it.
If you use the wizard or the configuration utility, in the Modify XML Denial-of-Service Check dialog box, on the General tab
you can enable or disable the Block, Log, Statistics, and Learn actions:
If you use the command-line interface, you can enter the following command to configure the XML Denial-of-Service
check:
set appfw profile <name> -xmlDoSAction [block ] [log ] [learn ] [st at s ] [none ]
To configure individual XML Denial-of-Service rules, you must use the configuration utility. On the Checks tab of the Modify
XML Denial-of-Service Check dialog box, select a rule and click Open to open the Modify XML Denial-of-Service dialog box
for that rule. T he individual dialog boxes differ for the different rules but are extremely simple. Some only allow you to
enable or disable the rule; others allow you to modify a number by typing a new value in a text box.
{http://prefix.example.com/path/}target_page.xml
T he user can modify the maximum name length to any value between one (1) character and 65,535.
Maximum # Element s
Restrict the maximum number of any one type of element per XML document to 65,535. You can modify the maximum
number of elements to any value between one (1) and 65,535.
To prevent misuse of the scripts on your protected web services to breach security on your web services, the XML Cross-
Site Scripting check blocks scripts that violate the same origin rule, which states that scripts should not access or modify
content on any server but the server on which they are located. Any script that violates the same origin rule is called a
cross-site script, and the practice of using scripts to access or modify content on another server is called cross-site scripting.
T he reason cross-site scripting is a security issue is that a web server that allows cross-site scripting can be attacked with a
script that is not on that web server, but on a different web server, such as one owned and controlled by the attacker.
T he application firewall offers various action options for implementing XML Cross-Site Scripting protection. You have the
option to configure Block , Log , and St at s actions.
T he application firewall XML XSS check is performed on the payload of the incoming requests and attack strings are
identified even if they are spread over multiple lines. T he check looks for XSS attack strings in the element and the
at t ribut e values. You can apply relaxations to bypass security check inspection under specified conditions. T he logs and
statistics can help you identify needed relaxations.
T he CDATA section of the XML payload might be an attractive area of focus for the hackers because the scripts are not
executable outside the CDATA section. A CDATA section is used for content that is to be treated entirely as character
data. HT ML mark up tag delimiters “< ”, “> ”, and “/> ” will not cause the parser to interpret the code as HT ML elements. T he
following example shows a CDATA Section with XSS attack string:
<![CDATA[\r\n
]]>
An action is applied when the XML Cross-Site Scripting check detects an XSS attack in the request. T he following options
are available for optimizing XML Cross-Site Scripting protection for your application:
Block — Block action is triggered if the XSS tags are detected in the request.
Log — Generate log messages indicating the actions taken by the XML Cross-Site Scripting check. If block is disabled, a
separate log message is generated for each location (ELEMENT , AT T RIBUT E) in which the XSS violation is detected.
However, only one message is generated when the request is blocked. You can monitor the logs to determine whether
responses to legitimate requests are getting blocked. A large increase in the number of log messages can indicate
If your application requires you to bypass the Cross-Site Scripting check for a specific ELEMENT or AT T RIBUT E in the XML
payload, you can configure a relaxation rule. T he XML Cross-Site Scripting check relaxation rules have the following
parameters:
Name — You can use literal strings or regular expressions to configure the name of the ELEMENT or the Attribute. T he
following expression exempts all ELEMENT S beginning with the string name_ followed by a string of uppercase or
lowercase letters, or numbers, that is at least two and no more than fifteen characters long:
^name_[0-9A-Za-z]{2,15}$
Note
T he names are case sensitive. Duplicate entries are not allowed, but you can use capitalization of the names and differences in
location to create similar entries. For example, each of the following relaxation rules is unique:
Locat ion — You can specify the Location of the Cross-site Scripting Check exception in your XML payload. T he option
ELEMENT is selected by default. You can change it to AT T RIBUT E.
Comment — T his is an optional field. You can use up to a 255 character string to describe the purpose of this relaxation
Rule.
Warning
Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular expressions, double-check
any regular expressions you write. Make sure that they define exactly the name that you want to add as an exception, and nothing
else. Careless use of Regular Expressions can have results that you do not want, such as blocking access to web content that you
did not intend to block or allowing an attack that the XML Cross-Site Scripting check would otherwise have blocked.
If you use the command-line interface, you can enter the following commands to configure the XML Cross-Site Scripting
Check:
> set appf w profile <name> -XMLXSSAct ion (([block ] [log ] [st at s ]) | [none ])
To configure a XML Cross-Sit e Script ing check relaxat ion rule by using t he command line
You can add relaxation rules to bypass inspection of XSS script attack inspection in a specific location. Use the bind or
unbind command to add or delete the relaxation rule binding, as follows:
> bind appf w profile <name> -XMLXSS <string> [isRegex (REGEX | NOT REGEX )] [-locat ion ( ELEMENT |
AT T RIBUT E )] – comment <string> [-st at e ( ENABLED | DISABLED )]
Example
After executing the above command, the following relaxation rule is configured. T he rule is enabled, the name is
treated as a literal (NOT REGEX), and ELEMENT is selected as the default location:
Done
In the configuration utility, you can configure the XML Cross-Site Scripting check in the pane for the profile associated with
your application.
To configure or modif y t he XML Cross-Sit e Script ing check by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2
options for configuration:
a) If you just want to enable or disable Block , Log , and St at s actions for the XML Cross-Sit e Script ing
check , you can select or clear check boxes in the table, click OK , and then click Save and Close to close the
Security Check pane.
You can proceed to configure other security checks if needed. Click OK to save all the changes you have made in the
Security Checks section, and then click Save and Close to close the Security Check pane.
To configure a XML Cross-Sit e Script ing relaxat ion rule by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Relaxat ion Rules .
3. In the Relaxation Rules table, double-click the XML Cross-Sit e Script ing entry, or select it and click Edit .
4. In the XML Cross-Sit e Script ing Relaxat ion Rules dialogue box, perform Add , Edit , Delet e , Enable , or Disable
operations for relaxation rules.
To manage XML Cross-Sit e Script ing relaxat ion rules by using t he visualizer
For a consolidated view of all the relaxation rules, you can highlight the XML Cross-Sit e Script ing row in the Relaxation
Rules table, and click Visualizer. T he visualizer for deployed relaxations offers you the option to Add a new rule or Edit an
existing one. You can also Enable or Disable a group of rules by selecting a node and clicking the corresponding buttons in
the relaxation visualizer.
To view or cust omize t he Cross-Sit e Script ing pat t erns by using t he configurat ion ut ilit y
You can use the configuration utility to view or customize the default list of XSS allowed attributes or allowed tags. You
can also view or customize the default list of XSS denied Patterns.
T he default lists are specified in Applicat ion F irewall > Signat ures > Def ault Signat ures . If you do not bind any
signature object to your profile, the default XSS Allowed and Denied list specified in the Default Signatures object will be
used by the profile for the Cross-Site Scripting security check processing. T he Tags, Attributes, and Patterns, specified in the
default signatures object, are read-only. You cannot edit or modify them. If you want to modify or change these, make a
copy of the Default Signatures object to create a User-Defined signature object. Make changes in the Allowed or Denied
lists in the new user-defined signature object and use this signature object in the profile that is processing the traffic for
which you want to use these customized allowed and denied lists.
1. Navigate to Applicat ion f irewall > Signat ures , select *Def ault Signat ures , and click Edit . T hen click Manage
SQL/XSS P at t erns .
T he Manage SQL/XSS Pat hs table shows following three rows pertaining to XSS :
xss/allowed/attribute
xss/allowed/tag
xss/denied/pattern
Select a row and click Manage Element s to display the corresponding XSS Elements (Tag, Attribute, Pattern) used by
To cust omize XSS Element s : You can edit the user-defined signature object to customize the allowed Tag, allowed
Attributes and denied Patterns. You can add new entries or remove the existing ones.
1. Navigat e t o Applicat ion f irewall > Signat ures , highlight the target user-defined signature, and click Edit . Click
Manage SQL/XSS P at t erns to display the Manage SQL/XSS pat hs table.
2. Select the target XSS row.
a) Click Manage Element s , to Add , Edit or Remove the corresponding XSS element.
Warning
Be very careful when you remove or modify any default XSS element, or delete the XSS path to remove the entire row. T he
signatures, HT ML Cross-Site Scripting security check, and XML Cross-Site Scripting security check rely on these Elements for
detecting attacks to protect your applications. Customizing the XSS Elements can make your application vulnerable to Cross-Site
Scripting attacks if the required pattern is removed during editing.
When the log action is enabled, the XML Cross-Site Scripting security check violations are logged in the audit log as
AP P F W_XML_XSS violations. T he application firewall supports both Native and CEF log formats. You can also send the
logs to a remote syslog server.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the XML Cross-Site
Scripting violations:
> Shell
Example of a XML Cross-Sit e Script ing securit y check violat ion log message in Nat ive log f ormat showing
<blocked> act ion
Oct 7 01:44:34 <local0.warn> 10.217.31.98 10/07/2015:01:44:34 GMT ns 0-PPE-1 : default APPFW APPFW_XML_XSS 1154
0 : 10.217.253.69 3466-PPE1 - owa_profile http://10.217.31.101/FFC/login.html Cross-site script check failed for field
script="Bad tag: script" <blocked >
Example of a XML Cross-Sit e Script ing securit y check violat ion log message in CEF log f ormat showing <not
blocked> act ion
T he Citrix configuration utility includes a useful tool (Syslog Viewer) for analyzing the log messages. You have multiple
options for accessing the Syslog Viewer:
Navigate to the Applicat ion F irewall > P rof iles , select the target profile, and click Securit y Checks . Highlight the
XML Cross-Sit e Script ing row and click Logs . When you access the logs directly from the XML Cross-Site Scripting
check of the profile, the configuration utility filters out the log messages and displays only the logs pertaining to these
security check violations.
You can also access the Syslog Viewer by navigating to Net Scaler > Syst em > Audit ing . In the Audit Messages
section, click the Syslog messages link to display the Syslog Viewer, which displays all log messages, including other
security check violation logs. T his is useful for debugging when multiple security check violations might be triggered
during request processing.
Navigate to Applicat ion F irewall > policies > Audit ing . In the Audit Messages section, click the Syslog messages
link to display the Syslog Viewer, which displays all log messages, including other security check violation logs.
T he XML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to you.
To select log messages for the XML Cross-Sit e Script ing check, filter by selecting AP P F W in the dropdown options for
Module . T he Event T ype list offers a rich set of options to further refine your selection. For example, if you select the
AP P F W_XML_XSS check box and click the Apply button, only log messages pertaining to the XML Cross-Site Scripting
security check violations appear in the Syslog Viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module , Event T ype , Event ID ,
Client IP etc. appear below the log message. You can select any of these options to highlight the corresponding
information in the log message.
When the stats action is enabled, the counter for the XML Cross-Site Scripting check is incremented when the application
firewall takes any action for this security check. T he statistics are collected for Rate and Total count for Traffic, Violations,
and Logs. T he size of an increment of the log counter can vary depending on the configured settings. For example, if the
block action is enabled, a request for a page that contains three XML Cross-Site Scripting violations increments the stats
counter by one, because the page is blocked as soon as the first violation is detected. However, if block is disabled,
processing the same request increments the statistics counter for violations and the logs by three, because each violation
generates a separate log message.
To display XML Cross-Sit e Script ing check st at ist ics by using t he command line
> sh appf w st at s
To display XML Cross-Sit e Script ing st at ist ics by using t he configurat ion ut ilit y
A XML SQL attack can inject source code into a web application such that it can be interpreted and executed as a valid
SQL query to perform a database operation with malicious intent. For example, XML SQL attacks can be launched to gain
unauthorized access to the contents of a database or to manipulate the stored data. XML SQL Injection attacks are not
only common, but can also be very harmful and costly.
Compartmentalizing the privileges of the database users can assist in protecting the database to some extent. All database
users should be given only the required privileges to complete their intended tasks, so that they cannot execute SQL
queries to perform other tasks. For example, a read-only user should not be allowed to write or manipulate data tables. T he
application firewall XML SQL Injection check inspects all XML requests to provide special defenses against injection of
unauthorized SQL code that might break security. If the application firewall detects unauthorized SQL code in any XML
request of any user, it can block the request.
T he NetScaler application firewall inspects the presence of SQL keywords and special characters to identify the XML SQL
Injection attack. A default set of keywords and special characters provides known keywords and special characters that are
commonly used to launch XML SQL attacks. T he application firewall considers three characters, single straight quote ('),
backslash (\), and semicolon (;) as special characters for SQL security check processing. You can add new patterns, and you
can edit the default set to customize the XML SQL check inspection.
T he application firewall offers various action options for implementing XML SQL Injection protection. You can Block the
request, Log a message in the ns.log file with details regarding the observed violations, and collect St at s to keep track of
the number of observed attacks.
In addition to actions, there are several parameters that can be configured for XML SQL injection processing. You can check
for SQL wildcard charact ers . You can change the XML SQL Injection type and select one of the 4 options
(SQLKeyword , SQLSplChar, SQLSplCharANDKeyword , SQLSplCharORKeyword ) to indicate how to evaluate the SQL
keywords and SQL special characters when processing the XML payload. T he XML SQL Comment s Handling parameter
gives you an option to specify the type of comments that need to be inspected or exempted during XML SQL Injection
detection.
You can deploy relaxations to avoid false positives. T he application firewall XML SQL check is performed on the payload of
the incoming requests, and attack strings are identified even if they are spread over multiple lines. T he check looks for SQL
Injection strings in the element and the at t ribut e values. You can apply relaxations to bypass security check inspection
under specified conditions. T he logs and statistics can help you identify needed relaxations.
An action is applied when the XML SQL Injection check detects an SQL Injection attack string in the request. T he following
actions are available for configuring an optimized XML SQL Injection protection for your application:
Block — If you enable block, the block action is triggered only if the input matches the XML SQL injection type
specification. For example, if SQLSplCharANDKeyword is configured as the XML SQL injection type, a request is not
blocked if it does not contain any key words, even if SQL special characters are detected in the payload. Such a request is
blocked if the XML SQL injection type is set to either SQLSplChar, or SQLSplCharORKeyword .
St at s — If enabled, the stats feature gathers statistics about violations and logs. An unexpected surge in the stats counter
might indicate that your application is under attack. If legitimate requests are getting blocked, you might have to revisit the
configuration to see if you need to configure new relaxation rules or modify the existing ones.
In addition to the block, log and stats actions, you can configure the following parameters for XML SQL Injection check:
Check f or XML SQL Wildcard Charact ers — Wild card characters can be used to broaden the selections of a structured
query language (SQL-SELECT ) statement. T hese wild card operators can be used in conjunction with LIKE and NOT LIKE
operators to compare a value to similar values. T he percent (%), and underscore (_) characters are frequently used as wild
cards. T he percent sign is analogous to the asterisk (*) wildcard character used with MS-DOS and to match zero, one, or
multiple characters in a field. T he underscore is similar to the MS-DOS question mark (?) wildcard character. It matches a
single number or character in an expression.
For example, you can use the following query to do a string search to find all customers whose names contain the D
character.
T he following example combines the operators to find any salary values that have 0 as the second and third character.
Different DBMS vendors have extended the wildcard characters by adding extra operators. T he NetScaler application
firewall can protect against attacks that are launched by injecting these wildcard characters. T he 5 default Wildcard
characters are percent (%), underscore (_), caret (^), opening square bracket ([), and closing square bracket (]). T his protection
applies to both HT ML and XML profiles.
T he default wildcard chars are a list of literals specified in the *Def ault Signat ures :
Wildcard characters in an attack can be PCRE, like [^A-F]. T he application firewall also supports PCRE wildcards, but the
literal wildcard chars above are sufficient to block most attacks.
Note
T he XML SQL wildca rd cha ra cte r check is different from the XML SQL s pe cia l cha ra cte r check. T his option must be used with
caution to avoid false positives.
SQL Special Charact er and Keyword — Both an SQL keyword and an SQL special character must be present in the
inspected location to trigger SQL violation. T his least restrictive setting is also the default setting.
SQL Special Charact er— At least one of the special characters must be present in the processed payload string to
trigger SQL violation.
SQL keyword — At least one of the specified SQL keywords must be present in the processed payload string to trigger
an SQL violation. Do not select this option without due consideration. T o avoid false positives, make sure that none of
the keywords are expected in the inputs.
SQL Special Charact er or Keyword — Either the keyword or the special character string must be present in the
payload to trigger the security check violation.
Tip
If you select the SQL Special Character option, the application firewall skips strings that do not contain any special characters. Since
most SQL servers do not process SQL commands that are not preceded by a special character, enabling this option can significantly
reduce the load on the application firewall and speed up processing without placing your protected web sites at risk.
SQL comment s handling — By default, the application firewall parses and checks all comments in XML data for injected
SQL commands. Many SQL servers ignore anything in a comment, even if preceded by an SQL special character. For faster
processing, if your XML SQL server ignores comments, you can configure the application firewall to skip comments when
examining requests for injected SQL. T he XML SQL comments handling options are:
ANSI — Skip ANSI-format SQL comments, which are normally used by UNIX-based SQL databases.
Nest ed — Skip nested SQL comments, which are normally used by Microsoft SQL Server.
ANSI/Nest ed — Skip comments that adhere to both the ANSI and nested SQL comment standards. Comments that
match only the ANSI standard, or only the nested standard, are still checked for injected SQL.
Check all Comment s — Check the entire request for injected SQL, without skipping anything. T his is the default setting.
Tip
In most cases, you should not choose the Nested or the ANSI/Nested option unless your back-end database runs on Microsoft SQL
Server. Most other types of SQL server software do not recognize nested comments. If nested comments appear in a request
directed to another type of SQL server, they might indicate an attempt to breach security on that server.
If your application requires you to bypass the XML SQL Injection inspection for a specific ELEMENT or AT T RIBUT E in the
XML payload, you can configure a relaxation rule. T he XML SQL Injection inspection relaxation rules have the following
parameters:
XMLSQLInjection: "PurchaseOrder_[0-9A-Za-z]{2,10}"
State: ENABLED
Not e: T he names are case sensitive. Duplicate entries are not allowed, but you can use capitalization of the names
and differences in location to create similar entries. For example, each of the following relaxation rules is unique:
Locat ion : You can specify the Location of the XML SQL Inspection exception in your XML payload. T he option
ELEMENT is selected by default. You can change it to AT T RIBUT E .
Comment : T his is an optional field. You can use up to a 255 character string to describe the purpose of this relaxation
Rule.
Warning
Regular expressions are powerful. Especially if you are not thoroughly familiar with PCRE-format regular expressions, double-check
any regular expressions you write. Make sure that they define exactly the name that you want to add as an exception, and nothing
else. Careless use of Regular Expressions can have results that you do not want, such as blocking access to web content that you
did not intend to block or allowing an attack that the XML SQL Injection inspection would otherwise have blocked.
To configure XML SQL Inject ion act ions and ot her paramet ers by using t he command line
In the command line interface, you can use either the set appf w profile command or the add appf w profile command
to configure the XML SQL Injection protections. You can enable the block, log, and stats action(s). Select the type of SQL
attack pattern (key words, wildcard characters, special strings) you want to detect in the payloads. Use the unset appf w
profile command to revert the configured settings back to their defaults. Each of the following commands sets only one
set appf w prof ile <name> -XMLSQLInject ionAct ion (([block ] [log ] [st at s ]) | [none ])
set appf w prof ile <name> -XMLSQLInject ionCheckSQLWildChars (ON |OF F )
set appf w prof ile <name> -XMLSQLInject ionT ype ([SQLKeyword ] | [SQLSplChar] |
[SQLSplCharANDKeyword ] | [SQLSplCharORKeyword ])
set appf w prof ile <name> -XMLSQLInject ionP arseComment s ([checkall] | [ansi|nest ed ] | [ansinest ed ])
To configure a SQL Inject ion relaxat ion rule by using t he command line
Use the bind or unbind command to add or delete relaxation rules, as follows:
bind appf w prof ile <name> -XMLSQLInject ion <string> [isRegex (REGEX | NOT REGEX )] [-locat ion ( ELEMENT |
AT T RIBUT E )] – comment <string> [-st at e ( ENABLED | DISABLED )]
unbind appf w prof ile <name> -XMLSQLInject ion <String>
Example:
> bind appfw profile test_profile -XMLSQLInjection "PurchaseOrder_[0-9A-Za-z]{2,15}" -isregex REGEX -location
AT T RIBUT E
In the configuration utility, you can configure the XML SQL Injection security check in the pane for the profile associated
with your application.
To configure or modif y t he XML SQL Inject ion check by using t he configurat ion ut ilit y
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Settings pane, click Securit y Checks .
T he security check table displays the currently configured action settings for all the security checks. You have 2
options for configuration:
a. If you just want to enable or disable Block , Log , and St at s actions for XML SQL Inject ion , you can select or
clear check boxes in the table, click OK , and then click Save and Close to close the Security Check pane.
b. If you want to configure additional options for this security check, double click XML SQL Inject ion , or select the
row and click Act ion Set t ings , to display the following options:
Check f or SQL Wildcard Charact ers — Consider SQL Wildcard characters in the payload to be attack patterns.
Check Request Cont aining — Type of SQL injection (SQLKeyword , SQLSplChar, SQLSplCharANDKeyword , or
SQLSplCharORKeyword ) to check.
SQL Comment s Handling — Type of comments (Check All Comment s , ANSI , Nest ed , or ANSI/Nest ed ) to check.
After changing any of the above settings, click OK to save the changes and return to the Security Checks table. You can
proceed to configure other security checks if needed. Click OK to save all the changes you have made in the Security
Checks section, and then click Save and Close to close the Security Check pane.
1. Navigate to Applicat ion F irewall > P rof iles , highlight the target profile, and click Edit .
2. In the Advanced Set t ings pane, click Relaxat ion Rules .
3. In the Relaxation Rules table, double-click the XML SQL Inject ion entry, or select it and click Edit .
4. In the XML SQL Inject ion Relaxat ion Rules dialogue box, perform Add , Edit , Delet e , Enable , or Disable operations
for relaxation rules.
To manage XML SQL Inject ion relaxat ion rules by using t he visualizer
For a consolidated view of all the relaxation rules, you can highlight the XML SQL Inject ion row in the Relaxation Rules
table, and click Visualizer. T he visualizer for deployed relaxations offers you the option to Add a new rule or Edit an
existing one. You can also Enable or Disable a group of rules by selecting a node and clicking the corresponding buttons in
the relaxation visualizer.
To view or cust omize t he SQL Inject ion pat t erns by using t he configurat ion ut ilit y
You can use the configuration utility to view or customize the SQL patterns.
T he default SQL patterns are specified in Applicat ion F irewall > Signat ures > *Def ault Signat ures . If you do not bind
any signature object to your profile, the default SQL patterns specified in the Default Signatures object will be used by the
profile for XML SQL Injection security check processing. T he rules and patterns in the Default Signatures object are read-
only. You cannot edit or modify them. If you want to modify or change these patterns, create a user-defined signature
object by making a copy of the Default Signatures object and changing the SQL patterns. Use the user-defined signature
object in the profile that processes the traffic for which you want to use these customized SQL patterns.
a. Navigate to Applicat ion firewall > Signat ures , select *Def ault Signat ures , and click Edit . T hen click Manage
SQL/XSS Pat t erns .
T he Manage SQL/XSS Paths table shows following four rows pertaining to SQL Injection:
b. Select a row and click Manage Element s to display the corresponding SQL patterns (keywords, special strings,
transformation rules or the wildcard characters) used by the application firewall SQL injection check.
To cust omize SQL Pat t erns: You can edit a user-defined signature object to customize the SQL key words, special
strings, and wildcard characters. You can add new entries or remove the existing ones. You can modify the transformation
rules for the SQL special strings.
a. Navigate to Applicat ion firewall > Signat ures , highlight the target user-defined signature, and click Edit . Click
Manage SQL/XSS Pat t erns to display the Manage SQL/XSS pat hs table.
i. Click Manage Element s , to Add , Edit or Remove the corresponding SQL element.
Warning
You must be very careful when removing or modifying any default SQL element, or deleting the SQL path to remove the entire row.
T he signature rules as well as the XML SQL Injection security check rely on these elements for detecting SQL Injection attacks to
protect your applications. Customizing the SQL patterns can make your application vulnerable to XML SQL attacks if the required
pattern is removed during editing.
When the log action is enabled, the XML SQL Inject ion security check violations are logged in the audit log as
AP P F W_XML_SQL violations. T he application firewall supports both Native and CEF log formats. You can also send the
logs to a remote syslog server.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the XML Cross-Site
Scripting violations:
> Shell
T he Citrix configuration utility includes a useful tool (Syslog Viewer) for analyzing the log messages. You have multiple
options for accessing the Syslog Viewer:
Navigate to Applicat ion F irewall > P rof iles , select the target profile, and click Securit y Checks . Highlight the XML
SQL Inject ion row and click Logs . When you access the logs directly from the XML SQL Injection check of the profile,
the configuration utility filters out the log messages and displays only the logs pertaining to these security check
violations.
You can also access the Syslog Viewer by navigating to Syst em > Audit ing . In the Audit Messages section, click the
Syslog messages link to display the Syslog Viewer, which displays all log messages, including other security check
violation logs. T his is useful for debugging when multiple security check violations might be triggered during request
processing.
Navigate to Applicat ion F irewall > P olicies > Audit ing . In the Audit Messages section, click the Syslog messages link
to display the Syslog Viewer, which displays all log messages, including other security check violation logs.
T he XML based Syslog Viewer provides various filter options for selecting only the log messages that are of interest to you.
To select log messages for the XML SQL Inject ion check, filter by selecting AP P F W in the dropdown options for
Module . T he Event T ype list offers a rich set of options to further refine your selection. For example, if you select the
AP P F W_XML_SQL check box and click the Apply button, only log messages pertaining to the XML SQL Inject ion
If you place the cursor in the row for a specific log message, multiple options, such as Module , Event T ype , Event ID , and
Client IP appear below the log message. You can select any of these options to highlight the corresponding information in
the log message.
When the stats action is enabled, the counter for the XML SQL Inject ion check is incremented when the application
firewall takes any action for this security check. T he statistics are collected for Rate and Total count for Traffic, Violations,
and Logs. T he size of an increment of the log counter can vary depending on the configured settings. For example, if the
block action is enabled, a request for a page that contains three XML SQL Inject ion violations increments the stats
counter by one, because the page is blocked as soon as the first violation is detected. However, if block is disabled,
processing the same request increments the statistics counter for violations and the logs by three, because each violation
generates a separate log message.
To display XML SQL Inject ion check st at ist ics by using t he command line
> sh appf w st at s
To display XML SQL Inject ion st at ist ics by using t he configurat ion ut ilit Y
If you use the wizard or the configuration utility, in the Modify XML Attachment Check dialog box, on the General tab you
can enable or disable the Block, Learn, Log, Statistics, and Learn actions:
If you use the command-line interface, you can enter the following command to configure the XML Attachment Check:
set appfw profile <name> -xmlAttachmentAction [block ] [learn ] [log ] [st at s ] [none ]
You must configure the other XML Attachment check settings in the configuration utility. In the Modify XML Attachment
Check dialog box, on the Checks tab, you can configure the following settings:
Maximum At t achment Size. Allow attachments that are no larger than the maximum attachment size you specify. T o
enable this option, first select the Enabled check box, and then type the maximum attachment size in bytes in the Size
text box.
At t achment Cont ent T ype. Allow attachments of the specified content type. T o enable this option, first select the
Enabled check box, and then enter a regular expression that matches the Content-T ype attribute of the attachments
that you want to allow.
You can type the URL expression directly in the text window. If you do so, you can use the Regex T okens menu to
enter a number of useful regular expressions at the cursor instead of typing them manually.
You can click Regex Editor to open the Add Regular Expression dialog box and use it to construct the URL expression.
If you use the wizard or the configuration utility, in the Modify Web Services Interoperability Check dialog box, on the
General tab you can enable or disable the Block, Log, Statistics, and Learn actions.
If you use the command-line interface, you can enter the following command to configure the Web Services
Interoperability check:
set appfw profile <name> -xmlWSIAction [block ] [log ] [learn ] [st at s ] [none ]
To configure individual Web Services Interoperability rules, you must use the configuration utility. On the Checks tab of the
Modify Web Services Interoperability Check dialog box, select a rule and click Enable or Disable to enable or disable the rule.
You can also click Open to open the Web Services Interoperability Detail message box for that rule. T he message box
displays read-only information about the rule. You cannot modify or make other configuration changes to any of these
rules.
T he WS-I check uses the rules listed in WS-I Basic Profile 1.0. WS-I delivers best practices for developing interoperable Web
Services solutions. WS-I checks are performed only on SOAP Messages.
Rule De s criptio n
When an ENVELOPE is a Fault, the soap:Fault element MUST NOT have element children other than faultcode, faultstring,
R1000
faultactor and detail.
R1001 When an ENVELOPE is a Fault, the element children of the soap:Fault element MUST be unqualified.
A RECEIVER MUST accept fault messages that have any number of qualified or unqualified attributes, including zero, appearing
R1003 on the detail element. T he namespace of qualified attributes can be anything other than the namespace of the qualified
document element Envelope.
When an ENVELOPE contains a faultcode element, the content of that element SHOULD be either one of the fault codes
R1004 defined in SOAP 1.1 (supplying additional information if necessary in the detail element), or a Qname whose namespace is
controlled by the fault's specifying authority (in that order of preference).
An ENVELOPE MUST NOT contain soap:encodingStyle attribute on any of the elements whose namespace is the same as the
R1005
namespace of the qualified document element Envelope.
R1006 An ENVELOPE MUST NOT contain soap:encodingStyle attributes on any element that is a child of soap:Body.
R1013 An ENVELOPE containing a soap:mustUnderstand attribute MUST only use the lexical forms 0 and 1.
R1015 A RECEIVER MUST generate a fault if they encounter an envelope whose document element is not soap:Envelope.
When an ENVELOPE contains a faultcode element the content of that element SHOULD NOT use of the SOAP 1.1 do t notation
R1031
to refine the meaning of the fault.
T he soap:Envelope, soap:Header, and soap:Body elements in an ENVELOPE MUST NOT have attributes in the same
R1032
namespace as that of the qualified document element Envelope
R1109 T he value of the SOAPAction HT T P header field in a HT T P request MESSAGE MUST be a quoted string.
R1111 An INSTANCE SHOULD use a 200 OK HT T P status code on a response message that contains an envelope that is not a fault.
R1126 An INSTANCE MUST return a 500 Internal Server Error HT T P status code if the response envelope is a Fault.
An ENVELOPE described with an rpc-literal binding MUST NOT have the xsi:nil attribute with a value of 1 or true on the part
R2211
accessors.
For one-way operations, an INSTANCE MUST NOT return a HT T P response that contains an envelope. Specifically, the HT T P
R2714
response entity-body must be empty.
An ENVELOPE described with an rpc-literal binding that is a response MUST have a wrapper element whose name is the
R2729
corresponding wsdl:operation name suffixed with the string Response.
An ENVELOPE described with an rpc-literal binding MUST place the part accessor elements for parameters and return value in
R2735
no namespace.
R2740 A wsdl:binding in a DESCRIPT ION SHOULD contain a soapbind:fault describing each known fault.
A HT T P request MESSAGE MUST contain a SOAPAction HT T P header field with a quoted value equal to the value of the
Rule De s criptio n
If you use the wizard or the configuration utility, in the Modify XML Message Validation Check dialog box, on the General
tab you can enable or disable the Block, Log, and Statistics actions.
If you use the command-line interface, you can enter the following command to configure the XML Message Validation
Check:
You must use the configuration utility to configure the other XML Validation check settings. In the Modify XML Message
Validation Check dialog box, on the Checks tab, you can configure the following settings:
XML Message Validat ion. Use one of the following options to validate the XML message:
SOAP Envelope. Validate only the SOAP envelope of XML messages.
WSDL. Validate XML messages by using an XML SOAP WSDL. If you choose WSDL validation, in the WSDL Object
drop-down list you must choose a WSDL. If you want to validate against a WSDL that has not already been imported
to the application firewall, you can click the Import button to open the Manage WSDL Imports dialog box and import
your WSDL. See "WSDL" for more information.
If you want to validate the entire URL, leave the Absolute radio button in the End Point Check button array
selected. If you want to validate only the portion of the URL after the host, select the Relative radio button.
If you want the application firewall to enforce the WSDL strictly, and not allow any additional XML headers not
defined in the WSDL, you must clear the Allow additional headers not defined in the WSDL check box.
Caution: If you uncheck the Allow Additional Headers not defined in the WSDL check box, and your WSDL does
not define all XML headers that your protected XML application or Web 2.0 application expects or that a client
sends, you may block legitimate access to your protected service.
XML Schema. Validate XML messages by using an XML schema. If you choose XML schema validation, in the XML
Schema Object drop-down list you must choose an XML schema. If you want to validate against an XML schema that
has not already been imported to the application firewall, you can click the Import button to open the Manage XML
Schema Imports dialog box and import your WSDL. See "WSDL" for more information.
Response Validat ion. By default, the application firewall does not attempt to validate responses. If you want to
validate responses from your protected application or Web 2.0 site, select the Validate Response check box. When you
do, the Reuse the XML Schema specified in request validation check box and the XML Schema Object drop-down list are
activated.
Check the Reuse XML Schema check box to use the schema you specified for request validation to do response
validation as well.
Note: If you check this check box, the XML Schema Object drop-down list is grayed out.
If you want to use a different XML schema for response validation, use the XML Schema Object drop-down list to
select or upload that XML schema .
If you use the wizard or the configuration utility, in the Modify XML SOAP Fault Filtering Check dialog box, on the General
tab you can enable or disable the Block, Log, and Statistics actions, and the Remove action, which removes SOAP faults
before forwarding the response to the user.
If you use the command-line interface, you can enter the following command to configure the XML SOAP Fault Filtering
Check:
You cannot configure exceptions to the XML SOAP Fault Filtering check. You can only enable or disable it.
Many application firewall filtering rules are designed to filter specific types of content. Because filtering rules that apply to
one type of content (such as HT ML) are often inappropriate when filtering a different type of content (such as images),
the application firewall attempts to determine the content type of requests and responses before it filters them. When a
web server or browser does not add a Content-Type header to a request or response, the application firewall applies a
default content type to the connection and filters the content accordingly.
T he default content type is normally "application/octet-stream", the most generic MIME/type definition.T his MIME/type is
appropriate for any type of content that a web server is likely to serve, but also does not provide much information to the
application firewall to allow it to choose appropriate filtering. If a protected web server on your network is configure to add
accurate content type headers to the content it serves, or serves only one type of content, you can create a profile for
that web server and assign a different default content type to it to improve both the speed and the accuracy of filtering.
You can also configure a list of allowed response content types for a specific profile. When this feature is configured, if the
application firewall filters a response that does not match one of the allowed content types, it blocks the response. After
upgrade from release 10.5 to 11.0, unknown content-types which are not in the default allowed content-type list do not
bind. You can add other content-types which you want to be allowed to the relaxed rules.
Note
You cannot include the "application/x-www-form-urlencoded" or "multipart/form-data" content types on the allowed response
content types list.
Example
T he following example sets the "text/html" content type as the default for the specified profile:
Example
T he following example unsets the default content type of "text/html" for the specified profile, allowing the type to revert
to "application/octet-stream":
Note
Always use last content-type header for processing and remove remaining content-type headers if any that ensures that the
backend server receives a request with only one content-type.
To block requests that can be bypassed, add an Application Firewall policy with rule as HT T P.REQ.HEADER ("content-
type").COUNT.GT (1)' and profile as appfw_block.
If a request is received without a Content-Type header or if the request has Content-Type header without any value, Application
Firewall applies the configured Re que s tCo nte ntT y pe value and processes the request accordingly.
Example
T he following example sets the "text/html" content type as the default for the specified profile:
Example
T he following example unsets the default content type of "text/html" for the specified profile, allowing the type to revert
to "application/octet-stream":
Example
T he following example adds the "text/shtml" content type to the allowed content types list for the specified profile:
Example
T he following example removes the "text/shtml" content type from the allowed content types list for the specified profile:
Note: You can include any valid MIME type on the allowed contents type list. Since many types of document can
contain active content and therefore could potentially contain malicious content, you should exercise caution when
adding MIME types to this list.
3. In the Comments text box, add an optional comment that describes the reason for adding this particular MIME type
to the allowed contents type list.
4. Click Create or OK to save your changes.
8. Click Close to close the Manage Allowed Content T ypes dialog box and return to the Settings tab.
9. Click OK to save your changes.
T he four application firewall built-in profiles provide simple protection for applications and web sites that either do not
require protection, or that should not be directly accessed by users at all. T hese profile types are:
AP P F W_BYP ASS. Skips all application firewall filtering and sends the unmodified traffic to the protected application or
web site, or to the client.
AP P F W_RESET . Resets the connection, requiring that the client re-establish his or her session by visiting a designated
start page.
AP P F W_DROP . Drops all traffic to or from the protected application or web site, and sends no response of any kind to
the client.
AP P F W_BLOCK. Blocks traffic to or from the protected application or web site.
You use the built-in profiles exactly as you do user-defined profiles, by configuring a policy that selects the traffic to which
you want to apply the profile and then associating the profile with your policy. Since you do not have to configure a built-in
policy, it provides a quick way to allow or block specified types of traffic or traffic that is sent to specific applications or
web sites.
User-defined profiles are profiles that are build and configured by users. Unlike the default profiles, you must configure a
user-defined profile before it will be of use filtering traffic to and from your protected applications.
T he application firewall has a number of security checks, all of which can be enabled or disabled, and configured in a number
of ways in each profile. Each profile also has a number of settings that control how it handles different types of content.
Finally, rather than manually configuring all of the security checks, you can enable and configure the learning feature. T his
feature observes normal traffic to your protected web sites for a period of time, and uses those observations to provide
you with a tailored list of recommended exceptions (relaxations) to some security checks, and additional rules for other
security checks.
During initial configuration, whether by using the Application Firewall Wizard or manually, you normally create one general
purpose profile to protect all content on your web sites that is not covered by a more specific profile. After that, you can
create as many specific profiles as you want to protect more specialized content.
Bound signat ure. Displays the signatures object that is bound to the profile in the previous column, if any.
P olicies. Displays the application firewall policy that invokes the profile in the leftmost column of that row, if any.
Comment s. Displays the comment associated with the profile in the leftmost column of that row, if any.
P rofile T ype. Displays the type of profile. Types are Built-In, HT ML, XML, and Web 2.0.
Above the table is a row of buttons and a drop-down list that allow you to create, configure, delete, and view information
about your profiles:
Creating a profile by using the configuration utility requires that you specify only two options. You specify basic or
advanced defaults, the default configuration for the various security checks and settings that are part of a profile, and
choose the profile type to match the type of content that the profile is intended to protect. You can also, optionally, add a
comment. After you create the profile, you must then configure it by selecting it in the data pane, and then clicking Edit.
If you plan to use the learning feature or to enable and configure a large number of advanced protections, you should
choose advanced defaults. In particular, if you plan to configure either of the SQL injection checks, either of the cross-site
scripting checks, any check that provides protection against Web form attacks, or the cookie consistency check, you should
plan to use the learning feature. Unless you include the proper exceptions for your protected Web sites when configuring
these checks, they can block legitimate traffic. Anticipating all of the necessary exceptions without creating any that are
too broad is difficult. T he learning feature makes this task much easier. Otherwise, basic defaults are quick and should
provide the protection that your web applications need.
T here are also a few restrictions on the name that you can give to a profile. A profile name cannot be the same as the
name assigned to any other profile or action in any feature on the NetScaler appliance. Certain action or profile names are
assigned to built-in actions or profiles, and can never be used for user profiles. A complete list of disallowed names can be
found in the Application Firewall ProfileSupplemental Information. If you attempt to create a profile with a name that has
already been used for an action or a profile, an error message is displayed and the profile is not created.
Example
T he following example adds a profile named pr-basic, with basic defaults, and assigns a profile type of HTML. T his is the
appropriate initial configuration for a profile to protect an HT ML Web site.
add appfw profile pr-basic -defaults basic -comment "Simple profile for web sites."
set appfw profile pr-basic -type HTML
Creating an application firewall profile requires that you specify only a few configuration details.
After you have configured the security checks, you can also configure a number of other settings that control the behavior,
not of a single security check, but the application firewall feature. T he default configuration is sufficient to protect most
web sites, but you should review them to make sure that they are right for your protected web sites.
For more information about the application firewall security checks, see "Advanced Protections."
save ns config
Example
T he following example shows how to enable blocking for the HT ML SQL Injection and HT ML Cross-Site Scripting checks in
a profile named pr-basic. T his command enables blocking for those actions while making no other changes to the profile.
set appfw profile pr-basic -crossSiteScriptingAction block
-SQLInjectionAction block
Note: When you change the profile type, you lose all configuration settings and learned relaxations or rules for the
features that the new profile type does not support. For example, if you change the profile type from Web 2.0 to XML, you
lose any configuration options for Start URL, Form Field Consistency Check, and the other HT ML-specific security checks.
T he configuration for any options that is supported by both the old and the new profile types remains unchanged.
Example
T he following example changes the type of a profile named pr-basic, from HTML to HTML XML, which is equivalent to the
Web 2.0 type in the configuration utility.
T he option to export the entire profile configuration and then import it into another appliance can be useful in various use
cases. For example, you might want to configure an application firewall profile in a test bed set-up to test and validate that
it is working as expected. Once you are satisfied, you can export the profile and import the profile configuration to your
production NetScaler appliances. T his functionality is also useful for backing up your configuration. You can export the
profile before making changes, so that you can easily roll back the configuration to a known state if necessary.
Note
Application firewall profiles that are exported and archived from one build cannot be restored to a system running a different build,
because changes introduced in the newer releases can lead to compatibility issues. If you attempt to restore an archived profile to a
different build than the one from which it was exported, an error message is logged in ns.log.
T he export and import profile functionality is available in both the configuration utility (GUI) and the command line interface
(CLI). T he configuration utility is recommended, because it offers easy to use Act ion options. With a click of a button you
can Export or Import the entire configuration of a profile.
If you use CLI to export a profile, you must archive the configuration and then export it. To import a profile, you must
import the archive into the NetScaler appliance and then execute the rest ore command to extract the configuration. T he
following set of CLI commands can be used for exporting, importing and managing the profile configurations.
St ep 3: Use a file transfer utility such as scp to transfer the exported archive file from NetScaler appliance A to the target
NetScaler appliance.
St ep 4 : Execute the import command to import the archived file. You can import the archive from your NetScaler’s local file
system, or you can use HT T P or HT T PS protocol to import the archive from a server by using the URL.
St ep 5: Execute the restore command to restore the profile configuration from the imported archive
To export an applicat ion firewall profile by using t he command line int erf ace
First, archive the profile’s configuration, and then export the archive to a target location. At the command prompt, type
the following commands:
where:
Execution of the above command creates 2 instances of the archive file. One in /var/tmp folder and another in the
/var/archive/appfw folder.
where:
<archiveName> is the name of the archive to export. (T he same name as in the previous command.
<target> is a file path starting with local: as the prefix, followed by <archiveName>.
Execution of the export command saves the exported archive file on the file system of your NetScaler appliance in the
/var/tmp folder.
Examples:
After the above two commands are executed, the /var/tmp folder contains the archived_test_pr file and the exported
copy, dutA_test_pr, which are identical in size. From the CLI, you can drop into the shell to navigate to the folder to verify
that these files are there.
After you have successfully scp’d the archived file from the source appliance to the target appliance, you are ready to
import the profile’s archive, and then execute the rest ore command to replicate the profile’s configuration on the target
appliance.
Log onto the target appliance. Drop into the shell and cd to the /var/tmp folder to verify that the size of the scp’d file on
this appliance matches the size of the original archived file on the source appliance. Exit the shell to return to the command
line.
where
<src> is the location of the archive file after it has been transferred from the source appliance on which it was created.
You can use a local file system and file name. If you have placed the archive on a server, you can use a URL to import the
archived file. If the path or file name contains spaces, enclose the URL in straight double quotation marks.
<name> is the name of the archive file to be imported.
<string> is an optional description of the purpose of the Archive.
Examples:
T his example restores the test_pr profile along with all bound objects (such as signatures, html error page, relaxation rules
and so on) on the target NetScaler appliance.
You can use the following CLI commands to access man pages for additional details.
T he configuration utility (GUI) is easier to use than the CLI. T he utility performs both archive and export operations when
you click Export . Similarly it executes both import and restore when you click Import . T he configuration utility can access
the local file system of the computer from which you access the utility. You can export a copy of the archive and save it on
your local computer. You can then import this copy directly in the target appliance without having to manually transfer the
archive file from one appliance to the other(s).
1. Navigate to Conf igurat ion > Securit y > Applicat ion F irewall > P rof iles .
2. In the details pane, select a profile to export. Click Act ions and select Export to download and save a copy in your
computer’s local file system.
1. Navigate to Conf igurat ion > Securit y > Applicat ion F irewall > P rof iles .
2. In the details pane, click Act ions and select Import . In the Import Application firewall Profile pane, the Import
From* selection box gives you 2 options:
URL: You can choose to import an archive by specifying a URL . When this option is selected, you must provide
an absolute path for the archived file in the URL input box.
F ile: You can choose to import an archive from the local F ile . When this option is selected, a Local F ile
selection field is displayed. You can browse your computer’s local files to select the target archive file.
Click Creat e to import the specified archive. Successful completion of the import operation creates the profile
configuration on the target appliance.
Highlights
You can replicate the entire configuration (including all import objects as well as configured relaxation rules for the
profile) on multiple appliances, without needing to repeat configuration steps, by using export and import profile
functionality.
T he imported objects, such as signatures, WSDL, Schema, error page and so on, are included in the archived tar file and
replicated on the target appliance.
Customized field types are included in the archived tar file and replicated on the target appliance.
T he policy bindings of the archived profile are not replicated when the configuration is restored. You must configure the
policy and bind it to the profile after importing the profile to the appliance.
T he name of the archive file can be up to 31 character long. As with profile names, an archive name must begin with an
alphanumeric character or underscore and contain only alphanumeric and underscore (_), number (#), period (.), space ( ),
colon (:), at (@), equals (=) or hyphen (-) characters.
Comments associated with the archive should be descriptive enough to convey the purpose of the archived
configuration. T he maximum allowed length for a comment is 255 characters.
T he “clear config – force basic” command does not remove the archived profiles.
T he import and export profile functionality is supported in high availability (HA) deployments.
You perform two different types of activities when using the learning feature. First, you enable and configure the feature
to use it. You can use learning on all traffic to your protected web applications, or you can configure a list of IPs (called the
Add Trusted Learning Clients list) from which the learning feature should generate recommendations. Second, after the
feature has been enabled and has processed a certain amount of traffic to your protected web sites, you review the list of
suggested rules and relaxations (learned rules) and mark each with one of the following designations:
Edit & Deploy. T he rule is pulled into the Edit dialog box so that you can modify it, and the modified form is deployed.
Deploy. T he unmodified learned rule is placed on the list of rules or relaxations for this security check.
Skip. T he learned rule is placed on a list of rules or relaxations that are not deployed. T he learned rule is removed when
skipped. However, as they are not added to relaxations, they might get learned again.
Learning is not performed only when relaxations are in place, except for field format rules. When rules are skipped, they are
only removed from learned database. As relaxations are not added, they might get learned again. When rules are deployed,
they are removed from learned database and also relaxations are added for the rules. As relaxations are added, they would
not be learned again. For fieldformat protection, learning is performed irrespective of relaxations.
Although you can use the command line interface for basic configuration of the learning feature, the feature is designed
primarily for configuration through the Application Firewall wizard or the configuration utility. You can perform only limited
configuration of the learning feature by using the command line.
T he wizard integrates configuration of learning features with configuration of the application firewall as a whole, and is
therefore the easiest method for configuring this feature on a new NetScaler appliance or when managing a simple
application firewall configuration. T he configuration utility visualizer and manual interface both provide direct access to all
learned rules for all security checks, and are therefore often preferable when you must review learned rules for a large
number of security checks.
If learning stops because the database has reached its size limit, you can restart learning either by reviewing the existing
learned rules and relaxations or by resetting the learning data. After learned rules or relaxations are approved or ignored,
they are removed from the database. After you reset the learning data, all existing learning data is removed from the
database and it is reset to its minimum size. When the database falls below 20 MB in size, learning restarts automatically.
Specify the application firewall profile to be configured and, for each security check that you want to include in that profile,
specify the minimum threshold or the percent threshold. T he minimum threshold is an integer representing the minimum
number of user sessions that the application firewall must process before it learns a rule or relaxation (default: 1). T he
percent threshold is an integer representing the percentage of user sessions in which the application firewall must observe
a particular pattern (URL, cookie, field, attachment, or rule violation) before it learns a rule or relaxation (default: 0). Use the
following commands:
Example
T he following example enables and configures the learning settings in the profile pr-basic for the HT ML SQL Injection
security check. T his is an appropriate initial test bed learning configuration, where you have complete control over the
traffic that is sent to the application firewall.
To remove any custom configuration of the learning settings for the specified profile and security check, and return the
learning settings to their defaults, at the command prompt type the following commands:
P ercent age of t imes t hreshold. Depending on which security check’s learning settings you are configuring, the
percentage of times threshold might refer to the percentage of total observed user sessions that violated the
security check, the percentage of requests, or the percentage of times a form field matched a particular field type,
before a learned relaxation is generated. Default: 0
5. T o remove all learned data and reset the learning feature, so that it must start its observations again from the beginning,
click Remove All Learned Data.
Note: T his button removes only learned recommendations that have not been reviewed and either approved or skipped.
It does not remove learned relaxations that have been accepted and deployed.
6. T o restrict the learning engine to traffic from a specific set of IPs, click T rusted Learning Clients, and add the IP
addresses that you want to use to the list.
1. T o add an IP address or IP address range to the T rusted Learning Clients list, click Add.
2. In the Add T rusted Learning Clients dialog box, T rusted Clients IP list box, type the IP address or an IP address range in
CIDR format.
3. In the Comments text area, type a comment that describes this IP address or range.
4. Click Create to add your new IP address or range to the list.
5. T o modify an existing IP address or range, click the IP address or range, and then click Open. Except for the name, the
dialog box that appears is identical to the Add T rusted Learning Clients dialog box.
6. T o disable or enable an IP address or range, but leave it on the list, click the IP address or range, and then click Disable
or Enable, as appropriate.
7. T o remove an IP address or range completely, click the IP address or range, and then click Remove.
7. Click Close to return to the Configure Application Firewall Profile dialog box.
8. Click Close to close the Configure Application Firewall Profile dialog box, and return to the Application Firewall Profile
screen.
To remove the relaxation from the list without deploying it, click Skip.
To modify and then accept the learned relaxation, click Edit & Deploy, edit the relaxation regular expression, and
then click OK.
To remove the modification from the list without deploying it, click Skip.
Instead of using static values, to configure the application firewall's security checks and settings, you can now use standard
NetScaler named variables. By creating variables, you can more easily export and then import configurations to new
NetScaler appliances, or update existing NetScaler appliances from a single set of configuration files. T his simplifies updates
when you use a test bed setup to develop a complex application firewall configuration that is tuned for your local network
and servers and then transfer that configuration to your production NetScaler appliances.
You create application firewall configuration variables in the same manner as you do any other NetScaler named variables,
following standard NetScaler conventions. To create a named expression variable by using the configuration utility, you use
the "Add Expression dialog box." To create a named expression variable by using the NetScaler command line, you use the
add expression command followed by the appropriate parameter.
T he following URLs and expressions can be configured with variables instead of static values:
To use a variable in the configuration, you enclose the variable name between two at (@) symbols and then use it exactly as
you would the static value that it replaces. For example, if you are configuring the Deny URL check by using the
configuration utility and want to add the named expression variable myDenyURL to the configuration, you would type
@myDenyURL@ into the Add Deny URL dialog box, Deny URL text area. To do the same task by using the NetScaler
command line, you would type add appfw profile <name> -denyURLAction @myDenyURL@.
T he NetScaler operating system supports direct entry of characters in the printable ASCII character set only— characters
with hexadecimal codes between HEX 20 (ASCII 32) and HEX 7E (ASCII 127). To include a character with a code outside
that range in your application firewall configuration, you must enter its UT F-8 hexadecimal code as a PCRE regular
A number of character types require encoding using a PCRE regular expression if you include them in your application
firewall configuration as a URL, form field name, or Safe Object expression. T hey include:
Upper-ASCII charact ers. Characters with encodings from HEX 7F (ASCII 128) to HEX FF (ASCII 255). Depending on the
character map used, these encodings can refer to control codes, ASCII characters with accents or other modifications,
non-Latin alphabet characters, and symbols not included in the basic ASCII set. T hese characters can appear in URLs,
form field names, and safe object expressions.
Double-Byt e charact ers. Characters with encodings that use two 8-byte words. Double-byte characters are used
primarily for representing Chinese, Japanese, and Korean text in electronic format. T hese characters can appear in URLs,
form field names, and safe object expressions.
ASCII cont rol charact ers. Non-printable characters used to send commands to a printer. All ASCII characters with
hexadecimal codes less than HEX 20 (ASCII 32) fall into this category. T hese characters should never appear in a URL or
form field name, however, and would rarely if ever appear in a safe object expression.
T he NetScaler appliance does not support the entire UT F-8 character set, but only the characters found in the following
eight charsets:
English US (ISO-8859-1). Although the label reads, “English US,” the application firewall supports all characters in the
ISO-8859-1 character set, also called the Latin-1 character set. T his character set fully represents most modern western
European languages and represents all but a few uncommon characters in the rest.
Chinese T radit ional (Big5). T he application firewall supports all characters in the BIG5 character set, which includes all
of the Traditional Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in Hong
Kong, Macau, Taiwan, and by many people of Chinese ethnic heritage who live outside of mainland China.
Chinese Simplified (GB2312). T he application firewall supports all characters in the GB2312 character set, which
includes all of the Simplified Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in
mainland China.
Japanese (SJIS). T he application firewall supports all characters in the Shift-JIS (SJIS) character set, which includes most
characters (ideographs) commonly used in modern Japanese.
Japanese (EUC-JP ). T he application firewall supports all characters in the EUC-JP character set, which includes all
characters (ideographs) commonly used in modern Japanese.
Korean (EUC-KR). T he application firewall supports all characters in the EUC-KR character set, which includes all
characters (ideographs) commonly used in modern Korean.
T urkish (ISO-8859-9). T he application firewall supports all characters in the ISO-8859-9 character set, which includes all
letters used in modern Turkish.
Unicode (UT F -8). T he application firewall supports certain additional characters in the UT F-8 character set, including
those used in modern Russian.
When configuring the application firewall, you enter all non-ASCII characters as PCRE-format regular expressions using the
hexadecimal code assigned to that character in the UT F-8 specification. Symbols and characters within the normal ASCII
character set, which are assigned single, two-digit codes in that character set, are assigned the same codes in the UT F-8
T he syntax you use to represent these UT F-8 codes in the application firewall configuration is “\xNN” for ASCII characters;
“\xNN\xNN” for non-ASCII characters used in English, Russian, and Turkish; and “\xNN\xNN\xNN” for characters used in
Chinese, Japanese, and Korean. For example, if you want to represent a ! in an application firewall regular expression as a
UT F-8 character, you would type \x21. If you want to include an á, you would type \xC3\xA1.
Note: Normally you do not need to represent ASCII characters in UT F-8 format, but when those characters might confuse
a web browser or an underlying operating system, you can use the character’s UT F-8 representation to avoid this
confusion. For example, if a URL contains a space, you might want to encode the space as \x20 to avoid confusing certain
browsers and web server software.
Below are examples of URLs, form field names, and safe object expressions that contain non-ASCII characters that must be
entered as PCRE-format regular expressions to be included in the application firewall configuration. Each example shows
the actual URL, field name, or expression string first, followed by a PCRE-format regular expression for it.
You can find a number of tables that include the entire Unicode character set and matching UT F-8 encodings on the
Internet. A useful web site that contains this information is located at the following URL:
http://www.utf8-chartable.de/unicode-utf8-table.pl
For the characters in the table on this web site to display correctly, you must have an appropriate Unicode font installed on
your computer. If you do not, the visual display of the character may be in error. Even if you do not have an appropriate
font installed to display a character, however, the description and the UT F-8 and UT F-16 codes on this set of web pages will
be correct.
Note: If an expression consists only of an exclamation point with nothing following, the exclamation point is treated as a
literal character, not syntax indicating an inverted expression.
T he following application firewall commands support inverted PCRE expressions:
Note: If the security check contains an isRegex flag or check box, it must be set to YES or checked to enable regular
expressions in the field. Otherwise the contents of that field are treated as literal and no regular expressions (inverted or
not) are parsed.
T he following names are assigned to built-in actions and profiles on the NetScaler appliance, and cannot be used as names
for a user-created application firewall profile.
AGRESSIVE
ALLOW
BASIC
CLIENT AUT H
COMPRESS
CSSMINIFY
DEFLAT E
DENY
DNS-NOP
DROP
GZIP
HT MLMINIFY
IMGOPT IMIZE
JSMINIFY
MODERAT E
NOCLIENT AUT H
NOCOMPRESS
NONE
NOOP
NOREWRIT E
RESET
SET ASLEARNNSLOG_ACT
Example
T he following example creates a policy label named policylbl1.
bind appfw policylabel <labelName> <policyName> <priority> [<gotoPriorityExpression>] [-invoke (<labelT ype>
<labelName>) ]
save ns config
Example
T he following example binds the policy policy1 to the policy label policylbl1 with a priority of 1.
Firewall policies can be complex because the policy rule can consist of multiple expressions in the NetScaler expressions
language, which is a full-fledged object oriented programming language capable of defining with extreme precision exactly
which connections to filter. Because firewall policies operate within the context of the application firewall, they must meet
certain criteria that are connected to how the application firewall functions and what traffic is appropriately filtered by it.
As long as you keep these criteria in mind, however, firewall policies are similar to policies for other NetScaler features. T he
instructions here do not attempt to cover all aspects of writing firewall policies, but only provide an introduction to policies
and cover those criteria that are unique to the application firewall.
Auditing policies are simple because the policy rule is always ns_true. You need only specify the log server that you want to
send logs to, the logging levels that you want to use, and a few other criteria that are explained in detail.
Firewall policies enable you to assign different filtering rules to different types of web content. Not all web content is alike.
A simple web site that uses no complex scripting and accesses and handles no private data might require only the level of
protection provided by a profile created with basic defaults. Web content that contains JavaScript-enhanced web forms or
accesses an SQL database probably requires more tailored protection. You can create a different profile to filter that
content and create a separate firewall policy that can determine which requests are attempting to access that content.
You then associate the policy expression with a profile you created and globally bind the policy to put it into effect.
T he application firewall processes only HT T P connections, and therefore uses a subset of the overall NetScaler expressions
language. T he information here is limited to topics and examples that are likely to be useful when configuring the
application firewall. Following are links to additional information and procedures for firewall policies:
For procedures that explain how to create and configure a policy, see Creating and Configuring Application Firewall
Policies.
For a procedure that explains in detail how to create a policy rule (expression), see T o create or configure an Application
Firewall rule (expression).
For a procedure that explains how to use the Add Expression dialog box to create a policy rule, see T o add a firewall rule
(expression) by using the Add Expression dialog box.
For a procedure that explains how to view the current bindings for a policy, see Viewing a Firewall Policy's Bindings.
For procedures that explain how to bind an application firewall policy, see Binding Application Firewall Policies.
For detailed information about the NetScaler expressions language, see Policies and Expressions.
Note
Application firewall evaluates the policies based on the configured priority and goto expressions. At the end of the policy
evaluation, the last policy that evaluates to true is used and the security configuration of the corresponding profile is invoked for
processing the request.
Policy_1 is a generic policy with Expression=ns_true and has a corresponding profile_1 which is a basic profile. T he priority is set
to 100.
Policy_2 is more specific with Expression=HT T P.REQ.URL.CONT AINS(“XYZ”) and has a corresponding profile_2 which is an
advance profile. T he GoT o Expression is set to NEXT and the priority is set to 95 which is a higher priority compared to Policy_1.
In this scenario, if the target string "XYZ" is detected in the URL of the processed request, Policy_2 match is triggered as it has a
higher priority even though Policy_1 is also a match. However, as per the GoT o expression configuration of Policy_2, the policy
evaluation continues and the next policy Policy_1 is also processed. At the end of the policy evaluation, Policy_1 evaluates as true
and the basic security checks configured in Profile_1 are invoked.
If the Policy_2 is modified and the GoT o Expression is changed from NEXT to END , the processed request that has the target string
"XYZ", triggers the Policy_2 match due to priority consideration and as per the GoT o expression configuration, the policy evaluation
Policy evaluation is completed in one pass. Once the policy evaluation is completed for the request and the corresponding profile
actions are invoked, the request does not go through another round of policy evaluation.
T he policy rule consists of one or more expressions in the NetScaler expressions language. T he NetScaler expressions
syntax is a powerful, object-oriented programming language that enables you to precisely designate the traffic that you
want to process with a specific profile. For users who are not completely familiar with the NetScaler expressions language
syntax, or who prefer to configure their NetScaler appliance by using a web-based interface, the configuration utility
provides two tools: the Prefix menu and the Add Expression dialog box. Both help you to write expressions that select
exactly the traffic that you want to process. Experienced users who are thoroughly familiar with the syntax may prefer to
use the NetScaler command line to configure their NetScaler appliances.
Note: In addition to the default expressions syntax, for backward compatibility the NetScaler operating system supports
the NetScaler classic expressions syntax on NetScaler Classic and nCore appliances and virtual appliances. Classic
expressions are not supported on NetScaler Cluster appliances and virtual appliances. Current NetScaler users who want to
migrate existing configurations to the NetScaler Cluster must migrate any policies that contain classic expressions to the
default expressions syntax.
For detailed information about the NetScaler expressions languages, see "Policies and Expressions."
You can create a firewall policy by using the configuration utility or the NetScaler command line.
Example
T he following example adds a policy named pl-blog, with a rule that intercepts all traffic to or from the host
blog.example.com, and associates that policy with the profile pr-blog. T his is an appropriate policy to protect a blog hosted
on a specific hostname.
4. Select the profile that you want to associate with this policy from the Profile drop-down list. You can create a new
profile to associate with your policy by clicking New, and you can modify an existing profile by clicking Modify.
5. In the Expression text area, create a rule for your policy.
You can type a rule directly into the text area.
You can click Prefix to select the first term for your rule, and follow the prompts. See "T o Create an Application
Firewall Rule (Expression)" for a complete description of this process.
You can click Add to open the Add Expression dialog box, and use it to construct the rule. See "T he Add Expression
Dialog Box" for a complete description of this process.
6. Click Create or OK, and then click Close.
T he policy rule, also called the expression, defines the web traffic that the application firewall filters by using the profile
associated with the policy. Like other NetScaler policy rules (or expressions), application firewall rules use NetScaler
expressions syntax. T his syntax is powerful, flexible, and extensible. It is too complex to describe completely in this set of
instructions. You can use the following procedure to create a simple firewall policy rule, or you can read it as an overview of
the policy creation process.
1. If you have not already done so, navigate to the appropriate location in the Application Firewall wizard or the NetScaler
configuration utility to create your policy rule:
If you are configuring a policy in the Application Firewall wizard, in the navigation pane, click Application Firewall, then
in the details pane click Application Firewall Wizard, and then navigate to the Specify Rule screen.
If you are configuring a policy manually, in the navigation pane, expand Application Firewall, then Policies, and then
Firewall. In the details pane, to create a new policy, click Add. T o modify an existing policy, select the policy, and then
click Open.
2. On the Specify Rule screen, the Create Application Firewall Profile dialog box, or the Configure Application Firewall
Profile dialog box, click Prefix, and then choose the prefix for your expression from the drop-down list. Your choices are:
HT T P . T he HT T P protocol. Choose this if you want to examine some aspect of the request that pertains to the
HT T P protocol.
SYS. T he protected Web site(s). Choose this if you want to examine some aspect of the request that pertains to the
recipient of the request.
CLIENT . T he computer that sent the request. Choose this if you want to examine some aspect of the sender of the
request.
SERVER. T he computer to which the request was sent. Choose this if you want to examine some aspect of the
recipient of the request.
After you choose a prefix, the application firewall displays a two-part prompt window that displays the possible next
choices at the top, and a brief explanation of what the selected choice means at the bottom.
When you have decided which term you want, double-click it to insert it into the Expression window.
4. T ype a period after the term you just chose. You are then prompted to choose your next term, as described in the
HTTP.REQ.HEADER("Host").EQ("shopping.example.com")
For shopping.example.com, substitute the name of the web host that you want to match.
Specific web f older or direct ory. To match traffic from a particular folder or directory on a Web host:
HTTP.REQ.URL.STARTSWITH("https//www.example.com/folder")
For www.example.com, substitute the name of the web host. For folder, substitute the folder or path to the content
that you want to match. For example, if your shopping cart is in a folder called /solutions/orders, you substitute that
string for folder.
Specific t ype of cont ent : GIF images. To match GIF format images:
HTTP.REQ.URL.ENDSWITH(".gif")
To match other format images, substitute another string in place of .gif.
Specific t ype of cont ent : script s. To match all CGI scripts located in the CGI-BIN directory:
HTTP.REQ.URL.STARTSWITH("https//www.example.com/CGI-BIN")
To match all JavaScripts with .js extensions:
HTTP.REQ.URL.ENDSWITH(".js")
For more information about creating policy expressions, see "Policies and Expressions."
Note: If you use the command line to configure a policy, remember to escape any double quotation marks within
NetScaler expressions. For example, the following expression is correct if entered in the configuration utility:
HTTP.REQ.HEADER("Host").EQ("shopping.example.com")
If entered at the command line, however, you must type this instead:
HTTP.REQ.HEADER(\"Host\").EQ(\"shopping.example.com\")
T he Add Expression dialog box (also referred to as the Expression Editor) helps users who are not familiar with the
NetScaler expressions language to construct a policy that matches the traffic that they want to filter.
1. If you have not already done so, navigate to the appropriate location in the Application Firewall wizard or the NetScaler
configuration utility:
If you are configuring a policy in the Application Firewall wizard, in the navigation pane, click Application Firewall, then
in the details pane click Application Firewall Wizard, and then navigate to the Specify Rule screen.
If you are configuring a policy manually, in the navigation pane, expand Application Firewall, then Policies, and then
Firewall. In the details pane, to create a new policy, click Add. T o modify an existing policy, select the policy, and then
click Open.
2. On the Specify Rule screen, in the Create Application Firewall Profile dialog box, or in the Configure Application Firewall
Profile dialog box, click Add.
When you bind a policy, you assign a priority to it. T he priority determines the order in which the policies you define are
evaluated. You can set the priority to any positive integer. In the NetScaler OS, policy priorities work in reverse order - the
higher the number, the lower the priority.
Because the application firewall feature implements only the first policy that a request matches, not any additional policies
that it might also match, policy priority is important for achieving the results that you intend. If you give your first policy a
low priority (such as 1000), you configure the application firewall to perform it only if other policies with a higher priority do
not match a request. If you give your first policy a high priority (such as 1), you configure the application firewall to perform
it first, and skip any other policies that might also match. You can leave yourself plenty of room to add other policies in any
order, without having to reassign priorities, by setting priorities with intervals of 50 or 100 between each policy when you
bind your policies.
For more information about binding policies on the NetScaler appliance, see "Policies and Expressions."
Example
T he following example binds the policy named pl-blog and assigns it a priority of 10.
1. Navigate to Security > Application Firewall > Policies > Firewall Policies
2. In the details pane, select the policy that you want to check, and then click Show Bindings. T he Binding Details for Policy:
Policy message box is displayed, with a list of bindings for the selected policy.
3. Click Close.
Web application security and modern web sites are complex. In a number of scenarios, a NetScaler policy might cause the
application firewall to behave differently in certain situations than a user who is familiar with policies would normally expect.
Following are a number of cases where the application firewall may behave in an unexpected fashion.
Request with a missing HTTP Host header and an absolute URL. When a user sends a request, in the majority of
cases the request URL is relative. T hat is, it takes as its starting point the Referer URL, the URL where the user's browser
is located when it sends the request. If a request is sent without a Host header, and with a relative URL, the request is
normally blocked both because it violates the HT T P specification and because a request that fails to specify the host
could under some circumstances constitute an attack. If a request is sent with an absolute URL, however, even if the
Host header is missing, the request bypasses the application firewall and is forwarded to the web server. Although such a
request violates the HT T P specification, it poses no possible threat because an absolute URL contains the host.
To create an auditing policy, you must first create either an NSLOG server or a SYSLOG server. After specifying the server,
you create the policy and specify the type of log and the server to which logs are sent.
You can create two different types of auditing server: an NSLOG server or a SYSLOG server. T he command names are
different, but the parameters for the commands are the same.
To create an auditing server, at the NetScaler command prompt, type the following commands:
add audit syslogAction <name> <serverIP> [-serverPort <port>] -logLevel <logLevel> ... [-dateFormat ( MMDDYYYY |
DDMMYYYY )] [-logFacility <logFacility>] [-tcp ( NONE | ALL )] [-acl ( ENABLED | DISABLED )] [-timeZone ( GMT_TIME |
LOCAL_TIME )] [-userDefinedAuditlog ( YES | NO )] [-appflowExport ( ENABLED | DISABLED )]
save ns config
Example
T he following example creates a syslog server named syslog1 at IP 10.124.67.91, with loglevels of emergency, critical, and
warning, log facility set to LOCAL1, that logs all TCP connections:
add audit syslogAction syslog1 10.124.67.91 -logLevel emergency critical warning -logFacility
LOCAL1 -tcp ALL
save ns config
To modif y or remove an auditing server by using the command line interf ace
T o modify an auditing server, type the set audit <type> command, the name of the auditing server, and the parameters
to be changed, with their new values.
T o remove an auditing server, type the rm audit <type> command and the name of the auditing server.
Example
T he following example modifies the syslog server named syslog1 to add errors and alerts to the log level:
set audit syslogAction syslog1 10.124.67.91 -logLevel emergency critical warning alert error
-logFacility LOCAL1 -tcp ALL
save ns config
To create or configure an auditing server by using the configuration utility
You can create an NSLOG policy or a SYSLOG policy. T he type of policy must match the type of server. T he command
names for the two types of policy are different, but the parameters for the commands are the same.
Example
T he following example creates a policy named syslogP1 that logs application firewall traffic to a syslog server named
syslog1.
Example
T he following example modifies the policy named syslogP1 to log application firewall traffic to a syslog server named
syslog2.
When a user's connection to an HT ML or Web 2.0 page is blocked, or a user asks for a non-existent HT ML or Web 2.0 page, the application firewall sends an HT ML-based error response to the user's
browser. When configuring which error response the application firewall should use, you have two choices:
You can configure a redirect URL, which can be hosted on any Web server to which users also have access. For example, if you have a custom error page on your Web server, 404.html, you can
configure the application firewall to redirect users to that page when a connection is blocked.
You can configure an HT ML error object, which is an HT ML-based Web page that is hosted on the application firewall itself. If you choose this option, you must upload the HT ML error object to
the application firewall. You do that in the Imports pane, on the HT ML Error Object tab.
T he error object must be a standard HT ML file that contains no non-HT ML syntax except for application firewall error object customization variables. It cannot contain any CGI scripts, server-parsed
code, or PHP code. T he customization variables enable you to embed troubleshooting information in the error object that the user receives when a request is blocked. While most requests that the
application firewall blocks are illegitimate, even a properly configured application firewall can occasionally block legitimate requests, especially when you first deploy it or after you make significant
changes to your protected Web sites. By embedding information in the error page, you provide the user with the information that he or she needs to give to the technical support person so that any
issues can be fixed.
To use these variables, you embed them in the HT ML or XML of the error page object as if they were an ordinary text string. When the error object is displayed to the user, for each customization
variable the application firewall substitutes the information to which the variable refers. An example HT ML error page that uses custom variables is shown below.
<!doctype html public "-//w3c//dtd html 4.0//en"> <html> <head> <title>Page Not Accessible</title> </head> <body> <h1>Page Not Accessible</h1> <p>The page that you accessed is not available. You can:</p>
To use this error page, copy it into a text or HT ML editor. Substitute the appropriate local information for the following variables, which are enclosed in square brackets to distinguish them from the
NetScaler variables. (Leave those unchanged.):
When a user's connection to an XML page is blocked, or a user asks for a nonexistent XML application, the application firewall sends an XML-based error response to the user's browser. You
configure the error response by uploading an XML-based error page to the application firewall in the Imports Pane, on the XML Error Object tab. All XML error responses are hosted on the application
firewall. You cannot configure a redirect URL for XML applications.
Note: You can use the same customization variables in an XML error object as in an HT ML error object.
XML Schema
When the application firewall performs a validation check on a user's request for an XML or Web 2.0 application, it can validate the request against the XML schema or design type document (DT D)
for that application and reject any request that does not follow the schema or DT D. Both an XML schema and a DT D are standard XML configuration files that describe the structure of a specific
type of XML document.
WSDL
When the application firewall performs a validation check on a user's request for an XML SOAP-based web service, it can validate the request against the web services type definition (WSDL) file for
that web service. A WSDL file is a standard XML SOAP configuration file that defines the elements of a specific XML SOAP web service.
Note: You cannot delete or export an imported file by using the command line.
To import a file by using the command line interf ace
Example
T he following example imports an HT ML error object from a file named error.html and assigns it the name HTMLError.
Before you attempt to import an XML schema, DT D, or WSDL file, or an HT ML or XML error object from a network
location, verify that the NetScaler ADC can connect to the Internet or LAN computer where the file is located. Otherwise,
you cannot import the file or object.
Before you attempt to export an XML schema, DT D, or WSDL file, or an HT ML or XML error object, verify that the
application firewall appliance can access the computer where the file is to be saved. Otherwise, you cannot export the file.
You edit the text of HT ML and XML error objects in the configuration utility without exporting and then reimporting them.
1. Navigate to Security > Application Firewall > Imports, and then select the tab for the type of file that you want to
modify.
2. Navigate to Application Firewall > Imports, and then select the tab for the type of file that you want to modify.
3. Select the file that you want to modify, and then click Edit.
T he text of the HT ML or XML error object is displayed in a browser text area. You can modify the text by using the
standard browser-based editing tools and methods for your browser.
Note: T he edit window is designed to allow you to make minor changes to your HT ML or XML error object. T o make
extensive changes, you may prefer to export the error object to your local computer and use standard HT ML or XML
web page editing tools.
4. Click OK, and then click Close.
Engine Settings. A collection of global settings— session cookie name, session time-out, maximum session lifetime,
logging header name, undefined profile, default profile, and import size limit— that pertain to all connections that the
application firewall processes, rather than to a specific subset of connections.
Conf idential Fields. A set of form fields in web forms that contain sensitive information that should not be logged to
the application firewall logs. Form fields such as password fields on a logon page or credit card information on a
shopping cart checkout form are normally designated as confidential fields.
Field Types. T he list of web form field types used by the Field Formats security check. Each of these field types is
defined by a PCRE-compliant regular expression that defines the type of data and the minimum/maximum length of
data that should be allowed in that type of form field.
XML Content Types. T he list of content types recognized as XML and subjected to XML-specific security checks. Each
of these content types is defined by a PCRE-compliant regular expression that defines the exact MIME type assigned to
that content.
JSON Content Types. T he list of content types recognized as JSON and subjected to JSON-specific security checks.
Each of these content types is defined by a PCRE-compliant regular expression that defines the exact MIME type
assigned to that content.
Cookie name— T he name of the cookie that stores the NetScaler session ID.
Session timeout— T he maximum inactive period allowed. If a user session shows no activity for this length of time, the
session is terminated and the user is required to reestablish it by visiting a designated start page.
Cookie post-encrypt pref ix— T he string that precedes the encrypted portion of any encrypted cookies.
Maximum session lif etime— T he maximum amount of time, in seconds, that a session is allowed to remain live. After
this period is reached, the session is terminated and the user is required to reestablish it by visiting a designated start
page. T his setting cannot be less then the session timeout. T o disable this setting, so that there is no maximum session
lifetime, set the value to zero (0).
Logging header name— T he name of the HT T P header that holds the Client IP, for logging.
Undef ined prof ile— T he profile applied when the corresponding policy action evaluates as undefined.
Def ault prof ile— T he profile applied to connections that do not match a policy.
Import size limit— T he maximum cumulative total byte count of all files imported to the ADC, including signatures,
WSDLs, schemas, HT ML and XML error pages. During an import, if the size of the imported object would cause the
cumulative total sizes of all imported files to exceed the configured limit, the import operation fails and the ADC displays
the following error message: ERROR: Import failed - exceeding the configured total size limit on the imported objects.
Learn message rate limit— T he maximum number of requests and responses per second that the learning engine is to
process. Any additional requests or responses over this limit are not sent to the learning engine.
Entity decoding— Decode HT ML entities when running application firewall checks.
Log malf ormed request— Enable logging of malformed HT T P requests.
Use conf igurable secret key— Use a configurable secret key for application firewall operations.
Reset learned data— Remove all learned data from the application firewall. Restarts the learning process by collecting
fresh data.
Two settings, Reset Learned Data and Signatures Auto-Update, are found in different places depending on whether you
use the command line or the configuration utility to configure your application firewall. When using the command line, you
configure Reset Learned Data by using the reset appfw learningdata command, which takes no parameters and has no
other functions. You configure Signatures Auto-Update in the set appfw settings command: the -signatureAutoUpdate
parameter enables or disables auto-updating of the signatures, and -signatureUrl configures the URL which hosts the
updated signatures file.
When using the configuration utility, you configure Reset Learned Data in Security > Application Firewall > Engine Settings;
the Reset Learned Data button is at the bottom of the dialog box. You configure Signatures Auto-Update for each set of
signatures in Security > Application Firewall > Signatures, by selecting the signatures file, clicking the right mouse button and
selecting Auto Update Settings.
Normally, the default values for the application firewall settings are correct. If the default settings cause a conflict with
other servers or cause premature disconnection of your users, however, you might need to modify them.
Done
Example
set appfw settings -sessionCookieName citrix-appfw-id -sessionTimeout 3600
-sessionLifetime 14400 -clientIPLoggingHeader NS-AppFW-Client-IP -undefaction APPFW_RESET
-defaultProfile APPFW_RESET -importSizeLimit 4096
save ns config
To configure engine settings by using the configuration utility
Entity Decoding
Log Malformed Request
Use Secret Key
Learn Message Rate Limit
Signatures Auto Update
4. Click OK.
Common types of information that you may want to protect with a confidential field designation include:
Passwords
Credit card numbers, validation codes, and expiration dates
Social security numbers
T ax ID numbers
Home addresses
Private telephone numbers
In addition to being good practice, proper use of confidential field designations may be necessary for PCI-DSS compliance on ecommerce servers, HIPAA compliance on servers that manage
medical information in the United States, and compliance with other data protection standards.
Important: In the following two cases, the Confidential Field designation does not function as expected:
If a Web form has either a confidential field or an action URL longer than 256 characters, the field or action URL is truncated in the NetScaler logs.
With certain SSL transactions, the logs are truncated if either the confidential field or the action URL is longer than 127 characters.
In either of these cases, the application firewall masks a fifteen-character string with the letter "x," instead of the normal eight character string. To ensure that any confidential information is
removed, the user must use form field name and action URL expressions that match the first 256, or (in cases where SSL is used) the first 127 characters.
To configure your application firewall to treat a web-form field on a protected web site as confidential, you add that field to the Confidential Fields list. You can enter the field name as a string, or
you can enter a PCRE-compatible regular expression specifying one or more fields. You can enable the confidential-field designation when you add the field, or you can modify the designation
later.
add appfw confidField <fieldName> <url> [-isRegex ( REGEX | NOT REGEX )] [-comment "<string>"] [-state ( ENABLED | DISABLED )]
save ns config
Example
T he following example adds all web form fields whose names begin withPassword to the confidential fields list.
set appfw confidField <fieldName> <url> [-isRegex ( REGEX | NOT REGEX )] [-comment "<string>"] [-state ( ENABLED | DISABLED )]
save ns config
Example
T he following example modifies the confidential field designation to add a comment.
set appfw confidField Password "https?://www[.]example[.]com/[^<>]*[^a-z]password[0-9a-z._-]*[.](asp|cgi|htm|html|htp|js|php)" -comment "Protect password fields." -isRegex REGEX -state ENABLED
save ns config
To remove a confidential field by using the command line interf ace
Examples
Following are some regular expressions that define form field names that you might find useful:
^passwd_ (Applies confidential-field status to all field names that begin with the “passwd_” string.)
^(([0-9a-zA-Z._-]*||\\x[0-9A-Fa-f][0-9A-Fa-f])+-)?passwd_ (Applies confidential-field status to all field names that begin with the string passwd_, or that contain the string -passwd_ after another
string that might contain non-ASCII special characters.)
Following are some regular expressions that define specific URL types that you might find useful. Substitute your own web host(s) and domain(s) for those in the examples.
If the web form appears on multiple web pages on the web host www.example.com, but all of those web pages are named logon.pl?, you could use the following regular expression:
https?://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_.-]*/)*logon[.]pl\?
If the web form appears on multiple web pages on the web host www.example-español.com, which contains the n-tilde (ñ) special character, you could use the following regular expression,
which represents the n-tilde special character as an encoded UT F-8 string containing C3 B1, the hexadecimal code assigned to that character in the UT F-8 charset:
https?://www[.]example-espa\xC3\xB1ol[.]com/([0-9A-Za-z][0-9A-Za-z_.-]*/)* logon[.]pl\?
If the web form containing query.pl appears on multiple web pages on different hosts within the example.com domain, you could use the following regular expression:
https?://([0-9A-Za-z][0-9A-Za-z_-.]*[.])*example[.]com/([0-9A-Za-z][0-9A-Za-z_-.]*/)*logon[.]pl\?
If the web form containing query.pl appears on multiple web pages on different hosts in different domains, you could use the following regular expression:
https?://([0-9A-Za-z][0-9A-Za-z_-.]*[.])*[0-9A-Za-z][0-9A-Za-z_-.]+[.][a-z]{2,6}/([0-9A-Za-z][0-9A-Za-z_-.]*/)*logon[.]pl\?
If the web form appears on multiple web pages on the web host www.example.com, but all of those web pages are named logon.pl?, you could use the following regular expression:
https?://www[.]example[.]com/([0-9A-Za-z][0-9A-Za-z_-.]*/)*logon[.]pl\?
T he application firewall comes with several default field types, which are:
integer. A string of any length consisting of numbers only, without a decimal point, and with an optional preceding minus
sign (-).
alpha. A string of any length consisting of letters only.
alphanum. A string of any length consisting of letters and/or numbers.
nohtml. A string of any length consisting of characters, including punctuation and spaces, that does not contain HT ML
symbols or queries.
any. Anything at all.
Important: Assigning the any field type as the default field type, or to a field, allows active scripts, SQL commands, and
other possibly dangerous content to be sent to your protected web sites and applications in that form field. You should
use the any type sparingly, if you use it at all.
You can also add your own field types to the Field Types list. For example, you might want to add a field type for a social
security number, postal code, or phone number in your country. You might also want to add a field type for a customer
identification number or store credit card number.
To add a field type to the Field Types list, you enter the field name as a literal string or PCRE-format regular expression.
Example
T he following example adds a field type named SSN that matches US Social Security numbers to the Field Types list, and
sets its priority to 1.
Example
T he following example modifies the field type to add a comment.
Examples
Following are some regular expressions for field types that you might find useful:
To configure the XML content types, you add the appropriate patterns to the XML Content Types list. You can enter a
content type as a string, or you can enter a PCRE-compatible regular expression specifying one or more strings. You can
also modify the existing XML content types patterns.
To add an XML content type pattern by using the command line interf ace
Example
T he following example adds the pattern .*/xml to the XML Content Types list and designates it as a regular expression.
To configure the XML content type list by using the configuration utility
You can configure the application firewall to examine web content for additional strings or patterns that indicate that
those files are JSON files. T his can ensure that the application firewall recognizes all JSON content on your site, even if
certain JSON content does not follow normal JSON naming conventions, ensuring that JSON content is subjected to JSON
security checks.
To configure the JSON content types, you add the appropriate patterns to the JSON Content Types list. You can enter a
content type as a string, or you can enter a PCRE-compatible regular expression specifying one or more strings. You can
also modify the existing JSON content types patterns.
To add a JSON content type pattern by using the command line interf ace
Example
T he following example adds the pattern .*/json to the JSON Content Types list and designates it as a regular expression.
When you enable the statistics action for application firewall signatures or security checks, the application firewall
maintains information about connections that match that signature or security check. You can view the accumulated
statistics information on the Monitoring tab of the main logon page of your application firewall appliance by selecting one
of the following choices in the Select Group list box:
Application Firewall. A summary of all statistics information gathered by your application firewall appliance for all
profiles.
Application Firewall (per prof ile). T he same information, but displayed per-profile rather than summarized.
You can use this information to monitor how your application firewall is operating and determine whether there is any
abnormal activity or abnormal amounts of hits on a signature or security check. If you see such a pattern of abnormal
activity, you can check the logs for that signature or security check, to diagnose the issue, and then take corrective action.
T he application firewall reports provide information about your application firewall configuration and how it is handling
traffic for your protected web sites.
ISPs and online merchants prove that they are in compliance with PCI DSS by having an audit conducted by a PCI DSS
Qualified Security Assessor (QSA) Company. T he PCI DSS report is designed to assist them both before and during the audit.
Before the audit, it shows which application firewall settings are relevant to PCI DSS, how they should be configured, and
(most important) whether your current application firewall configuration meets the standard. During the audit, the report
can be used to demonstrate compliance with relevant PCI DSS criteria.
T he PCI DSS report consists of a list of those criteria that are relevant to your application firewall configuration. Under
each criterion, it lists your current configuration options, indicates whether your current configuration complies with the PCI
DSS criterion, and explains how to configure the application firewall so that your protected web site(s) will be in compliance
with that criterion.
T he PCI DSS report is located under System > Reports. To generate the report as an Adobe PDF file, click Generate PCI DSS
Report. Depending on your browser settings, the report is displayed in the pop-up window or you are prompted to save it
to your hard disk.
Note: T o view this and other reports, you must have the Adobe Reader program installed on your computer.
Firewall License and Feature Status. Tells you whether the application firewall is licensed and enabled on your
NetScaler appliance.
Executive Summary. A table that lists the PCI DSS criteria and tells you which of those criteria are relevant to the
application firewall.
Detailed PCI DSS Criteria Inf ormation. For each PCI DSS criterion that is relevant to your application firewall
configuration, the PCI DSS report provides a section that contains information about whether your configuration is
currently in compliance and, if it is not, how to bring it into compliance.
Configuration. Data for individual profiles, which you access either by clicking Application Firewall Configuration at the
top of the report, or directly from the Reports pane. T he Application Firewall Configuration report is the same as the PCI
DSS report, with the PCI DSS-specific summary omitted, and is described below.
T he Application Firewall Configuration report starts with a Summary page, which consists of the following sections:
Application Firewall Policies. A table that lists your current application firewall policies, showing the policy name, the
content of the policy, the action (or profile) it is associated with, and global binding information.
Application Firewall Prof iles. A table that lists your current application firewall profiles and indicates which policy each
profile is associated with. If a profile is not associated with a policy, the table displays INACT IVE in that location.
To download all report pages for all policies, at the top of the Profiles Summary page click Download All Profiles. You display
the report page for each individual profile by selecting that profile in the table at the bottom of the screen. T he Profile
page for an individual profile shows whether each check action is enabled or disabled for each check, and the other
configuration settings for the check.
To download a PDF file containing the PCI DSS report page for the current profile, click Download Current Profile at the
top of the page. To return to the Profiles Summary page, click Application Firewall Profiles. To go back to the main page,
click Home. You can refresh the PCI DSS report at any time by clicking Refresh in the upper right corner of the browser. You
should refresh the report if you make changes to your configuration.
When the log action is enabled for security checks or signatures, the resulting log messages provide information about the
requests and responses that the application firewall has observed while protecting your web sites and applications. T he
most important information is the action taken by the application firewall when a signature or a security check violation
was observed. For some security checks, the log message can provide additional useful information, such as the location
and the detected pattern that triggered the violation. You can deploy security checks in non-block mode and monitor the
logs to determine whether the transactions that are triggering security violations are valid transactions (false positives). If
they are, you can either remove, or reconfigure the signature or security checks, deploy relaxations, or take other
appropriate measures to mitigate the false positives before you enable blocking for that signature or security check. An
excessive increase in the number of violation messages in logs can indicate a surge in malicious requests. T his can alert you
that your application might be under attack to exploit a specific vulnerability that is detected and thwarted by application
firewall protections.
T he application firewall uses the NetScaler format logs (also called native format logs) by default. T hese logs have the same
format as those generated by other NetScaler features. Each log contains the following fields:
T imestamp. Date and time when the connection occurred.
Severity. Severity level of the log.
Module. NetScaler module that generated the log entry.
Event T ype. T ype of event, such as signature violation or security check violation.
Event ID. ID assigned to the event.
Client IP. IP address of the user whose connection was logged.
T ransaction ID. ID assigned to the transaction that caused the log.
Session ID. ID assigned to the user session that caused the log.
Message. T he log message. Contains information identifying the signature or security check that triggered the log entry.
You can search for any of these fields, or any combination of information from different fields. Your selection is limited only
by the capabilities of the tools you use to view the logs. You can observe the application firewall log messages in the
configuration utility by accessing the NetScaler syslog viewer, or you can manually connect to the NetScaler appliance and
access logs from the command line interface, or you can drop into shell and tail the logs directly from the /var/log/ folder.
In addition to date, timestamp, client IP, log format, appliance, company, build version, module, and security check
information, application firewall CEF Log messages include the following details:
src – source IP address
spt – source port number
request – request URL
act – action (e.g. blocked, transformed)
msg – message (Message regarding the observed security check violation)
cn1 – event ID
cn2 – HT T P T ransaction ID
cs1 – profile name
cs2 – PPE ID (e.g. PPE1)
cs3 - Session ID
cs4 – Severity (e.g. INFO, ALERT )
cs5 – event year
method – Method (e.g. GET /POST )
For example, consider the following CEF format log message, which was generated when a Start URL violation was
triggered:
Jun 12 23:37:17 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11.0
|APPFW|APPFW_STARTURL|6|src=10.217.253.62 spt=47606 method=GET
request=http://aaron.stratum8.net/FFC/login.html msg=Disallow Illegal URL. cn1=1340
cn2=653 cs1=pr_ffc cs2=PPE1 cs3=EsdGd3VD0OaaURLcZnj05Y6DOmE0002 cs4=ALERT cs5=2015
act=blocked
T he above message can be broken down in the following components:
Message Description
June 12 Date
<local0.info>
NetScaler Appliance
NS11.0 Version
6 Severity
Example of a request check violation in CEF log format: request is not blocked
Jun 13 00:21:28 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11.0|APPFW|
APPFW_FIELDCONSISTENCY|6|src=10.217.253.62 spt=761 method=GET request=
http://aaron.stratum8.net/FFC/login.php?login_name\=abc&passwd\=
123456789234&drinking_pref\=on&text_area\=&loginButton\=ClickToLogin&as_sfid\
=AAAAAAWIahZuYoIFbjBhYMP05mJLTwEfIY0a7AKGMg3jIBaKmwtK4t7M7lNxOgj7Gmd3SZc8KUj6CR6a
7W5kIWDRHN8PtK1Zc-txHkHNx1WknuG9DzTuM7t1THhluevXu9I4kp8%3D&as_fid\=feeec8758b4174
0eedeeb6b35b85dfd3d5def30c msg=Field consistency check failed for field passwd cn1=1401
cn2=707 cs1=pr_ffc cs2=PPE1 cs3=Ycby5IvjL6FoVa6Ah94QFTIUpC80001 cs4=ALERT cs5=2015 act=
not blocked
Example of a response check violation in CEF format: response is transformed
Jun 13 00:25:31 <local0.info> 10.217.31.98 CEF:0|Citrix|NetScaler|NS11.0|APPFW|
APPFW_SAFECOMMERCE|6|src=10.217.253.62 spt=34041 method=GET request=
http://aaron.stratum8.net/FFC/CreditCardMind.html msg=Maximum number of potential credit
card numbers seen cn1=1470 cn2=708 cs1=pr_ffc cs2=PPE1
cs3=Ycby5IvjL6FoVa6Ah94QFTIUpC80001 cs4=ALERT cs5=2015 act=transformed
Geolocation, which identifies the geographic location from which requests originate, can help you configure the application
firewall for the optimal level of security. To bypass security implementations such as rate limiting, which rely on the IP
addresses of the clients, malware or rogue computers can keep changing the source IP address in requests. Identifying the
specific region from where requests are coming can help determine whether the requests are from a valid user or a device
attempting to launch cyberattacks. For example, if an excessively large number of requests are received from a specific
area, it is easy to determine whether they are being sent by users or a rogue machine. Geolocation analysis of the received
traffic can be very useful in deflecting attacks such as denial of service (DoS) attacks.
T he application firewall offers you the convenience of using the built-in NetScaler database for identifying the locations
corresponding to the IP addresses from which malicious requests are originating. You can then enforce a higher level of
security for requests from those locations. Citrix default syntax (PI) expressions give you the flexibility to configure location
based policies that can be used in conjunction with the built-in location database to customize firewall protection,
bolstering your defense against coordinated attacks launched from rogue clients in a specific region.
You can use the NetScaler built-in database, or you can use any other database. If the database does not have any
location information for the particular client IP address, the CEF log shows geolocation as an Unknown geolocation.
Note: Geolocation logging uses the Common Event Format (CEF). By default, CEF logging and GeoLocationLogging are
OFF. You must explicitly enable both parameters.
To configure the log action for a security checks of a profile by using the command line
Examples
T he CEF logging is disabled by default. At the command prompt, type one of the following commands to change or display
the current setting:
set appfw settings CEFLogging on
unset appfw settings CEFLogging
sh appfw settings | grep CEFLogging
To configure the logging of the credit card numbers by using the command line
or
T he application firewall offers you an option to isolate and redirect the application firewall security log messages to a
different log file. T his might be desirable if the application firewall is generating a large number of logs, making it difficult to
To redirect the application firewall logs to a different log file, configure a syslog action to send the application firewall logs
to a different log facility. You can use this action when configuring the syslog policy, and bind it globally for use by
application firewall.
Example
1. Switch to the shell and use an editor such as vi to edit the /etc/syslog.conf file. Add a new entry to use local2.* to send
logs to a separate file as shown in the following example:
local2.* /var/log/ns.log.appf w
2. Restart the syslog process. You can use the grep command to identify the syslog process ID (PID), as shown in the
following example:
root@ns# ps -A | grep syslog
3. From the command line interface, configure the syslog action and policy. Bind it as a global application firewall policy.
add audit syslogAction sysact1 127.0.0.1 -logLevel ALL -logFacility LOCAL2
4. All application firewall security check violations will now be redirected to the /var/log/ns.log.appfw file. You can tail this
file to view the application firewall violations that are getting triggered during the processing of the ongoing traffic.
root@ns# tail -f ns.log.appfw
Warning: If you have configured the syslog policy to redirect the logs to a different log facility, the application firewall log
messages no longer appear in the /var/log/ns.log file.
Viewing the Application Firewall Logs
You can view the logs by using the syslog viewer, or by logging onto the NetScaler appliance, opening a UNIX shell, and using
the UNIX text editor of your choice.
Switch to the shell and tail the ns.logs in the /var/log/ folder to access the log messages pertaining to the application
firewall security check violations:
Shell
tail -f /var/log/ns.log
You can use the vi editor, or any Unix text editor or text search tool, to view and filter the logs for specific entries. For
example, you can use grep command to access the log messages pertaining to the Credit Card violations:
tail -f /var/log/ns.log | grep SAFECOMMERCE
T he Citrix configuration utility includes a very useful tool (Syslog Viewer) for analyzing the log messages. You have multiple
T he HT ML based Syslog Viewer provides the following filter options for selecting only the log messages that are of interest
to you:
File— T he current /var/log/ns.log file is selected by default, and the corresponding messages appear in the Syslog Viewer.
A list of other log files in the /var/log directory are available in a compressed .gz format. T o download and un-compress
an archived log file, just select the log file from the dropdown option. T he log messages pertaining to the selected file
are then displayed in the syslog viewer. T o refresh the display, click the Refresh icon (a circle of two arrows).
Module list box— You can select the NetScaler module whose logs you want to view. You can set it to APPFW for
application firewall logs.
Event Type list box— T his box contains a set of check boxes for selecting the type of event you are interested in. For
example, to view the log messages pertaining to the signature violations, you can select the
APPFW_SIGNATURE_MATCH check box. Similarly, you can select a check box to enable the specific security check that
is of interest to you. You can select multiple options.
Severity— You can select a specific severity level to show just the logs for that severity level. Leave all the check boxes
blank if you want to see all logs.
To access the application firewall security check violation log messages for a specific security check, filter by selecting
APPFW in the dropdown options for Module. T he Event Type displays a rich set of options to further refine your
selection. For example, if you select the APPFW_FIELDFORMAT check box and click the Apply button, only log messages
pertaining to the Field Formats security check violations appear in the Syslog Viewer. Similarly, if you select the
APPFW_SQL and APPFW_STARTURL check boxes and click the Apply button, only log messages pertaining to these
two security check violations will appear in the syslog viewer.
If you place the cursor in the row for a specific log message, multiple options, such as Module, EventType, EventID,
ClientIP, TransactionID, and so on appear below the log message. You can select any of these options to highlight the
corresponding information in the logs.
Click to Deploy: T his functionality is available only in the configuration utility. You can use the Syslog Viewer to not only
view the logs but also to deploy relaxation rules based on the log messages for the application firewall security check
violations. T he log messages must be in CEF log format for this operation. If the relaxation rule can be deployed for a log
message, a check box appears at the right edge of the Syslog Viewer box in the row. Select the check box, and then select
an option from the Action list to deploy the relaxation rule. Edit & Deploy, Deploy, and Deploy All are available as Action
options. For example, you can select an individual log message to edit and deploy. You can also select the check boxes for
multiple log messages from one or more security checks and use the Deploy or Deploy All option. Click to Deploy
functionality is currently supported for the following security checks:
StartURL
Note: SQL Injection and XSS rules that are deployed by using Click to Deploy option do not include the fine grain relaxation
recommendations.
Highlights
CEF Log Format support— T he CEF log format option provides a convenient option to monitor, parse, and analyze the
application firewall log messages to identify attacks, fine tune configured settings to decrease false positives, and
gather statistics.
Click to Deploy— T he Syslog viewer provides an option to filter, evaluate, and deploy relaxation rules for single or
multiple security check violations from one convenient location.
Option to customize log message— You can use advanced PI expressions to customize log messages and include the
data you want to see in the logs.
Segregate application f irewall specif ic logs— You have an option to filter and redirect application-firewall specific
logs to a separate log file.
Remote Logging— You can redirect the log messages to a remote syslog server.
Geolocation Logging— You can configure the application firewall to include the geolocation of the area from where
the request is received. A built-in geolocation database is available, but you have the option to use an external
geolocation database. T he NetScaler appliance supports both IPv4 and IPv6 static geolocation databases.
Inf ormation rich log message— Following are some examples of the type of information that can be included in the
logs, depending on the configuration:
An application firewall policy was triggered.
A security check violation was triggered.
A request was considered to be malformed.
A request or the response was blocked or not blocked.
Request data (such as SQL or XSS special characters) or response data (such as Credit card numbers or safe object
strings) was transformed.
T he number of credit cards in the response exceeded the configured limit.
T he credit card number and type.
T he log strings configured in the signature rules, and the signature ID.
Geolocation information about the source of the request.
Masked (X’d out) user input for protected confidential fields.
A number of character types require encoding using a PCRE regular expression if you include them in your application
firewall configuration as a URL, form field name, or Safe Object expression. T hey include:
Upper-ASCII characters. Characters with encodings from HEX 7F (ASCII 128) to HEX FF (ASCII 255). Depending on the
character map used, these encodings can refer to control codes, ASCII characters with accents or other modifications,
non-Latin alphabet characters, and symbols not included in the basic ASCII set. T hese characters can appear in URLs,
form field names, and safe object expressions.
Double-Byte characters. Characters with encodings that use two 8-byte words. Double-byte characters are used
primarily for representing Chinese, Japanese, and Korean text in electronic format. T hese characters can appear in URLs,
form field names, and safe object expressions.
ASCII control characters. Non-printable characters used to send commands to a printer. All ASCII characters with
hexadecimal codes less than HEX 20 (ASCII 32) fall into this category. T hese characters should never appear in a URL or
form field name, however, and would rarely if ever appear in a safe object expression.
T he NetScaler appliance does not support the entire UT F-8 character set, but only the characters found in the following
eight charsets:
English US (ISO-8859-1). Although the label reads, “English US,” the application firewall supports all characters in the
ISO-8859-1 character set, also called the Latin-1 character set. T his character set fully represents most modern western
European languages and represents all but a few uncommon characters in the rest.
Chinese Traditional (Big5). T he application firewall supports all characters in the BIG5 character set, which includes all
of the Traditional Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in Hong
Kong, Macau, Taiwan, and by many people of Chinese ethnic heritage who live outside of mainland China.
Chinese Simplified (GB2312). T he application firewall supports all characters in the GB2312 character set, which includes
all of the Simplified Chinese characters (ideographs) commonly used in modern Chinese as spoken and written in mainland
China.
Japanese (SJIS). T he application firewall supports all characters in the Shift-JIS (SJIS) character set, which includes most
characters (ideographs) commonly used in modern Japanese.
Japanese (EUC-JP). T he application firewall supports all characters in the EUC-JP character set, which includes all
characters (ideographs) commonly used in modern Japanese.
Korean (EUC-KR). T he application firewall supports all characters in the EUC-KR character set, which includes all
characters (ideographs) commonly used in modern Korean.
Turkish (ISO-8859-9). T he application firewall supports all characters in the ISO-8859-9 character set, which includes all
letters used in modern Turkish.
When configuring the application firewall, you enter all non-ASCII characters as PCRE-format regular expressions using the
hexadecimal code assigned to that character in the UT F-8 specification. Symbols and characters within the normal ASCII
character set, which are assigned single, two-digit codes in that character set, are assigned the same codes in the UT F-8
character set. For example, the exclamation point (!), which is assigned hex code 21 in the ASCII character set, is also hex 21
in the UT F-8 character set. Symbols and characters from another supported character set have a paired set of hexadecimal
codes assigned to them in the UT F-8 character set. For example, the letter a with an acute accent (á) is assigned UT F-8
code C3 A1.
T he syntax you use to represent these UT F-8 codes in the application firewall configuration is “\xNN” for ASCII characters;
“\xNN\xNN” for non-ASCII characters used in English, Russian, and Turkish; and “\xNN\xNN\xNN” for characters used in
Chinese, Japanese, and Korean. For example, if you want to represent a ! in an application firewall regular expression as a
UT F-8 character, you would type \x21. If you want to include an á, you would type \xC3\xA1.
Note: Normally you do not need to represent ASCII characters in UT F-8 format, but when those characters might confuse
a web browser or an underlying operating system, you can use the character’s UT F-8 representation to avoid this
confusion. For example, if a URL contains a space, you might want to encode the space as \x20 to avoid confusing certain
browsers and web server software.
Below are examples of URLs, form field names, and safe object expressions that contain non-ASCII characters that must be
entered as PCRE-format regular expressions to be included in the application firewall configuration. Each example shows
the actual URL, field name, or expression string first, followed by a PCRE-format regular expression for it.
You can find a number of tables that include the entire Unicode character set and matching UT F-8 encodings on the
Internet. A useful web site that contains this information is located at the following URL:
http://www.utf8-chartable.de/unicode-utf8-table.pl
HT T P Request Smuggling
HT T P Response Splitting
HT T P Response Smuggling
Null Byte Injection
Remote File Inclusion
URL Redirector Abuse
Abuse of Functionality
Brute Force
Content Spoofing
Denial of Service
Directory Indexing
Information Leakage
Insufficient Anti-automation
Insufficient Authentication
Insufficient Authorization
Insufficient Session Expiration
LDAP Injection
Session Fixation
Best Practices
Autocomplete Attribute
Insufficient Cookie Access Control
Insufficient Password Strength
Invalid HT T P Method Usage
Non-HttpOnly Session Cookie
Persistent Session Cookie
Personally Identifiable Information
Secured Cachable HT T P Messages
Unsecured Session Cookie
Although the streaming process is transparent to the users, minor configuration adjustments are required due to the
following changes:
RegEx Pattern Match: RegEx pattern match is now restricted to 4K for contiguous character string match.
Field Name Match: Application firewall learning engine can only distinguish the first 128 bytes of the name for learning. If a
form has multiple fields with names that have identical string match for the first 128 bytes, the learning engine may not be
able to distinguish between them. Similarly, the deployed relaxation rule might inadvertently relax all such fields.
Removing white spaces, percent decoding, unicode decoding, and charset conversion which is done during canonicalization
is carried out prior to security check inspection. T he 128 byte limit is applicable to the canonicalized representation of the
field name in UT F-8 character format. T he ASCII characters are 1 byte but the UT F-8 representation of the characters in
some international languages may range from 1-4 bytes. If each character in the name takes 4 bytes when converted to
UT F-8 format, only first 32 characters in the name may be distinguished by the learned rule for such a language.
Field Consistency Check: When the field Consistency check is enabled, all the forms in the session are now stored based
on the “as_fid” tag inserted by the application firewall without consideration for the “action_url.”
Mandatory Form tagging f or Form Field consistency: When the field consistency check is enabled, the form tag must
be enabled also. T he Field Consistency protection might not work if form tagging is turned off.
Sessionless Form Field Consistency: T he application firewall no longer carries out the “GET ” to “POST ” conversion of
forms when sessionless field consistency parameter is enabled. T he form tag is required for sessionless field consistency
also.
Tampering of as_f id: If a form is submitted after tampering as_fid, it now triggers field consistency violation even if no
other field was tampered. In non-streaming requests, this was allowed because the forms could be validated using the
“action_url” stored in the session.
XSS/SQL Transf orm: Raw data is used for transformation because the SQL special characters ( single quote('), backslash (\),
and semicolon (;)), and XSS tags ((<) and(>)) are same in all languages and do not need canonicalization of data. All
representations of these characters, such as HT ML entity encoding, percent encoding, or ASCII are evaluated for transform
operation.
T he application firewall no longer inspects both the attribute name and value for the XSS transform operation. Now only
XSS attribute names are transformed when streaming is engaged.
Processing XSS Tags: As part of the streaming changes in 10.5.e build onwards, the application firewall processing of the
Cross-site Scripting tags has changed. In earlier releases, presence of either open bracket (<), or close bracket (>), or both
open and close brackets (<>) was flagged as Cross-site Scripting Violation. T he behavior has changed in 10.5.e build
onwards. Presence of only the open bracket character (<), or only the close bracket character (>) is no longer considered as
an attack. It is when an open bracket character (<) is followed by a close bracket character (>), the Cross-site scripting
attack gets flagged. Both characters must be present in the right order (< followed by >) to trigger Cross-site scripting
violation.
Note
Change in SQL violation log Message: As part of the streaming changes in 10.5.e build onwards, we now process the input data
in blocks. RegEx pattern matching is now restricted to 4K for contiguous character string matching. With this change, the SQL
violation log messages might include different information compared to the earlier builds. T he keyword and special character in the
input could be separated by a large number of bytes. We now keep track of the SQL keywords and special strings when processing
the data, instead of buffering the entire input value. In addition to the field name, the log message now includes the SQL keyword, or
the SQL special character, or both the SQL keyword and the SQL special character, as determined by the configured setting. T he rest
of the input is no longer included in the log message, as shown in the following example:
Example:
In 10.5, when the application firewall detects the SQL violation, the entire input string might be included in the log message, as shown
below:
SQL Keyword check failed for field text=\"select a name f rom testbed1\;\\(\;\\)\".*\<blocked\>
In 11.0, we log only the field name, keyword and special character (if applicable) in the log message, as shown below:
T his change is applicable to requests that contain application/x-www-f orm-urlencoded, or multipart/f orm-data, or text/x-
gwt-rpc content-types. Log messages generated during processing of JSON or XML payloads are not affected by this change.
RAW POST Body: T he security check inspections are always done on RAW POST body.
Form ID: T he application firewall inserted “as_fid” tag, which is a computed hash of the form, will no longer be unique for
the user session. It will now have an identical value for a specific form irrespective of the user or the session.
Charset: If a request does not have a charset, the default charset specified in the application profile is used when
processing the request.
Counters:
_err counters: indicate the rare event which should have succeeded but failed due to either memory allocation problem or
some other resource crunch.
_cur counters: counters indicating current values that keep changing based on usage from current transactions.
Tips:
T he application firewall security checks should work exactly the same as before.
T here is no set ordering for the processing of the security checks.
T he response side processing is not affected and remains unchanged.
Streaming is not engaged if CVPN is used.
Important
Calculating the Cookie length: In release 10.5.e (in a few interim enhancement builds prior to 59.13xx.e build) as well as in the
11.0 release (in builds prior to 65.x), application firewall processing of the Cookie header was changed. In those releases, every
cookie is evaluated individually, and if the length of any one cookie received in the Cookie header exceeds the configured
BufferOverflowMaxCookieLength, the Buffer Overflow violation is triggered. As a result of this change, requests that were blocked
in 10.5 and earlier release builds might be allowed, because the length of the entire cookie header is not calculated for determining
the cookie length. In some situations, the total cookie size forwarded to the server might be larger than the accepted value, and the
server might respond with "400 Bad Request".
Note that this change has been reverted. The behavior in the 10.5.e ->59.13xx.e and subsequent 10.5.e
enhancement builds as well as in the 11.0 release 65.x and subsequent builds is now similar to that of the non-
enhancement builds of release 10.5. The entire raw Cookie header is now considered when calculating the length
of the cookie. Surrounding spaces and the semicolon (;) characters separating the name-value pairs are also
included in determining the cookie length.
T he NetScaler now offers the option to isolate traffic for a specific application firewall profile and collect nstrace for the
HT ML requests that trigger a log or block action or malformed requests that might be causing reset or aborts. T he nstrace
collected in – appfw mode will include details of the entire request including the application firewall generated log
messages. You can use “Follow TCP stream” in the trace to view the details of the individual transaction including headers,
payload, as well as the corresponding log message, together in the same screen.
T his gives you a comprehensive overview regarding your traffic. Having a detailed view of the request, payload, and
associated log records can be very useful to analyze security check violation. You can easily identify the pattern that is
triggering the violation. If the pattern should be allowed, you can take a decision to modify the configuration and/or add a
relaxation rule.
T his enhancement helps in troubleshooting the NetScaler ADC and offers the following benefits:
1. Isolate traf f ic f or specif ic prof ile: T his enhancement can be quite useful when you need to isolate traffic for only one
profile or specific transactions of a profile for troubleshooting. You no longer have to skim through the entire data
collected in the trace or need special filters to isolate requests that are of interest to you which can be tedious
especially with heavy traffic. You now have the option to view only the data that you are interested in.
2. Collect data f or specif ic requests: T he trace can be collected for a specified duration. You can collect trace for only a
couple of requests to isolate, analyze, and debug specific transactions if needed.
3. Identif y resets or aborts: Unexpected closing of connections are not easily visible. T he trace collected in – appfw mode
captures a reset or an abort, triggered by the application firewall. T his allows a quicker isolation of issue when you do
not see a security check violation message. Malformed requests or other non-RFC compliant requests terminated by
application firewall will now be easier to identify.
4. View decrypted SSL traf f ic: HT T PS traffic is captured in plain text to allow for easier troubleshooting.
5. Provides comprehensive view: Allows you to look at the entire request at the packet level, check the payload, look at
the logs to check what security check violation is being triggered and identify the match pattern in the payload. If the
payload consists of any unexpected data, junk strings, or non-printable characters (null character, \r or \n etc), they are
easy to discover in the trace.
6. Modif y conf iguration: T he debugging can provide useful information to decide if the observed behavior is the correct
behavior or the configuration should be modified.
7. Expedite response time: Faster debugging on target traffic can improve the response time to provide explanations
and/or root cause analysis by Citrix engineering and support team.
Please see any task topic in eDocs for documenting tasks. http://support.citrix.com/proddocs/topic/ns-security-10-5-
map/appfw-config-manual-cli-tsk.html
To configure debug tracing f or a profile by using the command line interf ace
Step 1. Enable tracing for the profile. You can use the show command to verify the configured setting.
set appfw profile <profile> -trace ON
Location of the trace: T he nstrace is stored in a time-stamped folder which is created in the /var/nstrace directory and
can be viewed using wireshark. You can tail the /var/log/ns.log to see the log messages providing details regarding the
location of the new trace.
Tips:
When – appfw mode option is used, the nstrace will only collect the data for the profile(s) for which “trace” was enabled.
Enabling trace on the profile will not automatically start collecting the traces till you explicitly execute the “start
nstrace” command to collect the trace.
Although, enabling trace on a profile may not have any adverse effect on the performance of the application firewall
but you may want to enable this feature only for the duration for which you want to collect the data. It is
recommended that you turn the – trace flag off after you have collected the trace. T his will prevent the risk of
inadvertently getting data from profiles for which you had enabled this flag in the past.
T he Block or Log action must be enabled for the security check for the transaction record to be included in the nstrace.
Resets and aborts will be logged independently of security checks actions when trace is “On” for the profile(s).
T his feature is only applicable for troubleshooting the requests received from the client. T he traces in – appfw mode do
not include the responses received from the server.
You can continue to use all the options which are applicable for the nstrace command. For example,
"start nstrace -tcpdump enabled -size 0 -mode appFW"
If a request triggers multiple violations, the nstrace for that record will include all the corresponding log messages.
CEF log message format is supported for this functionality.
Signature violations triggering block and/or log action for request side checks will also be included in the trace.
Only HT ML (non-XML) requests are collected in the trace.
A cluster is a group of NetScaler appliances that are configured and managed as a single system. Each appliance in the
cluster is called a node. Depending on the number of nodes the configurations are active on, cluster configurations are
referred to as striped, partially striped, or spotted configurations. T he application firewall is fully supported in all
configurations.
T he two main advantages of striped and partially striped virtual server support in cluster configurations are the following:
1. Session failover support— Striped and partially striped virtual server configurations support session failover. T he advanced
application firewall security features, such as Start URL Closure and the Form Field Consistency check, maintain and use
sessions during transaction processing. In ordinary high availability configurations, or in spotted cluster configurations,
when the node that is processing the application firewall traffic fails, all the session information is lost and the user has
to reestablish the session. In striped virtual server configurations, user sessions are replicated across multiple nodes. If a
node goes down, a node running the replica becomes the owner. Session information is maintained without any visible
impact to the user.
2. Scalability— Any node in the cluster can process the traffic. Multiple nodes of the cluster can process the incoming
requests served by the striped virtual server. T his improves the application firewall’s ability to handle multiple simultaneous
requests, thereby improving the overall performance.
Security checks and signature protections can be deployed without the need for any additional cluster-specific application
firewall configuration. You just do the usual application firewall configuration on the configuration coordinator (CCO) node
for propagation to all the nodes.
Note: T he session information is replicated across multiple nodes, but not across all the nodes in the striped configuration.
T herefore, failover support accommodates a limited number of simultaneous failures. If multiple nodes fail simultaneously,
the application firewall might lose the session information if a failure occurs before the session is replicated on another
node.
Highlights
Application firewall offers scalability, high throughput, and session failover support in cluster deployments.
All application firewall security checks and signature protections are supported in all cluster configurations.
Character-Maps are not yet supported for a cluster. T he learning engine recommends Field-T ypes in learned rules for the
Field Format security check.
Stats and learned rules are aggregated from all the nodes in a cluster.
Distributed Hash T able (DHT ) provides the caching of the session and offers the ability to replicate session information
across multiple nodes. When a request comes to the virtual server, the NetScaler appliance creates application firewall
sessions in the DHT , and can also retrieve the session information from the DHT .
Clustering is licensed with the Enterprise and Platinum licenses. T his feature is not available with the Standard license.
• Check P olicy hit s, Bindings, Net work configurat ion, Applicat ion F irewall configurat ion
- Identify misconfiguration
• Inspect logs f or securit y violat ions and recent configurat ion changes
- /var/log/ns.log
- /var/log/import.log
- /var/log/aslearn.log
• Condit ional profile level t race helps ident if y t he t raf fic and violat ion records
- stop nstrace
- Appfw sets the window size to 9845 when NetScaler resets the connection due to an invalid http message.
• Monitor memory allocated and freed from Application Firewall components and objects during the target time period. It
helps in isolating the protection leading to high CPU usage.
- Profiler output
- Observe logs
- startURLClosure
- Formfiledconsistency
- CSRF
- Cookie protections
Ascert ain t hat aut oupdat e of signat ures is not leading t o high CP U (Disable t o confirm).
• Look for global memory statistics to ascertain that there is enough memory in the system and there are no memory
allocation failures by executing the following command:
- nsconmsg -d memstats
• Observe current allocated and maximum memory limits for appsecure, IP reputation, cache and compression by executing
the following command:
• Check appfw, DHT, IP reputation activity counters by executing the following command:
• Check all Application Firewall error counters by executing the following command:
• Inspect for CPU, APPFWREQ, AS and DHT counters by executing the following command:
- show cacheparameter
If required, reduce session timeout to ensure that session limits are not used by executing the following command:
Use the nsconmsg – d memst at s command. Observe the MEM_AP P SECURE field.
Use the st at appf w command to obtain meory consumption information.
Application Firewall does not automatically delete the logs after certain period of time or size.
All AppFw logs are archived in the /var/log/ns.log file. T he ns.log file performs the rollover task.
T here is no CLI option to increase Application Firewall memory. Application Firewall memory is platform-specific.
You may use the nsapimgr option to increase memory but it is not recommended.
T he max allowed memory for Application Firewall is determined by the platform and disabling IC does not impact memory
allocation.
• Since release 11.0, the streaming flag can be enabled on per profile basis to avoid buffering by executing the following
command:
Aslearn process
Example:
• Identify recent configuration commands executed prior to the observed problem by verifying the ns.log file:
- /var/log/ns.log
- /var/log/aslearn.log
• Identify the GUI and CLI command which is failing by executing the following command:
Examples:
Examples:
Ok
- If 2000 learn items (per protection) are reached, you cannot start learning any more for that protection
- If 20 MB size is reached for the database, stop learning for all protections
- du -h /var
To add signature:
1. Select the Def ault -signature and click add to make a copy.
3. Enable the target rules that are pertinent to your specific need.
– Block and Log actions are enabled by default. Stats is another option
• Optimize the processing overhead by enabling only those signatures that are applicable for protecting your
application.
• You can add your own customized rules to inspect incoming requests to detect various types of attacks, such as
SQL injection or cross-site scripting attacks.
• You can also add rules to inspect the responses to detect and block leakage of sensitive information such as credit
card numbers.
• Add multiple security check conditions to create your own customized check.
Following are some of the best practices you can follow when encountered with issues related to Signatures:
• Verify that the import command has succeeded on primary as well as secondary.
• Check ns.log to identify any errors during signature import and auto update.
• Check if the device is unable to access the Signature Update URL hosted on AWS for auto-update.
• Check for version mismatch between signature objects on the primary and secondary nodes.
• Monitor for High CPU Utilization (disable auto-update to rule out issue with signature update).
1. Enable tracing for the profile. You can use the show command to verify the configured setting.
2. Start collecting trace. You can continue to use all the options which are applicable for the nstrace command.
stop nstrace
Location of the trace: T he nstrace is stored in a time-stamped folder which is created in the /var/nstrace directory and can
be viewed using wireshark. You can tail the /var/log/ns.log file to see the log messages providing details regarding the
location of the new trace.
– View decrypted SSL traffic: HT T PS traffic is captured in plain text to allow for easier troubleshooting.
– Provides comprehensive view: Allows you to look at the entire request at the packet level, check the payload, view
logs to check what security check violation is being triggered and identify the match pattern in the payload. If the
payload consists of any unexpected data, junk strings, or non-printable characters (null character, \r or \n etc), they
are easy to discover in the trace.
– Expedite response time: Faster debugging on target traffic to do root cause analysis.
• Application Firewall sets window size to 9845 when resetting connection for invalid http messages.
– Malformed request received - connection reset [Client/Server sending invalid content-length header]
– T he iprep process takes about five minutes to start after you enable the reputation feature. T he IP reputation
feature might not work for that duration.
– Session timeout has a default value of 900 seconds. If session timeout is set to a low value, browser may trigger
false positives for checks which rely on sessionization (e.g CSRF, FFC). Check for session timeout and look at the session ID
(cs3 in CEF logs). If the sessionID is different, the session timeout could be the reason.
T his may be seen in scenarios where we come across a form field which is not in the forms in our session.
– T he session has timed out from when the form was sent to the client and when it was received.
• Trace HT ML Requests with Application Firewall Security Violation Logs on NetScaler Appliance
• https://regex101.com/
• Datasheets
– Ensuring enough memory for Application Firewall and configuring cache limit appropriately.
T he NetScaler analyzes incoming requests, sends requests for cacheable data to cache servers, and sends non-cacheable
requests and dynamic HT T P requests to origin servers.
Cache redirection is a policy-based feature. By default, requests that match a policy are sent to the origin server, and all
other requests are sent to a cache server. For testing or maintenance, you might want to skip policy evaluation and direct
all requests to the cache or to the origin server.
You can combine content switching with cache redirection to cache selective content and serve content from specific
cache servers for specific types of requested content.
A NetScaler configured for cache redirection can be deployed at the edge of a network, in front of the origin server, or
anywhere along the network backbone. In an edge deployment, commonly used by Internet Service Providers (ISPs), cable
companies, content delivery distribution networks, and enterprise networks, the NetScaler resides directly in front of the
clients. In a server-side deployment, the NetScaler is closer to the origin servers.
Cache redirection is used most commonly with the HT T P service type, but it also supports the secure HT T PS protocol.
Warning
T he Classic Cache Redirection policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to
use the Advanced Cache redirection policies. You can also use the nspepi utility tool for the conversion.
A cache redirection virtual server applies cache redirection policies to each incoming request. By default, if a request
matches one of the configured policies, it is considered non-cacheable, and the NetScaler appliance sends it to the origin
server. Other requests are sent to a cache server. T his behavior can be reversed, so that requests that match configured
cache redirection policies are sent to cache servers.
T he NetScaler provides a set of policies for cache redirection. If these built-in policies are not adequate for your
deployment, you can configure user-defined cache redirection policies.
Note: Once you have determined which built-in cache redirection policies to use, or have created user-defined policies,
proceed with configuring cache redirection. T o use this feature, you must configure at least one cache redirection virtual
server, and, for normal operation, you must bind at least one cache redirection policy to that virtual server.
Built-in cache redirection policies can be directly bound to a virtual server and do not need further configuration.
Cache redirection policies use two types of NetScaler expressions languages, classic and default syntax. For more information about these languages, see Policies and Expressions.
T he NetScaler appliance provides the following built-in classic cache redirection policies:
bypass-non-get Bypass the cache if the request uses an HT T P method other than GET.
bypass-cache-control Bypass the cache if the request header contains a Cache-Control: no-cache or Cache-Control: no-store header, or if the HT T P request contains a pragma header.
bypass-dynamic-url Bypass the cache if the URL suggests that the content is dynamic, as indicated by the presence of any of the following extensions:
cgi
asp
exe
cfm
ex
shtml
htx
Also bypass the cache if the URL starts with any of the following:
/cgi-bin/
/bin/
/exec/
bypass-urltokens Bypass the cache because the request is dynamic, as indicated by one of the following tokens in the URL: ?, !, or =.
bypass-cookie Bypass the cache for any URL that has a cookie header and an extension other than .gif or .jpg.
NetScaler appliances provide the following two built-in actions for the default syntax cache redirection policies:
CACHE
ORIGIN
As implied by their names, they direct the request to the cache server or the origin server, respectively.
Note: If you are using the built-in default syntax cache redirection policy, you cannot modify the action.
T he NetScaler appliance provides the following built-in default syntax cache redirection policies:
bypass-non-get_adv Bypass the cache if the request uses an HT T P method other than GET.
bypass-cache-control_adv Bypass the cache if the request header contains a Cache-Control: no-cache or Cache-Control: no-store header, or if the HT T P request contains a pragma header.
bypass-dynamic-url_adv Bypass the cache if the URL suggests that the content is dynamic, as indicated by the presence of any of the following extensions:
cgi
asp
exe
cfm
ex
shtml
/cgi-bin/
/bin/
/exec/
bypass-urltokens_adv Bypass the cache because the request is dynamic, as indicated by one of the following tokens in the URL: ?, !, or =.
bypass-cookie_adv Bypass the cache for any URL that has a cookie header and an extension other than .gif or .jpg.
Updated: 2013-08-23
You can display the available cache redirection polices by using the command line interface or the configuration utility.
To display the built-in cache redirection policies by using the command line interface
At the command prompt, type:
You do not explicitly configure actions for cache redirection policies. By default, the NetScaler appliance considers any request that matches a policy
to be non-cacheable and directs the request to the origin server instead of the cache.
Cache redirection policies based on the classic policy format are called classic cache redirection policies. Each such policy has a name and includes a
classic expression or a set of classic expressions that are combined by using logical operators.
For classic cache redirection policies, you do not explicitly configure actions for the policies. By default, the NetScaler appliance considers any request
that matches a policy to be non-cacheable and directs the request to the origin server instead of the cache.
Cache redirection policies based on the newer policy format are called default syntax redirection policies. Such policy has a name and includes a
default syntax expression, or a set of default syntax expressions that are combined by using logical operators, and the following built-in actions:
CACHE
ORIGIN
For more information about classic expressions and default syntax expressions, see Policies and Expressions.
At the command prompt, type the following commands to add a cache redirection policy and verify the configuration:
Examples
> add cr policy Policy-CRD-2 -rule "REQ.HTTP.METHOD == POST && (REQ.HTTP.URL == /*.cgi || REQ.HTTP.URL != /*.gif)"
Done
> show cr policy Policy-CRD-2
Cache-By-Pass RULE: REQ.HTTP.METHOD == POST && (REQ.HTTP.URL == '/*.cgi' || REQ.HTTP.URL != '/*.gif') Policy:Policy-CRD-2
Done
>
Policy that evaluates a header:
Examples
> add cr policy crpol11 -rule "http.req.method.eq(post) && (HTTP.REQ.URL.ENDSWITH(\".gif\") || HTTP.REQ.URL.ENDSWITH(\".cgi\"))" -action cache
Done
> show cr policy crpol11
Policy: crpol11 Rule: http.req.method.eq(post) && (HTTP.REQ.URL.ENDSWITH(".gif") || HTTP.REQ.URL.ENDSWITH(".cgi")) Action: CACHE
Done
>
Policy that evaluates a header:
T o modify a cache redirection policy, use the set cr policy command, which is just like add cr policy command, except that you enter the name of
an existing policy.
T o remove a policy, use the rm cr policy command, which accepts only the <name> argument. If the policy is bound to a virtual server, you have to
unbind the policy, before you can remove it.
For the details of unbinding a cache redirection policy, see "Unbinding a Policy from a Cache Redirection Virtual Server."
Expression T ype-General
Flow T ype -REQ
Protocol -HT T P
Qualifier -URL
Operator - !=
Value* - /*.jpeg
T he simple expression in the following example checks for an If-Modified-Since header in a request:
T he name can begin with a letter, number, or the underscore symbol, and can consist of from one to 127 letters, numbers, and the hyphen (-),
period (.) pound (#), space ( ), at (@), equals (=), and underscore (_) symbols. You should choose a name that will make it easy for others to tell what
type of content this policy was created to detect.
4. Choose the type of compound expression that you want to create. Your choices are:
Mat ch Any Expression . T he policy matches the traffic if one or more individual expressions match the traffic.
Mat ch All Expressions . T he policy matches the traffic only if every individual expression matches the traffic.
T abular Expressions . Switches the Expressions list to a tabular format with three columns. In the rightmost column, you place one of the
following operators:
T he AND [ && ] operator, to require that, to match the policy, a request must match both the current expression and the following
expression.
T he OR [ || ] operator, to require that, to match the policy, a request must match either the current expression or the following expression,
or both. Only if the request does not match either expression does it not match the policy.
You can also group expressions in nested subgroups by selecting an existing expression and clicking one of the following operators:
T he BEGIN SUBGROUP [+ ( ] operator, which tells the NetScaler appliance to begin a nested subgroup with the selected expression. (T o
remove this operator from the expression, click -( .)
T he END SUBGROUP [+ ) ] operator, which tells the NetScaler appliance to end the current nested subgroup with the selected expression.
(T o remove this operator from the expression, click -) .)
Advanced F ree-F orm. Switches off the Expressions Editor entirely and turns the Expressions list into a text area in which you can type a
compound expression. T his is both the most powerful and the most difficult method of creating a policy expression, and is recommended only
for those thoroughly familiar with the NetScaler classic expressions language.
For more information about creating classic expressions in the Advanced Free-Form text area, see "Configuring Classic Policies and Expressions".
Caution: If you switch to Advanced Free Form expression editing mode, you cannot switch back to any of the other modes. Do not choose this
expression editing mode unless you are sure that you want to use it.
5. If you chose Match Any Expression, Match All Expressions, or T abular Expressions, click Add to display the Add Expression dialog box.
You should leave the expression type set to General for cache redirection policies.
6. In the Flow T ype drop-down list, choose a flow type for your expression.
T he flow type determines whether the policy examines incoming or outgoing connections. You have two choices:
T he protocol determines the type of information that the policy examines in the request or response. Depending upon whether you chose REQ or
RES in the previous drop-down list, either all four or only three of the following choices are available:
T he contents of the Qualifier drop-down list depend on which protocol you chose. T he following table describes the choices available for each
T able 1. Cache Redirect ion P olicy Qualif iers Available f or Each P rot ocol
CLIENT .CERT .VALIDFROM Date from which the client certificate is valid. (T he start date.)
CLIENT .CERT .VALIDT O Date after which the client certificate is no longer valid. (T he end date.)
9. Choose the operator for your expression from the Operator drop-down list.
Your choices depend on the qualifier you chose in the previous step. T he complete list of operators that can appear in this drop-down list is:
10. If the Value text box is visible, type the appropriate string or number into the text box.
For example, if you want this policy to select requests sent to the host shopping.example.com, you would type that string in the Value text box.
11. If you chose HEADER as the qualifier, type the header you want in the Header Name text box.
12. Click OK to add your expression to the Expression list.
13. Repeat steps 4 through 11 to create additional expressions.
14. Click Close to close the Add Expression dialog box and return to the Create Cache Redirection Policy dialog box.
T ransparent . A transparent cache can reside on a variety of points along a network backbone to alleviate traffic along
the delivery route. In transparent mode, the cache redirection virtual server intercepts all traffic flowing to the NetScaler
appliance and applies cache redirection policies to determine whether content should be served from the cache or from
the origin server.
F orward proxy . A forward proxy cache server resides on the edge of an enterprise LAN and faces the WAN. In the
forward proxy mode, the cache redirection virtual server resolves the hostname of the incoming request by using a DNS
server and forwards requests for non-cacheable content to the resolved origin servers. Cacheable requests are sent to
the configured cache servers.
Reverse proxy . Reverse proxy caches are configured for specific origin servers. Incoming traffic directed to the reverse
proxy, can either be served from a cache server or be sent to the origin server with or without modification to the URL.
By default, cacheable requests are sent to a cache server, and non-cacheable requests to the origin server. For example,
when the NetScaler appliance receives a request that is directed to a web server, it compares the HT T P headers in the
request with a set of policy expressions. If the request does not match the policy, the appliance forwards the request to a
cache server. If the request does match a policy, the appliance forwards the request, unchanged, to the web server.
For details on how to modify this default behavior, see "Directing Policy Hits to the Cache instead of the Origin."
To configure transparent redirection, first enable cache redirection and load balancing, and configure edge mode. T hen,
create a cache redirection virtual server with a wildcard IP address (*), so that this virtual server can receive traffic coming to
the NetScaler on any IP address the appliance owns. To this virtual server, bind cache redirection policies that describe the
types of requests that should not be cached. T hen, create a load balancing virtual server that will receive traffic from the
cache redirection virtual server for cacheable requests. Finally, create a service that represents a physical cache server and
bind it to the load balancing virtual server.
At the command prompt, type the following command to enable cache redirection and load balancing and verify the
settings:
enable ns feature cr lb
show ns feature
Example
...
...
...
T his mode turns on the collection of statistics for the dynamically learned services and is typically used in transparent
deployments for cache redirection.
At the command prompt, type the following commands to enable edge mode and verify the setting:
Example
A transparent cache redirection virtual server uses an IP address of * and a port number, usually 80, that can accept HT T P
traffic sent to any IP address that the NetScaler represents. As a result, you can configure only one transparent cache
redirection virtual server. Any additional cache redirection virtual servers that you configure must be forward proxy or reverse
proxy redirection servers.
At the command prompt, type the following commands to add a cache redirection virtual server and verify the
configuration:
add cr vserver <name> <serviceT ype> [<IPAddress> <port> ] [-cacheT ype <cacheT ype>] [-redirect <redirect>]
show cr vserver [<name>]
Example
T o modify a virtual server, use the set cr vserver command, which is just like using the add cr vserver command, except
that you enter the name of an existing virtual server.
T o remove a virtual server, use the rm cr vserver command, which accepts only the <name> argument.
Name*— name
4. In the Protocol drop-down list, select a supported protocol (for example, HT T P ). If the virtual server is to receive traffic
on a port other than the standard port for the selected protocol, enter a new value in the Port field.
5. Click the Advanced tab.
6. Verify that Cache T ype is set to T RANSPARENT and Redirect is set to POLICY.
7. Click Create, and then click Close. T he Cache Redirection Virtual Servers pane displays the new virtual server.
8. Select the new cache redirection virtual server to display the details of its configuration.
Example
Example
Each cache server is represented on the appliance by a service, which is bound to a load balancing virtual server that receives
requests from the cache redirection virtual server and forwards those requests to the servers.
For details on configuring load balancing virtual servers and other configuration options, see "Load Balancing."
At the command prompt, type the following commands to create a load balancing virtual server and verify the
configuration:
Example
4. In the Protocol* drop down list, select a supported protocol (for example, HT T P ). If the virtual server is to receive traffic
on a port other than the well-known port for the selected protocol, enter a new value in the Port field.
5. Click Create, and then click Close. T he Load Balancing Virtual Servers pane displays the new virtual server.
At the command prompt, type the following commands to create an HT T P service and verify the configuration:
add service <name> <IP> <serviceT ype> <port> -cacheT ype <cacheT ype>
show service [<name>]
Example
4. In the Protocol* drop-down list, select a supported protocol (for example, HTTP).
5. Click Create, and then click Close.
Example
T o unbind a service, use the unbind lb vserver command instead of bind lb vserver.
To bind/unbind a service f rom a load balancing virtual server by using the configuration utility
However, if you want to configure a fully transparent cache (a cache configuration in which the cache service receives the
client’s IP address and port number), you must not only enable the USIP option, either globally or on the cache service, but
also disable the Use Proxy Port setting, either globally or on the cache service. Disabling the Use Proxy Port setting enables
the appliance to use the client’s source port as the source port when it connects to the cache service, and ensures a fully
transparent cache configuration.
For more information about configuring the Use Proxy Port option globally or on a service, see "Configuring the Source Port
for Server-Side Connections."
A method to solve this problem is to assign a source port range to the NetScaler appliance. T his allotment enables network
devices to unambiguously identify the NetScaler appliance that sent the request.
To assign a source port range to a NetScaler appliance by using the command line interf ace
If you want to override this functionality and let the cache redirection virtual server decide whether the request should be
served from the cache or not, configure the particular load balancing virtual server to be cacheable.
Such a configuration is typically used when an ISP uses a NetScaler appliance at the edge of its network and all traffic
flows through the appliance.
To enable load balancing virtual servers to redirect requests to the cache by using the command line
interf ace
Example
When using transparent cache redirection, you may want to turn off cache redirection for load balancing virtual servers
that always direct traffic to origin servers.
To turn of f caching f or a load balancing virtual server by using the command line interf ace
T o turn off caching for a load balancing virtual, use the unset lb vserver command instead of set lb vserver. Specify a value
of NO value for the -cacheable parameter.
To enable or disable load balancing virtual servers to redirect requests to the cache by using the
configuration utility
When the NetScaler is configured as a forward proxy, users must modify their browsers so that the browser sends requests
to the forward proxy instead of the destination servers.
A forward proxy cache redirection virtual server on the NetScaler compares the request with a policy for caching. If the
request is not cacheable, the NetScaler queries a DNS load balancing virtual server for resolution of the destination, and
then sends the request to the origin server. If the request is cacheable, the NetScaler forwards the request to a load
balancing virtual server for the cache.
T he NetScaler relies on a host domain name or IP address in the request's HOST header to determine the requested
destination. If there is no HOST header in the request, the appliance inserts a HOST header based on the destination IP
address in the request.
Typically, the NetScaler appliance acts as a forward proxy in an enterprise LAN. In such a configuration, the appliance
resides at the edge of an enterprise LAN and intercepts client requests before they are fanned out to the WAN.
Configuring the appliance in the forward proxy mode reduces traffic on the WAN.
To configure forward proxy cache redirection, first enable load balancing and cache redirection on the NetScaler. T hen,
configure a DNS load balancing virtual server and associated services. Also configure a load balancing virtual server and bind
to it appropriate services for the cache. Configure a forward proxy cache redirection virtual server and bind the DNS and
load balancing virtual servers to it. You must also configure caching policies and bind them to the cache redirection virtual
server. To complete the setup, configure the client browsers to use the forward proxy.
For details on how to enable cache redirection and load balancing on the NetScaler, see "Enabling Cache Redirection and
Load Balancing."
For details on how to create a load balancing virtual server, see "Creating a Load Balancing Virtual Server."
For details on how to configure services that represent the cache server, see "Configuring an HT T P Service."
For details on how to bind the service to a virtual server, see "Binding/Unbinding a Service to/from a Load Balancing Virtual
Server."
For details on how to create a forward proxy cache redirection server, see "Configuring a Cache Redirection Virtual Server",
and create a virtual server of type T RANSPARENT or FORWARD.
For details on binding cache redirection policies to the cache redirection virtual server, see "Configuring a Cache Redirection
Policy."
At the command line, type the following commands to create a DNS service and verify the configuration :
Example
4. In the Protocol* drop down list, select a supported protocol (for example, DNS).
5. Click Create, and then click Close.
At the command line, type the following commands to create a DNS load balancing virtual server and verify the
configuration:
Example
At the command prompt, type the following commands to bind the DNS service to the load balancing virtual server and
verify the configuration:
Example
Refer the documentation for your browser to configure the browser to use a forward proxy. Specify the IP address and
port number of the forward proxy cache redirection virtual server for this configuration.
Unlike a transparent proxy cache, the reverse proxy cache has its own IP address and can replace destination domains and URLs in
a non-cacheable request with new destination domains and URLs.
You can deploy reverse proxy cache redirection at the origin-server side or at the edge of a network. When deployed at the origin
server, the reverse proxy cache redirection virtual server is a front-end for all requests to the origin server.
In the reverse proxy mode, when the NetScaler receives a request, a cache redirection virtual server evaluates the request and
forwards it to either a load balancing virtual server for the cache or a load balancing virtual server for the origin. T he incoming
request can be transformed by changing the host header or the host URL before they it is sent to the backend server.
To configure reverse proxy cache redirection, first enable cache redirection and load balancing. T hen, configure a load balancing
virtual server and services to send cacheable requests to the cache servers. Also configure a load balancing virtual server and
associated services for the origin servers. T hen, configure a reverse proxy cache redirection virtual server and bind relevant cache
redirection policies to it. Finally, configure mapping policies and bind them to the reverse proxy cache redirection virtual server.
T he mapping policies have an associated action that enables the cache redirection virtual server to forward any non-cacheable
request to the load balancing virtual server for the origin.
For details on how to enable cache redirection and load balancing on the NetScaler, see "Enabling Cache Redirection and Load
Balancing."
For details on how to create a load balancing virtual server, see "Creating a Load Balancing Virtual Server."
For details on how to configure services that represent the cache server, see "Configuring an HT T P Service."
For details on how to bind the service to a virtual server, see "Binding/Unbinding a Service to/from a Load Balancing Virtual Server."
For details on how to create a reverse proxy cache redirection server, see "Configuring a Cache Redirection Virtual Server", and
create a virtual server of type REVERSE.
For details on binding built-in cache redirection policies to the cache redirection virtual server, see "Binding Policies to the Cache
Redirection Virtual Server."
If an incoming request is non-cacheable, the reverse-proxy cache redirection virtual server replaces the domain and URL in the
request with the domain and URL of a target origin server and forwards the request to the load balancing virtual server for the
origin.
A mapping policy enables the reverse proxy cache redirection virtual server to replace the destination domain and URL and forward
the request to the load balancing virtual server for the origin.
A mapping policy must first translate the domain and the URL, and then pass the request on to the origin load balancing virtual
A mapping policy can map a domain, a URL prefix, and a URL suffix, as follows:
Domain mapping: You can map a domain without a prefix or suffix. T he domain mapping is the default mapping for the virtual
server (for example, mapping www.mycompany.com to www.myrealcompany.com).
Prefix mapping: You can replace a specified pattern prefixed as part of the URL (for example, mapping
www.mycompany.com/sports/index.html to www.mycompany.com/news/index.html).
Suffix mapping: You can replace the file suffix in the URL (for example, mapping www.mycompany.com/sports/index.html to
www.mycompany.com/sports/index.asp).
T he source and the destination strings being mapped must be similar. If you specify a source domain, you must specify a
destination domain, and if you specify a source suffix, you must specify a destination suffix. Similarly, if you specify an exact URL
from the source, the target URL must also be an exact URL.
Once you configure mapping policies for the reverse proxy mode, you must bind them to the cache redirection virtual server.
You can use combinations of the source URL, target URL, and source and target domains to configure all three types of domain
mapping.
To configure a mapping policy for reverse proxy mode by using the command line
interface
At the command prompt, type the following command to add a policy map and verify the configuration:
add policy map <mapPolicyName> -sd <string> [-su <string>] [-td <string>] [-tu <string>]
show policy map [<mapPolicyName>]
Example
> add policy map myOtherMappingPolicy -sd www.mycompany.com -td www.myrealcompany.com -su /news.html -tu /realnews.html
Done
> show policy map myOtherMappingPolicy
1) Name: myOtherMappingPolicy
Source Domain: www.mycompany.com Source Url: /news.html
Target Domain: www.myrealcompany.com Target Url: /realnews.html
Done
>
To configure a mapping policy for reverse proxy mode by using the configuration
Name*- mapPolicyName
Source Domain*-sd
T arget Domain*-td
Source URL-su
T arget URL-tu
* A required parameter
4. Click Create, and then click Close. T he Map pane displays the new mapping policy.
To bind the mapping policy to the cache redirection virtual server by using the
command line interface
At the command prompt, type the following commands to bind the mapping policy to the cache redirection virtual server and
verify the configuration:
Example
In selective cache redirection, the NetScaler appliance intercepts a client request and forwards non-cacheable requests to
the original destination in the client request. For cacheable requests, the appliance sends the requests to the destination
cache server that can serve content of a specific content type.
Selective cache redirection involves configuring content switching policies in addition to cache redirection policies. T he
NetScaler first evaluates the cache redirection policies that are bound to the cache redirection virtual server. If a request
matches a cache redirection policy, the cache redirection virtual server sends the request to the origin server or a load
balancing virtual server for the origin. If no cache redirection policies match the request, the NetScaler evaluates the
content switching policies bound to the cache redirection virtual server. If a content switching policy matches the request,
the cache redirection virtual server redirects the request to a load balancing virtual server for the cache.
To configure selective cache redirection, first enable cache redirection, load balancing, and content switching on the
NetScaler appliance. T hen, configure a load balancing virtual server for the cache and an associated HT T P service. After this,
configure a cache redirection virtual server and bind both the cache redirection and content switching policies to it. Once
you have bound the policies, you can configure the virtual server to give precedence to either rule based or URL based
content-switching policies.
When configured for transparent mode cache redirection in an edge deployment topology, the NetScaler sends all
cacheable HT T P traffic to a transparent cache farm. Clients access the Internet through the NetScaler, which is configured
as a Layer 4 switch that receives traffic on port 80.
T he NetScaler can direct requests for images (for example, .gif and .jpg files) to one server in the transparent cache farm,
and all other requests for static content to other servers in the farm. For this configuration, you configure content
switching policies to send images to the image cache and send all other cacheable content to a default cache.
Note: T he configuration described here is for transparent selective cache redirection. T herefore, it does not require a load
balancing virtual server for the origin, as would a reverse proxy configuration.
To configure this type of selective cache redirection, first enable cache redirection, load balancing, and content switching.
T hen, configure a load balancing virtual server for the cache and configure an associated HT T P service. T hen, configure a
cache redirection virtual server and create and bind both cache redirection and content switching policies to this virtual
server.
For details on how to enable cache redirection and load balancing on the NetScaler, see "Configuring Cache Redirection."
enable ns feature CS
show ns feature
Example
For details on how to create a load balancing virtual server, see "Creating a Virtual Server."
For details on how to configure services that represent the cache server, see "Configuring an HT T P Service."
For details on how to bind the service to a virtual server, see "Binding/Unbinding a Service to/from a Load Balancing Virtual
Server."
For details on how to create a transparent proxy cache redirection server, see "Configuring a Cache Redirection Virtual
Server", and create a virtual server of type T RANSPARENT.
For details on binding built-in cache redirection policies to the cache redirection virtual server, see "Binding Policies to the
Cache Redirection Virtual Server."
To identify requests that contain a .gif or .jpeg extension as cacheable, you configure a cache redirection policy and bind it
to the cache redirection virtual server.
Note: If a request matches a policy, the NetScaler appliance forwards it to the origin server. As a result, in the following
procedure, you configure policies to match requests that do not have ".gif" or ".jpeg" extensions.
To configure cache redirection for a specific type of content, configure a policy that uses a simple expression, as described
in "Configuring a Cache Redirection Policy."
After defining the content switching policy, you bind it to a cache redirection virtual server and specify a load balancing
virtual server. Requests that match the policy are forwarded to the named load balancing virtual server. Requests that do
not match the content switching policy are forwarded to the default load balancing virtual server for the cache.
For more details about the content switching feature and configuring content switching policies, see "Content Switching."
You must first create the content switching policy and then bind it to the cache redirection virtual server.
To create a content switching policy by using the command line interf ace
Examples
T he Expression portion of the dialog box changes to match your choice. T he default syntax Expression view has fewer
elements than does the classic syntax Expression view. In the default syntax Expression view, instead of a preview
window, a button provides access to an expression evaluator. T he evaluator evaluates the expression you entered, to
verify that it is valid, and displays an analysis of the expression's effect.
To bind the content switching policy to a cache redirection virtual server by using the command line
interf ace
At the command prompt, type the following commands to bind the content switching policy to a cache redirection virtual
server and verify the configuration:
Example
Once you bind content switching policies of either type to a cache redirection virtual server, you can configure the virtual
server to give precedence to either rule based or URL based policies. T his will, in turn, decide which servers the particular
requests are directed to.
To configure precedence for policy evaluation, use the precedence parameter, which specifies the type of policy (URL or
RULE) that takes precedence on the content redirection virtual server.
To configure precedence f or policy evaluation by using the command line interf ace
At the command prompt, type the following commands to configure precedence for policy evaluation and verify the
configuration:
Example
To view statistics for a specific cache redirection virtual servers, use the name parameter to specify the name of the virtual
server for which statistics will be displayed. Otherwise, statistics for all cache redirection virtual servers are displayed.
Maximum Length: 127
To view statistics f or a cache redirection virtual server by using the command line interf ace
Vserver Summary
IP port Protocol State
Vser...CRD-1 0.0.0.0 80 HTTP UP
VServer Stats:
Rate (/s) Total
Requests 0 0
Responses 0 0
Request bytes 0 0
Response bytes 0 0
Done
>
To view statistics f or a cache redirection virtual server by using the configuration utility
Omit the server name to display basic statistics for all cache redirection virtual servers. Include the server name to display
detailed statistics for that virtual server, including number and size of requests and responses that pass through the virtual
server
To view the statistics of a cache redirection virtual server by using the monitoring and dashboard utilities
1. T o view the statistics by using the monitoring utilities, click the Monitoring tab.
2. In the Select Group drop-down menu, choose CR Virtual Servers. A list of cache redirection virtual servers appears.
3. T o view the statistics by using the dashboard utilities, click the Dashboard tab.
Examples
You can change the default behavior so that when a request matches a policy, the request is forwarded to a load balancing
virtual server for the cache.
To change the destination for a policy hit to the origin or the cache, use the onPolicyMatch parameter, which specifies
where to send requests that match the cache redirection policy.
Note: For this option to work, you must select the cacheredirection type as POLICY.
Possible values: CACHE, ORIGIN
To change the destination f or a policy hit to the origin or the cache by using the command line interf ace
At the command prompt, type the following commands to change the destination for a policy hit and verify the
configuration:
Example
To specify a backup cache redirection virtual server, use the backupVServer parameter, which specifies Backup Virtual Server.
Maximum Length: 127
At the command prompt, type the following commands to specify a backup cache redirection virtual server and verify the
configuration:
Example
You can configure the NetScaler to send ICMP responses to PING requests according to your settings. On the IP address
corresponding to the virtual server, set the ICMP RESPONSE to VSVR_CNT RLD, and on the virtual server, set the ICMP
VSERVER RESPONSE.
Updated: 2013-08-22
You can specify expiration of client requests by setting a timeout value for the cache redirection virtual server. T he timeout
value is the number of seconds for which the cache redirection virtual server waits to receive a response for the client
request.
To configure a time-out value, use the cltT imeout parameter, which specifies the time, in seconds, after which the
NetScaler appliance closes any idle client connections. T he default value is 180sec for HT T P/SSL-based services and
9000sec for TCP-based services.
Example
Updated: 2013-08-23
A Via header lists the protocols and recipients between the start and end points for a request or a response and informs
the server of proxies through which the request was sent. You can configure the cache redirection virtual server to insert a
Via header in each HT T P request. T he via parameter is enabled by default when you create a cache redirection virtual server.
To enable or disable Via-header insertion in client requests, use the via parameter, which specifies the state of the system in
inserting a Via header in the HT T P requests.
Default value: ON
Example
Updated: 2013-11-08
You can configure the NetScaler appliance to reuse TCP connections to the cache and origin servers across client
connections. T his can improve performance by saving the time required to establish a session between the server and the
NetScaler. T he reuse option is enabled by default when you create a cache redirection virtual server.
To enable or disable the reuse of TCP connections, use the reuse parameter, which specifies the state of reuse of TCP
connections to the cache or origin servers across client connections.
Default value: ON
To enable or disable the reuse of TCP connections by using the command line
interface
At the command prompt, type:
Updated: 2013-08-22
T he down state flush option performs delayed cleanup of connections on a cache redirection virtual server. T he down
state flush option is enabled by default when you create a cache redirection virtual server.
To enable or disable the down state flush option, set the downStateFlush parameter.
To enable of disable the down state flush option by using the command line
interface
At the command prompt, type the following commands to configure delayed connection clean up and verify the
configuration:
You can solve the problem by deploying the NetScaler appliances in two tiers (layers), where the appliances in the upper tier
load balance those in the lower tier and the appliances in the lower tier load balance the cache servers. T his arrangement is
called n-tier cache redirection.
For purposes such as auditing and security, an ISP has to track client details such as the IP address, information provided,
and the time of the interaction. T herefore, client connections through a NetScaler appliance have to be fully transparent.
However, if you configure transparent cache redirection, with the NetScaler appliances deployed in parallel, the IP address
of the client has to be shared among all the appliances. Sharing of the client IP address creates a conflict that makes
network devices, such as routers, cache servers, origin servers, and other NetScaler appliances, unable to determine the
appliance, and therefore the client, to which the response should be sent.
To solve the problem, NetScaler n-tier cache redirection splits the source port range among the appliances in the lower tier
and includes the client IP address in the request sent to the cache servers. T he upper-tier NetScaler appliances are
configured to do sessionless load balancing in order to avoid unnecessary load on the appliances.
When the lower-tier NetScaler appliance communicates with a cache server, it uses a mapped IP address (MIP) to represent
the source IP address. T herefore, the cache server can identify the NetScaler from which it received the request and send
the response to the same NetScaler.
T he lower-tier NetScaler appliance inserts the client IP address into the header of the request sent to the cache server. T he
client IP in the header helps the NetScaler to determine the client to which the packet should be forwarded when it
receives the response from a cache server, or the origin server in case of a cache miss. T he origin server determines the
response to be sent according to the client IP inserted in the request header.
T he origin server sends the response to an upper-tier NetScaler, including the source port number from which the origin
server received the request. T he entire source port range, 1024 to 65535, is distributed among the lower-tier NetScaler
appliances. Each lower-tier appliance is exclusively assigned a group of addresses within the range. T his allotment enables
the upper-tier appliance to unambiguously identify the lower-tier NetScaler appliance that sent the request to the origin
server. T he upper-tier appliance can therefore forward the response to the correct lower-tier appliance.
T he upper-tier NetScaler appliances are configured to do policy-based routing, and the routing policies are defined to
determine the IP address of the destination NetScaler from the source port range.
Configure the cache redirection port range on the NetScaler. Assign an exclusive range to each lower-tier NetScaler.
Configure a load balancing virtual server and enable MAC-based redirection.
Create a service for each cache server that is to be load balanced by this NetScaler. When creating the service, enable
insertion of client IP in the header. T hen, bind all the services to the load balancing virtual server.
Configure a transparent mode cache redirection virtual server with the following settings:
Enable the Origin USIP option.
Add a source IP expression to include the client IP in the header.
Enable the Use Port Range option.
T he following figure shows how cache redirection works when a client request is cacheable and the response is sent from a
cache server.
Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler appliances, L2NS1, L2NS2,
Traffic Flow
1. Client sends a request, and the router forwards it to L1NS1.
2. L1NS1 load balances the request to L2NS2.
3. L2NS2 load balances the request to the cache server CRS1, and the request is cacheable. L2NS2 includes the client IP in
the request header.
4. CRS1 sends the response to L2NS2 because L2NS2 used its MIP as the source IP address when connecting to CRS1.
5. With the help of the client IP address in the request header, L2NS2 identifies the client from which the request came.
L2NS2 directly sends the response to the router, avoiding unnecessary load on the NetScaler in the upper tier.
6. T he router forwards the response to Client A.
T he following figure shows how cache redirection works when a client request is sent to an origin server for a response.
Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler appliances, L2NS1, L2NS2,
L2NS3, and L2NS4, are deployed in the lower tier. Client A sends a request, which is forwarded by the router. Cache servers
CRS1, CRS2, and CRS3 service the cache requests. Origin Server O services the uncached requests.
Traffic Flow
1. Client sends a request, and the router forwards it to L1NS1.
2. L1NS1 load balances the request to L2NS2.
3. T he request is uncacheable (cache bypass). T herefore, L2NS2 sends the request to the origin server through the router.
4. T he origin server sends the response to an upper-tier NetScaler, L1NS2.
T he following figure shows how cache redirection works when a client request is not cached.
Two NetScaler appliances, L1NS1 and L1NS2, are deployed in the upper tier, and four NetScaler appliances, L2NS1, L2NS2,
L2NS3, and L2NS4, are deployed in the lower tier. Client A sends a request, which is forwarded by the router. Cache servers
CRS1, CRS2, and CRS3 service the cache requests. Origin Server O services the uncached requests.
Traffic Flow
1. Client sends a request, and the router forwards it to L1NS1.
2. L1NS1 load balances the request to L2NS2.
3. L2NS2 load balances the request to the cache server CRS1 because the request is cacheable.
4. CRS1 does not have the response (cache miss). CRS1 forwards the request to the origin server through the NetScaler in
the lower tier. L2NS3 intercepts the traffic.
5. L2NS3 takes the client IP from the header and forwards the request to the origin server. T he source port included in the
packet is the L2NS3 port from which the request is sent to the origin server.
6. T he origin server sends the response to an upper-tier NetScaler, L1NS2.
7. According to the PBR policies, L1NS2 forwards the traffic to the appropriate NetScaler in the lower tier, L2NS3.
8. L2NS3 forwards the response to the router.
9. T he router forwards the response to Client A.
add lb vserver <name>@ ANY * <port> -persistenceT ype <persistenceMethod> -lbMethod <lbMethod> -m MAC -
sessionless ENABLED -cltT imeout <client_T imeout_Value>
bind lb vserver <name>@ <serviceName>
Run this command for each service to be bound.
enable ns mode l3
add ns pbr <name> <action> -srcPort <sourcePortNumber> -destPort <startPortNumber-endPortNumber> -nexthop
<serviceIpAddress> -protocol T CP
apply ns pbrs
1. Enable L3 mode:
1. In the navigation pane, click System, and then click Settings.
2. In the Settings group, click the Configure modes link.
3. Select the Layer 3 Mode (IP Forwarding) check box.
4. Click OK.
2. Configure policy-based routing (PBR):
1. Navigate to System > Network > PBRs.
1. In the Policy-Based Routing (PBRs) pane, click Add.
2. T ype a name for the PBR.
3. Select the action as Allow.
4. In the Next Hop box, type the IP address of the service, which represents a lower-tier NetScaler.
5. Select T CP from the Protocol drop-down list.
6. T ype the source port and the range of the destination port corresponding to the lower-tier NetScaler being added.
7. Click Create.
8. In the details pane, select the PBR and click Apply.
9. Repeat Step (i) to Step (vii) for each lower-tier NetScaler.
3. Create a service for each lower-tier NetScaler:
1. Navigate to T raffic Management > Load Balancing > Services.
1. In the details pane, click Add.
2. Specify the name, protocol, IP address, and port. T he protocol should be ANY.
3. Click Create.
4. Configure a load balancing virtual server:
1. Navigate to T raffic Management > Load Balancing > Virtual Servers.
add service <name>@ <cacheServiceIP> <serviceT ype> <port> -cip ENABLED "ClientIP" – cachetype transparent
Repeat for each cache server.
add cr vserver <name> <serviceT ype> * <port> -srcIPExpr "HT T P.REQ.HEADER(\"ClientIP\")" -originusip ON –
usePortRange ON
set ns param-crPortRange <startPortNumber-endPortNumber>
Note
T his feature is available with a NetScaler enterprise or platinum edition license.
A NetScaler cluster is a group of nCore appliances working together as a single system image. Each appliance of the cluster
is called a node. T he cluster can have one appliance or as many as 32 NetScaler nCore hardware or virtual appliances as
nodes. For more information on SDX hardware appliances, see "Setting up a Cluster of NetScaler Instances".
T he client traffic is distributed between the nodes to provide high availability, high throughput, and scalability.
To create a cluster, you must add the appliances as cluster nodes, set up communication between the nodes, set up links to
the client and server networks, configure the appliances, and configure the distribution of client and server traffic.
T he following table lists the NetScaler configurations that are not supported in NetScaler 10 and also gives the status of the features in subsequent releases. For the features that are supported
since the first cluster release, click here.
Important
- Unless specified otherwise in this table, all NetScaler features are supported in a cluster.
- T he "Node-level" entry in the table indicates that the feature is supported only on individual cluster nodes.
SSL FIPS No No No No No No
Note: The content switching feature is supported from NetScaler 10.1 onwards.
Policy-based logging for content switching policies No Yes Yes Yes Yes Yes
DNSSEC No No No No No No
DNS64 No No No No No No
TFTP No No No No No Yes
Connection mirroring No No No No No No
Integrated caching Node-Level Node-level Node-level Node-level Node Level Node Level
Large shared cache No Node-level Node-level Node-level Node Level Node Level
HTTP Denial-of-Service Protection (HDOSP) Node-level Node-level Node-level Node-level Node Level Node Level
Priority queuing (PQ) Node-level Node-level Node-level Node-level NodeLevel Node Level
Sure connect (SC) Node-level Node-level Node-level Node-level Node Level Node Level
Surge protection Node-level Node-level Node-level Node-level Node Level Node Level
NAT46 No No No No No No
NAT64 No No No No No No
RNAT6 No No No No No No
LSN/CGNAT No No No No No No
NetScaler Push No No No No No No
Graceful Shutdown No No No No No No
DHCP RA No No No No No No
Network Bridge No No No No No No
Call Home Node-level Node-level Node-level Node-level Node Level Node Level
NetScaler Gateway (SSL VPN / full VPN and CVPN) No No Node-level Node-level Node Level Node Level
Dynamic Routing No No No Yes with v4 protocol support Yes with v6 protocols (ospfv3, Yes with v6 protocols (ospfv3,
RIPng, ISIS6, BGP6) support RIPng, ISIS6, BGP6) support
SYSLOG-TCP, load balancing of syslog servers, SNIP support, and FQDN support
No No No No No Yes
for syslog
Load balancing, load balancing persistency, DNS load balancing, SIP, maxClient, Spillover (connection and dynamic), Spillover based on bandwidth, DataStream, Compression control, Content filtering,
TCP buffering, Cache redirection, Distributed Denial-of-Service (DDoS), Client Keep-alive, Basic networking (IPv4 and IPv6), OSPF (IPv4 and IPv6), RIP (IPv4 and IPv6), RIP (IPv4 and IPv6), VLAN, ICMP,
Fragmentation, MBF, ACL, Simple ACL, MSR, Path MT U discovery, IP-IP, SNMP, Policies (classic and advanced), Rewrite, Responder, HT T P callout, Web server logging, Audit logging (nslog and syslog),
USIP, Location commands, HT ML injection, NIT RO API, AppExpert, KRPC.
All appliances must have the same software version and build.
All appliances must be of the same platform type. T his means that a cluster must have either all hardware appliances
(MPX) or virtual appliances (VPX) or SDX NetScaler instances.
Not e:
For a cluster of hardware appliances (MPX), the appliances must be of the same model type.
For the formation of the heterogeneous cluster, all appliances must be of MPX platform type.
For a cluster of virtual appliances (VPX), the appliances must be deployed on the following hypervisors: XenServer,
Hyper-V, VMware ESX, and KVM.
Clusters of SDX NetScaler instances are supported in NetScaler 10.1 and later releases. T o create a cluster of SDX
NetScaler instances, see "Setting up a Cluster of NetScaler Instances".
Jumbo frames are supported on a NetScaler cluster that is made up of NetScaler SDX instances.
All appliances must have the same licenses. Also, depending on the NetScaler version, there are some additional aspects
to address:
Note: For a cluster of virtual appliances, that has large configurations, it is recommended to use 6 GB RAM for each node
of the cluster.
Note: Unless specified otherwise, cluster features and configurations are the same for L2 and L3 clusters.
L2 clust er: In this cluster deployment, all cluster nodes belong to the same network.
L3 clust er (also ref erred t o as 'clust er in INC mode'): In this cluster deployment, cluster nodes can belong to
different networks. T he cluster nodes from a specific network must be grouped into nodegroups that include only nodes
from that network. From the following figure, we see that nodes n1, n2, n3 are in the same network and are grouped
into Nodegroup1.
Similarly, the case for nodes n4 and n5, that are grouped in Nodegroup2. In the third network, there are two nodegroups.
Nodegroup3 includes n6 and n7 and Nodegroup4 includes n8 and n9.
T he configurations that are available on the configuration coordinator are automatically propagated to the other cluster
nodes and therefore all cluster nodes have the same configurations.
Note:
NetScaler allows only a few configurations to be performed on individual cluster nodes through their NetScaler IP (NSIP)
address. In these cases, you must ensure configuration consistency manually across all nodes in the cluster. T hese
configurations are not propagated across the other cluster nodes. For more information on operations supported on
each cluster nodes, see "Operations Supported on Individual Cluster Nodes".
T he following commands when executed on the cluster IP address are not propagated to other cluster nodes:
shutdown: Shuts down only the configuration coordinator.
reboot: Reboots only the configuration coordinator.
rm cluster instance: Removes the cluster instance from the node that you are executing the command on.
For a command to propagate to other cluster nodes:
T he quorum must be configured on cluster instance.
T he majority of the cluster quorum with (n/2 + 1) of the cluster nodes must be active for the cluster to be
operational.
A cluster can run with a minimum number of nodes when majority rule (n/2 + 1) is relaxed.
When a node is added to a cluster, the configurations and the files (SSL certificates, licenses, DNS, and so on) that are
available on the cluster configuration coordinator are synchronized to the newly added cluster node. When an existing
cluster node, that was intentionally disabled or that had failed, is once again added, the cluster compares the
configurations available on the node with the configurations available on the configuration coordinator. If there is a
mismatch in configurations, the node is synchronized by using one of the following:
F ull synchronizat ion. If the difference between configurations exceeds 255 commands, all the configurations of the
configuration coordinator are applied to the node that is rejoining the cluster. T he node remains operationally
unavailable for the duration of the synchronization.
Increment al Synchronizat ion. If the difference between configurations is less than or equal to 255 commands, only
the configurations that are not available are applied to the node that is rejoining the cluster. T he operational state of
the node remains unaffected.
For example, you can define a SNIP address to be active on only one node, or define a SNIP address to be active on all
nodes, or define a VIP address to be active on only one node, or define a VIP address to be active on all nodes, or define a
VIP address to be active only on two nodes of a 3-node cluster.
Depending on the number of nodes the configurations are active on, cluster configurations are referred to as striped,
partially striped, or spotted configurations.
Figure 1. T hree-node cluster with striped, partially striped, and spotted configurations
Striped All the All entities No specific configuration required to make an entity striped. By default,
configuration cluster all entities defined on a cluster IP address are striped on all the cluster
nodes nodes.
Partially striped A Refer "Node Bind the entities that you want to be partially striped, to a node group.
configuration subset Groups" T he configuration will be active only on the cluster nodes that belong
of to the node group.
cluster
nodes
Spotted Single SNIP A spotted configuration can be defined using one of two approaches.
configuration cluster address SNIP address. When creating the SNIP address, specify the node
node SNMP on which you want the SNIP address to be active, as the owner
Engine ID node.
Hostname Example:
of cluster
node group at run time. T o change the ownership, you must first delete the SNIP
address and add it again by specifying the new owner.
Ent it ies t hat can be bound t o a node group. By binding the
entity to a single-member node group.
Note: When USIP is disabled, Citrix recommends you to use spotted SNIP addresses. You can use striped SNIP addresses only if there is a shortage of IP
addresses. The use of striped IP addresses can result in ARP flux issues. When USIP is enabled, Citrix recommends you to use striped SNIP addresses as a
gateway for server initiated traffic.
Note: For an L3 cluster (nodes across different networks), only ECMP traffic distribution can be used.
T he flow receiver gets the traffic and then, using internal cluster logic determines the node that must process the traffic.
T his node is called the flow processor. T he flow receiver steers the traffic to the flow processor over the backplane (if the
flow receiver and the flow processor are on the same network) or through the tunnel (if the flow receiver and the flow
processor are on different networks).
Note:
T he flow receiver and flow processor must be nodes capable of serving traffic.
From NetScaler 11 onwards, you can disable steering on the cluster backplane. For more information, see "Disabling
Steering on the Cluster Backplane".
T he above figure shows a client request flowing through the cluster. T he client sends a request to a virtual IP (VIP) address.
T he flow processor establishes a connection with the server. T he server processes the request and sends the response to
the subnet IP (SNIP) address that sent the request to the server.
If the SNIP address is a striped or partially striped IP address, the traffic distribution mechanism configured on the server
data plane selects one of the cluster nodes as the flow receiver. T he flow receiver receives the traffic, determines the
flow processor, and steers the request to the flow processor through the cluster backplane.
If the SNIP address is a spotted IP address, the node that owns the SNIP address receives the response from the server.
In an asymmetric cluster topology (all cluster nodes are not connected to the external switch), you must use linksets either
exclusively or combined with ECMP or cluster link aggregation. For more information, see "Using Linksets".
T he above figure shows a cluster which has nodegroups NG1 and NG2 that include 3 cluster nodes each. T he cluster also
has 3 nodes that are not part of any nodegroup.
T o define spotted and partially striped configurations. For more information, see "Nodegroups for Spotted and Partially-
Striped Configurations".
T o configure redundancy of nodegroups. For more information, see "Configuring Redundancy for Nodegroups".
Note: Supported from NetScaler 10.5 Build 52.1115.e onwards.
T o define an L3 cluster (also called a cluster in INC mode). In an L3 cluster, cluster nodes can be from different networks.
You must group nodes that belong to a network in a single nodegroup. For example, if n1, n2, n3 are in network1 and n4,
n5, n6 are in network2, then NG1 must include nodes of network1 and NG2 must include nodes of network2. For setting
up an L3 cluster, see "Creating a NetScaler Cluster".
Note: Supported from NetScaler 11 onwards.
Note: T he above functions of a nodegroup are mutually exclusive. T his means that a nodegroup can provide only one of
the above mentioned functionality.
Important
From NetScaler release 10.5, you can configure the cluster to be functional even when the majority criteria is not satisfied. T his
configuration must be performed when creating a cluster.
Po s s ible
T y pe De s criptio n
v a lue s
Specifies the responsibility of the node within the cluster setup. You can set the admin state to be one of the following:
PASSIVE (default state). These nodes are in sync with the cluster, but do not serve any traffic. You must explicitly
change its state to one of the other admin states, to make it ready to play a more active role. In passive admin state, the
node becomes Inactive without clearing the existing TCP connections. If the existing connections are not closed
properly, all connections on client side or server side disconnect or fail. To avoid this, we must reset all existing
connections on the inactive node.
ACTIVE. These nodes are in sync with the cluster and serve traffic that reaches the cluster. Check operational state for
information on when this node can serve traffic.
PASSIVE,
SPARE. These nodes act as backup nodes for the cluster. Spare nodes are always in sync with the cluster, but do not
Admin state ACT IVE,
serve any traffic till one of the ACTIVE (admin state) nodes becomes unavailable. When this happens, the admin state of
SPARE this node continues to be SPARE, but its operational state changes to ACTIVE.
Note: The preemption parameter that is specified on a cluster instance, indicates whether the SPARE node remains
operationally active even when a ACTIVE (admin state) node becomes available.
If preemption is disabled, the spare node continues to serve traffic even if a node in ACTIVE admin state comes back
online.
If preemption is enabled, when a node in ACTIVE admin state comes back online, it preempts the spare node and
starts serving traffic. The spare node goes back to inactive state.
Indicates whether the cluster node can successfully handle traffic by checking for the following criteria for
the node:
T he interfaces are up and enabled.
T he SSL cards are available.
T he cluster synchronization operation is enabled and completed.
UP, NOT T he backplane interface is up and enabled.
Health UP, T he CLAG member(s) are up.
UNKNOWN
Based on the above criteria, the health of a node can be:
UP. When all the criteria are satisfied.
Po s s ible
T y pe De s criptio n
v a lue s Indicates that the node can serve traffic. T he operational state of a node is determined by a combination of
the admin state and the health of the node.
ACT IVE. When the health of the node is UP and one of the following is true:
UNKNOWN. When the node cannot receive heartbeats from other nodes.
Review the ns.log file, error counters, and the output of the "show cluster node" command, to help
determine the exact reason for a node to be in INACT IVE and UNKNOWN state.
All routing configurations must be performed from the cluster IP address and the configurations are propagated to the
other cluster nodes.
Routing runs only on spotted SNIP addresses and NSIP addresses.
Routes are limited to the maximum number of ECMP routes supported by the upstream router
Node-specific routing configurations must be performed by using the owner-node argument as follows:
!
interface vlan97
!
router ospf
owner-node 0
ospf router-id 97.131.0.1
exit-owner-node
owner-node 1
ospf router-id 97.131.0.2
exit-owner-node
owner-node 2
ospf router-id 97.131.0.3
exit-owner-node
redistribute kernel
network 97.0.0.0/8 area 0
!
Retrieve node-specific routing configurations by specifying the node(s) in the owner-node argument as follows:
> vtysh
ns# owner-node 0 1
ns(node-0 1)# show cluster state
ns(node-0 1)# exit-owner-node
Clear node-specific routing configurations by specifying the node(s) in the owner-node argument as follows:
> vtysh
ns# owner-node 0 1
ns(node-0 1)# clear config
ns(node-0 1)# exit-owner-node
Routing protocol daemons can run and adjacencies can be formed on active and inactive nodes of a cluster.
Only active nodes advertise host routes to striped VIP addresses. Spotted VIP addresses are advertised by active owner
node.
Active and inactive nodes can learn dynamic routes and install them into the routing table.
Routes learnt on a node are propagated to other nodes in the cluster only if route propagation is configured. T his is
mostly needed in asymmetric topologies where the unconnected nodes may not be able to form adjacencies.
ns(config)# ns route-install propagate
Note: Make sure that route propagation is not configured in a symmetric cluster topology as it can result in making the
node unavailable to the cluster.
CLIP address. An IP address owned by the cluster coordinator node (CCO). T he CLIP address can float between different
nodes in a cluster setup. If the CLIP is moved to a different node of the cluster, that node becomes the CCO. T he CCO is
the NetScaler appliance that is responsible for management tasks in the cluster. A network administrator uses the CLIP
address to connect to the cluster to perform configuration and management tasks, such as accessing unified GUI,
reporting, tracing packet flow, and collecting logs. T he CCO node does not have an NSIP address. Only configurations
performed on the CCO through the cluster IP address are propagated to other nodes in the cluster.
St riped IP address . A logical IP address available on all nodes of the cluster, it can be either a VIP or SNIP address.
Spot t ed IP address . A logical IP (preferably SNIP address) is available only on one node. A spotted IP address has visibility
on only that node. To minimize traffic-steering overhead, Citrix recommends that you use spotted SNIP address for
backend communication with the server.
For example, in a four-node cluster group, you must configure each node with a spotted SNIP address. For more
information on how to configure a spotted IP configuration, see http://docs.citrix.com/en-
us/netscaler/12/clustering/cluster-overview/cluster-config-type.html.
You can define a SNIP address to be active on only one node, or active on all nodes. If a virtual IP address and Subnet IP
address is available only on a specific node, it is of spotted configuration or if the Subnet IP address and Virtual server IP
address are available on all nodes, it is defined as striped configuration.
Not e: In a four-node cluster setup, you must configure a spotted SNIP address on each node. For more information about
configuring a spotted IP configuration, see http://docs.citrix.com/en-us/netscaler/12/clustering/cluster-overview/cluster-
config-type.html.
In an L3 cluster setup, only spotted SNIP configuration is supported, as shown in the following table.
Yes
Striped No Yes
L3 cluster is also referred to as “cluster in Independent Network Configuration (INC) mode”. In L3 cluster deployment, the
cluster nodes in the same network are grouped together to form a Nodegroup. L3 cluster uses GRE tunneling to steer the
packets across networks. T he heartbeat messages across L3 clusters will be routed.
Architecture
Example
Nodegroup . T he cluster nodes from each network (n1, n2) and (n3, n4), as depicted in below figure, are grouped
together to form a Nodegroup. T hese Nodegroups are terminated to the layer 3 switch on either side of the network.
T he cluster communicates with the client through the physical connections between the cluster node and the client-
side connecting device. T he logical grouping of these physical connections is called the client data plane.
T he cluster communicates with the server through the physical connections between the cluster node and the server
side connecting device. T he logical grouping of these physical connections is called the server data plane.
Backplane Swit ch. Cluster nodes within the same network communicate with each other by using the cluster
backplane. T he backplane is a set of interfaces in which one interface of each node is connected to a common switch,
which is called the cluster backplane switch.
GRE T unnel. T he packets between nodes in a L3 cluster are exchanged over an unencrypted GRE tunnel that uses the
NSIP addresses of the source and destination nodes for routing. T he steering mechanism will change for nodes
belonging to different network. T he packets are steered through a GRE tunnel to the node on the other subnet, instead
of rewriting the MAC.
T hree NetScaler appliances (n1, n2, and n3) nodes are grouped together into Nodegroup1.
Similarly, the nodes n4 and n5 are grouped in Nodegroup2. In the third network, there are two nodegroups. Nodegroup3
includes n6 and n7 and Nodegroup4 includes n8 and n9.
T he NetScaler appliances that belong to the same network are combined together to form a Nodegroup.
T he backplane is not mandatory while configuring L3 subnets. If the backplane is not specified, the node will not go to
backplane fail state. Note: If you have some cluster nodes in the L2 network, it is
mandatory to enable steering on the cluster backplane, else the nodes will go to backplane fail state.
T he external traffic distribution in L3 cluster supports only Equal Cost Multiple Path (ECMP).
T he following parameters are processed when steering is disabled is an L3 cluster deployment:
ICMP errors
Fragmentation
Striped SNIPs or MIPs
T he entities (route, route6, pbr, and pbr6) can be bound to configuration nodegroup.
VLAN, RNAT , and IP tunnel cannot be bound to a config nodegroup.
Config nodegroup should always have property ST RICT “YES.
T he cluster nodes should not be added to a config nodegroup via “add cluster node” command.
T he “clear config extended+” command will not clear the entities (route, route6, pbr, pb6, rnat, IP tunnel, ip6tunnel).
T hese entities should be cleared when an “add cluster instance – INC enabled” command is configured.
In an L3 cluster configuration, the cluster command has different attributes to configure that is based on nodes, and
nodegroups. T he L3 cluster configuration also includes an IPv6 profile apart from IPv4 profiles.
save ns config
reboot -warm
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
You must configure the cluster IP address to be advertised to the upstream router to make the cluster configuration
accessible from any subnet. T he cluster IP address is advertised as a kernel route by the dynamic routing protocols
configured on a node.
Enable t he host rout e opt ion of t he clust er IP address . T he host route option pushes the cluster IP address to
ZebOS routing table for kernel route redistribution through dynamic routing protocols.
Conf iguring a dynamic rout ing prot ocol on a node . A dynamic routing protocol advertises the cluster IP address to
the upstream router. For more information on configuring a dynamic routing protocol, see http://docs.citrix.com/en-
us/netscaler/12/networking/ip-routing/configuring-dynamic-routes.html.
To enable t he host rout e opt ion of t he clust er IP Address by using t he Net Scaler command line
Done
T he spotted and partially striped configurations on L3 cluster slightly differs from L2 cluster. T he configuration might differ
from node to node as the nodes reside on different subnets. T he network configurations can be node specific in L3 cluster,
hence you have to configure the spotted or partially striped configurations based on the below-mentioned parameters.
To configure spotted, partially striped configurations on a NetScaler appliance over L3 cluster perform the following tasks:
T o add a VLAN
bind vlan <id> -ifnum – [IPAddress <ip_addr | ipv6_addr |> [-ownergroup <ng>]
Done
Done
Done
Done
Done
Done
In an L3 cluster, to replicate the same set of configurations on more than one nodegroup, the following commands are
used:
To support the above configuration, a new nodegroup ‘all’ has to be defined and you have to configure the following
commands:
Forming a cluster requires you to set up inter-node communication, create the cluster (by adding the first NetScaler
appliance), and then add the other cluster nodes. Each of these steps is explained with relevant details in subsequent
topics.
Note: While there are some differences in setting up an L2 and L3 cluster, there are many similarities too. T he subsequent
topics explain the setup for both cluster types while highlighting the configurations that are specific to L3 clusters.
1. Identify the network interface that you want to use for the backplane.
2. Connect an Ethernet or optical cable from the selected network interface to the cluster backplane switch.
For example, to use interface 1/2 as the backplane interface for node 4, connect a cable from the 1/2 interface of node 4
to the backplane switch.
Do not use the appliance's management interface (0/x) as the backplane interface. In a cluster, the interface 0/1/x is
read as:
0 -> node ID 0
1/x -> NetScaler interface
Backlane interfaces must not be used for the client or server data planes.
Configure a link aggregate (LA) channel to optimize the throughput of the cluster backplane.
Citrix recommends that you dedicate a separate switch for the backplane, so that large amounts of traffic can be
handled seamlessly.
Backplane interfaces of all nodes of a cluster must be connected to the same switch and bound to the same L2 VLAN.
If you have multiple clusters with the same cluster instance ID, make sure that the backplane interfaces of each cluster
are bound to a different VLAN.
T he backplane interface is always monitored, regardless of the HA monitoring settings of that interface.
T he state of MAC spoofing on the different virtualization platforms can affect the steering mechanism on the cluster
backplane. T herefore, make sure the appropriate state is configured:
T he MT U for the cluster backplane is automatically updated. However, if jumbo frames are configured on the cluster, the
MT U of the cluster backplane must be explicitly configured. T he value must be set to 78 + X, where X is the maximum
MT U of the client and server data planes. For example, if MT U of server data plane is 7500 and of the client data plane is
8922, then the MT U of cluster backplane must be set to 78 + 8922 = 9000. T o set this MT U, use the following
command:
> set interface <backplane_interface> -mtu <value>
T he MT U for interfaces of the backplane switch must be specified to be greater than or equal to 1578 bytes, if the
cluster has features like MBF, L2 policies, ACLs, routing in CLAG deployments, and vPath.
T he responsibility of configuration coordination in a cluster is not fixed to a specific node. It can change over time
depending on the following factors:
T he priority of the node. T he node with the highest priority (lowest priority number) is made the configuration
coordinator. T herefore, if a node with a priority number lower than that of the existing configuration coordinator is
added, the new node takes over as the configuration coordinator.
Note: Node priority can be configured from NetScaler 10.1 onwards.
If the current configuration coordinator goes down. T he node with the next lowest priority number takes over as the
configuration coordinator. If the priority is not set or if there are multiple nodes with the lowest priority number, the
configuration coordinator is selected from one of the available nodes.
Note: T he configurations of the appliance (including SNIP addresses and VLANs) are cleared by implicitly executing the clear
ns config extended command. However, the default VLAN and NSVLAN are not cleared from the appliance. T herefore, if
you want the NSVLAN on the cluster, make sure it is created before the appliance is added to the cluster. For an L3 cluster
(cluster nodes on different networks), networking configurations are not cleared from the appliance.
Important
HA Monitor (HAMON) on a cluster setup is used to monitor the health of an interface on each node. T he HAMON parameter should
be enabled on each node to monitor the state of the interface. If the operational state of the HAMON enabled interface goes down
due to any reason, the respective cluster node is marked as unhealthy (NOT UP) and that node cannot serve traffic.
1. Log on to an appliance (for example, appliance with NSIP address 10.102.29.60) that you want to add to the cluster.
2. Add a cluster instance.
add cluster instance <clId> -quorumType <NONE | MAJORIT Y> -inc <ENABLED | DISABLED>
Note:
T he cluster instance ID must be unique within a LAN.
For an L3 cluster, make sure the inc parameter is set to ENABLED. T he "inc" parameter must be disabled for an L2
cluster.
3. [Only for an L3 cluster] Create a nodegroup. In the next step, the newly added cluster node must be associated with this
nodegroup.
Note: T his nodegroup will include all or a subset of the NetScaler appliances that belong to the same network.
add cluster nodegroup <name>
Adding a node for an L2 cluster (all cluster nodes are in the same network).
Example
> add ns ip 10.102.29.61 255.255.255.255 -type clip
6. Enable the cluster instance.
enable cluster instance <clId>
Verify the cluster configurations by using the show cluster instance command. Verify that the output of the command
displays the NSIP address of the appliance as a node of the cluster.
1. Log on to an appliance (for example, an appliance with NSIP address 10.102.29.60) that you intend to add to the cluster.
2. Navigate to System > Cluster.
3. In the details pane, click the Manage Cluster link.
4. In the Cluster Configuration dialog box, set the parameters required to create a cluster. For a description of a parameter,
hover the mouse cursor over the corresponding text box.
5. Click Create.
6. In the Configure cluster instance dialog box, make sure that the Enable cluster instance check box is selected.
7. In the Cluster Nodes pane, select the node and click Open.
8. In the Configure Cluster Node dialog box, set the State.
9. Click OK, and then click Save.
10. Warm reboot the appliance.
T he cluster configurations are then synchronized on this node. T here can be an intermittent drop in traffic while the
synchronization is in progress.
To add a node to the cluster by using the command line interf ace
1. Log on to the cluster IP address and, at the command prompt, do the following:
1. Add the appliance (for example, 10.102.29.70) to the cluster.
add cluster node <nodeId> <IPAddress> -state <state> -backplane <interface_name> -nodegroup <name>
2. Log on to the newly added node (for example, 10.102.29.70) and do the following:
1. Join the node to the cluster.
join cluster -clip <ip_addr> -password <password>
Example
> join cluster -clip 10.102.29.61 -password nsroot
To join a previously added node to the cluster by using the configuration utility
If you have used the command line to add a node to the cluster, but have not joined the node to the cluster, you can use
the following procedure.
Note: When a node joins the cluster, it takes over its share of traffic from the cluster and hence an existing connection can
get terminated.
1. Log on to the node that you want to join to the cluster (for example, 10.102.29.70).
2. Navigate to System > Cluster.
3. In the details pane, under Get Started, click the Join Cluster link.
4. In the Join to existing cluster dialog box, set the cluster IP address and the nsroot password of the configuration
coordinator. For a description of a parameter, hover the mouse cursor over the corresponding text box.
5. Click OK.
To view details of a cluster instance by using the command line interf ace
Note: When executed from the NSIP address of a cluster node that is not the configuration coordinator, this command
displays the status of the cluster on this node.
To view details of a cluster node by using the command line interf ace
You must have detailed knowledge of routing protocols to use ECMP. For more information, see "Configuring Dynamic Routes. For more information on routing in a cluster, see "Routing in a Cluster".
Enable the required routing protocol (OSPF, RIP, BGP, or ISIS) on the cluster IP address.
Bind the interfaces and the spotted IP address (with dynamic routing enabled) to a VLAN.
Configure the selected routing protocol and redistribute the kernel routes on the ZebOS by using the vtysh shell.
You must perform similar configurations on the cluster IP address and on the external connecting device.
Note:
Make sure that the licenses on the cluster support dynamic routing, otherwise ECMP does not work.
ECMP is not supported for wildcard virtual servers since RHI needs a VIP address to advertise to a router and wildcard virtual servers do not have associated VIP addresses.
As seen in the above figure, the ECMP router can reach the VIP address via SNIP0, SNIP1, or SNIP2.
To configure ECMP on the cluster by using the command line interf ace
Example
> add vlan 97
4. Bind the interfaces of the cluster nodes to the VLAN.
bind vlan <id> -ifnum <interface_name>
Example
> bind vlan 97 -ifnum 0/1/2 1/1/2 2/1/2
5. Add a spotted SNIP address for each node and enable dynamic routing on it.
add ns ip <SNIP> <netmask> -ownerNode <positive_integer> -dynamicRouting ENABLED
Example
> add ns ip 97.131.0.1 255.0.0.0 -ownerNode 0 -dynamicRouting ENABLED -type SNIP
> add ns ip 97.131.0.2 255.0.0.0 -ownerNode 1 -dynamicRouting ENABLED -type SNIP
> add ns ip 97.131.0.3 255.0.0.0 -ownerNode 2 -dynamicRouting ENABLED -type SNIP
6. Bind one of the spotted SNIP addresses to the VLAN. When you bind one spotted SNIP address to a VLAN, all other spotted SNIP addresses defined on the cluster in that subnet are
automatically bound to the VLAN.
bind vlan <id> -IPAddress <SNIP> <netmask>
Example
> bind vlan 97 -ipAddress 97.131.0.1 255.0.0.0
Note: You can use NSIP addresses of the cluster nodes instead of adding SNIP addresses. If so, you do not have to perform steps 3 - 6.
7. Configure the routing protocol on ZebOS using vtysh shell.
Example: To configure OSPF routing protocol on node IDs 0, 1, and 2.
For OSPF specific RHI settings, there are additional settings that can be done as follows:
add ns ip <IPAddress> <netmask> -type VIP -ospfLSAType ( T YPE1 | T YPE5 ) -ospfArea <positive_integer>
Use the add ns ip6 command to perform the above commands on IPv6 addresses.
8. Configure ECMP on the external switch. T he following sample configurations are provided for the Cisco® Nexus 7000 C7010 Release 5.2(1) switch. Similar configurations must be performed on
other switches.
//For OSPF (IPv4 addresses) Global config: Configure terminal feature ospf Interface config: Configure terminal interface Vlan10 no shutdown ip address 97.131.0.5/8 Configure terminal router ospf 1
To configure ECMP f or static routes traf fic distribution by using the command line interf ace
Code COPY
Important
Cluster link aggregation is supported for a cluster of hardware (MPX) appliances.
Cluster link aggregation is supported for a cluster of virtual (VPX) appliances that are deployed on ESX and KVM hypervisors, with
the following restrictions:
Dedicated interfaces need to be used. T his means that the interfaces must not be shared with other virtual machines.
If the cluster link aggregation member interfaces are manually disabled or if cluster link aggregation itself is manually
disabled, then interface power down capability is achieved only by LACP timeout mechanism.
Note: Cluster link aggregation is not supported on VPX appliances that are deployed on XenServer, AWS, and Hyper-V.
Starting from 12. 0 release, cluster link aggregation is supported on NetScaler SDX appliances. For more information on forming
a cluster link aggregation by using SDX appliances, see "Configuring Cluster Link Aggregation".
T he number of interfaces that can be bound to cluster LA is 16 (from each node), and the maximum number of interfaces in
cluster LA can be (16 * n), where n is the number of nodes in a cluster. T he total number of interfaces in cluster LA depends on
the number of interfaces for every port channel on upstream switch.
For example, consider a three-node cluster where all three nodes are connected to the upstream switch. A cluster LA
channel (CLA/1) is formed by binding interfaces 0/1/2, 1/1/2, and 2/1/2.
To configure a static cluster LA channel by using the command line interf ace
Example
> add channel CLA/1 -speed 1000
Note: You must not specify the speed as AUT O. Rather, you must explicitly specify the speed as 10, 100, 1000, or 10000.
Only interfaces that have the speed matching the <speed> attribute in the cluster LA channel are added to the active
distribution list.
3. Bind the required interfaces to the cluster LA channel. Make sure that the interfaces are not used for the cluster
backplane.
bind channel <id> <ifnum>
Example
> bind channel CLA/1 0/1/2 1/1/2 2/1/2
4. Verify the configurations.
show channel <id>
Example
> show channel CLA/1
Note: You can bind the cluster LA channel to a VLAN by using the bind vlan command. T he interfaces of the channel are
automatically bound to the VLAN.
5. Configure static LA on the external switch. T he following sample configurations are provided for the Cisco® Nexus 7000
C7010 Release 5.2(1). Similar configurations must be performed on other switches.
Global config:
Configure terminal
interface Ethernet2/47
switchport
switchport access vlan 10
channel-group 7 mode on
no shutdown
interface Ethernet2/48
You must perform similar configurations on the cluster IP address and on the external connecting device. If possible,
configure the upstream switch to distribute traffic based on IP address or port instead of MAC address.
Points to remember:
Enable LACP (by specifying the LACP mode as either ACT IVE or PASSIVE).
Note: Make sure the LACP mode is not set as PASSIVE on both the NetScaler cluster and the external connecting
device.
Specify the same LACP key on each interface that you want to be the part of the channel. For creating a cluster LA
channel, the LACP key can have a value from 5 through 8. For example, if you set the LACP key on interfaces 0/1/2,
1/1/2, and 2/1/2 to 5, CLA/1 is created. T he interfaces 0/1/2, 1/1/2, and 2/1/2 are automatically bound to CLA/1. Similarly,
if you set the LACP key to 6, CLA/2 channel is created.
To configure a dynamic cluster LA channel by using the command line interf ace
On the cluster IP address, for each interface that you want to add to the cluster LA channel, type:
Global config:
Configure terminal
feature lacp
Interface level config:
interface Ethernet2/47
switchport
switchport access vlan 10
channel-group 7 mode active
no shutdown
interface Ethernet2/48
switchport
switchport access vlan 10
To understand the need for link redundancy, let us consider the example of the following cluster setup along with the
accompanying cases (with attention to case 3):
In this setup, interfaces I1, I2, I3 and I4 are bound to LACP channel with KEY 5. On the partner side, I1 and I2 are connected
to Switch 1 to form a single LA channel with KEY 1. Similarly, I3 and I4 are connected to Switch 2 to form a single LA
channel with KEY 2.
Now let us consider the following cases to understand the need for link redundancy:
T he throughput of the partner channels is checked against the configured threshold throughput. T he partner channel that
satisfies the threshold throughput is selected in first-in-first-out (FIFO) manner. If none of the partner channel meets the
threshold, or if threshold throughput is not configured, the partner channel with the maximum number of links is selected.
Note: T he threshold throughput can be configured from NetScaler 11 onwards.
For example, consider a three node cluster where the upstream switch has only two ports available. Using linksets, you can
connect two nodes to the switch and leave the third node unconnected. In the following figure, a linkset (LS/1) is formed
by binding the interfaces 0/1/2 and 1/1/2. NS2 is the unconnected node of the cluster.
T he linkset informs NS2 that it can use interfaces 0/1/2 and 1/1/2 to communicate with the network devices. All traffic to
and from NS2 is now routed through interfaces 0/1/2 or 1/1/2.
Example
> add linkset LS/1
3. Bind the required interfaces to the linkset. Make sure the interfaces are not used for the cluster backplane.
bind linkset <id> -ifnum <interface_name> ...
Example
> bind linkset LS/1 -ifnum 0/1/2 1/1/2
4. Verify the linkset configurations.
show linkset <id>
Example
> show linkset LS/1
Note: You can bind the linkset to a VLAN by using the bind vlan command. T he interfaces of the linkset are automatically
bound to the VLAN.
You can achieve this requirement by defining a nodegroup that includes the specific cluster nodes, and then binding the
configuration to that nodegroup. T his ensures that the configuration is active only on those cluster nodes. T hese
configurations are called partially-striped or spotted (if active only one a single node). For more information, see Striped,
Partially Striped, and Spotted Configurations.
For example, consider a cluster with three nodes. You create a nodegroup NG0 that includes node n1 and another
nodegroup NG1 that includes n2 and n3. Bind load balancing virtual servers .77 to NG0 and load balancing virtual server .69
to NG1.
T his means that virtual server .77 will be active only on n1 and consequently only n1 will receive traffic that is directed to
.77. Similarly, virtual server .69 will be active only on nodes n2 and n3 and consequently only n2 and n3 will receive traffic that
is directed to .69.
Figure 1. NetScaler cluster with nodegroups configured for spotted and partial-striped configurations
Load balancing, content switching, cache redirection, authentication (AAA) virtual servers
Note: FT P load balancing virtual servers cannot be bound to nodegroups.
VPN virtual server (Supported from NetScaler 10.5 Build 50.10 onwards)
Global Server Load Balancing (GSLB) sites and other GSLB entities (Supported from NetScaler 10.5 Build 52.11 onwards)
Limit identifiers and stream identifiers
By default, a nodegroup is designed to provide back up nodes for members of a nodegroup. If a nodegroup member goes
down, a cluster node that is not a member of the nodegroup dynamically replaces the failed node. T his node is called the
replacement node.
Note: For a single-member nodegroup, a backup node is automatically preselected when an entity is bound to the
nodegroup.
When the original member of the nodegroup comes up, the replacement node, by default, is replaced by the original
member node.
From NetScaler 10.5 Build 50.10 onwards, however, the NetScaler allows you to change this replacement behavior. When
you enable the sticky option, the replacement node is retained even after the original member node comes up. T he original
node takes over only when the replacement node goes down.
You can also disable the backup functionality. To do this, you must enable the strict option. In this scenario, when a
nodegroup member goes down, no other cluster node is picked up as a backup node. T he original node continues being part
of the nodegroup when it comes up. T his option ensures that entities bound to a nodegroup are active only on nodegroup
members.
Note: T he strict and sticky option can be set only when creating a nodegroup.
Check NetScaler Features Supported in a Cluster to see the NetScaler versions from which GSLB, NetScaler Gateway, and
application firewall are supported in a cluster.
Example
> add cluster nodegroup NG0 -strict YES
3. Bind the required nodes to the nodegroup. T ype the following command for each member of the nodegroup:
bind cluster nodegroup <name> -node <nodeId>
Note: T he gslbSite and service parameters are available from NetScaler 10.5 onwards.
Example: T o bind virtual servers VS1 and VS2 and rate limit identifier named identifier1.
Example
> show cluster nodegroup NG0
Note: T his functionality can be used to configure datacenter redundancy where each nodegroup is configured as a
datacenter.
To achieve this use case, cluster nodes must be logically grouped into nodegroups, where some nodegroups must be
configured as ACT IVE and others as SPARE. T he active nodegroup with the highest priority (that is, the lowest priority
number) is made operationally active and therefore serves traffic. When a node from this operationally active nodegroup
goes down, the node count of this nodegroup is compared with the node count of the other active nodegroups in order of
their priority. If a nodegroup has a higher or equal node count, that nodegroup is made operationally active. Else, the spare
nodegroups are checked.
Note:
Only one state-specific nodegroup can be active at a given point in time.
A cluster node inherits the state of the nodegroup. So, if a node with "SPARE" state is added to nodegroup with state
as "ACT IVE", the node automatically behaves as an active node.
T he preemption parameter that is defined for the cluster instance decides whether the initial active nodegroup will take
control when the it comes up again.
A spare node group can take up a node group and host active traffic when an active node group goes down.
T he following figure shows a nodegroup setup that has nodegroup redundancy defined. NG1 is initially the active
nodegroup. When it loses one of the nodes, the spare nodegroup (NG3) with the highest priority starts serving traffic.
If required, you can disable steering so that the process becomes local to the flow receiver and therefore makes the flow
receiver as the flow processor. Such a configuration setup can come handy when you have a high latency link.
Steering can be disabled at the individual virtual server level or at the global level. T he global configuration takes precedence
over the virtual server setting.
Disabling backplane steering f or all striped virtual servers
Configured at cluster instance level. T raffic meant for any striped virtual server will not be steered on cluster backplane.
add cluster instance <clId> -processLocal ENABLED
Disabling backplane steering f or a specif ic striped virtual server
Configured on a striped virtual server. T raffic meant for the virtual server will not be steered on cluster backplane.
add lb vserver <name> <serviceT ype> -processLocal ENABLED
Additionally, you can forcefully synchronize the configurations that are available on the configuration coordinator (full
synchronization) to a specific cluster node. Make sure you synchronize one cluster node at a time, otherwise the cluster can
get affected.
At the command prompt of the appliance on which you want to synchronize the configurations, type:
T he directories and files from the configuration coordinator that are synchronized are:
/nsconfig/ssl/
/var/netscaler/ssl/
/var/vpn/bookmark/
/nsconfig/dns/
/nsconfig/htmlinjection/
/netscaler/htmlinjection/ens/
/nsconfig/monitors/
/nsconfig/nstemplates/
/nsconfig/ssh/
/nsconfig/rc.netscaler
/nsconfig/resolv.conf
/nsconfig/inetd.conf
/nsconfig/syslog.conf
/nsconfig/snmpd.conf
/nsconfig/ntp.conf
/nsconfig/httpd.conf
/nsconfig/sshd_config
/nsconfig/hosts
/nsconfig/enckey
/var/nslw.bin/etc/krb5.conf
/var/nslw.bin/etc/krb5.keytab
/var/lib/likewise/db/
/var/download/
/var/wi/tomcat/webapps/
/var/wi/tomcat/conf/Catalina/localhost/
/var/wi/java_home/lib/security/cacerts
/var/wi/java_home/jre/lib/security/cacerts
/nsconfig/license/
/nsconfig/rc.conf
Tip
Files (certificates and key files) that are copied to the cluster configuration coordinator manually (or through the shell) are not
automatically available on the other cluster nodes. You must execute the "sync cluster files" command from the cluster IP
address before executing a command that depends on these file(s).
To view the statistics of a cluster instance by using the command line interf ace
To view the statistics of a cluster node by using the command line interf ace
Note: When executed from the cluster IP address, this command displays the cluster level statistics. However, when
executed from the NSIP address of a cluster node, the command displays node level statistics.
To view the statistics of a cluster instance by using the configuration utility
Note:
T he discover operation can be performed only through the configuration utility.
T his operation cannot discover NetScaler appliances from different networks.
When performing this operation to add nodes to an existing cluster, the L3 VLAN configurations will be cleared from the
node. You must make sure to define these configurations once the appliance is added to the cluster.
A disabled node cannot serve traffic and all existing connections on this node are terminated.
Note: If the configurations of a disabled non-configuration coordinator node are modified (through the NSIP address of
the node), the configurations are not automatically synchronized on that node. You must manually synchronize the
configurations as described in Synchronizing Cluster Configurations.
To disable a cluster node by using the command line interf ace
At the command prompt of the node that you want to disable, type:
Note: T o disable the cluster, run the disable cluster instance command on the cluster IP address.
To disable a cluster node by using the configuration utility
1. On the node that you want to disable, navigate to System > Cluster, and click Manage Cluster.
2. In the Configure cluster instance dialog box, unselect the Enable cluster instance check box.
Note: T o disable the cluster instance on all the nodes, perform the above procedure on the cluster IP address.
Note:
If the deleted node was the cluster configuration coordinator, another node is automatically selected as the cluster
configuration coordinator, and the cluster IP address is assigned to that node. All the current cluster IP address sessions
will be invalid and you will have to start a new session.
T o delete the whole cluster, you must remove each node individually. When you remove the last node, the cluster IP
address(es) are deleted.
When an active node is removed, the traffic serving capability of the cluster is reduced by one node. Existing connections
on this node are terminated.
Note: If the cluster IP address is unreachable from the node, execute the rm cluster instance command on the NSIP
address of that node itself.
For NetScaler 10
1. Log on to the node that you want to remove from the cluster and remove the reference to the cluster instance.
rm cluster instance <clId>
save ns config
2. Log on to the cluster IP address and remove the node from which you removed the cluster instance.
rm cluster node <nodeId>
save ns config
Make sure you do not run the rm cluster node command from the local node as this results in inconsistent configurations
between the configuration coordinator and the node.
On the cluster IP address, navigate to System > Cluster > Nodes, select the node you want to remove and click Remove.
For detailed information on cluster link aggregation, see Using Cluster Link Aggregation.
To remove a node f rom a cluster that uses cluster link aggregation as the traf fic distribution mechanism
3. On the upstream switch, remove the corresponding interface from the channel by using switch-specific commands.
Note: You do not have to manually remove the nodes interface on the cluster link aggregation channel. It is
automatically removed when the node is deleted in the next step.
4. Remove the node from the cluster.
rm cluster node <nodeId>
To verify the above configuration, you must send a jumbo probe (of the above computational size) to all peer nodes of a
Cluster setup. If the probe does not succeed, the appliance displays a warning message in the output of the “show cluster
instance” command.
Cluster ID: 1
Preemption: DISABLED
Propagation: ENABLED
Warning
T he MT U for a backplane interface must be large enough to handle all packets in the frame. It must be equal to <MT U_VAL>. If the
recommended value is not user configurable, you must review the MT U value of jumbo interfaces.
Node ID Node IP
In a cluster deployment, if the client-side or server side-link of a node goes down, traffic is steered to this node through the
peer nodes for processing. T he steering of traffic is implemented by configuring dynamic routing and adding static ARP
entries, pointing to the special MAC address of each node, on all the nodes. If there are a large number of nodes in a cluster
deployment, adding and managing static ARP entries with special MAC addresses on all the nodes is a cumbersome task.
Now, nodes implicitly use special MAC addresses for steering packets. T herefore, static ARP entries pointing to special MAC
addresses are no longer required to be added to the cluster nodes.
Consider a scenario where Node 1 is bound to route monitor 1.1.1.0 255.255.255.0. When a dynamic route fails, Node 1
become INACT IVE. Health status is available in the Show Cluster Node command by node id as show below.
Code COPY
IP: 10.102.169.96
Backplane: 1/1/2
Health: NOT UP
To display the MIB configuration for a cluster node other than the CCO, include the "ownerNode" parameter in the show
snmp mib command
To configure and view MIB configuration on CLIP by using the command line interface.
Done
> set mib -contact John -name NS59 -location San Jose -customID 123 -ownerNode 3
Done
--------------------
--------------------
sysUpTime: 124300
sysObjectID: .1.3.6.1.4.1.5951.1.1
sysContact: John
sysName: NS59
sysServices: 72
Done
Done
--------------------
--------------------
sysUpTime: 146023
sysObjectID: .1.3.6.1.4.1.5951.1.1
sysName: NetScaler
sysServices: 72
Done
1. Cluster upgrade
2. New Node Addition
To upgrade a cluster, you must upgrade one node at a time. Before upgrading a node, you must set it to passive state and
then set it to active state after the upgrade. To avoid terminating existing connections when upgrading the node, shut it
down gracefully with a configured timeout interval. Otherwise, 1/Nth (where N is the cluster size) of the cluster's
connections are terminated.
Note: If existing sessions are not completed within the configured timeout interval, they get terminated after the grace
time.
Following are the steps to gracefully handle nodes in a cluster upgrade scenario:
1. Consider a cluster setup of five nodes (n0, n1, n2, n3, n4).
2. Before you shut down a node, you must configure “retainConnectionsOnCluster” option to retain all existing connections of this node at cluster level or virtual
server level for specific time interval. For example:
On CLIP
OR
3. Now, log on to the NSIP address of node n3 and set the node n3 to PASSIVE with a timeout internal. For example:
saveconfig
4. After the grace period expires, close all connections, shut down n3 and reboot the NetScaler appliance.
5. Upgrade the appliance. Then, with the CLI connected to the appliance's NSIP address, set the node to ACTIVE. For example:
saveconfig
7. After all nodes are upgraded and set to ACTIVE, reset the retainConnectionsOnCluster option from the CLIP address. For example:
saveconfig
Note: If there is a version mismatch when upgrading a Cluster, cluster propagation is automatically disabled and no commands are allowed on the CLIP.
If you have an appliance that is already serving traffic, and you want to add this appliance as a node to a cluster without
terminating its existing connections, set the option to retain existing connections either at Global level or specific virtual
sever level and save the configuration. Now set the option to retain connections to NO, to allow existing connections from
other nodes to be reassigned to the new node.
Following are the steps to gracefully handle nodes if a node newly added:
1. You must save the existing configuration that has “retainConnectionsOnCluster” option enabled to retain all existing
connections of this node at cluster level or virtual server level for specific time interval.
On CLIP
OR
3. Disable “the retainConnectionOnCluster” option to “NO” for distributing existing connections from other nodes to the
newly added node n5.
On CLIP
OR
Note: T he backplane steering depends on the type of traffic distribution mechanism (ECMP, CLAG, and USIP) on a cluster
setup. T he increase in backplane steering is based on the traffic type.
To retain existing connections at the global (cluster) level by using the command line
command COPY
Example COPY
To retain existing connections of a specific virtual server in the cluster by using the command line
T his option is configured to retain existing connections specific to a load balancing virtual server. To retain those
connections, we enable this option at the virtual server level. By default, this option is disabled.
command COPY
Example COPY
To set a cluster node to passive state with a gracefully timeout interval. T his setting is performed in the node’s NSIP as
propagation is disabled during cluster upgrade.
Code COPY
-backplane <interface_name>@
-priority <positive_integer>
-delay <mins>
Example COPY
Following are the modified functionalities available to pass IPv6 core protocols, such as ND test cases, Router Solicitation
processing and sending Route advertisement and router redirection messaging in IPv6readylogo phase2 test suite.
With these modified commands, the following configurations are supported in a clustered appliance.
For a clustered setup to pass IPv6 Ready Logo test cases, you can execute the following configurations on the Cluster
Management IP address (CLIP).
Global Configuration
A global IPv6 configuration enables you to set the global IPv6 parameters (such as relearning, routeRedirection,
ndBasereachT ime, nRetransmissionT ime, natprefix, td, and doodad) to run the basic IPv6 configuration.
command COPY
To add a VLAN to the clustered setup by using the NetScaler command line
command COPY
To add another VLAN to the clustered set up by using the NetScaler command line
command COPY
command COPY
T his command adds the global prefix as on-link prefix into RA information for subsequent Router Advertisements. At the
command prompt, type:
command COPY
To add IPv6 SNIP address on a VLAN by using the NetScaler command line
command COPY
command COPY
command COPY
command COPY
To display link local IPv6 address attached to VLAN by using the NetScaler command line
command COPY
Example 1
command COPY
add vlan 2
add vlan 3
Example 2
command COPY
Interfaces : 1/6
IPs :
3ffe:501:ffff:100:2e0:edff:fe15:ea2a/64
Interfaces : 1/5
IPs :
3ffe:501:ffff:101:2e0:edff:fe15:ea2b/64
Done
To test IPv6 core protocols, you can use the following new or modified IPv6 configurations.
To set VLAN specific Router Advertisement parameters by using the NetScaler command line
Code COPY
set nd6RAvariables -vlan <positive_integer> [-ceaseRouterAdv ( YES | NO)] [-sendRouterAdv ( YES | NO )] [-srcLinkLayerAddrOption
To set an on-link global prefix’s configurable parameters by using the NetScaler command line
set onLinkIPv6Prefix <ipv6Prefix> [-onlinkPrefix ( YES | NO )][-autonomusPrefix ( YES | NO )] [-depricatePrefix ( YES | NO )][-decrementPr
To add configurable parameters to an on-link global prefix by using the NetScaler command line
command COPY
add onLinkIPv6Prefix <ipv6Prefix> [-onlinkPrefix ( YES | NO )] [-autonomusPrefix ( YES | NO )] [-depricatePrefix ( YES | NO )][-
To set on-link link IPv6 prefix’s configurable parameters by using the NetScaler command line
command COPY
To bind an on-link link IPv6 prefix’s configurable parameters by using the NetScaler command line
command COPY
command COPY
Example
command COPY
> sh nd6RAvariables
1) Vlan : 1
2) Vlan : 2
Done
>
1) Vlan : 2
Prefix :
3ffe:501:ffff:100::/64
Done
To manage heartbeat messages on a node interf ace by using the NetScaler command line
command COPY
To know how this feature is used for monitoring static routes in ECMP deployment, see Using Equal Cost Multiple
Path (ECMP) topic.
To set owner node response status by using the NetScaler command line
command COPY
Example
command COPY
1. Navigate to System > Network > IPs and click Add to create a spotted SNIP address.
2. On the Create IP Address page, select or clear the ownerDownResponse check box.
Navigate to System > Network > IPs, select an IP address, and click Edit to select or clear the ownerDownResponse
check box.
Important: Currently, only a single-node active cluster system supports VRIDs and VRID6s.
To configure a virtual router ID on a single-node active cluster, add the VRID or VRID6 and bind it to the cluster-node
interface.
command COPY
To bind a VRID to the cluster-node interface by using the NetScaler command line.
command COPY
Example COPY
done
command COPY
To bind a VRID6 to cluster node interface by using the NetScaler command line.
Code COPY
Example COPY
Done
A two-node cluster is functional even if only one node is able to serve traffic.
Creating a two node cluster is the same as creating any other cluster. You must add one node as the configuration
coordinator and the other node as the other cluster node.
Note: Incremental configuration synchronization is not supported in a two-node cluster. Only full synchronization is
supported.
Note:
Before uploading the backed-up HA configuration file to the cluster, you must modify it to make it cluster compatible.
Refer to the relevant step of the procedure below.
Use the batch -f <backup_f ilename> command to upload the backed-up configuration file.
T he above approach is a very basic migration solution which results in downtime for the deployed application. As such, it
must be used only in deployments where there is no consideration to application availability.
However, in most deployments, the availability of the application is of paramount importance. For such cases, you must use
the approach where an HA setup can be migrated to a cluster setup without any resulting downtime. In this approach, an
existing HA setup is migrated to a cluster setup by first removing the secondary appliance and using that appliance to
create a single-node cluster. After the cluster becomes operational and serves traffic, the primary appliance of the HA
setup is added to the cluster.
To convert a HA setup to cluster setup (without any downtime) by using the command line interf ace
Let us consider the example of a HA setup with primary appliance (NS1) - 10.102.97.131 and secondary appliance (NS2) -
10.102.97.132.
should be changed to
You can transition to an L3 cluster when you want the cluster to include nodes from other networks.
1. Create a nodegroup.
Example
You can transition to an L2 cluster when you want to retain nodes that belong to a single network.
1. Remove the cluster nodes from the networks that you do not want to retain.
Example
Note:
T he parent-child topology of GSLB is not supported in a cluster.
If you have configured the static proximity GSLB method, make sure that the static proximity database is present on all
the cluster nodes. T his happens by default if the database file is available at the default location. However, if the
database file is maintained in a directory other than /var/netscaler/locdb/, you must manually synch the file to all the
cluster nodes.
Log on to the cluster IP address and perform the following operations at the command prompt:
1. Configure the different GSLB entities. For information, see Configuring Global Server Load Balancing.
Note: When creating the GSLB site, make sure that you specify the cluster IP address and public cluster IP address
(needed only when the cluster is deployed behind a NAT device). T hese parameters are required to ensure the availability
of the GSLB auto-sync functionality.
add gslb site <siteName> <siteType> <siteIPAddress> -publicIP <ip_addr> -clip <ip_addr> <publicCLIP>
Note: Enable the sticky option if you want to set up GSLB based on VPN users.
3. Bind a single cluster node to the node group.
bind cluster nodegroup <name> -node <nodeId>
Note: Make sure that the IP address of the local GSLB site IP address is striped (available across all cluster nodes).
5. Bind the ADNS (or ADNS-T CP) service or the DNS (or DNS-T CP) load balancing virtual server to the node group.
To bind the ADNS service:
7. [Optional] T o setup GSLB based on VPN users, bind the VPN virtual server to the GSLB node group.
bind cluster nodegroup <name> -vServer <string>
2. Create a node group and perform other node group related configurations.
Navigate to System > Cluster > Node Groups to perform the required configurations.
For the detailed configurations to be performed, see the description provided in the CLI procedure mentioned above.
P oint s t o remember when using cache redirect ion in t ransparent mode on a clust er:
Before configuring cache redirection, make sure that you have connected all nodes to the external switch and that you
have linksets configured. Otherwise, client requests will be dropped.
When MAC mode is enabled on a load balancing virtual server, make sure MBF mode is enabled on the cluster by using
the enable ns mode MBF command. Otherwise, the requests are sent to origin server directly instead of being sent to
the cache server.
To understand how a combination of cluster LA channel and linksets can be used, consider a three-node cluster for which
the upstream switch has only two ports available. You can connect two of the cluster nodes to the switch and leave the
other node unconnected.
Note: Similarly, you can also use a combination of ECMP and linksets in an asymmetric topology.
Figure 1. Linksets and cluster LA channel topology
To deploy a clust er wit h a common int erf ace f or t he client and server and a dif f erent int erf ace f or t he
clust er backplane
2. On the cluster IP address, create VLANs for the backplane interfaces and for the client and server interfaces.
//For the backplane interfaces
add vlan 10
bind vlan 10 0/1/1 1/1/1 2/1/1
//For the interfaces that are connected to the client and server networks.
add vlan 20
bind vlan 20 0/1/2 1/1/2 2/1/2
3. On the switch, create VLANs for the interfaces corresponding to the backplane interfaces and the client and server
interfaces. T he following sample configurations are provided for the Cisco® Nexus 7000 C7010 Release 5.2(1) switch.
Similar configurations must be performed on other switches.
//For the backplane interfaces. Repeat for each interface...
interface Ethernet2/47
switchport access vlan 100
switchport mode access
end
//For the interfaces connected to the client and server networks. Repeat for each interface...
interface Ethernet2/47
switchport access vlan 200
switchport mode access
end
2. On the cluster IP address, create VLANs for the backplane, client, and server interfaces.
//For the backplane interfaces
add vlan 10
bind vlan 10 0/1/1 1/1/1 2/1/1
To deploy a clust er wit h t he same swit ch f or t he client s and servers and a dif f erent swit ch f or t he clust er
backplane
2. On the cluster IP address, create VLANs for the backplane, client, and server interfaces.
//For the backplane interfaces
add vlan 10
bind vlan 10 0/1/1 1/1/1 2/1/1
T he cluster configurations will be the same as the other deployments scenarios. Most of the client-side configurations will
be done on the client-side switches.
In this feature, the same VMAC address is configured on both the nodes of the cluster. T his VMAC address is used in GARP
advertisements and ARP responses for the IP addresses configured on a node. T his feature is useful in an active-spare two-
node cluster setup that has external devices/routers that do not accept GARP advertisements.
With the same VMAC address on both cluster nodes, when the active node goes down and the spare node takes over as
active, the MAC address for the IP addresses on the new active node remain unchanged and the ARP tables on the
external devices/routers do not need to be updated.
Perform the following tasks on a cluster setup to configure interface based VRRP for IPv4:
Add a VRID . A VRID is an integer used by the Cluster setup to form a VMAC address.
Bind t he VRID t o node int erf aces . Bind the interfaces to the created VRID. T he bound interfaces (in the current
active node) use the VMAC address in GARP advertisements and ARP responses for its IPv4 addresses. You must
associate the VRID to the interfaces of both nodes of the active-spare cluster setup. T his is because unlike in a high
availability setup, interface IDs differ in a cluster setup.
To bind t he VRID t o an int erf ace by using t he Net Scaler Command line
To add a VRID and bind it t o int erf aces by using t he Net Scaler GUI
1. Navigate to Syst em > Net work > VMAC and, on the VMAC tab, click Add .
2. On the Creat e VMAC page, specify a value in the Virt ual Rout er ID* field, bind interfaces in the Associat e
Int erf aces section, and then click Creat e .
Done
Done
Perform the following tasks on a cluster setup to configure interface based VRRP for IPv6:
Add a VRID6 . A VRID6 is an integer used by the Cluster setup to form a VMAC6 address. T he generic VMAC6 address is
in the form of 00:00:5e:00:01:<VRID6>.
Bind t he VRID6 t o node int erf aces . Bind the interfaces to the created VRID6. T he bound interfaces (in the current
active node) use the VMAC6 address in GARP advertisements and ARP responses for its IPv6 addresses. You must
associate the VRID6 to the interfaces of both nodes of the active-spare cluster setup. T his is because unlike in a high
availability setup, interface IDs differ in a cluster setup.
To bind t he VRID6 t o an int erf ace by using t he Net Scaler Command line
To add a VRID6 and bind it t o int erf aces by using t he Net Scaler GUI
1. Navigate to Syst em > Net work > VMAC and, on the VMAC6 tab, click Add .
2. On the Creat e VMAC6 page, specify a value in the Virt ual Rout er ID* field, bind interfaces in the Associat e
Int erf aces section, and then click Creat e .
Done
Done
IP based VRRP
In IP based VRRP, striped VIP addresses bound to the same VRID are configured on all nodes of a cluster setup. T hese VIP
addresses are active on all the nodes
One of the cluster nodes acts as the VRID owner and sends out the VRRP advertisement to other nodes. In case of failure
of the VRID owner node, another node in the cluster assumes the ownership of the VRID and starts sending VRRP
advertisements. You can also assign a specific cluster node as the owner of the VRID.
Perform the following tasks on a cluster setup for configuring IP based VRRP for IPv4:
Add a VRID. A VRID is an integer used by the Cluster setup to form a VMAC address. The generic VMAC address is in the form of 00:00:5e:00:02:<VRID>.
(Optional) Assign a node as the owner of the VMAC address. You can set the owner node parameter (while adding or modifying VRID6) to the ID of the cluster
node to assign it as the owner of the VMAC address. If the assigned owner node fails, one of the UP cluster nodes is dynamically elected as the owner of the
VMAC address.
Bind the VRID to the VIP address of the nodes. Bind the created VRID to the striped VIP address.
To bind the VRID to VIP address by using the NetScaler Command line
1. Navigate to System > Network > VMAC and, on the VMAC tab, click Add.
2. On the Create VMAC page, specify a value in the Virtual Router ID* field and then click Create.
1. Navigate to System > Network > IPs, on the IPV4s tab, select a VIP address and click Edit.
2. Set the Virtual Router ID parameter while editing the VIP configuration.
Done
Done
Perform the following tasks on a cluster setup for configuring IP based VRRP for IPv6:
Add a VRID6. A VRID6 is an integer used by the Cluster setup to form a VMAC6 address. The generic VMAC6 address is in the form of 00:00:5e:00:02:<VRID6>.
(Optional) Assign a node as the owner of the VMAC6 address. You can set the owner node parameter (while adding or modifying VRID6) to the ID of the
cluster node to assign it as the owner of the VMAC6 address. If the assigned owner node fails, one of the UP cluster nodes is dynamically elected as the owner
of the VMAC6 address.
Bind the VRID6 to the VIP6 address of the nodes. Bind the created VRID6 to the striped VIP6 address.
To bind the VRID6 to VIP6 address by using the NetScaler Command line
1. Navigate to System > Network > VMAC and, on the VMAC6 tab, click Add.
2. On the Create VMAC6 page, specify a value in the Virtual Router ID* field and then click Create.
1. Navigate to System > Network > IPs, on the IPV6s tab, select a VIP address and click Edit.
2. Set the Virtual Router ID parameter while editing the VIP6 configuration.
Done
Done
A node that is being upgraded or downgraded is not removed from the cluster. T he node continues to be a part of the
cluster and serves traffic uninterrupted, except for the down-time when the node reboots after it is upgraded or
downgraded.
However, due to software version mismatch among the cluster nodes, configuration propagation is disabled on the cluster
and is enabled only after all the cluster nodes are of the same version. Since configuration propagation is disabled during
upgrading on downgrading a cluster, you cannot perform any configurations through the cluster IP address during this time.
Important
Configurations can be lost on downgrading the cluster.
When you are upgrading a cluster to NetScaler 11.0 build 64.x from an earlier NetScaler 11.0 build, cluster configuration
propagation is disabled. T his exception arises because the cluster version in build 64.x is different from the one in previous
NetScaler 11.0 builds.
Traditionally, this issue occurred only during an upgrade of a cluster to a different NetScaler version (for example, from 10.5
to 11.0). It must be noted that normally the cluster version matches the NetScaler version.
No te : Configuration propagation remains disabled until all the cluster nodes are upgraded to Build 64.x.
During the upgrade, you must not perform any configuration changes on the cluster nodes.
You cannot add cluster nodes while upgrading or downgrading the cluster software version.
You can perform node-level configurations through the NSIP address of individual nodes, but make sure to perform the
same configurations on all the nodes to maintain them in synch.
You cannot execute the "start nstrace" command from the cluster IP address when the cluster is being upgraded.
However, you can get the trace of individual nodes by performing this operation on individual cluster nodes through their
NetScaler IP (NSIP) address.
Owing to changes in cluster licensing that were made in NetScaler 10.5 Build 52.11 (see license requirements), look into
the following:
If the cluster is setup in a build prior to NetScaler 10.5 Build 52.11, the cluster will work with the separate cluster
license file. No changes are required.
If the cluster is setup in NetScaler 10.5 Build 52.11 or later releases and then downgraded to a build prior to NetScaler
10.5 Build 52.11, the downgraded cluster will not work as it now expects a separate cluster license file.
While upgrading the NetScaler appliance from a NetScaler 10.1 build to a NetScaler 10.5 build, do not execute the "show
audit messages" command as this can cause the NetScaler appliance to become unresponsive.
NetScaler 10.5 54.x and 55.x builds are not suitable for cluster deployment. T his is because, for services that need
probing, SYN packets are processed locally (on the flow receiver) even though syncookie is disabled.
When a cluster is being upgraded, it is possible that the upgraded nodes have some additional features activated that
are not available on the nodes that are not upgraded. T his results in a license mismatch warning while the cluster is being
upgraded. T his warning will be automatically resolved when all the cluster nodes are upgraded.
Important
- Citrix recommends that you wait for the previous node to become active before upgrading or downgrading the next node.
- Citrix recommends that the cluster configuration node must be upgraded/downgraded last to avoid multiple disconnect of cluster
IP sessions.
1. Make sure the cluster is stable and the configurations are synchronized on all the nodes.
2. Access each node through its NetScaler IP (NSIP) address and perform the following:
1. Upgrade or downgrade the cluster node. For detailed information about upgrading and downgrading the software of
an appliance, see Upgrading or Downgrading the System Software.
T he operations are:
For example, when you execute the command disable interface 1/1/1 from the NSIP address of a cluster node, the
interface is disabled only on that node. Since the command is not propagated, the interface 1/1/1 remains enabled on all
the other cluster nodes.
Important
T he formation or supportability of a heterogeneous cluster is possible and limited only to MPX hardware platforms.
T he supportability and formation of the heterogeneous cluster depend on certain Citrix NetScaler models. T he following
table lists the platforms that are supported in the formation of a heterogeneous cluster.
Not e: If you run the “join cluster” command from the node that has an unequal number of packet engines, the following
error message appears: “Mismatch in the number of active PPEs between CCO and local
node”.
1. T he number of packet engines present on all of the MPX hardware appliances should be same in the cluster deployment.
2. T he extra management CPU setting should be same on all the cluster nodes.
3. T he newly added node should have the same capacity on the data planes and backplane, as that of existing cluster
nodes.
4. If there are mixed platform devices supporting different ciphers, then the cluster would agree upon a common cipher list.
If you are not able to find the issue by using the above two approaches, you can use one of the following:
Isolat e t he source of t he f ailure. T ry bypassing the cluster to reach the server. If the attempt is successful, the
problem is probably with the cluster setup.
Check t he commands recent ly execut ed. Run the history command to check the recent configurations performed
on the cluster. You can also review the ns.conf file to verify the configurations that have been implemented.
Check t he ns.log f iles. Use the log files, available in the /var/log/ directory of each node, to identify the commands
executed, status of commands, and the state changes.
Check t he newnslog f iles. Use the newnslog files, available in the /var/nslog/ directory of each node, to identify the
events that have occurred on the cluster nodes. You can view multiple newnslog files as a single file, by copying the files
to a single directory, and then running the following command:
nsconmsg -K newnslog-node<id> -K newnslog.node<id> -d current
If you still cannot resolve the issue, you can try tracing the packets on the cluster or use the show techsupport -scope
cluster command to send the report to the technical support team.
Can be configured to trace packets selectively by using classic expressions and default expressions.
Can capture the trace in multiple formats: nstrace format (.cap) and T CP dump format (.pcap).
Can aggregate the trace files of all cluster nodes on the configuration coordinator.
Can merge multiple trace files into a single trace file (only for .cap files).
You can use the nstrace utility from the NetScaler command line or the NetScaler shell.
Run the start nstrace command on the appliance. T he command creates trace files in the /var/nstrace/<date-timestamp> directory. T he trace
file names are of the form nstrace<id>.cap.
You can view the status by executing the show nstrace command. You can stop tracing the packets by executing the stop nstrace command.
Note: You can also run the nstrace utility from the NetScaler shell by executing the nstrace.sh file. However, it is recommended that you use
the nstrace utility through the NetScaler command line interface.
You can trace the packets on all the cluster nodes and obtain all the trace files on the configuration coordinator.
Run the start nstrace command on the cluster IP address. T he command is propagated and executed on all the cluster nodes. T he trace files
are stored in individual cluster nodes in the /var/nstrace/<date-timestamp> directory. T he trace file names are of the form
nstrace<id>_node<id>.cap.
You can use the trace files of each node to debug the nodes operations. But if you want the trace files of all cluster nodes in one location,
you must run the stop nstrace command on the cluster IP address. T he trace files of all the nodes are downloaded on the cluster
configuration coordinator in the /var/nstrace/<date-timestamp> directory as follows:
You can prepare a single file from the trace files (supported only for .cap files) obtained from the cluster nodes. T he single trace files gives you a
cumulative view of the trace of the cluster packets. T he trace entries in the single trace file are sorted based on the time the packets were
received on the cluster.
where,
srcdir is the directory from which the trace files are merged. All trace files within this directory are merged into a single file.
dstdir is the directory where the merged trace file are created.
filename is the name of the trace file that is created.
filesize is the size of the trace file.
Following are some examples of using the nstrace utility to filter packets.
start nstrace -filter "INTF == 0/1/1 && INTF == 1/1/1 && INTF == 2/1/1"
Using def ault expressions:
start nstrace -filter "SOURCEIP == 10.102.34.201 || (SVCNAME != s1 && SOURCEPORT > 80)"
Using def ault expressions
When you run the "start nstrace" command, you can set the new "capsslkeys" parameter to capture the SSL master keys for all SSL sessions.
If you include this parameter, a file named nstrace.sslkeys is generated along with the packet trace. T his file can be imported into Wireshark to
decrypt the SSL traffic in the corresponding trace file.
T his functionality is similar to web browsers exporting session keys that can later be imported into Wireshark for decrypting SSL traffic.
1. Generates smaller trace files that do not include the extra packets created by the SSLPLAIN mode of capturing.
2. Provides the ability to view plaintext [SP(1] from the trace and choose whether to share the master keys file or protect sensitive data by
not sharing it.
1. SSL sessions cannot be decrypted if initial packets of the session are not captured.
2. SSL sessions cannot be captured if the Federal Information Processing Standard (FIPS) mode is enabled.
To capt ure SSL session keys by using t he command line int erf ace (CLI)
At the command prompt, type the following commands to enable or disable SSL session keys in a trace file and verify trace operation.
Example
Done
To configure content switching, first create a basic content switching setup, and then customize it to meet your needs.
T his entails enabling the content switching feature, setting up load balancing for the server or servers that host each
version of the content that is being switched, creating a content switching virtual server, creating policies to choose which
requests are directed to which load balancing virtual server, and binding the policies to the content switching virtual server.
You can then customize the setup to meet your needs by setting precedence for your policies, protecting your setup by
configuring a backup virtual server, and improving the performance of your setup by redirecting requests to a cache.
Content Switching enables the NetScaler appliance to direct requests sent to the same Web host to different servers with
different content. For example, you can configure the appliance to direct requests for dynamic content (such as URLs with
a suffix of .asp, .dll, or .exe) to one server and requests for static content to another server. You can configure the appliance
to perform content switching based on TCP/IP headers and payload.
You can also use content switching to configure the appliance to redirect requests to different servers with different
content on the basis of various client attributes. Some of those client attributes are:
Device T ype. T he appliance examines the user agent or custom HT T P header in the client request for the type of
device from which the request originated. Based on the device type, it directs the request to a specific Web server. For
example, if the request came from a cell phone, the request is directed to a server that is capable of serving content that
the user can view on his or her cell phone. A request from a computer is directed to a different server that is capable of
serving content designed for a computer screen.
Language. T he appliance examines the Accept-Language HT T P header in the client request and determines the
language used by the client's browser. T he appliance then sends the request to a server that serves content in that
language. For example, using content switching based on language, the appliance can send someone whose browser is
configured to request content in French to a server with the French version of a newspaper. It can send someone else
whose browser is configured to request content in English to a server with the English version.
Cookie. T he appliance examines the HT T P request headers for a cookie that the server set previously. If it finds the
cookie, it directs requests to the appropriate server, which hosts custom content. For example, if a cookie is found that
indicates that the client is a member of a customer loyalty program, the request is directed to a faster server or one with
special content. If it does not find a cookie, or if the cookie indicates that the user is not a member, the request is
directed to a server for the general public.
HT T P Met hod. T he appliance examines the HT T P header for the method used, and sends the client request to the
right server. For example, GET requests for images can be directed to an image server, while POST requests can be
directed to a faster server that handles dynamic content.
Layer 3/4 Dat a. T he appliance examines requests for the source or destination IP, source or destination port, or any
A typical content switching deployment consists of the entities described in the following diagram.
A content switching configuration consists of a content switching virtual server, a load balancing setup consisting of load
balancing virtual servers and services, and content switching policies. To configure content switching, you must configure a
content switching virtual server and associate it with policies and load balancing virtual servers. T his process creates a
content group— a group of all virtual servers and policies involved in a particular content switching configuration.
Content switching can be used with HT T P, HT T PS, TCP, and UDP connections. For HT T PS, you must enable SSL Offload.
When a request reaches the content switching virtual server, the virtual server applies the associated content switching
policies to that request. T he priority of the policy defines the order in which the policies bound to the content switching
virtual server are evaluated. If you are using default syntax policies, when you bind a policy to the content switching virtual
server, you must assign a priority to that policy. If you are using NetScaler classic policies, you can assign a priority to your
policies, but are not required to do so. If you assign priorities, the policies are evaluated in the order that you set. If you do
not, the NetScaler appliance evaluates your policies in the order in which they were created.
In addition to configuring policy priorities, you can manipulate the order of policy evaluation by using Goto expressions and
policy bank invocations. For more details about default syntax policy configuration, see "Configuring Default Syntax
Policies."
After it evaluates the policies, the content switching virtual server routes the request to the appropriate load balancing
virtual server, which sends it to the appropriate service.
Content switching virtual servers can only send requests to other virtual servers. If you are using an external load balancer,
Warning
T he Content Switching Classic policy is deprecated from NetScaler 12.0 onwards and as an alternative, Citrix recommends you to
use the Content Switching advanced policies. You can also use the nspepi utility tool for the conversion.
Before you configure content switching, you must understand how content switching is set up and how the services and
virtual servers are connected.
To configure a basic, functional content switching setup, first enable the content switching feature. T hen, create at least
one content group. For each content group, create a content switching virtual server to accept requests to a group of web
sites that use content switching. Also create a load balancing setup, which includes a group of load balancing virtual servers
to which the content switching virtual server directs requests. To specify which requests to direct to which load balancing
virtual server, create at least two content switching policies, one for each type of request that is to be redirected. When
you have created the virtual servers and policies, bind the policies to the content switching virtual server. You can also bind a
policy to multiple content switching virtual servers. When you bind a policy, you specify the load balancing virtual server to
which requests that match the policy are to be directed.
In addition to binding individual policies to a content switching virtual server, you can bind policy labels. If you create
additional content groups, you can bind a policy or policy label to more than one of the content switching virtual servers.
Note: After creating a content group, you can modify its content switching virtual serve to customize the configuration.
For information on modifying the configuration of an existing content switching virtual server, see "Customizing the Basic
Content Switching Configuration." For information on disabling and re-enabling entities, unbinding policies, and removing
entities, see "Managing a Content Switching Setup."
T his section includes the following details:
Enabling Content Switching
Creating Content Switching Virtual Servers
Configuring a Load Balancing Setup for Content Switching
Configuring a Content Switching Action
Configuring Content Switching Policies
Configuring Content Switching Policy Labels
Binding Policies to a Content Switching Virtual Server
Configuring Policy Based Logging for Content Switching
Verifying the Configuration
At the command prompt, type the following commands to enable content switching and verify the configuration:
enable ns feature CS
show ns feature
Example
Navigate to System > Settings and, in the Modes and Features group, select Configure Basic Features, and select Content
Switching.
Navigate to Traffic Management > Content Switching > Virtual Servers, and add a virtual server.
T he content switching virtual server redirects all requests to a load balancing virtual server. You must create one load
balancing virtual server for each version of the content that is being switched. T his is true even when your setup has only
one server for each version of the content, and you are therefore not doing any load balancing with those servers. You can
also configure actual load balancing with multiple load-balanced servers that mirror each version of the content. In either
scenario, the content switching virtual server needs to have a specific load balancing virtual server assigned to each version
of the content that is being switched.
T he load balancing virtual server then forwards the request to a service. If it has only one service bound to it, it selects that
service. If it has multiple services bound to it, it uses its configured load balancing method to select a service for the request,
and forwards that request to the service that it selected.
To configure a basic load balancing setup, you need to perform the following tasks:
For more information on load balancing, see "Load Balancing." For detailed instructions on setting up a basic load balancing
configuration, see Setting Up Basic Load Balancing.
However, if your content switching policy uses a default syntax rule, you can configure an action for the policy. In the
action, you can specify the name of the target load balancing virtual server, or you can configure a request-based
expression that, at run time, computes the name of the load balancing virtual server to which to send the request. T he
action expression must be specified in the default syntax.
T he expression option can drastically reduce the size of your content switching configuration, because you need only one
policy per content switching virtual server. Content switching policies that use an action can also be bound to multiple
content switching virtual servers, because the target load balancing virtual server is no longer specified in the content
switching policy. T he ability to bind a single policy to multiple content switching virtual servers helps to further reduce the
size of your content switching configuration.
After you create an action, you create a content switching policy and specify the action in the policy, so that the action is
performed when that policy matches a request.
Note: You can also, for a content switching policy that uses a default syntax rule, specify the target load balancing virtual
server when binding the policy to a content switching virtual server, instead of using a separate action. For domain-based
policies, URL-based policies, and rule based policies that use classic expressions, an action is not available. So, for these types
of policies, you specify the name of the target load balancing virtual server when binding the policy to a content switching
virtual server. For more information, see "Binding Policies to a Content Switching Virtual Server."
Configuring an Action that Specifies the Name of the Target Load Balancing Virtual Server
If you choose to specify the name of the target load balancing virtual server in a content switching action, you need as
many content switching policies as you have target load balancing virtual servers. Content switching decisions, in this case,
are based on the rule in the content switching policy, and the action merely specifies the target load balancing virtual
server. When a request matches the policy, the request is forwarded to the specified load balancing virtual server.
To create and verify a content switching action that specifies the name of the
target load balancing virtual server, by using the command line interface
At the command prompt, type:
Example
> add cs action mycsaction -targetLBVserver mylbvserver -comment "Forwards requests to mylbvserver."
Done
> show cs action mycsaction
Name: mycsaction
Target LB Vserver: mylbvserver
Hits: 0
Undef Hits: 0
Done
>
To configure a content switching action that specifies the name of the target load
balancing virtual server, by using the configuration utility
1. Navigate to T raffic Management > Content Switching > Actions.
2. Configure a content switching action, and specify the name of the target load balancing virtual server.
Configuring an Action that Specifies an Expression f or Selecting the Target at Run Time
If you choose to configure a request-based expression that can dynamically compute the name of the target load
balancing virtual server, you need to configure only one content switching policy to select the appropriate virtual server. T he
rule for the policy can be a simple TRUE (the policy matches all requests) because, in this case, content switching decisions
are based on the expression in the action. By configuring an expression in an action, you can drastically reduce the size of
your content switching configuration.
If you choose to configure a request-based expression for computing the name of the target load balancing virtual server
at run time, you must carefully consider how to name the load balancing virtual servers in the configuration. You must be
able to derive their names by using the request-based policy expression in the action.
For example, if you are switching requests on the basis of the URL suffix (file extension of the requested resource), when
naming the load balancing virtual servers, you can follow the convention of appending the URL suffix to a predetermined
string, such as mylb_. For example, load balancing virtual servers for HT ML pages and PDF files could be named mylb_html
and mylb_pdf, respectively. In that case, the rule that you can use in the content switching action, to select the appropriate
load balancing virtual server, is "mylb_"+HTTP.REQ.URL.SUFFIX. If the content switching virtual server receives a request
for an HT ML page, the expression returns mylb_html, and the request is switched to virtual server mylb_html.
Example
Domain-based policies. T he NetScaler appliance compares the domain of an incoming URL with the domains specified
in the policies. T he appliance then returns the most appropriate content. Domain-based policies must be classic policies;
default syntax policies are not supported for this type of content switching policy.
URL-based policies. T he appliance compares an incoming URL with the URLs specified in the policies. T he appliance then
returns the most appropriate URL-based content, which is usually the longest matching configured URL. URL-based
policies must be classic policies; default syntax policies are not supported for this type of content switching policy.
Rule-based policies. T he appliance compares incoming data to expressions specified in the policies. You create rule-
based policies by using either a classic expression or a default syntax expression. Both classic and default syntax policies
are supported for rule-based content switching policies.
Note: A rule based policy can be configured with an optional action. A policy with an action can be bound to multiple
virtual servers or policy labels.
If you set a priority when binding your policies to the content switching virtual server, the policies are evaluated in order
of priority. If you do not set specific priorities when binding your policies, the policies are evaluated in the order in which
they were created.
For information about NetScaler classic policies and expressions, see "Configuring Classic Policies and Expressions." For
information about Default Syntax policies, see "Configuring Default Syntax Expressions."
To create a content switching policy by using the command line interf ace
Example
Navigate to Traffic Management > Content Switching > Policies, select a policy and, in the Action list, select Rename.
Navigate to Traffic Management > Content Switching > Policies, and configure a content switching policy.
For information about policy labels, see the "Creating Policy Labels."
A content switching policy label consists of a name, a label type, and a list of policies bound to the policy label. T he policy
label type specifies the protocol that was assigned to the policies bound to the label. It must match the service type of the
content switching virtual server to which the policy that invokes the policy label is bound. For example, you can bind TCP
Payload policies to a policy label of type TCP only. Binding TCP Payload policies to a policy label of type HT T P is not
supported.
Each policy in a content switching policy label is associated with either a target (which is equivalent to the action that is
associated with other types of policies, such as rewrite and responder policies) or a gotoPriorityExpression option and/or an
invoke option. T hat is, for a given policy in a content switching policy label, you can specify a target, or you can set the
gotoPriorityExpression option and/or the invoke option. Additionally, if multiple policies evaluate to true, only the target of
the last policy that evaluates to true is considered.
You can use either the NetScaler command line or the configuration utility to configure content switching policy labels. In
the NetScaler command-line interface (CLI), you first create a policy label by using the add cs policylabel command. T hen,
you bind policies to the policy label, one policy at a time, by using the bind cs policylabel command. In the NetScaler
configuration utility, you perform both tasks in a single dialog box.
To create a content switching policy label by using the command line interf ace
Navigate to Traffic Management > Content Switching > Policy Labels , select a policy label and, in the Action list, select
Rename.
At the command prompt, type the following commands to bind a policy to a policy label and verify the configuration:
Example
At the command prompt, type the following commands to unbind a policy from a policy label and verify the configuration:
Example
rm cs policylabel <labelName>
To manage a content switching policy label by using the configuration utility
Navigate to Traffic Management > Content Switching > Policy Labels, configure a policy label, bind policies to the label, and
optionally specify a priority, gotoPriority expression, and an invoke option.
Note: If your content switching policy uses a default syntax rule, you can configure a content switching action for the
policy. If you configure an action, you must specify the target load balancing virtual server when you are configuring the
action, not when you are binding the policy to the content switching virtual server. For more information about configuring
a content switching action, see Configuring a Content Switching Action.
To bind a policy to a content switching virtual server and select a target load balancing virtual server by using
the command line interf ace
Navigate to T raffic Management > Content Switching > Virtual Servers, open a virtual server and, in the Content Switching
Policy Binding section, bind a policy to the virtual server, and specify a target load balancing virtual server.
Note: If multiple policies bound to a given virtual server evaluate to T RUE and are configured with an audit message action,
the NetScaler appliance does not perform all the audit message actions. It performs only the audit message action that is
configured for the policy whose content switching action is performed.
To configure policy based logging for a content switching policy, you must first configure an audit message action. For more
information about configuring an audit message action, see Configuring the NetScaler Appliance for Audit Logging. After
you configure the audit message action, you specify the action in a content switching policy.
To configure policy based logging f or a content switching policy by using the command line interf ace
At the command line, type the following commands to configure policy based logging for a content switching policy and
verify the configuration:
Example
> set cs policy cspol1 -logAction csLogAction
Done
> show cs policy cspol1
1) CS Vserver: csvs1
Priority: 10
Done
>
To configure policy based logging f or a content switching policy by using the configuration utility
Navigate to Traffic Management > Content Switching > Policies, open a policy and, in the Log Action list, select a log action
for the policy.
Updated: 2013-10-31
You can view the properties of content switching virtual servers that you have configured on the NetScaler. You can use
the information to verify whether the virtual server is correctly configured and, if necessary, to troubleshoot. In addition to
details such as name, IP address, and port, you can view the various policies bound to a virtual server, and its traffic-
management settings.
T he content switching policies are displayed in the order of their priority. If more than one policy has the same priority, they
are shown in the order in which they are bound to the virtual server.
Note: If you have configured the content switching virtual server to forward traffic to a load balancing virtual server, you
can also view the content switching policies by viewing the properties of the load balancing virtual server.
To view the properties of content switching virtual servers by using the command
line interface
To list basic properties of all content switching virtual servers in your configuration, or detailed properties of a specific
content switching virtual server, at the command prompt, type one of the following commands:
show cs vserver
show cs vserver <name>
Example
1.
show cs vserver Vserver-CS-1
Vserver-CS-1 (10.102.29.161:80) - HTTP Type: CONTENT
State: UP
Last state change was at Thu Jun 30 10:48:59 2011
Time since last state change: 6 days, 20:03:00.760
Client Idle Timeout: 180 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
Appflow logging: DISABLED
Port Rewrite : DISABLED
State Update: DISABLED
Default: Content Precedence: RULE
Vserver IP and Port insertion: OFF
Case Sensitivity: ON
Push: DISABLED Push VServer:
Push Label Rule: none
2.
show cs vserver
1) Vserver-CS-1 (10.102.29.161:80) - HTTP Type: CONTENT
State: UP
…
Appflow logging: DISABLED
Port Rewrite : DISABLED
State Update: DISABLED
You can view the properties of the content switching policies that you defined, such as the name, domain, and URL or
expression, and use the information to find any mistakes in the configuration, or to troubleshoot if something is not
working as it should.
To view the properties of content switching policies by using the command line
interface
To list either basic properties of all content switching policies in your configuration or detailed properties of a specific
content switching policy, at the command prompt, type one of the following commands:
show cs policy
show cs policy <PolicyName>
Example
show cs policy
T he Content Switching Visualizer is a tool that you can use to view a content switching configuration in graphical format.
You can use the visualizer to view the following configuration items:
A summary of the load balancing virtual servers to which the content switching virtual server is bound.
All services and service groups that are bound to the load balancing virtual server and all monitors that are bound to the
services.
T he configuration details of any displayed element.
Any policies bound to the content switching virtual server. T hese policies need not be content switching policies. Many
types of policies, such as Rewrite policies, can be bound to a content switching virtual server.
After you configure the various elements in a content switching and load balancing setup, you can export the entire
configuration to an application template file.
Note: T he Visualizer requires a graphical interface, so it is available only through the configuration utility.
To view a content switching configuration by using the Visualizer in the
configuration utility
T o customize the basic content switching configuration, see the following sections:
Configuring Case Sensitivity for Policy Evaluation
Setting the Precedence for Policy Evaluation
Support for Multiple Ports for HT T P and SSL T ype Content Switching Virtual Servers
Configuring per-VLAN Wildcarded Virtual Servers
Configuring the Microsoft SQL Server Version Setting
You can configure the content switching virtual server to treat URLs as case sensitive in URL-based policies. When case sensitivity is configured, the NetScaler appliance
considers case when evaluating policies. For example, if case sensitivity is off, the URLs /a/1.htm and /A/1.HT M are treated as identical. If case sensitivity is on, those URLs
are treated as separate and can be switched to different targets.
If you configure precedence based on URL, the request URL is compared to the configured URLs. If none of the configured URLs match the request URL, then rule-based policies are checked. If the request URL does not match
any rule-based policies, or if the content group selected for the request is down, then the request is processed as follows:
If you configure a default group for the content switching virtual server, then the request is forwarded to the default group.
If the configured default group is down or if no default group is configured, then an “HTTP 404 Not Found” error message is sent to the client.
Note: You should configure URL-based precedence if the content type (for example, images) is the same for all clients. However, if different types of content must be served based on client attributes (such as Accept-Language),
you must use rule-based precedence.
If a default group is configured for the content switching virtual server, the request is forwarded to the default group.
If the configured default group is down or if no default group is configured, an “HTTP 404 Not Found” error message is sent to the client.
1. Navigate to Traffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Traffic Settings, and then specify Precedence.
Support f or Multiple Ports f or HTTP and SSL Type Content Switching Virtual Servers
You can configure the NetScaler ADC so that HT T P and SSL content switching virtual servers listen on multiple ports, without having to configure separate virtual servers.
T his feature is especially useful if you want to base a content switching decision on a part of the URL and other L7 parameters. Instead of configuring multiple virtual
servers with the same IP address and different ports, you can configure one IP address and specify the port as *. As a result, the configuration size is also reduced.
To configure an HTTP or SSL content switching virtual server to listen on multiple ports by using the command line
At the command prompt, type:
If you want to configure content switching for traffic on a specific virtual local area network (VLAN), you can create a wildcarded virtual server with a listen policy that
restricts it to processing traffic only on the specified VLAN.
To configure a wildcarded virtual server that listens to a specific VLAN by using the command line interface
At the command prompt, type:
add cs vserver <name> <serviceT ype> IPAddress * Port * -listenpolicy <expression> [-listenpriority <positive_integer>]
Example
To configure a wildcarded virtual server that listens to a specific VLAN by using the configuration utility
Navigate to Traffic Management > Content Switching > Virtual Servers, and configure a virtual server. Specify a listen policy that restricts it to processing traffic only on the
specified VLAN.
To set the Microsoft SQL Server version parameter by using the command line interface
At the command prompt, type the following commands to set the Microsoft SQL Server version parameter for a content switching virtual server and verify the configuration:
Example
> set cs vserver myMSSQLcsvip -mssqlServerVersion 2008R2 Done > show cs vserver myMSSQLcsvip myMSSQLcsvip (192.0.2.13:1433) - MSSQL Type: CONTENT State: UP . . . . . . MSsql Server Version: 2008R2 . . . . . . Done >
To set the Microsoft SQL Server version parameter by using the configuration utility
1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server and specify the protocol as MYSQL.
2. In Advanced Settings, select MySQL, and specify the Server Version.
A diameter interface provides a connection between the different diameter nodes. T he following sample deployment uses
Cx and Rx interfaces. A Cx interface provides a connection between a CSCF and an HSS. An Rx interface provides a
connection between a CSCF and a PCRF. All the messages reach the NetScaler appliance. Depending on whether the
message is for a Cx or an Rx interface, and on the content switching policies defined, the NetScaler selects an appropriate
load balancing server pool.
Sample Configuration
1. For each entity, create a service, a load balancing server, and bind the service to the virtual server.
add service svc_pcrf[1-3] 1.1.1.1[1-3] DIAMETER 3868
add service svc_hss[1-3] 1.1.1.2[1-3] DIAMETER 3868
add lb vserver vs_rx DIAMETER -persistenceType DIAMETER –persistavpno 263
add lb vserver vs_cx DIAMETER -persistenceType DIAMETER –persistavpno 263
bind lb vserver vs_rx svc_pcrf[1-3]
bind lb vserver vs_cx svc_hss[1-3]
If the primary content switching virtual server is marked DOWN or DISABLED, the NetScaler appliance can direct requests to a backup
content switching virtual server. It can also send a notification message to the client regarding the site outage or maintenance. T he
backup content switching virtual server is a proxy and is transparent to the client.
When configuring the backup virtual server, you can specify the configuration parameter Disable Primary When Down to ensure that,
when the primary virtual server comes back up, it remains the secondary until you manually force it to take over as the primary. T his is
useful if you want to ensure that any updates to the database on the server for the backup are preserved, enabling you to
synchronize the databases before restoring the primary virtual server.
You can configure a backup content switching virtual server when you create a content switching virtual server or when you change
the optional parameters of an existing content switching virtual server. You can also configure a backup content switching virtual
server for an existing backup content switching virtual server, thus creating cascaded backup content switching virtual servers. T he
maximum depth of cascaded backup content switching virtual servers is 10. T he appliance searches for a backup content switching
virtual server that is up and accesses that content switching virtual server to deliver the content.
Note: If a content switching virtual server is configured with both a backup content switching virtual server and a redirect URL, the
backup content switching virtual server takes precedence over the redirect URL. T he redirect is used when the primary and backup
virtual servers are down.
To set up a backup content switching virtual server by using the command line interface
At the command prompt, type:
T he spillover option diverts new connections arriving at a content switching virtual server to a backup content switching virtual server
when the number of connections to the content switching virtual server exceeds the configured threshold value. T he threshold value is
dynamically calculated, or you can set the value. T he number of established connections (in case of TCP) at the virtual server is
If the backup content switching virtual servers reach the configured threshold and are unable to take the load, the primary content
switching virtual server diverts all requests to the redirect URL. If a redirect URL is not configured on the primary content switching
virtual server, subsequent requests are dropped.
set cs vserver <name> -soMethod <methodT ype> -soT hreshold <thresholdValue> -soPersistence <persistenceValue>
-soPersistenceT imeout <timeoutValue>
Example
set cs vserver Vserver-CS-1 -soMethod Connection -soThreshold 1000 -soPersistence enabled -soPersistenceTimeout 2
To set a content switching virtual server to divert new connections to a backup virtual
server by using the configuration utility
1. Navigate to T raffic Management > Content Switching > Virtual Servers, configure a virtual server and specify the protocol as
MYSQL.
2. In Advanced Settings, select Protection, and configure spillover.
Redirect URLs can be absolute URLs or relative URLs. If the configured redirect URL contains an absolute URL, the HTTP redirect is sent to the configured location, regardless of
the URL specified in the incoming HTTP request. If the configured redirect URL contains only the domain name (relative URL), the HTTP redirect is sent to a location after
appending the incoming URL to the domain configured in the redirect URL.
Citrix recommends using an absolute URL. That is, a URL ending in /, for example www.example.com/ instead of a relative URL. A relative URL redirection might result in the
vulnerability scanner reporting a false positive.
Note: If a content switching virtual server is configured with both a backup virtual server and a redirect URL, the backup virtual server takes precedence over the redirect URL. A
redirect URL is used when the primary and backup virtual servers are down.
When redirection is configured and the content switching virtual server is unavailable, the appliance issues an HTTP 302 redirect to the user’s browser.
To configure a redirect URL for when the content switching virtual server is unavailable by
using the command line interface
At the command prompt, type:
To configure a redirect URL for when the content switching virtual server is unavailable by
using the configuration utility
1. Navigate to Traffic Management > Content Switching > Virtual Servers, configure a virtual server and specify the protocol as MYSQL.
2. In Advanced Settings, select Protection, and specify a Redirect URL.
T he content switching feature enables the distribution of client requests across multiple servers on the basis of the specific content
For smooth traffic management, it is important for the content switching virtual server to know the status of the load balancing
virtual servers. T he state update option helps to mark the content switching virtual server DOWN if the load balancing virtual server
bound to it is marked DOWN. A load balancing virtual server is marked DOWN if all the physical servers bound to it are marked DOWN.
T he status of the content switching virtual server is marked as UP. It remains UP even if there is no bound load balancing virtual server
that is UP.
When you add a new content switching virtual server, initially, its status is shown as DOWN. When you bind a load balancing virtual
server whose status is UP, the status of the content switching virtual server becomes UP.
If more than one load balancing virtual server is bound and if one of them is specified as the default, the status of the content
switching virtual server reflects the status of the default load balancing virtual server.
If more than one load balancing virtual server is bound without any of them being specified as the default, the status of the content
switching virtual server is marked UP only if all the bound load balancing virtual servers are UP.
To configure the state update option by using the command line interface
At the command prompt, type:
When a physical server receives a surge of requests, it becomes slow to respond to the clients that are currently connected to it, which
leaves users dissatisfied and disgruntled. Often, the overload also causes clients to receive error pages. T o avoid such overloads, the
NetScaler appliance provides features such as surge protection, which controls the rate at which new connections to a service can be
established.
T he appliance does connection multiplexing between clients and physical servers. When it receives a client request to access a service
on a server, the appliance looks for an already established connection to the server that is free. If it finds a free connection, it uses
that connection to establish a virtual link between the client and the server. If it does not find an existing free connection, the
appliance establishes a new connection with the server, and establishes a virtual link between client and the server. However, if the
appliance cannot establish a new connection with the server, it sends the client request to a surge queue. If all the physical servers
bound to the load balancing or content switching virtual server reach the upper limit on client connections (max client value, surge
protection threshold or maximum capacity of the service), the appliance cannot establish a connection with any server. T he surge
protection feature uses the surge queue to regulate the speed at which connections are opened with the physical servers. T he
appliance maintains a different surge queue for each service bound to the virtual server.
If the surge queue for a service or service group becomes too long, you may want to flush it. You can flush the surge queue of a
specific service or service group, or of all the services and service groups bound to a load balancing virtual server. Flushing a surge queue
does not affect the existing connections. Only the requests present in the surge queue get deleted. For those requests, the client has
to make a fresh request.
You can also flush the surge queue of a content switching virtual server. If a content switching virtual server forwards some requests
to a particular load balancing virtual server, and the load balancing virtual server also receives some other requests, when you flush the
surge queue of the content switching virtual server, only the requests received from this content switching virtual server are flushed;
the other requests in the surge queue of the load balancing virtual server are not flushed.
Note: You cannot flush the surge queues of cache redirection, authentication, VPN or GSLB virtual servers or GSLB services.
Note: Do not use the Surge Protection feature if Use Source IP (USIP) is enabled.
To flush a surge queue by using the command line interface
T he flush ns surgeQ command works in the following manner:
You can specify the name of a service, service group, or virtual server whose surge queue has to be flushed.
If you specify a name while executing the command, surge queue of the specified entity will be flushed. If more than one entity has
the same name, the appliance flushes surge queues of all those entities.
If you specify the name of a service group, and a server name and port while executing the command, the appliance flushes the
surge queue of only the specified service group member.
You cannot directly specify a service group member (<serverName> and <port>) without specifying the name of the service group
(<name>) and you cannot specify <port> without a <serverName>. Specify the <serverName> and <port> if you want to flush the
surge queue for a specific service group member.
If you execute the command without specifying any names, the appliance flushes the surge queues of all the entities present on
the appliance.
If a service group member is identified with a server name, you must specify the server name in this command; you cannot specify its
IP address.
1.
flush ns surgeQ –name SVC1ANZGB –serverName 10.10.10.1 80
The above command flushes the surge queue of the service or virtual server that is named SVC1ANZGB and has IP address as 10.10.10
2.
flush ns surgeQ
The above command flushes all the surge queues on the appliance.
To flush a surge queue by using the configuration utility
Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server and, in the Action list, select Flush Surge
Queue.
T hese tasks may require unbinding policies from the content switching virtual server, or disabling or removing content
switching virtual servers. After you have made changes to your setup, you may need to re-enable servers and rebind policies.
You might also want to rename your virtual servers.
When you unbind a content switching policy from its virtual server, the virtual server no longer includes that policy when
determining where to direct requests.
To unbind a policy from a content switching virtual server by using the command
line interface
At the command prompt, type:
You normally remove a content switching virtual server only when you no longer require the virtual server. When you remove
a content switching virtual server, the NetScaler appliance first unbinds all policies from the content switching virtual server,
and then removes it.
To remove a content switching virtual server by using the command line interface
At the command prompt, type:
rm cs vserver Vserver-CS-1
Content switching virtual servers are enabled by default when you create them. You can disable a content switching virtual
server for maintenance. If you disable the content switching virtual server, the state of the content switching virtual server
changes to Out of Service. While out of service, the content switching virtual server does not respond to requests.
Example
You can rename a content switching virtual server without unbinding it. T he new name is propagated automatically to all
affected parts of the NetScaler configuration.
Domain and Exact Requests must match the configured domain name and configured URL (an exact prefix match if only the prefix is configured; or an
URL exact match of the prefix and suffix if both the prefix and suffix are configured).
Example:
Domain and Wild Requests must match the exact domain name and a partial prefix of the configured URL.
Card URL
Example:
Domain Only Requests need match only the configured domain name.
Example:
The Exact URL The incoming URL must exactly match the URL specified by the policy. If only a URL prefix rule is configured, there must be an exact
prefix match with the incoming URL. If a URL prefix and suffix-based rule is configured, there should be an exact match of the prefix
and suffix with the incoming URL.
Example:
Prefix Only (Wild All the incoming URLs must start with the configured prefix.
Card URL)
Example:
sports/*” matches all URLs under /sports “/sports*” matches all URLs whose prefix match “/sports” starting from the beginning of a
URL
Suffix Only (Wild All incoming URLs must end with the configured URL suffix.
Card URL)
Example:
“/*.jsp” matches all All incoming URLs must start with the configured prefix and end with the configured suffix.
URLs whose file
extension is “jsp” Example:
Note: You can configure rule-based content switching using classical policy expressions or advanced policy expressions.
Example
rm cs policy Policy-CS-1
T he NetScaler cache redirection feature redirects HT T P requests to a cache. You can significantly reduce the burden of
responding to HT T P requests and improve your Web site performance through proper implementation of the cache
redirection feature.
A cache stores frequently requested HT T P content. When you configure cache redirection on a virtual server, the NetScaler
appliance sends cacheable HT T P requests to the cache and non-cacheable HT T P requests to the origin Web server. For
more information on cache redirection, see "Cache Redirection."
To configure the down state flush setting on a virtual server by using the
command line interface
At the command prompt, type:
Virtual servers and the services that are bound to them may use different ports. When a service responds to an HT T P
connection with a redirect, you may need to configure the NetScaler appliance to modify the port and the protocol to
ensure that the redirection goes through successfully. You do this by enabling and configuring the redirectPortRewrite
setting.
Inserting the IP Address and Port of a Virtual Server in the Request Header
If you have multiple virtual servers that communicate with different applications on the same service, you must configure
the NetScaler appliance to add the IP address and port number of the appropriate virtual server to the HT T P requests that
are sent to that service. T his setting allows applications running on the service to identify the virtual server that sent the
request.
If the primary virtual server is down and the backup virtual server is up, the configuration settings of the backup virtual server
are added to the client requests. If you want the same header tag to be added, regardless of whether the requests are
Note: T his option is not supported for wildcarded virtual servers or dummy virtual servers.
To insert the IP address and port of the virtual server in the client requests by using
the command line interface
At the command prompt, type:
You can configure a virtual server to terminate any idle client connections after a configured time-out period elapses. When
you configure this setting, the NetScaler appliance waits for the time you specify and, if the client is idle after that time, it
closes the client connection.
To set a time-out value for idle client connections by using the command line
interface
At the command prompt, type:
To set a time-out value for idle client connections by using the configuration utility
1. Navigate to T raffic Management > Content Switching > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select T raffic Settings, and specify a Client Idle T ime-Out value.
Identif ying Connections with the 4-tuple and Layer 2 Connection Parameters
You can now set the L2Conn option for a content switching virtual server. With the L2Conn option set, connections to the
content switching virtual server are identified by the combination of the 4-tuple (<source IP>:<source port>::<destination
IP>:<destination port>) and Layer 2 connection parameters. T he Layer 2 connection parameters are the MAC address, VLAN
ID, and channel ID.
To set the L2Conn option for a content switching virtual server by using the
Example
For best results, use the following resources to troubleshoot a content switching issue on a NetScaler appliance:
Configuration file
Relevant newnslog file
T race files
Network topology diagram for the network setup of the customer
Citrix documentation, such as release notes, Knowledge Center articles, and eDocs
T he most common content switching issues involve the content switching feature not working at all, or working only
intermittently, and Service Unavailable responses.
Issue
T he content switching feature is not functioning.
Resolution
Resolution
Verify the URL and policy bindings. T he client receives the 503 response when none of the policies you have
configured is evaluated and no default load balancing virtual server is defined and bound to the content switching
virtual server.
From the configuration, verify the policies and URL being accessed by the client.
Verify that for every type of request the respective policy is evaluated. If the policy is not evaluated, check the policy
expression and update it if necessary.
Verify the URL and HT T P request and response headers. T o do so, record an HT T PHeader trace and, if necessary,
record the packet traces on the appliance and the client.
Resolution
Study the network topology diagram, if available, of the setup to understand the various devices installed between
the client and the server(s).
Verify the configuration and policy bindings. Make sure that the URL in the policy expression matches to the one in
the client request.
Verify that appropriate priorities are assigned to the policies. An incorrect precedence or priority assigned to a policy
can cause a problem.
Run the following commands to verify the bindings and the values of the policy hit counters in the output of the
commands:
show cs vserver <CS VServer>
Using iehttpheaders or a similar utility, determine whether the HT T P headers for the requests or responses provide
any pointers to the issue.
Check the release notes and Knowledge Center articles.
If the issue is still not resolved, contact Citrix T echnical Support with appropriate data for further investigation.
When deployed in front of database servers, a NetScaler ensures optimal distribution of traffic from the application servers
and Web servers. Administrators can segment traffic according to information in the SQL query and on the basis of
database names, usernames, character sets, and packet size.
You can either configure load balancing to switch requests based on load balancing algorithms or elaborate the switching
criteria by configuring content switching to make a decision based on an SQL query parameters. You can further configure
monitors to track the state of database servers.
Note: NetScaler DataStream is supported only for MySQL and MS SQL databases. For information about the supported
protocol version, character sets, special queries, and transactions, see DataStream Reference.
How NetScaler DataStream Works
In DataStream, the NetScaler is placed in-line between the application and/or Web servers and the database servers. On
the NetScaler appliance, the database servers are represented by services.
A typical DataStream deployment consists of the entities described in the following diagram.
As shown in this figure, a DataStream configuration can consist of an optional content switching virtual server (CS), a load
balancing setup consisting of load balancing virtual servers (LB1 and LB2) and services (Svc1, Svc2, Svc3, and Svc4), and
content switching policies (optional).
T he clients (application or Web servers) send requests to the IP address of a content switching virtual server (CS) configured
If a content switching virtual server is not configured on the NetScaler, the clients (application or Web servers) send their
requests to the IP address of a load balancing virtual server configured on the NetScaler appliance. T he NetScaler
authenticates the client by using the database user credentials configured on the NetScaler appliance, and then uses the
same credentials to authenticate the connection with the database server. T he load balancing virtual server distributes the
requests to the database servers according to the load balancing algorithm. T he most effective load balancing algorithm
for database switching is the least connection method.
DataStream uses connection multiplexing to enable multiple client-side requests to be made over the same server-side
connection. T he following connection properties are considered:
User name
Database name
Packet size
Character set
You need to configure your database user name and password on the NetScaler ADC. For example, if you have a user John
configured on the database, you need to configure the user John on the ADC too. When you add the database user names
and passwords on the ADC, these are added to the nsconfig file.
Note: Names are case sensitive.
T he ADC uses these user credentials to authenticate the clients, and then authenticate the server connections with the
database servers.
Navigate to System > User Administration > Database Users, and configure a database user.
If you have changed the password of the database user on the database server, you must reset the password of the
corresponding user configured on the NetScaler.
To reset the password of a database user by using the command line interf ace
Navigate to System > User Administration > Database Users, select a user, and enter new values for the password.
If a database user no longer exists on the database server, you can remove the user from the NetScaler. However, if the
user continues to exist on the database server and you remove the user from the NetScaler, any request from the client
with this user name does not get authenticated, and therefore, does not get routed to the database server.
rm db user <username>
Navigate to System > User Administration > Database Users, select a user, and click Delete.
At the command line, type the following commands to create a database profile and verify the configuration:
Example
> add dbProfile myDBProfile -interpretQuery YES -stickiness YES -kcdAccount mykcdaccnt
Done
> show dbProfile myDBProfile
Name: myDBProfile
Interpret Query: YES
Stickyness: YES
KCD Account: mykcdaccnt
Reference count: 0
Done
>
To create a database profile by using the configuration utility
Navigate to System > Profiles and, on the Database Profiles tab, configure a database profile.
To bind a database profile to a load balancing or content switching virtual server by using the command line
interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers or T raffic Management > Content Switching >
Virtual Servers, and open a virtual server.
2. In Advanced Settings, select Profiles and, in the DB Profile list, select a profile to bind to the virtual server. T o create a
new profile, click plus (+).
Protocol
Use the MYSQL protocol type for MySQL databases and MSSQL protocol type for MS SQL databases while configuring
virtual servers and services. T he MySQL and T DS protocols are used by the clients to communicate with the respective
database servers by using SQL queries. For information about the MySQL protocol, see
http://dev.mysql.com/doc/internals/en/client-server-protocol.html. For information about the T DS protocol, see
http://msdn.microsoft.com/en-us/library/dd304523(v=prot.13).aspx.
Port
Port on which the virtual server listens for client connections. Use port 3306 for MySQL database servers.
Method
It is recommended that you use the Least Connection method for better load balancing and lower server load. However,
other methods, such as Round Robin, Least Response T ime, Source IP Hash, Source IP Destination IP Hash, Least
Bandwidth, Least Packets, and Source IP Source Port Hash, are also supported.
Note: URL Hash method is not supported for DataStream.
MS SQL Server Version
If you are using the Microsoft SQL Server, and you expect some clients to not be running the same version as your
Microsoft SQL Server product, set the Server Version parameter for the load balancing virtual server. T he version setting
provides compatibility between the client-side and server-side connections by ensuring that all communication conforms to
the server's version. For more information about setting the Server Version parameter, see Configuring the MySQL and
Microsoft SQL Server Version Setting.
MySQL Server Version
If you are using the MySQL Server, and you expect some clients to not be running the same version as your MySQL Server
product, set the Server Version parameter for the load balancing virtual server. T he version setting provides compatibility
between the client-side and server-side connections by ensuring that all communication conforms to the server's version.
For more information about setting the Server Version parameter, see Configuring the MySQL and Microsoft SQL Server
Version Setting.
You can configure content switching policies with default syntax expressions to switch content based on connection
properties, such as user name and database name, command parameters, and the SQL query to select the server.
T he default syntax expressions evaluate traffic associated with MYSQL and MS SQL database servers. You can use
request-based expressions in default syntax policies to make request switching decisions at the content switching virtual
server bind point and response-based expressions (expressions that begin with MYSQL.RES) to evaluate server responses to
user-configured health monitors.
Note: For information about default syntax expressions, see Default Syntax Expressions: DataStream.
Protocol
Use the MYSQL protocol type for MySQL databases and MSSQL protocol type for MS SQL databases while configuring
virtual servers and services. T he MySQL and T DS protocols are used by the clients to communicate with the respective
database servers by using SQL queries. For information about the MySQL protocol, see
http://dev.mysql.com/doc/internals/en/client-server-protocol.html. For information about the T DS protocol, see
http://msdn.microsoft.com/en-us/library/dd304523(v=prot.13).aspx.
Port
Port on which the virtual server listens for client connections. Use port 3306 for MySQL database servers.
MS SQL Server Version
If you are using Microsoft SQL Server, and you expect some clients to not be running the same version as your Microsoft
SQL Server product, set the Server Version parameter for the content switching virtual server. T he version setting provides
compatibility between the client-side and server-side connections by ensuring that all communication conforms to the
server's version. For more information about setting the Server Version parameter, see Configuring the Microsoft SQL
Server Version Setting.
For DataStream, you need to use the built-in monitors, MYSQL-ECV and MSSQL-ECV. T his monitor provides the ability to
send an SQL request and parse the response for a string.
Before configuring monitors for DataStream, you must add database user credentials to your NetScaler. For information
about configuring monitors, see Monitors.
When you create a monitor, a TCP connection is established with the database server, and the connection is authenticated
by using the user name provided while creating the monitor. You can then run an SQL query to the database server and
evaluate the server response to check whether it matches the configured rule.
Examples
In the following example, the value of the error message is evaluated to determine the state of the server.
Examples
In the following example, the value of the error message is evaluated to determine the state of the server.
T he following figure shows the entities and the values of the parameters you need to configure on the appliance.
In this example scenario, a service (Svc_mysql_1) is created to represent the master database and is bound to a load balancing
virtual server (Lb_vsr_mysql_master). T hree more services (Svc_mysql_2, Svc_mysql_3, and Svc_mysql_4) are created to represent
the three slave databases, and they are bound to another load balancing virtual server (Lb_vsr_mysql_slave).
A content switching virtual server (Cs_vsr_mysql_1) is configured with associated policies to send all WRIT E requests to the load
balancing virtual server, Lb_vsr_mysql_master, and all READ requests to the load balancing virtual server, Lb_vsr_mysql_slave.
When a request reaches the content switching virtual server, the virtual server applies the associated content switching policies to
that request. After evaluating the policies, the content switching virtual server routes the request to the appropriate load balancing
virtual server, which sends it to the appropriate service.
T he following table lists the names and values of the entities and the policy configured on the NetScaler.
To configure DataStream f or a master/slave database setup by using the command line interf ace
You can use the following sample SQL expressions to define tokens:
MySQL MS SQL
MYSQL.REQ.QUERY.COMMAND MSSQL.REQ.QUERY.COMMAND
T he following example shows how the NetScaler DataStream feature works when you configure the token method of
load balancing.
Figure 1. How DataStream Works with the T oken Method of Load Balancing
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, configure a virtual server and specify the protocol as
MYSQL.
2. Click in the Service section, and configure two services specifying the protocol as MYSQL. Bind these services to the
virtual server.
3. In Advanced Settings, click Method and, in the Load Balancing Method list, select T OKEN and specify the expression as
MYSQL.CLIENT .DAT ABASE.
When operating in transparent mode, the NetScaler appliance does not perform load balancing, content switching, or
connection multiplexing for the requests. However, it responds to a client's pre-login packet on behalf of the server so that
it can prevent encryption from being agreed upon during the pre-login handshake. T he login packet and subsequent
packets are forwarded to the server.
For logging or analyzing MSSQL requests in transparent mode, you have to do the following:
Configure the NetScaler appliance as the default gateway for both clients and servers.
Do one of the following on the NetScaler appliance:
If you can conf igure the use source IP address (USIP) option globally, create a load balancing virtual server with
a wildcard IP address and the port number on which the MSSQL servers listen for requests (a port-specific wildcard
virtual server). T hen, enable the USIP option globally. If you configure a port-specific wildcard virtual server, you do not
have to create MSSQL services on the appliance. T he appliance discovers the services on the basis of the destination
IP address in the client requests. For instructions, see Configuring T ransparent Mode by Using a Wildcard Virtual Server.
If you do not want to conf igure the USIP option globally, create MSSQL services with the USIP option enabled
on each of them. If you configure services, you do not have to create a port-specific wildcard virtual server. For
instructions, see Configuring T ransparent Mode by Using MSSQL Services.
Configure audit logging, AppFlow, or Action Analytics to log or collect statistics about the requests. If you configure a
virtual server, you can bind your policies either to the virtual server or to the global bind point. If you do not configure a
virtual server, you can bind your policies to only the global bind point.
You can configure transparent mode by configuring a port-specific wildcard virtual server and enabling Use Source IP (USIP)
mode globally. When a client sends its default gateway (the NetScaler appliance) a request with the IP address of an
MSSQL server in the destination IP address header, the appliance checks whether the destination IP address is available. If
the IP address is available, the virtual server forwards the request to the server. Otherwise, it drops the request.
Example
Done
>
To create a wildcard virtual server by using the NetScaler configuration utility
Navigate to Traffic Management > Load Balancing > Virtual Servers, and create a virtual server. Specify MSSQL as the
protocol and * as the IP address.
To enable Use Source IP (USIP) mode globally by using the command line
At the command prompt, type the following commands to enable USIP mode globally and verify the configuration:
Example
You can configure transparent mode by configuring MSSQL services and enabling USIP on each service. When a client sends
its default gateway (the NetScaler appliance) a request with the IP address of an MSSQL server in the destination IP
address header, the appliance forwards the request to the destination server.
add service <name> (<IP> | <serverName>) <serviceT ype> <port> -usip YES
show service <name>
Example
As an example, consider that database servers server1, server2, and server3 host databases mydatabase1 and mydatabase2.
If mydatabase1 becomes unavailable on server2, the load balancing device must be aware of that change in state, and it
must load balance requests for mydatabase1 across only server1 and server3. After mydatabase1 becomes available on
server2, the load balancing device must include server2 in load balancing decisions. Similarly, if mydatabase2 becomes
unavailable on server3, the device must load balance requests for mydatabase2 across only server1 and server2, and it must
include server3 in its load balancing decisions only when mydatabase2 becomes available. T his load balancing behavior must
be consistent across all the databases that are hosted on the server farm.
T he Citrix NetScaler appliance implements this behavior by retrieving a list of all the databases that are active on a service.
To retrieve the list of active databases, the appliance uses a monitor that is configured with an appropriate SQL query. If
the requested database is unavailable on a service, the appliance excludes the service from load balancing decisions until it
becomes available. T his behavior ensures uninterrupted service to clients.
Note: Database specific load balancing is currently supported for only MSSQL and MySQL service types. T his support is also
available for Microsoft SQL Server 2012 high availability deployment.
To set up database specific load balancing, you must enable the load balancing feature, configure a load balancing virtual
server of type MSSQL or MySQL, configure the services that host the database, and bind the services to the virtual server.
T he monitor needs valid user credentials to log on to the database server, so you must configure a database user account
on each of the servers and then add the user account to the NetScaler appliance. T hen, you configure an MSSQL-ECV or
MYSQL-ECV monitor and bind the monitor to each service. Finally, you must test the configuration to ensure that it is
working as intended. Before you perform these configuration tasks, make sure you understand how database specific load
balancing works.
For database specific load balancing, you configure a monitor that periodically queries each database server for the names
of all the active databases on it. T he Citrix NetScaler appliance stores the results, and regularly updates the records on the
basis of the information retrieved through monitoring. When a client queries a particular database, the appliance uses the
configured load balancing method to select a service, and then checks its records to determine whether the database is
You can configure load balancing entities such as services and virtual servers when the load balancing feature is disabled, but
they will not function until you enable the feature.
enable ns feature LB
show ns feature
Example
To configure a virtual server to load balance databases on the basis of availability, you enable the database specific load
balancing parameter on the virtual server. Enabling the parameter modifies the load balancing logic so that the NetScaler
appliance refers the results of the monitoring probe sent to the selected service, before forwarding the query to that
service.
Note
For configuration examples related to MSSQL or MySQL, refer to the following topics:
At the command prompt, type the following command to configure a load balancing virtual server for database specific load balancing and
verify the configuration:
Configuring Services
After you enable the load balancing feature, you must create at least one service for each application server that is to be
included in your load balancing setup. T he services that you configure provide the connections between the NetScaler
appliance and the load balanced servers. Each service has a name and specifies an IP address, a port, and the type of data
that is served.
If you create a service without first creating a server object, the IP address of the service is also the name of the server
that hosts the service. If you prefer to identify servers by name rather than IP address, you can create server objects and
then specify a server's name instead of its IP address when you create a service.
In databases, a connection is always stateful, which means that as soon as a connection is established, it must be
authenticated.
You need to configure your database user name and password on the NetScaler ADC. For example, if you have a user John
configured on the database, you need to configure the user John on the ADC too. When you add the database user names
and passwords on the ADC, these are added to the nsconfig file.
Note: Names are case sensitive.
T he ADC uses these user credentials to authenticate the clients, and then authenticate the server connections with the
database servers.
If you have changed the password of the database user on the database server, you must reset the password of the
corresponding user configured on the NetScaler.
To reset the password of a database user by using the command line interface
At the command prompt, type
If a database user no longer exists on the database server, you can remove the user from the NetScaler. However, if the
user continues to exist on the database server and you remove the user from the NetScaler, any request from the client
with this user name does not get authenticated, and therefore, does not get routed to the database server.
rm db user <username>
Example
To retrieve a list of all the active databases on a database instance, you create a monitor that logs on to the database server by using a
valid user credentials and runs an appropriate SQL query. The SQL query you need to use depends on your SQL server deployment. For
example, in an MSSQL database mirroring setup, you can use the following query to retrieve a list of active databases available on a server
instance.
show databases
You also configure the monitor to evaluate the response for an error condition, and to store the results if there is no error. If the response
contains an error, the monitor marks the service as DOWN, and the appliance excludes the service from load balancing decisions until an
error is no longer returned.
Note: The database specific load balancing feature is supported only for the MSSQL and MySQL service types. Therefore, the monitor type
must be MSSQL-ECV or MYSQL-ECV.
To configure a monitor to retrieve the names of all the active databases hosted on
a service by using the command line
At the command prompt, type the following commands to retrieve the names of all the active databases hosted on a service and verify the
configuration:
add lb monitor <monitorName> <type> -userName <string> -sqlQuery <text> -evalRule <expression> -storedb ENABLED
show lb monitor <monitorName>
1. Navigate to Traffic Management > Load Balancing > Monitors and configure a monitor of type MSSQL-ECV or MYSQL-ECV.
2. In Special Parameters, specify a user name, query, and a rule
For example, for MSSQL-ECV, the query should be "select name from sys.databases where state=0"), and a rule should be
MSSQL.RES.TYPE.NE(ERROR).
For MSSQL-ECV, the query should be "show databases" and a rule should be MYSQL.RES.TYPE.NE(ERROR).
Consider the following scenario in which database specific load balancing is configured in a high availability group
deployment. S1 through S5 are the services on the NetScaler. DB1 through DB4 are the databases on the servers
represented by the services S1 through S5. AV1 and AV2 are the availability groups. Each availability group contains up to
one primary database server instance and up to four secondary database server instances. A service, representing the
servers in the availability group, can be primary for one availability group and secondary for another availability group. Each
availability group contains different databases and one listener, which is a service. All requests arrive on the listener service
that resides on the primary database. AVI contains databases DB1 and DB2. AV2 contains databases DB3 and DB4. L1 and
L2 are the listeners on AV1 and AV2 respectively. S1 is the primary service for AV1 and S2 is the primary service for AV2.
S2 DB3, DB4
S3 DB3, DB4
S4 DB1, DB2
Sample Configuration
1. Configure load balancing and content switching virtual servers.
add lb vserver lbwrite -dbslb enabled
add lbvserver lbread MSSQL -dbslb enabled
add csvserver csv MSSQL 1.1.1.10 1433
2. Configure two listener services, one for each availability group, and five services S1 through S5 representing databases
DB1 through DB4.
add service L1 1.1.1.11 MSSQL 1433
add service L2 1.1.1.12 MSSQL 1433
add service s1 1.1.1.13 MSSQL 1433
add service s2 1.1.1.14 MSSQL 1433
add service s3 1.1.1.15 MSSQL 1433
add service s4 1.1.1.16 MSSQL 1433
add service s5 1.1.1.17 MSSQL 1433
3. Bind the services to the load balancing virtual servers.
bind lbvserver lbwrite L1
bind lbvserver lbwrite L2
bind lbvserver lbread s1
bind lbvserver lbread s2
bind lbvserver lbread s3
bind lbvserver lbread s4
bind lbvserver lbread s5
4. Configure database users.
add db user nsdbuser1 -password dd260427edf
add db user nsdbuser2 -password ccd1234xyzw
5. Configure two monitors, monitor_L1 and monitor_L2 for each listener service, to retrieve the list of active databases in
that availability group. Add a monitor, monitor1 to retrieve the list of databases for the secondary database server
instance.
add lb monitor monitor_L1 MSSQL-ECV -userName user1 -sqlQuery "SELECT name FROM sys.databases a INNER JOIN
sys.dm_hadr_availability_replica_states b ON a.replica_id=b.replica_id INNER JOIN sys.availability_group_listeners c on
b.group_id = c.group_id INNER JOIN sys.availability_group_listener_ip_addresses d on c.listener_id = d.listener_id
Done
> show lb vserver DBSpecificLB1
DBSpecificLB1 (192.0.2.10:1433) - MSSQL Type: ADDRESS
...
DBS_LB: ENABLED
Done
>
To configure services
To configure a monitor to retrieve the names of all the active databases hosted on a service by using the
command line
> add lb monitor mssql-monitor1 MSSQL-ECV -userName user1 -sqlQuery "select name from sys.databases where
state=0" -evalRule "MSSQL.RES.T YPE.NE(ERROR)" -storedb EN
Done
...
User name.....:"user1"
Version...:70 STORE_DB...:ENABLED
Done
>
Done
...
DBS_LB: ENABLED
Done
>
To configure services
To configure a monitor to retrieve the names of all the active databases hosted on a service by using the
command line
> add lb monitor mysql-monitor1 MYSQL-ECV -userName user1 -sqlQuery "show databases" -evalRule
"MYSQL.RES.T YPE.NE(ERROR)" -storedb ENABLED
Done
...
Done
>
You can also configure the NetScaler appliance to generate audit log messages for the DataStream feature.
Database MySQL database versions 4.1, 5.0, 5.1, 5.4, 5.5, and MS SQL database versions 2000, 2000SP1, 2005, 2008, 2008R2, and
Versions 5.6. 2012.
Character Sets
T he character set used by the client while sending a request may be different from the character set used in the database
server responses. Although the charset parameter is set during the connection establishment, it can be changed at any time
by sending an SQL query. T he character set is associated with a connection, and therefore, requests on connections with
one character set cannot be multiplexed onto a connection with a different character set.
NetScaler parses the queries sent by the client and the responses sent by the database server.
T he character set associated with a connection can be changed after the initial handshake by using the following two
queries:
Transactions
In MySQL, transactions are identified by using the connection parameter AUTOCOMMIT or the BEGIN:COMMIT queries.
T he AUTOCOMMIT parameter can be set during the initial handshake, or after the connection is established by using the
query SET AUTOCOMMIT .
NetScaler explicitly parses each and every query to determine the beginning and end of a transaction.
If the connection is a transaction, the T RANSACT ION flag is set. Or, if the AutoCommit mode is OFF, the AUTOCOMMIT
flag is not set. NetScaler parses the response, and if either the T RANSACT ION flag is set or the AUTOCOMMIT flag is not
set, it does not do connection multiplexing. When these conditions are no longer true, the NetScaler begins connection
multiplexing.
Note
Transactions are also supported for MS SQL.
Special Queries
T here are special queries, such as SET and PREPARE, that modify the state of the connection and may break request
switching, and therefore, these need to be handled differently.
On receiving a request with special queries, NetScaler sends an OK response to the client and additionally, stores the
request in the connection.
When a non-special query, such as INSERT and SELECT, is received along with a stored query, the NetScaler first, looks for
the server-side connection on which the stored query has already been sent to the database server. If no such connections
exist, NetScaler creates a new connection, and sends the stored query first, and then, sends the request with the non-
special query.
In case of SET, USE db, and INIT _DB special queries, the appliance modifies a field in the server side connection
corresponding to the special query. T his results in better reuse of the server side connection.
T he following is a list of the special queries for which NetScaler has a modified behavior.
SET query
T he SET SQL queries define variables that are associated with the connection. T hese queries are also used to define global
variables, but as of now, NetScaler is unable to differentiate between local and global variables. For this query, the
NetScaler uses the 'store and forward' mechanism.
USE <db> query
Using this query, the user can change the database associated with a connection. In this case, NetScaler parses the <db>
value sent and modifies a field in the server side connection to reflect the new database to be used.
INIT_DB command
Using this query, the user can change the database associated with a connection. In this case, NetScaler parses the
<init_db> value sent and modifies a field in the server side connection to reflect the new database to be used.
COM_PREPARE
NetScaler stops request switching on receiving this command.
PREPARE query
T his query is used to create prepared statements that are associated with a connection. For this query, the NetScaler uses
the 'store and forward' mechanism.
You can now configure the NetScaler appliance to generate audit log messages for the DataStream feature. Audit log
messages are generated when client-side and server-side connections are established, closed, or dropped. T he categories of
messages that you can log and view are ERROR and INFO. Error messages for client-side connections begin with "CS" and
error messages for server-side connections begin with "SS." Additional information is provided where necessary. For
example, log messages for closed connections (CS_CONN_CLOSED) include only the connection ID. However, log messages
for established connections (CS_CONN_EST D) include information such as the user name, database name, and the client IP
address in addition to the connection ID.
You can configure the NetScaler appliance to concurrently function as an authoritative DNS server for one domain and a DNS proxy server for
another domain. When you configure the NetScaler as the authoritative DNS server or DNS proxy server for a zone, you can enable the
appliance to use the Transmission Control Protocol (TCP) for response sizes that exceed the size limit specified for the User Datagram Protocol
(UDP).
You can configure the NetScaler appliance to function as an ADNS server, DNS proxy server, end resolver, and forwarder. You can add DNS
resource records on the NetScaler, including service (SRV) records, IPv6 (AAAA) records, address (A) records, mail exchange (MX) records, canonical
name (CNAME) records, pointer (PT R) records, start of authority (SOA) records, and text (T XT ) records. Also, you can configure the NetScaler to
load balance external DNS name servers.
T he NetScaler can be configured as the authority for a domain. To do this, you add valid SOA and NS records for the domain.
An ADNS server is a DNS server that contains complete information about a zone.
To configure the NetScaler as an ADNS server for a zone, you must add an ADNS service, and then configure the zone. To do so, you add valid
SOA and NS records for the domain. When a client sends a DNS request, the NetScaler appliance searches the configured resource records for
the domain name. You can configure the ADNS service to be used with the NetScaler Global Server Load Balancing (GSLB) feature.
You can delegate a subdomain, by adding NS records for the subdomain to the zone of the parent domain. You can then make the NetScaler
authoritative for the subdomain, by adding a "glue record" for each of the subdomain name servers. If GSLB is configured, the NetScaler makes a
GSLB load balancing decision based on its configuration and replies with the IP address of the selected virtual server. T he following figure shows
the entities in an ADNS GSLB setup and a DNS proxy setup.
T he NetScaler appliance can function as a DNS proxy. Caching of DNS records, which is an important function of a DNS proxy, is enabled by
T he NetScaler provides two options, minimum time to live (T T L) and maximum T T L for configuring the lifetime of the cached data. T he cached
data times out as specified by your settings for these two options. T he NetScaler checks the T T L of the DNS record coming from the server. If
the T T L is less than the configured minimum T T L, it is replaced with the configured minimum T T L. If the T T L is greater than the configured
maximum T T L, it is replaced with the configured maximum T T L.
T he NetScaler also allows caching of negative responses for a domain. A negative response indicates that information about a requested
domain does not exist, or that the server cannot provide an answer for the query. T he storage of this information is called negative caching.
Negative caching helps speed up responses to queries on a domain, and can optionally provide the record type.
T he NetScaler supports recursive resolution of DNS requests. In recursive resolution, the resolver (DNS client) sends a recursive query to a name
server for a domain name. If the queried name server is authoritative for the domain, it responds with the requested domain name. Otherwise,
the NetScaler queries the name servers recursively until the requested domain name is found.
Before you can apply the recursive query option, you must first enable it. You can also set the number of times the DNS resolver must send a
resolution request (DNS retries) if a DNS lookup fails.
You can configure the NetScaler as a DNS forwarder. A forwarder passes DNS requests to external name servers. T he NetScaler allows you to
add external name servers and provides name resolution for domains outside the network. T he NetScaler also allows you to set the name lookup
priority to DNS or Windows Internet Name Service (WINS).
When a client sends a DNS request to find the DNS resource record, it receives a list of IP addresses resolving to the name in the DNS request.
T he client then uses one of the IP addresses in the list, generally, the first record or IP address. Hence, a single server is used for the total T T L of
the cache and is overloaded when a large number of requests arrive.
When the NetScaler receives a DNS request, it responds by changing the order of the list of DNS resource records in a round robin method. T his
feature is called round robin DNS . Round robin distributes the traffic equally between data centers. T he NetScaler performs this function
automatically. You do not have to configure this behavior.
Functional Overview
If the NetScaler is configured as an ADNS server, it returns the DNS records in the order in which the records are configured. If the NetScaler is
configured as a DNS proxy, it returns the DNS records in the order in which it receives the records from the server. T he order of the records
present in the cache matches the order in which records are received from the server.
T he NetScaler then changes the order in which records are sent in the DNS response in a round robin method. T he first response contains the
first record in sequence, the second response contains the second record in sequence, the third response contains the third record in sequence,
and the order continues in the same sequence. T hus, clients requesting the same name can connect to different IP addresses.
As an example of round robin DNS, consider DNS records that have been added as follows:
add dns addRec ns1 1.1.1.1 add dns addRec ns1 1.1.1.2 add dns addRec ns1 1.1.1.3 add dns addRec ns1 1.1.1.4
T he domain, abc.com is linked to an NS record as follows:
T he following table lists the record types that you can configure for a domain name record on the NetScaler. For example,
you can configure a maximum of 25 IP addresses for one record.
Address (A) 25
IPv6 (AAAA) 5
Service (SRV) 8
Pointer (PT R) 20
Text (T XT ) 20
Note
T he maximum number of IP addresses for a specific hostname is 25. However, the number of different address records can be
more than 25.
At the command prompt, type the following commands to add an SRV record and verify the configuration:
add dns srvRec <domain> <target> -priority <positive_integer> -weight <positive_integer> -port <positive_integer> [-T T L
<secs>]
sh dns srvRec <domain>
Example
T o modify an SRV record, type the set dns srvRec command, the name of the domain for which the SRV record is
configured, the name of the target host that hosts the associated service, and the parameters to be changed, with their
new values.
T o remove an SRV record, type the rm dns srvRec command, the name of the domain for which the SRV record is
configured, and the name of the target host that hosts the associated service.
Navigate to Traffic Management > DNS > Records > SRV Records and create an SRV record.
At the command prompt, type the following commands to add an AAAA record and verify the configuration:
Example
Navigate to Traffic Management > DNS > Records > AAAA Records and create an AAAA record.
You cannot delete Address records for a host participating in global server load balancing (GSLB). However, the NetScaler
deletes Address records added for GSLB domains when you unbind the domain from a GSLB virtual server. Only user-
configured records can be deleted manually. You cannot delete a record for a host referenced by records such as NS, MX, or
CNAME.
At the command prompt, type the following commands to add an Address record and verify the configuration:
Example
Navigate to Traffic Management > DNS > Records > Address Records and create an Address record.
When an email message is sent through the Internet, a mail transfer agent sends a DNS query requesting the MX record for
the domain name. T his query returns a list of host names of mail exchange servers for the domain, along with a preference
number. If there are no MX records, the request is made for the Address record of that domain. A single domain can have
multiple mail exchange servers.
At the command prompt, type the following commands to add an MX record and verify the configuration:
add dns mxRec <domain> -mx <string> -pref <positive_integer> [-T T L <secs>]
show dns mxRec <domain>
Example
T o modify an MX record, type the set dns mxRec command, the name of the domain for which the MX record is
configured, the name of the MX record, and the parameters to be changed, with their new values.
T o set the T T L parameter to its default value, type the unset dns mxRec command, the name of the domain for which
the MX record is configured, the name of the MX record, and -TTL without any T T L value. You can use the unset dns
mxRec command to unset only the T T L parameter.
T o remove an MX record, type the rm dns mxRec command, the name of the domain for which the MX record is
configured, and the name of the MX record.
Navigate to Traffic Management > DNS > Records > Mail Exchange Records and create an MX record.
At the command prompt, type the following commands to create an NS record and verify the configuration:
Example
Navigate to Traffic Management > DNS > Records > Name Server Records and create an NS record.
In some cases, a NetScaler appliance in proxy mode requests an address record from the cache instead of the server.
At the command prompt, type the following commands to create a CNAME record and verify the configuration:
Example
Navigate to Traffic Management > DNS > Records > Canonical Records and create a CNAME record.
Updated: 2015-05-26
NetScaler ADC when deployed in a proxy mode does not always send the query for an address record to the back-end
server. T his happens when for a answer to a query for an address record, a partial CNAME chain is present in the cache.
T here are few conditions in which the ADC caches the partial CNAME record and serves the query from the cache.
Following are the conditions:
NetScaler should be deployed in a proxy mode
T he response from the back-end server should have a CNAME chain, for which the record type of last entry in the
answer section must be a CNAME and the question type not a CNAME
T he response from the back-end server cannot be a No-data or NX-Domain
T he response from the back-end server has to be a authoritative response
NetScaler ADCs support NAPT R in two modes: ADNS mode and proxy mode. In proxy mode, the ADC caches the response
from the servers and uses the cached records to server future queries. A maximum of 20 NAPT R records can be added for a
particular domain in NetScaler. NetScaler caches the reply to a DNS NAPT R record query. Any subsequent requests for the
NAPT R record is served from the cache.
At the command prompt, type the following commands to add a NAPT R record and verify the configuration:
rm dns naptrRec<domain> (<order> <preference> [-flags <string>] [-services <string>] (-regexp <expression> | -replacement
<string>) ) | -recordId <positive_integer>@)
To configure a NAPTR record using configuration utility
Navigate to Traffic Management > DNS > Records > NAPT R Records and create an NAPT R record.
IPv6 addresses are reverse mapped under the domain IP6.ARPA. IPv6 reverse-maps use a sequence of nibbles separated by
dots with the suffix ".IP6.ARPA" as defined in RFC 3596. For example, the reverse lookup domain name corresponding to the
address, 4321:0:1:2:3:4:567:89ab would be b.a.9.8.7.6.5.0.4.0.0.0.3.0.0.0.2.0.0.0.1.0.0.0.0.0.0.0.1.2.3.4.IP6.ARPA.
At the command prompt, type the following commands to add a PT R record and verify the configuration:
Example
Navigate to Traffic Management > DNS > Records > PT R Records and create a PT R record.
At the command prompt, type the following commands to add an SOA record and verify the configuration:
Example
T o modify an SOA record, type the set dns soaRec command, the name of the domain for which the record is
configured, and the parameters to be changed, with their new values.
T o remove an SOA record, type the rm dns soaRec command and the name of the domain for which the record is
configured.
Navigate to Traffic Management > DNS > Records > SOA Records and create an SOA record.
All configuration types (authoritative DNS, DNS proxy, end resolver, and forwarder configurations) on the NetScaler
appliance support T XT records. You can add a maximum of 20 T XT resource records to a domain. Each resource record is
stored with a unique, internally generated record ID. You can view the ID of a record and use it to delete the record.
However, you cannot modify a T XT resource record.
To create a TXT resource record by using the command line interf ace
At the command prompt, type the following commands to create a T XT resource record and verify the configuration:
Example
> add dns txtRec www.example.com "Contact: Mark" "Email: mark@example.com" -TTL 36000
Done
> show dns txtRec www.example.com
1) Domain : www.example.com Record id: 13783 TTL : 36000 secs Record Type : ADNS
"Contact: Mark"
"Email: mark@example.com"
Done
To remove a TXT resource record by using the command line interf ace
At the command prompt, type the following commands to remove a T XT resource record and verify the configuration:
Example
You can use the show dns txtRec command first to view the record ID of the T XT resource record that you want to
remove, as shown:
Navigate to Traffic Management > DNS > Records > T XT Records and create a T XT record.
To view DNS records statistics by using the command line interf ace
stat dns
Example
Runtime Statistics
Dns queries 21
NS queries 8
SOA queries 18
.
.
.
Configuration Statistics
AAAA records 17
A records 36
MX records 9
.
.
.
Error Statistics
Nonexistent domain 17
No AAAA records 0
No A records 13
.
.
.
Done
>
To view DNS records statistics by using the configuration utility
You must create a DNS zone on the appliance in the following scenarios:
T he NetScaler appliance owns all the records in a zone, that is, the appliance is operating as the authoritative DNS server
for the zone. T he zone must be created with the proxyMode parameter set to NO.
T he NetScaler appliance owns only a subset of the records in a zone, and all the other resource records in the zone are
hosted on a set of back-end name servers for which the appliance is configured as a DNS proxy server. A typical
configuration where the NetScaler appliance owns only a subset of the resource records in the zone is a global server
load balancing (GSLB) configuration. Only the GSLB domain names are owned by the NetScaler appliance, while all the
other records are owned by the back-end name servers. T he zone must be created with the proxyMode parameter set
to YES.
You want to offload DNSSEC operations for a zone from your authoritative DNS servers to the appliance. T he zone
must be created with the proxyMode parameter set to YES. You might need to configure additional settings for the
zone.
T he current topic describes how to create a zone for the first two scenarios. For more information about how to configure
a zone for offloading DNSSEC operations to the appliance, see Offloading DNSSEC Operations to the NetScaler
Appliance.
Note: If the NetScaler is operating as the authoritative DNS server for a zone, you must create Start of Authority (SOA)
and name server (NS) records for the zone before you create the zone. If the NetScaler is operating as the DNS proxy
server for a zone, SOA and NS records must not be created on the NetScaler appliance. For more information about
creating SOA and NS records, see Configuring DNS Resource Records.
When you create a zone, all existing domain names and resource records that end with the name of the zone are
automatically treated as a part of the zone. Additionally, any new resource records created with a suffix that matches the
name of the zone are implicitly included in the zone.
To create a DNS zone on the NetScaler appliance by using the command line interf ace
At the command prompt, type the following command to add a DNS zone to the NetScaler appliance and verify the
configuration:
Example
T o modify a DNS zone, type the set dns zone command, the name of the DNS zone, and the parameters to be changed,
with their new values.
T o remove a DNS zone, type the rm dns zone command and the name of the dns zone.
Navigate to Traffic Management > DNS > Zones and create a DNS zone.
T he following table shows the parameters that are configured for the ADNS service illustrated in the preceding topology
diagram.
To configure an ADNS setup, you must configure the ADNS service. For instructions on configuring the ADNS service, see
"Load Balancing".
During DNS resolution, the ADNS server directs the DNS proxy or local DNS server to query the NetScaler for the IP address
of the domain. Because the NetScaler is authoritative for the domain, it sends the IP address to the DNS proxy or local
DNS server. T he following diagram describes the placement and role of the ADNS server in a GSLB configuration.
An ADNS service is used for global service load balancing. For more information about creating a GSLB setup, see "Global
Server Load Balancing". You can add, modify, enable, disable, and remove an ADNS service. For instructions on creating an
ADNS service, see Configuring Services.
Note: You can configure the ADNS service to use SNIP or any new IP address.
When you create an ADNS service, the NetScaler responds to DNS queries on the configured ADNS service IP and port.
You can verify the configuration by viewing the properties of the ADNS service You can view properties such as name, state,
IP address, port, protocol, and maximum client connections.
By default, some clients use the User Datagram Protocol (UDP) for DNS, which specifies a limit of 512 bytes for the payload
length of UDP packets. To handle payloads that exceed 512 bytes in size, the client must use the Transmission Control
Protocol (TCP). To enable DNS communications over TCP, you must configure the NetScaler appliance to use the TCP
protocol for DNS. T he NetScaler then sets the truncation bit in the DNS response packets. T he truncation bit specifies
that the response is too large for UDP and that the client must send the request over a TCP connection. T he client then
uses the TCP protocol on port 53 and opens a new connection to the NetScaler. T he NetScaler listens on port 53 with the
IP address of the ADNS service to accept the new TCP connections from the client.
T o configure the NetScaler to use the T CP protocol, you must configure an ADNS_T CP service. For instructions on creating
After you create an ADNS service, you can add DNS records. For instructions on adding DNS records, see Configuring DNS
Resource Records.
Domain delegation is the process of assigning responsibility for a part of the domain space to another name server.
T herefore, during domain delegation, the responsibility for responding to the query is delegated to another DNS server.
Delegation uses NS records.
In the following example, sub1.abc.com is the subdomain for abc.com. T he procedure describes the steps to delegate the
subdomain to the name server ns2.sub1.abc.com and add an Address record for ns2.sub1.abc.com.
T o configure domain delegation, you need to perform the following tasks, which are described in the sections that follow:
1. Create an SOA record for a domain.
2. Create an NS record to add a name server for the domain.
3. Create an Address record for the name server.
4. Create an NS record to delegate the subdomain.
5. Create a glue record for the name server.
For instructions on adding glue records for a subdomain, see the procedure for adding an Address (A) record, Configuring
DNS Resource Records.
For instructions on configuring Address records, see Creating Address Records for a Domain Name. In Host Name and IP
address text boxes, type the domain name for the DNS Address record and the IP address, for example, ns2.sub1.abc.com
and 10.102.12.135, respectively.
By default, the NetScaler appliance caches responses from DNS name servers. When the appliance receives a DNS query, it
checks for the queried domain in its cache. If the address for the queried domain is present in its cache, the NetScaler
returns the corresponding address to the client. Otherwise, it forwards the query to a DNS name server that checks for the
availability of the address and returns it to the NetScaler. T he NetScaler then returns the address to the client.
For requests for a domain that has been cached earlier, the NetScaler serves the Address record of the domain from the
cache without querying the configured DNS server.
T he NetScaler discards a record stored in its cache when the time-to-live (T T L) value of the record reaches the configured
value. A client that requests an expired record has to wait until the NetScaler retrieves the record from the server and
updates its cache. To avoid this delay, the NetScaler proactively updates the cache by retrieving the record from the server
before the record expires.
T he following table lists sample names and the values of the entities that need to be configured on the NetScaler.
Note: T o configure DNS proxy, you need to know how to configure load balancing services and virtual servers. For
information about configuring load balancing services and virtual servers, see "Load Balancing", and then configure DNS
proxy setup.
T his document includes the following information:
Creating a Load Balancing Virtual Server
Updated: 2014-12-29
To configure a DNS Proxy on the NetScaler ADC, configure a load balancing virtual server of type DNS. To configure a DNS
virtual server to load balance a set of DNS servers that support recursive queries, you must set the Recursion Available
option. With this option, the RA bit is set to ON in the DNS replies from the DNS virtual server.
For instructions on creating a load balancing virtual server, see "Load Balancing".
After creating a load balancing virtual server of type DNS, you must create DNS services. You can add, modify, enable,
disable, and remove a DNS service. For instructions on creating a DNS service, see "Load Balancing".
Updated: 2013-09-13
To complete the DNS Proxy configuration, you must bind the DNS services to the load balancing virtual server. For
instructions on binding a service to a load balancing virtual server, see "Load Balancing".
Updated: 2013-08-26
Some clients use the User Datagram Protocol (UDP) for DNS communications. However, UDP specifies a maximum packet
size of 512 bytes. When payload lengths exceed 512 bytes, the client must use the Transmission Control Protocol (TCP).
When a client sends the Citrix® NetScaler® appliance a DNS query, the appliance forwards the query to one of the name
servers. If the response is too large for a UDP packet, the name server sets the truncation bit in its response to the
NetScaler. T he truncation bit indicates that the response is too large for UDP and that the client must send the query over
a TCP connection. T he NetScaler relays the response to the client with the truncation bit intact and waits for the client to
initiate a TCP connection with the IP address of the DNS load balancing virtual server, on port 53. T he client sends the
request over a TCP connection. T he NetScaler appliance then forwards the request to the name server and relays the
response to the client.
To configure the NetScaler to use the TCP protocol for DNS, you must configure a load balancing virtual server and services,
both of type DNS_TCP. You can configure monitors of type DNS_TCP to check the state of the services. For instructions
on creating DNS_TCP virtual servers, services, and monitors, see "Load Balancing."
For updating the records proactively, the NetScaler uses a TCP connection to the server to retrieve the records.
Important: T o configure the NetScaler to use UDP for DNS and use T CP only when the payload length of UDP exceeds
512 bytes, you need to configure DNS and DNS_T CP services. T he IP address of the DNS_T CP service must be same as
that of the DNS service.
Configuring Time-to-Live Values f or DNS Entries
T he T T L is the same for all DNS records with the same domain name and record type. If the T T L value is changed for one
of the records, the new value is reflected in all records of the same domain name and type. T he default T T L value is 3600
seconds. T he minimum is 0, and the maximum is 604800. If a DNS entry has a T T L value less than the minimum or greater
than the maximum, it is saved as the minimum or maximum T T L value, respectively.
To specify the minimum and/or maximum T T L by using the command line interface
At the NetScaler command prompt, type the following commands to specify the minimum and maximum T T L and verify the
configuration:
Example
Note: When the T T L expires, the record is deleted from the cache. T he NetScaler proactively contacts the servers and
obtains the DNS record just before the DNS record expires.
Flushing DNS Records
You can delete all DNS records present in the cache. For example, you might want to flush DNS records when a server is
restarted after modifications are made.
Updated: 2013-08-26
You can add DNS records to a domain for which the Citrix® NetScaler® appliance is configured as a DNS proxy server. For
information about adding DNS records, see Configuring DNS Resource Records.
Updated: 2013-08-27
For information about removing a load balancing virtual server, see Load Balancing.
Updated: 2013-09-10
T he default value for this parameter is 255. T his default value is sufficient in most scenarios. If the name servers serve a
large number of concurrent DNS requests under normal operating conditions, you can specify either a large value or a value
of zero (0). A value of 0 disables this feature and specifies that there is no limit to the number of DNS requests that are
allowed on a single client connection. T his is a global parameter and applies to all the DNS virtual servers that are configured
on the NetScaler appliance.
Example
In recursive resolution, the NetScaler appliance queries different name servers recursively to access the IP address of a
domain. When the NetScaler receives a DNS request, it checks its cache for the DNS record. If the record is not present in
the cache, it queries the root servers configured in the ns.conf file. T he root name server reports back with the address of a
DNS server that has detailed information about the second-level domain. T he process is repeated until the required record
is found.
When you start the NetScaler appliance for the first time, 13 root name servers are added to the ns.conf file. T he NS and
Address records for the 13 root servers are also added. You can modify the ns.conf file, but the NetScaler does not allow
you to delete all 13 records; at least one name server entry is required for the appliance to perform name resolution. T he
following diagram illustrates the process of name resolution.
In the process shown in the diagram, when the name server receives a query for the address of s1.s2.s3.com, it first checks
the root name servers for s1.s2.s3.com. A root name server reports back with the address of the .com name server. If the
address of s1.s2.s3.com is found in the name server, it responds with a suitable IP address. Otherwise, it queries other name
servers for s3.com, then for s2.s3.com to retrieve the address of s1.s2.s3.com. In this way, resolution always starts from root
name servers and ends with the domain’s authoritative name server.
Updated: 2013-08-27
To configure the NetScaler appliance to function as an end resolver, you must enable recursive resolution on the appliance.
Example
Updated: 2013-08-27
T he NetScaler appliance can be configured to make a preconfigured number of attempts (called DNS retries) when it does
not receive a response from the server to which it sends a query. By default, the number of DNS retries is set to 5.
To set the number of DNS retries by using the command line interface
At the command prompt, type the following commands to set the number of retries and verify the configuration:
Example
T he NetScaler appliance allows you to add external name servers to which it can forward the name resolution queries that
cannot be resolved locally. To configure the NetScaler appliance as a forwarder, you must add the name servers to which it
should forward name resolution queries. You can specify the lookup priority to specify the name service that the NetScaler
appliance must use for name resolution.
While adding name servers, you can provide an IP address or a virtual IP address (VIP). If you add an IP address, the
NetScaler load balances requests to the configured name servers in round robin method. If you add a VIP, you can configure
any load balancing method.
Note: To verify the configuration, you can also use the sh dns <recordtype> <domain> command. If the queried records are
not present in the cache, the resource records are fetched from the configured external name servers.
To add a name server (when the NetScaler appliance acts as a forwarder) by using
the command line interface
At the command prompt, type;
Example:
To add a name server (when the NetScaler appliance acts as a resolver) by using the
command line interface
At the command prompt, type:
Example
Note
T o remove a name server, at the NetScaler command prompt, type the rm dns nameServer command followed by the IP
address of the name server.
T o view the details of the DNS nameserver, at the NetScaler command prompt, type show dns nameServer command
followed by the IP address of the name server.
Note
Presently, the NetScaler appliance supports name servers over UDP only and thus the DNS response size is limited to 512 bytes. If
the DNS response size exceeds 512 bytes, the truncated bit is set in the DNS response. T he NetScaler appliance ignores such
messages.
To set the lookup priority to DNS by using the command line interf ace
At the command prompt, type the following commands to set the lookup priority to DNS and verify the configuration:
Example
Note: If the DNS virtual server that you have configured is DOWN and if you set the -nameLookupPriority to DNS, the
NetScaler does not attempt WINS lookup. T herefore, if a DNS virtual server is not configured or is disabled, set the -
nameLookupPriority to WINS.
To enable or disable a name server by using the command line interf ace
At the command prompt, type the following commands to enable or disable a name server and verify the configuration:
Example
A NetScaler appliance can log the following sections in the DNS request or response, on the basis of your configuration:
Header Section
Questions Section
Answer Section
Authority Section
Additional Section
DNS Profiles
You can use a DNS profile to configure various DNS parameters that you want the DNS endpoint to apply to the DNS
traffic. In the profile, you can enable logging, caching and negative caching.
Important: From NetScaler 11.0 release, enabling DNS caching using global DNS parameters has been deprecated. You can
enable or disable DNS caching using DNS profiles. You can now enable DNS caching for an individual virtual server by
enabling DNS caching in a DNS profile and setting the DNS profile to the individual virtual server.
DNS profiles support the following types of DNS logging:
DNS Query Logging
DNS Answer Section Logging
DNS Extended Logging
DNS Error Logging
Note: If errors occur during processing of a query, they are logged if this option is set in the DNS profile.
Note: If errors occur during processing of either queries or responses, the errors are logged if this option is set in the DNS
profile.
Following is an example of a message logged when the cache lookup is completed and the response is embedded in the
packet:
DNS DNS_RESPONSE 2252 0 : T:100.100.100.118#21411:100.100.100.10
#53/48537/Q/(RD,AA,CD,RA,R)/NO/1/1/2/6#a1.citrix.com1./1#ANS#A/
120/1.1.1.1##AUTH#citrix.com1/NS/120/n2.citrix.com1#n1.citrix.com1##ADD#n1.citrix.com1
/A/120/1.1.1.1#1.1.1.2##n1.citrix.com1/AAAA/120/
1111:2345:6789:ffab:abcd:effa:1234:3212##n2.citrix.com1/A/120/2.1.1.2
##n2.citrix.com1/AAAA/120/2222:faff:3212:8976:123:1241:64:ff9b##OPT/0/1280/DO##
Following is an example of a message logged when an error occurs during processing of a DNS request or response:
DNS DNS_ERROR 149 0 : U:10.102.27.70#27832:10.102.27.73#53/61153/Q/
(RD)/NO/1/0/0/0#test.com./1140#Packet Dropped
NetScaler appliance log DNS requests and responses in the following Syslog format:
Field Values
T = T CP
<transport> U = UDP
<client IP>#< client ephemeral port > DNS client IP address and port number
<DNS endpoint IP>#<port> NetScaler DNS endpoint IP address and port number
Q : query
I : inverse query
S: status
<opcode>
X0: unassigned
N : notify
U : update
X1-10: unassigned values
RD : recursion desired
T C : truncated
AA : authoritative response
<header flags> CD : check disabled
AD : authenticated data
Z : unassigned
RA : recursion available
R : response
NO : no error
F format error
S : server failure
NX : non-existent domain
NI : not implemented
R: query refused
<rcode>
YX : Name Exists when it should not
YXR : RR Set Exists when it should not
NXR: RR Set that should exist does not
NAS : Server Not Authoritative for zone
NA : Not Authorized
NZ : Name not contained in zone
X1-5: unassigned
/question section count/answer section count/auth Question section, Authority section count, and Additional
section count/additional section count section count in the DNS request
<queried domain name>/<queried type> Queried domain and queried type in the DNS request
OPT /<edns version>/UDP max payload size/DO OPT record format in the DNS log
When a DNS query with ECS option that includes either IPv4
or IPv6 address is sent, the ECS option is logged with either
"ECS/Q" indicating that the values in the log are from the
query or "ECS/R" indicating that the values in the log are from
the response.
ECS
ECS
option
option
set in
Scenario set in Logged Details
the
the DNS
DNS
Response
Query
Query
logging &
ECS option is not
extended Yes Yes
logged.
logging are
not enabled
Query
ECS option is logged
logging is
with the string
not enabled,
"ECS/R/ " and the
but Yes Yes
Scope Prefix-
extended
Length is set to the
logging is
calculated value.
enabled
Query
logging is
not enabled,
ECS option is not
but Yes No
logged.
extended
logging is
enabled
SOA record SOA/3600/ns1.dnslogging.test./ Origin server, contact, and other details. Resource
root.dnslogging.test./100/3600/3/3600/5## record format is :
< originServer >/<contact>/<serial
number>/<refresh
rate>/<retry>/<expire>/<minimum>##
To conf igure DNS logging f or NetScaler conf igured as DNS Proxy by using the command line interf ace
1. Add a syslog action and enable DNS in the action. At the command prompt, type:
add audit syslogAction <name> (<serverIP> | -lbVserverName <string>) [-serverPort <port>] -logLevel <logLevel> ...
[-dateFormat <dateFormat>] [-logFacility <logFacility>] [-tcp ( NONE | ALL )] [-acl ( ENABLED | DISABLED )] [-timeZone
( GMT_TIME | LOCAL_TIME )] [-userDefinedAuditlog ( YES | NO )] [-appflowExport ( ENABLED |DISABLED )] [-lsn (
Example:
add audit syslogAction nssyslogact1 10.102.151.136 -logLevel CRITICAL ERROR WARNING NOTICE INFORMATIONAL
DEBUG -logFacility LOCAL4 -timeZone LOCAL_TIME -dns ENABLED
2. Create a syslog policy and specify the created syslog action in the policy. At the command prompt, type:
add audit syslogPolicy <name> <rule> <action>
Example:
Example:
4. Create a DNS profile and enable any of the following type of logs that you want to configure:
DNS Query Logging
DNS Answer Section Logging
DNS Extended Logging
DNS Error Logging
At the command prompt, type:
Example:
Example:
Example:
7. Bind the service to the virtual server. At the command prompt, type:
bind lb vserver <name> <serviceName>
8. Set the created DNS profile to the virtual server. At the command prompt, type:
set lb vserver <name> [ - dnsProfileName <string>]
Example:
Sample DNS Logging Conf iguration f or NetScaler Appliance Conf igured as DNS Proxy
> add audit syslogAction nssyslogact1 10.102.151.136 -logLevel
CRITICAL ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -timeZone
LOCAL_TIME -dns ENABLED
Done
> add audit syslogPolicy syslogpol1 ns_true nssyslogact1
Done
> bind system global syslogpol1
Done
> add dns profile dnsprofile1 -dnsqueryLogging ENABLED
Done
> add lb vserver lb1 dns 100.100.100.10 53 –dnsProfileName dnsprofile1
Done
> add service svc1 10.102.84.140 dns 53
Done
> bind lb vserver lb1 svc1
Done
Sample DNS Logging Conf iguration f or NetScaler Appliance Conf igured as ADNS
> add audit syslogAction nssyslogact1 10.102.151.136 -logLevel CRITICAL
ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4 -timeZone LOCAL_TIME
-dns ENABLED
Done
> add audit syslogPolicy syslogpol1 ns_true nssyslogact1
Done
> bind system global syslogpol1
Done
> add dns profile dnsprofile1 -dnsqueryLogging ENABLED
Done
> add lb vserver lb1 dns 100.100.100.10 53 –dnsProfileName dnsprofile1
Done
> add service svc1 10.102.84.140 dns 53
Done
> bind lb vserver lb1 svc1
Done
Sample DNS Logging Conf iguration f or NetScaler Appliance Conf igured as a Forwarder
Sample DNS Logging Conf iguration f or NetScaler Appliance Conf igured as a Resolver
> add audit syslogAction nssyslogact1 10.102.151.136
-logLevel CRITICAL ERROR WARNING NOTICE INFORMATIONAL DEBUG -logFacility LOCAL4
-timeZone LOCAL_TIME -dns ENABLED
Done
> add audit syslogPolicy syslogpol1 ns_true nssyslogact1
Done
> bind system global syslogpol1
Done
> add dns profile dnsprofile1 -dnsqueryLogging ENABLED
Done
> set dns parameter -recursion enABLED
Done
> add nameserver 1.1.1.100 -local dnsProfileName dnsprofile1
Done
Policy based logging enables you to specify a format for log messages. T he contents of a log message are defined by using
a default syntax expression. When the message action specified in the policy is performed, the NetScaler appliance
constructs the log message from the expression and writes the message to the log file. You can configure the appliance to
log only when a particular DNS policy evaluates to True.
Note: If you have set a DNS policy with a DNS profile for the request side, NetScaler appliance logs only the query.
T o configure policy based logging for a DNS policy, you must first configure an audit message action. For more information
about configuring an audit message action, see Configuring Policy-Based Logging. After configuring the audit message
action, specify the message action in a DNS policy.
To conf igure policy based logging f or a DNS policy by using the command line interf ace
At the command prompt, type the following commands to configure policy based logging for a DNS policy and verify the
configuration:
add dns action <actionName> <actionT ype> [-IPAddress <ip_addr|ipv6_addr> ... | -viewName <string> |
-pref erredLocList <string> ...] [-TTL <secs>] [-dnsProf ileName <string>]
set dns policy <name> [<rule>] [-actionName <string>] [-logAction <string>]
Example 1:
In a GSLB deployment, if you want to respond with different IP addresses to the client requests coming from a particular
subnet, instead of responding with IP addresses used for general purposes (such as the IP addresses of internal users), you
can configure a DNS policy with the action type as DNS view. In this case, you can configure DNS logging on the specified
DNS action such that you can log the specific responses.
For example:
> add dns profile dns_prof1 -dnsqueryLogging enABLED -dnsanswerSecLogging enABLED
Done
> add dns view dns_view1
Done
> add dns action dns_act1 viewName -view dns_view1 –dnsprofilename dns_prof1
Done
> add dns policy dns_pol1 "CLIENT.IP.SRC.APPLY_MASK(255.255.255.0).EQ(100.100.100.0)”
dns_act1
Done
> bind dns global dns_pol1 100 -gotoPriorityExpression END -type REQ_DEFAULT
Done
> bind gslb service site_1_svc -viewName dns_view1 123.1.1.1
Done
> bind gslb service site_5_svc -view dns_view1 132.1.1.1
Done
Note: In the above configuration, if you query for the domain configured on a GSLB virtual server, for example,
sampletest.com, all the internal users of subnet 100.100.100.0/24 are served with the DNS view IP addresses, and the
responses are logged. Client requests for other subnets are not logged.
Example 2:
If you want to log only the queries for the domain example.com, you can create a DNS profile with query logging enabled
and set the DNS profile to a DNS action with the action type NOOP, and then create a DNS policy and set the DNS
action. For example:
>add dns profile query_logging -dnsqueryLogging ENABLED
Done
>add dns action dns_act1 NOOP -dnsprofileName query_logging
Done
>add dns policy dns_pol1 DNS.REQ.QUESTION.DOMAIN.EQ("example.com") dns_act1
Done
DNS suffixes have significance and are valid only when the NetScaler is configured as an end resolver or forwarder. You can
specify a suffix of up to 127 characters.
Example
In the ADNS mode, the NetScaler appliance returns the records held in its local cache. If there are no records in the cache,
the appliance returns the NXDOMAIN (negative) response.
If the NetScaler can match the domain delegation records, it returns the NS records. Otherwise, it returns the NS records
of the root domain.
In proxy mode, the NetScaler appliance checks its local cache. If there are no records in the cache, the appliance passes the
query to the server.
Updated: 2013-08-26
If a GSLB domain is configured on the NetScaler appliance and an ANY query is sent for the GSLB domain (or GSLB site
domain), the appliance returns the IP address of the GSLB service that it selects through the Load Balancing decision. If the
multiple IP response (MIR) option is enabled, the IP addresses of all GSLB services are sent.
For the NetScaler to return these records when it responds to the ANY query, all records corresponding to a GSLB domain
must be configured on the NetScaler.
Note: If records for a domain are distributed between the NetScaler and a server, only records configured on the NetScaler
are returned.
T he NetScaler provides the option to configure DNS views and DNS policies. T hese are used for performing global server
load balancing. For more information, see Global Server Load Balancing.
Note
Negative caching is supported only when the back-end server is configured as an authoritative DNS (ADNS) server for the queried
domain.
NXDOMAIN error message— If a negative response is present in the local cache, the NetScaler returns an error message
(NXDOMAIN). If the response is not in the local cache, the query is forwarded to the server, and the server returns an
NXDOMAIN error to the NetScaler appliance. T he appliance caches the response locally, then returns the error message
to the client.
NODAT A error message— If the domain name in query is valid but records of the given type are not available, the
appliance sends a NODAT A error message.
When negative caching is enabled, the appliance caches the negative response from the DNS server and serves the future
requests from the cache only. T his helps speed up responses to queries and also to reduce the DNS traffic. Negative
caching can be used in all deployments, that is, when a NetScaler appliance is serving as a proxy, as an end resolver, or as a
forwarder.
You can enable or disable negative caching using DNS profile, for more information see, DNS Profiles. By default, negative
caching is enabled in the default DNS profile (default-dns-profile) that are bound by default to a DNS virtual server or in the
newly created DNS profile.
To enable or disable negative caching by using the command line interf ace
At the command prompt, type the following commands to enable or disable negative caching and verify the configuration:
add dns profile <dnsProfileName> [-cacheRecords ( ENABLED | DISABLED )] [-cacheNegativeResponses (ENABLED |
DISABLED )]
show dns profile [<dnsProfileName>]
To specif y service or virtual server level DNS parameters by using the command line interf ace
At the command prompt, perform the following:
1. Configure the DNS profile.
add dns profile <dnsProfileName> [-cacheRecords ( ENABLED | DISABLED )] [-cacheNegativeResponses (ENABLED |
DISABLED )]
Example
>set service service1 -dnsProfileName dns_profile1
Done
To bind the DNS profile to the virtual server:
Example
>set lb vserver lbvserver1 -dnsProfileName dns_profile1
Done
To specif y service or virtual server level DNS parameters by using the conf iguration utility
1. Configure the HT T P profile.
Navigate to System > Profiles> DNS Profile, and create the DNS profile.
.
2. Bind the HT T P profile to the service or virtual server.
Navigate to Traf fic Management > Load Balancing> Services/Virtual Servers, and create the DNS profile, which
should be bound to the service/virtual server.
Note:
ECS caching is disabled by default. You have to enable caching of EDNS0 client-subnet data in the associated DNS
profile.
T he number of subnets that you can cache for a domain is limited to the available subnet IDs, that is, 1270 in the
NetScaler appliance. Optionally, you can set the limit to a lower number (minimum value: 1 ipv4/ipv6).
To limit the number of subnets that can be cached per domain by using the command line
Example
At this point, the response and the client-subnet identifier (2.2.2.0/24) are cached. Further requests from the same subnet
and domain will be served from the cache.
For example, if the client’s IP address is 2.2.2.100 and the query is for www.example.com, the query is served from the cache
instead of being sent to the backend server.
T he DNSSEC specification is described in RFC 4033, “DNS Security Introduction and Requirements,” RFC 4034, “Resource
Records for the DNS Security Extensions,” and RFC 4035, “Protocol Modifications for the DNS Security Extensions.” T he
operational aspects of implementing DNSSEC within DNS are discussed in RFC 4641, “DNSSEC Operational Practices.”
You can configure DNSSEC on the Citrix® NetScaler® ADC. You can generate and import keys for signing DNS zones. You
can configure DNSSEC for zones for which the NetScaler ADC is authoritative. You can configure the ADC as a DNS proxy
server for signed zones hosted on a farm of backend name servers. If the ADC is authoritative for a subset of the records
belonging to a zone for which the ADC is configured as a DNS proxy server, you can include the subset of records in the
DNSSEC implementation.
T he NetScaler ADC does not act as a DNSSEC resolver. DNSSEC on the ADC is supported only in the following deployment scenarios:
1. ADNS— NetScaler is the ADNS and generates the signatures itself.
2. Proxy— NetScaler acts as a DNSSEC proxy. It is assumed that the NetScaler is placed in front of the ADNS/LDNS servers in a trusted mode. T he ADC acts only as a proxy caching
entity and does not validate any signatures.
Updated: 2014-08-27
You must enable DNSSEC on the NetScaler ADC for the ADC to respond to DNSSEC-aware clients. By default, DNSSEC is enabled.
You can disable the DNSSEC feature if you do not want the NetScaler ADC to respond to clients with DNSSEC-specific information.
Example
Updated: 2014-10-29
For each DNS zone that you want to sign, you must create two pairs of asymmetric keys. One pair, called the Zone Signing Key, is used to sign all the resource record sets in the zone.
T he second pair is called the Key Signing Key and is used to sign only the DNSKEY resource records in the zone.
When the Zone Signing Key and Key Signing Key are created, the suffix .key is automatically appended to the names of the public components of the keys and the suffix .private is
automatically appended to the names of their private components.
Additionally, the NetScaler ADC also creates a Delegation Signer (DS) record and appends the suffix .ds to the name of the record. If the parent zone is a signed zone, you must publish
the DS record in the parent zone to establish the chain of trust.
When you create a key, the key is stored in the /nsconfig/dns/ directory, but it is not automatically published in the zone. After you create a key by using the create dns key command,
Perform the steps described in this topic to create a Zone Signing Key and then repeat the steps to create a Key Signing Key. T he example that follows the command syntax first
creates a Zone Signing Key pair for the zone example.com. T he example then uses the command to create a Key Signing Key pair for the zone.
create dns key -zoneName <string> -keyT ype <keyT ype> -algorithm RSASHA1 -keySize <positive_integer> -fileNamePrefix <string>
Example
> create dns key -zoneName example.com -keyType zsk -algorithm RSASHA1 -keySize 1024 -fileNamePrefix example.com.zsk.rsasha1.1024
File Name: /nsconfig/dns/example.com.zsk.rsasha1.1024.key (public); /nsconfig/dns/example.com.zsk.rsasha1.1024.private (private); /nsconfig/dns/example.com.zsk.rsasha1.1024.ds (ds)
This operation may take some time, Please wait...
Done
> create dns key -zoneName example.com -keyType ksk -algorithm RSASHA1 -keySize 4096 -fileNamePrefix example.com.ksk.rsasha1.4096
File Name: /nsconfig/dns/example.com.ksk.rsasha1.4096.key (public); /nsconfig/dns/example.com.ksk.rsasha1.4096.private (private); /nsconfig/dns/example.com.ksk.rsasha1.4096.ds (ds)
This operation may take some time, Please wait...
Done
>
Updated: 2014-10-29
A key (Zone Signing Key or Key Signing Key) is published in a zone by adding the key to the NetScaler ADC. A key must be published in a zone before you sign the zone.
Before you publish a key in a zone, the key must be available in the /nsconfig/dns/ directory. T herefore, if you used other means to generate the key— means other than the create
dns key command on the NetScaler ADC (for example, by using the bind-keygen program on another computer)— make sure that the key is added to the /nsconfig/dns/ directory
before you publish the key in the zone.
If the key has been generated by another program, you can import the key to your local computer and use the NetScaler configuration utility to add the key to the /nsconfig/dns/
directory. Or, you can use other means to import the key to the directory, such as the Secure File Transfer Protocol (SFT P).
You must use the add dns key command for each public-private key pair that you want to publish in a given zone. If you created a Zone Signing Key pair and a Key Signing Key pair for a
zone, use the add dns key command to first publish one of the key pairs in the zone and then repeat the command to publish the other key pair. For each key that you publish in a
zone, a DNSKEY resource record is created in the zone.
T he example that follows the command syntax first publishes the Zone Signing Key pair (that was created for the example.com zone) in the zone. T he example then uses the
command to publish the Key Signing Key pair in the zone.
add dns key <keyName> <publickey> <privatekey> [-expires <positive_integer> [<units>]] [-notificationPeriod <positive_integer> [<units>]] [-T T L <secs>]
show dns zone [<zoneName> | -type <type>]
Example
Updated: 2014-08-27
You can configure the parameters of a key that has been published in a zone. You can modify the key’s expiry time period, notification period, and time-to-live (T T L) parameters. If you
change the expiry time period of a key, the NetScaler ADC automatically re-signs all the resource records in the zone with the key, provided that the zone is currently signed with the
particular key.
set dns key <keyName> [-expires <positive_integer> [<units>]] [-notificationPeriod <positive_integer> [<units>]] [-T T L <secs>]
show dns key [<keyName>]
Example
> set dns key example.com.ksk -expires 30 DAYS -notificationPeriod 3 DAYS -TTL 3600
Done
> show dns key example.com.ksk
1) Key Name: example.com.ksk
Expires: 30 DAYS Notification: 3 DAYS TTL: 3600
Public Key File: example.com.ksk.rsasha1.4096.key
Private Key File: example.com.ksk.rsasha1.4096.private
Done
>
To configure a key by using the configuration utility
1. Navigate to T raffic Management > DNS > Keys.
2. In the details pane, click the key that you want to configure, and then click Open.
3. In the Configure DNS Key dialog box, modify the values of the following parameters as shown:
Expires— expires
Notification Period— notificationPeriod
T T L— T T L
4. Click OK.
Updated: 2014-08-27
To secure a DNS zone, you must sign the zone with the keys that have been published in the zone. When you sign a zone, the NetScaler ADC creates a Next Secure (NSEC) resource
record for each owner name. T hen, it uses the Key Signing Key to sign the DNSKEY resource record set. Finally, it uses the Zone Signing Key to sign all the resource record sets in the
zone, including the DNSKEY resource record sets and NSEC resource record sets. Each sign operation results in a signature for the resource record sets in the zone. T he signature is
captured in a new resource record called the RRSIG resource record.
Example
Example
T o unsign the zone, clear the check boxes for the keys (Zone Signing Key and Key Signing Key) with which you want to unsign the zone.
You can unsign the zone with more than one Zone Signing Key or Key Signing Key pair.
4. Click OK.
Updated: 2014-08-27
You can view the NSEC records that the NetScaler ADC automatically creates for each owner name in the zone.
To view the NSEC record for a given record in a zone by using the command line interface
At the command prompt, type the following command to view the NSEC record for a given record in a zone:
Updated: 2014-08-27
To remove a key from the NetScaler ADC by using the command line interface
At the command prompt, type the following command to remove a key and verify the configuration:
Example
If any global server load balancing (GSLB) domains configured on the ADC belong to the zone being signed, the GSLB
domain names are signed along with the other records that belong to the zone.
After you sign a zone, responses to requests from DNSSEC-aware clients include the RRSIG resource records along with
the requested resource records. DNSSEC must be enabled on the ADC. For more information about enabling
DNSSEC, see Enabling and Disabling DNSSEC.
Finally, after you configure DNSSEC for the authoritative zone, you must save the NetScaler configuration.
Note: T he terms zone-less proxy server configuration and partial zone are used only in the context of the NetScaler
appliance.
Important: When configured in proxy mode, the ADC does not perform signature verification on DNSSEC responses before
updating the cache.
If you configure the ADC as a DNS proxy to load balance DNSSEC aware resolvers (servers), you must set the Recursion
Available option while configuring the DNS virtual server. If a DNSSEC query arrives with Checking Disabled (CD) bit set, the
query is passed on to the server with the CD bit retained, and the response from the server is not cached. In releases prior
to 10.5.e build xx.x, the ADC unset the CD bit before passing it to the server and also cached the server response.
Updated: 2014-08-27
For a zone-less DNS proxy server configuration, zone signing must be performed on the backend name servers. On the
NetScaler ADC, you configure the ADC as a DNS proxy server for the zone. You create a load balancing virtual server of
protocol type DNS, configure services on the ADC to represent the name servers, and then bind the services to the load
balancing virtual server. For more information about these configuration tasks, see Configuring the NetScaler as a DNS
Proxy Server.
When a client sends the ADC a DNS request with the DNSSEC OK (DO) bit set, the ADC checks its cache for the requested
information. If the resource records are not available in its cache, the ADC forwards the request to one of the DNS name
servers, and then relays the response from the name server to the client. Additionally, the ADC caches the RRSIG resource
records along with the response from the name server. Subsequent requests from DNSSEC-aware clients are served from
the cache (including the RRSIG resource records), subject to the time-to-live (T T L) parameter. If a client sends a DNS
request without setting the DO bit, the ADC responds with only the requested resource records, and does not include the
RRSIG resource records that are specific to DNSSEC.
Updated: 2014-08-27
A typical partial zone configuration on the NetScaler ADC is seen when global server load balancing (GSLB) domains are
configured on the ADC, and the GSLB domains are a part of a zone for which the backend name servers are authoritative.
Signing a zone that includes only a partial zone on the ADC involves including the partial zone information in the backend
name server zone files, signing the zone on the backend name servers, and then signing the partial zone on the ADC. T he
same key set must be used to sign the zone on the name servers and the partial zone on the ADC.
For example, if the name of the zone that is configured on the backend name servers is example.com, you must create a
zone named example.com on the ADC, with the proxyMode parameter set to YES. For more information about adding a
zone, see Configuring a DNS Zone.
Note: Do not add SOA and NS records for the zone. T hese records should not exist on the ADC for a zone for which the
ADC is not authoritative.
2. Import the keys (from one of the backend name servers) to the ADC and then add them to the /nsconfig/dns/ directory.
For more information about how you can import a key and add it to the ADC, see Publishing a DNS Key in a Zone.
3. Sign the partial zone with the imported keys. When you sign the partial zone with the keys, the ADC generates RRSIG
and NSEC records for the resource record sets and individual resource records in the partial zone, respectively. For more
information about signing a zone, see Signing and Unsigning a DNS Zone.
If the GSLB domains belong to a zone for which the backend name servers are authoritative, you must first sign the zone
on the name servers, and then sign the partial zone on the ADC to complete the DNSSEC configuration for the zone. For
more information, see Configuring DNSSEC for a Partial Zone Ownership Configuration.
Updated: 2014-08-27
When a zone is updated, that is, when new records are added to the zone or existing records are changed, the process of
re-signing the new (or modified) record is performed automatically by the Citrix® NetScaler® ADC. If a zone contains
multiple Zone Signing Keys, the ADC re-signs the new (or modified) record with the key with which the zone is signed at the
point in time when the re-signing is to be performed.
Updated: 2014-08-27
On the NetScaler ADC, you can use the pre-publish and double signature methods to perform a rollover of the Zone Signing
Key and Key Signing Key. More information about these two rollover methods is available in RFC 4641, “DNSSEC
Operational Practices.”
T he following topics map commands on the ADC to the steps in the rollover procedures discussed in RFC 4641.
T he key expiry notification is sent through an SNMP trap called dnskeyExpiry. T hree MIB variables, dnskeyName,
dnskeyT imeToExpire, and dnskeyUnitsOfExpiry are sent along with the dnskeyExpiry SNMP trap. For more information, see
Citrix NetScaler SNMP OID Reference at .
Stage 1: Initial. T he zone contains only those key sets with which the zone has currently been signed. T he state of the
zone in the initial stage is the state of the zone just before you begin the key rollover process.
Example
Consider the key, example.com.zsk1, with which the zone example.com is currently signed. T he zone contains only those
RRSIGs that were generated by the example.com.zsk1 key, which is due for expiry. T he Key Signing Key is
example.com.ksk1.
A new key example.com.zsk2 is added to the example.com zone. T he zone is not signed with example.com.zsk2 until the
pre-roll phase is complete. T he example.com zone contains DNSKEY resource records for both example.com.zsk1 and
example.com.zsk2.
NetScaler commands
Publish the new DNS key in the zone by using the add dns key command.
For more information about publishing the key in the zone, including an example, see Publishing a DNS Key in a Zone.
Stage 3: New RRSIGs. T he zone is signed with the new DNS key and then unsigned with the old DNS key. T he old DNS
key is not removed from the zone and remains published until the RRSIGs that were generated by the old key expire.
Example
T he zone is signed with example.com.zsk2 and then unsigned with example.com.zsk1. T he zone continues to publish
example.com.zsk1 until the RRSIGs that were generated by example.com.zsk1 expire.
NetScaler commands
Stage 4 : DNSKEY Removal. When the RRSIGs that were generated by the old DNS key expire, the old DNS key is
removed from the zone.
Example
NetScaler commands
On the ADC, you remove the old DNS key by using the rm dns key command. For more information about removing a key
from a zone, including an example, see Removing a DNS Key.
Consider the key, example.com.zsk1, with which the zone example.com is currently signed. T he zone contains only those
RRSIGs that were generated by the example.com.zsk1 key, which is due for expiry. T he Key Signing Key is
example.com.ksk1.
Stage 2: New DNSKEY. T he new key is published in the zone and the zone is signed with the new key. T he zone
contains the RRSIGs that are generated by the old and the new keys. T he minimum duration for which the zone must
contain both sets of RRSIGs is the time required for all the RRSIGs to expire.
Example
A new key example.com.zsk2 is added to the example.com zone. T he zone is signed with example.com.zsk2. T he
example.com zone now contains the RRSIGs generated from both keys.
NetScaler commands
Publish the new key in the zone by using the add dns key command.
For more information about publishing the key in the zone, including an example, see Publishing a DNS Key in a Zone.
Sign the zone with the new key by using the sign dns zone command.
For more information about signing a zone, including examples, see Signing and Unsigning a DNS Zone.
Stage 3: DNSKEY Removal. When the RRSIGs that were generated by the old DNS key expire, the old DNS key is
removed from the zone.
Example
NetScaler commands
On the ADC, you remove the old DNS key by using the rm dns key command.
For more information about removing a key from a zone, including an example, see Removing a DNS Key.
For setting up DNSSEC offloading, you must configure a DNS load balancing virtual server, configure services that represent
the DNS servers, and then bind the services to the virtual server. For information about configuring a DNS load balancing
virtual server, configuring services, and binding the services to the virtual server, see Configuring a DNS Zone.
You must create a zone entity on the ADC for each DNS zone whose DNSSEC operations you want to offload. For each
DNS zone, you must enable the Proxy Mode and DNSSEC Offload parameters. You can optionally configure NSEC record
generation for an offloaded zone. To create a DNS zone entity for DNSSEC offloading, follow the instructions in this topic.
To complete the configuration, you must generate DNS keys for the zone, add the keys to the zone, and then sign the
zone with the keys. T his process is the same as for normal DNSSEC. For information about creating keys, adding keys to a
zone, and signing the zone, see Domain Name System Security Extensions.
After you configure DNS offloading, you must flush the DNS cache on the ADC. Flushing the DNS cache ensures that any
unsigned records in the cache are removed and subsequently replaced by signed records. For information about flushing the
DNS cache, see Flushing DNS Records.
To enable DNSSEC of floading f or a zone by using the command line interf ace
At the command line, type the following commands to enable DNSSEC offloading for a zone and verify the configuration:
add dns zone <zoneName> -proxyMode YES -dnssecOffload ENABLED [-nsec ( ENABLED | DISABLED )
show dns zone
Example
> add dns zone example.com -proxyMode YES -dnssecOffload ENABLED nsec ENABLED
Done
> show dns zone example.com
Zone Name : example.com
Proxy Mode : YES
DNSSEC Offload: ENABLED NSEC: ENABLED
Done
>
To enable DNSSEC of floading f or a zone by using the configuration utility
You can now add a password to the DNS key. To add a password to the DNS key, you must first add the password in the
create dns key command and then provide the same password in the add dns key command when adding the DNS key to
the NetScaler appliance. For example:
create dns key -zoneName com -keytype ksK -algorithm rsASHA1 -keysize 4 096 - fileNamePrefix
com.ksk.rsasha1.4 096 -password 1jsf d3Wa
add dns key com.zsk.4 096 /nsconfig/dns/com.zsk.rsasha1.4 096.private -password 1jsf d3Wa
Note:
For default partitioned environment, the keys are read from default location/nsconfig/dns/. However, if the keys are
stored in a different location, the path name has to be provided in the add dns key – private command. Example, add dns
key – private <path name>.
For non-default partitioned environment, the keys are read from the default
location/nsconfig/partitions/<partitionname>/dns/.
In DNS resolution, the wildcard domain is supported by wildcard RRs. T he wildcard RRs are used to synthesize the responses
to queries for a nonexistent domain name. For example, if you queried http://image.example.com, and the subdomain
"image" did not exist, you could be redirected to example.com.
A wildcard record has an asterisk (*) character as the leftmost label of a domain name. For example, *.example.com. An
asterisk at any other place in the domain name does signify a wildcard DNS record. For example, new.*.example.com is not
a valid wildcard DNS record.
Note:
Wildcard domain is supported only when the NetScaler appliance is authoritative for the zone.
Wildcard domain is not supported for NS and SOA records.
Wildcard domain cannot be applied when the query is in another zone.
Wildcard domain cannot be applied when the QNAME or a name between the wildcard domain and the QNAME is
known to exist.
Example Configuration
Example COPY
In the example, wildcard domain name is added for A and AAAA record.
When a query is received for a domain name that exists in the zone, say www.example.com, the NetScaler appliance
responds with the corresponding response; that is 2.2.2.2 in the example.
For a nonexistent domain name that matches with a wildcard type, a synthesized response is delivered.
In the example, the NetScaler appliance responds with 10.10.10.10 and 10.10.10.11 for domain name nonexist.example.com
or xyz.example.com.
Wildcard synthesize is not applicable for a domain name that exists in the zone.
For example, for the query www.example.com and type AAAA, the NetScaler appliance does not synthesize with wildcard,
because www.example.com exists with type A. In the example, the NetScaler appliance responds with a NODATA response.
For a query say abc.example.com and type AAAA, the NetScaler appliance responds with a synthesized response; that is
2001::1 in the example.
A DNS attack fills the cache with negative records (NXDOMAIN and NODATA). As a result, responses to legitimate requests
are not cached, so new requests are sent to a back-end server for DNS resolution. Responses are therefore delayed.
You can now flush the negative DNS records from the NetScaler appliance's DNS cache.
Example
1. Navigate to Conf iguration > Traf f ic Management > DNS > Records.
2. In the details pane, click Flush Proxy Records.
3. In the Flush Type box, select Negative Records.
4. In the Negative Records Type box, select either NXDOMAIN or NODATA.
To prevent random subdomain and NXDOMAIN attacks, you can restrict the DNS cache memory, and you can adjust the
T T L values for negative records.
To limit the amount of memory consumed by the DNS cache, you can specify the maximum cache size (in MB), and also
the cache size (in MB) for storing negative responses. When either limit is reached, no more entries are added to the cache.
Also, syslog messages are logged and, if you have configured SNMP traps, SNMP traps are generated. If these limits are not
set, caching continues until the system memory is exhausted.
A higher T T L value for negative records can result in storing records that are not valuable for a long period of time. A lower
T T L value results in sending more requests to the back-end server.
T he T T L of the negative record is set to a value that can be lesser of the T T L value or the ”Expires” value of the SOA
record.
Note:
To use the NetScaler command line to limit the memory consumed by the DNS Cache
Example
To use the NetScaler GUI to limit the memory consumed by the DNS Cache
Navigate to Configuration > Traf fic Management > DNS, click Change DNS Settings, and set the following parameters:
Example
An attack can flood the DNS cache with entries that are not valuable but can cause flushing of the already cached
legitimate records to make room for the new entries. To prevent attacks from filling the cache with invalid data, you can
retain the legitimate records even after they exceed their T T L values.
If you enable the cacheNoExpire parameter, the records currently in the cache are retained until you disable the parameter.
Note:
T his option can be used only when the maximum cache size is specified (maxCacheSize parameter).
If maxnegcacheT T L is configured and cacheNoExpire is enabled, cacheNoExpire takes priority.
To retain DNS records in the cache by using the NetScaler command line
Example
1. Navigate to Conf iguration > Traf f ic Management > DNS and click Change DNS Settings.
2. Select Cache No Expire.
For greater visibility and control of DNS requests arriving at the NetScaler appliance, you can set the cacheHitBypass
parameter to forward all requests to the back-end servers and allow cache to be built but not used. After the cache is built,
you can disable the parameter so that requests are served from the cache.
Example
1. Navigate to Conf iguration > Traf f ic Management > DNS and click Change DNS Settings.
2. Select Cache Hit Bypass.
A DNS query spanning multiple packets presents the potential threat of a Slowloris attack. T he NetScaler appliance can
silently drop DNS queries that are split into multiple packets.
You can set the splitPktQueryProcessing parameter to ALLOW or DROP a DNS query if the query is split into multiple
packets.
To limit the DNS queries to a single packet by using the NetScaler command line
Example
You can collect statistics of the DNS responses served from cache and use these statistics to create a threshold beyond
which additional DNS traffic is dropped, and enforce this threshold with a bandwidth based policy. Previously, bandwidth
calculation for a DNS load balancing virtual server was not accurate, because the number of cache hits was not reported.
In proxy mode, the statistics for Request bytes, Response bytes, Total Packets rcvd, and Total Packets sent statistics are
continuously updated. Previously, these statistics were not always updated, particularly for a DNS load balancing virtual
server.
Proxy mode also now enables you to determine the number of DNS responses served from the cache. To help collect these
statistics, the following options have been added to the stat lb vserver <DNSvirtualServerName> command:
Requests – T otal number of requests received by the DNS or DNS_T CP vserver. Includes the requests forwarded to the
back end and the requests answered from the cache.
Vserver hits – T otal number of requests forwarded to the back end. T he total number of cache hits is the difference
between Requests and Vserver hits.
Responses – T otal number of responses sent by this vserver. For example, if a DNS LB virtual server received 5 DNS
requests, forwarded 3 of them to the back end, and served 2 of them from the cache, the corresponding value of each
of these statistics would be as follows:
Vserver hits: 3
Requests: 5
Responses: 5
Dividing the load between the firewalls, which eliminates a single point of failure and allows the network to scale.
Increasing high availability.
Configuring a NetScaler appliance for firewall load balancing is similar to configuring load balancing, with the exception that
the recommended service type is ANY, recommended monitor type is PING, and the load balancing virtual server mode is set
to MAC.
You can set up firewall load balancing in a sandwich, an enterprise, or multiple-firewall environment configuration. T he
sandwich environment is used for load balancing traffic entering the network from outside and traffic leaving the network
to the internet and involves configuring two NetScaler appliances, one on each side of a set of firewalls. You configure an
enterprise environment for load balancing traffic leaving the network to the internet. T he enterprise environment involves
configuring a single NetScaler appliance between the internal network and the firewalls that provide access to the Internet.
T he multiple-firewall environment is used for load balance traffic coming from another firewall. Having firewall load
balancing enabled on both the sides of NetScaler improves the traffic flow in both the egress and ingress direction and
ensures faster processing of the traffic. T he multiple-firewall environment involves configuring a NetScaler appliance
sandwiched between two firewalls.
Important: If you configure static routes on the NetScaler for the destination IP address and enable L3 mode, the
NetScaler uses its routing table to route the traffic instead of sending the traffic to the load balancing vserver.
Note: For FT P to work, an additional virtual server or service should be configured on the NetScaler with IP address and
port as * and 21 respectively, and the service type specified as FT P. In this case, the NetScaler manages the FT P protocol
by accepting the FT P control connection, modifying the payload, and managing the data connection, all through the same
firewall.
Firewall Load Balancing supports only some of the load balancing methods supported on the NetScaler. Also, you can
configure only a few types of persistence and monitors.
T he following load balancing methods are supported for firewall load balancing.
Least Connections
Round Robin
Least Packets
Least Bandwidth
Source IP Hash
Destination IP Hash
Source IP Destination IP Hash
Source IP Source Port hash
Least Response T ime Method (LRT M)
Custom Load
Firewall Persistence
Only PING and transparent monitors are supported in firewall load balancing. You can bind a PING monitor (default) to the
backend service that represents the firewall. If a firewall is configured not to respond to ping packets, you can configure
transparent monitors to monitor hosts on the trusted side through individual firewalls.
In this setup, a NetScaler is located on each side of a set of firewalls. T he NetScaler placed between the firewalls and the
Internet, called the external NetScaler that handles ingress traffic selects the best firewall, based on the configured
method. T he NetScaler between the firewalls and the private network, called the internal NetScaler tracks the firewall from
which the initial packet for a session is received. It then makes sure that all subsequent packets for that session are sent to
the same firewall.
T he internal NetScaler can be configured as a regular traffic manager to load balance traffic across the private network
servers. T his configuration also allows traffic originating from the private network (egress) to be load balanced across the
firewalls.
To avail benefits related to HT T P and TCP, configure the service and virtual server with type HT T P or TCP. For FT P to work,
configure the service with type FT P.
Updated: 2015-05-22
Perform the following tasks to configure the external NetScaler in a sandwich environment
At the command prompt, type the following command to enable load balancing and verify the configuration:
enable ns feature LB
show ns feature
Example
Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.
Navigate to Traffic Management > Load Balancing > Services and add a service. Specify ANY in the Protocol field and * in
the Port field.
Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition to a transparent
monitor, after you create and bind a transparent monitor, you need to bind a PING monitor to the service.
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
Example
Navigate to T raffic Management > Load Balancing > Monitors, and then create and bind a transparent monitor.
Configure a wildcard virtual server for traffic coming from the Internet
To configure a wildcard virtual server for traffic coming from the Internet by using the command line interface
Navigate to Traffic Management > Load Balancing > Virtual Servers and create a wildcard virtual server. Specify ANY in the
Protocol field and * in the Port field.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers and select the virtual server for which you want to
configure the redirection mode (for example, Vserver-LB-1).
2. Edit the Basic Settings section and. click more.
3. From the Redirection Mode drop-down list, select MAC Based.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers and select the virtual server for which you want to
bind the service.
2. Click in the Services section and select a service to bind.
To save and verify the configuration by using the command line interface
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
save ns config
show vserver
Example
save config
sh lb vserver FWLBVIP1
FWLBVIP1 (*:*) - ANY Type: ADDRESS
State: UP
Last state change was at Mon Jun 14 06:40:14 2010
Time since last state change: 0 days, 00:00:11.240
Effective State: UP ARP:DISABLED
Client Idle Timeout: 120 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
No. of Bound Services : 2 (Total) 2 (Active)
Updated: 2015-06-04
Perform the following tasks to configure the internal NetScaler in a sandwich environment
At the command prompt, type the following command to enable load balancing and verify the configuration:
enable ns feature LB
show ns feature
Example
Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.
Navigate to Traffic Management > Load Balancing > Services and add a service. Specify ANY in the Protocol field and * in
the Port field.
Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition to a transparent
monitor, after you create and bind a transparent monitor, you need to bind a PING monitor to the service.
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
Example
1. Navigate to T raffic Management > Load Balancing > Monitors and create a monitor.
2. In the Create Monitor dialog box, enter the required parameters and select Transparent.
Configure a wildcard virtual server to load balance the traffic sent to the firewalls
To configure a wildcard virtual server to load balance the traffic sent to the firewalls by using the command line interface
Navigate to T raffic Management > Load Balancing > Virtual Servers and create a wildcard virtual server. Specify ANY in the
1. Navigate to T raffic Management > Load Balancing > Virtual Servers and select the virtual server for which you want to
configure the redirection mode (for example, Vserver-LB-1).
2. Edit the Basic Settings section and. click more.
3. From the Redirection Mode drop-down list, select MAC Based.
To configure the virtual server in MAC rewrite mode by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.
Navigate to Traffic Management > Load Balancing > Services and configure a service for each virtual server. Specify HTTP in
the Protocol field and select HTTP under Available Monitors.
1.
To configure a service for each virtual server by using the configuration utility
Navigate to T raffic Management > Load Balancing > Services, double-click a service and add a monitor.
To bind a monitor to a service by using the configuration utility
Navigate to Traffic Management > Load Balancing > Virtual Services and configure an HT T P virtual server. Specify HTTP in
the Protocol field.
1.
To configure an HT T P virtual server to balance traffic sent to the servers by using the configuration utility
To save and verify the configuration by using the command line interface
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
save ns config
show vserver
Example
save config
show lb vserver FWLBVIP2
FWLBVIP2 (*:*) - ANY Type: ADDRESS
State: UP
Last state change was at Mon Jun 14 07:22:54 2010
Time since last state change: 0 days, 00:00:32.760
Effective State: UP
Client Idle Timeout: 120 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
No. of Bound Services : 2 (Total) 2 (Active)
Configured Method: LEASTCONNECTION
Current Method: Round Robin, Reason: A new service is bound
Mode: MAC
Persistence: NONE
Connection Failover: DISABLED
After the configuration is up and running, you should view the statistics for each service and virtual server to check for
possible problems.
To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of the virtual servers
configured on the NetScaler appliance. You can display a summary of statistics for all the virtual servers, or you can specify
the name of a virtual server to display the statistics only for that virtual server. You can display the following details:
Name
IP address
Port
Protocol
State of the virtual server
Rate of requests received
Rate of hits
To display a summary of the statistics for all the virtual servers currently configured on the NetScaler, or for a single virtual
server, at the command prompt, type:
1. Navigate to T raffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the virtual server, and click
Statistics.
You can view the rate of requests, responses, request bytes, response bytes, current client connections, requests in surge
queue, current server connections, and so forth using the service statistics.
1. Navigate to T raffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.
To avail benefits related to HT T P and TCP, configure the service and vserver with type HT T P or TCP. For FT P to work,
configure the service with type FT P.
Updated: 2013-11-08
At the command prompt, type the following command to enable load balancing and verify the configuration:
enable ns feature LB
show ns feature
Example
Navigate to System > Settings and, in Configure Basic Features, select Load Balancing.
Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition to a transparent
monitor, after you create and bind a transparent monitor, you need to bind a PING monitor to the service.
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
Example
Name*
T ype*— type
Destination IP
T ransparent
* A required parameter
4. Click Create, and then click Close. In the Monitors pane, select the monitor that you just configured and verify that the
settings displayed at the bottom of the screen are correct.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and select a virtual server.
2. Click in the Service section, and select a service to bind.
To save and verify the configuration by using the command line interface
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
save ns config
show vserver
Example
save config
show lb vserver FWLBVIP2
FWLBVIP2 (*:*) - ANY Type: ADDRESS
State: UP
Last state change was at Mon Jun 14 07:22:54 2010
Time since last state change: 0 days, 00:00:32.760
Effective State: UP
Client Idle Timeout: 120 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
No. of Bound Services : 2 (Total) 2 (Active)
Configured Method: LEASTCONNECTION
Current Method: Round Robin, Reason: A new service is bound
Mode: MAC
Persistence: NONE
Connection Failover: DISABLED
After the configuration is up and running, you should view the statistics for each service and virtual server to check for
To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of the virtual servers
configured on the NetScaler appliance. You can display a summary of statistics for all the virtual servers, or you can specify
the name of a virtual server to display the statistics only for that virtual server. You can display the following details:
Name
IP address
Port
Protocol
State of the virtual server
Rate of requests received
Rate of hits
To display a summary of the statistics for all the virtual servers currently configured on the NetScaler, or for a single virtual
server, at the command prompt, type:
1. Navigate to T raffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the virtual server, and click
Statistics.
You can view the rate of requests, responses, request bytes, response bytes, current client connections, requests in surge
queue, current server connections, and so forth using the service statistics.
1. Navigate to T raffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.
With a configuration like the one shown in Figure 1, you can configure the NetScaler to load balance the traffic through
the an internal firewall even if it is load balanced by an external firewall. For example, with this feature configured, the
traffic coming from the external firewalls (firewalls 1, 2, and 3) is load balanced on the internal firewalls (firewalls 4, 5, and 6)
and vice versa.
To avail benefits related to HT T P and TCP, configure the service and virtual server with type HT T P or TCP. For FT P to work,
configure the service with type FT P.
Updated: 2015-05-18
T o configure a NetScaler appliance in a multiple-firewall environment, you have to enable the load balancing feature,
configure a virtual server to load balance the egress traffic across the external firewalls, configure a virtual server to load
balance the ingress traffic across the internal firewalls, and enable firewall load balancing on the NetScaler. T o configure a
virtual server to load balance traffic across a firewall in the multiple-firewall environment, you need to:
1. Configure a wildcard service for each firewall
2. Configure a monitor for each wildcard service
3. Configure a wildcard virtual server to load balance the traffic sent to the firewalls
4. Configure the virtual server in MAC rewrite mode
5. Bind firewall services to the wildcard virtual server
At the command prompt, type the following command to enable load balancing and verify the configuration:
Example
At the command prompt, type the following command to configure support for all the protocols and ports:
Binding a transparent monitor will override the PING monitor. To configure a PING monitor in addition to a transparent
monitor, after you create and bind a transparent monitor, you need to bind a PING monitor to the service.
At the command prompt, type the following commands to configure a transparent monitor and verify the configuration:
Example
Name*
T ype*— type
Destination IP
T ransparent
* A required parameter
4. Click Create, and then click Close. In the Monitors pane, select the monitor that you just configured and verify that the
settings displayed at the bottom of the screen are correct.
Configuring a virtual server to load balance the traffic sent to the firewalls
T o load balance any kind of traffic, you need to configure a wildcard virtual server specifying the protocol and port as any
value.
To configure a virtual server to load balance the traffic sent to the firewalls by using the command line interface
To save and verify the configuration by using the command line interface
save ns config
show vserver
Example
save config
show lb vserver FWLBVIP2
FWLBVIP2 (*:*) - ANY Type: ADDRESS
State: UP
Last state change was at Mon Jun 14 07:22:54 2010
Time since last state change: 0 days, 00:00:32.760
Effective State: UP
Client Idle Timeout: 120 sec
Down state flush: ENABLED
Disable Primary Vserver On Down : DISABLED
No. of Bound Services : 2 (Total) 2 (Active)
Configured Method: LEASTCONNECTION
Current Method: Round Robin, Reason: A new service is bound
Mode: MAC
Persistence: NONE
Connection Failover: DISABLED
After the configuration is up and running, you should view the statistics for each service and virtual server to check for
possible problems.
To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of the virtual servers
configured on the NetScaler appliance. You can display a summary of statistics for all the virtual servers, or you can specify
the name of a virtual server to display the statistics only for that virtual server. You can display the following details:
Name
IP address
Port
Protocol
State of the virtual server
Rate of requests received
Rate of hits
To display a summary of the statistics for all the virtual servers currently configured on the NetScaler, or for a single virtual
server, at the command prompt, type:
1. Navigate to T raffic Management > Load Balancing > Virtual Servers > Statistics.
2. If you want to display the statistics for only one virtual server, in the details pane, select the virtual server, and click
Statistics.
You can view the rate of requests, responses, request bytes, response bytes, current client connections, requests in surge
queue, current server connections, and so forth using the service statistics.
1. Navigate to T raffic Management > Load Balancing > Services > Statistics.
2. If you want to display the statistics for only one service, select the service, and click Statistics.
Note
T his feature is available as an option with a NetScaler standard edition license, but is included with the enterprise and platinum
edition licenses.
NetScaler appliances configured for global server load balancing (GSLB) provide for disaster recovery and ensure continuous
availability of applications by protecting against points of failure in a wide area network (WAN). GSLB can balance the load
across data centers by directing client requests to the closest or best performing data center, or to surviving data centers in
case of an outage.
In a typical configuration, a local DNS server sends client requests to a GSLB virtual server, to which are bound GSLB services.
A GSLB service identifies a load balancing or content switching virtual server, which can be at the local site or a remote site.
If the GSLB virtual server selects a load balancing or content switching virtual server at a remote site, it sends the virtual
server’s IP address to the DNS server, which sends it to the client. T he client then resends the request to the new virtual
server at the new IP.
T he GSLB entities that you must configure are the GSLB sites, the GSLB services, the GSLB virtual servers, load balancing or
content switching virtual servers, and authoritative DNS (ADNS) services. You must also configure MEP. You can also
configure DNS views to expose different parts of your network to clients accessing the network from different locations.
Note: T o take full advantage of the NetScaler GSLB features, you should use NetScaler appliances for load balancing or
content switching at each data center, so that your GSLB configuration can use the proprietary Metric Exchange Protocol
(MEP) to exchange site metrics.
When you configure GSLB on NetScaler appliances and enable Metric Exchange Protocol (MEP), the appliances use the
DNS infrastructure to connect the client to the data center that best meets the criteria that you set. T he criteria can
designate the least loaded data center, the closest data center, the data center that responds most quickly to requests
from the client’s location, a combination of those metrics, and SNMP metrics. An appliance keeps track of the location,
performance, load, and availability of each data center and uses these factors to select the data center to which to send a
client request.
A GSLB configuration consists of a group of GSLB entities on each appliance in the configuration. T hese entities include
GSLB sites, GSLB services, GSLB virtual servers, load balancing and/or content switching servers, and ADNS services.
All the sites in an active-active deployment are active, and all the services for a particular application/domain are bound to
the same GSLB vserver. Sites exchange metrics through the Metrics Exchange Protocol (MEP). Site metrics exchanged
between the sites include the status of each load balancing and content switching virtual server, current number of
connections, current packet rate, and current bandwidth usage. T he NetScaler appliance needs this information to perform
load balancing across the sites.
An active-active deployment can include a maximum of 32 GSLB sites, because MEP cannot synchronize more than 32 sites.
No backup sites are configured in this deployment type.
T he NetScaler appliance sends client requests to the appropriate GSLB site as determined by the GSLB method specified in
the GSLB configuration.
For an active-active deployment, you can configure the following GSLB methods.
Round Robin
Least Connections
Least Response T ime
Least Bandwidth
Least Packets
Source IP Hash
Custom Load
Round T rip T ime (RT T )
Static Proximity
Note:
If Site 1 receives the client request, the GSLB virtual server in Site 1 selects a load balancing or content switching virtual
server and sends the virtual server’s IP address to the DNS server, which sends it to the client. T he client then resends the
request to the new virtual server at the new IP address.
As both sites are active, the GSLB algorithm evaluates the services at both sites when making a selection as determined by
the configured GSLB method.
In this type of deployment, some of the sites (remote sites) are reserved only for disaster recovery. T hese sites do not
participate in any decision making until all the active sites are DOWN. A passive site does not become operational unless a
disaster event triggers a failover.
Once you have configured the primary data center, replicate the configuration for the backup data center and designate it
as the passive GSLB site by designating a GSLB virtual server at that site as the backup virtual server.
An active-passive deployment can include a maximum of 32 GSLB sites, because MEP cannot synchronize more than 32
sites.
For an active-passive deployment, you can configure the following GSLB methods.
Round Robin
Least Connections
Least Response T ime
Least Bandwidth
Least Packets
Source IP Hash
Custom Load
Round T rip T ime (RT T )
Static Proximity
Note:
When the client sends a DNS request, the request can land in any of the sites. However, the services are selected only from
the active site (Site1) as long as it is UP.
Services from the passive site (Site 2) are selected only if the active site (Site 1) is DOWN.
T he GSLB parent-child topology is a two-level hierarchical design with the following characteristics:
At the top level are parent sites, which have peer relationships with other parents.
Each parent can have multiple child sites.
Each parent site exchanges health information with its child sites and with other parent sites.
A child site communicates only with its parent site.
In a parent-child relationship for GSLB, only the parent site responds to ADNS queries. T he child sites act as normal load
balancing sites.
An ADNS service or DNS load balancing virtual servers should be configured only in the parent site.
A parent site can have a normal GSLB configuration, that is, services from local and all remote sites, but a child site can
have local services only. Also, only the parent sites have GSLB virtual servers configured.
Note
In a parent-child topology, the exchange of site metrics is initiated from the lower of two IP addresses. However, from NetScaler
release 11.1 build 51.x, the parent sites initiate connections to the child sites, and not vice versa, because the parent sites have
information about all the child sites in the GSLB setup.
In a parent-parent connection, the exchange of site metrics is still initiated from the lower IP of two IP addresses.
In a parent-child topology, GSLB services are not always required to be configured on a child site. However, if you have additional
configuration such as client authentication, client IP address insertion, or other SSL-specific requirement, you must add an explicit
GSLB service on the child site and configure it accordingly.
In a parent-child topology, the parent site and the child site can be on different NetScaler software versions. However, to use the
GSLB automaticConfigSync option to synchronize the configuration across the parent sites, all parent sites must be on the same
NetScaler software versions. If you are not using the automaticConfigSync option, then the parent site and the child site can be
on different NetScaler software versions but make sure that you are not using any of the new features in the latest release. T his
is also applicable, in general, to two NetScaler nodes participating in GSLB.
In the diagram, Site P1 and Site P2 are parent sites in a peer relationship. Site P1C1 and P2C1 are the child sites of P1 and P2
respectively.
If you have a firewall configured at a GSLB site, make sure that port 3011 is open.
T he configuration of a child site includes the child site and its parent site, but no other parent or child sites.
Network metrics, such as RT T and persistence session information, are synchronized only across the parent sites.
T herefore, parameters such as nwMetricExchange and sessionExchange are disabled by default on all the child sites.
T o verify correct parent-child configuration, check the states of all the GSLB services bound to the parent sites.
Example
Example
For a complete example of a parent-child configuration, using the command line interface, see Example of a Complete
Parent-Child Configuration, Using the NetScaler CLI.
Note
If the load balancing virtual server IP address is a private IP address and the public IP address is different from this IP address, you
need to configure a GSLB service for the local load balancing virtual server on the child site. T his is required for statistics collection
between the parent and the child site.
add gslb service <name> <private IP/lb vserver IP> http 80 –sitename <childsite name> -publicip <public IP of LB vserver>
Example:
add gslb service Service-GSLB 192.168.1.3 http 80 -GSLB_Site11 site 11_lb1 172.16.1.1
Where 192.168.1.3 is a private IP address of the load balancing virtual server and 172.16.1.1 is a public IP address of the load
balancing virtual server.
Note: T his feature was introduced in NetScaler release 11.1 build 51.x. To use the backup parent site topology, make sure
that the parent site and the child sites are on NetScaler 11.1 build 51.x and later.
T he backup parent site topology is useful in scenarios wherein a large number of child sites are associated with a parent
site. If this parent site goes DOWN, all of its child sites become unavailable. To prevent this, you can now configure a
backup parent site to which the child sites can connect if the original parent site is DOWN. T he parent site sends the
backup parent list to the child sites through the MEP messages.
When a parent site is DOWN, the other parent sites in the GSLB get to know that a particular parent site is DOWN
through MEP because MEP to that parent site is DOWN. T he other parent sites in the GSLB setup look up the backup
When the original parent site is back UP, it tries to establish connections with its child sites that have migrated to a
different parent. When a connection attempt is successful, the child site is reassigned to its original parent site.
Note:
Only parent sites can be configured as backups, and this configuration can only be done at the parent site.
Synchronization is done only on the parent sites. GSLB child sites’ configuration is not affected by synchronization. T his
is because the parent site and the child site configurations are not identical. T he child sites configuration consists only of
its own and its parent site’s details. Also, GSLB services are not always required to be configured in the child sites.
Note: For illustration purposes, the figure shows only one backup parent for each parent site.
T he following list summarizes the behavior of the parent and child sites under various scenarios:
Scenario 2: Only the MEP connection between SiteP1 and SiteP2 has gone DOWN. Child_site1 rejects SiteP2's
connection request, because its parent, SiteP1, is still UP.
Scenario 3: SiteP3 and Child_Site1 detect that SiteP1 is DOWN, and the MEP connection between SiteP3 and SiteP2 is
also DOWN. However, Site P2 detects that SiteP1 is UP, and the MEP connection between SiteP1 and SiteP2 is UP.
SiteP2 does not take any action.
SiteP3 checks SiteP1’s backup list and finds that SiteP2 has a higher preference than SiteP3. But SiteP2 is DOWN, so
SiteP3 tries to establish a connection with Child_site1. Child_site1 has detected that SiteP1 is DOWN, so it accepts
SiteP3's connection request.
Now the connection between SiteP1 and SiteP2 goes DOWN. SiteP2 checks SiteP1’s backup list and finds itself as
the most preferred backup, so it tries to connect to Child_site1. Child_site1 evaluates the new connection request
based on SiteP1’s list and finds SiteP2 as the most preferred backup, so it migrates to SiteP2 from SiteP3.
To configure a backup parent site by using the command line interf ace
Note:
You cannot add a new site as a backup parent. You must first add all the sites, and then configure the site as a backup
parent.
T o remove a backup parent, you must use the unset command, which unsets all the sites that were previously configured
as backup parent sites.
1. Navigate to Conf iguration > Traf f ic Management > GSLB > Sites.
2. Add a new site or select an existing site.
3. Choose the Backup Parent Sites option box while creating or configuring the GSLB site.
GSLB Sites
GSLB Services
GSLB Virtual Servers
Load Balancing or Content Switching Virtual Servers
ADNS Services
DNS VIPs
GSLB Sites
A typical GSLB setup consists of data centers, each of which has various network appliances that may or may not be
NetScaler appliances. T he data centers are called GSLB sites. Each GSLB site is managed by a NetScaler appliance that is
local to that site. Each of these appliances treats its own site as the local site and all other sites, managed by other
appliances, as remote sites.
If the appliance that manages a site is the only NetScaler appliance in that data center, the GSLB site hosted on that
appliance acts as a bookkeeping placeholder for auditing purposes, because no metrics can be collected. Typically, this
happens when the appliance is used only for GSLB, and other products in the data center are used for load balancing or
content switching.
T he concept of sites is central to NetScaler GSLB implementations. Unless otherwise specified, sites form a peer
relationship among themselves. T his relationship is used first to exchange health information and then to distribute load as
determined by the selected algorithm. In many situations, however, a peer relationship among all GSLB sites is not desirable.
Reasons for not having an all-peer implementation could be;
T o clearly separate GSLB sites. For example, to separate sites that participate in resolving DNS queries from the traffic
management sites.
T o reduce the volume of Metric Exchange Protocol (MEP) traffic, which increases exponentially with an increasing
number of peer sites.
T hese goals can be achieved by using parent and child GSLB sites.
GSLB Services
A GSLB service is usually a representation of a load balancing or content switching virtual server, although it can represent
any type of virtual server. T he GSLB service identifies the virtual server’s IP address, port number, and service type. GSLB
services are bound to GSLB virtual servers on the NetScaler appliances managing the GSLB sites. A GSLB service bound to a
GSLB virtual server in the same data center is local to the GSLB virtual server. A GSLB service bound to a GSLB virtual server in
a different data center is remote from that GSLB virtual server.
Note
A GSLB virtual server has one or more GSLB services bound to it, and load balances traffic among those services. It evaluates
the configured GSLB methods (algorithms) to select the appropriate service to which to send a client request. Because the
GSLB services can represent either local or remote servers, selecting the optimal GSLB service for a request has the effect
of selecting the data center that should serve the client request.
T he domain for which global server load balancing is configured must be bound to the GSLB virtual server, because one or
more services bound to the virtual server will serve requests made for that domain.
Unlike other virtual servers configured on a NetScaler appliance, a GSLB virtual server does not have its own virtual IP
address (VIP).
A load balancing or content switching virtual server represents one or many physical servers on the local network. Clients
send their requests to the load balancing or content switching virtual server’s virtual IP (VIP) address, and the virtual server
balances the load across the physical servers. After a GSLB virtual server selects a GSLB service representing either a local or
a remote load balancing or content switching virtual server, the client sends the request to that virtual server’s VIP address.
For more information about load balancing or content switching virtual servers and services, see Load Balancing or Content
Switching.
ADNS Services
An ADNS service is a special kind of service that responds only to DNS requests for domains for which the NetScaler
appliance is authoritative. When an ADNS service is configured, the appliance owns that IP address and advertises it. Upon
reception of a DNS request by an ADNS service, the appliance checks for a GSLB virtual server bound to that domain. If a
GSLB virtual server is bound to the domain, it is queried for the best IP address to which to send the DNS response.
DNS VIPs
A DNS virtual IP is a virtual IP (VIP) address that represents a load balancing DNS virtual server on the NetScaler appliance.
DNS requests for domains for which the NetScaler appliance is authoritative can be sent to a DNS VIP.
GSLB methods are algorithms that the GSLB virtual server uses to select the best-performing GSLB service. After the host
name in the Web address is resolved, the client sends traffic directly to the resolved service IP address.
For GSLB methods to work with a remote site, either MEP must be enabled or explicit monitors must be bound to the
remote services. If MEP is disabled, RT T, Least Connections, Least Bandwidth, Least Packets and Least Response T ime
methods default to Round Robin.
Specif ying a GSLB Method Other than Static Proximity or Dynamic (RTT)
Updated: 2013-11-11
For information about the Round Robin, Least Connections, Least Response T ime, Least Bandwidth, Least Packets, Source
IP Hash, or Custom Load method, see "Load Balancing."
To change the GSLB method by using the command line interface
At the command prompt, type:
Round Robin: When a GSLB virtual server is configured to use the round robin method, it continuously rotates a list of
the services that are bound to it. When the virtual server receives a request, it assigns the connection to the first service
in the list, and then moves that service to the bottom of the list.
Least Response Time: When the GSLB virtual server is configured to use the least response time method, it selects the
service with the fewest active connections and the lowest average response time. You can configure this method for
HT T P and Secure Sockets Layer (SSL) services only. T he response time (also called T ime to First Byte, or T T FB) is the time
interval between sending a request packet to a service and receiving the first response packet from the service. T he
NetScaler appliance uses response code 200 to calculate T T FB.
Least Connections: When a GSLB virtual server is configured to use the least connection GSLB algorithm (or method), it
selects the service with the fewest active connections. T his is the default method, because, in most circumstances, it
provides the best performance.
Least Bandwidth: A GSLB virtual server configured to use the least bandwidth method selects the service that is
currently serving the least amount of traffic, measured in megabits per second (Mbps). T he following example shows
how the virtual server selects a service for GSLB by using the least bandwidth method.
Least Packets: A GSLB virtual server configured to use the least packets method selects the service that has received
the fewest packets in the last 14 seconds.
Source IP Hash: A GSLB virtual server configured to use the source IP hash method uses the hashed value of the client
IPv4 or IPv6 address to select a service. T o direct all requests from source IP addresses that belong to a particular
network to a specific destination server, you must mask the source IP address. For IPv4 addresses, use the netMask
parameter. For IPv6 addresses, use the v6NetMaskLength parameter.
Custom Load: Custom load balancing is performed on server parameters such as CPU usage, memory, and response time.
When using the custom load method, the NetScaler appliance usually selects a service that is not handling any active
transactions. If all of the services in the GSLB setup are handling active transactions, the appliance selects the service
with the smallest load. A special type of monitor, known as a load monitor, calculates the load on each service in the
network. T he load monitors do not mark the state of a service, but they do take services out of the GSLB decision when
those services are not UP.
If two or more GSLB sites at different geographic locations serve the same content, the NetScaler appliance maintains a
database of IP address ranges and uses the database for decisions about the GSLB sites to which to direct incoming client
requests.
For the static proximity method to work, you must either configure the NetScaler appliance to use an existing static
proximity database populated through a location file or add custom entries to the static proximity database. After adding
custom entries, you can set their location qualifiers. After configuring the database, you are ready to specify static
proximity as the GSLB method.
For details about configuring static proximity, see Configuring Static Proximity.
When a client’s DNS request for a domain comes to the NetScaler appliance configured as the authoritative DNS for that
domain, the appliance uses the RT T value to select the IP address of the best performing site to send it as a response to
the DNS request.
T he NetScaler appliance uses different mechanisms, such as ICMP echo request / reply (PING), UDP, and TCP to gather the
RT T metrics for connections between the local DNS server and participating sites. T he appliance first sends a ping probe to
determine the RT T. If the ping probe fails, a DNS UDP probe is used. If that probe also fails, the appliance uses a DNS TCP
probe.
T hese mechanisms are represented on the Netscaler appliance as Load Balancing Monitors and are easily identified due to
their use of the "ldns" prefix. T he three monitors, in their default order, are:
ldns-ping
ldns-dns
ldns-tcp
T hese monitors are built in to the appliance and are set to safe defaults, but may be customized just like any other monitor
on the appliance.
T he default order may also be changed by setting it explicitly as a GSLB parameter. For example, to set the order to be the
DNS UDP query followed by the PING and then TCP, type the following command:
Unless they have been customized, the NetScaler appliance performs UDP and TCP probing on port 53, however unlike
regular load balancing monitors the probes need not be successful in order to provide valid RT T information. ICMP port
unavailable messages, TCP Resets and DNS error responses, which would usually constitute a failure are all acceptable for
calculating the RT T value.
Once the RT T data has been compiled, the Netscaler uses the proprietary metrics exchange protocol (MEP) to exchange
RT T values between participating sites. After calculating RT T metrics, the appliance sorts the RT T values to identify the
data center with the best (smallest) RT T metric."
If RT T information is not available (for example, when a client’s local DNS server accesses the site for the first time), the
NetScaler appliance selects a site by using the round robin method and directs the client to the site.
To configure the dynamic method, you configure the site’s GSLB virtual server for dynamic RT T. You can also set the interval
at which local DNS servers are probed to a value other than the default.
Updated: 2014-11-24
To configure a GSLB virtual server for dynamic RT T, you specify the RT T load balancing method.
T he NetScaler appliance regularly validates the timing information for a given local server. If a change in latency exceeds the
configured tolerance factor, the appliance updates its database with the new timing information and sends the new value
to other GSLB sites by performing a MEP exchange. T he default tolerance factor is 5 milliseconds (ms).
T he RT T tolerance factor must be the same throughout the GSLB domain. If you change it for a site, you must configure
identical RT T tolerance factors on all NetScaler appliances deployed in the GSLB domain.
To configure a GSLB virtual server for dynamic RTT by using the command line
interface
At the command prompt, type:
Updated: 2014-11-24
T he NetScaler appliance uses different mechanisms, such as ICMP echo request / reply (PING), TCP, and UDP to obtain RT T
metrics for connections between the local DNS server and participating GSLB sites. By default, the appliance uses a ping
monitor and probes the local DNS server every 5 seconds. T he appliance then waits 2 seconds for the response and, if a
response is not received in that time, it uses the TCP DNS monitor for probing.
However, you can modify the time interval for probing the local DNS server to accommodate your configuration.
set lb monitor <monitorName> <type> -interval <integer> <units> -resptimeout <integer> <units>
Example
T he static proximity database can be created in the default format or in a format derived from commercially configured
third party databases (such as www.maxmind.com and www.ip2location.com).
T he NetScaler ADC includes an IP geolocation database, GeoLite2 (published by MaxMind). T he database is available in a
format supported by NetScaler ADC at: /var/netscaler/inbuilt_db/Citrix_Netscaler_InBuilt_GeoIP_DB.csv. You can use
this IP geolocation database as the location file for the static proximity based GSLB method or in location based policies.
T hese databases vary in the details they provide. T here is no strict enforcement of the database file format, except that
the default file has format tags. T he database files are ASCII files that use a comma as the field delimiter. T here are
differences in the structure of fields and the representation of IP addresses in the locations.
T he format parameter describes the structure of the file to the NetScaler appliance. Specifying an incorrect value for the
format option can corrupt the internal data.
Note: T he default location of the database file is /var/netscaler/locdb, and on a high availability (HA) setup, an identical
copy of the file must be present in the same location on both NetScaler appliances.
T he following abbreviations are used in this section:
CSHN. Short name of a country based on the country code standard of ISO-3166.
LCN. Long name of the country.
RC. Region code based on ISO-3166-2 (for US and Canada). T he region code “FIPS-10-4” is used for the other regions.
Note: Some databases provide short country names according to ISO-3166 and long country names as well. T he NetScaler
uses short names when storing and matching qualifiers.
To create a static proximity database, log on to the UNIX shell of the NetScaler appliance and use an editor to create a file
with the location details in one of the NetScaler-supported formats.
To add a static location file by using the command line interf ace
Example
You can view an imported location file database by using the View Database dialog box in the configuration utility. T here is
no NetScaler command line equivalent.
By default, when you add a location file, it is saved in the netscaler format. You can convert a location file of other formats
into the netscaler format.
Note: T he nsmap option can be accessed only from the command line interface. T he conversion is possible only into the
netscaler format.
To convert the static database format, at the NetScaler command prompt, type the following command:
At the command prompt, type the following commands to add a custom entry to the static proximity database and verify
the configuration:
add location < IPfrom> < IPto> <preferredLocation> [-longitude <integer>[-latitude <integer>]]
show location
Example
IPf rom
First IP address in the range, in dotted decimal notation. T his is a mandatory argument.
IPto
Last IP address in the range, in dotted decimal notation. T his is a mandatory argument.
pref erredLocation
String of qualifiers, in dotted notation, describing the geographical location of the IP address range. Each qualifier is more
specific than the one that precedes it, as in continent.country.region.city.isp.organization. For example,"NA.US.CA.San
Jose.AT T .citrix".
Note: A qualifier that includes a dot (.) or space ( ) must be enclosed in double quotation marks.
T his is a mandatory argument. Maximum Length: 197
longitude
Numerical value, in degrees, specifying the longitude of the geographical location of the IP address-range.
Note: Longitude and latitude parameters are used for selecting a service with the static proximity GSLB method. If they are
not specified, selection is based on the qualifiers specified for the location.
Maximum value: 180
latitude
Numerical value, in degrees, specifying the latitude of the geographical location of the IP address-range.
Note: Longitude and latitude parameters are used for selecting a service with the static proximity GSLB method. If they are
not specified, selection is based on the qualifiers specified for the location.
Maximum value: 180
Navigate to AppExpert > Location, click the Custom Entries tab, and add the custom entries.
If the geographic context is set with no Continent qualifier, Continent is derived from Country. Even the built-in qualifier
labels are based on the context, and the labels can be changed. T hese qualifier labels specify the locations mapped with
the IP addresses used to make static proximity decisions.
To perform a static proximity-based decision, the NetScaler appliance compares the location attributes (qualifiers) derived
from the IP address of the local DNS server resolver with the location attributes of the participating sites. If only one site
matches, the appliance returns the IP address of that site. If there are multiple matches, the site selected is the result of a
round robin on the matching GSLB sites. If there is no match, the site selected is a result of a round robin on all configured
sites. A site that does not have any qualifiers is considered a match.
To set the location qualifiers by using the command line interf ace
set locationparameter -context <context> -q1label <string> [-q2label <string>] [-q3label <string>] [-q4label <string>] [-
q5label <string>] [-q6label <string>]
Example
At the command prompt, type the following commands to configure static proximity and verify the configuration:
Example
1. Navigate to T raffic Management > GSLB > Virtual Servers and double-click the virtual server.
2. Click the Method section and from the Choose Method drop-down list, select STATICPROXIMITY.
Synchronizing GSLB static proximity databases synchronizes the files in the /var/netscaler/locdb directory across the slave
nodes. During the synchronization process, the master node fetches the running configuration from each of the slave
nodes and compares it to the configuration on the master node. T he master GSLB node uses the rsync program to
synchronize the static proximity database across the slave nodes. To speed up the synchronization process, the rsync
program makes only enough changes to eliminate the differences between the two files. T he synchronization process
cannot be rolled back.
T he following example synchronizes Site2, which is a slave site, to master site Site1. T he administrator enters the sync gslb
config command on Site1:
An RPC node is created automatically when a GSLB site is created, and is assigned an internally generated user name and
password. T he NetScaler appliance uses this user name and password to authenticate itself to remote GSLB sites during
connection establishment. No configuration steps are necessary for an RPC node, but you can specify a password of your
choice, enhance security by encrypting the information that GSLB sites exchange, and specify a source IP address for the
RPC node.
T he appliance needs a NetScaler-owned IP address to use as the source IP address when communicating with other GSLB
sites. By default, the RPC nodes use a subnet IP (SNIP) address but you might want to specify an IP address of your choice.
T he following topics describe the behavior and configuration of RPC nodes on the NetScaler appliance:
Updated: 2014-11-21
You can secure the communication between sites in your GSLB setup by changing the password of each RPC node. After
you change the password for the RPC node of the local site, you must manually propagate the change to the RPC node at
each of the remote sites.
T he password is stored in encrypted form. You can verify that the password has changed by using the show rpcNode
command to compare the encrypted form of the password before and after the change.
To change the password of an RPC node by using the command line interface
At the command line, type the following commands to change the password of an RPC node:
Example
To unset the password of an RPC node by using the command line interface
To unset the password of an RPC node by using the NetScaler command line, type the unset rpcNode command, the IP
address of the RPC node, and the password parameter, without a value.
Updated: 2014-11-24
You can secure the information that is exchanged between GSLB sites by setting the secure option for the RPC nodes in
the GSLB setup. With the secure option set, the NetScaler appliance encrypts all communication sent from the node to
other RPC nodes.
To encrypt the exchange of site metrics by using the command line interface
At the command prompt, type the following commands to encrypt the exchange of site metrics and verify the
configuration:
Example
To encrypt the exchange of site metrics by using the NetScaler configuration utility
1. Navigate to System > Network > RPC and double-click a RPC node.
2. Select the Secure option, and click OK.
By default, the NetScaler appliance uses a NetScaler-owned subnet IP (SNIP) address as the source IP address for an RPC
node, but you can configure the appliance to use a specific SNIP address. If a SNIP address is not available, the GSLB site
cannot communicate with other sites. In such a scenario, you must configure either the NetScaler IP (NSIP) address or a
virtual IP (VIP) address as the source IP address for an RPC node. A VIP address can be used as the source IP address of an
RPC node only if the RPC node is a remote node. If you configure a VIP address as the source IP address and remove the
VIP address, the appliance uses a SNIP address.
Note
From NetScaler 11.0.64.x release onwards, you can configure the appliance to use GSLB Site IP address as the source IP address for
an RPC node.
To specify a source IP address for an RPC node by using the command line
interface
At the command prompt, type the following commands to change the source IP address for an RPC node and verify the
configuration:
Example
To unset the source IP address parameter by using the command line interface
To unset the source IP address parameter by using the NetScaler command line, type the unset rpcNodecommand, the IP
address of the RPC node, and the srcIP parameter, without a value.
MEP is required for health checking of data centers to ensure their availability. A connection for exchanging network metric
(round-trip time) can be initiated by either of the data centers involved in the exchange, but a connection for exchanging
site metrics is always initiated by the data center with the lower IP address. By default, the data center uses a subnet IP
address (SNIP) to establish a connection to the IP address of a different data center. However, you can configure a
specific SNIP, virtual IP (VIP) address, or the NetScaler IP (NSIP) address, as the source IP address for metrics exchange. T he
communication process between GSLB sites uses T CP port 3011 or 3009, so this port must be open on firewalls that are
between the NetScaler appliances.
Note: You cannot configure a GSLB site IP address as the source IP address for site metrics exchange.
If the source and target sites (the site that initiates a MEP connection and the site that receives the connection request,
respectively) have both private and public IP addresses configured, the sites exchange MEP information by using the public
IP addresses.
You can also bind monitors to check the health of remote services as described in "Monitoring GSLB Services." When
monitors are bound, metric exchange does not control the state of the remote service. If a monitor is bound to a remote
service and metric exchange is enabled, the monitor controls the health status. Binding the monitors to the remote service
enables the NetScaler appilance to interact with a non-NetScaler load balancing device. T he NetScaler can monitor non-
NetScaler devices but cannot perform load balancing on them unless monitors are bound to all GSLB services and only
static load balancing methods (such as the round robin, static proximity, or hash-based methods) are used.
With NetScaler release 11.1.51.x or later, to avoid unnecessary disruption of services, you can set a time delay for marking
GSLB services as DOWN when a MEP connection goes DOWN.
Site metrics exchanged between the GSLB sites include the status of each load balancing, or content switching virtual
server, the current number of connections, the current packet rate, and current bandwidth usage information.
T he NetScaler appliance needs this information to perform load balancing between the sites. T he site metric exchange
interval is 1 second. A remote GSLB service must be bound to a local GSLB virtual server to enable the exchange of site
metrics with the remote service.
To enable or disable site metrics exchange by using the command line interface
At a command prompt, type the following commands to enable or disable site metric exchange and verify the
configuration:
Example
If your GSLB sites use the round-trip time (RT T ) load balancing method, you can enable or disable the exchange of RT T
information about the client's local DNS service. T his information is exchanged every 5 seconds.
For details about changing the GSLB method to a method based on RT T, see "GSLB Methods."
Example
Configuring a time delay f or the GSLB services to be marked as DOWN when a MEP connection goes DOWN
If the status of a MEP connection to a remote site changes to DOWN, the status of every GSLB service on that remote
site is marked as DOWN, although the site might not actually be DOWN.
You can now set a delay to allow some time for reestablishment of the MEP connection before the site is marked as
DOWN. If the MEP connection is back UP before the delay expires, the services are not affected.
For example, if you set the delay 10, the GSLB services are marked as DOWN until the MEP connection has been DOWN
Note: T his delay is applicable only to services not bound to a monitor. T he delay does not affect the trigger monitors.
Example
You can configure NetScaler appliance to provide persistent connections, so that a client transmission to any virtual server
in a group can be directed to a server that has received previous transmissions from the same client.
You can enable or disable the exchange of persistence information at each site. T his information is exchanged once every 5
seconds between NetScaler appliances participating in GSLB.
Example
T his wizard is available in the NetScaler GUI. To access the wizard, navigate to Configuration > Traf fic Management >
GSLB and click Get Started.
You can also access this wizard from the GSLB dashboard. Navigate to Configuration > T raf fic Management > GSLB >
Dashboard and click Configure GSLB.
Important
T his feature is supported in High Availability deployment and not in Admin Partition and Cluster deployments.
Before you begin configuring an active-active site, make sure you have configured a standard load balancing setup for each
server farm or data center.
Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure that:
Local GLSB Sites are configured on all the appliances in the GSLB configuration.
You have enabled management access on all the GSLB Sites in the configuration.
You have configured the firewall to accept the auto synchronization and MEP connections.
T he master and slave NetScaler appliances are running the same NetScaler software versions.
All the NetScaler appliances participating as sites should have the same NetScaler software version (the sites are not in a
master-slave relationship).
T he RPC node password is same across all the GSLB sites in the GSLB configuration.
1. Navigate to Traf f ic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS service or a DNS virtual server for the site, you can do it now.
1. Click View and then click Add.
2. Enter the service name, IP address and select the protocol (ADNS/ADNS_T CP) through which the data is exchanged
with the service.
3. Select Active-Active Site.
4. Enter the fully qualified domain name and specify the time period for which the record must be cached by DNS proxies.
5. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site's configuration must include
all the other sites as remote GSLB sites. T here can be only one local site and all other sites are remote sites.
1. Enter the site details, such as the site name and site IP address.
2. Select either REMOT E or LOCAL site type.
3. Optionally, change the RPC password and, if necessary, secure it.
4. If a monitor is to be bound to the GSLB service, select the condition under which the monitor is to monitor the
service. T his will be effective only after a monitor is bound to the services. T he possible conditions are:
ALWAYS. Monitor the GSLB service at all times.
Before you begin configuring an active-passive site, make sure you have configured a standard load balancing setup for
each server farm or data center.
Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure that:
Local GLSB Sites are configured on all the appliances in the GSLB configuration.
You have enabled management access on all the GSLB Sites in the configuration.
You have configured the firewall to accept the auto synchronization and MEP connections.
T he master and slave NetScaler appliances are running the same NetScaler software versions.
All the NetScaler appliances participating as sites should have the same NetScaler software version (the sites are not in a
master-slave relationship).
T he RPC node password is same across all the GSLB sites in the GSLB configuration.
1. Navigate to Traf f ic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS service or a DNS virtual server for the site, you can do it now.
1. Click View and then click Add.
2. Enter the service name, IP address and select the protocol (ADNS/ADNS_T CP) through which the data is exchanged
with the service.
3. Select Active-Passive Site.
4. Enter the fully qualified domain name and specify the time period for which the record must be cached by DNS proxies.
5. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site's configuration must include
all the other sites as remote GSLB sites. T here can be only one local site and all other sites are remote sites.
Note
For details about configuring GSLB entities of an active-passive GSLB setup for disaster recovery, see Configuring GSLB for Disaster
Recovery.
T he following figure shows the workflow involved in a GSLB parent-child topology configuration.
Before you begin configuring the parent-child topology deployment, make sure you have configured a standard load
balancing setup for each server farm or data center.
Also, for synchronizing the GSLB configuration across the GSLB sites in the deployment, make sure that:
Local GLSB Sites are configured on all the appliances in the GSLB configuration.
You have enabled management access on all the GSLB Sites in the configuration.
You have configured the firewall to accept the auto synchronization and MEP connections.
All the NetScaler appliances participating as sites should have the same NetScaler software version (the sites are not in a
master-slave relationship).
T he RPC node password is same across all the GSLB sites in the GSLB configuration.
1. Navigate to Traf f ic Management > GSLB, and then click Get Started.
2. If you have not configured an ADNS server or a DNS virtual server for the site, you can do it now.
1. Click View and then click Add.
1. Enter the fully qualified domain name and specify the time period for which the record must be cached by DNS proxies.
2. Configure the GSLB sites. Each site must be configured with a local GSLB site, and each site's configuration must include
all the other sites as remote GSLB sites. T here can be only one local site. All other sites are remote sites. If the specified
site IP address is owned by the appliance (for example, a MIP address or SNIP address), the site is a local site. Otherwise,
it is a remote site.
3. Enter the site details, such as the site name and site IP address.
1. Select the site type.
2. Optionally, change the RPC password and, if necessary, secure it.
3. If a monitor is to be bound to the GSLB service, select the condition under which the monitor is to monitor the
service. T his will be effective only after a monitor is bound to the services. T he possible conditions are:
Always. Monitor the GSLB service at all times.
MEP Fails. Monitor the GSLB service only when the exchange of metrics through MEP fails.
MEP Fails and Service is DOWN. Exchange of metrics through MEP is enabled but the status of the service,
updated through metrics exchange, is DOWN.
4. Configure the GSLB services.
1. Enter the service details such as service name, service type, and port number.
2. Associate the service with a site (local or remote) by selecting the GSLB site to which the GSLB service belongs.
3. Select the monitor that must be bound to the service when MEP fails, if required. T he service can be an existing server,
or you can create a new server or a virtual server.
T o associate an existing server, select the server name. T he service IP address is auto-populated.
T o associate a new server, create a server by entering the server IP details and its public IP address and the public
port number.
T o associate a virtual server, select an already existing virtual server or click + and add a new virtual server. T his
vserver is the load balancing vserver to which this GSLB service will be associated. If the public IP address is different
from the server IP, which can happen in a NAT environment, enter the public IP address and the public port number.
5. Configure the GSLB virtual servers.
1. Enter the name of the GSLB virtual server name and select the DNS record type.
2. Click > in the Select Service box and choose the GSLB services to be bound to the GSLB virtual server.
3. Click > in the Domain Binding box to view the domain name that is bound to the GSLB virtual server.
4. Choose the GSLB method for selecting the best-performing GSLB service. T he default values for GSLB method,
backup method, and dynamic weight are automatically populated by default. You can change them if required.
If you choose the Algorithm based method, select the primary and backup methods and also specify the dynamic
weight option.
If you choose the Static Proximity method, select the backup method and the dynamic weight method. Also,
provide the location of the database file by clicking the > icon or add a new location by clicking + in the Select a
location database box.
To configure such a GSLB setup, you must first configure a standard load balancing setup for each server farm or data
center. T his enables you to balance load across the different servers in each server farm. T hen, configure both NetScaler
appliances as authoritative DNS (ADNS) servers. Next, create a GSLB site for each server farm, configure GSLB virtual servers
for each site, create GLSB services, and bind the GSLB services to the GSLB virtual servers. Finally, bind the domain to the
GSLB virtual servers. T he GSLB configurations on the two appliances at the two different sites are identical, although the
load-balancing configurations for each site is specific to that site.
Note: T o configure a GSLB site in a NetScaler cluster setup, see Setting Up GSLB in a Cluster.
Configuring a Standard Load Balancing Setup
Updated: 2013-08-30
A load balancing virtual server balances the load across different physical servers in the data center. T hese servers are
represented as services on the NetScaler appliance, and the services are bound to the load balancing virtual server.
For details on configuring a basic load balancing setup, see Load Balancing.
Note: For the NetScaler to be authoritative, you must also create SOA and NS records. For more information about SOA
and NS records, see "Domain Name System."
To create an ADNS service by using the command line interf ace
At the command prompt, type the following commands to create an ADNS service and verify the configuration:
Example
rm service <name>
Example
rm service Service-ADNS-1
To configure an ADNS service by using the configuration utility
Once GSLB sites are created for a domain, the NetScaler appliance sends client requests to the appropriate GSLB site as
determined by the GSLB algorithms configured.
At the command prompt, type the following commands to create a GSLB site and verify the configuration:
Example
T o modify a GSLB site, use the set gslb site command, which is just like using the add gslb site command, except that you
enter the name of an existing GSLB Site.
T o unset a site parameter, use the unset gslb site command, followed by the siteName value and the name of the
parameter to be reset to its default value.
T o remove a GSLB site, use the rm gslb site command, which accepts only the <name> argument.
To view the statistics of a GSLB site by using the command line interf ace
add gslb service <serviceName> <serverName | IP> <serviceT ype> <port>-siteName <string>
show gslb service <serviceName>
Example
After creating a service group, you can bind it to a virtual server, and you can add services to the group. You can also bind
monitors to the service groups.
In cloud deployments, users are given a domain name as a reference when accessing the load balancing solution for
management purposes. It is recommended that external entities do not use the IP addresses that these domain names
resolve to. Also, the load balancing layers scale up or down based on the load, and the IP addresses are not guaranteed to
be static. T herefore, it is recommended to use the domain name to refer to the load balancing endpoints instead of IP
addresses. T his requires the GSLB services to be referred using the domain name instead of IP addresses and it must
consume all the IP addresses returned for the load balancing layer domain name and have a representation for the same in
GSLB.
To use domain names instead of IP addresses when referring to the load balancing endpoints, you can use the domain
name-based service groups for GSLB.
T he Trigger Monitors option can be used to indicate if the GSLB site must use the monitors always, or use monitors when
metrics exchange protocol (MEP) is DOWN.
T herefore, it is recommended that the Trigger Monitors option on GSLB site entity is set to MEPDOWN. When the Trigger
Monitors option is set to MEPDOWN, the load balancing domain resolution and monitoring ownership lies with the local
GSLB node. When Trigger Monitors option is set to MEPDOWN, the load balancing domain resolution and subsequent
monitoring is done by the local GSLB node of a GSLB service group. T he results are then propagated to all other nodes
participating in GSLB by using the metrics exchange protocol (MEP).
Also, whenever the set of IP addresses associated with a load balancing domain are updated, it is notified through MEP.
Configuring and Managing GSLB Service Groups by using the NetScaler CLI
To add a
add gslb serviceGroup <serviceGroupName>@ <serviceType> [-autoScale ( DISABLED | DNS )] -siteName <string>
GSLB
Example
service
add gslb serviceGroup Service-Group-1 http -siteName Site1 -autoScale DNS
group
To bind a
bind gslb serviceGroup <serviceGroupName> ((<IP>@ <port>) | <serverName>@ | ((-monitorName <string>@
GSLB
Example
service
bind gslb serviceGroup Service-Group-1 203.0.113.2
group to a
bind gslb serviceGroup Service-Group-1 S1 80
virtual
bind gslb serviceGroup Service-Group-1 -monitorName Mon1
server
To unbind a
GSLB unbind gslb serviceGroup <serviceGroupName> ((<IP>@ <port>) | <serverName>@ | -monitorName <string>@)
service Example
group to a unbind gslb serviceGroup Service-Group-1 -monitorName Mon1
virtual
server
To set set gslb serviceGroup <serviceGroupName>@ [(<serverName>@ <port> [-weight <positive_integer>] [-hashId
parameters <positive_integer>] [-publicIP <ip_addr|ipv6_addr|*>] [-publicPort <port>]) | -maxClient <positive_integer> | -cip (
for a GSLB ENABLED | DISABLED ) | <cipHeader> | -cltT imeout <secs> | -svrT imeout <secs> | -maxBandwidth <positive_integer> |
service -monT hreshold <positive_integer> | -downStateFlush ( ENABLED | DISABLED )] [-monitorName <string> -weight
group <positive_integer>] [-healthMonitor ( YES | NO )] [-comment <string>] [-appflowLog ( ENABLED | DISABLED )]
To unset
Operation CLI Command
parameters
unset gslb serviceGroup <serviceGroupName>@ [<serverName>@ <port> [-weight] [-hashId] [-publicIP] [-publicPort]] [-
from a
maxClient] [-cip] [-cltT imeout] [-svrT imeout] [-maxBandwidth] [-monT hreshold] [-appflowLog] [-monitorName] [-weight]
GSLB
[-healthMonitor] [-cipHeader] [-downStateFlush] [-comment]
service
group
To enable a
enable gslb serviceGroup <serviceGroupName>@ [<serverName>@ <port>]
GSLB
Example
service
enable gslb serviceGroup SG1 S1 80
group
To disable disable gslb serviceGroup <serviceGroupName>@ [<serverName>@ <port>] [-delay <secs>] [-graceFul ( YES | NO )]
a GSLB Example
service disable gslb serviceGroup SRG2 S1 80
group Note: T he service group that has to be disabled must be a DBS service group and not an autoscale service group.
To remove
rm gslb serviceGroup <serviceGroupName>
a GSLB
Example
service
rm gslb serviceGroup Service-Group-1
group
To view the
statistics of stat gslb serviceGroup [<serviceGroupName>]
a GSLB Example
service stat gslb serviceGroup Service-Group-1
group
To view the
show gslb serviceGroup [<serviceGroupName> | -includeMembers]
properties
Example
of a GSLB
show gslb serviceGroup SG1
service
show gslb serviceGroup -includeMembers
group
show gslb
When this command is executed, the GSLB service groups are also displayed.
site
show gslb
When this command is executed, the GSLB service groups are be displayed.
vs
stat gslb
When this command is executed, the GSLB service groups statistics are also displayed.
vs
show lb
monitor When this command is executed the GSLB service group bindings are also displayed.
bindings
For deployment scenario and example configuration of GSLB service groups, see the following topics:
Note
A GSLB virtual server protocol requirement is mainly to create a relation between the virtual server and the services that are bound
to the virtual server. T his also keeps CLI/APIs consistent with respect to other types of virtual servers. T he Service Type parameter
on a service or a virtual server is not leveraged while serving the DNS requests. It is instead referenced during site persistence,
monitoring, and for the purpose of doing lookups via MEP.
add gslb vserver <name> <serviceT ype> -ipT ype (IPv4 | IPv6)
show gslb vserver <name>
Example
To view the statistics of a GSLB virtual server by using the command line interface
At the command prompt, type:
Request bytes. T otal number of request bytes received on this service or virtual server.
Response bytes. Number of response bytes received by this service or virtual server.
Current client established connections. Number of client connections in EST ABLISHED state.
Current load on the service. Load on the service (Calculated from the load monitor bound to the service).
T he data of number of requests and responses, and the number of current client and server connections may not be
displayed or may not be synchronized with the data of the corresponding load balancing virtual server.
Basic: Clears the statistics that are specific to the virtual server but retains the statistics that are contributed by the
bound GLSB service.
Full: Clears both the virtual server and the bound GSLB service statistics.
To clear the statistics of a GSLB virtual server by using the command line interface
At the command prompt, type:
To clear the statistics of a GSLB service by using the command line interface
At the command prompt, type:
To clear the statistics of a GSLB virtual server by using the configuration utility
1. Navigate to T raffic Management > GSLB > Virtual Servers.
2. Select the GSLB virtual server and, click Statistics, and then click Clear.
3. From the Clear drop-down list, select Basic or Full, and then click OK.
Updated: 2014-11-21
When you create a GSLB virtual server, it is enabled by default. If you disable it, it cannot process traffic. A disabled GSLB
virtual server is not included in GSLB configuration but is not removed from the NetScaler appliance.
To enable or disable a GSLB virtual server by using the command line interface
At the command prompt, type one of the following commands:
Example
At the command prompt, type the following commands to bind a GSLB service to a GSLB virtual server and verify the
configuration:
Example
1. Navigate to T raffic Management > GSLB > Virtual Servers and double-click a virtual server.
2. Click in the Domains section, and configure a domain and bind the domain.
For details on configuring SOA and NS records, see "Domain Name System".
To bind a domain to a GSLB virtual server by using the command line interf ace
At the command prompt, type the following commands to bind a domain to a GSLB virtual server and verify the
configuration:
Example
5. Click Create.
6. Click OK.
To view the statistics of a domain by using the command line interf ace
To view the configuration details of the entities bound to a GSLB domain using the command line
T he NetScaler appliance from which you use the synchronization option is referred to as the 'master node' and the GSLB
sites on which the configuration is copied as 'slave nodes'. When you synchronize a GSLB configuration, the configurations
on all the GSLB sites participating in the GSLB setup are made similar to that on the master node.
Synchronization (may also be referred to as 'auto sync') is carried out in the following manner:
T he master node finds the differences between the configuration of the master node and slave node, and changes the
configuration of the slave node to make it similar to the master node.
If you force a synchronization (use the 'force sync' option), the NetScaler deletes the GSLB configuration from the slave
node and then configures the slave to make it similar to the master node.
During synchronization, if a command fails, synchronization is not aborted and the error message are logged into a .err
file in the /var/netscaler/gslb directory.
Synchronization is done only on the parent sites. GSLB child sites’ configuration is not affected by synchronization. T his
is because the parent site and the child site configurations are not identical. T he child sites configuration consists only of
its own and its parent site’s details. Also, GSLB services are not always required to be configured in the child sites.
If you disable the internal user login, the GSLB auto sync uses the SSH keys to synchronize the configuration. But, to use
GSLB auto sync in partition environment, you need to enable the internal user login and make sure that the partition
username in the local and remote GSLB sites is same.
Note
On the remote GSLB site RPC node, configure the firewall to accept auto-sync connections by specifying the remote site IP
(cluster IP address for cluster setup) and port (3010 for RPC and 3008 for secure RPC). T he source IP address that will be used for
auto-sync is the NSIP of the master node (NSIP of the configuration coordinator in a cluster setup). T he destination IP is the site IP
(remote site IP).
T he source IP address cannot be synchronized across the sites participating in GSLB because the source IP address for a RPC
node is specific to each NetScaler appliance. T herefore, after you force a synchronization (using the sync gslb config -forceSync
command or by selecting the ForceSync option in the NetScaler GUI), you have to manually change the source IP addressess on
the other NetScaler appliances.
Port 22 is also required for synchronizing the database files to the remote site.
If you use the saveconfig option, the sites that participate in the synchronization process automatically save their
configuration, in the following way:
1. T he master node saves its configuration immediately before it initiates the process of synchronization.
2. After the process of synchronization is complete, the slave nodes save their configuration. A slave node saves its
configuration only if the configuration difference was applied successfully on it. If synchronization fails on a slave node,
you must manually investigate the cause of the failure and take corrective action.
On the master node, the names of the remote GSLB sites must be identical to the names of sites configured on the
NetScaler appliances hosting those sites.
During the synchronization, traffic disruptions may occur.
NetScaler can synchronize only up to 80000 lines of the configuration.
Synchronization may fail:
If the spill over method is changed from CONNECT ION to DYNAMIC CONNECT ION.
If you interchange the site prefix of the GSLB services bound to a GSLB virtual server on the master node and then try
to synchronize.
If the RPC node passwords are different for NetScaler IP address (NSIP) and loopback IP address.
If you have configured the GSLB sites as High Availability (HA) pairs, the RPC node passwords of primary and secondary
nodes should be same.
If you rename any GLSB entity that are part of your GSLB configuration (use “show gslb runningConfig” command to
display the GSLB configuration). You need to use the force sync option to synchronize the configuration to other GSLB
sites.
Note: To overcome the limitations due to some settings in the GSLB configuration, you can use the force sync option. But,
if you use the force sync option the GSLB entities are removed and re-added to the configuration and the GSLB statistics
are reset to zero. Hence the traffic is disrupted during the configuration change.
Before you start the synchronization of a GSLB setup, make sure that:
On all the GSLB sites including the master node, management access and SSH should be enabled for the IP address of
the corresponding GSLB site. T he IP address of a GSLB site must be an IP address owned by the NetScaler. For more
information about adding the GSLB site IP addresses and enabling Management Access, see "Configuring a Basic GSLB
Site".
T he GSLB configuration on the NetScaler appliance that is considered as the master node is complete and appropriate
to be copied on all the sites.
If you are synchronizing the GSLB configuration for the first time, all the sites participating in GSLB need to have the
GSLB site entity of their respective local sites.
You are not synchronizing sites that, by design, do not have the same configuration.
At the command prompt, type the following commands to synchronize GSLB sites and verify the configuration:
Example COPY
Gslb_site1[Master]:
Getting Config: ok
Gslb_site2[Slave]:
Getting Config: ok
Comparing config: ok
Applying changes: ok
Done
1. Navigate to Conf iguration > Traf f ic Management > GSLB > Dashboard.
If you attempt to manually synchronize (with the sync gslb config command) a site while it is being autosynchronized, a
"Sync in progress" error message appears. Autosynchronization cannot be triggered for a site that is in the process of being
synchronized manually.
Notes:
All logs related to real-time sync are stored in the /var/netscaler/gslb/periodic_sync.log file.
T he sync status file and default configuration file are stored in the location /var/netscaler/gslb_sync.
Enabling AutomaticConfigSync from default partition of a partitioned appliance is not supported. However, it can be
enabled from all other partitions. T he sync status file and default configuration file are stored in the location
/var/partitions/<partition name>/netscaler/gslb_sync.
It is recommended that all the NetScaler appliances participating as sites have the same NetScaler software version.
T o change the RPC node password, first change the password on the slave site and then on the master site.
Configure local GSLB sites on each site participating in GSLB.
Enable automaticConfigSync on one of the sites where the configuration is performed. T his site eventually gets
synchronized to other GSLB sites.
If there is a new configuration or changes are made to the existing configuration, make sure to check the status using
the “show gslb syncStatus” command to confirm if the changes are synchronized across all sites or if there was any
error.
Example
1. Navigate to Conf iguration > Traf f ic Management > GSLB > Change GSLB Settings.
2. Select Automatic Conf ig Sync.
Note: T his option must be enabled only in the site where the configuration is performed.
You can access the GSLB settings from the dashboard. You can also start the GSLB configuration wizard from the
dashboard. Additionally, you can perform the synchronization and test the GSLB setup from the dashboard.
To access the GSLB dashboard, navigate to Configuration > Traf fic Management > GSLB > Dashboard.
If a metric exchange connection is momentarily lost between any of the participating sites, the remote site is marked as
DOWN and load balancing is performed on the remaining sites that are UP. When metric exchange for a site is DOWN, the
remote services belonging to the site are marked DOWN as well.
T he NetScaler appliance periodically evaluates the state of the remote GSLB services by using either MEP or monitors that
are explicitly bound to the remote services. Binding explicit monitors to local services is not required, because the state of
the local GSLB service is updated by default using the MEP. However, you can bind explicit monitors to a remote service.
When monitors are explicitly bound, the state of the remote service is not controlled by the metric exchange.
By default, when you bind a monitor to a remote GSLB service, the NetScaler appliance uses the state of the service
reported by the monitor. However, you can configure the NetScaler appliance to use monitors to evaluate services in the
following situations:
Always use monitors (default setting).
Use monitors when MEP is DOWN.
Use monitors when remote services and MEP are DOWN.
T he second and third of the above settings enable the NetScaler to stop monitoring when MEP is UP. For example, in a
hierarchical GSLB setup, a GSLB site provides the MEP information about its child sites to its parent site. Such an
intermediate site may evaluate the state of the child site as DOWN because of network issues, though the actual state of
the site is UP. In this case, you can bind monitors to the services of the parent site and disable MEP to determine the actual
state of the remote service. T his option enables you to control the manner in which the states of the remote services are
determined.
To use monitors, first create them, and then bind them to GSLB services.
You can configure a GSLB site to always use monitors (the default), use monitors when MEP is down, or use monitors when
both the remote service and MEP are down. In the latter two cases, the NetScaler appliance stops monitoring when MEP
returns to the UP state.
Example
Updated: 2014-11-24
To add a monitor, you specify the type and the port. You cannot remove a monitor that is bound to a service. You must first
unbind the monitor from the service.
Example
rm lb monitor <monitorName>
To add a monitor by using the configuration utility
Navigate to T raffic Management > Load Balancing > Monitors, and add or delete a monitor.
Updated: 2014-11-24
Once you create monitors, you must bind them to GSLB services. When binding monitors to the services, you can specify a
weight for the monitor. After binding one or more weighted monitors, you can configure a monitor threshold for the
service. T his threshold takes the service down if the sum of the bound monitor weights falls below the threshold value.
Note: In the configuration utility, you can set both the weight and the monitoring threshold at the same time that you
bind the monitor. When using the command line, you must issue a separate command to set the service’s monitoring
threshold.
To bind the monitor to the GSLB service by using the command line interface
At the command prompt, type:
To bind the monitor to the GSLB service by using the configuration utility
1. Navigate to T raffic Management > GSLB > Services.
2. Click the Monit or section and bind the monitor to the GSLB service.
To set the monitoring threshold for a GSLB service by using the configuration
utility
1. Navigate to T raffic Management > GSLB > Services.
2. Click the Monit or T hreshold section and enter a threshold value.
Tip
For information about the GSLB service groups, see Configuring a GSLB Service Group.
Deployment scenario
Two datacenters are deployed in two AWS regions, one in Sydney and one in North Virginia. Another datacenter is
deployed in Azure. An AWS ELB in each AWS region is used to load balance the application servers. ALB is used for Azure to
load balancing the application server. T he NetScaler appliances are configured for GSLB for the ELBs and ALB using GSLB
domain name based autoscale service group.
Important
You must configure the required security groups in AWS and attach it to the GSLB instance. Port 53 must be allowed in the security
group inbound and outbound rules. Also, ports (3009 or 3011 depending on secure MEP configuration) for MEP communication
must be open. For application monitoring, the corresponding ports must be allowed in the security group outbound rules.
T he configuration steps for the above deployment scenario and the corresponding CLI commands are as follows:
2. Add a name server with the DNS gateway IP address where the GSLB node is added. T his must be done in all
datacenters.
4. Add GSLB autoscale service groups for each ELB and ALB and bind each server to the respective service group.
5. Add a GSLB virtual server and bind the application domain and the service groups to this virtual server.
Tip
For information about the GSLB service groups, see Configuring a GSLB Service Group.
Deployment scenario
If there are multiple applications hosted on the same application server, the GSLB should probe these applications to see if
the applications are responding or not. If an application is not responding, the user must be directed to the server on which
the application is UP. Also, if one of the applications is DOWN, then the server should not be marked DOWN, because the
other applications are UP.
In the following example, multiple applications (HT T PS) are hosted on one server in each GSLB site and hence all these
applications resolve to one IP address of the respective site.
Using the GSLB service groups, you can have the same server with an IP address and port bound to multiple service groups
where each service group represents a different application.
An application specific monitor is bound to the service groups that marks the service group as DOWN if the application is
DOWN. T hus, whenever an application is DOWN, only that application is taken out from the setup and not the server.
add gslb serviceGroup app1_site1 HTTP -maxClient 0 -cip DISABLED -cltTimeout 180 -svrTimeout 360 -siteName s1
add gslb serviceGroup app2_site1 HTTP -maxClient 0 -cip DISABLED -cltTimeout 180 -svrTimeout 360 -siteName s1
add gslb serviceGroup app1_site2 HTTP -maxClient 0 -cip DISABLED -cltTimeout 180 -svrTimeout 360 -siteName s2
add gslb serviceGroup app2_site2 HTTP -maxClient 0 -cip DISABLED -cltTimeout 180 -svrTimeout 360 -siteName s2
Configuring Global Server Load Balancing for DNS Queries with NAPT R records
Using the EDNS0 Client Subnet Option for Global Server Load Balancing
You can also configure monitoring for GSLB services to determine their states.
T hese settings depend on your network deployment and the types of clients you expect to connect to your servers.
Updated: 2014-11-26
You can restrict the number of new clients that can simultaneously connect to a load balancing or content switching virtual
server by configuring the maximum number of clients and/or the maximum bandwidth for the GSLB service that represents
the virtual server.
To modify the maximum clients or bandwidth of a GSLB service by using the
command line interface
At the command prompt, type the following command to modify the maximum number of client connections or the
maximum bandwidth of a GSLB service and verify the configuration:
Example
Updated: 2014-11-24
For example, you can have two entries in DNS as ftp.example.com and www.example.com for FT P services and HT T P
services on the same domain, example.com. CNAME-based GSLB services are useful in a multilevel domain resolver
configuration or in multilevel domain load balancing. Configuring a CNAME-based GSLB service can also help if the IP
address of the physical server is likely to change.
If you configure CNAME-based GSLB services for a GSLB domain, when a query is sent for the GSLB domain, the NetScaler
appliance provides a CNAME instead of an IP address. If the A record for this CNAME record is not configured, the client
must query the CNAME domain for the IP address. If the A record for this CNAME record is configured, the NetScaler
provides the CNAME with the corresponding A record (IP address). T he NetScaler appliance handles the final resolution of
the DNS query, as determined by the GSLB method. T he CNAME records can be maintained on a different NetScaler
appliance or on a third-party system.
In an IP-address-based GSLB service, the state of a service is determined by the state of the server that it represents.
However, a CNAME-based GSLB service has its state set to UP by default; the virtual server IP (VIP) address or metric
exchange protocol (MEP) are not used for determining its state. If a desktop-based monitor is bound to a CNAME-based
GSLB service, the state of the service is determined according to the result of the monitor probes.
You can bind a CNAME-based GSLB service only to a GSLB virtual server that has the DNS Record Type as CNAME. Also, a
NetScaler appliance can contain at most one GSLB service with a given CNAME entry.
T he following are some of the features supported for a CNAME-based GSLB service:
GSLB-policy based site affinity is supported, with the CNAME as the preferred location.
Source IP persistence is supported. T he persistency entry contains the CNAME information instead of the IP address
and port of the selected service.
Note: T he Empty-Down-Response feature should be enabled on the GSLB virtual server to which you bind the CNAME-
based GSLB service. If you enable the Empty-Down-Response feature, when a GSLB virtual server is DOWN or disabled, the
response to a DNS query, for the domains bound to this virtual server, contains an empty record without any IP addresses,
instead of an error code.
To create a CNAME-based GSLB service by using the command line interface
At the command prompt, type:
When you configure persistence on a GSLB virtual server to which a service is bound, the service continues to serve requests
from the client even after it is disabled, accepting new requests or connections only to honor persistence. After a
configured period of time, known as the graceful shutdown period, no new requests or connections are directed to the
service, and all of the existing connections are closed.
When disabling a service, you can specify a graceful shutdown period, in seconds, by using the delay argument. During the
graceful shutdown period, if the service is bound to a virtual server, its state appears as Out of Service.
Updated: 2015-06-02
In a typical network, there are servers that have a higher capacity for traffic than others. However, with a regular load
balancing configuration, the load is evenly distributed across all services even though different services represent servers
with different capacities.
To optimize your GSLB resources, you can configure dynamic weights on a GSLB virtual server. T he dynamic weights can be
based on either the total number of services bound to the virtual server or the sum of the weights of the individual services
bound to the virtual server. Traffic distribution is then based on the weights configured for the services.
When dynamic weights are configured on the GSLB virtual server, requests are distributed according to the load balancing
method, the weight of the GSLB service, and the dynamic weight. T he product of the weight of the GSLB service and the
dynamic weight is known as the cumulative weight. T herefore, when dynamic weight is configured on the GSLB virtual
server, requests are distributed on the basis of the load balancing method and the cumulative weight.
When dynamic weight for a virtual server is disabled, the numerical value is set to 1. T his ensures that the cumulative weight
is a non-zero integer at all times.
Dynamic weight can be based on the total number of active services bound to load balancing virtual servers or on the
weights assigned to the services.
Consider a configuration with two GSLB sites configured for a domain and each site has two services that can serve the
client. If a service at either site goes down, the other server in that site has to handle twice as much traffic as a service at
the other site. If dynamic weight is based on the number of active services, the site with both services active has twice the
weight of the site with one service down and therefore receives twice as much traffic.
Alternatively, consider a configuration in which the services at the first site represent servers that are twice as powerful as
servers at the second site. If dynamic weight is based on the weights assigned to the services, twice as much traffic can be
sent to the first site as to the second.
Note: For details on assigning weights to load balancing services, see "Assigning Weights to Services".
As an illustration of how dynamic weight is calculated, consider a GSLB virtual server that has a GSLB service bound to it.
Note: Dynamic weights are not applicable when content switching virtual servers are configured.
To configure a GSLB virtual server to use dynamic weights by using the command
line interface
At the command prompt, type:
T he GSLB virtual server is responsible for DNS-based site persistence, and it controls the site persistence for a remote GSLB
service. T he NetScaler appliance supports persistence based on the source IP address or on HT T P cookies.
When you bring a physical service DOWN with a delay time, the physical service goes into the transition out of service
(T ROFS) state. Site persistence is supported as long as the service is in the T ROFS state. T hat is, if the same client sends a
request for the same service within the specified delay time after a service is marked T ROFS, the same GSLB site (data
center) services the request.
Note: If connection proxy is specified as the site persistence method and if you also want to configure persistence of the
physical servers, do not configure SOURCEIP persistence. When the connection is proxied, an IP address owned by the
NetScaler is used, and not the actual IP address of the client. Configure methods such as cookie persistence or rule-based
persistence on the load balancing virtual server.
Updated: 2014-11-24
With source-IP persistence, when a DNS request is received at a data center, the NetScaler appliance first looks for an
entry in the persistence table and, if an entry for the local DNS server exists and the server mentioned in the entry is
configured, the IP address of that server is sent as the DNS response.
For the first request from a particular client, the NetScaler appliance selects the best GSLB site for the request and sends
its IP address to the client. Since persistence is configured for the source IP address of the client, all subsequent requests
by that client or another local DNS server in the same IP subnet are sent the IP address of the GSLB site that was selected
for the first request.
For source-IP address based persistence, the same set of persistence identifiers must be configured on the GSLB virtual
servers in all data centers. A persistence identifier is a number used by the data centers to identify a particular GSLB virtual
server. A cookie transmits the persistence identifier, enabling the NetScaler appliance to identify the domain so that it can
forward all appropriate requests to the same domain. When persistence is enabled, the persistence information is also
exchanged as part of metrics exchange.
For the NetScaler appliance to support persistence across sites, persistence must be enabled on the GSLB virtual servers of
set gslb vserver <name> -persistenceT ype (SOURCEIP|NONE) -persistenceId <positive_integer> [-persistMask <netmask>] –
[timeout <mins>]
Example
set gslb vserver vserver-GSLB-1 -persistenceType SOURCEIP -persistenceId 23 -persistMask 255.255.255.255 –timeout 2
Updated: 2014-11-26
T he NetScaler appliance provides persistence at the HT T P-request level by using connection proxy and HT T P redirect. With
these persistence methods, the appliance uses an HT T P cookie (known as a “site cookie”) to reconnect the client to the
same server. T he NetScaler inserts the site cookie in the first HT T P response.
T he site cookie contains information about the selected GSLB service on which the client has a persistent connection. T he
cookie expiration is based on the cookie timeout configured on the NetScaler appliance. If the virtual server names are not
identical on all the sites, you must use the persistence identifier. Cookies inserted are compliant with RFC 2109.
When the NetScaler appliance responds to a client DNS request by sending the IP address of the selected GSLB site, the
client sends an HT T P request to that GSLB site. T he physical server in that GSLB site adds a site cookie to the HT T P
header, and connection persistence is in effect.
If the DNS entry in the client cache expires, and then the client sends another DNS query and is directed to a different
GSLB site, the new GSLB site uses the site cookie present in the client request header to implement persistence. If the
GSLB configuration at the new site uses connection-proxy persistence, the new site creates a connection to the GSLB site
that inserted the site cookie, proxies the client request to the original site, receives a response from the original GSLB site,
relays that response back to the client, and closes the connection. If the GSLB configuration uses HT T P redirect
persistence, the new site redirects the request to the site that originally inserted the cookie.
Note: Connection proxy persistence can be configured only for local services. However, connection proxy persistence must
If one of the conditions is not met, connection proxy does not occur, but a site cookie is added if the local GSLB service
has connection proxy enabled AND:
No site cookie is supplied; OR,
T he site cookie refers to an IP address that is not an active GSLB remote service; OR,
T he cookie refers to the IP address of the virtual server on which the request is received.
Note
In a GSLB parent-child configuration, connection proxy works as intended even when a GSLB service is not configured on a child
site. However, if you have additional configuration such as client authentication, client IP address insertion, or other SSL-specific
requirement, you must add an explicit GSLB service on the site and configure it accordingly.
For more information about parent-child topology, see Parent-Child Topology Deployment Using the MEP Protocol.
To set persistence based on HTTP cookies by using the command line interface
At the command prompt, type:
set gslb service <serviceName> -sitePersistence (ConnectionProxy [-sitePrefix <prefix>] | HT T Predirect -sitePrefix <prefix>)
Example
Updated: 2014-11-24
T he state of a virtual server depends on the states of the services bound to it, and the state of each service depends on the monitors bound to
it. If a server is slow or down, the monitoring probes time out and the service that represents the server is marked as DOWN. A virtual server is
marked as DOWN only when all services bound to it are marked as DOWN. You can configure services and virtual servers to either terminate all
connections when they go down, or allow the connections to go through. T he latter setting is for situations in which a service is marked as
DOWN because of a slow server.
When you configure the down state flush option, the NetScaler appliance performs a delayed cleanup of connections to a GSLB service that is
down.
To enable delayed cleanup of virtual server connections by using the command line interface
At the command prompt, type the following commands to configure delayed connection cleanup and verify the configuration:
Example
To enable delayed cleanup of virtual server connections by using the configuration utility
1. Navigate to T raffic Management > GSLB > Services and double-click the service.
2. Click the Ot her Set t ings section and select the Down St at e F lush option.
Updated: 2015-05-22
You can use DNS policies to implement site affinity by directing traffic from the IP address of a local DNS resolver or network to a predefined
target GSLB site. T his is configured by creating DNS policies with DNS expressions and binding the policies globally on the NetScaler appliance.
DNS Expressions
Updated: 2013-07-18
T he NetScaler appliance provides certain predefined DNS expressions that can be used for configuring actions specific to a domain. Such
actions can, for example, drop certain requests, select a specific view for a specific domain, or redirect certain requests to a specific location.
T hese DNS expressions (also called rules) are combined to create DNS policies that are then bound globally on the NetScaler appliance.
T he CLIENT.UDP.DNS.DOMAIN DNS expression can be used with string expressions. If you are using domain names as part of the expression,
they must end with a period (.). For example, CLIENT.UDP.DNS.DOMAIN.ENDSWITH(“abc.com.”)
1. Click the icon next to the Expression text box. Click Add. (Leave the Flow T ype and Protocol drop-down list boxes empty.) Follow these steps
to create a rule.
2. In the Qualifier box, select a qualifier (for example, LOCAT ION).
3. In the Operator box, select an operator (for example, ==).
4. In the Value box, type a value (for example, Asia, Japan....).
5. Click OK. Click Create and click Close. T he rule is created.
6. Click OK.
A DNS policy includes the name of a DNS action to be performed when the policy rule evaluates to TRUE. A DNS action can do one of the
following:
Send the client an IP address for which you have configured a DNS view. For more information about DNS views, see Adding DNS Views.
Send the client the IP address of a GSLB service after referring to a list of preferred locations that overrides static proximity behavior. For
more information about preferred locations, see Overriding Static Proximity Behavior by Configuring Preferred Locations.
Send the client a specific IP address as determined by the evaluation of the DNS query or response (DNS response rewrite).
Forward a request to the name server without performing a lookup in the appliance's DNS cache.
Drop a request.
You cannot create a DNS action for dropping a DNS request or for bypassing the DNS cache on the appliance. If you want to drop a DNS
request, use the built-in action, dns_default_act_Drop. If you want to bypass the DNS cache, use the built-in action,
dns_default_act_Cachebypass. Both actions are available along with custom actions in the Create DNS Policy and the Configure DNS Policy
dialog boxes. T hese built-in actions cannot be modified or removed.
At the command prompt, type the following commands to configure a DNS action and verify the configuration:
add dns action <actionName> <actionT ype> (-IPAddress <ip_addr | ipv6_addr> ... | -viewName <string> | -preferredLocList <string> ...) [-T T L
<secs>]
show dns action [<actionName>]
Examples
Example 1: Configuring DNS Response Rewrit e. T he following DNS action sends the client a preconfigured IP address when the policy to
which the action is bound evaluates to true:
> add dns action dns_act_response_rewrite Rewrite_Response -IPAddress 192.0.2.20 192.0.2.56 198.51.100.10
Done
> show dns action dns_act_response_rewrite
> add dns action send_preferred_location GslbPrefLoc -preferredLocList NA.tx.ns1.*.*.* NA.tx.ns2.*.*.* NA.tx.ns3.*.*.*
Done
> show dns action send_preferred_location
1) ActionName: send_preferred_location ActionType: GslbPrefLoc PreferredLocList: "NA.tx.ns1.*.*.*" "NA.tx.ns2.*.*.*" "NA.tx.ns3.*.*.*"
Done
1. Navigate to T raffic Management > DNS > Actions, create or edit a DNS action.
2. In the Create DNS Action or Configure DNS Action dialog box, set the following parameters:
Action Name (cannot be changed for an existing DNS action)
T ype (cannot be changed for an existing DNS action)
T o set the T ype parameter, do one of the following:
T o create a DNS action that is associated with a DNS view, select View Name. T hen, from the View Name list, select the DNS view that
you want to use in the action.
T o create a DNS action with a preferred location list, select Preferred Location List. In Preferred Location, enter a location, and then
click Add. Add as many DNS locations as you want.
T o configure a DNS action for rewriting a DNS response on the basis of policy evaluation, select Rewrite Response. In IP Address, enter
an IP address, and then click Add. Add as many IP addresses as you want.
T T L (applicable only to the Rewrite Response action type)
DNS policies operate on a location database that uses static and custom IP addresses. T he attributes of the incoming local DNS request are
defined as part of an expression, and the target site is defined as part of a DNS policy. While defining actions and expressions, you can use a
pair of single quotation marks (‘’) as a wildcard qualifier to specify more than one location. When a DNS policy is configured and a GSLB request
is received, the custom IP address database is first queried for an entry that defines the location attributes for the source:
When a DNS query comes from an LDNS, the characteristics of the LDNS are evaluated against the configured policies. If they match, an
appropriate action (site affinity) is executed. If the LDNS characteristics match more than one site, the request is load balanced between the
sites that match the LDNS characteristics.
If the entry is not found in the custom database, the static IP address database is queried for an entry, and if there is a match, the above
policy evaluation is repeated.
If the entry is not found in either the custom or static databases, the best site is selected and sent in the DNS response on the basis of the
configured load balancing method.
DNS policies are global to the NetScaler and cannot be applied to a specific virtual server or domain.
Domain or virtual server specific binding of policy is not supported.
You can use DNS policies to direct clients that match a certain IP address range to a specific site. For example, if you have a GSLB setup with
multiple GSLB sites that are separated geographically, you can direct all clients whose IP address is within a specific range to a particular data
center.
You can configure expressions to evaluate DNS traffic. A DNS expression begins with the DNS.REQ or DNS.RES prefixes. Functions are
available for evaluating the queried domain, the query type, and the carrier protocol. For more information about DNS expressions, see
"Expressions for Evaluating a DNS Message and Identifying Its Carrier Protocol" in "Policy Configuration and Reference".
At the command prompt, type the following commands to create a DNS policy and verify the configuration:
Example
Done
1. Navigate to T raffic Management > DNS > Policies and create a DNS policy.
2. In the Create DNS Policy or Configure DNS Policy dialog box, set the following parameters:
Policy Name (cannot be changed for an existing policy)
Action
Expression
T o specify an expression, do the following:
1. Click Add, and then, in the drop-down box that appears, select the expression element with which you want to begin the expression. A
second list appears. T he list contains a set of expression elements that you can use immediately after the firs expression element.
DNS policies are bound globally on the NetScaler appliance and are available for all configured GSLB virtual servers. Even though DNS policies are
globally bound, policy execution can be limited to a specific GSLB virtual server by specifying the domain in the expression.
Note: Even though the bind dns global command accepts REQ_OVERRIDE and RES_OVERRIDE as valid bind points, those bind points are
redundant, because DNS policies can be bound only globally. Bind your DNS policies only to the REQ_DEFAULT and RES_DEFAULT bind
points.
At the command prompt, type the following commands to bind a DNS policy globally and verify the configuration:
Example
Done
You can configure DNS views to identify various types of clients and provide an appropriate IP address to a group of clients who query for the
same GSLB domain. DNS views are configured by using DNS policies that select the IP addresses sent back to the client.
For example, if you have configured GSLB for your company’s domain and have the server hosted in your company’s network, clients querying
for the domain from within your company’s internal network can be provided with the server’s internal IP address instead of the public IP
address. Clients that query DNS for the domain from the Internet, on the other hand, can be provided the domain's public IP address.
To add a DNS view, you assign it a name of up to 31 characters. T he leading character must be a number or letter. T he following characters are
also allowed: @ _ - . (period) : (colon) # and space ( ). After adding the view, you configure a policy to associate it with clients and a part of the
network, and you bind the policy globally. To configure and bind a DNS policy, see Managing Local DNS Traffic by Using DNS Policies.
Example
For details on how to create a DNS policy and how to bind DNS policies globally, see Managing Local DNS Traffic by Using DNS Policies.
You can configure GSLB for proximity based on the round trip time (RT T ), static proximity, or a combination of the two.
Dynamic round trip time (RT T ) is a measure of time or delay in the network between the client’s local DNS server and a data
resource. To measure dynamic RT T, the NetScaler appliance probes the client’s local DNS server and gathers RT T metric
information. T he NetScaler then uses this metric to make its load balancing decision. Global server load balancing monitors
the real-time status of the network and dynamically directs the client request to the data center with the lowest RT T
value
To configure GSLB for proximity with dynamic method, you must first configure the basic GSLB set up and then configure
dynamic RT T.
First create two GSLB sites, local and remote. T hen, for the local site, create a GSLB virtual server and GSLB services and
bind the services to the virtual server. T hen create ADNS services and bind the domain for which you are configuring GSLB
to the GSLB virtual server at the local site. Finally, create a load balancing virtual server with the same virtual server IP
address as the GSLB service.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Once you have configured a basic GSLB setup, configure the dynamic RT T method.
For details on how to configure the GSLB virtual server to use the dynamic RT T method for load balancing, see Configuring
Dynamic RT T .
T he static proximity method for GSLB uses an IP address-based static proximity database to determine the proximity
between the client’s local DNS server and the GSLB sites. T he NetScaler appliance responds with the IP address of a site
that best matches the proximity criteria.
If two or more GSLB sites at different geographic locations serve the same content, the NetScaler appliance maintains a
database of IP address ranges and uses the database for decisions about the GSLB sites to which to direct incoming client
requests.
To configure GSLB for proximity with static proximity, you must first configure the basic GSLB set up and then configure
static proximity.
First create two GSLB sites, local and remote. T hen, for the local site, create a GSLB virtual server and GSLB services and
bind the services to the virtual server. T hen create ADNS services and bind the domain for which you are configuring GSLB
to the GSLB virtual server at the local site. Finally, create a load balancing virtual server with the same virtual server IP
address as the GSLB service.
Once you have configured a basic GSLB setup, configure static proximity.
For details on how to configure the GSLB virtual server to use static proximity for load balancing, see Configuring Static
Proximity.
You can configure the GSLB virtual server to use a combination of static proximity and dynamic RT T when you have some
clients coming from an internal network like a branch office. You can configure GSLB such that the clients coming from the
branch office or any other internal network are directed to a particular GSLB site that is geographically close to the client
network. For all other requests, you can use dynamic RT T.
First create two GSLB sites, local and remote. T hen, for the local site, create a GSLB virtual server and GSLB services and
bind the services to the virtual server. T hen create ADNS services and bind the domain for which you are configuring GSLB
to the GSLB virtual server at the local site. Finally, create a load balancing virtual server with the same virtual server IP
address as the GSLB service.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Once you have configured a basic GSLB setup, configure the GSLB virtual server to use static proximity for all traffic
originating from an internal network and then use dynamic RT T for all other traffic.
For details on how to configure static proximity, see Configuring Static Proximity and for details on how to configure
dynamic RT T, see Configuring Dynamic RT T .
Configuring a GSLB Virtual Server to Respond with an Empty Address Record When DOWN
Updated: 2015-05-04
Configuring a backup entity for a GSLB virtual server ensures that DNS traffic to a site is not interrupted if the GSLB virtual server
goes down. T he backup entity can be another GSLB virtual server, or it can be a backup IP address. With a backup entity
configured, if the primary GSLB virtual server goes down, the backup entity handles DNS requests. To specify what should happen
when the primary GSLB virtual server comes back up again, you can configure the backup entity to continue handling traffic until
you manually enable the primary virtual server to take over (using the disablePrimaryOnDown option), or you can configure a
timeout period after which the primary takes over.
Note: You can configure a single backup entity as a backup for multiple GSLB virtual server.
If you configure both the timeout and the disablePrimaryOnDown option for the backup entity, the backup session time-out
takes precedence over the disablePrimaryOnDown setting.
To configure a backup GSLB virtual server by using the command line interface
At the command prompt, type the following commands to configure a GSLB virtual server as a backup virtual server and verify the
configuration:
set gslb vserver <name> -backupVServer <name> [-backupSessionT imeout <timeoutValue>] [-disablePrimaryOnDown (ENABLED
| DISABLED)]
show gslb vserver <name>
Example
To set GSLB virtual server as a backup virtual server by using the configuration utility
1. Navigate to T raffic Management > GSLB > Virtual Servers, and double-click the GSLB virtual server.
2. Click the Backup Virt ual Server section and select the backup virtual server.
A typical DNS response contains the IP address of the best performing GSLB service. However, if you enable multiple IP response
(MIR), the NetScaler appliance sends the best GSLB service as the first record in the response and adds the remaining active
services as additional records. If MIR is disabled (the default), the NetScaler appliance sends the best service as the only record in
the response.
To configure a GSLB virtual server for multiple IP responses by using the command line
interface
At the command prompt, type the following commands to configure a GSLB virtual server for multiple IP responses and verify the
configuration:
Example
To set a GSLB virtual server for multiple IP responses by using the configuration utility
1. Navigate to T raffic Management > GSLB > Virtual Servers and double-click the GSLB virtual server for which you want to
configure a backup virtual server (for example, vserver-GSLB-1).
2. On the Advanced tab, under When this VServer is “UP,” select the Send all “active” service IP in response (MIR) check box, and
click OK.
Updated: 2014-11-24
A DNS response can contain either the IP address of the requested domain or an answer stating that the IP address for the
domain is not known by the DNS server, in which case the query is forwarded to another name server. T hese are the only possible
responses to a DNS query.
When a GSLB virtual server is disabled or in a DOWN state, the response to a DNS query for the GSLB domain bound to that
virtual server contains the IP addresses of all the services bound to the virtual server. However, you can configure the GSLB virtual
server to in this case send an empty down response (EDR). When this option is set, a DNS response from a GSLB virtual server that
is in a DOWN state does not contain IP address records, but the response code is successful. T his prevents clients from
attempting to connect to GSLB sites that are down.
Note: You must configure this setting for each virtual server to which you want it to apply.
To configure a GSLB virtual server for empty down responses by using the command
line interface
At the command prompt, type:
To set a GSLB virtual server for empty down responses by using the configuration utility
1. Navigate to T raffic Management > GSLB > Virtual Servers and double-click the GSLB virtual server for which you want to
configure a backup virtual server (for example, vserver-GSLB-1).
2. On the Advanced tab, under When this VServer is “Down,” select the Do not send any service’s IP address in response (EDR)
check box.
3. Click OK.
Updated: 2014-11-24
You can configure a backup site for your GSLB configuration. With this configuration in place, if all of the primary sites go DOWN,
the IP address of the backup site is provided in the DNS response.
Typically, if a GSLB virtual server is active, that virtual server sends a DNS response with one of the active site IP addresses as
selected by the configured GSLB method. If all the configured primary sites in the GSLB virtual server are inactive (in the DOWN
state), the authoritative domain name system (ADNS) server or DNS server sends a DNS response with the backup site’s IP address.
Example
Updated: 2014-11-24
Once the number of connections to a primary GSLB virtual server exceeds the configured threshold value, you can use the spillover
option to divert new connections to a backup GSLB virtual server. T his threshold value can be calculated dynamically or set
manually. Once the number of connections to the primary virtual server drops below the threshold, the primary GSLB virtual server
resumes serving client requests.
You can configure persistence with spillover. When persistence is configured, new clients are diverted to the backup virtual server if
that client is not already connected to a primary virtual server. When persistence is configured, connections that were diverted to
the backup virtual server are not moved back to the primary virtual server after the number of connections to the primary virtual
server drops below the threshold. Instead, the backup virtual server continues to process those connections until they are
If the backup virtual server reaches the configured threshold and is unable to take any additional load, the primary virtual server
diverts all requests to the designated redirect URL. If a redirect URL is not configured on the primary virtual server, subsequent
requests are dropped.
T he spillover feature prevents the remote backup GSLB service (backup GSLB site) from getting flooded with client requests when
the primary GSLB virtual server fails. T his occurs when a monitor is bound to a remote GSLB service, and the service experiences a
failure that causes its state to go DOWN. T he monitor continues to keep the state of the remote GSLB service UP, however,
because of the spillover feature.
As part of the resolution to this problem, two states are maintained for a GSLB service, the primary state and effective state. T he
primary state is the state of the primary virtual server and the effective state is the cumulative state of the virtual servers (primary
and backup chain). T he effective state is set to UP if any of the virtual servers in the chain of virtual servers is UP. A flag that
indicates that the primary VIP has reached the threshold is also provided. T he threshold can be measured by either the number of
connections or the bandwidth.
A service is considered for GSLB only if its primary state is UP. Traffic is directed to the backup GSLB service only when all the
primary virtual servers are DOWN. Typically, such deployments will have only one backup GSLB service.
Adding primary and effective states to a GSLB service has the following effects:
When source IP persistence is configured, the local DNS is directed to the previously selected site only if the primary virtual
server on the selected site is UP and below threshold. Persistence can be ignored in the round robin mode.
If cookie-based persistence is configured, client requests are redirected only when the primary virtual server on the selected site
is UP.
If the primary virtual server has reached its saturation and the backup VIP(s) is absent or down, the effective state is set to
DOWN.
If external monitors are bound to an HT T P-HT T PS virtual server, the monitor decides the primary state.
If there is no backup virtual server to the primary virtual server and the primary virtual server has reached its threshold, the
effective state is set to DOWN.
To configure a backup GSLB virtual server by using the command line interface
At the command prompt, type the following commands to configure a backup GSLB virtual server and verify the configuration:
set gslb vserver <name> -soMethod <method> -soT hreshold <threshold> -soPersistence ( ENABLED | DISABLED ) -
soPersistenceT imeout <timeout>
show gslb vserver <name>
Example
set gslb vserver Vserver-GSLB-1 -soMethod CONNECTION -soThreshold 1000 -soPersistence ENABLED -soPersistenceTimeout 2
show gslb vserver Vserver-GSLB-1
To configure a backup GSLB virtual server by using the configuration utility
1. Navigate to T raffic Management > GSLB > Virtual Servers and double-click the virtual server that you want to configure as a
backup (for example, Vserver-LB-1).
2. Click the SpillOver section and set the following parameters:
Method— soMethod
T hreshold— soT hreshold
Persistence T ime-out (min) — soPersistenceT imeout
Updated: 2014-11-24
A conventional disaster recovery setup includes an active data center and a standby data center. T he standby data center
is a remote site. When a failover occurs as a result of a disaster event that causes the primary active data center to be
inactive, the standby data center becomes operational.
Configuring disaster recovery in an active-standby data-center setup consists of the following tasks.
Create the active data center.
Add a local GSLB site.
Add a GSLB vserver, which represents the active data center.
Bind the domain to the GSLB virtual server.
Add gslb services and bind the services to active GSLB virtual server.
Create the standby data center.
Add a remote gslb site.
Add a gslb vserver, which represents standby data center.
Add gslb services which represents standby data center and bind the services to the standby gslb vserver.
Designate the standby data center by configuring the standby GSLB virtual server as the backup virtual server for the
active GSLB virtual server.
Once you have configured the primary data center, replicate the configuration for the backup data center and designate it
as the standby GSLB site by designating a GSLB virtual server at that site as the backup virtual server.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
To designate the standby GSLB site by using the command line interface
At both the active site and the remote site, at the command prompt, type:
By default, once the primary virtual server becomes active, it starts receiving traffic. However, if you want the traffic to be
directed to the backup virtual server even after the primary virtual server becomes active, use the ‘disable primary on down’
option.
An active-active GSLB deployment, in which both GSLB sites are active, removes any risk that may arise in having a standby
data center. With such a setup, web or application content can be mirrored in geographically separate locations. T his
ensures that data is consistently available at each distributed data center.
To configure GSLB for disaster recovery in an active-active data center set up, you must first configure the basic GSLB
setup on the first data center and then configure all other data centers.
First create at least two GSLB sites. T hen, for the local site, create a GSLB virtual server and GSLB services and bind the
services to the virtual server. T hen create ADNS services and bind the domain for which you are configuring GSLB to the
GSLB virtual server in the local site. Finally, at the local site, create a load balancing virtual server with the same virtual server
IP address as the GSLB service.
Once you have configured the first data center, replicate the configuration for other data centers part of the setup.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Updated: 2014-11-24
When you configure GSLB to use the weighted round robin method, weights are added to the GSLB services and the
configured percentage of incoming traffic is sent to each GSLB site. For example, you can configure your GSLB setup to
forward 80 percent of the traffic to one site and 20 percent of the traffic to another. After you do this, the NetScaler
appliance will send four requests to the first site for each request that it sends to the second.
To set up the weighted round robin method, first create two GSLB sites, local and remote. Next, for the local site create a
GSLB virtual server and GSLB services, and bind the services to the virtual server. Configure the GSLB method as round robin.
Next, create ADNS services and bind the domain for which you are configuring GSLB to the GSLB virtual server. Finally,
create a load balancing virtual server with the same virtual server IP address as the GSLB service.
Each service that represents a physical server in the network has weights associated with it. T herefore the GSLB service is
assigned a dynamic weight that is the sum of weights of all services bound to it. Traffic is then split between the GSLB
services based on the ratio of the dynamic weight of the particular service to the total weight. You can also configure
individual weights for each GSLB service instead of the dynamic weight.
If the services do not have weights associated with them, you can configure the GSLB virtual server to use the number of
services bound to it to calculate the weight dynamically.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Example
To add weights to the GSLB services by using the command line interface
At the command prompt, type:
Updated: 2014-11-24
Data center persistence is required for web applications that require maintaining a connection with the same server instead
of having the requests load balanced. For example, in an e-commerce portal, maintaining a connection between the client
and the same server is critical. For such applications, HT T P redirect persistence can be configured in an active-active setup.
To configure GSLB for disaster recovery with data center persistence, you must first configure the basic GSLB set up and
then configure HT T P redirect persistence.
First create two GSLB sites, local and remote. Next, for the local site, create a GSLB virtual server and GSLB services and
bind the services to the virtual server. Next, create ADNS services and bind the domain for which you are configuring GSLB
to the GSLB virtual server at the local site. Next, create a load balancing virtual server with the same virtual server IP address
as the GSLB service. Finally, duplicate the previous steps for the remote configuration, or configure the NetScaler appliance
to autosynchronize your GSLB configuration.
For details on how to configure a basic GSLB setup, see Configuring GSLB Entities Individually.
Once you have configured a basic GSLB setup, configure HT T P redirect precedence to enable data center persistence.
Example
Note
When site persistence is not configured and if a load balancing virtual server that is configured as a local GSLB service is DOWN, the
HT T P requests are redirected to other healthy GSLB sites using a 302 redirect.
In the DNS action, you can configure a list of up to 8 preferred locations. T he locations must be provided in the dotted
qualifier notation, which is the notation in which you add custom locations to the static proximity database. T he locations
can include wildcards for qualifiers that you want to omit. For information about the dotted qualifier notation for
locations, see Adding Custom Entries to a Static Proximity Database. When entering the preferred locations, you must
enter them in the descending order of priority.
When a policy evaluates to TRUE, the NetScaler appliance matches the preferred locations, in priority order, with the
locations of GSLB services. Matches are of the following two types:
If all the non-wildcard qualifiers in a preferred location match the corresponding qualifiers in the location of a GSLB
service, the match is considered a perfect match. For example, a GSLB service location of *.UK.*.* or Europe.UK.*.* is a
perfect match for the preferred location *.UK.*.*.
If only a subset of the non-wildcard qualifiers match, the match is considered a partial match. For example, a GSLB
service location of Europe.EG is a partial match for the preferred location Europe.UK.
When a DNS policy evaluates to TRUE, the following algorithm is used to select a GSLB service:
1. T he appliance evaluates the preferred location that has the highest priority and moves down the priority order until a
perfect match is found between a preferred location and the location of a GSLB service.
If a perfect match is found, the appliance checks whether the corresponding GSLB service is up. If it is up, it returns the
IP address of the GSLB service in the DNS response. If multiple perfect matches are found (which can happen when one
or more wildcards are used in a preferred location), the appliance checks the state of each of the corresponding GSLB
services and load balances the GSLB services that are up.
2. If a perfect match is not found for any of the preferred locations, the appliance returns to the preferred location that
has the highest priority and moves down the priority order until a partial match is found between a preferred location
and the location of a GSLB service.
If a partial match is found, the appliance checks whether the corresponding GSLB service is up. If it is up, it returns the IP
address of the GSLB service in the DNS response. If multiple partial matches are found, the appliance checks the state
of each of the corresponding GSLB services and load balances the GSLB services that are up.
3. If none of the perfect and partial matches are up, the appliance load balances all other available GSLB services.
In this way, the appliance implements a type of site affinity for traffic that matches the DNS policy.
Restrict the selection of a GSLB service from a subset of GSLB services bound to a GSLB virtual server for the given
domain.
Apply different load balancing methods on the different subsets of GSLB services in the deployment.
Apply spillover policies on a subset of GSLB services, and you cannot have a backup for a subset of GSLB services.
Configure a subset of GSLB services to serve different content. T hat is, you cannot content switch between servers in
different GSLB sites. T he GSLB configuration assumes that the servers contain the same content.
Define a subset GSLB services with different priorities and specify an order in which the services in the subset are applied
to a request.
You can now configure a content switching (CS) policy to customize the GSLB deployment. First configure a set of GSLB
services and bind it to a GSLB virtual server. T hen, configure a CS virtual server of target type GSLB, define a CS policy and
action with the GSLB virtual server as target virtual server, and bind the CS policy to CS virtual server.
Important
Only CS policies with DNS based expressions can be bound to a CS virtual server of target type GSLB.
If a GLSB service is bound to a CS virtual server through a GSLB virtual server, you cannot bind another GSLB virtual server bound
with the same GSLB service to the CS virtual server.
Example
Consider a GLSB deployment that includes two GSLB sites. At each site, four GSLB services (S-1, S-2, S-3, and S-4) are bound
to GSLB virtual server VS-1. You can configure a content switching (CS) virtual server of target type GSLB and define a CS
policy and action with VS-1 as the target virtual server, so that requests for content in English are served only by S-1 and S-
2, and requests for content in the local language are served only by S-3 and S-4.
You could give S-1 priority by configuring a backup virtual server to VS-1 and binding S-2 to the backup virtual server. Client
requests would then be served by S-1 unless the server it represents went down, in which case the requests would be
served by S-2. If both S-1 and S-2 were down, clients would receive an empty response.
To configure GSLB Service Select ion using Cont ent Swit ching:
1. Configure GSLB. For instructions, see Configuring Global Server Load Balancing.
2. Configure a Content Switching (CS) virtual server of target type GSLB. For more information, see Creating Content
Switching Virtual Servers.
3. Configure Content Switching (CS) policies. For more information, see Configuring Content Switching Policies.
4. Configure CS actions that designate a GSLB virtual server as the target virtual server. For more information, see
Configuring a Content Switching Action.
T he following sample configuration sends requests from the client with IP address 5.5.5.5 to SERVICE_GSLB1 and
SERVICE_GSLB2. SERVICE_GSLB1 has a higher priority than SERVICE_GSLB2, and SERVICE_GSLB2 serves the client requests
only when SERVICE_GSLB1 is down. If both SERVICE_GSLB1 and SERVICE_GSLB2 are down, SERVICE_GSLB3 and service-
GSLB4 are not considered, and a blank response is sent to the client.
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
Done
In Telco deployments, you can configure a NetScaler appliance to receive DNS queries with NAPT R records from clients
such as mobile management entities (MMEs), which play the role of a DNS resolver to discover all the services that are
offered by the domain name. T he appliance responds to the query with NAPT R records for all the services that are up. T he
MME can use this NAPT R response to run the S-NAPT R procedure to select the nodes on the basis of the service offered,
colocation, topological closeness, and so on.
If multiple nodes qualify for selection, the MME can use the preference field in the NAPT R record from the NetScaler
appliance to determine the node.
While responding to a DNS query with NAPT R record, a NetScaler appliance constructs a response NAPT R record for each
GSLB service.
Fie ld
TTL T he amount of time for which the NAPT R record can be cached.
Specifies the order in which the NAPT R record MUST be processed. You can specify the order in the GSLB service.
Order
Otherwise, it is set to 1.
Specifies the order in which NAPT R records with equal "order" values SHOULD be processed, low numbers being
Preference
processed before high numbers. If the order is not specified in the GSLB service, it is set to 1.
Controls the aspects of the rewriting and interpretation of the fields in the record. T he NetScaler appliance sets this value
Flags
to A.
For detailed GSLB configuration instructions, see Configuring Global Server Load Balancing (GSLB). Make sure that you do
the following:
Set the following parameters while adding the GSLB virtual server:
serviceT ype: ANY
dnsRecordT ype: NAPT R
lbMethod: CUST OMLOAD
Example
add gslb vserver gslb_vs ANY -dnsRecordType NAPT R -lbMethod CUSTOMLOAD
While adding a GSLB site, set the naptrReplacementSuffix parameter to the domain name that you want to embed in
the NAPT R records.
Example
add gslb site site1 10.102.218.200 -naptrReplacementSuffix example.com
Done
Done
>add gslb service sgw1 3.3.3.13 ANY * -siteName site1 -naptrreplacement sgw1.site1. -naptrOrder 2 -naptrServices x-3gpp-sgw:x-s5-gtp -naptrD
Done
>add gslb service sgw2 3.3.3.11 ANY * -siteName site1 -naptrreplacement sgw2.site1. -naptrOrder 5 -naptrServices x-3gpp-sgw:x-s5-gtp -naptr
Done
>add gslb service sgw3 3.3.3.12 ANY * -siteName site2 -naptrreplacement sgw3.site1. -naptrOrder 10 -naptrServices x-3gpp-sgw:x-s5-gtp -nap
Done
Done
Done
Done
Done
Done
Done
Note
NetScaler supports only EDNS0.
Important
Make sure that the LDNS in your deployment supports EDNS0 Client Subnet so that the incoming DNS queries contains the EDNS0
Client Subnet option and the NetScaler appliance uses the ECS address while processing the DNS query.
In a typical GSLB deployment, when you use proximity-based load balancing methods like static proximity or dynamic round-
trip time (RT T ), the NetScaler appliance uses the local DNS (LDNS) IP address for determining the topological closeness of
the client and performs GSLB accordingly. But when a centralized DNS resolver, such as Google DNS or OpenDNS, is
involved in the deployment, the NetScaler appliance sends the DNS request to a datacenter close to the centralized DNS
resolver, which might not be close to the client. For example, in a typical NetScaler GSLB deployment using the static
proximity load balancing method, an end-user request from Japan is sent to a datacenter in Japan and an end user request
from California is sent to a datacenter in California. But if a centralized DNS resolver is involved, the NetScaler appliance
might send a request from Japan to a datacenter in California.
You can use the ECS option in deployments that include the NetScaler appliance configured as Authoritative DNS (ADNS)
server for a GSLB domain. If you use static proximity as the load balancing method, you can use the IP subnet in the EDNS
header instead of the LDNS IP address to determine the geographical proximity of the client. In the case of proxy mode
deployment, the NetScaler appliance forwards an ECS-enabled DNS query as-is to the back-end servers, and the appliance
does not cache ECS-enabled DNS responses.
Note
T he ECS option is not applicable for all other deployment modes, such as ADNS mode for non-GSLB domains, resolver mode, and
forwarder mode. In all these modes, the ECS option is ignored by NetScaler. Also, by default, ECS is disabled for GSLB deployment.
You can configure a GSLB virtual server to verify that the address returned by the EDNS0 Client Subnet (ECS) option of the
DNS query is not a private or an unroutable IP address. With address validation enabled, the NetScaler appliance ignores the
ECS address in the DNS query if it is listed in the following table, and instead uses the LDNS IP address for global server load
Note
By default, address validation is disabled.
192.0.0.0/24 Used for IET F protocol assignments, includes the private space
192.168.0.0/16
2001::/32 T EREDO
2001:10::/28 ORCHID
fc00::/7 Unique-local
To enable address validat ion by using t he command line int erf ace:
add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site2
add gslb service site1_child1_http_gsvc1 10.102.82.132 HTTP 80 -publicIP 10.102.82.132 -publicPort 80 -maxClient 0 -siteName site1_child1 -cl
add gslb service site1_child2_http_gsvc1 10.102.82.68 HTTP 80 -publicIP 10.102.82.68 -publicPort 80 -maxClient 0 -siteName site1_child2 -cltTi
add gslb service site2_child1_http_gsvc1 10.106.24.134 HTTP 80 -publicIP 10.106.24.134 -publicPort 80 -maxClient 0 -siteName site2_child1 -cl
add gslb service site2_child2_http_gsvc1 10.106.24.68 HTTP 80 -publicIP 10.106.24.68 -publicPort 80 -maxClient 0 -siteName site2_child2 -cltTi
add gslb vserver gv1 HTTP -backupLBMethod ROUNDROBIN -tolerance 0 -appflowLog DISABLED
add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
You can add the following commands for load balancing configuration:
add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0 -cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 18
add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
You can add the following commands for load balancing configuration:
add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0 -cip DISABLED -usip NO -useproxyport YES -sp OFF -cltTimeout 1
add gslb site site1_child1 10.102.82.131 -publicIP 10.102.82.131 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
add gslb site site1_child2 10.102.82.67 -publicIP 10.102.82.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site1
add gslb site site2_child1 10.106.24.132 -publicIP 10.106.24.132 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site2
add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site2
add gslb service site1_child1_http_gsvc1 10.102.82.132 HTTP 80 -publicIP 10.102.82.132 -publicPort 80 -maxClient 0 -siteName site1_child1 -cl
add gslb service site1_child2_http_gsvc1 10.102.82.68 HTTP 80 -publicIP 10.102.82.68 -publicPort 80 -maxClient 0 -siteName site1_child2 -cltTi
add gslb service site2_child1_http_gsvc1 10.106.24.134 HTTP 80 -publicIP 10.106.24.134 -publicPort 80 -maxClient 0 -siteName site2_child1 -cl
add gslb service site2_child2_http_gsvc1 10.106.24.68 HTTP 80 -publicIP 10.106.24.68 -publicPort 80 -maxClient 0 -siteName site2_child2 -cltTi
add gslb vserver gv1 HTTP -backupLBMethod ROUNDROBIN -tolerance 0 -appflowLog DISABLED
add gslb site site2_child1 10.106.24.132 -publicIP 10.106.24.132 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site2
You can add the following commands for load balancing configuration:
add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0 -cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 18
add gslb site site2_child2 10.106.24.67 -publicIP 10.106.24.67 -nwMetricExchange DISABLED -sessionExchange DISABLED -parentSite site2
You can add the following commands for load balancing configuration:
add service svc1 10.102.82.25 HTTP 80 -gslb NONE -maxClient 0 -maxReq 0 -cip DISABLED -usip NO -useproxyport YES -sp ON -cltTimeout 18
To configure link load balancing, many users begin by configuring a basic setup with default settings. Configuring a basic
setup involves configuring services, virtual servers, monitors, routes, an LLB method, and, optionally, configuring persistence.
Once a basic setup is operational, you can customize it for your environment.
Load balancing methods that are applicable to LLB are round robin, destination IP hash, least bandwidth, and least packets.
You can optionally configure persistence for connections to be sustained on a specific link. T he available persistence types
are source IP address-based, destination IP address-based, and source IP and destination IP address-based. PING is the
default monitor but configuring a transparent monitor is recommended.
You can customize your setup by configuring reverse NAT (RNAT ) and backup links.
Updated: 2014-10-27
A default monitor (PING) is automatically bound to a service type of ANY when the service is created, but you can replace
the default monitor with a transparent monitor, as described in "Creating and Binding a T ransparent Monitor."
To create a service by using the command line interface
At the command prompt, type:
Example
4. Click Create.
5. Repeat Steps 2-4 to create another service.
6. Click Close.
7. In the Services pane, select the services that you just configured and verify that the settings displayed at the bottom of
the screen are correct.
Updated: 2014-10-28
After you create a service, create a virtual server and bind services to the virtual server. T he default LB method of least
connections is not supported in LLB. For information about changing the LB method, see "Configuring the LLB Method and
Persistence."
To create a link load balancing virtual server and bind a service by using the
command line interface
At the command prompt, type:
Example
Updated: 2014-10-28
By default, the NetScaler appliance uses the least connections method to select the service for redirecting each client
request, but you should set the LLB method to one of the supported methods. You can also configure persistence, so that
different transmissions from the same client are directed to the same server.
To configure the LLB method and/or persistence by using the command line
interface
At the command prompt, type the following command:
Example
Updated: 2014-10-28
After configuring the IPv4 or IPv6 services, virtual servers, LLB methods, and persistence, you configure an IPv4 or IPv6 LLB
route for the network specifying the LLB virtual server as the gateway. A route is a collection of links that are load
balanced. Requests are sent to the LLB virtual server IP address that acts as the gateway for all outbound traffic and
selects the router based on the LLB method configured.
To configure an IPv4 LLB route by using the command line interface
At the command prompt, type:
Example
add lb route6 ::/0 llb6_vs show lb route6 Network VIP Flags ----------- --------- -------- 1) ::/0 llb6_vs UP
Example
4. Click Create, and then click Close. T he route that you just created appears on the LLB or the LLB6 tab in the Routes
pane.
T he following diagram shows a basic LLB setup. A service is configured for each of the two links (ISPs) and PING monitors
are bound by default to these services. A link is selected based on the LLB method configured.
Updated: 2014-10-28
You create a transparent monitor to monitor the health of upstream devices, such as routers. You can then bind the
transparent monitor to services. T he default PING monitor monitors the connectivity only between the NetScaler
appliance and the upstream device. T he transparent monitor monitors all the devices existing in the path from the appliance
to the device that owns the destination IP address specified in the monitor. If a transparent monitor is not configured and
the status of the router is UP but one of the next hop devices from that router is down, the appliance includes the router
while performing load balancing and forwards the packet to the router. However, the packet is not delivered to the final
destination because one of the next hop devices is down. By binding a transparent monitor, if any of the devices (including
the router) are down, the service is marked as DOWN and the router is not included when the appliance performs link load
balancing.
To create a transparent monitor by using the command line interface
At the command prompt, type:
Example
Name*
T ype*
Destination IP
T ransparent
* A required parameter
Example
You can configure an LLB setup for reverse network address translation (RNAT ) for outbound traffic. T his ensures that the
return network traffic for a specific flow is routed through the same path. First configure basic LLB, as described in
"Configuring a Basic LLB Setup", and then configure RNAT . You must then enable use subnet IP (USNIP) mode.
Add IP NS <network><subnet of first ISP in the IP router> <subnet mask> -t ype SNIP
Add IP NS <in the IP subnet of second ISP router> <subnet mask> -t ype SNIP
NatIP: 10.140.23.1
NatIP: 10.141.23.1
Note
You can also configure RNAT by using Access Control Lists (ACLs). Refer Configuring RNAT for details.
Example
In the following diagram, Rout er-vip is the primary virtual server, and Backup_Rout er-vip is the secondary virtual server
designated as the backup virtual server.
Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an IPv6 service in the above
figure.
By default, all traffic is sent through the primary route. However, when the primary route fails, all traffic is diverted to the backup
route as shown in the following diagram.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers and select the secondary virtual server for which you
Note: If your Internet service provider has provided an IPv6 address, replace the IPv4 service with an IPv6 service in the
above figure.
However, if any one of the gateways (Rout er1-vip or Rout er2-vip ) is DOWN, traffic is routed through the backup router.
In the following diagram, Rout er1-vip for ISP1 is DOWN, so all traffic with the destination IP specified as 30.30.30.30 is
also sent through ISP2.
Updated: 2013-09-05
To evaluate the performance of virtual servers or to troubleshoot problems, you can display details of the virtual servers
configured on the NetScaler appliance. You can display a summary of statistics for all the virtual servers, or you can specify
the name of a virtual server to display the statistics only for that virtual server. You can display the following details:
Name
IP address
Port
Protocol
State of the virtual server
Rate of requests received
Rate of hits
You can view the rate of requests, responses, request bytes, response bytes, current client connections, requests in surge
queue, current server connections, and so forth using the service statistics.
Distribute all requests for a specific protected website, application, or resource between two or more identically
configured servers.
Use any of several different algorithms to determine which server should receive each incoming user request, basing the
decision on different factors, such as which server has the fewest current user connections or which server has the
lightest load.
T he load balancing feature is a core feature of the NetScaler appliance. Most users first set up a working basic
configuration and then customize various settings, including persistence for connections. In addition, you can configure
features for protecting the configuration against failure, managing client traffic, managing and monitoring servers, and
managing a large scale deployment.
A load balancing setup includes a load-balancing virtual server and multiple load-balanced application servers. T he virtual
server receives incoming client requests, uses the load balancing algorithm to select an application server, and forwards the
requests to the selected application server. T he following conceptual drawing illustrates a typical load balancing
deployment. Another variation involves assigning a global HT T P port.
T he load balancing virtual server can use any of a number of algorithms (or methods) to determine how to distribute load
among the load-balanced servers that it manages. T he default load balancing method is the least connection method, in
which the NetScaler appliance forwards each incoming client connection to whichever load-balanced application server
currently has the fewest active user connections.
T he entities that you configure in a typical NetScaler load balancing setup are:
T he virtual server, services, and load balanced application servers in a load balancing setup can use either Internet Protocol
version 4 (IPv4) or Internet Protocol version 6 (IPv6) IP addresses. You can mix IPv4 and IPv6 addresses in a single load
balancing setup.
For variations in the load balancing setup, see the following use cases:
In a load balancing setup, the load balancing server is logically located between the client and the server farm, and manages
traffic flow to the servers in the server farm. On the NetScaler appliance, the application servers are represented by virtual
entities called services. T he following diagram shows the topology of a basic load balancing configuration.
T he following diagram shows the load balancing sample values and mandatory parameters that are described in the
preceding table.
In some cases you might need to use a wildcard for the IP address or the port of a virtual server or for the port of a service.
T he following cases may require using a wildcard:
If the NetScaler appliance is configured as a transparent pass through, which must accept all traffic that is sent to it
regardless of the IP or port to which it is sent.
If one or more services listen on ports that are not well known.
If one or more services, over time, change the ports that they listen on.
If you reach the limit for the number of IP addresses and ports that you can configure on a single NetScaler appliance.
If you want to create virtual servers that listen for all traffic on a specific virtual LAN.
When a wildcard-configured virtual server or service receives traffic, the NetScaler appliance determines the actual IP
address or port and creates new records for the service and associated load balanced application server. T hese dynamically
created records are called dynamically learned server and service records.
For example, a firewall load balancing configuration can use wildcards for both the IP address and port. If you bind a
wildcard TCP service to this type of load balancing virtual server, the virtual server receives and processes all TCP traffic that
does not match any other service or virtual server.
T he following table describes some of the different types of wildcard configurations and when each should be used.
* * T CP A general wildcard virtual server that accepts traffic sent to any IP address and port on
the NetScaler appliance. When using a wildcarded virtual server, the appliance
dynamically learns the IP and port of each service and creates the necessary records as
it processes traffic.
* * T CP A firewall load balancing virtual server. You can bind firewall services to this virtual server,
IP * T CP,UDP, A virtual server that accepts all traffic that is sent to the specified IP address, regardless
Address and ANY of the port. You must explicitly bind to this type of virtual server the services to which it
will redirect traffic. It will not dynamically learn them.
Note: You do not configure services or virtual servers for a global HT T P port. In this
case, you configure a specific port as a global HT T P port (for example, set ns param -
httpPort 80). T he appliance then accepts all traffic that matches the port number, and
processes it as HT T P traffic. T he appliance dynamically learns and creates services for
this traffic.
* port SSL, A virtual server that accepts all traffic sent to any IP address on a specific port. Used for
SSL_T CP global transparent SSL offloading. All SSL, HT T P, and TCP processing that usually is
performed for a service of the same protocol type is applied to traffic that is directed
to this specific port. T he appliance uses the port to dynamically learn the IP of the
service it should use. If –cleartext is not specified, the NetScaler appliance uses end-to-
end SSL.
* port Not All other virtual servers that can accept traffic to the port. You do not bind services to
applicable these virtual servers; the NetScaler appliance learns them dynamically.
Note: If you have configured your NetScaler appliance as a transparent pass through that makes use of global (wildcard)
ports, you may want to turn on Edge mode. For more information, see "Configuring Edge Mode."
T he NetScaler appliance attempts to locate virtual servers and services by first attempting an exact match. If none is
found, it continues to search for a match based on wildcards, in the following order:
If the appliance is unable to select a virtual server by IP address or port number, it searches for a virtual server on the basis
of the protocol used in the request, in the following order:
1. HT T P
2. T CP
3. ANY
You do not configure services or virtual servers for a global HT T P port. Instead, you configure a specific port by using the set
ns param command. After configuring this port, the NetScaler appliance accepts all traffic that matches the port number,
and processes it as HT T P traffic, dynamically learning and creating services for that traffic.
You can configure more than one port number as a global HT T P port. If you are specifying more than one port number in a
single set ns param command, separate the port numbers by a single white space. If one or more ports have already been
specified as global HT T P ports, and you want to add one or more ports without removing the ports that are currently
In this example, port 8888 is added to the global HT T P port list. Port 80 is already configured as a global HT T P port.
...
...
Done
>
To configure a global HTTP port by using the configuration utility
1. Navigate to System > Settings > Change HT T P Parameters, and then add an HT T P port number.
You can configure load balancing entities such as services and virtual servers when the load balancing feature is disabled, but
they will not function until you enable the feature.
enable ns feature LB
show ns feature
Done
2) Surge Protection SP ON
3) Load Balancing LB ON
Done
Create an entry for your server on the NetScaler appliance. T He NetScaler appliance supports IP address based servers and
domain-based servers. If you create an IP address based server, you can specify the name of ther server instead of its IP
address when you create a service. For information about setting up DNS for a domain-based server, see Domain Name
System.
Navigate to T raf fic Management > Load Balancing > Servers , and add a server object.
After you enable the load balancing feature, you must create at least one service for each application server that is to be
included in your load balancing setup. T he services that you configure provide the connections between the NetScaler
appliance and the load balanced servers. Each service has a name and specifies an IP address, a port, and the type of data
that is served.
If you create a service without first creating a server object, the IP address of the service is also the name of the server
that hosts the service. If you prefer to identify servers by name rather than IP address, you can create server objects and
then specify a server's name instead of its IP address when you create a service.
When you create a service that uses UDP as the transport layer protocol, a ping monitor is automatically bound to the
service. A ping monitor is the most basic of the built-in monitors. When you create a service that uses TCP as the transport
layer protocol, a TCP_default monitor is automatically bound to the service. When you develop a strategy for managing
your load balancing setup, you might decide to bind a different type of monitor, or multiple monitors, to the service.
Before you create a service, you need to understand the different service types and how each is used. T he following list
describes the types of services supported on the NetScaler appliance.
HT T P
Used for load-balanced servers that accept HT T P traffic, such as standard web sites and web applications. T he HT T P
service type enables the NetScaler appliance to provide compression, content filtering, caching, and client keep-alive
support for your Layer 7 web servers. T his service type also supports virtual server IP port insertion, redirect port rewriting,
Web 2.0 Push, and URL redirection support.
Because HT T P is a TCP-based application protocol, you can also use the TCP service type for web servers. If you do so,
however, the NetScaler appliance is able to perform only Layer 4 load balancing. It cannot provide any of the Layer 7
support described earlier.
SSL
Used for servers that accept HT T PS traffic, such as ecommerce web sites and shopping cart applications. T he SSL service
type enables the NetScaler appliance to encrypt and decrypt SSL traffic (perform SSL offloading) for your secure web
applications. It also supports HT T P persistence, content switching, rewrite, virtual server IP port insertion, Web 2.0 Push, and
URL redirection.
You can also use the SSL_BRIDGE, SSL_TCP, or TCP service types. If you do so, however, the NetScaler performs only Layer
4 load balancing. It cannot provide SSL offloading or any of the Layer 7 support described above
FT P
You can also use TCP or ANY service types for FT P servers.
T CP
Used for servers that accept many different types of TCP traffic, or that accept a type of TCP traffic for which a more
specific type of service is not available.
You can also use the ANY service type for these servers.
SSL_T CP
Used for servers that accept non-HT T P-based SSL traffic, to support SSL offloading.
You can also use the TCP service type for these services. If you do so, the NetScaler appliance performs both the Layer 4
load balancing and SSL offloading.
UDP
Used for servers that accept UDP traffic. You can also use the ANY service type.
SSL_BRIDGE
Used for servers that accept SSL traffic when you do not want the NetScaler appliance to perform SSL offloading.
Alternatively, you can use the SSL_TCP service type.
NNT P
Used for servers that accept Network News Transfer Protocol (NNT P) traffic, typically Usenet sites.
DNS
Used for servers that accept DNS traffic, typically nameservers. With the DNS service type, the NetScaler appliance
validates the packet format of each DNS request and response. It can also cache DNS responses. You can apply DNS
policies to DNS services.
You can also use the UDP service type for these services. If you do, however, the NetScaler appliance can only perform
Layer 4 load balancing. It cannot provide support for DNS-specific features.
ANY
Used for servers that accept any type of TCP, UDP, or ICMP traffic. T he ANY parameter is used primarily with firewall load
balancing and link load balancing.
SIP -UDP
Used for servers that accept UDP-based Session Initiation Protocol (SIP) traffic. SIP initiates, manages, and terminates
multimedia communications sessions, and has emerged as the standard for Internet telephony (VoIP).
You can also use the UDP service type for these services. If you do, however, the NetScaler appliance performs only Layer 4
load balancing. It cannot provide support for SIP-specific features.
Used for servers that accept DNS traffic, where the NetScaler appliance acts as a proxy for TCP traffic sent to DNS servers.
With services of the DNS-TCP service type, the NetScaler appliance validates the packet format of each DNS request and
response and can cache DNS responses, just as with the DNS service type.
You can also use the TCP service type for these services. If you do, however, the NetScaler appliance only performs Layer 4
load balancing of external DNS name servers. It cannot provide support for any DNS-specific features.
RT SP
Used for servers that accept Real T ime Streaming Protocol (RT SP) traffic. RT SP provides delivery of multimedia and other
streaming data. Select this type to support audio, video, and other types of streamed media.
You can also use the TCP service type for these services. If you do, however, the NetScaler appliance performs only Layer 4
load balancing. It cannot parse the RT SP stream or provide support for RT SPID persistence or RT SP NAT ting.
DHCP RA
Used for servers that accept DHCP traffic. T he DHCPRA service type can be used to relay DHCP requests and responses
between VLANs.
DIAMET ER
Used for load balancing Diameter traffic among multiple Diameter servers. Diameter uses message-based load balancing.
SSL_DIAMET ER
Services are designated as DISABLED until the NetScaler appliance connects to the associated load-balanced server and
verifies that it is operational. At that point, the service is designated as ENABLED. T hereafter, the NetScaler appliance
periodically monitors the status of the servers, and places any that fail to respond to monitoring probes (called health
checks) back in the DISABLED state until they respond.
Note: You can create a range of services from a single CLI command or the same dialog box. T he names in the range vary by
a number used as a suffix/prefix. For example, service1, service2, and so on. From the configuration utility, you can specify a
range only in the last octet of the IP address, which is the fourth in case of an IPv4 address and the eighth in case of an
IPv6 address. From the command line, you can specify the range in any octet of the IP address.
QUIC
Used by load balancing servers that accept UDP based QUIC video traffic. T he service enables the NetScaler appliance to
optimize encrypted ABR video traffic over UDP protocol.
3. In the Create Service dialog box, specify values for the following parameters:
4. Click Creat e , and then click Close . T he service you created appears in the Services pane.
After you create your services, you must create a virtual server to accept traffic for the load balanced Web sites,
applications, or servers. Once load balancing is configured, users connect to the load-balanced Web site, application, or
server through the virtual server’s IP address or FQDN.
Note: T he virtual server is designated as DOWN until you bind the services that you created to it, and until the NetScaler
appliance connects to those services and verifies that they are operational. Only then is the virtual server designated as UP.
To create a virtual server by using the command line interface
At the command prompt, type:
After you have created services and a virtual server, you must bind the services to the virtual server. In most cases, services
are bound to virtual servers of the same type, but you can bind certain types of services to certain different types of virtual
HT T P SSL You would normally bind an SSL service to an HT T P virtual server to do encryption.
SSL HT T P You would normally bind an HT T P service to an SSL virtual server to do SSL offloading.
SSL_T CP T CP You would normally bind a T CP service to an SSL_T CP virtual server to do SSL offloading for
other T CP (SSL decryption without content awareness).
T he state of the services bound to a virtual server determines the state of the virtual server: if all of the bound services are
DOWN, the virtual server is marked DOWN, and if any of the bound services is UP or OUT OF SERVICE, the state of the
virtual server is UP.
To bind a service to a load balancing virtual server by using the command line
interface
At the command prompt, type:
To bind a service to a load balancing virtual server by using the configuration utility
1. Navigate to T raf f ic Management > Load Balancing > Virt ual Servers , and select a virtual server.
2. Click in the Service section, and select a service to bind.
After finishing your basic configuration, you should view the properties of each service and load balancing virtual server in
your load balancing setup to verify that each is configured correctly. After the configuration is up and running, you should
view the statistics for each service and load balancing virtual server to check for possible problems.
To view t he propert ies of server object s by using t he command line int erf ace
Navigate to T raf fic Management > Load Balancing > Servers . T he parameter values of the available servers appear in
the details pane.
To view t he propert ies of a load balancing virt ual server by using t he command line int erf ace
To view t he propert ies of a load balancing virt ual server by using t he configurat ion ut ilit y
1. Navigate to T raf fic Management > Load Balancing > Virt ual Servers .
2. In the details pane, click a virtual server to display its properties at the bottom of the
details pane.
3. To view cache redirection and content switching virtual servers that are bound to this
To view t he propert ies of services by using t he command line int erf ace
Navigate to T raf fic Management > Load Balancing > Services . T he details of the available services appear on the
Services pane.
2. In the details pane, select the service whose binding information you want to view.
Name
IP address
Port
Protocol
State of the virtual server
Rate of requests received
Rate of hits
To display virt ual server st at ist ics by using t he command line int erf ace
To display a summary of the statistics for all the virtual servers currently configured on the NetScaler, or for a single virtual
server, at the command prompt, type:
Done
To display virt ual server st at ist ics by using t he configurat ion ut ilit y
2. If you want to display the statistics for only one virtual server, in the details pane, select the virtual server whose statistics
you want to display.
To view t he st at ist ics of a service by using t he command line int erf ace
2. In the details pane, select the service whose statistics you want to view (for example, Service-HT T P-1).
T he state and effective state of a virtual server are the same if a backup virtual server is not configured. However, if a
backup virtual server or a chain of backup virtual servers is configured, the effective state is derived from the states of the
services that are bound to the primary virtual server and the backup virtual server(s). If any of the backup virtual servers in
the chain is UP, the effective state of the primary virtual server is UP, even if all the services bound to the primary virtual
server are DOWN.
T he following diagrams show the conditions under which a virtual server transitions from one state to another.
UP : If probes from all the monitors bound to the service are successful.
DOWN : If monitoring probes to the service are not answered within the configured time limit.
OUT OF SERVICE : If you administratively disable the service, or if you gracefully shut down the service and there are no
active transactions to the service
GOING OUT OF SERVICE (T ROF S): If you administratively disable the service with delay, or gracefully shut down the
A service in the process of transitioning from UP to OFS is in the GOING OUT OF SERVICE state. A service transitioning
from DOWN to OFS is in the DOWN WHEN GOING OUT OF SERVICE state. For example, if a service is DOWN and you
disable it with delay, the service transitions to DOWN WHEN GOING OUT OF SERVICE and then to the OUT OF SERVICE
state. If a service is UP and you disable it with delay, the service transitions to GOING OUT OF SERVICE. During this time, if a
monitoring probe to the server fails, the service transitions to DOWN WHEN GOING OUT OF SERVICE and, after the delay
time expires, enters the OFS state.
Note
You can configure spillover to a backup virtual server by setting the "healthT hreshold" parameter to a non-zero positive value. T hen,
if a single service bound to the primary virtual server transitions to the DOWN WHEN GOING OUT OF SERVICE state and the health
threshold is not reached, the primary virtual server is marked DOWN and new connections are directed to the backup virtual server.
T he following diagrams show the conditions under which a service transitions from one state to another.
HT T Ponlyflag— Include the HttpOnly attribute in persistence cookies. T he HttpOnly attribute limits the scope of a
cookie to HT T P requests and helps mitigate the risk of cross-site scripting attacks.
UseSecuredPersistenceCookie— Encrypt the persistence cookie values by using a SHA2 hash algorithm.
Cookiepassphrase— Specify the passphrase used to generate a secured persistence cookie value.
DBS_LB— Enable database specific load balancing for MySQL and MSSQL service types.
Cl_process_local— Packets destined to a virtual server in a cluster are not steered. Enable option for single packet
request response mode or when the upstream device is performing a proper RSS for connection based distribution.
Note
You can set DBS_LB and Cl_process_local parameters on a virtual server and in the profile. If you enable these parameters on a virtual server and then
set a profile to this virtual server, the parameters appear as disabled in the output of the "show lb vserver" command for that virtual server. Check the
profile to see the actual status of these parameters. In addition, if you set and then unset a profile to a virtual server, the parameters will be set with
default values for that virtual server.
Done
LB Profile name: p1
No of vservers bound: 0
Done
To associat e an LB profile wit h an LB virt ual server by using t he Net Scaler command line
Done
Mode: IP
Persistence: NONE
L2Conn: OFF
RHIstate: PASSIVE
DBS_LB: DISABLED
Traffic Domain: 0
LB Profile: p1
Done
To associat e an LB profile wit h an LB virt ual server by using t he Net Scaler GUI
1. Navigate to T raf f ic Management > Load Balancing > Virt ual Servers .
2. Select a virtual server, and click Edit .
3. In Advanced Set t ings , click P rof iles .
4. In the LB P rof ile list, select the profile to associate with this virtual server.
Some load balancing algorithms are best suited to handling traffic on websites, others to managing traffic to DNS servers,
and others to handling complex web applications used in e-commerce or on company LANs or WANs. T he following table
lists each load balancing algorithm that the NetScaler appliance supports, with a brief description of how each operates.
LEASTCONNECT ION Which service currently has the fewest client connections. T his is the default load balancing
algorithm.
ROUNDROBIN Which service is at the top of a list of services. After that service is selected for a connection,
it moves to the bottom of the list.
LEAST RESPONSET IME Which load balanced server currently has the quickest response time.
LEAST BANDWIDT H Which service currently has the fewest bandwidth constraints.
LRT M Fewest active connections and the lowest average response time.
Depending on the protocol of the service that it is load balancing, the NetScaler appliance sets up each connection
between client and server to last for a different time interval. T his is called load balancing granularity, of which are three
types: request-based, connection-based, and time-based granularity. T he following table describes each type of granularity
and when each is used.
Request - HT T P or A new service is chosen for each HT T P request, independent of TCP connections. As with
based HT T PS all HT T P requests, after the Web server fulfills the request, the connection is closed.
Connection- TCP and A service is chosen for every new TCP connection. T he connection persists until
based TCP-based terminated by either the service or the client.
protocols
other than
HT T P
T ime-based UDP and A new service is chosen for each UDP packet. Upon selection of a service, a session is
other IP created between the service and a client for a specified period of time. When the time
protocols expires, the session is deleted and a new service is chosen for any additional packets,
even if those packets come from the same client.
During startup of a virtual server, or whenever the state of a virtual server changes, the virtual server can initially use the
round robin method to distribute the client requests among the physical servers. T his type of distribution, referred to as
startup round robin, helps prevent unnecessary load on a single server as the initial requests are served. After using the
round robin method at the startup, the virtual server switches to the load balancing method specified on the virtual server.
To set t he st art up round-robin f act or by using t he command line int erf ace
Example
1. Navigate to T raffic Management > Load Balancing > Configure Load Balancing Parameters, and set the Startup RR
Factor.
For TCP, HT T P, HT T PS, and SSL_TCP services, the NetScaler appliance includes the following connection types in its list of
existing connections:
Act ive connect ions t o a service. Connections representing requests that a client has sent to the virtual server and
that the virtual server has forwarded to a service. For HT T P and HT T PS services, active connections represent only those
HT T P or HT T PS requests that have not yet received a response.
Wait ing connect ions in t he surge queue. Any connections to the virtual server that are waiting in a surge queue and
have not yet been forwarded to a service. Connections can build up in the surge queue at any time, for any of the
following reasons:
Your services have connection limits, and all services in your load balancing configuration are at that limit.
T he surge protection feature is configured and has been activated by a surge in requests to the virtual server.
T he load-balanced server has reached an internal limit and therefore does not open any new connections. (For
example, an Apache server’s connection limit is reached.)
When a virtual server uses the least connection method, it considers the waiting connections as belonging to the specific
service. T herefore, it does not open new connections to those services.
For UDP services, the connections that the least connection algorithm considers include all sessions between the client and
a service. T hese sessions are logical, time-based entities. When the first UDP packet in a session arrives, the NetScaler
appliance creates a session between the source IP address and port and the destination IP address and port.
For Real-T ime Streaming Protocol (RT SP) connections, the NetScaler appliance uses the number of active control
connections to determine the lowest number of connections to an RT SP service.
T he following example shows how a virtual server selects a service for load balancing by using the least connection method.
Consider the following three services:
T he following diagram illustrates how the NetScaler appliance forwards incoming requests when using the least connection
method.
Service-HT T P-3 receives the first request, because it is not handling any active transactions.
Note: If connections to Service-HT T P-2 close, it might get new connections before each of the other two services has
15 active transactions.
T he following table explains how connections are distributed in the three-service load balancing setup described above.
(N = 0)
Request-2 Service- 2
Request-3 Service- 3
HT T P-3
(N = 2)
Request-4 Service- 4 Service-HT T P-1 and Service-HT T P-3 have the same
HT T P-1 number of active connections.
(N = 3)
Request-5 Service- 4
HT T P-3
(N = 3)
Request-6 Service- 5
HT T P-1
(N = 4)
Request-7 Service- 5
HT T P-3
(N = 4)
Request-8 Service- 6
HT T P-1
(N = 5)
Service-HT T P-2 is selected for load balancing when it completes its active transactions and the current connections to
it close, or when the other services (Service-HT T P-1 and Service-HT T P-3) have 15 or more connections each.
T he NetScaler appliance can also use the least connection method when weights are assigned to services. It selects a
service by using the value (Nw) of the following expression:
T he following example shows how the NetScaler appliance selects a service for load balancing by using the least
connection method when weights are assigned to services. In the preceding example, suppose Service-HT T P-1 is assigned a
weight of 2, Service-HT T P-2 is assigned a weight of 3, and Service-HT T P-3 is assigned a weight of 4. Connections are
forwarded as follows:
Note: If services are not handling any active transactions, the NetScaler appliance uses the round robin method
regardless of the weights assigned to each of the services.
Service-HT T P-3 receives the second, third, fourth, fifth, sixth, and seventh requests because the service has lowest Nw
value.
Service-HT T P-1 receives the eighth request. Because Service-HT T P-1 and Service-HT T P-3 now have same Nw value, the
NetScaler performs load balancing in a round robin manner. T herefore, Service-HT T P-3 receives the ninth request.
T he following table explains how connections are distributed on the three-service load balancing setup that is described
above.
(Nw = 0)
(Nw =
2500)
(Nw =
5000)
(Nw =
7500)
(Nw =
10000)
(Nw =
15000)
(Nw =
15000)
Service-HT T P-2 is selected for load balancing when it completes its active transactions or when the Nw value of other
services (Service-HT T P-1 and Service-HT T P-3) is equal to 50000.
T he following diagram illustrates how the NetScaler appliance uses the least connection method when weights are
assigned to the services.
Figure 2. Mechanism of the Least Connections Load Balancing Method when Weights are Assigned
T he following diagram illustrates how the NetScaler appliance uses the round robin method with a load balancing setup
that contains three load-balanced servers and their associated services.
If you assign a different weight to each service, the NetScaler appliance performs weighted round robin distribution of
incoming connections. It does this by skipping the lower-weighted services at appropriate intervals.
For example, assume that you have a load balancing setup with three services. You set Service-HT T P-1 to a weight of 2,
Service-HT T P-2 to a weight of 3, and Service-HT T P-3 to a weight of 4. T he services are bound to Vserver-LB-1, which is
configured to use the round robin method. With this setup, incoming requests are delivered as follows:
Note: You can also configure weights on services to prevent multiple services from using the same server and overloading
Figure 2. How the Round Robin Load Balancing Method Works with Weighted Services
To configure the round robin method, see Configuring a Load Balancing Method that Does Not Include a Policy.
T he following example shows how a virtual server selects a service for load balancing by using the least response time
method. Consider the following three services:
T he following diagram illustrates how the NetScaler appliance uses the least response time method to forward the
connections.
Figure 1. How the Least Response T ime Load Balancing Method Works
T he virtual server selects a service by multiplying the number of active transactions by the T T FB for each service and then
selecting the service with the lowest result. For the example shown above, the virtual server forwards requests as follows:
Service-HT T P-3 receives the first request, because the service is not handling any active transactions.
Service-HT T P-3 also receives the second and third requests, because the result is lowest of the three services.
Service-HT T P-1 receives the fourth request. Since Service-HT T P-1 and Service-HT T P-3 have the same result, the
NetScaler appliance chooses between them by applying the Round Robin method.
Service-HT T P-3 receives the fifth request.
Service-HT T P-2 receives the sixth request, because at this point it has the lowest result.
Because Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 all have the same result at this point, the NetScaler
T he following table explains how connections are distributed in the three-service load balancing setup described above.
(N = 0)
(N = 2)
(N = 3)
Request-4 Service- N=8 Service-HT T P-1 and Service-HT T P-3 have the
HT T P-1 same N values.
(N = 6)
(N = 6)
(N = 7)
(N = 8)
(N = 8)
Suppose Service-HT T P-1 is assigned a weight of 2, Service-HT T P-2 is assigned weight of 3, and Service-HT T P-3 is assigned
weight of 4.
Service-HT T P-3 receives the first request, because it is not handling any active transactions.
If services are not handling any active transactions, the NetScaler selects them regardless of the weights assigned to
them.
Service-HT T P-3 receives the second, third, fourth, and fifth requests, because this service has the lowest Nw value.
Service-HT T P-2 receives the sixth request, because this service has the lowest Nw value.
Service-HT T P-3 receives the seventh request, because this service has the lowest Nw value.
Service-HT T P-2 receives the eighth request, because this service has the lowest Nw value.
Service-HT T P-1 has the lowest weight and therefore the highest Nw value, so the virtual server does not select it for load
balancing.
T he following table explains how connections are distributed in the three-service load balancing setup described above.
(Nw = 0)
(Nw = 2500
(Nw = 5000)
(Nw =
15000)
(Nw =
20000)
(Nw =
23333.34)
(Nw =
25000)
(Nw =
26666.67)
Service-HT T P-1 is selected for load balancing when it completes its active transactions or when the Nw values of other
services (Service-HT T P-2 and Service-HT T P-3) are equal to 105000.
T he following diagram illustrates how the NetScaler appliance uses the least response time method when weights are
assigned.
Figure 2. How the Least Response T ime Load Balancing Method Works When Weights Are Assigned
When a load balancing virtual server is configured to use the least response time method with monitors, it uses the existing
monitoring infrastructure to select the service with the smallest number of active transactions and the fastest average
response time. Before you use the least response time method with monitoring, you must bind application-specific monitors
to each service and enable least response time method mode on these monitors. T he NetScaler appliance then makes load
balancing decisions based on the response times it calculates from monitoring probes. For more information about
configuring monitors, see Configuring Monitors in a Load Balancing Setup.
You can use the least response time method with monitors to select non-HT T P and non-HT T PS services. You can also use
this method when several monitors are bound to a service. Each monitor determines the response time by using the
protocol that it measures for the service that it is bound to. T he virtual server then calculates an average response time for
that service by averaging the results.
T he following table summarizes how response times are calculated for various monitors.
PING T ime difference between the ICMP ECHO request and the ICMP ECHO response.
TCP T ime difference between the SYN request and the SYN+ACK response.
HT T P T ime difference between the HT T P request (after the TCP connection is established) and
the HT T P response.
TCP-ECV T ime difference between the time the data send string is sent and the data receive string
is returned.
A tcp-ecv monitor without the send and receive strings is considered to have an incorrect
UDP-ECV T ime difference between the UDP send string and the UDP receive string.
DNS T ime difference between a DNS query and the DNS response.
TCPS T ime difference between a SYN request and the SSL handshake completion.
FT P T ime difference between the sending of the user name and the completion of user
authentication.
USER T ime difference between the time when a request is sent to the dispatcher and the time
when the dispatcher response is received.
T he following example shows how the NetScaler appliance selects a service for load balancing by using the least response
time method with monitors. Consider the following three services:
Service-HT T P-1 is handling 3 active transactions and the response time is five seconds.
Service-HT T P-2 is handling 7 active transactions and the response time is one second.
Service-HT T P-3 is not handling any active transactions and the response time is two seconds.
T he following diagram illustrates the process that the NetScaler appliance follows when it forwards requests.
Figure 3. How the Least Response T ime Load Balancing Method Works When Using Monitors
Service-HT T P-3 receives the first request, because this service is not handling any active transaction.
Service-HT T P-3 receives the second, third, and fourth requests, because this service has the lowest N value.
Service-HT T P-2 receives the fifth request, because this service has the lowest N value.
Since both Service-HT T P-2 and Service-HT T P-3 currently have the same N value, the NetScaler appliance switches to
the round robin method T herefore, Service-HT T P-3 receives the sixth request.
Service-HT T P-2 receives the seventh and eighth requests, because this service has the lowest N value.
Service-HT T P-1 is not considered for load balancing, because it is more heavily loaded (has the highest N value) when
compared to the other two services. However, if Service-HT T P-1 completes its active transactions, the NetScaler appliance
again considers that service for load balancing.
(N = 0)
(N = 2)
(N = 4)
(N = 6)
(N = 7)
Request-6 Service- N = 10
HT T P-3
(N = 8)
(N = 8)
Request-8 Service- N = 10
HT T P-1
(N = 9)
Service-HT T P-1 is again selected for load balancing when it completes its active transactions or when the N value of
the other services (Service-HT T P-2 and Service-HT T P-3) is equal to 15.
T he NetScaler appliance also performs load balancing by using the number of active transactions, response time, and
weights if different weights are assigned to services. T he NetScaler appliance selects the service by using the value (Nw) in
the following expression:
As in the preceding example, suppose Service-HT T P-1 is assigned a weight of 2, Service-HT T P-2 is assigned a weight of 3,
and Service-HT T P-3 is assigned a weight of 4.
Service-HT T P-3 receives the first request, because it is not handling any active transactions.
Service-HT T P-3 receives the second, third, and fourth requests, because this service has the lowest Nw value.
Service-HT T P-1 has the lowest weight and the highest Nw value, so the NetScaler appliance does not select it for load
balancing.
(Nw = 0)
(Nw = 5000
(Nw =
15000)
(Nw =
20000)
(Nw =
23333.34)
(Nw =
25000)
(Nw =
23333.34)
(Nw
=25000)
Service-HT T P-1 is selected for load balancing when it completes its active transactions or when the Nw value of the
other services (Service-HT T P-2 and Service-HT T P-3) is equal to 75000.
T he following diagram illustrates how the virtual server uses the least response time method when weights are assigned.
Figure 4. How the Least Response T ime Load Balancing Method with Monitors Works When Weights Are Assigned
To configure the least response time method using monitors, see Configuring a Load Balancing Method that Does Not
Include a Policy.
You can use the hashing load balancing methods in an environment where a cache serves a wide range of content from the Internet or specified origin servers.
Caching requests reduces request and response latency, and ensures better resource (CPU) utilization, making caching popular on heavily used Web sites and
application servers. Since these sites also benefit from load balancing, hashing load balancing methods are widely useful.
These hashing algorithms ensure minimal disruption when services are added to or deleted from your load balancing setup. Most of them calculate two hash values:
The NetScaler appliance then generates a new hash value by using both of those hash values. Finally, it forwards the request to the service with highest hash value.
As the appliance computes a hash value for each request and selects the service that will process the request, it populates a cache. Subsequent requests with the
same hash value are sent to the same service. The following flow chart illustrates this process.
Consider a scenario where three services (Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3) are bound to a virtual server, any hash method is configured,
and the hash value is Hash1. When the configured services are UP, the request is sent to Service-HTTP-1. If Service-HTTP-1 is down, the NetScaler appliance
calculates the hash value for the last log of the number of services. The NetScaler then selects the service with the highest hash value, such as Service-HTTP-2. The
following diagram illustrates this process.
Note: If the NetScaler appliance fails to select a service by using a hashing method, it defaults to the least connection method to select a service for the incoming
request. You should adjust server pools by removing services during periods of low traffic to enable the caches to repopulate without affecting performance on your
load balancing setup.
When you configure the NetScaler appliance to use the URL hash method for load balancing the services, for selecting a
service, the NetScaler generates a hash value of the HT T P URL present in the incoming request. If the service selected by
the hash value is DOWN, the algorithm has a method to select another service from the list of active services. T he
NetScaler caches the hashed value of the URL, and when it receives subsequent requests that use the same URL, it
forwards them to the same service. If the NetScaler cannot parse an incoming request, it uses the round robin method for
load balancing instead of the URL hash method.
For generating the hash value, NetScaler uses a specific algorithm and considers a part of the URL. By default, the
NetScaler considers the first 80 bytes of the URL. If the URL is of less than 80 bytes, the complete URL is used. You can
specify a different length. T he hash length can be from 1 to 4096 bytes. Generally, if long URLs are used where only a small
number of characters are different, it is a good idea to make the hash length as high as possible to try to ensure a more
even load distribution.
Consider a scenario where three services, Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3, are bound to a virtual
server, and the load balancing method configured on the virtual server is the URL hash method. T he virtual server receives a
request and the hash value of the URL is U1. NetScaler selects Service-HT T P-1. If Service-HT T P-1 is DOWN, the NetScaler
selects Service-HT T P-2.
If Service-HT T P-1 and Service-HT T P-2 are down, requests that generate the hash URL1 are sent to Service-HT T P-3. If
these services are UP, requests that generate the hash URL1 are distributed in the following manner:
To configure the URL hash method, see Configuring a Load Balancing Method that Does Not Include a Policy. Select the
load balancing method as URL Hash, and set the hash length to the number of bytes to be used for generating the hash
value.
A load balancing virtual server configured to use the domain hash method uses the hashed value of the domain name in the
HT T P request to select a service. T he domain name is taken from either the incoming URL or the Host header of the HT T P
request. If the domain name appears in both the URL and the Host header, the NetScaler gives preference to the URL.
If you configure domain name hashing, and an incoming HT T P request does not contain a domain name, the NetScaler
appliance defaults to the round robin method for that request.
T he hash-value calculation uses the name length or hash length value, whichever is smaller. By default, the NetScaler
appliance calculates the hash value from the first 80 bytes of the domain name. To specify a different number of bytes in
the domain name when calculating the hash value, you can set the hashLength parameter (Hash Length in the
configuration utility) to a value of from 1 to 4096 (bytes).
To configure the domain hash method, see Configuring a Load Balancing Method that Does Not Include a Policy.
A load balancing virtual server configured to use the destination IP hash method uses the hashed value of the destination
IP address to select a server. You can mask the destination IP address to specify which part of it to use in the hash value
T his load balancing method is appropriate for use with the cache redirection feature.
To configure the destination IP hash method for an IPv4 destination server, you set the netMask parameter. To configure
this method for an IPv6 destination server, you use the v6NetMaskLen parameter. In the configuration utility, text boxes
for setting these parameters appear when you select the Destination IP Hash method.
To configure the destination IP hash method, see Configuring a Load Balancing Method that Does Not Include a Policy.
A load balancing virtual server configured to use the source IP hash method uses the hashed value of the client IPv4 or IPv6
address to select a service. To direct all requests from source IP addresses that belong to a particular network to a specific
destination server, you must mask the source IP address. For IPv4 addresses, use the netMask parameter. For IPv6
addresses, use the v6NetMaskLength parameter.
To configure the source IP hash method, see Configuring a Load Balancing Method that Does Not Include a Policy.
A load balancing virtual server configured to use the source IP destination IP hash method uses the hashed value of the
source and destination IP addresses (either IPv4 or IPv6) to select a service. Hashing is symmetric; the hash-value is the
same regardless of the order of the source and destination IPs. T his ensures that all packets flowing from a particular client
to the same destination are directed to the same server.
To direct all requests that belong to a particular network to a specific destination server, you must mask the source IP
address. For IPv4 addresses, use the netMask parameter. For IPv6 addresses, use the v6NetMaskLength parameter.
To configure the source IP destination IP hash method, see see Configuring a Load Balancing Method that Does Not
Include a Policy.
A load balancing virtual server configured to use the source IP source port hash method uses the hash value of the source
IP (either IPv4 or IPv6) and source port to select a service. T his ensures that all packets on a particular connection are
directed to the same service.
T his method is used in connection mirroring and firewall load balancing. For more information about connection mirroring,
see Connection Failover.
To direct all requests that belong to a particular network to a specific destination server, you must mask the source IP
address. For IPv4 addresses, use the netMask parameter. For IPv6 addresses, use the v6NetMaskLength parameter.
To configure the source IP source port hash method, see Configuring a Load Balancing Method that Does Not Include a
Policy.
A load balancing virtual server configured to use the call ID hash method uses the hash value of the call ID in the SIP header
to select a service. Packets for a particular SIP session are therefore always directed to the same proxy server.
To configure the call ID hash method, see Configuring a Load Balancing Method that Does Not Include a Policy.
Consider three services, Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3.
T he following diagram illustrates how the virtual server uses the least bandwidth method to forward requests to the three
services.
T he virtual server selects the service by using the bandwidth value (N), which is the sum of the number of bytes transmitted
and received over the previous 14 seconds. If each request requires 1 Mbps bandwidth, the NetScaler appliance delivers
requests as follows:
Service-HT T P-3 receives the first request, because this service has the lowest N value.
Since Service-HT T P-1 and Service-HT T P-3 now have same N value, the virtual server switches to the round robin method
for these servers, alternating between them. Service-HT T P-1 receives the second request, Service-HT T P-3 receives the
third request, Service-HT T P-1 receives the fourth request, Service-HT T P-3 receives the fifth request, and Service-HT T P-1
receives the sixth request.
Since Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 now all have same N value, the virtual server includes Service-
HT T P-2 in the round robin list. T herefore, Service-HT T P-2 receives the seventh request, Service-HT T P-3 receives the
eighth request, and so on.
(N = 2)
Request-2 Service-HT T P- N=4 Service-HT T P-1 and Service-HT T P-3 have the same N values.
1
(N = 3)
(N = 3)
(N = 4)
(N = 4)
Request-6 Service-HT T P- N=6 Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 have the
1 same N values.
(N = 5)
(N = 5)
(N = 5)
Note: If you enable the RT SP NAT option on the virtual server, the NetScaler appliance uses the number of data and
control bytes exchanged to determine the bandwidth usage for RT SP services. For more information about RT SP NAT
As in the preceding example, suppose Service-HT T P-1 is assigned a weight of 2, Service-HT T P-2 is assigned a weight of 3,
and Service-HT T P-3 is assigned a weight of 4. T he NetScaler appliance delivers requests as follows:
Service-HT T P-3 receives the first second, third, fourth, and fifth requests, because this service has the lowest Nw value.
Service-HT T P-1 receives the sixth request, because this service has the lowest Nw value.
Service-HT T P-3 receives the seventh request, because this service has the lowest Nw value.
Service-HT T P-2 receives the eighth request, because this service has the lowest Nw value.
(Nw =
5000)
(Nw =
5000)
(Nw =
7500)
(Nw =
10000)
(Nw =
(Nw =
15000)
(Nw =
15000)
(Nw =
16666.67)
T he following diagram illustrates how the virtual server uses the least bandwidth method when weights are assigned to the
services.
Figure 2. How the Least Bandwidth Load Balancing Method Works When Weights Are Assigned
To configure the least bandwidth method, see Configuring a Load Balancing Method that Does Not Include a Policy.
For example, consider three services, Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3.
T he following diagram illustrates how the NetScaler appliance uses the least packets method to choose a service for each
request that it receives.
T he NetScaler appliance selects a service by using the number of packets (N) transmitted and received by each service in
the last 14 seconds. Using this method, it delivers requests as follows:
Service-HT T P-3 receives the first request, because this service has the lowest N value.
Since Service-HT T P-1 and Service-HT T P-3 now have the same N value, the virtual server switches to the round robin
method. Service-HT T P-1 therefore receives the second request, Service-HT T P-3 receives the third request, Service-
HT T P-1 receives the fourth request, Service-HT T P-3 receives the fifth request, and Service-HT T P-1 receives the sixth
request.
Since Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 all now have same N value, the virtual server switches to the
round robin method for Service-HT T P-2 as well, including it in the round robin list. T herefore, Service-HT T P-2 receives the
seventh request, Service-HT T P-3 receives the eighth request, and so on.
(N = 2)
Request-2 Service-HT T P- N=4 Service-HT T P-1 and Service-HT T P-3 have the same N values.
1
(N = 3)
(N = 3)
(N = 4)
(N = 4)
Request-6 Service-HT T P- N=6 Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 have the
1 same N values.
(N = 5)
(N = 5)
(N = 5)
Note: If you enable the RT SP NAT option on the virtual server, the NetScaler uses the number of data and control packets
to calculate the number of packets for RT SP services. For more information about RT SP NAT option, see Managing RT SP
As in the preceding example, suppose Service-HT T P-1 is assigned a weight of 2, Service-HT T P-2 is assigned a weight of 3,
and Service-HT T P-3 is assigned a weight of 4. T he NetScaler appliance delivers requests as follows:
Service-HT T P-3 receives the first second, third, fourth, and fifth requests, because this service has the lowest Nw value.
Service-HT T P-1 receives the sixth request, because this service has the lowest Nw value.
Service-HT T P-3 receives the seventh request, because this service has the lowest Nw value.
Service-HT T P-2 receives the eighth request, because this service has the lowest Nw value.
(Nw =
5000)
(Nw =
5000)
(Nw =
7500)
(Nw =
10000)
(Nw =
(Nw =
15000)
(Nw =
15000)
(Nw =
16666.67)
T he following diagram illustrates how the virtual server uses the least packets method when weights are assigned.
Figure 2. How the Least Packets Method Works When Weights Are Assigned
To configure the least packets method, see Configuring a Load Balancing Method that Does Not Include a Policy.
For more information about load monitors, see Understanding Load Monitors. T he following diagram illustrates how a load
monitor operates.
T he load monitor uses Simple Network Management Protocol (SNMP) probes to calculate load on each service by sending
an SNMP GET request to the service. T his request contains one or more object IDs (OIDs). T he service responds with an
SNMP GET response, with metrics corresponding to the SNMP OIDs. T he load monitor uses the response metrics, described
below, to calculate the load on the service.
T he load monitor calculates the load on a service by using the following parameters:
Metrics values retrieved through SNMP probes that exist as tables in the NetScaler.
T hreshold value set for each metric.
Weight assigned to each metric.
For example, consider three services, Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3.
If each request uses 10 MB memory, the NetScaler appliance delivers requests as follows:
Service-HT T P-1 receives the first, second, third, fourth, and fifth requests, because this service has the lowest N value.
Service-HT T P-1 and Service-HT T P-2 now have the same load, so the virtual server reverts to the round robin method for
these servers. T herefore, Service-HT T P-2 receives the sixth request, and Service-HT T P-1 receives the seventh request.
Since Service-HT T P-1, Service-HT T P-2, and Service-HT T P-3 all now have same load, the virtual server reverts to the
round robin method for Service-HT T P-3 as well. T herefore, Service-HT T P-3 receives the eighth request.
(N = 20)
Request-2 Service- N = 40
HT T P-1
(N = 30)
(N = 40)
Request-4 Service- N = 60
HT T P-1
(N = 50)
Request-5 Service- N = 70
HT T P-1
(N = 60)
Request-6 Service- N = 80 Service-HT T P-2 and Service-HT T P-3 have the same
HT T P-1 N values.
(N = 70)
Request-7 Service- N = 80
HT T P-2
(N = 70)
(N = 80)
If different weights are assigned to the services, the custom load algorithm considers both the load on each service and
the weight assigned to each service. It selects a service by using the value (Nw) in the following expression:
As in the preceding example, suppose Service-HT T P-1 is assigned a weight of 4, Service-HT T P-2 is assigned a weight of 3,
and Service-HT T P-3 is assigned a weight of 2. If each request uses 10 MB memory, the NetScaler appliance delivers
requests as follows:
Service-HT T P-1 receives the first, second, third, fourth, fifth, sixth, seventh, and eighth requests, because this service has
the lowest Nw value.
Service-HT T P-2 receives the ninth request, because this service has the lowest Nw value.
Service-HT T P-3 has the highest Nw value, and is therefore not considered for load balancing.
(Nw =
50000)
(Nw = 5000)
(Nw =
15000)
(Nw =
20000)
(Nw =
23333.34))
(Nw =
25000)
(Nw =
23333.34)
(Nw =
233333.34)
Service-HT T P-1 is selected for load balancing when it completes its active transactions or when the Nw value of other
services (Service-HT T P-2 and Service-HT T P-3) is equal to 400,000.
T he following diagram illustrates how the NetScaler appliance uses the custom load method when weights are assigned.
Figure 3. How the Custom Load Method Works When Weights Are Assigned
To configure the custom load method, see Configuring a Load Balancing Method that Does Not Include a Policy.
For the static proximity method to work, you must either configure the NetScaler appliance to use an existing static
proximity database populated through a location file or add custom entries to the static proximity database. After adding
custom entries, you can set their location qualifiers. After configuring the database, you are ready to specify static
proximity as the load balancing method.
At the command prompt, type the following commands to configure static proximity and verify the configuration:
Example
show lb vserver
1. Navigate to T raf f ic Managemen t > Load Balancing > Virt ual Servers and select the virtual server.
2. Click Edit and exapnd the Met hod section.
3. In the Load Balancing Met hod list, select ST AT ICP ROXIMIT Y .
T his method is content aware; it operates differently for TCP, HT T P, and HT T PS connections. For HT T P or HT T PS services,
the token is found in the HT T P headers, the URL, or the BODY. To locate the token, you specify or create a classic or
advanced expression. For more information on classic or advanced expressions, see Policy Configuration and Reference.
For HT T P services, the virtual server searches for the configured token in the first 24 kilobytes (KB) of the TCP payload. For
non-HT T P (TCP, SSL, and SSL_TCP) services, the virtual server searches for the configured token in the first 16 packets if the
total size of the 16 packets is less than 24 KB. But if the total size of the 16 packets is greater than 24 KB, the NetScaler
searches for the token in the first 24 KB of payload. You can use this load balancing method across virtual servers of
different types to make sure that requests presenting the same token are directed to appropriate services, regardless of
the protocol used.
For example, consider a load balancing setup consisting of servers that contain Web content. You want to configure the
NetScaler appliance to search for a specific string (the token) inside the URL query portion of the request. Server-1 has two
services, Service-HT T P-1 and Service-TCP-1, and Server-2 has two services, Service-HT T P-2 and Service-TCP-2. T he TCP
services are bound to Vserver-LB-2, and the HT T P services are bound to Vserver-LB-1.
If Vserver-LB-1 receives a request with the token AA, it selects the service Service-HT T P-1 (bound to server-1) to process
the request. If Vserver-LB-2 receives a different request with the same token (AA), it directs this request to the service
Service-TCP-1. T he following diagram illustrates this process.
set lb vserver <name> -lbMethod T OKEN -rule <rule> -datalength <length> -dataoffset <offset>
show lb vserver <name>
Example
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, click Method
3. In the Load Balancing Method list, select T oken, and specify an expression.
Note:
T he token method is policy based and requires more configuration than is described here. To configure the token method,
see Configuring the Token Method.
For some hash-based methods, you can mask an IP address to direct requests belonging to the same subnet to the same
server. For more information, see T he Destination IP Hash Method, T he Source IP Hash Method, T he Source IP Destination
IP Hash Method, and T he Source IP Source Port Hash Method.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, click Method, and in the Load Balancing Method list, select a method.
Before you can configure persistence, you need to understand the different types of persistence, how they are used, and
what the implications of each type is. You then need to configure the NetScaler appliance to provide persistent
connections for those Web sites and Web applications that require them.
You can also configure backup persistence, which takes effect in the event that the primary type of persistence configured
for a load balancing virtual server fails. You can configure persistence groups, so that a client transmission to any virtual
server in a group can be directed to a server that has received previous transmissions from the same client.
For information about persistence with RADIUS load balancing, see Configuring RADIUS Load Balancing with Persistence.
If a server participating in a persistence session goes DOWN, the load balancing virtual server uses the configured load
balancing method to select a new service, and establishes a new persistence session with the server represented by that
service. If the server goes OUT OF SERVICE, it continues to process existing persistence sessions, but the virtual server does
not direct any new traffic to it. After the shutdown period elapses, the virtual server ceases to direct connections from
existing clients to the service, closes existing connections, and redirects those clients to new services if necessary.
Depending on the persistence type you configure, the NetScaler appliance might examine the source IPs, destination IPs,
SSL session IDs, Host or URL headers, or some combination of these things to place each connection in the proper
persistence session. It might also base persistence on a cookie issued by the Web server, on an arbitrarily assigned token, or
on a logical rule. Almost anything that allows the appliance to match connections with the proper persistence session and
be used as the basis for persistence.
T he following table summarizes the persistence types available on the NetScaler appliance.
Source IP SOURCEIP. Connections from the same client IP address are parts of the same persistence session.
HT T P Cookie COOKIEINSERT. Connections that have the same HT T P Cookie header are parts of the same
persistence session.
SSL Session ID SSLSESSION. Connections that have the same SSL Session ID are parts of the same persistence
session.
URL Passive URLPASSIVE. Connections to the same URL are treated as parts of the same persistence session.
Custom Server CUSTOMSERVERID. Connections with the same HT T P HOST header are treated as parts of the
ID same persistence session.
Destination IP DEST IP. Connections to the same destination IP are treated as parts of the same persistence
session.
Source and SRCIPDEST IP. Connections that are both from the same source IP and to the same destination IP
RT SP Session ID RT SPSID. Connections that have the same RT SP Session ID are treated as parts of the same
persistence session.
User-Defined RULE. Connections that match a user-defined rule are treated as parts of the same persistence
Rule session.
Depending on the type of persistence that you have configured, the virtual server can support either 250,000 simultaneous
persistent connections or any number of persistent connections up to the limits imposed by the amount of RAM on your
NetScaler appliance. T he following table shows which types of persistence fall into each category.
T able 2. P ersist ence T ypes and Numbers of Simult aneous Connect ions Support ed
P ersist ence T ype Number of Simult aneous P ersist ent Connect ions
Support ed
Source IP, SSL Session ID, Rule, destination IP, source 250 K
IP/destination IP, SIP Call ID, RT SP Session ID
Cookie, URL Server ID, Custom Server ID Memory limit. In case of CookieInsert, if timeout is not 0, the
number of connections is limited by memory.
Some types of persistence are specific to particular types of virtual server. T he following table lists each type of persistence
and indicates which types of persistence are supported on which types of virtual server.
T able 3. Relat ionship of P ersist ence T ype t o Virt ual Server T ype
CALLID NO NO NO NO NO NO NO YES
RT SP ID NO NO NO NO NO NO YES NO
Caut ion : In some circumstances, using persistence based on source IP address can overload your servers. All requests to a
single Web site or application are routed through the single gateway to the NetScaler appliance, even though they are
then redirected to multiple locations. In multiple proxy environments, client requests frequently have different source IP
addresses even when they are sent from the same client, resulting in rapid multiplication of persistence sessions where a
single session should be created. T his issue is called the “Mega Proxy problem.” You can use HT T P cookie-based persistence
instead of Source IP-based persistence to prevent this from happening.
To configure persistence based on Source IP Address, see Configuring Persistence Types T hat Do Not Require a Rule.
Note: If all incoming traffic comes from behind a Network Address T ranslation (NAT ) device or proxy, the traffic appears to
the NetScaler appliance to come from a single source IP address. T his prevents Source IP persistence from functioning
properly. Where this is the case, you must select a different persistence type.
When the NetScaler appliance detects the cookie, it forwards the request to the service IP and port in the cookie,
maintaining persistence for the connection. You can use this type of persistence with virtual servers of type HT T P or
HT T PS. T his persistence type does not consume any NetScaler resources and therefore can accommodate an unlimited
number of persistent clients.
Note: If the client’s Web browser is configured to refuse cookies, HT T P cookie-based persistence will not work. It might be
advisable to configure a cookie check on the Web site, and warn clients that do not appear to be storing cookies properly
that they will need to enable cookies for the Web site if they want to use it.
T he format of the cookie that the NetScaler appliance inserts is:
NSC_XXXX=<ServiceIP ><ServicePort>
where:
NSC_XXXX is the virtual server ID that is derived from the virtual server name.
ServiceIP and ServicePort are encoded representations of the service IP address and service port, respectively. T he IP
address and port are encoded separately.
You can set a time-out value for this type of persistence to specify an inactivity period for the session. When the
connection has been inactive for the specified period of time, the NetScaler appliance discards the persistence session. Any
subsequent connection from the same client results in a new server being selected based on the configured load balancing
method, and a new persistence session being established.
Note: If you set the time-out value to 0, the NetScaler appliance does not specify an expiration time, but sets a session
cookie that is not saved when the client’s browser is shut down.
By default, the NetScaler appliance sets HT T P version 0 cookies for maximum compatibility with client browsers. (Only
certain HT T P proxies understand version 1 cookies; most commonly used browsers do not.) You can configure the appliance
to set HT T P version 1 cookies, for compliance with RFC2109. For HT T P version 0 cookies, the appliance inserts the cookie
expiration date and time as an absolute Coordinated Universal T ime (GMT ). It calculates this value as the sum of the current
GMT time on the appliance and the time-out value. For HT T P version 1 cookies, the appliance inserts a relative expiration
time by setting the “Max-Age” attribute of the HT T P cookie. In this case, the client’s browser calculates the actual
expiration time.
To configure persistence based on a cookie inserted by the appliance, see Configuring Persistence Types T hat Do Not
Require a Rule.
In the HT T P cookie, the appliance by default sets the httponly flag to indicate that the cookie is nonscriptable and should
not be revealed to the client application. T herefore, a client-side script cannot access the cookie, and the client is not
susceptible to cross-site scripting.
Certain browsers, however, do not support the httponly flag and, therefore, might not return the cookie. As a result,
persistence is broken. For browsers that do not support the flag, you can omit the httponly flag in the persistence cookie.
1. Navigate to T raffic Management > Load Balancing > Configure Load Balancing Parameters, and select or clear the
Persistence Cookie HT T POnly Flag.
From release 10.5 build 55.8, you can encrypt the cookie in addition to any SSL encryption.
To encrypt the cookie by using the command line interface, at the command prompt, type:
To encrypt the cookie by using the configuration utility, navigate to Traf fic Management > Change Load Balancing
Parameters, and select Encode Persistence Cookie Values and enter a passphrase in Cookie Passphrase.
Note:
T here are two issues that users should consider before choosing this type of persistence. First, this type of persistence
consumes resources on the NetScaler appliance, which limits the number of concurrent persistence sessions that it can
support. If you expect to support a very large number of concurrent persistence sessions, you might want to choose
another type of persistence.
Second, if the client and the load-balanced server should renegotiate the session ID during their transactions, persistence is
not maintained, and a new persistence session is created when the client’s next request is received. T his may result in the
client’s activity on the website being interrupted and the client might be asked to reauthenticate or restart the session. It
may also result in large numbers of abandoned sessions if the timeout is set to too large a value.
To configure persistence based on SSL session ID, see Configuring Persistence Types T hat Do Not Require a Rule.
Note
SSL session ID persistence is not supported with session tickets.
To support backup persistence for SSL session ID, the NetScaler appliance creates session entries for both source IP and
SSL session ID when a client request is received for the first time. For the subsequent requests containing the same session
ID, the SSL session ID is used. However, when the client and the load-balanced server renegotiate the session, the client
request is forwarded to the same server by using the Source IP persistence and a new SSL Session ID persistence entry is
created.
For information about configuring backup persistence, see Configuring Backup Persistence.
Note: If the AVP number is not defined in Diameter base-protocol RFC 6733, and if the number is nested inside a grouped AVP, you must define a sequence of AVP
numbers (maximum of 3) in parent-to-child order. For example, if persist AVP number X is nested inside AVP Y, which is nested in Z, define the list as Z Y X.
To configure Diameter-based persistence on a virtual server by using the command line interface
Example
For example, if your site provides different types of data, such as images, text, and multimedia, from different servers, you can assign each server a server ID. On the
NetScaler appliance, you specify those server IDs for the corresponding services, and you configure custom server ID persistence on the corresponding load
balancing virtual server. When sending a request, the client inserts the server ID into the URL indicating the required type of data.
In your load balancing setup, assign a server ID to each service for which you want to use the user-defined server ID to maintain persistence. Alphanumeric
server IDs are allowed.
Specify rules, in the default-syntax expression language, to examine the URL queries for the server ID and forward traffic to the corresponding server.
Configure custom server ID persistence.
Note: The persistence time-out value does not affect the Custom Server ID persistence type. There is no limit on the maximum number of persistent clients because
this persistence type does not store any client information.
Example
In a load balancing setup with two services, assign server ID 2345-photo-56789 to Service-1, and server ID 2345-drawing-abb123 to Service-2. Bind these services
to a virtual server named Web11.
set service Service-1 10.102.29.5 -CustomServerID 2345-photo-56789
set service Service-2 10.102.29.6 -CustomServerID 2345-drawing-abb123
On virtual server Web11, enable Custom Server ID persistence.
Create the following expression so that all URL queries containing the string "sid=" are examined.
HTTP.REQ.URL.AFTER_STR("sid=")
Example
When a client sends a request with the following URL to the IP address of Web11, the NetScaler directs the request to Service-2 and honors persistence.
Example
http://www.example.com/index.asp?&sid=2345-drawing-abb123
For more information about default-syntax policy expressions, see the Policy Configuration and Reference.
With destination IP address-based persistence, when the NetScaler appliance receives a request from a new client, it
creates a persistence session based on the IP address of the service selected by the virtual server (the destination IP
address). Subsequently, it directs requests to the same destination IP to the same service. T his type of persistence is used
with link load balancing. For more information about link load balancing, see Link Load Balancing.
T he time-out value for destination IP persistence is the same as that for source IP persistence, described in Persistence
Based on Source IP Address.
To configure persistence based on the destination IP address, see Configuring Persistence Types T hat Do Not Require a
Rule.
With source and destination IP address-based persistence, when the NetScaler appliance receives a request, it creates a
persistence session based on both the IP address of the client (the source IP address) and the IP address of the service
selected by the virtual server (the destination IP address). Subsequently, it directs requests from the same source IP and to
the same destination IP to the same service.
T he time-out value for destination IP persistence is the same as that for source IP persistence, described in Persistence
Based on Source IP Address.
To configure persistence based on both source and destination IP addresses, see Configuring Persistence Types T hat Do
Not Require a Rule.
To configure persistence based on SIP Call ID, see Configuring Persistence Types T hat Do Not Require a Rule.
Note: RT SP Session ID persistence is configured by default on RT SP virtual servers, and you cannot modify that setting.
Sometimes different RT SP servers issue the same session IDs. When this happens, unique sessions cannot be created
between the client and the RT SP server by using only the RT SP session ID. If you have multiple RT SP servers that may issue
the same session IDs, you can configure the appliance to append the server IP address and port to the session ID, creating
a unique token that can be used to establish persistence. T his is called session ID mapping.
To configure persistence based on RT SP Session IDs, see Configuring Persistence Types T hat Do Not Require a Rule.
Important: If you need to use session ID mapping, you must set the following parameter when configuring each service
within the load balancing setup. Also, make sure that no non-persistent connections are routed through the RT SP virtual
server.
URL passive persistence requires configuring an advanced expression that specifies the query element that contains the
server IP address-port information. For more information about classic and advanced policy expressions, see Policies and
Expressions.
T he following expression configures the appliance to examine requests for URL queries that contain the string "urlp=",
extract the server IP address-port information, convert it from a hexadecimal string to an IP and port number, and forward
the request to the service configured with this IP address and port number.
If URL passive persistence is enabled and the above expression is configured, a request with the following URL and server IP
address-port string is directed to 10.102.29.10:80.
http://www.example.com/index.asp?&urlp=0A661D0A0050
T he persistence time-out value does not affect this persistence type; persistence is maintained as long as the server IP
address-port information can be extracted from client requests. T his persistence type does not consume any NetScaler
resources, so it can accommodate an unlimited number of persistent clients.
To configure URL passive persistence, you first configure persistence as described in Configuring Persistence Types T hat Do
Not Require a Rule. You set the persistence type to URLPASSIVE. You then perform the procedures provided below.
Example
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In the Persistence section, choose the persistence type that meets your requirement. T he most suitable persistence
type for the virtual server is available as option buttons. Other persistence types that are applicable to the specific virtual
server type can be selected from the Others list.
Rule based persistence requires a classic or default syntax expression. You can use a classic expression to evaluate request
headers, or you can use a default syntax expression to evaluate request headers, Web form data in a request, response
headers, or response bodies. For example, you could use a classic expression to configure persistence based on the
contents of the HT T P Host header. You could also use a default syntax expression to configure persistence based on
application session information in a response cookie or custom header. For more information on creating and using classic
and default syntax expressions, see Policies and Expressions.
T he expressions that you can configure depends on the type of service for which you are configuring rule based
persistence. For example, certain RADIUS-specific expressions are not allowed for protocols other than RADIUS, and TCP-
option based expressions are not allowed for service types other than the ANY type. For TCP and SSL_TCP service types,
you can use expressions that evaluate TCP/IP protocol data, Layer 2 data, TCP options, and TCP payloads.
Note: For a use case that involves configuring rule based persistence on the basis of Financial Information eXchange ("FIX")
Protocol data transmitted over T CP, see Configuring Rule Based Persistence Based on a Name-Value Pair in a T CP Byte
Stream.
Rule based persistence can be used for maintaining persistence with entities such as Branch Repeater appliances, Branch
Repeater plug-ins, cache servers, and application servers.
Note: On an ANY virtual server, you cannot configure rule-based persistence for the responses.
To configure persistence based on a user-defined rule, you first configure persistence as described in Configuring Persistence
Types T hat Do Not Require a Rule, and set the persistence type to RULE. You then perform the procedures provided below.
You can configure rule based persistence by using the configuration utility or the NetScaler command line.
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In the Persistence section, choose the persistence type that meets your requirement. T he most suitable persistence
type for the virtual server is available as option buttons. Other persistence types that are applicable to the specific virtual
server type can be selected from the Others list.
Examples
Example: Classic Expression f or a Request Payload
T he following classic expression creates a persistence session based on the presence of a User-Agent HT T P header that
contains the string, “MyBrowser”, and directs any subsequent client requests that contain this header and string to the
T he following default syntax expression does exactly the same thing as the previous classic expression.
HT T P.REQ.HEADER("User-Agent").CONTAINS ("MyBrowser")
T he following expression examines responses for “server” cookies, and then directs any requests that contain that cookie
to the same server that was selected for the initial request.
At the command prompt, type the following commands to configure persistence and verify the configuration:
T imeout is the time period for which a persistence session is in effect. Default value: 2. Maximum value: 1440.
Example
show lb vserver
Note: For IP-based persistence, you can also set the persistMask parameter.
To configure persistence on a virtual server by using the NetScaler GUI
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In the Persistence section, choose the persistence type that meets your requirement. T he most suitable persistence
type for the virtual server is available as option buttons. Other persistence types that are applicable to the specific virtual
server type can be selected from the Others list.
Note
T he following table describes the combinations of primary and secondary backup persistence types, and the conditions
when the backup persistence is used.
Primary Backup
When the primary persistence lookup f ails…
persistence persistence
T he appliance falls back to source IP based persistence only when the client browser does not return
Cookie
Source IP any cookie in the request. However, if the browser returns a cookie (not necessarily the persistence
Insert
cookie), it is assumed that the browser supports cookies and hence backup persistence is not triggered.
T he appliance uses source-IP based persistence when the parameter specified in the rule is missing in
Rule Source IP
the incoming request.
Note
If the primary persistence type is HT T P-Cookie based persistence, and the backup persistence type is Source IP-based, you can
set a timeout value for backup persistence. For instructions, see Setting a T imeout Value for Idle Client Connections.
You cannot set a timeout value for backup persistence when the primary persistence is rule based, because in that case the
timeout value for secondary persistence must be the same as for the primary persistence. T herefore, the primary and
secondary expire at the same time.
To set backup persistence f or a virtual server by using the command line interf ace
set lb vserver <name> -persistenceT ype <PersistenceT ype> -persistenceBackup <BackupPersistenceT ype>
Example COPY
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, select Persistence, and specify a backup persistence type.
You can configure either source IP-based persistence or HT T P cookie-based persistence for persistence groups. After you
set persistence for the entire group, you cannot change it for individual virtual servers in the group. If you configure
persistence on a group and then add a new virtual server to the group, the persistence of the new virtual server is changed
to match the persistence setting of the group.
When persistence is configured on a group of virtual servers, persistence sessions are created for initial requests, and
subsequent requests are directed to the same service as initial request, regardless of the virtual server in the group that
receives each client request.
If you configure HT T P cookie-based persistence, the domain attribute of the HT T P cookie is set. T his setting causes the
client software to add the HT T P cookie into client requests if different virtual servers have different public host names. For
more information about CookieInsert persistence type, see Persistence Based on HT T P Cookies.
To create a virtual server persistency group by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Persistency Groups, create a persistency group, and specify the
virtual servers that must be part of this group.
To modif y a virtual server group by using the command line interf ace
Previously, persistence entries were local to the vserver. If you had to apply persistence across multiple vservers, you had to
add the vservers to a load balancing group and then apply a common persistence type to the group. T he above requirement
could not be achieved, because all the vservers bound to a load balancing group inherited the persistency configured on the
group.
With the persistency sharing between vservers feature, you can set the new useVserverPersistency parameter for a load
balancing group to allow the vservers in the group to use their own persistency parameters instead of inheriting them from
the group settings. You can configure separate rule-based persistency on each vserver.
Optionally, you can also designate one of the vservers in the group as a master vserver. When a vserver is designated as a
master vserver, only that vserver creates the persistence entries, which are used by all the vservers in the group. If the
master vserver is down, the NetScaler appliance does not create any new persistence entries.
Note: Persistence sharing across vservers is supported only for rule based persistency methods. You must configure
compatible rule based persistence parameters on the member virtual servers.
Example
Assume v1 and v2 are bound to a load balancing group, v1 is a RADIUS type vserver and v2 is an HT T P type vserver.
‘Radius.req.avp(8).value.typecast_text_t’ persistency is configured on v1 and ‘client.ip.src’ is configured on v2.
When traffic flows through the RADIUS vserver v1, it creates a persistent entry based on the evaluated rule string. Later,
when traffic reaches the HT T P type vserver v2, v2 checks for the persistence entries on the load balancing group and uses
the same persistence session to direct traffic to the same back-end server.
To share persistency parameters across vservers in a load balancing group, you must first enable the useVserverPersistency
parameter and then designate one of the vservers in the group as a master server.
Example
To designate a vserver as a master vserver by using the command line interf ace
Example
1. Navigate to Conf iguration > Traf f ic Management > Load Balancing > Persistency Groups.
2. Click Add to add a new group or select an existing group and click Edit.
3. Select Use Vserver Persistence.
4. In the Virtual Server Name box, click + to add the vservers to the group. You can select the available vservers or create
new vservers.
5. Click Create if you are adding a new group or Close if you are modifying an existing group.
6. Select the group for which you have enabled the useVserverPersistency parameter and click Edit to set a vserver as a
master to create persistence entries.
7. From the Master vServer list, select the vserver that has to be designated as a master vserver.
Arguments
useVserverPersistency
Allow the virtual servers in a group to use their own persistency parameters to create persistent sessions, instead of
inheriting the persistency settings from the group settings. When this parameter is enabled, persistence cannot be set on
the load balancing group.
When this parameter is disabled, the group's virtual servers inherit the persistency parameters from the group settings.
When this parameter is toggled on the load balancing group, the NetScaler appliance flushes all the corresponding
persistence entries of the group and the member virtual servers.
Default: DISABLED
Example
masterVserver
Designate a virtual server as a master virtual server in its load balancing group. Once designated, only the master virtual
server can create the persistent entries used by the group.
Note: T his parameter can be set only if the useVserverPersistency parameter is enabled.
Example Configuration of Sharing Persistent Sessions by Using the Command Line Interf ace
For more details, see Setting Up Basic Load Balancing and Configuring Persistence Groups.
If you configure RADIUS load balancing on the NetScaler appliance to support persistent client connections to RADIUS
authentication servers, the appliance uses the user logon or the specified RADIUS attribute instead of the client IP as the
session ID, directing all connections and records associated with that user session to the same RADIUS server. Users are
therefore able to log on to your VPN from mobile access locations without experiencing disconnections when the client IP
or WiFi access point changes.
To configure RADIUS load balancing with persistence, you must first configure RADIUS authentication for your VPN. For
information and instructions, see the Authentication, Authorization, Auditing (AAA) chapter in AAA Application Traffic. You
must also choose either the Load Balancing or Content Switching feature as the basis for your configuration, and make
sure that the feature you chose is enabled. T he configuration process with either feature is almost the same.
T hen, you configure either two load balancing, or two content switching, virtual servers, one to handle RADIUS
authentication traffic and the other to handle RADIUS accounting traffic. Next, you configure two services, one for each
load balancing virtual server, and bind each load balancing virtual server to its service. Finally, you create a load balancing
persistency group and set the persistency type to RULE.
To configure RADIUS load balancing with persistence, see the following sections:
To use the Load Balancing or Content Switching feature, you must first ensure that the feature is enabled. If you are
configuring a new NetScaler appliance that has not previously been configured, both of these features are already enabled,
so you can skip to the next section. If you are configuring a NetScaler appliance with a previous configuration on it, and
you are not certain that the feature you will use is enabled, you must do that now.
For instructions on enabling the load balancing feature, see Enabling Load Balancing.
For instructions on enabling the content switching feature, see Enabling Content Switching.
After enabling the load balancing or content switching feature, you must next configure two virtual servers to support
RADIUS authentication:
RADIUS authentication virtual server. T his virtual server and its associated service will handle authentication traffic to
your RADIUS server. Authentication traffic consists of connections associated with users logging onto your protected
Important: You must create either a pair of load balancing virtual servers or a pair of content switching virtual servers to use
in your RADIUS persistence configuration. You cannot mix virtual server types.
To configure a load balancing virtual server by using the command line interface
At the command prompt type the following commands to create a new load balancing virtual server and verify the
configuration:
add lb vserver <name> RADIUS <IP address> <port> -lbmethod T OKEN -rule <rule>
show lb vserver <name>
To configure an existing load balancing virtual server, replace the above add lb virtual server command with the set lb vserver
command, which takes the same arguments.
add cs vserver <name> RADIUS <IP address> <port> -lbmethod T OKEN -rule <rule>
show cs vserver <name>
To configure an existing content switching virtual server, replace the above add cs vserver command with the set cs
vserver command, which takes the same arguments.
Example
add lb vserver radius_auth_vs1 RADIUS 192.168.46.33 1812 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
add lb vserver radius_acct_vs1 RADIUS 192.168.46.34 1813 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
set lb vserver radius_auth_vs1 RADIUS 192.168.46.33 1812 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
set lb vserver radius_auth_vs1 RADIUS 192.168.46.34 1813 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
Configuring Services
After configuring your virtual servers, you must next configure two services, one for each of the virtual servers that you
created. For instructions, see Configuring Services.
Note: Once configured, these services are in the DISABLED state until the NetScaler appliance can connect to your RADIUS
After configuring your services, you must next bind each of the virtual servers that you created to the appropriate service.
For instructions, see Binding Services to the Virtual Server.
After binding your load balancing virtual servers to the corresponding services, you must set up your RADIUS load balancing
configuration to support persistence. To do so, you configure a load balancing persistency group that contains your RADIUS
load balancing virtual servers and services, and configure that load balancing persistency group to use rule-based
persistence. A persistency group is required because the authentication and accounting virtual servers are different and
both the authentication & accounting message for a single user should reach the same RADIUS server. By configuring a
persistency group, the same session is used for both virtual servers. For instructions, see Configuring Persistence Groups.
From release 12.0, a NetScaler appliance supports RADIUS shared secret. A RADIUS client and server communicate with
each other by using a shared secret that is configured on the client and on the server. Transactions between a RADIUS
client and server are authenticated through the use of a shared secret. T his secret is also used to encrypt some of the
information in the RADIUS packet.
T he validation of the RADIUS shared secret key happens in the following scenarios:
RADIUS shared secret key is conf igured f or both the radius client and the radius server: T he NetScaler appliance
uses the RADIUS secret key for both the client side and the server side. If the verification succeeds, the appliance allows
the RADIUS message to go through. Otherwise, it drops the RADIUS message.
RADIUS shared secret key is not conf igured f or either the radius client or the radius server: T he NetScaler
appliance drops the RADIUS message, because shared-secret-key validation cannot be performed on a node that has no
radkey configured.
RADIUS shared secret key is not conf igured f or both the RADIUS client and the RADIUS server: T he NetScaler
appliance bypasses the RADIUS secret key validation and allows the RADIUS messages to go through.
You can configure a default RADIUS shared secret or configure on a per client or a subnet basis. It is recommended to add a
RADIUS shared secret key for all deployments with RADIUS policy configured. T he appliance uses the source IP address of
the RADIUS packet to decide which shared secret to use. You may configure a RADIUS client and server and the
corresponding shared secret as follows:
Arguments
IPaddress
IP address or subnet of the RADIUS client in CIDR format. T he appliance uses the source IP address of an incoming
request packet to match the client IP address. Instead of configuring a client IP address, you can configure the client
network address. Longest prefix is matched to identify the shared secret for an incoming client request.
Shared secret between the client, NetScaler appliance, and the server. Maximum length: 31.
Example COPY
add lb vserver radius_auth_vs1 RADIUS 192.168.46.33 1812 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
add lb vserver radius_acct_vs1 RADIUS 192.168.46.34 1813 -lbmethod TOKEN -rule CLIENT.UDP.RADIUS.USERNAME
A shared secret must be configured both for a RADIUS client and server. T he command is the same. T he subnet determines
whether the shared secret is for a client or for a server.
For example, if the subnet specified is a client subnet, the shared secret is for the client. If the subnet specified is a server
subnet (192.168.41.0/24 in the above example), the shared secret is for the server.
A subnet of 0.0.0.0/0 implies that it is the default shared secret for all clients and servers.
Note
Only the PAP and CHAP authentication methods are supported with RADIUS shared secret.
Note: A NetScaler nCore appliance uses multiple CPU cores for packet handling. Every session on the appliance is owned by
a CPU core. If the appliance receives a request for which a session does not already exist, a session is created, and one of
the cores is designated as the owner of that session. Subsequent requests that belong to that session might not always
arrive at and be handled by the owner core. In that case, inter-core messaging ensures that the session information on the
owner core is always current. However, when a core receives a request that belongs to a persistence session owned by
another core, the inter-core messaging does not refresh the timeout value for the persistence session. Consequently, in the
output of successively executed show lb persistentSessions commands, which display timeout values from owner cores
only, the timeout value for a persistence session might diminish to 0 (zero), even if the persistence session continues to be
active.
To view a persistence session by using the command line interf ace
At the command prompt, type the following commands to clear persistence sessions and verify the configuration:
Examples
Example 1 clears all persistence sessions for load balancing virtual server lbvip1. Example 2 first displays the persistence
sessions for load balancing virtual server lbvip1, clears the session with persistence parameter xls, and then displays the
persistence sessions to verify that the session was cleared.
Example
> clear persistentSessions lbvip1
Done
> show persistentSessions
Done
>
Example 2
> show persistentSessions lbvip1
Type SRC-IP ... PERSISTENCE-PARAMETER
RULE 0.0.0.0 ... xls
RULE 0.0.0.0 ... txt
RULE 0.0.0.0 ... html
Done
> clear persistentSessions lbvip1 -persistenceParam xls
Done
> show persistentSessions lbvip1
Type SRC-IP ... PERSISTENCE-PARAMETER
RULE 0.0.0.0 ... txt
RULE 0.0.0.0 ... html
Done
>
To clear persistence sessions by using the configuration utility
In Branch Repeater load balancing configurations, you must also configure a load monitor and bind it to the service. T he
monitor takes the service out of subsequent load balancing decisions until the load on the service is brought below the
configured threshold. For information about configuring a load monitor for your virtual server, see Understanding Load
Monitors.
You can configure the virtual server to perform one of the following actions with the requests that would otherwise form
a part of the persistence session:
Send each request to one of the other services. T he virtual server takes a load balancing decision and sends each
request to one of the other services on the basis of the configured load balancing method. If all the services are
overloaded, requests are dropped until a service becomes available.
Both wildcard and IP address– based virtual servers support this option. T his action is appropriate for all deployments,
including deployments in which the virtual server is load balancing Branch Repeater appliances or firewalls.
Bypass the virtual server-service conf iguration. T he virtual server does not take a load balancing decision. Instead, it
simply bridges each request through to a physical server on the basis of the destination IP address in the request.
Only wildcard virtual servers of type ANY and UDP support the bypass option. Wildcard virtual servers have a *:* IP and
port combination. T his action is appropriate for deployments in which you are using the virtual server to load balance
Branch Repeater appliances or firewalls. In these deployments, the NetScaler appliance first forwards a request to a
Branch Repeater appliance or firewall, and then forwards the processed response to a physical server. If you configure
the virtual server to bypass the virtual server– service configuration for overloaded services, if a Branch Repeater
appliance or firewall gets overloaded, the virtual server bridges requests directly to their destination IP addresses until the
Branch Repeater appliance or firewall can accept requests.
To override persistence settings f or overloaded services by using the command line interf ace
At the command prompt, type the following commands to override persistence settings for overloaded services and verify
the configuration:
Example
> set lb vserver mylbvserver -skippersistency ReLb
1. Navigate to T raffic Management > Load Balancing > Virtual Servers and select the virtual server of type UDP or ANY.
2. In the Advanced Settings pane, select T raffic Settings, and specify the type of Skip Persistency.
Resolution: T o resolve this issue, you can perform any of the following tasks:
Reduce the time out value for persistence
Increase the number of cores for the appliance
Af ter conf iguring Cookie Insert persistence on the NetScaler appliance, the users report that the connections
work f ine f or some time, but then start getting disconnected. What best practice should I f ollow when
conf iguring persistence?
Cause: By default, the time-out value for Cookie Insert persistence is 120 seconds.
Resolution: When you configure persistence for applications for which idle time cannot be determined, set the Cookie
Insert persistence time-out value to 0. With this setting, the connection does not time out.
Af ter conf iguring an HTTP virtual server on the NetScaler appliance, I need to make sure that a user always
connects to the same server f or the requested content, so I conf igured SourceIP persistence. Now, increasing
the time-out value f or persistence introduces latency. How can I increase the timeout value without af f ecting
perf ormance?
Resolution: Consider using Cookie Insert persistence with the time-out value set to 0. T his setting enables long-duration
persistence settings, because the appliance does not specify a time for expiring the cookie.
Af ter conf iguring Cookie Insert persistence on the NetScaler appliance, it works as expected when clients f rom
the same time zone access the content. However, when a client f rom another time zone makes an attempt to
connect, the connection is immediately timed out.
Cause: T ime based Cookie Insert persistence works as expected when a client from the same time zone makes a
connection. However, when the client machine and NetScaler appliance are in different time zones, the cookie is not valid.
For example, when a client in EST time zone sends a cookie at 11:00 AM EST to a NetScaler appliance in the PST time zone,
the appliance receives the cookie at 2:00 PM PST. As a result of the difference in time, the cookie is not valid, and the
connection is immediately timed-out.
A NetScaler appliance is used to load balance application servers, such as Oracle Weblogic server. To make sure
that clients get persistent connections to these servers, SourceIP persistence is conf igured. It works as expected
when a connection is made f rom a computer. However, when thin clients attempt a connection through a
terminal server and, as a result, the appliance receives requests f rom multiple clients f rom the same IP address
(the terminal server IP address). Theref ore, the connections f rom all thin clients are directed to the same
application server. Is it possible to conf igure persistency f or requests f rom individual thin clients based on the
client IP address?
Cause: T he NetScaler appliance receives requests from the terminal server and the source IP address of the request
remains the same. As a result, the appliance cannot distinguish among the requests received from the thin clients and
provide persistence according to the requests from thin clients.
The NetScaler appliance is used to load balance Web Interface servers. When accessing the servers, the user receives the “State Error” error message.
Additionally, when one of the Web Interface servers is shut down or not available, some of the users receive an error message.
Cause: Lack of persistence to the Web Interface servers can result in error messages when a user attempts to connect to the server.
Resolution: Citrix recommends that you specify the Cookie Insert persistence method on the NetScaler appliance when load balancing Web Interface servers.
T he default load balancing algorithm on the NetScaler appliance is the least connection method, which configures the
appliance to send each incoming connection to the service that is currently handling the fewest connections. You can
specify different load balancing algorithms, each of which is suited to different conditions.
To accommodate applications such as shopping carts, which require that all requests from the same user be directed to the
same server, you can configure the appliance to maintain persistent connections between clients and servers. You can also
specify persistence for a group of virtual servers, causing the appliance to direct individual client requests to the same
service regardless of which virtual server in the group receives the client request.
You can enable and configure the redirection mode that the appliance uses when redirecting user requests, choosing
between IP-based and MAC-based forwarding. You can assign weights to different services, specifying what percentage of
incoming load should be directed to each service, so that you can include servers with different capacities in the same load
balancing setup without overloading the lower-capacity servers or allowing the higher-capacity servers to sit idle.
As an alternative to using the port number to generate the hash value, you can specify a unique hash identifier for each
service. For a service, the same hash identifier value must be specified on all the virtual servers. If a physical server serves
more than one type of application, each application type should have a unique hash identifier.
T he algorithm for computing the hash value for a service works as follows:
By default, a global setting specifies the use of port number in a hash calculation.
If you configure a hash identifier for a service, it is used, and the port number is not, regardless of the global setting.
If you do not configure a hash identifier, but change the default value of the global setting so that it does not specify
use of the port number, the hash value is based only on the IP address of the service.
If you do not configure a hash identifier or change the default value of the global setting to use the port number, the
hash value is based on the IP address and the port number of the service.
You can also specify hash identifiers when using the NetScaler command line to bind services to a service group. In the
configuration utility, you can open a service group and add hash identifiers on the Members tab.
To change the use-port-number global setting by using the command line interf ace
Example
> set lb parameter -usePortForHashLb NO
Done
>show lb parameter
Global LB parameters:
Persistence Cookie HttpOnly Flag: DISABLED
Use port for hash LB: NO
Done
To change the use-port-number global setting by using the configuration utility
1. Navigate to T raffic Managment > Load Balancing > Configure Load Balancing parameters.
2. Select or clear Use Port for Hash Based LB Methods.
To create a new service and specif y a hash identifier f or a service by using the command line interf ace
At the command prompt, type the following commands to set the hash ID and verify the setting:
Example
Done
To specif y a hash identifier f or an existing service by using the command line interf ace
Type the set service command, the name of the service, and -hashID followed by the ID value.
To specify a hash identifier for each member to be added to the group and verify the setting, at the command prompt, type
the following commands (Be sure to specify a unique hashID for each member.):
Example
1) 1.1.1.1:80 State: DOWN Server Name: 1.1.1.1 Server ID: 123 Weight: 1
Hash Id: 32211
To specif y a hash identifier f or an already configured service group member by using the configuration
utility
You can configure MAC-Based forwarding on networks that use direct server return (DSR) topology, link load balancing, or
firewall load balancing. For more information on MAC-Based forwarding, see Configuring MAC-Based Forwarding.
To configure the redirection mode by using the command line interf ace
Note
For a service that is bound to a virtual server on which -m MAC option is enabled, you must bind a non-user monitor.
To configure a wildcarded virtual server that listens to a specific VLAN by using the command line interf ace
At the command prompt, type the following commands to configure a wildcarded virtual server that listens to a specific
VLAN and verify the configuration:
add lb vserver <name> <serviceT ype> IPAddress * Port * -listenpolicy <expression> [-listenpriority <positive_integer>]
show vserver
Example
After you have created this virtual server, you bind it to one or more services as described in Setting Up Basic Load Balancing.
Note: If you use a load balancing method that supports weighting of services (for example, the round robin method), you
can assign a weight to the service.
T he following table describes the load balancing methods that support weighting, and briefly describes the manner in which
weighting affects how a service is selected for each one.
Round Robin T he virtual server prioritizes the queue of available services such that services with the highest
weights come to the front of the queue more frequently than those with the lowest weights
and receive proportionately more traffic. For a complete description, see T he Round Robin
Method.
Least Connection T he virtual server selects the service with the best combination of fewest active transactions
and highest weight. For a complete description, see T he Least Connection Method.
Least Response T ime T he virtual server selects the service with the best combination of fewest active transactions
and Least Response and fastest average response time. For a complete description, see T he Least Response T ime
T ime Method using Method.
Monitors
Least Bandwidth T he virtual server selects the service with the best combination of least traffic and highest
bandwidth. For a complete description, see T he Least Bandwidth Method.
Least Packets T he virtual server selects the service with the best combination of fewest packets and highest
weight. For a complete description, see T he Least Packets Method.
Custom Load T he virtual server selects the service with the best combination of lowest load and highest
weight. For a complete description, see T he Custom Load Method.
Hashing methods and Weighting is not supported by these load balancing methods.
Token method
To configure a virtual server to assign weights to services by using the command line interf ace
To set the Microsof t SQL Server version parameter by using the command line interf ace
At the command prompt, type the following commands to set the Microsoft SQL Server version parameter for a load
balancing virtual server and verify the configuration:
Example
> set lb vserver myMSSQLvip -mssqlServerVersion 2008R2
Done
> show lb vserver myMSSQLvip
myMSSQLvip (190.0.2.12:1433) - MSSQL Type: ADDRESS
...
...
MSsql Server Version: 2008R2
...
...
Done
>
To set the MySQL Server version parameter by using the command line interf ace
At the command prompt, type the following commands to set the MySQL Server version parameter for a load balancing
virtual server and verify the configuration:
Example
> set lb vserver mysqlsvr -mysqlserverversion 5.5.30
Done
> sh lb vserver mysqlsvr
mysqlsvr (2.22.2.222:3306) - MYSQL Type: ADDRESS
...
...
Mysql Server Version: 5.5.30
...
...
When Diameter messages are exchanged, the Diameter server usually does much more processing than does the Diameter
client. With the increase in control plane signaling volume, the Diameter server becomes a bottleneck. T herefore, Diameter
messages must be load balanced to multiple servers. A virtual server performing load balancing of Diameter messages
provides the following benefits:
Lighter load on Diameter servers, which translates to faster response time to end users.
Server health monitoring and better failover capabilities.
Better scalability in terms of server addition without changing client configuration.
High availability.
SSL-Diameter offloading.
Diameter client. Supports Diameter client applications in addition to the base protocol. Diameter clients are often
implemented in devices situated at the edge of a network and provide access control services for that network. T ypical
examples of Diameter clients are a Network Access Server (NAS) and the Mobile IP Foreign Agent (FA).
Diameter agent. Provides relay, proxy, redirect, or translation services. T he NetScaler appliance (configured with a
Diameter load balancing virtual server) plays the role of a Diameter agent.
Diameter server. Handles the authentication, authorization, and accounting requests for a particular realm. A Diameter
server must support Diameter server applications in addition to the base protocol.
In a typical Diameter topology, when an end-user device (such as a mobile phone) needs a service, it sends a request to a
Example
A mobile service provider uses Diameter for its billing system. When a subscriber uses a prepaid number, the Diameter client
repeatedly sends requests to the server to check the available balance. T he Diameter protocol establishes a connection
between the client and the server, and all requests are exchanged over that connection. Connection based load balancing
would be pointless, because there is only one connection. However, with the large number of messages on the connection,
message based load balancing expedites the process of billing the prepaid mobile subscriber.
A Diameter client opens a connection to the NetScaler appliance and sends a Diameter capability exchange (CER) message.
Diameter messages are composed of command codes and each command has a set of Attribute-Value Pairs (AVPs), such as
Origin-Host and Host-IP-Address.
T he NetScaler selects a Diameter server, opens a connection to the server, and forwards the CER message to the server.
T he server reads the client identity and determines that it is directly connected to the client.
T he Diameter server prepares the Diameter handshake reply and sends it to the NetScaler appliance. T he appliance
modifies the handshake and inserts its own identity. At this point, the Diameter client determines that it is directly
connected to the NetScaler (the agent).
Note: Until the Diameter handshake is complete, all Diameter request messages from the client are queued on the selected
server. T he packets are forwarded to the server when the handshake is complete.
Load Balancing Diameter Traf fic
When a client sends a request to the NetScaler appliance, the appliance parses the request and contextually load balances
it to a Diameter server on the basis of a persist AVP. T he NetScaler has advertised the client identity to the server, so it does
not add route entries, because the server is expecting messages directly from client.
Server initiated requests are not as frequent as client requests. Server initiated requests are similar to client initiated
requests, except:
Since messages are received from multiple servers, the NetScaler maintains the transaction state by adding a unique Hop
by Hop (HbyH) number to each forwarded request message. When the message response arrives (with same HbyH
number), the appliance translates this HbyH number to the HbyH number that was received on the server when the
request arrived.
NetScaler adds a route entry by putting its identity, because the client sees the NetScaler as a relay agent.
Note: If a Diameter message spans more than one packet, the NetScaler accumulates the packets in an incomplete header
queue and forwards them to the server when the full message is accumulated. Similarly, if a single packet contains more
than one Diameter message, the NetScaler splits the packet and forwards the messages to servers as determined by the
load balancing virtual server.
Disconnecting a Session
A Disconnect Peer Request (DPR) indicates the peer's intention of closing the connection, with the reason for closing the
connection. T he peer replies with a DPA (TCP always provides successful DPA).
To configure the NetScaler appliance to load balance Diameter traffic, you must first set the Diameter parameters on the
appliance, then add the Diameter monitor, add the Diameter services, bind the services to the monitor, add the Diameter
load balancing virtual server, and bind the services to the virtual server.
To configure load balancing for Diameter traffic by using the command line
interface
1. Configure the Diameter parameters.
set ns diameter -identity <string> -realm <string> -serverClosePropagation <YES|NO>
Example
set ns diameter -identity mydomain.org -realm org -serverClosePropagation YES
2. Add a Diameter monitor.
add lb monitor <monitorName> DIAMET ER -originHost <string> -originRealm <string>
Example
add lb monitor diameter_mon DIAMETER -originHost mydomain.org -originRealm org
3. Create the Diameter services.
add service <name> <IP> DIAMET ER <port>
Example
add service diameter_svc0 10.102.82.86 DIAMETER 3868
add service diameter_svc1 10.102.82.87 DIAMETER 3868
add service diameter_svc2 10.102.82.88 DIAMETER 3868
add service diameter_svc3 10.102.82.89 DIAMETER 3868
4. Bind the Diameter services to the Diameter monitor.
bind service <name>@ monitorName <monitorName>
-Example
bind service diameter_svc0 -monitorName diameter_mon
bind service diameter_svc1 -monitorName diameter_mon
bind service diameter_svc2 -monitorName diameter_mon
bind service diameter_svc3 -monitorName diameter_mon
5. Add a Diameter load balancing virtual server with Diameter persistence.
add lb vserver <name> DIAMET ER <IPAddress> <port> -persistenceType DIAMET ER -persistAVPno <positive_integer>
Example
bind lb vserver diameter_vs diameter_svc0
bind lb vserver diameter_vs diameter_svc1
bind lb vserver diameter_vs diameter_svc2
bind lb vserver diameter_vs diameter_svc3
7. Save the configuration.
save ns config
Note: You can also configure load balancing of Diameter traffic over SSL by using the SSL_DIAMETER service type.
To configure load balancing for Diameter traffic by using the configuration utility
1. Navigate to System > Settings > Change Diameter Parameters and set the diameter parameters.
2. Navigate to T raffic Management > Load Balancing > Virtual Servers, and create a load balancing virtual server of type
Diameter.
3. Create a service of type Diameter.
4. Create a monitor of type Diameter. In Special parameters, set the origin host and origin realm.
5. Bind the monitor to the service, and bind the service to the Diameter virtual server.
6. In Advanced Settings, click Persistence, specify Diameter and enter a persistence AVP number.
7. Click Save, and click Done.
T his feature enables you to configure a FIX or SSL_FIX load balancing virtual server to distribute incoming FIX messages and
provide security in FIX messaging. NetScaler supports FIX message based load balancing (MBLB) for FIX 4.1, FIX 4.2, FIX 4.3
and FIX 4.4 versions.
1. Efficient management of FIX or SSL_FIX servers with superior HA and health monitoring.
2. SYN protection to all FIX or SSL_FIX servers.
3. FIX session persistence.
A FIX MBLB setup includes a FIX load-balancing virtual server and multiple load-balanced FIX servers. T he FIX virtual server
receives incoming client traffic, parses the incoming traffic into FIX messages, selects a FIX server for each FIX message and
forwards the message to the selected FIX server. T he following conceptual drawing illustrates a typical FIX load balancing
set up.
In a basic FIX MBLB setup, the FIX virtual server distributes FIX messages coming from clients to the load-balanced FIX
servers using the round robin load-balancing method. With persistence of type FIXSESSION enabled, the FIX virtual server
selects the same server for different FIX messages belonging to the same FIX session. T he FIX session is determined based
on the values of FIX fields SenderCompID (tag 49) and TargetCompID (tag 56).
Following are the configurations that you must do to load balance FIX message traffic:
To configure a FIX load balancing server by using the command line interface
At the command prompt, type:
Example
To configure a SSL_FIX load balancing virtual server by using the command line
interface
At the command prompt, type:
AExample
Example
Example
Example
Example
Example
stat lb vserver_svc1
To bind FIX service to FIX virtual server by using the command line interface
At the command prompt, type:
T o bind FIX service to FIX virtual server by using the command line interface COPY
Example
To display FIX persistent sessions by using the command line interf ace
Example
Note
Note: You can now configure the load balancing of FIX traffic over SSL by using the SSL_FIX service type. T his service provides
secured communication for FIX messages.
To configure FIX load balancing virtual server by using the NetScaler GUI
1. Navigate to the Conf iguration > Traf f ic Management > Load Balancing > Virtual Servers page and click Add to
create a FIX Load Balancing virtual server.
2. On the Load Balancing Virtual Server page, set the server parameters:
1. Virtual Server Name
2. Protocol type as "FIX"
3. Server IP Address T ype
4. Server IP Addres
5. Server Port Number
3. Click OK and Continue to set additional parameters.
4. In the Services section, select or add a new FIX load balancing virtual service, and bind it to the FIX server.
5. In the Persistence section, set the following parameters:
1. Persistence type as ‘FIXSESSION’
2. T ime-out interval
6. Click OK and then Done.
To edit a FIX load balancing virtual server by using the NetScaler GUI
Navigate to Configuration > Traf fic Management > Load Balancing > Virtual Servers page, select a FIX server and click
Edit.
To delete a FIX load balancing virtual server by using the NetScaler GUI
Navigate to Configuration > Traf fic Management > Load Balancing > Virtual Servers page, select a FIX server and click
Delete.
To configure FIX Load Balancing Virtual Service by using the NetScaler GUI
To edit a FIX load balancing virtual service by using the NetScaler GUI
Navigate to Configuration > Traf fic Management > Load Balancing > Services page, select a FIX service and click Edit.
To delete a FIX load balancing virtual service by using the NetScaler GUI
Navigate to Configuration > Traf fic Management > Load Balancing > Services page, select a FIX service and click
Delete.
Navigate to Configuration > Traf fic Management > Load Balancing > Virtual Servers page and then click Statistics to
display the FIX server statistics.
Navigate to Configuration > Traf fic Management page and, under Monitor Sessions click Virtual Server Persistent
Sessions.
1. Navigate to Conf iguration > Traf f ic Management page and, under Monitor Sessions click Clear Persistent
Sessions.
2. On the Clear Persistent Sessions page, set the following parameters:
1. Virtual Server – Choose a FIX virtual server
2. Persistence Parameter – Choose a FIX persistence parameter
3. Click OK.
T o protect a load balancing configuration against failure, see the following sections:
Redirecting Client Requests to an Alternate URL
Configuring a Backup Load Balancing Virtual Server
Configuring Spillover
Connection Failover
Flushing the Surge Queue
You can redirect to a page on the local server or a remote server. You can redirect to a relative URL or an absolute URL. If
you configure a redirect to a relative URL consisting of a domain name with no path, the NetScaler appliance appends the
path of the incoming URL to the domain. If you use an absolute URL, the HT T P redirect is sent to that URL with no
modification.
Note: If a load balancing virtual server is configured with both a backup virtual server and a redirect URL, the backup virtual
server takes precedence over the redirect URL. A redirect is used only when both the primary and backup virtual servers are
DOWN.
To configure a virtual server to redirect the client request to a URL by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click Protection, and specify a redirect URL.
You can configure a backup load balancing virtual server when you create it, or you can change the optional parameters of
an existing virtual server. You can also configure a backup virtual server for an existing backup virtual server, thus creating
cascading backup virtual servers. T he maximum depth of cascading backup virtual servers is 10.
If you have multiple virtual servers that connect to two servers, you have a choice for what happens if the primary virtual
server goes DOWN and then comes back up. T he default behavior is for the primary virtual server to resume its role as
primary. However, you may want to configure the backup virtual server to remain in control in the event that it takes over.
For example, you may want to sync updates on the backup virtual server to the primary virtual server and then manually
force the original primary server to resume its role. In this case, you can designate the backup virtual server to remain in
control in the event that the primary virtual server goes DOWN and then comes back up.
You can configure a redirect URL on the primary load balancing virtual server as a fallback for when both the primary and the
backup virtual servers are DOWN or have reached their threshold for handling requests. When services bound to virtual
servers are OUT OF SERVICE, the appliance uses the redirect URL.
Note: If a load balancing virtual server is configured with both a backup virtual server and a redirect URL, the backup virtual
server takes precedence over the redirect URL. A redirect is used only when the primary and backup virtual servers are down.
To set a backup virtual server by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click Protection, and select a backup virtual server.
3. If you want the backup virtual server to remain in control until you manually enable the primary virtual server even if the
primary virtual server comes back up, select Disable Primary When Down.
T he spillover method specifies the operational condition on which you want to base your spillover configuration (for example, the number of established connections, bandwidth, or
combined health of the server farm). When a new connection arrives, the appliance verifies that the primary virtual server is up and compares the operational condition with the
configured spillover threshold. If the threshold is reached, the spillover feature diverts new connections to the first available virtual server in the backup chain. T he backup virtual server
manages the connections it receives until the load on the primary falls below the threshold.
If you configure spillover persistence, the backup virtual server continues to process the connections it received, even after the load on the primary falls below the threshold. If you
configure spillover persistence and a spillover persistence timeout, the backup virtual server processes connections for only the specified period of time after the load on the primary falls
below the threshold.
Note: In most cases, spillover is triggered if the value associated with the spillover method exceeds the threshold (for example, number of connections). Keep in mind, however, that with
the server-health spillover method, spillover is triggered if the health of the server farm falls below the threshold.
You can configure spillover in one of the following ways:
Specify a predefined spillover method. Four predefined methods are available, and they fulfill common spillover requirements.
Configure policy based spillover. In policy based spillover, you use a NetScaler rule to specify the conditions that should be met for spillover to occur. NetScaler rules give you the
flexibility to configure spillover for various operational conditions.
Use policy based spillover if a predefined method does not satisfy your requirements. If you configure both for a primary virtual server, the policy based spillover configuration takes
precedence over the predefined method.
First, you create the primary virtual server and the virtual servers that you need for the backup chain. You set up the backup chain by specifying one virtual server as the backup for the
primary (that is, you create a secondary virtual server), a virtual server as the backup for the secondary (that is, you create a tertiary virtual server), and so on. T hen, you configure spillover
by either specifying a predefined spillover method or creating and binding spillover policies.
For instructions for assigning a virtual server as the backup for another virtual server, see Configuring a Backup Load Balancing Virtual Server.
Updated: 2013-09-02
Predefined spillover methods fulfill some of the more common spillover requirements. To use one of the predefined spillover methods, you configure spillover parameters on the primary
virtual server. To create a chain of backup virtual servers, you also configure spillover parameters on backup virtual servers.
If the backup virtual servers reach their own threshold values, and the service type is TCP, the NetScaler appliance sends clients a TCP reset. For service types HT T P, SSL, and RT SP , it
diverts new requests to the redirect URL configured for the primary virtual server. A redirect URL can be specified for only HT T P, SSL, and RT SP virtual servers. If a redirect URL is not
configured, the NetScaler appliance sends clients a TCP reset (if the virtual server is of type TCP) or an HT T P 503 response (if the virtual server is of type HT T P or SSL).
Note: With RT SP virtual servers, the NetScaler appliance uses only data connections for spillover. If the backup RT SP virtual server is not available, the requests are redirected to an RT SP
URL and an RT SP redirect message is sent to the client.
To configure a predefined spillover method for a virtual server by using the command line interface
At the command prompt, type:
set lb vserver <vServerName> -soMethod <spillOverType> -soT hreshold <positiveInteger> -soPersistence ENABLED -soPersistenceT imeout <positiveInteger>
Example
set lb vserver Vserver-LB-1 -soMethod Connection -soThreshold 1000 -soPersistence enabled -soPersistenceTimeout 2
To configure a predefined spillover method for a virtual server by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click Protection, and set the spillover parameters.
Spillover policies, which are based on rules (expressions), enable you to configure the appliance for a wider range of spillover scenarios. For example, you can configure spillover on the
basis of the virtual server’s response time, or on the basis of number of connections in the virtual server’s surge queue.
To configure policy based spillover, first create a spillover action. You then select the expression that you want to use in the spillover policy , configure the policy, and associate the action
with it. Finally, you bind the spillover policy to a load balancing, content switching, or global server load balancing virtual server. You can bind multiple spillover policies to a virtual server,
with priority numbers. T he appliance evaluates the spillover policies in ascending order of priority numbers and performs the action associated with the last policy to evaluate to T RUE.
A virtual server can also have a backup action. T he backup action is performed if the virtual server does not have one or more backup virtual servers, or if all of the backup virtual servers
are DOWN, disabled, or have reached their own spillover limits.
When a spillover policy results in an UNDEF condition (an exception thrown when the result of policy evaluation is undefined), an UNDEF action is performed. T he UNDEF action is always
ACCEPT. You cannot specify an UNDEF action of your choice.
At the command prompt, type the following commands to configure a spillover policy and verify the configuration:
Example
> add spillover action mySoAction -action SPILLOVER
Done
> show spillover action mySoAction
1) Name: mySoAction Action: SPILLOVER
Done
>
Selecting an Expression for the Spillover Policy
In the policy expression, you can use any virtual-server based expression that returns a Boolean value. For example, you could use one of the following expressions:
In addition to the existing functions such as RESPT IME, ST AT E, and T HROUGHPUT , you can use the following virtual server based functions that have been introduced with this feature:
Averagesurgecount
Returns the average number of requests in the surge queues of active services. Returns 0 (zero) if there are no active services. Raises an UNDEF condition if used with a content
switching or global server load balancing virtual server.
Activeservices
Returns the number of active services. Raises an UNDEF condition if used with a content switching or global server load balancing virtual server.
Activetransactions
Returns the value of the virtual-server-level counter for current active transactions.
is_dynamic_limit_reached
Returns a Boolean T RUE if the number of connections being managed by the virtual server equals the dynamically calculated threshold. T he dynamic threshold is the sum of the
maximum client (Max Clients) settings of the bound services that are UP.
You can use a policy expression to implement any of the predefined spillover methods. T he following table maps the predefined spillover methods to the expressions you can use to
implement them:
At the command prompt, type the following commands to configure a spillover policy and verify the configuration:
add spillover policy <name> -rule <expression> -action <string> [-comment <string>]
show spillover policy <name>
Example
> add spillover policy mySoPolicy -rule SYS.VSERVER("v1").RESPTIME.GT(50) -action mySoAction -comment "Triggers spillover when the vserver's response time is greater than 50 ms."
Done
> show spillover policy mySoPolicy
1) Name: mySoPolicy Rule: "SYS.VSERVER(\"v1\").RESPTIME.GT(50)" Action: mySoAction Hits: 0 ActivePolicy: 0
Comment: "Triggers spillover when the vserver\'s response time is greater than 50 ms."
Done
>
At the command prompt, type the following commands to bind a spillover policy to a load balancing, content switching, or global server load balancing virtual server and verify the
configuration:
bind (lb | cs | gslb) vserver <name> -policyName <string> -priority <positive_integer> [-gotoPriorityExpression <expression>]
show (lb | cs | gslb) vserver <name>
Example
> bind lb vserver vserver1 -policyName mySoPolicy -priority 5
Done
> show lb vserver vserver1
vserver1 (2.2.2.12:80) - HTTP Type: ADDRESS
...
Note: For the predefined spillover methods that are configured directly on the virtual server (as values of the Spillover Method parameter), the backup action is not configurable. By
default, the appliance sends clients a T CP reset (if the virtual server is of type T CP) or an HT T P 503 response (if the virtual server is of type HT T P or SSL).
T he backup action is configured on the virtual server. You can configure the virtual server to accept requests (after the threshold specified by the policy is reached), redirect clients to a
URL, or simply drop requests until the number of requests falls below the threshold.
To configure a backup action for spillover by using the command line interface
At the command prompt, type the following commands to configure a backup action and verify the configuration:
Example
> set lb vserver vs1 -soBackupAction REDIRECT -redirectURL http://www.mysite.com/maintenance
Done
> show lb vserver vs1
vs1 (10.102.29.76:80) - HTTP Type: ADDRESS
State: UP
...
Redirect URL: http://www.mysite.com/maintenance
...
Done
>
To configure a backup action for spillover by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click Protection, and then specify a spillover backup action.
You can set up connection failover in either stateless or stateful mode. In the stateless connection failover mode, the HA
nodes do not exchange any information about the connections that are failed over. T his method has no runtime overhead.
In the stateful connection failover mode, the primary appliance synchronizes the data of the failed-over connections with
the new secondary appliance.
Connection failover is helpful if your deployment has long lasting connections. For example, if you are downloading a large
file over FT P and a failover occurs during the download, the connection breaks and the download is aborted. However, if
you configure connection failover in stateful mode, the download continues even after the failover.
In stateless connection failover, the new primary appliance tries to re-create the packet flow according to the information
contained in the packets it receives.
In stateful failover, to maintain current information about the mirrored connections, the primary appliance sends messages
to the secondary appliance. T he secondary appliance maintains the data related to the packets but uses it only in the
event of a failover. If a failover occurs, the new primary (old secondary) appliance starts using the stored data about the
mirrored connections and accepting traffic. During the transition period, the client and server may experience a brief
disruption and retransmissions.
Note:
Verify that the primary appliance is able to authorize itself on the secondary appliance. To verify correct configuration of
the passwords, use the show rpcnode command from command line or use the RPC option of the Network menu in
NetScaler GUI.
A basic HA configuration with connection failover contains the entities shown in the following figure.
Supported Setup
Connection failover can be configured only on load balancing virtual servers. It cannot be configured on content switching
virtual servers. If you enable connection failover on load balancing virtual servers that are attached to a content switching
virtual server, connection failover will not work because the load balancing virtual servers do not initially accept the traffic.
Load balancing All methods supported for the service type ANY. All methods applicable to the
methods supported service types.
However, if Source IP persistence is not set, the
SRCIPSRCPORT HASH method must be used.
It can be ON or OFF.
Service bindings Service can be bound to only one virtual server. Service can be bound to one or more
virtual servers.
SYN For any connection, if a failover occurs after the NetScaler issues SYN-ACK but before it receives the final
protection ACK, the connection is not supported by connection failover. T he client must reissue the request to
establish the connection.
Surge If the failover occurs before a connection with the server is established, the new primary NetScaler tries
protection to establish the connection with the server. It also retransmits all the packets held in the course of surge
protection.
Access If enabled, the access-down functionality takes precedence over connection failover.
down
INC Independent network configuration is not supported in the high availability (HA) mode.
Close on After failover, the NAT PCBs may not be closed on response.
Navigate to Traf fic Management > Load Balancing > Virtual Servers. Open the virtual server, and in Advanced
Settings, click Protection, and select Connection Failover as Statef ul.
Example
When connection failover is disabled on a virtual server, the resources allocated to the virtual server are freed.
Example
Navigate to Traf fic Management > Load Balancing > Virtual Servers. Open the virtual server, in Protection,
select Connection Failover as Disabled.
T he length of a surge queue increases whenever a request comes for which the appliance cannot establish a connection, and the
length decreases whenever a request in the queue gets sent to the server or a request gets timed out and is removed from the queue.
If the surge queue for a service or service group becomes too long, you may want to flush it. You can flush the surge queue of a
specific service or service group, or of all the services and service groups bound to a load balancing virtual server. Flushing a surge queue
does not affect the existing connections. Only the requests present in the surge queue get deleted. For those requests, the client has
to make a fresh request.
You can also flush the surge queue of a content switching virtual server. If a content switching virtual server forwards some requests
to a particular load balancing virtual server, and the load balancing virtual server also receives some other requests, when you flush the
surge queue of the content switching virtual server, only the requests received from this content switching virtual server are flushed;
the other requests in the surge queue of the load balancing virtual server are not flushed.
Note: You cannot flush the surge queues of cache redirection, authentication, VPN or GSLB virtual servers or GSLB services.
Note: Do not use the Surge Protection feature if Use Source IP (USIP) is enabled.
To flush a surge queue by using the command line interf ace
You can specify the name of a service, service group, or virtual server whose surge queue has to be flushed.
If you specify a name while executing the command, surge queue of the specified entity will be flushed. If more than one entity has
the same name, the appliance flushes surge queues of all those entities.
If you specify the name of a service group, and a server name and port while executing the command, the appliance flushes the
surge queue of only the specified service group member.
You cannot directly specify a service group member (<serverName> and <port>) without specifying the name of the service group
(<name>) and you cannot specify <port> without a <serverName>. Specify the <serverName> and <port> if you want to flush the
surge queue for a specific service group member.
If you execute the command without specifying any names, the appliance flushes the surge queues of all the entities present on
the appliance.
If a service group member is identified with a server name, you must specify the server name in this command; you cannot specify its
IP address.
The above command flushes the surge queue of the service or virtual server that is named SVC1ANZGB and has IP address as 10.10.10
2.
flush ns surgeQ
The above command flushes all the surge queues on the appliance.
To flush a surge queue by using the configuration utility
Navigate to Traffic Management > Content Switching > Virtual Servers, select a virtual server and, in the Action list, select Flush Surge
Queue.
When you enable or disable a server object, you enable or disable all services associated with the server object. When you
refresh the NetScaler appliance after disabling a server object, the state of its service appears as OUT OF SERVICE. If you
specify a wait time when disabling a server object, the server object continues to handle established connections for the
specified amount of time, but rejects new connections. If you remove a server object, the service to which it is bound is also
deleted.
rm server <name>
Example
rm server 10.102.29.5
To remove a server object by using the configuration utility
You can remove a service when it is no longer used. When you remove a service, it is unbound from its virtual server and deleted from the NetScaler configuration.
Examples
You remove a virtual server only when you no longer require the virtual server. Before you remove it, you must unbind all
services from it.
To enable or disable a virtual server by using the command line interf ace
Examples
To unbind a service f rom a virtual server by using the command line interf ace
You can also use the Visualizer to add and bind new objects, modify existing ones, and enable or disable objects. Most
configuration elements displayed in the Visualizer appear under the same names as in other parts of the configuration
utility. However, unlike the rest of the configuration utility, the Visualizer groups services that have the same configuration
details and monitor bindings into an entity called a service container.
A service container is set of similar services and service groups that are bound to a single load balancing virtual server. Next
to the service container is a number that shows the number of services in the group. T he services in the container have the
same properties, with the exception of the name, IP address, and port, and their monitor bindings should have the same
weight and binding state. When you bind a new service to a virtual server, it is placed into an existing container if its
configuration and monitor bindings match those of other services; otherwise, it is placed in its own container.
T he following procedures provide only basic steps for using the Visualizer. Because the Visualizer duplicates functionality in
other areas of the Load Balancing feature, other methods of viewing or configuring all of the settings that can be
configured in the Visualizer are provided throughout the Load Balancing documentation.
Note: T he Visualizer requires a graphic interface, so it is available only through the configuration utility.
To view load balancing virtual server properties by using the Visualizer
To view configuration details f or services, service groups, and monitors by using the Visualizer
To view configuration details f or policies and policy labels by using the Visualizer in the configuration utility
To add, remove, or disable a resource in a load balancing configuration by using the Visualizer
Sessionless load balancing. You can configure sessionless load balancing virtual servers and perform load balancing
without creating sessions in configurations that use DSR or intrusion detection systems (IDS).
Integrated caching. You can redirect HT T P requests to a cache.
Priority queuing. You can direct requests based on priority, by integrating your configuration with the Priority Queuing
feature.
SureConnect. You can use load balancing with the SureConnect feature to redirect important requests to a custom
Web page, insulating them from delays due to network congestion.
Delayed cleanup. You can configure delayed cleanup of virtual server connections to prevent the cleanup process from
using CPU cycles during periods when the NetScaler appliance is experiencing high loads.
Rewrite. You can use the Rewrite feature to modify port and protocol when performing HT T P redirection, or insert the
virtual server IP address and port into a custom Request header.
RTSP NAT.
Rate-based monitoring. You can enable rate-based monitoring to divert excess traffic.
Layer 2 Parameters. You can configure a virtual server to use the L2 parameters to identify a connection.
ICMP Response. You can configure the NetScaler to send ICMP responses to PING requests according to your settings.
On the IP address corresponding to the virtual server, set the ICMP RESPONSE to VSVR_CNT RLD, and on the virtual
server, set the ICMP VSERVER RESPONSE.
T he following settings can be made on a virtual server:
When you set ICMP VSERVER RESPONSE to PASSIVE on all virtual servers, NetScaler always responds.
When you set ICMP VSERVER RESPONSE to ACT IVE on all virtual servers, NetScaler responds even if one virtual server
is UP.
When you set ICMP VSERVER RESPONSE to ACT IVE on some and PASSIVE on others, NetScaler responds even if one
virtual server set to ACT IVE is UP.
Sessionless load balancing can operate in MAC-based forwarding mode or IP-based forwarding mode.
For MAC-based forwarding, the IP address of the sessionless virtual server must be specified on all the physical servers to
which the traffic is forwarded.
For IP-based forwarding in sessionless load balancing, the IP address and port of the virtual server need not be specified on
the physical servers, because this information is included in the forwarded packets. When forwarding a packet from the
client to the physical server, the appliance leaves client details such as IP address and port unchanged and adds the IP
address and port of the destination.
Supported Setup
NetScaler sessionless load balancing supports the following service types and load balancing methods:
Service Types
Round Robin
Least Bandwidth
LRT M (Least response time method)
Source IP Hash
Destination IP Hash
Source IP Destination IP Hash
Source IP Source Port Hash
Custom Load
Limitations
Sessionless load balancing has the following limitations:
T he NetScaler must be deployed in two-arm mode.
A service must be bound to only one virtual server.
Sessionless load balancing is not supported for service groups.
Sessionless load balancing is not supported for domain based services (DBS services).
Sessionless load balancing in the IP mode is not supported for a virtual server that is configured as a backup to a primary
virtual server.
You cannot enable spillover mode.
Note: While configuring a virtual server for sessionless load balancing, explicitly specify a supported load balancing method.
T he default method, Least Connection, cannot be used for sessionless load balancing.
Note: T o configure sessionless load balancing in MAC-based redirection mode on a virtual server, the MAC-based
forwarding option must be enabled on the NetScaler.
To add a sessionless virtual server by using the command line interf ace
At the command prompt, type the following commands to add a sessionless virtual server and verify the configuration:
Example
Note
For a service that is bound to a virtual server on which -m MAC option is enabled, you must bind a non-user monitor.
A cache stores frequently requested HT T P content. When you configure cache redirection on a virtual server, the NetScaler
appliance sends cacheable HT T P requests to the cache, and non-cacheable HT T P requests to the origin Web server.
To configure cache redirection on a virtual server by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click T raffic Settings, and select Cacheable.
To configure priority queuing on a virtual server by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click T raffic Settings, and select Priority Queuing.
Note: You must configure priority queuing globally for it to function correctly.
To configure SureConnect on a virtual server, you must first configure the alternative content. For information about
configuring a SureConnect website, see SureConnect. After you configure the website, enable SureConnect on the load
balancing virtual server to put your SureConnect custom web page in use.
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click T raffic Settings, and select SureConnect.
T he state of a virtual server depends on the states of the services bound to it. T he state of each service depends on the
responses of the load balanced servers to probes and health checks sent by the monitors that are bound to that service.
Sometimes the load balanced servers do not respond. If a server is slow or busy, monitoring probes can time out. If
repeated monitoring probes are not answered within the configured timeout period, the service is marked DOWN.
A virtual server is marked DOWN only when all services bound to it are marked DOWN. When a virtual server goes DOWN, it
terminates all connections, either immediately or after allowing existing connections to complete.
You must not enable the downStateFlush setting on those application servers that must complete their transactions. You
can enable this setting on Web servers whose connections can safely be terminated when they marked DOWN.
T he following table summarizes the effect of this setting on an example configuration consisting of a virtual server,
Vserver-LB-1, with one service bound to it, Service-TCP-1. In the table, E and D denote the state of the downStateFlush
setting: E means Enabled, and D means Disabled.
E D For some service types, such as TCP, for which the NetScaler appliance does not support
connection reuse, both client and server connections are terminated.
For service types, such as HT T P, for which the appliance supports connection reuse, both client
and server connections are terminated only if a transaction is active on those connections. If a
transaction is not active, only client connections are terminated.
D E For some service types, such as TCP, for which the NetScaler appliance does not support
connection reuse, both client and server connections are terminated.
For service types, such as HT T P, for which the appliance supports connection reuse, both client
and server connections are terminated only if a transaction is active on those connections. If a
transaction is not active, only server connections are terminated.
If you want to disable a service only when all the established connections are closed by the server or the client, you can use
the graceful shutdown option. For information about the graceful shutdown of a service, see Graceful Shutdown of
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click T raffic Settings, and select Down State Flush.
T his setting affects only HT T P and HT T PS traffic. If this setting is enabled on a virtual server, the virtual server rewrites the
port on redirects, replacing the port used by the service with the port used by the virtual server.
If the virtual server or service is of type SSL, you must enable SSL redirect on the virtual server or service. If both the virtual
server and service are of type SSL, enable SSL redirect on the virtual server.
Scenario 1: T he virtual server is of type HT T P and services are of type SSL. SSL redirect, and optionally port rewrite, is
enabled on the service. If port rewrite is enabled, the port of HT T PS URLs is rewritten. HT T P URLs from the server are sent
as is to the client.
Redirect URL f rom the Server Redirect URL sent to the Client
Only SSL redirect is enabled. T he virtual server can be configured on any port.
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com:444/
SSL redirect and port rewrite are enabled. T he virtual server is configured on port 80.
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com/
SSL redirect and port rewrite are enabled. Virtual server is configured on port 8080.
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ http://domain.com:8080/
https://domain.com:444/ http://domain.com:8080/
Scenario 2: T he virtual server is of type SSL and services are of type HT T P. If port rewrite is enabled, only the port of HT T P
URLs is rewritten. HT T PS URLs from the server are sent as is to the client.
Redirect URL f rom the Server Redirect URL sent to the Client
SSL redirect is enabled on the virtual server. T he virtual server can be configured on any port.
http://domain.com/ https://domain.com/
http://domain.com:8080/ https://domain.com:8080/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com:444/
SSL redirect and port rewrite are enabled on the virtual server. T he virtual server is configured on port 443.
http://domain.com/ https://domain.com/
http://domain.com:8080/ https://domain.com/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com:444/
SSL redirect and port rewrite are enabled. T he virtual server is configured on port 444.
http://domain.com:8080/ https://domain.com:444/
https://domain.com/ https://domain.com/
https://domain.com:445/ https://domain.com:445/
Scenario 3: T he virtual server and service are of type HT T P. Port rewrite must be enabled on the virtual server. Only the port
of HT T P URLs is rewritten. HT T PS URLs from the server are sent as is to the client.
Redirect URL f rom the Server Redirect URL sent to the Client
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com:444/
http://domain.com/ http://domain.com:8080/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com/
https://domain.com:445/ https://domain.com:445/
Scenario 4: T he virtual server and service are of type SSL. If port rewrite is enabled, only the port of HT T PS URLs is
rewritten. HT T P URLs from the server are sent as is to the client.
Redirect URL f rom the Server Redirect URL sent to the Client
SSL redirect is enabled on the virtual server. T he virtual server can be configured on any port.
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com:444/
SSL redirect and port rewrite are enabled on the virtual server. T he virtual server is configured on port 443.
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com/
https://domain.com:444/ https://domain.com/
SSL redirect and port rewrite are enabled on the virtual server. T he virtual server is configured on port 444.
http://domain.com/ http://domain.com/
http://domain.com:8080/ http://domain.com:8080/
https://domain.com/ https://domain.com:444/
https://domain.com:445/ https://domain.com:444/
To configure HTTP redirection on a virtual server by using the command line interf ace
Example
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open the virtual server.
2. In Advanced Settings, click SSL Parameters, and select SSL Redirect.
If the primary virtual server is down and the backup virtual server is up, the configuration settings of the backup virtual server
are added to the client requests. If you want the same header tag to be added, regardless of whether the requests are
from the primary virtual server or backup virtual server, then you must configure the required header tag on both virtual
servers.
Note: T his option is not supported for wild card virtual servers or dummy virtual servers.
To insert the IP address and port of the virtual server in the client requests by using the command line
interf ace
A server can distinguish monitor probes from traffic if the source IP address used for monitor probes belongs to a
specific set.
T o improve server security, a server may be configured to respond to requests from a specific set of IP addresses or,
sometimes, from a single specific IP address. In such a case, the NetScaler can use only the IP addresses accepted by the
server as the source IP address.
T he NetScaler can manage its internal connections efficiently if it can distribute its IP addresses into IP sets and use an
address from a set only for connecting to a specific service.
To configure the NetScaler to use a specified source IP address, create net profiles (network profiles) and configure the
NetScaler entities to use the profile. A net profile can be bound to load balancing or content switching virtual servers,
services, service groups, or monitors. A net profile has NetScaler owned IP addresses (SNIPs and VIPs) that can be used as
the source IP address. It can be a single IP address or a set of IP addresses, referred to as an IP set. If a net profile has an
IP set, NetScaler dynamically selects an IP address from the IP set at the time of connection. If a profile has a single IP
address, the same IP address is used as the source IP.
If a net profile is bound to a load balancing or content switching virtual server, the profile will be used for sending traffic to
all the services bound to it. If a net profile is bound to a service group, NetScaler uses the profile for all the members of the
service group. If a net profile is bound to a monitor, NetScaler uses the profile for all the probes sent from the monitor.
Note: When a NetScaler appliance uses a VIP address to communicate with a server, it uses session entries to identify
whether the traffic destined to the VIP address is a response from a server or a request from a client.
Usage of a net profile f or sending traf fic:
If the Use Source IP Address (USIP) option is enabled, NetScaler uses the IP address of the client and ignores all the net
profiles. If the USIP option is not enabled, NetScaler selects the source IP in the following manner:
If there is no net profile on the virtual server or the service/service group, NetScaler uses the default method.
If there is a net profile only on the service/service group, NetScaler uses that net profile.
If there is a net profile only on the virtual server, NetScaler uses the net profile.
If there is a net profile both on the virtual server and service/service group, NetScaler uses the net profile bound to the
service/service group.
For monitor probes, NetScaler selects the source IP in the following manner:
If there is a net profile bound to the monitor, NetScaler uses the net profile of the monitor. It ignores the net profiles
Note: If there is no net profile bound to a service, NetScaler looks for a net profile on the service group if the service is
bound to a service group.
To use a specified source IP address for communication, go through the following steps:
1. Create IP sets from the pool of SNIPs and VIPs owned by the NetScaler. An IP set can consist of both SNIP and VIP
addresses. For instructions, see Creating IP Sets.
2. Create net profiles. For instructions, see Creating a Net Profile.
3. Bind the net profiles to NetScaler entities. For instructions, see Binding a Net Profile to a NetScaler Entity.
Note: A net profile can have only the IP addresses specified as SNIP and VIP on the NetScaler.
Managing Net Profiles
A net profile (or network profile) contains an IP address or an IP set. During communication with physical servers or peers,
the NetScaler appliance uses the addresses specified in the profile as the source IP address.
Creating an IP Set
An IP set is a set of IP addresses, which are configured on the NetScaler appliance as Subnet IP addresses (SNIPs) or Virtual
IP addresses (VIPs). An IP set is identified with a meaningful name that helps in identifying the usage of the IP addresses
contained in it. To create an IP set, add an IP set and bind NetScaler owned IP addresses to it. SNIP addresses and VIP
addresses can be present in the same IP set.
Examples
1.
> add ipset skpnwipset
Done
> bind ipset skpnwipset 21.21.20.1
Done
3.
> bind ipset skpipset 11.11.11.101
ERROR: Invalid IP address
[This IP address could not be added because this is not an IP address owned by the NetScaler]
> add ns ip 11.11.11.101 255.255.255.0 -type SNIP
ip "11.11.11.101" added
Done
> bind ipset skpipset 11.11.11.101
IPAddress "11.11.11.101" bound
Done
4.
> sh ipset
1) Name: ipset-1
2) Name: ipset-2
3) Name: ipset-3
4) Name: skpnewipset
Done
5.
> sh ipset skpnewipset
IP:21.21.21.21
IP:21.21.21.22
IP:21.21.21.23
IP:21.21.21.24
IP:21.21.21.25
Done
To create an IP set by using the configuration utility
Navigate to System > Network > IP Sets, and create an IP set.
A net profile (network profile) consists of one or more SNIP or VIP addresses of the NetScaler.
To create a net profile by using the command line interface
At the command prompt, type:
add netprofile <name> [-srcIp <srcIpVal>] If the srcIpVal is not provided in this command, it can be provided later by using
A net profile can be bound to a load balancing virtual server, service, service group, or a monitor.
Note: You can bind a net profile at the time of creating a NetScaler entity or bind it to an already existing entity.
To bind a net profile to a server by using the command line interface
You can bind a net profile to load balancing virtual servers and content switching virtual servers. Specify the appropriate
virtual server.
Examples
To bind a net profile to a service group by using the command line interface
At the command prompt, type:
To set a time-out value f or idle client connections by using the command line interf ace
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, click Traf f ic Settings, and set the client idle time-out value in seconds.
For more information about enabling and configuring NAT, see "IP Addressing."
In NAT -off mode, NAT is not enabled and configured. T he appliance receives RT SP requests from the client and routes
them to the service that it selects using the configured load balancing method. T he load balanced RT SP servers send their
responses directly to the client, bypassing the appliance. You must therefore configure the appliance to use Direct Server
Return (DSR) mode, and assign publicly accessible FQDNs in DNS to your load balanced RT SP servers.
For more information about enabling and configuring DSR mode, see "Configuring Load Balancing in Direct Server Return
Mode." For more information about configuring DNS, see "Domain Name System."
In either case, when you configure RT SP load balancing, you must also configure rtspNat to match the topology of your
load balancing setup.
Example
1. Navigate to Traf f ic Management > Load Balancing > Virtual Servers, and open a virtual server of type RT SP.
2. In Advanced Settings, click Traf f ic Settings, and select RTSP Natting.
Enabling the L2Conn parameter for a load balancing virtual server allows multiple TCP and non-TCP connections with the
same 4-tuple (<source IP>:<source port>::<destination IP>:<destination port>) to co-exist on the NetScaler appliance. T he
appliance uses both the 4-tuple and the Layer 2 parameters to identify TCP and non-TCP connections.
T herefore, when an nCore NetScaler appliance on which the l2Conn parameter is set for one or more load balancing virtual
servers is downgraded to a Classic build or to an nCore build that does not support the l2Conn parameter, the load
balancing configurations that use the l2Conn parameter become ineffective.
To configure the L2 connection option by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select T raffic Settings, and select Layer 2 Parameters.
On a wildcard load balancing virtual server if you explicitly configure a route to a destination, by default, the NetScaler
appliance forwards traffic according to the configured route. If you want the NetScaler to not look up for the configured
route, you can set the Prefer Direct Route option to NO.
If a device is directly connected to a NetScaler appliance, the NetScaler directly forwards traffic to the device. For example,
if the destination of a packet is a firewall, the packet need not be routed through another firewall. However, in some cases,
you may want the traffic to go through the firewall even if the device is directly connected to it. In such cases, you can set
the Prefer Direct Route Option to NO.
Note: T he preferDirectRoute setting is applicable to all the wildcard virtual servers on the NetScaler appliance.
To set the pref er direct route option by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Configure Load Balancing parameters.
2. Select Prefer Direct Route.
T he NetScaler supports using a source port from a specified port range for communicating to the servers. One of the use
case of this feature is for servers that are configured to identify received traffic belonging to a specific set on the basis of
source port for logging and monitoring purposes. For example, identifying internal and external traffic for logging purpose.
Configuring the NetScaler appliance to use a source port from a port range for communicating to the servers consists of
the following tasks:
Create a net prof ile and set the source port range parameter. A source port range parameter specifies one or more
port ranges. T he NetScaler randomly selects one of the free ports from the specified port ranges and used it as the
source port for each connection to servers.
Bind the net prof ile to load balancing virtual servers, services, or service groups: A net profile with source port
range setting can be bound to a virtual server, service, or a service group of a load balancing configuration. For a
connection to a virtual server, the NetScaler randomly selects one of the free ports from the specified port ranges of a
net profile and use this port as the source port for connecting to one of the bound server.
To specif y a source port range or ranges by using the NetScaler command line
Done
Done
Done
Done
Some situations require that the NetScaler appliance send all of a specific client's traffic from the same IP address when
sending the traffic to servers. T he servers can then, for example, identify traffic belonging to a specific set for logging and
monitoring purposes.
T he source IP persistency option of a net profile enables the NetScaler appliance to use the same address, specified in the
net profile, to communicate with servers about all sessions initiated from a specific client to a virtual server.
To enable source IP persistency in a net profile by using the NetScaler command line
T o enable source IP persistency while adding a net profile, at the command prompt, type:
add netProfile <name> -srcippersistency ( ENABLED | DISABLED )
show netprofile <name>
T o enable source IP persistency in an existing net profile, at the command prompt, type:
set netProfile <name> -srcippersistency ( ENABLED | DISABLED )
show netprofile <name>
Example
In the following sample configuration, net profile NET PROFILE-IPPRST NCY-1 has the source IP persistency option enabled
and is bound to load balancing virtual server LBVS-1.
T he NetScaler appliance always use the same IP address (in this example, 192.0.2.11) to communicate with servers bound to
LBVS-1, for all sessions initiated from a specific client to the virtual server.
Example COPY
Done
Done
Done
Done
A link local IPv6 address and the associated VLAN ID are specified in the following format in services, service groups, and
servers configurations: <IPv6_Addrs>%<vlan_id>
For example, fe80:123:4567::a%2048:, fe80:123:4567::a is the link local address AND 2048 is the VLAN ID.
Examples COPY
Done
Done
Done
This functionality is not available globally. It has to be configured for each virtual server. The functionality is available only for virtual servers that use one of the
following load balancing methods:
Round robin
Least connection
Least response time
Least bandwidth
Least packets
LRTM (Least Response Time Method)
Custom load
With automated slow start, a service is taken out of the slow start phase when one of the following conditions applies:
The actual request rate is less than the new service request rate.
The service does not receive traffic for three successive increment intervals.
The request rate has been incremented 200 times.
The percentage of traffic that the new service must receive is greater than or equal to 100.
With manual slow start, the service remains in the slow start phase until you take it out of that phase.
As an example, assume that you are using a virtual server to load balance 2 services, Service1 and Service2, in round robin mode. Further assume that the virtual
server is receiving 240 requests per second, and that it is distributing the load evenly across the services. When a new service, Service3, is added to the
configuration, you might want to increase the load on it manually through values of 10, 20, and 40 requests per second before sending it its full share of the load.
The following table shows the values to which you set the three parameters.
Parameter Value
Interval in seconds 0
New service request rate 10, 20, 40, and 0, at intervals that you choose
When you set the new service request rate parameter to 0, Service3 is no longer considered a new service, and receives its full share of the load.
Assume that you add another service, Service4, during the ramp-up period for Service3. In this example, Service4 is added when the new service request rate
parameter is set to 40. Therefore, Service4 begins receiving 40 requests per second.
The following table shows the load distribution on the services during the period described in this example.
new service request rate = new service request rate = new service request rate = new service request rate
10 req/sec 20 req/sec 40 req/sec = 0 req/sec
Service3 10 20 40 60
Service4 - - 40 60
As an example, assume that four services, Service1, Service2, Service3, and Service4, are bound to a load balancing virtual server, vserver1. Further assume that
vserver1 receives 100 requests per second, and that it distributes the load evenly across the services (25 requests per second per service). When you add a fifth
service, Service5, to the configuration, you might want the appliance to send the new service 4 requests per second for the first 10 seconds, 8 requests per second
for the next 10 seconds, and so on, until it is receiving 20 requests per second. For this requirement, the following table shows the values to which you set the three
parameters:
Parameter Value
Interval in seconds 10
Increment value 4
Units for the new service request rate Requests per second
With this configuration, the new service begins receiving as many requests as the existing services 50 seconds after it is added or its state has changed from DOWN
to UP. During each interval in this period, the appliance distributes to the existing servers the excess of requests that would have been sent to the new service in the
absence of stepwise increments. For example, in the absence of stepwise increments, each service, including Service5, would have received 20 requests each per
second. With stepwise increments, during the first 10 seconds, when Service5 receives only 4 requests per second, the appliance distributes the excess of 16
requests per second to the existing services, resulting in the distribution pattern shown in the following table and figure over the 50-second period. After the 50-
second period, Service5 is no longer considered a new service, and it receives its normal share of traffic.
Req/sec forService1 25 24 23 22 21 20
Req/sec forService2 25 24 23 22 21 20
Req/sec forService3 25 24 23 22 21 20
Req/sec forService4 25 24 23 22 21 20
Req/sec forService5 0 4 8 12 16 20
Total req/sec (load on the virtual server) 100 100 100 100 100 100
Figure 1. A Graph of the Load Distribution Pattern on All Services for the 50-second Period Immediately after Service5 is Added
An alternative requirement might be for the appliance to send Service5 25% of the load on the existing services in the first 5 seconds, 50% in the next 5 seconds,
and so on, until it is receiving 20 requests per second. For this requirement, the following table shows the values to which you set the three parameters.
Parameter Value
Interval in seconds 5
Increment value 25
With this configuration, the service begins receiving as many requests as the existing services 20 seconds after it is added or its state has changed from DOWN to
UP. The traffic distribution during the ramp-up period for the new service is identical to the one described earlier, where the unit for the step increments was
“requests per second.”
You set the slow start parameters by using either the set lb vserver or the add lb vserver command. T he following command
is for setting slow start parameters when adding a virtual server.
To configure stepwise load increments for a new service by using the command
line interface
At the command prompt, type the following commands to configure stepwise increments in the load for a service and
Example
T he monitor can be in the ENABLED or DISABLED state when you set the no-monitor option, and when you remove the
no-monitor option, the earlier state of the monitor is resumed.
You can set the no-monitor option for a service when creating the service. You can also set the no-monitor option on an
existing service.
If a service for which you enabled the no-monitor option goes down, the NetScaler continues to show the service as UP
and continues to forward traffic to the service. A persistent connection to the service can worsen the situation. In that
case, or if many services shown as UP are actually DOWN, the system may fail. T o avoid such a situation, when the
external mechanism that monitors the services reports that a service that is DOWN, remove the service from the
NetScaler configuration.
If you configure the no-monitor option on a service, you cannot configure load balancing in the Direct Server Return
(DSR) mode. For an existing service, if you set the no-monitor option, you cannot configure the DSR mode for the
service.
To set the no-monitor option f or a new service by using the command line interf ace
At the command prompt, type the following commands to create a service with the health monitor option, and verify the
configuration:
add service <serviceName> <IP | serverName> <serviceT ype> <port> -healthMonitor (YES|NO)
Example
At the command prompt, type the following command to set the health monitor option:
Example
By default, the state of a service and the state of the corresponding monitor are UP.
>show service LB-SVC1
LB-SVC1 (10.102.29.5:80) - HTTP
State: UP
When the no-monitor option is set on a service, the state of the monitor changes to UNKNOWN.
> set service LB-SVC1 -healthMonitor NO
Done
> show service LB-SVC1
LB-SVC1 (10.102.29.5:80) - HTTP
State: UP
Last state change was at Fri Dec 10 10:17:37 2010.
Time since last state change: 5 days, 18:55:48.710
Health monitoring: OFF
For surge protection to function correctly, you must enable it globally. For more information about surge protection, see
"Surge Protection."
To set surge protection on the service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a source.
2. In Advanced Settings, select T raffic Settings, and select Surge Protection.
Under certain conditions, you can configure the downStateFlush setting to immediately terminate existing connections
when a service or a virtual server is marked DOWN. You must not enable the downStateFlush setting on those application
servers that must complete their transactions. You can enable this setting on Web servers whose connections can safely be
terminated when they marked DOWN.
T he following table summarizes the effect of this setting on an example configuration consisting of a virtual server,
Vserver-LB-1, with one service bound to it, Service-1. In the table, E and D denote the state of the downStateFlush setting:
E means Enabled, and D means Disabled.
E D For some service types, such as TCP, for which the NetScaler appliance does not support
connection reuse, both client and server connections are terminated.
For service types, such as HT T P, for which the appliance supports connection reuse, both client
and server connections are terminated only if a transaction is active on those connections. If a
transaction is not active, only client connections are terminated.
D E For some service types, such as TCP, for which the NetScaler appliance does not support
connection reuse, both client and server connections are terminated.
For service types, such as HT T P, for which the appliance supports connection reuse, both client
and server connections are terminated only if a transaction is active on those connections. If a
transaction is not active, only server connections are terminated.
If you want to disable a service only when all the established connections are closed by the server or the client, you can use
the graceful shutdown option. For information about the graceful shutdown of a service, see Graceful Shutdown of
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Down State Flush.
To set down state flush on the virtual server by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select T raffic Settings, and select Down State Flush.
To avoid disrupting established sessions, you can place a service in the Transition Out of Service (T ROFS) state by doing one
of the following:
Adding a T ROFS code or string to the monitor— Configure the server to send a specific code or string in response to a
monitor probe.
Explicitly disable the service and:
Set a delay (in seconds).
Enable graceful shut down.
If you bind only one monitor to a service, and the monitor is T ROFS-enabled, it can place the service in the T ROFS state on
the basis of the server’s response to a monitor probe. T his response is compared with the value in the trofsCode parameter
for an HT T P monitor or the trofsString parameter for an HT T P-ECV or TCP-ECV monitor. If the code matches, the service is
placed in the T ROFS state. In this state, it continues to honor the persistent connections.
If multiple monitors are bound to a service, the effective state of the service is calculated on the basis of the state of all
the monitors that are bound to the service. Upon receiving a T ROFS response, the state of the T ROFS-enabled monitor is
considered as UP for the purpose of this calculation. For more information about how a NetScaler appliance designates a
service as UP, see Setting a T hreshold Value for the Monitors Bound to a Service.
Important:
You can bind multiple monitors to a service, but must not T ROFS-enable more than one of them.
You can convert a T ROFS-enabled monitor to a monitor that is not T ROFS-enabled, but not vice versa.
To configure a TROFS code or string in a monitor by using the command line interf ace
To modif y the TROFS code or string by using the command line interf ace
Disabling a Service
Often, however, you cannot estimate the amount of time needed for all the connections to a service to complete the
existing transactions. If a transaction is unfinished when the wait time expires, shutting down the service may result in data
loss. In this case, you can specify graceful shutdown for the service, so that the service is disabled only when all the current
active client connections are closed by either the server or the client. See the following table for behavior if you specify a
wait time in addition to graceful shutdown.
Persistence is maintained according to the specified method even if you enable graceful shutdown. T he system continues
to serve all the persistent clients, including new connections from the clients, unless the service is marked DOWN during the
graceful shutdown state as a result of the checks made by a monitor.
State Results
Graceful shutdown is Service is shut down after the last of the current active client connections is served, even if the wait time has
enabled and a wait time not expired. T he appliance checks the status of the connections once every second. If the wait time expires,
is specified. any open sessions are closed.
Graceful shutdown is
Service is shut down only after the wait time expires, even if all established connections are served before
disabled and a wait time
expiration.
is specified.
Graceful shutdown is
Service is shut down only after the last of the previously established connections is served, regardless of the
enabled and no wait
time taken to serve the last connection.
time is specified.
Graceful shutdown is
No graceful shutdown. Service is shut down immediately after the disable option is chosen or the disable
disabled and no wait
command is issued. (T he default wait time is zero seconds.)
time is specified.
To terminate existing connections when a service or a virtual server is marked DOWN, you can use the Down State Flush
option. For more information, see Enabling Cleanup of Virtual Server Connections.
To configure gracef ul shutdown f or a service by using the command line interf ace
At the command prompt, type the following commands to shut down a service gracefully and verify the configuration:
1 bound monitor:
1) Monitor Name: tcp-default
State: UP Weight: 1
Probes: 13898 Failed [Total: 0 Current: 0]
Last response: Probe skipped - live traffic to service.
Response Time: N/A
Done
1 bound monitor:
1) Monitor Name: tcp-default
State: UNKNOWN Weight: 1
Probes: 13898 Failed [Total: 0 Current: 0]
Last response: Probe skipped - service state OFS.
Response Time: N/A
Done
To configure gracef ul shutdown f or a service by using the configuration utility
If you set the trofsPersistence flag to ENABLED, persistent sessions are honored. If you set it to DISABLED, they are not.
To set the trof sPersistence flag by using the command line interf ace
At the command prompt, type one of the following commands to set the trofsPersistence flag for a new virtual server or
an existing virtual server, or to return the setting to its default value:
Argument
trof sPersistence. Honor current active client connections and new requests on persistence sessions when the service is in
T ROFS state.
Examples:
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Sure Connect.
For more information about Layer 2 and Layer 3 modes, see IP Addressing.
For the appliance to bridge packets sent to the DOWN services, enable Layer 2 mode with the accessDown parameter.
To enable access down on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Access Down.
Note: T CP buffering set at the service level takes precedence over the global setting. For more information about
configuring T CP buffering globally, see "T CP Buffering."
To enable TCP Buf f ering on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select T CP Buffering.
Note: For compression to function correctly, you must enable it globally. For more information about configuring
compression globally, see Compression.
To enable compression on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Compression.
If you do not enable this setting, the client will open a new connection for every request that it sends to the Web site. T he
client keep-alive setting saves the packet round trip time required to establish and close connections. T his setting also
reduces the time to complete each transaction. Client keep-alive can be enabled only on HT T P or SSL service types.
Client keep-alive set at the service level takes precedence over the global client keep-alive setting. For more information
about client keep-alive, see Client Keep-Alive.
To enable client keep-alive on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Client Keep-Alive.
However, in some situations, the server needs to be aware of the client it has to serve. When you enable the client IP
setting, the NetScaler inserts the client's IPv4 or IPv6 address while forwarding the requests to the server. T he server inserts
this client IP in the header of the responses. T he server is thus aware of the client.
To insert client IP address in the client request by using the command line interf ace
1. Navigate to Traf f ic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select Traf f ic Settings, and select Client IP Address.
For more information about configuring USIP globally, see "Enabling Use Source IP Mode."
To enable USIP mode f or a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T raffic Settings, and select Use Source IP Address.
T he NetScaler appliance is configured with two load balancing virtual servers, LBVS1 and LBVS2.
Both the virtual servers are bound to the same service, S-ANY.
Use (the client's) source IP address (USIP) is enabled on the service.
Client C1 sends two requests, Req1 and Req2, for the same service.
Req1 is received by LBVS1 and Req2 is received by LBVS2.
LBVS1 and LBVS2 forward the request to S-ANY, and when S-ANY sends the response, they forward the response to the
client.
Consider two cases:
Use the client port. When the NetScaler uses the client port, both the virtual servers use the client's IP address
(because USIP is ON) and the client's port when connecting to the server. T herefore, when the service sends the
response, the NetScaler cannot determine which virtual server should receive the response.
Use proxy port. When the NetScaler uses a proxy port, the virtual servers use the client's IP address (because USIP is
ON), but different ports when connecting to the server. T herefore, when the service sends the response, the port
number identifies the virtual server that should receive the response.
However, if you require a fully transparent configuration, such as a fully transparent cache redirection configuration, you
must disable the Use Proxy port Setting so that the NetScaler appliance can use the source port from the client’s request.
T he Use Proxy Port option becomes relevant if the use source IP (USIP) option is enabled. For TCP-based service types, such
as TCP, HT T P, and SSL, the option is enabled by default. For UDP-based service types, such as UDP and DNS, including ANY,
the option is disabled by default. For more information about the USIP option, see "Enabling Use Source IP Mode."
You can configure the Use Proxy Port setting either globally or on a given service.
You configure the Use ProxyPort settingon the service if you want to override the global setting.
To configure the Use Proxy Port setting on a service by using the command line
interface
At the command prompt, type:
You configure the Use Proxy Port setting globally if you want to apply the setting to all the services on the NetScaler
appliance. T he global setting is overridden by service-specific Use Proxy Port settings.
To configure the Use Proxy Port setting globally by using the command line
interface
At the command prompt, type the following commands to configure the Use Proxy Port setting globally and verify the
configuration:
Example
For more information on the Maximum Client setting, see Load Balancing Domain-Name Based Services.
Note: Connections that are in the process of closing are not considered for this limit.
To set a limit to the number of client connections by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Maximum Clients.
Note: You can configure the max request option for HT T P or SSL services only.
To limit the number of client requests per connection by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Maximum Requests.
For example, assume that three monitors, named Monitor-HT T P-1, Monitor-HT T P-2, and Monitor-HT T P-3 respectively, are
bound to Service-HT T P-1, and that the threshold configured on the service is three. Suppose the following weights are
assigned to each monitor:
To set the monitor threshold value on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Monitor T hreshold.
To set a timeout value f or idle client connections by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Client Idle T ime-out.
To set a timeout value f or idle server connections by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Server Idle T ime-out.
To set a maximum bandwidth limit on a service by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Services, and open a service.
2. In Advanced Settings, select T hresholds & T imeouts, and select Maximum Bandwidth.
To set cache redirection on a service by using the command line interf ace
To configure a load balancing virtual server to retain the client VLAN ID by using the command line interf ace
At the command prompt, type the following command to configure a load balancing virtual server to retain the client VLAN
ID and verify the configuration:
Note
For a service that is bound to a virtual server on which -m MAC option is enabled, you must bind a non-user monitor.
To configure a load balancing virtual server to retain the client VLAN ID by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select T raffic Settings, and select Retain VLAN ID.
You can also enable an SNMP alarm called ENT IT Y-STAT E if you want the NetScaler appliance to notify you when the
percentage health of bound services causes a virtual server to change state.
To configure percentage based automatic state transition by using the command line interf ace
At the command prompt, type the following commands to configure automatic state transition for a virtual server and
verify the configuration:
To configure percentage based automatic state transition by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and open a virtual server.
2. In Advanced Settings, select T raffic Settings, and set a Health T hreshold.
To enable the ENTITY-STATE alarm by using the command line interf ace
At the command prompt, type the following commands to enable the ENT IT Y-STAT E SNMP alarm and verify the
configuration:
Note: You can create a custom monitor based on a built-in monitor. T o learn how to create custom monitors, see
Configuring Monitors in a Load Balancing Setup.
This section includes the following details:
Monitoring T CP-based Applications
Monitoring FT P Services
Monitoring RT SP Services
You cannot delete or modify default monitors. When you bind any other monitor to a TCP service, the default monitor is
unbound from the service. T he following table lists the monitor types, and the parameters and monitoring processes
associated with each type.
tcp Not applicable The NetScaler appliance establishes a 3-way handshake with the monitor destination, and then closes the
connection.
If the appliance observes TCP traffic to the destination, it does not send TCP monitoring requests. This occurs if
LRTM is disabled. By default, LRTM is disabled on this monitor.
http httprequest [“HEAD /”] - The NetScaler appliance establishes a 3-way handshake with the monitor destination.
HTTP request that is sent to
the service. After the connection is established, the appliance sends HTTP requests, and then compares the response code
with the configured set of response codes.
respcode [200] - A set of HTTP
response codes are expected
from the service.
tcp-ecv send [""] - is the data that is The NetScaler appliance establishes a 3-way handshake with the monitor destination.
sent to the service. The
maximum permissible length When the connection is established, the appliance uses the send parameter to send specific data to the service
of the string is 512 K bytes. and expects a specific response through the receive parameter.
recv [""] - expected response Different servers send different sizes of segments. However, the pattern must be within 16 TCP segments.
from the service. The
maximum permissible length
of the string is 128 K bytes.
http-ecv send [""] - HTTP data that is The NetScaler appliance establishes a 3-way handshake with the monitor destination.
sent to the service
When the connection is established, the appliance uses the send parameter to send the HTTP data to the
recv [""] - the expected HTTP service and expects the HTTP response that the receive parameter specifies. (HTTP body part without including
response data from the HTTP headers). Empty response data matches any response. Expected data may be anywhere in the first 24K
service bytes of the HTTP body of the response.
ping Not Applicable The NetScaler appliance sends an ICMP echo request to the destination of the monitor and expects an ICMP
echo response.
To configure built-in monitors for TCP-based applications, see Configuring Monitors in a Load Balancing Setup.
Secure T CP monit oring. T he NetScaler appliance establishes a T CP connection. After the connection is established,
the appliance performs an SSL handshake with the server. After the handshake is over, the appliance closes the
connection.
Secure HT T P monit oring. T he NetScaler appliance establishes a T CP connection. After the connection is established,
the appliance performs an SSL handshake with the server. When the SSL connection is established, the appliance sends
HT T P requests over the encrypted channel and checks the response codes.
T he following table describes the available built-in monitors for monitoring SSL services.
TCP TCP connection Successful TCP connection established and successful SSL handshake.
SSL handshake
HT T P TCP connection Successful TCP connection is established, successful SSL handshake is performed, and
expected HT T P response code in server HT T P response is encrypted.
SSL handshake
Encrypted HT T P
request
TCP-ECV TCP connection Successful TCP connection is established, successful SSL handshake is performed, and
expected TCP data is received from the server.
SSL handshake
(Data sent to a
server is
encrypted.)
HT T P- TCP connection Successful TCP connection is established, successful SSL handshake is performed, and
ECV expected HT T P data is received from the server.
SSL handshake
(Encrypted HT T P
request)
add lb monit or <monitorName> <type> -script Name <string> -script Args <string> -secure ( YES | NO )
> add monitor FTPS_MON USER –scriptname nsftp.pl –scriptargs “file=example;user=sam;password=sam_passwd” –secure YES
OR
add monitor mon1 FTP-EXTENDED -username root -password freebsd -filename fsdf
1. Navigate to T raf fic Management > Load Balancing > Monit ors and, for T ype , specify USER or F T P -EXT ENDED .
2. Depending on which type you specified, set one of the following groups of parameters:
a. USER : In Special Paramet ers , specify a Script Name (nsftp.pl) and the Script Argument s .
b. F T P -EXT ENDED : In Special Paramet ers , specify a F ile Name , User Name , and Password .
To configure built-in monitors to check the state of FT P services, see Configuring Monitors in a Load Balancing Setup.
To configure secure monit oring using SF T P by using t he Net Scaler command line
add lb monit or <monitorName> <type> -script Name <string> -script Args <string> -secure ( YES | NO )
1. Navigate to T raf fic Management > Load Balancing > Monit ors and in T ype specify USER .
Important
T his feature is supported only on the new Default profiles. For more information about these profiles, see Enhanced SSL Profiles
Infrastructure Overview.
A monitor inherits either the global settings or the settings of the service to which it is bound. If a monitor is bound to a
non-SSL or non-SSL_TCP service, such as SSL_BRIDGE, you cannot configure it with SSL settings such as the protocol
version or the ciphers to be used. T herefore, if your deployment requires SSL-based monitoring of the back-end servers, the
monitoring is ineffective.
You can have more control over SSL-based monitoring of back-end servers, by binding an SSL profile to a monitor. An SSL
profile contains SSL parameters, cipher bindings, and ECC bindings. For example, you can set server authentication, ciphers,
and protocol version in an SSL profile and bind the profile to a monitor. Note that to perform server authentication, you
must also bind a CA certificate to a monitor. To perform client authentication, you must bind a client certificate to the
monitor. New parameters for the "bind lb monitor" command enable you to do so.
Note
T he SSL settings take effect only if you add a secure monitor. Also, the SSL profile type must be Ba ckEnd .
HT T P
HT T P-ECV
T CP
T CP-ECV
HT T P-INLINE
bind monit or <monitor name> -cert keyName <string> [(-CA [-crlCheck ( Mandat ory | Opt ional ) | -ocspCheck (
Mandat ory | Opt ional )]
Paramet er Specifies
sipmethod T ype of SIP request used to probe the SIP service. Specify one of the following methods:
INVIT E
OPT ION (the default)
REGIST ER
respcode SIP response code with which the SIP service responds the probe request.
Default: 200.
Paramet er Specifies
userName User name on the RADIUS/NNT P/FT P/FT P-EXT ENDED/MYSQL/POP3 server. T his user name is used in
the probe.
password Password used in monitoring RADIUS/NNT P/FT P/FT P-EXT ENDED/MYSQL/POP3/LDAP servers.
radKey Shared secret key value that the RADIUS server uses during client authentication.
radNASid NAS-ID that is encapsulated in the payload when an access request is made.
radNASip T he IP address that is encapsulated in the payload when an access-request is made. When radNASip is
not configured, the NetScaler sends the mapped IP address (MIP) to the RADIUS server as the NAS IP
address.
To monitor a RADIUS service, you must configure the RADIUS server to which it is bound as follows:
1. Add the user name and password of the client that the monitor will use for authentication to the RADIUS
authentication database.
2. Add the IP address and secret key of the client to the appropriate RADIUS database.
3. Add the IP addresses that the appliance uses to send RADIUS packets to the RADIUS database. If the NetScaler
appliance has more than one mapped IP address, or if a subnet IP address (SNIP) is used, you must add the same secret
key for all of the IP addresses.
Caution: If the IP address used by the appliance are not added to the RADIUS database, the RADIUS server will discard all
packets.
To configure built-in monitors to check the state of RADIUS server, see Configuring Monitors in a Load Balancing Setup.
When configuring a RADIUS accounting monitor, you must specify a secret key. You can specify optional parameters, each
of which represents a RADIUS attribute, such as Acct-Status-Type and Framed-IP-Address. For information about these
attributes, see RFC 2865, "Remote Authentication Dial In User Service (RADIUS)," and RFC 2866, "RADIUS Accounting."
At the command prompt, type the following commands to configure a RADIUS accounting monitor and verify the
configuration:
add lb monitor <monitorName> RADIUS_ACCOUNT ING [-userName <string>] {-password } {-radKey } [-radNASip
<ip_addr>] [-radAccountT ype <positive_integer>] [-radFramedIP <ip_addr>] [-radAPN <string>] [-radMSISDN <string>]
[-radAccountSession <string>]
show lb monitor <monitorName>
Example
add lb monitor radAccntMon RADIUS_ACCOUNTING -radKey "8d#>9jr4rV)L7%a2-zW13sM"
Parameter Parameter
query The DNS query (domain name) sent to the DNS service that is being monitored. Default value: “\007” If the DNS query succeeds, the service is
marked as UP; otherwise, it is marked as DOWN.
For a reverse monitor, if the DNS query succeeds, the service is marked as DOWN; otherwise, it is marked as UP. If no response is received, the
service is marked as DOWN.
queryType The type of DNS query that is sent. Possible values: Address, Zone.
IPAddress List of IP addresses that are checked against the response to the DNS monitoring probe.
IPv6 Select this check box if the IP address uses IPv6 format.
To configure the built-in DNS or DNS-TCP monitors, see Configuring Monitors in a Load Balancing Setup.
You configure the LDAP monitor to define the search that it should perform when sending a query. You can use the Base
DN parameter to specify a location in the directory hierarchy where the LDAP server should start the test query. You can
use the Attribute parameter to specify an attribute of the target entity.
Paramet er Specifies
baseDN Base name for the LDAP monitor from where the LDAP search must start. If the LDAP server is running
locally, the default value of base is dc=netscaler, dc=com.
To configure the built-in LDAP monitor, see Configuring Monitors in a Load Balancing Setup.
Paramet er Specifies
To configure built-in MySQL monitor, see Configuring Monitors in a Load Balancing Setup.
Paramet er Specifies
snmpVersion SNMP version that is used for load monitoring. Possible Values: V1, V2.
To configure the built-in SNMP monitor, see Configuring Monitors in a Load Balancing Setup.
Paramet er Specifies
userName User name on the RADIUS/NNT P/FT P/FT P-EXT ENDED/MYSQL/POP3 server. T his user name is used in
the probe.
password Password used in monitoring RADIUS/NNT P/FT P/FT P-EXT ENDED/MYSQL/POP3/LDAP servers.
To configure the built-in NNT P monitor, see Configuring Monitors in a Load Balancing Setup.
Paramet er Specifies
userName User name POP3 server. T his user name is used in the probe.
To configure the built-in POP3 monitor, see Configuring Monitors in a Load Balancing Setup.
Paramet er Specifies
userName User name SMT P server. T his user name is used in the probe.
To configure the built-in SMT P monitor, see Configuring Monitors in a Load Balancing Setup.
T he NetScaler appliance can be configured to load balance RT SP servers using two topologies: NAT -off and NAT -on. RT SP
servers send their responses directly to the client, bypassing the appliance. T he appliance must be configured to monitor
RT SP services differently depending upon which topology your network uses. T he appliance can be deployed either in inline
or non-inline mode in both NAT -off and NAT -on mode.
In NAT -off mode, the appliance operates as a router: it receives RT SP requests from the client and routes them to the
service that it selects using the configured load balancing method. If your load balanced RT SP servers are assigned publicly
accessible FQDNs in DNS, the load balanced servers send their responses directly to the client, bypassing the appliance. T he
following figure demonstrates this configuration.
1. T he client sends a DESCRIBE request to the appliance. T he appliance uses the configured load balancing method to
choose a service, and routes the request to Media Server-1.
2. T he client sends a SET UP request to the appliance. If the RT SP session ID is exchanged in the DESCRIBE request, the
appliance, using RT SPSID persistence, routes the request to Media Server-1. If the RT SP session ID is exchanged in the
SET UP request, the appliance does one of the following:
If the RT SP request comes on the same T CP connection, it routes the request to Media Server-1, maintaining
persistence.
If the request arrives on a different T CP connection, it uses the configured load balancing method to choose a
service, and sends the request to that service, not maintaining persistence. T his means that the request may be sent
to a different service.
3. Media Server-1 receives the SET UP request from the appliance, allocates resources to process the RT SP request, and
sends the appropriate session ID to the client.
In NAT -on mode, the appliance receives RT SP requests from the client and routes those requests to the appropriate media
server using the configured load balancing method. T he media server then sends its responses to the client through the
appliance, as illustrated in the following diagram.
1. T he client sends a DESCRIBE request to the appliance. T he appliance uses the configured load balancing method to
choose a service, and routes the request to Media Server-1.
2. T he client sends a SET UP request to the appliance. If the RT SP session ID is exchanged in the DESCRIBE request, the
appliance, using the RT SPSID persistence, routes the request to Media Server-1. If the RT SP session ID is exchanged in
the SET UP request, the appliance does one of the following:
T he RT SP monitor uses the RT SP protocol to evaluate the state of the RT SP services. T he RT SP monitor connects to the
RT SP server and conducts a sequence of handshakes to ensure that the server is operating correctly.
Paramet er Specifies
rtspRequest T he RT SP request string that is sent to the RT SP server (for example, OPT IONS *). T he default value is
07. T he length of the request must not exceed 163 characters.
respCode Set of response codes that are expected from the service.
For instructions on configuring an RT SP monitor, see Configuring Monitors in a Load Balancing Setup.
To configure a CIT RIX-XML-SERVICE monitor, you need to specify the application name in addition to setting the standard
parameters. T he application name is the name of the application that has to be run to monitor the state of the XML
Broker service. T he default application is Notepad.
To configure monitors for XML Broker services, see "Configuring Monitors in a Load Balancing Setup."
Note
T he parameter “Application Name” for Citrix-XML-Service monitor is invalid for XA and XD versions 7 and later. T he probing criteria
is different from XA/XD 7. However, you can still use application name for versions below XA/XD 7.
ARP locates a hardware address for a load balanced server when only the network layer address is known. ARP works with
IPv4 to translate IP addresses to Ethernet MAC addresses. ARP monitoring is not relevant to IPv6 networks, and is
therefore not supported on those networks.
For instructions on configuring an ARP monitor, see Configuring Monitors in a Load Balancing Setup.
T he monitor sends a probe to the XenDesktop Delivery Controller server in the form of an XML message. If the server responds to the probe with the
identity of the server farm, the probe is considered to be successful and the server's status is marked as UP. If the HT T P response does not have a success
code or the identity of the server farm is not present in the response, the probe is considered to be a failure and the server's status is marked as DOWN.
T he Validate Credentials option determines the probe to be sent by the monitor to the XenDesktop Delivery Controller server, that is, whether to request
only the server name or to also validate the login credentials.
Note: Regardless of whether or not the user credentials (user name, password and domain) are specified on the CIT RIX-XD-DDC monitor, the XenDesktop
Delivery Controller server validates the user credentials only if the option to validate credentials is enabled on the monitor.
If you use the wizard for configuring the load balancing of the XenDesktop servers, the CIT RIX-XD-DDC monitor is automatically created and bound to
the XenDesktop Delivery Controller services.
At the command prompt, type the following commands to add an XD-DDC monitor and verify the configuration:
add lb monitor <monitorName> <monitorT ype> -userName <userName> -password <password> -ddcDomain <ddc_domain_name> -validateCred YES
show lb monitor <monitorName>
Example
> add lb monitor xdddcmon Citrix-xd-ddc -userName Administrator -password E12Dc35450a1 -ddcDomain dhop -validateCred YES
Done
> show lb monitor xdddcmon
1) Name......:xdddcmon Type......:CITRIX-XD-DDC State......: ENABLED
Standard parameters:
Interval......:..5 sec...Retries......:..3
Response timeout......:..2 sec...Down time......:..30 sec
Reverse......:..NO...Transparent......:..NO
Secure......:..NO...LRTM......:..ENABLED
Action......:..Not applicable...Deviation......:..0 sec
Destination IP......:..Bound service
Destination port......:..Bound service
Iptunnel......:..NO
TOS......:..NO...TOS ID......:..0
SNMP Alert Retries......:..0...Success Retries......:..1
Failure Retries......:..0
Special parameters:
User Name..........:"Administrator"
Password...........:*****
DDC Domain.........: "dhop"
Done
set lb monitor <monitorName> <monitorT ype> -userName -password -ddcDomain <ddc_domain_name> -validateCred YES
Example
> set lb monitor XD_DDC_21.21.21.22_443_mn CITRIX-xd-ddc -userName Administrator -password D123S1R2A123 -ddcDomain dhop -validateCred YES
Done
A CIT RIX-WEB-INT ERFACE monitor can monitor the Web Interface services efficiently because it monitors a dynamic page
at the location specified by the site path. T he monitor checks for critical failures in resource availability.
T o mark a service as UP, the appliance expects the following response from the server:
1. For the first GET request, 200 OK .
2. For the POST request with credentials, 302 Found with the required WIAuthID.
3. For the last GET request with session cookie, 200 OK.
Note: If a redirect URL is configured, 302 Found is expected in the first request before 200 OK.
Note: Monitor probes originate from the NetScaler IP (NSIP) address.
When you configure a CIT RIX-WEB-INT ERFACE monitor, specify the site path to the location of the http page that
displays the data collected by the monitor. To monitor the status of the service, in the specified site path, you can view the
data updated dynamically by the monitoring script auth/nocookies.aspx.
Note: End the site path with a slash (/) to indicate that the monitored resource is dynamic.
Note: When you configure the WI-EXT ENDED monitor, when specifying the site path, do not enter a slash (/) at the end of
the path as the software internally adds a slash at the end of the path. For example, note the following command:
add monitor wi CITRIX-WI-EXTENDED -sitepath "/Citrix/DesktopWeb" -username aaa -password bbb -domain ccc
A CIT RIX-WI-EXT ENDED monitor verifies the logging process with the Web Interface service. T his monitor accesses the
login page and passes the user name, password, domain, and site path that were specified while configuring the monitor. It
verifies the validity of the login credentials, correct configuration of the monitor (for example, the site path), and the
connection with the IIS server.
Note: T he CIT RIX-WI-EXT ENDED monitor is supported only for the .NET version of the WI servers. T his monitor will not
work for the JSP version of the WI servers.
If you use the wizard for configuring load balancing of the XenDesktop servers, a CIT RIX-WEB-INT ERFACE monitor is
automatically created and bound to the WI services. T he wizard adds and binds a CIT RIX-WEB-INT ERFACE monitor by
default. If you want to add and bind a CIT RIX-WI-EXT ENDED monitor, select the Validate Credentials check box and type
the necessary data. If you do not use the wizard, add a monitor corresponding to the WI services and bind it to each WI
service that you create.
For instructions on using the wizard, see Configuring XenDesktop for Load Balancing or Configuring XenApp for Load
Balancing.
For instructions on adding a CIT RIX-WEB-INT ERFACE monitor, see Creating Monitors.
For instructions on binding a monitor to a service, see Binding Monitors to Services.
add lb monitor <monitorName> <monitorT ype> -sitePath <site_path> -dispatcherIP 127.0.0.1 -dispatcherPort 3013
Navigate to Traffic Management > Load Balancing > Monitors, and create a WI monitor of type CIT RIX-WEB-INT ERFACE
or CIT RIX-WI-EXT ENDED.
Note: Monitor probes originate from the NetScaler IP (NSIP) address. However, if the subnet of a StoreFront server is
different from that of the appliance, then the subnet IP (SNIP) address is used.
Beginning with release 10.1 build 120.13, you can also bind a StoreFront monitor to a service group. A monitor is bound to
each member of the service group and probes are sent to the IP address and port of the bound member (service). Also,
because each member of a service group is now monitored by using the member's IP address, you can now use the
StoreFront monitor to monitor StoreFront cluster nodes that are added as members of the service group.
In earlier releases, the StoreFront monitor tried to authenticate anonymous stores. As a result, a service could be marked as
DOWN and you could not launch XenApp or XenDesktop by using the URL of the load balancing virtual server.
From build 64.x, the probe order has changed. T he monitor now determines the state of the StoreFront store by
successively probing the account service, the discovery document, and then the authentication service, and skips
authentication for anonymous stores.
T he hostname parameter for StoreFront monitors is deprecated. T he secure parameter is now used to determine whether
to use HT T P (the default) or HT T PS to send monitor probes.
At the command prompt, type the following commands to configure a StoreFront monitor and verify the configuration:
Example
add lb monitor storefront_ssl STOREFRONT -storename myStore -storefrontacctservice YES -secure YES
Navigate to Traffic Management > Load Balancing > Monitors, and create a WI monitor of type STOREFRONT .
Note
For more information about the StoreFront monitors, see Load balancing with NetScaler.
With any of these types of monitors, you can use the supplied functionality, or you can create your own scripts and use
those scripts to determine the state of the service to which the monitor is bound.
Note: Inline monitors cannot be bound to HT T P or HT T PS Global Server Load Balancing (GSLB) remote or local services
because these services represent virtual servers rather than actual load balanced Web servers.
Inline monitors have a time-out value and a retry count when probes fail. You can select any of the following action types
for the NetScaler appliance to take when a failure occurs:
NONE. No explicit action is taken. You can view the service and monitor, and the monitor indicates the number of
current contiguous error responses and cumulative responses checked.
LOG. Logs the event in ns/syslog and displays the counters.
DOWN. Marks the service down and does not direct any traffic to the service. T his setting breaks any persistent
connections to the service. T his action also logs the event and displays counters.
After the service is down, the service remains DOWN for the configured down time. After the DOWN time elapses, the
inline monitor uses the configured URL to probe the service to see if it is available again. If the probe succeeds, the state of
the service is changed to UP. Traffic is directed to the service, and monitoring resumes as before.
Dispat cher. A process, on the appliance, that listens to monitoring requests. A dispatcher can be on the loopback
IP address (127.0.0.1) and port 3013. Dispatchers are also known as internal dispatchers. A dispatcher can also be a
web server that supports Common Gateway Interface (CGI). Such dispatchers are also known as external
dispatchers. T hey are used for custom scripts that do not run on the FreeBSD environment, such as .NET scripts.
Note: You can configure the monitor and the dispatcher to use HT T PS instead of HT T P by enabling the “secure”
option on the monitor and configure it as an external dispatcher. However, an internal dispatcher understands only
HT T P, and cannot use HT T PS.
In a HA setup, the dispatcher runs on both the primary and secondary NetScaler appliances. T he dispatcher remains
inactive on the secondary appliance.
Script . T he script is a program that sends custom probes to the load balanced server and returns the response code
to the dispatcher. T he script can return any value to the dispatcher, but if a probe succeeds, the script must return a
value of zero (0). T he dispatcher considers any other value as probe failure.
T he NetScaler appliance is bundled with sample scripts for commonly used protocols. T he scripts exist in the
/nsconfig/monitors directory. If you want to add a new script, add it there. If you want to customize an existing
script, create a copy with a new name and modify it.
Important: Starting with release 10.1 build 122.17, the script files for user monitors are in a new location.
If you upgrade an MPX or VPX virtual appliance to release 10.1 build 122.17 or later, the changes are as follows:
A new directory named conflicts is created in /nsconfig/monitors/ and all the built-in scripts of the previous builds
If you provision a virtual appliance with release 10.1 build 122.17 or later, the changes are as follows:
All built-in scripts are available in the /netscaler/monitors/ directory.
T he /nsconfig/monitors/ directory is empty.
If you create a new custom script, you must save it in the /nsconfig/monitors/ directory.
T he maximum number of characters in the name of the script must not exceed 63.
T he maximum number of script arguments that can be provided to a script must not exceed 512.
T he maximum number of characters that can be provided in the parameter script arguments must not exceed 639.
To debug the script, you must run it by using the nsumon-debug.pl script from the NetScaler command line. You use
the script name (with its arguments), IP address, and the port as the arguments of the nsumon-debug.pl script. Users
must use the script name, IP address, port, time-out, and the script arguments for the nsumon-debug.pl script.
Import ant : Starting with release 10.5 build 57.x, and 11.0 script files for user monitors support IPv6 addresses and
include the following changes:
For the following protocols, new pm files have been included for IPv6 support.
Radius
NNT P
POP3
SMT P
T he following sample scripts in /netscaler/monitors/ has been updated for IPv6 support:
nsbmradius.pl
nsldap.pl
nsnntp.pl
nspop3 nssf.pl
nssnmp.pl
nswi.pl
nstftp.pl
nssmtp.pl
nsrdp.pl
nsftp.pl
nsappc.pl
After upgrading to release 10.5 build 57.x, or 11.0, if you want to use your existing custom scripts with IPv6
services, make sure that you update the existing custom scripts with the changes provided in the updated
sample scripts in /netscaler/monitors/.
Note: T he sample script nsmysql.pl does not support IPv6 address. If an IPv6 service is bound to a user monitor
that uses nsmysql.pl, the probe will fail.
T he following LB monitor types have been updated to support IPv6 addresses:
USER
SMT P
NNT P
LDAP
SNMP
POP3
FT P_EXT ENDED
STOREFRONT
APPC
If you are creating a new custom script that uses one of these LB monitors types, make sure that you include
IPv6 support in the custom script. Refer to the associated sample script in /netscaler/monitors/ for the changes
that you have to make in the custom script for IPv6 support.
To track the status of the server, the monitor sends an HT T P POST request to the configured dispatcher. T his POST
request contains the IP address and port of the server, and the script that must be executed. T he dispatcher executes the
script as a child process, with user-defined parameters (if any). T hen, the script sends a probe to the server. T he script sends
the status of the probe (response code) to the dispatcher. T he dispatcher converts the response code to an HT T P
response and sends it to the monitor. Based on the HT T P response, the monitor marks the service as up or down.
T he appliance logs the error messages to the /var/nslog/nsumond.log file when user monitor probes fail. T he following
table lists the user monitors and the possible reasons for failure.
Missing or invalid script arguments, which can include an invalid number of arguments or
argument format.
Monitor fails to locate an entry for the target entity in the LDAP server.
Missing or invalid script arguments, which can include an invalid number of arguments or
argument format.
Logon fails.
Missing or invalid script arguments, which can include an invalid number of arguments or
argument format.
Logon fails.
Missing or invalid script arguments, which can include an invalid number of arguments or
argument format.
Logon fails.
Missing or invalid script arguments, which can include an invalid number of arguments or
argument format.
Logon fails.
T he monitor threshold value setting is greater than or equal to the actual threshold of the
monitor.
RDP (Windows Terminal Missing or invalid script arguments, which can include an invalid number of arguments or
Server) argument format.
Mismatch in versions.
You can view the log file from the NetScaler command line by using the following commands, which open a BSD shell,
display the log file on the screen, and then close the BSD shell and return you to the NetScaler command prompt:
> shell
root@ns# cat /var/nslog/nsumond.log
root@ns# exit
>
User monitors also have a time-out value and a retry count for probe failures. You can use user monitors with non-user
monitors. During high CPU utilization, a non-user monitor enables faster detection of a server failure.
If the user monitor probe times out during high CPU usage, the state of the service remains unchanged.
Note
For scriptable monitors, the response timeout must be configured to a value equal to expected timeout + 1 second.
For example, if you expect the timeout to be 4 seconds, configure the response timeout as 5 seconds.
HT T P Meaning
response
code
500 - Internal Internal error/resource constraints in dispatcher (out of memory, too many connections, unexpected
server error system error, or too many processes). T he service is not marked DOWN.
You configure the user monitor for HT T P by using the following parameters.
Paramet er Specifies
scriptArgs T he strings that are added in the POST data. T hey are copied to the request verbatim.
To create a user monitor to monitor HT T P, see Configuring Monitors in a Load Balancing Setup.
A possible solution is to use a Perl script that initiates an FT P session with the server and checks for the presence of the
file. You can then create a user monitor that uses the Perl script. T he NetScaler includes such a Perl script (nsftp.pl), in the
/nsconfig/monitors/ directory.
You can use a user monitor with an external dispatcher. Consider a case where you must track the health of a server based
on the state of an SMT P service on another server. T his scenario is illustrated in the following diagram.
T he following diagram illustrates a load monitor configured for the services described in the basic load balancing setup
discussed in Setting Up Basic Load Balancing.
Note: T he load monitor does not determine the state of the service. It only enables the appliance to consider the service
for load balancing.
After you configure the load monitor, you must then configure the metrics that the monitor will use. For load assessment,
the load monitor considers server parameters known as metrics, which are defined within the metric tables in the appliance
configuration. Metric tables can be of two types:
Local. By default, this table exists in the appliance. It consists of four metrics: connections, packets, response time, and
bandwidth. T he appliance specifies these metrics for a service, and SNMP queries are not originated for these services.
T hese metrics cannot be changed.
Cust om. A user-defined table. Each metric is associated with an OID.
NetScaler
RADWARE
CISCO-CSS
LOCAL
You can either add the appliance-generated metric tables, or you can add tables of your own choosing, as shown in the
following table. T he values in the metric table are provided only as examples. In an actual scenario, consider the real values
for the metrics.
CPU 1.2.3.4 2 70
Memory 4.5.6.7 3 80
Connections 5.6.7.8 4 90
To calculate the load for one or more metrics, you assign a weight to each metric. T he default weight is 1. T he weight
represents the priority given to each metric. If the weight is high, the priority is high. T he appliance chooses a service based
on the SOURCEIPDEST IP hash algorithm.
You can also set the threshold value for each metric. T he threshold value enables the appliance to select a service for load
balancing if the metric value for the service is less than the threshold value. T he threshold value also determines the load on
each service.
Example
1. Navigate to T raffic Management > Load Balancing > Metric T ables and create a metric table.
2. T o bind metrics, click Bind and specify a metric and an SNMP OID.
You can view the detail of all configured metric tables, such as name and type, to determine whether the metric table is
internal or created and configured.
HT T P
ICMP
T CP (from release 11.1 build 49.x)
T he following table describes the conditions of HT T P direct and reverse monitoring for a service:
HT T P response code does not match the probe's specifications. Fail Success
To configure HT T P reverse monit oring f or a service by using t he Net Scaler command line
>add lb monitor <Monitor_Name> HT T P -respCode 200 -httpRequest "HEAD /" -destIP <Primary_Service_IP_Address> -
destPort 80 -reverse YES
T he following table describes the conditions of ICMP direct and reverse monitoring for a service:
If a direct TCP monitor receives a RESET in response to a monitor probe, the service is marked DOWN. However, if a reverse
TCP monitor receives a RESET response, the probe is considered successful, and the service is marked UP.
T he following table describes the conditions of TCP reverse monitoring for a service:
To configure T CP reverse monit oring f or a service by using t he Net Scaler command line
As shown above, each service has a monitor bound to it. T he monitor probes the load balanced server via its service. As long
as the load balanced server responds to the probes, the monitor marks it UP. If the load balanced server should fail to
respond to the designated number of probes within the designated time period, the monitor marks it DOWN.
T he Create Monitor screen contains two sections, Basic Paramet ers and Advanced Paramet ers .
Depending on the monitor type, the Basic Paramet ers section contains the parameters that must be set for each
monitor. T he Advanced Paramet ers section contains the parameters that can be used in advanced use cases.
T he following figure is a sample of a Create Monitor page of the ARP monitor type.
Ret ries
Maximum number of probes to send to establish the state of a service for which a monitoring probe fails.
f ailureRet ries
Number of retries that must fail, out of the number specified for the Retries parameter, for a service to be marked as
DOWN. For example, if the Retries parameter is set to 10 and the Failure Retries parameter is set to 6, out of the ten
probes sent, at least six probes must fail if the service is to be marked as DOWN.
Number of consecutive probe failures after which the appliance generates an SNMP trap called monProbeFailed.
T he alertRetries parameter, which specifies the maximum number of consecutive monitoring-probe failures after which the
NetScaler appliance generates an SNMP trap called monProbeFailed, can now be set to a value higher than the Retries
value (which specifies the maximum number of probes to send to establish the state of a service for which a monitoring
probe failed). If the alertRetries value is higher than the Retries value, the SNMP trap is not sent until after the service is
DOWN.
For example, if you set Retries to 3, alertRetries to 12, and the time interval to 5 seconds, the service is marked DOWN after
15 seconds (3*5), but no alert is generated. If the monitor probes are still failing after 60 seconds (12*5), the NetScaler
appliance generates a monProbeFailed trap. If a probe succeeds at some time between 15 and 60 seconds, the service is
marked UP and no alert is generated.
Setting the alertRetries value to a value higher than the Retries value helps in generating only genuine alerts and avoid false
positives during scheduled restarts.
Example
1. Navigate to Conf igurat ion > T raf f ic Management > Load Balancing > Monit ors .
2. Click Add to add a new monitor or select an existing monitor and click Edit .
Note: T he destination IP address of a monitor probe can be different than the server IP address and port.
Note: T wo sets of parameters apply to monitors: those that apply to all monitors, regardless of type, and those that are
specific to a monitor type. For information on parameters for a specific monitor type, see the description for that type of
monitor.
Navigate to Traffic Management > Load Balancing > Monitors, and open a monitor to modify.
Note: When you unbind all user-configured monitors from a service or a service group, the default monitor is bound to the
service and the service group. T he default monitors then probes the service or the service groups.
1. Navigate to T raffic Management > Load Balancing > Services, and open a service to modify.
2. Click in the Monitors section, select a monitor, and click Unbind.
Note: When you remove monitors bound to a service, the default monitor is bound to the service. You cannot remove
default monitors.
1. Navigate to T raffic Management > Load Balancing > Monitors. T he details of the available monitors appear in the
Monitors pane.
For the TCP monitors, you can configure the NetScaler to close a monitor-probe connection after receiving SYN-ACK from
the service. To do so, set the value of the monitorConnectionClose parameter to RESET. If you want the monitor-probe
connection to go through the complete procedure, set the value to FIN.
Note: T he monitorConnectionClose setting is applicable to all the monitors bound to all the services configured on the
NetScaler appliance.
1. Navigate to T raffic Management > Load Balancing > Configure Load Balancing Parameters.
2. Select FIN or Reset.
You can also configure the appliance to close a monitor-probe connection at the service and service group level by setting
the monConnectionClose parameter. If this parameter is not set, the monitor connection is closed by using the value set in
the global load balancing parameters. If this parameter is set at the service or service group level, the monitor connection is
closed by sending a connection termination message, with the FIN or RESET bit set, to the service or service group.
To configure monit or-connect ion closure at t he service level by using t he Net Scaler command line
To configure monit or-connect ion closure at t he service group level by using t he Net Scaler command line
To configure monit or-connect ion closure at t he service level by using t he Net Scaler GUI
To configure monit or-connect ion closure at t he service group level by using t he Net Scaler GUI
Note: You cannot skip the maximum-client-connections check for an individual service. If you specify this option, it applies
to all the monitors bound to all the services configured on the NetScaler appliance.
To set the Skip MaxClients f or Monitor Connections option by using the command line interf ace
1. Navigate to T raffic Management > Load Balancing > Configure Load Balancing Parameters.
2. Select Skip MaxClients for Monitoring Connections.
You can set persistence for a group of virtual servers. You can bind monitors to a group of services. Creating a range of
virtual servers and services of identical type allows you to set up and configure those servers in a single procedure, which
significantly shortens the time required to configure those virtual servers and services.
By translating or masking IP addresses, you can take down virtual servers and services, and make changes to your
infrastructure, without extensive reconfiguration of your service and virtual server definitions.
T he following are the types of ranges you can specify when adding services and virtual servers to your configuration:
Numeric ranges. Instead of typing a single number, you can specify a range of consecutive numbers.
For example, you can create a range of virtual servers by specifying a starting IP address, such as 10.102.29.30, and then
typing a value for the last byte that indicates the range, such as 34. In this example, five virtual servers will be created
with IP addresses that range between 10.102.29.30 and 10.102.29.34.
For example, if you have three virtual servers named Vserver-x, Vserver-y, and Vserver-z, instead of configuring them
separately, you can type vserver [x-z] to configure them all.
Updated: 2013-11-12
Example
OR
Updated: 2013-11-12
You create a range of services as described below. If you specify a range for the service name, specify a range for the IP
address too.
After creating a service group, you can bind it to a virtual server, and you can add services to the group. You can also bind
monitors to service groups.
Using domain-name based service (DBS) group members is advantageous because you need not reconfigure the member on
the NetScaler appliance if the IP address of the member changes. T he appliance automatically senses such changes
through the configured name server. T his feature is particularly useful in cloud scenarios, where the service provider can
change a physical server or change the IP address for a service. If you specify a DBS group member, the NetScaler learns the
IP address dynamically.
You can bind both IP-based and DBS members to the same service group.
Note: If you use DBS service group members, make sure that either a name server is specified or a DNS server is configured
on the NetScaler. A domain name will be resolved into an IP address only if the corresponding address record is present on
the NetScaler or the name server.
Creating Service Groups
When you bind a service group to a virtual server, the member services are bound to the virtual server.
To bind a service group to a virtual server by using the command line interface
At the command prompt, type:
Adding services to a service group enables the service group to manage the servers. You can add the servers to a service
group by specifying the IP addresses or the names of the servers.
In the configuration utility, if you want to add a domain-name based service group member, select Server Based.
With this option, you can add any server that has been assigned a name, regardless of whether the name is an IP address or
a user-assigned name.
Note: You can add a range of IP addresses. T he IP addresses in the range must be consecutive. Specify the range by
entering the starting IP address in the IP Address text box (for example, 10.102.29.30). Specify the end byte of the IP
address range in the text box under Range (for example, 35). In the Port text box type the port (for example, 80), and
then click Add.
4. Click Create.
When you create a service group, the default monitor of the type appropriate for the group is automatically bound to it.
Monitors periodically probe the servers in the service group to which they are bound and update the state of the service
groups.
Retaining the Original State of a Service Group Member af ter Disabling and Enabling a Virtual Server
From build 64.x, a new global option, – retainDisableServer, enables you to retain a service-group member's state when a
server is disabled and reenabled.
Previously, a member's state would change from DISABLED to ENABLED under the following set of conditions:
Under these conditions, disabling the server disables all the service group members, and reenabling the server enables all the
members, by default, regardless of their earlier states. To bring the members back to the original states, you must manually
disable those member(s) in the service group. T his is a cumbersome task and prone to errors.
Updated: 2013-11-12
You can modify attributes of service group members. You can set several attributes of the service group, such as maximum
client, SureConnect, and compression. T he attributes are set on the individual servers in the service group. You cannot set
parameters on the service group such as transport information (IP address and port), weight, and server ID.
Note: A parameter you set for a service group is applied to the member servers in the group, not to individual services.
To modify a service group by using the command line interface
At the command prompt, type the following command with one or more of the optional parameters:
set servicegroup <serviceGroupName> [-type <type>] [-maxClient <maxClient>] [-maxReq <maxReq>] [-cacheable (YES|NO)]
[-cip (ENABLED|DISABLED)] [-cipHeader <cipHeader>] [-usip (YES|NO)] [-sc (ON|OFF)] [-sp (ON|OFF)] [-cltT imeout
<cltT imeout>] [-svrT imeout <svrT imeout>] [-cka (YES|NO)] [-T CPB (YES|NO)] [-CMP (YES|NO)] [-maxBandwidth
<maxBandwidth>] [-maxT hreshold <maxT hreshold>] [-state (ENABLED|DISABLED)] [-downStateFlush
(ENABLED|DISABLED)
Example
Updated: 2013-09-04
When you remove a service group, the servers bound to the group retain their individual settings and continue to exist on
the NetScaler.
rm servicegroup <ServiceGroupName>
Example
rm servicegroup Service-Group-1
To remove a service group by using the configuration utility
1. Navigate to Traf f ic Management > Load Balancing > Service Groups.
2. Select a service group, and click Delete.
Updated: 2013-11-12
When you unbind a member from the service group, the attributes set on the service group will no longer apply to the
member that you unbound. T he member services retains its individual settings, however, and continues to exist on the
NetScaler.
To unbind members from a service group by using the command line interface
At the command prompt, type:
Updated: 2013-11-12
When you unbind a service group from a virtual server, the member services are unbound from the virtual server and
To unbind a service group from a virtual server by using the command line
interface
At the command prompt, type:
Updated: 2013-12-10
When you unbind a monitor from a service group, the monitor that you unbound no longer monitors the individual services
that constitute the group.
To unbind a monitor from a service group using the command line interface
At the command prompt, type:
Updated: 2013-09-04
When you enable a service group and the servers, the services belonging to the service group are enabled. Similarly, when a
service belonging to a service group is enabled, the service group and the service are enabled. By default, service groups are
enabled.
After disabling an enabled service, you can view the service using the configuration utility or the command line to see the
amount of time that remains before the service goes DOWN.
In the Service Groups page, the Effective State column displays the status of the service groups. Status UP/DOWN in the
Effective State column is clickable. You can click the status and get the list of members along with their status in the same
view. Select a member and click the Monitor Details button to view the reason for the status being DOWN.
Note: Prior to NetScaler release 12.0 build 56.20, the status in the Effective State column was not clickable.
Updated: 2013-09-04
You can view the following settings of the configured service groups: name, IP address, state, protocol, maximum client
To view the properties of a service group by using the command line interface
At the command prompt, type one of the following commands to display the group properties or the properties and the
group members:
Example
Updated: 2013-09-04
You can view service-group statistical data, such as rate of requests, responses, request bytes, and response bytes. T he
NetScaler appliance uses the statistics of a service group, such as these, to balance the load on the services.
To view the statistics of a service group by using the command line interface
At the command prompt, type:
In large-scale deployments, the same service group can be bound to multiple load balancing virtual servers. In such a case,
instead of viewing each virtual server to see the service group it is bound to, you can view a list of all the load balancing
virtual servers bound to a service group. You can view the following details of each virtual server:
Name
State
IP address
To display the virtual servers bound to a service group by using the command line
interface
At the command prompt, type the following command to display the virtual servers bound to a service group:
T he process of name resolution for a domain based server might return more than one IP address. T he number of IP
addresses in the DNS response is determined by the number of address (A) records configured for the domain name, on the
name server. Even if the name resolution process returns multiple IP addresses, only one IP address is bound to the service
group. To scale up or scale down a service group, you need to manually bind and unbind additional domain based servers to
and from the service group, respectively.
However, you can configure a domain based service group to scale automatically on the basis of the complete set of IP
addresses returned by a DNS name server for a domain based server. T o configure automatic scaling, when binding a
domain based server to a service group, enable the automatic scaling option. Following are the steps for configuring a
domain based service group that scales automatically:
Add a name server for resolving domain names. For more information about configuring a name server on the appliance,
see Adding a Name Server.
Add a domain based server. For information about adding a domain based server, see Adding a Server.
Add a service group and associate the domain based server to the service group, with the autoscale option set to DNS.
For information about adding a service group, see Configuring Service Groups.
When a domain based server is bound to a service group and the automatic scaling option is set on the binding, a UDP
monitor and a TCP monitor are automatically created and bound to the domain based server. T he two monitors function as
resolvers. T he TCP monitor is disabled by default, and the appliance uses the UDP monitor to send DNS queries to the name
server to resolve the domain name. If the DNS response is truncated (has the TC flag set to 1), the appliance falls back to
TCP and uses the TCP monitor to send the DNS queries over TCP. T hereafter, the appliance continues to use only the TCP
monitor.
T he DNS response from the name server might contain multiple IP addresses for the domain name. With the automatic
scaling option set, the appliance polls each of the IP addresses by using the default monitor, and then includes in the service
group only those IP addresses that are up and available. After the IP address records expire, as defined by their time-to-live
(T T L) values, the UDP monitor (or the TCP monitor, if the appliance has fallen back to using the TCP monitor) queries the
name server for domain resolution and includes any new IP addresses in the service group. If an IP address that is part of
the service group is not present in the DNS response, the appliance removes that address from the service group after
gracefully closing existing connections to the group member, a process during which it does not allow any new connections
to be established with the member. If a domain name that resolved successfully in the past results in an NXDOMAIN
response, all the service group members associated with that domain are removed.
Static (IP-address based) members and dynamically scaling domain based members can coexist in a service group. You can
also bind members with different domain names to a service group with the automatic scaling option set. However, each
domain name associated with a service group must be unique within the service group. You must enable the automatic
scaling option for each domain based server that you want to use for automatic service group scaling. If an IP address is
common to one or more domains, the IP address is added to the service group only once.
At the command prompt, type the following commands to configure the service group and verify the configuration:
add serviceGroup <serviceGroupName> <serverName> <port> -autoScale (YES | NO)
show serviceGroup <serviceGroupName>
Example
In the following example, server1 is a domain based server. T he DNS response contains multiple IP addresses. Five addresses
are available and are added to the service group.
2) 192.0.2.32:80 State: UP Server Name: server1 (Auto scale) Server ID: None Weight: 1
3) 192.0.2.36:80 State: UP Server Name: server1 (Auto scale) Server ID: None Weight: 1
4) 192.0.2.55:80 State: UP Server Name: server1 (Auto scale) Server ID: None Weight: 1
5) 192.0.2.80:80 State: UP Server Name: server1 (Auto scale) Server ID: None Weight: 1
When configured for a domain-based server, IP address translation enables the appliance to locate an alternate server IP
address in the event that you take the server down for maintenance or if you make any other infrastructure changes that
affect the server.
When configuring the mask, you must use standard IP mask values (a power of two, minus one) and zeros, for example,
255.255.0.0. Non-zero values are only permitted in the starting octets.
When you configure a translation IP for a server, you create a 1:1 correspondence between a server IP address and an
alternate server that shares leading or trailing octets in its IP address. T he mask blocks particular octets in the original
server's IP address. T he DNS-resolved IP address is transformed to a new IP address by applying the translation IP address
and the translation mask.
For example, you can configure a translation IP address of 10.20.0.0 and a translation mask of 255.255.0.0. If a DNS-
resolved IP address for a server is 40.50.27.3, this address is transformed to 10.20.27.3. In this case, the translation IP
address supplies the first two octets of the new address, and the mask passes through the last two octets from the
original IP address. T he reference to the original IP address, as resolved by DNS, is lost. Monitors for all services to which the
server is bound also report on the transformed IP address.
When configuring a translation IP address for a domain-based server, you specify a mask and an IP address to which the
DNS-resolved IP address is to be translated.
Note: T ranslation of the IP address is only possible for domain-based servers. You cannot use this feature for IP-based
servers. T he address pattern can be based on IPv4 addresses only.
To configure a translation IP address f or a server by using the command line interf ace
Navigate to Traffic Management > Load Balancing > Servers, create a domain-based server, and specify a translation IP
address.
By configuring a mask for a virtual server IP address, you can avoid reconfiguration of your virtual servers due to a change in
routing or another infrastructure change. T he mask allows the traffic to continue to flow without extensive
reconfiguration of your virtual servers.
T he mask for a virtual server IP address works somewhat differently from the IP pattern definition for a server described in
Translating the IP Address of a Domain-Based Server. For a virtual server IP address mask, a non-zero mask is interpreted as
an octet that is considered. For a service, the non-zero value is blocked.
Additionally, for a virtual server IP address mask, either leading or trailing values can be considered. If the virtual server IP
address mask considers values from the left of the IP address, this is known as a forward mask. If the mask considers the
values to the right side of the address, this is known as a reverse mask.
Note: T he NetScaler appliance evaluates all forward mask virtual servers before evaluating reverse mask virtual servers.
When masking a virtual server IP address, you also need to create an IP address pattern for matching incoming traffic with
the correct virtual server. When the appliance receives an incoming IP packet, it matches the destination IP address in the
packet with the bits that are considered in the IP address pattern, and after it finds a match, it applies the IP address mask
to construct the final destination IP address.
In this case, the first 16 bits in the original destination IP address match the IP address pattern for this virtual server, so this
incoming packet is routed to this virtual server.
If a destination IP address matches the IP patterns for more than one virtual server, the longest match takes precedence.
Consider the following example:
T he pattern associated with Virtual Server 2 matches more bits than that associated with Virtual Server 1, so IPs that
match it will be sent to Virtual Server 2.
If you configure your NetScaler appliance to use domain names for your servers rather than IPs, you may also need to set
up IP translation and masking for those servers.
T o configure load balancing for commonly used protocols, see the following sections:
Load Balancing for a Group of FT P Servers
Load Balancing DNS Servers
Load Balancing Domain-Name Based Services
Load Balancing a Group of SIP Servers
Load Balancing RT SP Servers
Load Balancing of Remote Desktop Protocol (RDP) Servers
T he following diagram describes the topology of a load balancing configuration for a group of FT P servers.
In the diagram, the services Service-FT P-1, Service-FT P-2, and Service-FT P-3 are bound to the virtual server Vserver-LB-1.
Vserver-LB-1 forwards the client’s connection request to one of the services using the least connection load balancing
method. Subsequent requests are forwarded to the service that the appliance initially selected for load balancing.
T he following table lists the names and values of the basic entities configured on the appliance.
T he following diagram shows the load balancing entities, and the values of the parameters that need to be configured on
the appliance.
T he appliance can also provide a passive FT P option to access FT P servers from outside of a firewall. When a client uses the
passive FT P option and initiates a control connection to the FT P server, the FT P server also initiates a control connection
to the client. It then initiates a data connection to transfer a file through the firewall.
To create services and virtual servers of type FT P, see Setting Up Basic Load Balancing. Name the entities and set the
parameters to the values described in the columns of the previous table. When you configure a basic load balancing setup, a
default monitor is bound to the services.
Next, bind the FT P monitor to the services by following the procedure described in the section Binding Monitors to Services.
add lb monitor monitor-FTP-1 FTP -interval 360 -userName User -password User
To create FTP monitors by using the configuration utility
T he following diagram describes the topology of a load balancing configuration that load balances a group of DNS services.
In the diagram, the services Service-DNS-1, Service-DNS-2, and Service-DNS-3 are bound to the virtual server Vserver-LB-1.
T he virtual server Vserver-LB-1 forwards client requests to a service using the least connection load balancing method. T he
following table lists the names and values of the basic entities configured on the appliance.
To configure a basic DNS load balancing setup, see Setting Up Basic Load Balancing. Follow the procedures to create
services and virtual servers of type DNS, naming the entities and setting the parameters using the values described in the
previous table. When you configure a basic load balancing setup, the default ping monitor is bound to the services. For
instructions on binding a DNS monitor to DNS services, you can also see Binding Monitors to Services.
T he following procedure describes the steps to create a monitor that maps a domain name to the IP address based on a
query.
add lb monitor <monitorName> DNS -query <domainName> -queryT ype <Address|ZONE> -IPAddress <ipAddress>
Example
add lb monitor monitor-DNS-1 DNS -query www.citrix.com -queryType Address -IPAddress 10.102.29.66
When you configure services with domain names instead of IP addresses, and if the name server resolves the domain name
to a new IP address, the monitor bound to the service runs a health check on the new IP address, and updates the service
IP address only when the IP address is found to be healthy. T he monitor could be the default monitor bound to the service
or you can bind any other supported monitor. It probes the service at regular intervals defined in the monitor parameters. If
the domain name resolves to a new IP address, the monitor sends a fresh probe to check the health of the service. All
subsequent probes are at the predefined interval.
Note: When you change the IP address of a server, the corresponding service is marked down for the first client request.
T he name server resolves the service IP address to the changed IP address for the next request, and the service is marked
UP.
When the appliance receives a request for a service, it selects the target service. T his way, the appliance balances load on
your services. T he following diagram describes the topology of a load balancing configuration that load balances a group of
domain-name based servers (DBS).
T he following table lists the names and values of the basic entities configured on the appliance.
server-2 www.citrix.com 80 HT T P
To configure a basic load balancing setup, see Setting Up Basic Load Balancing. Create the services and virtual servers of
type HT T P, and name the entities and set the parameters using the values described in the previous table.
You can add, remove, enable, and disable external name servers. You can create a name server by specifying its IP address, or
you can configure an existing virtual server as the name server.
You can also add an authoritative name server that resolves the domain name to an IP address.
Note
You can add a name server of type TCP, UDP or UDP_TCP to resolver DBS probes. However, if TCP and UDP name servers coexists,
and a UDP name server receives a response with truncated bit, this response is not retried over TCP name server.
T he traffic in a SIP based communication system is routed through dedicated devices and applications (entities). In a
multimedia communication session, these entities exchange messages. T he following figure shows a basic SIP based
communication system:
A NetScaler ADC enables you to load balance SIP messages over UDP or over T CP (including T LS). You can configure the
NetScaler ADC to load balance SIP requests to a group of SIP proxy servers. T o do so, you create a load balancing virtual
server with the load balancing method and the type of persistence set to one of the following combinations:
Call-ID hash load balancing method with no persistence setting
Call-ID based persistence with least connection or round robin load balancing method
Rule based persistence with least connection or round robin load balancing method
Also, by default, the NetScaler ADC appends RPORT to the via header of the SIP request, so that the server sends the
response back to the source IP address and port from which the request originated.
Note: For load balancing to work, you must configure the SIP proxies so that they do not add private IP addresses or
private domains to the SIP header/payload. SIP proxies must add to the SIP header a domain name that resolves to the IP
address of the SIP virtual server. Also, the SIP proxies must communicate with a common database to share registration
information.
Server Initiated Traf f ic
For server-initiated SSL traffic, the NetScaler ADC uses a built-in certificate-key pair. If you want to use a custom
certificate-key pair, bind the custom certificate-key pair to the NetScaler internal service named nsrnatsip-127.0.0.1-5061.
T he NetScaler ADC can load balance SIP servers that send requests over UDP or TCP, including TCP traffic secured by T LS.
T he ADC provides the following service types to load balance the SIP servers:
SIP_UDP – Used when SIP servers send SIP messages over UDP.
SIP_T CP – Used when SIP servers send SIP messages over T CP.
SIP_SSL – Used to secure SIP signaling traffic over T CP by using SSL or T LS. T he NetScaler ADC supports the following
modes:
End-to-end T LS connection between the client, the ADC, and the SIP server.
T LS connection between the client and the ADC, and T CP connection between the ADC and the SIP server.
T CP connection between the client and the ADC, and T LS connection between the ADC and the SIP server.
T he following figure shows the topology of a setup configured to load balance a group of SIP servers sending SIP
messages over TCP or UDP.
To configure a basic load balancing setup f or SIP traf fic by using the command line interf ace
Example
add service Service-SIP-UDP-1 192.0.2.5 SIP_UDP 80
2. Create as many virtual servers as necessary to handle the services that you created. T he virtual server type must match
the type of services that you will bind to it. At the command prompt, type:
add lb vserver <name> <serverName> (SIP_UDP | SIP_TCP | SIP_SSL) <port>
Example
add lb vserver Vserver-LB-1 SIP_UDP 10.102.29.60 80
Example
bind lb vserver Vserver-LB-1 Service-SIP-UDP-1
4. (Optional) Create a custom monitor of type SIP-UDP or SIP-T CP, and bind the monitor to the service. At the command
prompt, type:
add lb monitor <monitorName> <monitorType> [<interval>]
Example
add lb monitor mon1 sip-UDP -sipMethod REGISTER -sipuRI sip:mon@test.com -sipregURI sip:mon@test.com -respcode
200
5. If you created a SIP_SSL virtual server, bind an SSL certificate key pair to the virtual server. At the command prompt,
type: At the command prompt, type:
bind ssl vserver <vServerName> -certkeyName <certificate-KeyPairName> -CA – skipCAName
Example
bind ssl vserver Vserver-LB-1 -certkeyName CertKey-SSL-1
6. Configure RNAT as required by your network topology. At the command prompt, type one of the following commands
to create, respectively, an RNAT entry that uses a network address as the condition and a MIP or SNIP as the NAT IP
address, an RNAT entry that uses a network address as the condition and a unique IP address as the NAT IP address, an
RNAT entry that uses an ACL as the condition and a MIP or SNIP as the NAT IP address, or an RNAT entry that uses an
ACL as a condition and a unique IP address as the NAT IP address:
set rnat <IPAddress> <netmask>
Example
set rnat 192.168.1.0 255.255.255.0 -natip 10.102.29.50
If you want to use a custom certificate-key pair, bind the custom certificate-key pair to the NetScaler internal service
named nsrnatsip-127.0.0.1-5061.
Example
add ssl certKey c1 -cert cert.epm -key key.ky
7. If you want to append RPORT to the SIP messages that the SIP server initiates, type the following command at the
command prompt:
set lb sipParameters -rnatSrcPort <rnatSrcPort> -rnatDstPort<rnatDstPort> -retryDur <integer> -addRportVip
<addRportVip> - sip503RateT hreshold <sip503_rate_threshold_value>
Done
Done
Done
> add lb mon mon1 sip-udp -sipMethod REGISTER -sipuRI sip:mon@test.com -sipregURI sip:mon@test.com -respcode 200
Done
Done
Done
> set lb sipParameters -rnatSrcPort 5060 -rnatDstPort 5060 -retryDur 1000 -addRportVip ENABLED -sip503RateThreshold
1000
Done
Done
Done
Done
> add lb mon mon1 sip-tcp -sipMethod REGISTER -sipuRI sip:mon@test.com -sipregURI sip:mon@test.com -respcode 200
Done
Done
Done
> set lb sipParameters -rnatSrcPort 5060 -rnatDstPort 5060 -retryDur 1000 -addRportVip ENABLED -sip503RateThreshold
1000
Done
Sample Configuration f or load balancing and securing SIP traf fic over TCP
Done
Done
Done
> add lb mon mon1 sip-tCP -sipMethod REGISTER -sipuRI sip:mon@test.com -sipregURI sip:mon@test.com -respcode 200
Done
Done
Done
Done
> set lb sipParameters -rnatSrcPort 5060 -rnatDstPort 5060 -retryDur 1000 -addRportVip ENABLED -sip503RateThreshold
1000
Done
To configure a basic load balancing setup f or SIP traf fic by using the configuration utility
1. Navigate to T raffic Management > Load Balancing > Virtual Servers, and add a virtual server of type SIP_UDP, SIP_T CP,
or SIP_SSL.
2. Click the Service section, and add a service of type SIP_UDP, SIP_T CP, or SIP_SSL.
3. (Optional) Click the Monitor section, and add a monitor of type: SIP-UDP or SIP-T CP.
4. Bind the monitor to the service, and bin