You are on page 1of 866

Citrix®NetScaler®

Installation and Configuration Guide - Volume 1
Release 8.1
Copyright and Trademark Notice
©CITRIX SYSTEMS, INC., 2009. ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED OR
TRANSMITTED IN ANY FORM OR BY ANY MEANS OR USED TO MAKE DERIVATIVE WORK (SUCH AS TRANSLATION,
TRANSFORMATION, OR ADAPTATION) WITHOUT THE EXPRESS WRITTEN PERMISSION OF CITRIX SYSTEMS, INC.
ALTHOUGH THE MATERIAL PRESENTED IN THIS DOCUMENT IS BELIEVED TO BE ACCURATE, IT IS PRESENTED
WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE ALL RESPONSIBILITY FOR THE USE
OR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS MANUAL.
CITRIX SYSTEMS, INC. OR ITS SUPPLIERS DO NOT ASSUME ANY LIABILITY THAT MAY OCCUR DUE TO THE USE OR
APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS DOCUMENT. INFORMATION IN THIS DOCUMENT IS SUBJ ECT
TO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN EXAMPLES ARE FICTITIOUS UNLESS
OTHERWISE NOTED.
The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits
for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against
harmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio-
frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio
communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be
required to correct the interference at their own expense.
Modifying the equipment without Citrix' written authorization may result in the equipment no longer complying with FCC requirements
for Class A digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required to
correct any interference to radio or television communications at your own expense.
You can determine whether your equipment is causing interference by turning it off. If the interference stops, it was probably caused by
the NetScaler Request Switch™ 9000 Series equipment. If the NetScaler equipment causes interference, try to correct the interference by
using one or more of the following measures:
Move the NetScaler equipment to one side or the other of your equipment.
Move the NetScaler equipment farther away from your equipment.
Plug the NetScaler equipment into an outlet on a different circuit from your equipment. (Make sure the NetScaler equipment and your
equipment are on circuits controlled by different circuit breakers or fuses.)
Modifications to this product not authorized by Citrix Systems, Inc., could void the FCC approval and negate your authority to operate the
product.
BroadCom is a registered trademark of BroadCom Corporation. Fast Ramp, NetScaler, and NetScaler Request Switch are trademarks of
Citrix Systems, Inc. Linux is a registered trademark of Linus Torvalds. Internet Explorer, Microsoft, PowerPoint, Windows and Windows
product names such as Windows NT are trademarks or registered trademarks of the Microsoft Corporation. NetScape is a registered
trademark of Netscape Communications Corporation. Red Hat is a trademark of Red Hat, Inc. Sun and Sun Microsystems are registered
trademarks of Sun Microsystems, Inc. Other brand and product names may be registered trademarks or trademarks of their respective
holders.
Software covered by the following third party copyrights may be included with this product and will also be subject to the software license
agreement: Copyright 1998 ©Carnegie Mellon University. All rights reserved. Copyright ©David L. Mills 1993, 1994. Copyright ©
1992, 1993, 1994, 1997 Henry Spencer. Copyright ©J ean-loup Gailly and Mark Adler. Copyright ©1999, 2000 by J ef Poskanzer. All
rights reserved. Copyright ©Markus Friedl, Theo de Raadt, Niels Provos, Dug Song, Aaron Campbell, Damien Miller, Kevin Steves. All
rights reserved. Copyright ©1982, 1985, 1986, 1988-1991, 1993 Regents of the University of California. All rights reserved. Copyright ©
1995 Tatu Ylonen, Espoo, Finland. All rights reserved. Copyright ©UNIX System Laboratories, Inc. Copyright ©2001 Mark R V
Murray. Copyright 1995-1998 ©Eric Young. Copyright ©1995,1996,1997,1998. Lars Fenneberg. Copyright ©1992. Livingston
Enterprises, Inc. Copyright ©1992, 1993, 1994, 1995. The Regents of the University of Michigan and Merit Network, Inc. Copyright ©
1991-2, RSA Data Security, Inc. Created 1991. Copyright ©1998 J uniper Networks, Inc. All rights reserved. Copyright ©2001, 2002
Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 1999-
2001©The Open LDAP Foundation. All Rights Reserved. Copyright ©1999 Andrzej Bialecki. All rights reserved. Copyright ©2000
The Apache Software Foundation. All rights reserved. Copyright (C) 2001-2003 Robert A. van Engelen, Genivia inc. All Rights
Reserved. Copyright (c) 1997-2004 University of Cambridge. All rights reserved. Copyright (c) 1995. David Greenman. Copyright (c)
2001 J onathan Lemon. All rights reserved. Copyright (c) 1997, 1998, 1999. Bill Paul. All rights reserved. Copyright (c) 1994-1997 Matt
Thomas. All rights reserved. Copyright ©2000 J ason L. Wright. Copyright ©2000 Theo de Raadt. Copyright ©2001 Patrik Lindergren.
All rights reserved.
Part No. NS-ICG1-81-0609
Last Updated: November 2009
CONTENTS
Chapter 1 Managing the Citrix NetScaler
SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv
Configuring SNMP V1 and V2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii
Configuring SNMP V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxx
Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxv
How it Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxv
Configuring Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvi
Role-Based Authorization Command Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . xli
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlii
Configuring RBAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlii
Configuring Clock Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l
NetScaler Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii
Logging NetScaler Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii
Customizing Syslog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liii
Configuring Log File Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liv
Path Maximum Transmission Unit Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . lv
How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lv
Enabling PMTU Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lvi
Autodetected Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lvi
Chapter 2 Introduction
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Additional Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3
Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Additional Maintenance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4
Subscription Advantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Knowledge Center Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Education and Training. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Documentation Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6
Chapter 3 High Availability
How High Availability Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
Considerations for a High Availability Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
ii Installation and Configuration Guide - Volume 1
Configuring High Availability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9
Configuring a Basic High Availability Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 10
Modifying an Existing HA Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13
Customizing an High Availability Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuring the Communication Intervals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16
Configuring Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17
Configuring Command Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18
Forcing a Node to Failover. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20
Improving the Reliability of a High Availability Setup . . . . . . . . . . . . . . . . . . . . . 22
Configuring Virtual MAC Addresses (VMAC) . . . . . . . . . . . . . . . . . . . . . . . . 22
Configuring High Availability Nodes in Different Subnets . . . . . . . . . . . . . . . 27
Configuring Link Redundancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
Configuring Route Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34
HA Health Check Computation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Configuring the State of a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37
Forcing the Secondary Node to Stay Secondary . . . . . . . . . . . . . . . . . . . . . . . . 37
Forcing the Primary Node to Stay Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38
Troubleshooting HA Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39
Chapter 4 Basic Network Configuration
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Configuring System-Owned IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41
Creating the NetScaler IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Configuring IP Address Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42
Modifying IP Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47
Managing IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51
Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Configuring Static ARP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53
Configuring Modes of Packet Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56
Enabling and Disabling Layer 2 Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57
Enabling and Disabling Layer 3 Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58
Enabling and Disabling MAC-Based Forwarding Mode . . . . . . . . . . . . . . . . . 59
Contents iii
Proxying Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62
Selecting the Destination IP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Selecting the Source IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63
Configuring the Use Source IP Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Configuring Network Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Managing Network Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69
Configuring Link Aggregation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73
Configuring VLANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81
Applying Rules to Classify Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82
Forwarding Packets on the System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83
Configuring VMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Configuring Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95
Configuring Simple ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Configuring Extended ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100
Configuring Bridge Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Modifying Bridge Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108
Chapter 5 Load Balancing
How Load Balancing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111
Configuring Basic Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113
Configuring a Basic Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Modifying an Existing Load Balancing Configuration . . . . . . . . . . . . . . . . . .125
Customizing Load Balancing Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131
Changing the Load Balancing Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . .132
Configuring Persistent Connections Between Clients and Servers . . . . . . . . .171
Configuring Persistence Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179
Configuring the Redirection Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182
Assigning Weights to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184
Protecting the Load Balancing Configuration against Failure. . . . . . . . . . . . . . . .185
Redirecting Client Requests to an Alternate URL . . . . . . . . . . . . . . . . . . . . . .185
Configuring a Backup LB Vserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
Diverting Excess Traffic to a Backup LB Vserver. . . . . . . . . . . . . . . . . . . . . .188
Configuring Stateful Connection Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . .191
iv Installation and Configuration Guide - Volume 1
Managing Client Traffic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Configuring Sessionless LB Vservers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195
Redirecting HTTP Requests to a Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197
Directing Requests Based on Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198
Directing Requests to a Custom Web Page. . . . . . . . . . . . . . . . . . . . . . . . . . . 199
Enabling Delayed Cleanup of Vserver Connections. . . . . . . . . . . . . . . . . . . . 200
Rewriting Ports and Protocols for HTTP Redirection. . . . . . . . . . . . . . . . . . . 201
Inserting the IP Address and Port of a Vserver in the Request Header. . . . . . 203
Managing and Monitoring Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Configuring Services for Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206
Redirecting Client Requests to a Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222
Configuring Monitors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223
Monitoring Applications and Services Using Prebuilt Monitors . . . . . . . . . . 232
Monitoring Applications and Services Using Customized Monitors . . . . . . . 247
Configuring Load Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252
Configuring Support for Third-party Load Balancers Using SASP . . . . . . . . 257
Managing a Large Scale Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263
Configuring a Range of Vservers and Services. . . . . . . . . . . . . . . . . . . . . . . . 264
Configuring Service Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266
Translating the IP Address of a Domain-Based Server. . . . . . . . . . . . . . . . . . 276
Masking a Virtual Server IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278
Configuring Load Balancing for Commonly Used Protocols. . . . . . . . . . . . . . . . 281
Load Balancing for a Group of FTP Servers. . . . . . . . . . . . . . . . . . . . . . . . . . 282
Load Balancing a Group of SSL Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284
Load Balancing DNS Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285
Load Balancing with Domain-Name Based Services . . . . . . . . . . . . . . . . . . . 287
Load Balancing a Group of SIP Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292
Configuring Load Balancing in Commonly Used Deployment Scenarios. . . . . . 295
Configuring Load Balancing in Direct Server Return Mode. . . . . . . . . . . . . . 295
Configuring Load Balancing in Direct Server Return mode using IP Tunneling.
299
Configuring Load Balancing in Direct Server Return mode using TOS . . . . 303
Configuring Load Balancing in One-arm Mode . . . . . . . . . . . . . . . . . . . . . . . 307
Configuring Load Balancing in the Inline Mode. . . . . . . . . . . . . . . . . . . . . . . 309
Load Balancing of Intrusion Detection System Servers . . . . . . . . . . . . . . . . . 310
Troubleshooting Common Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315
Chapter 6 Content Switching
How Content Switching Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317
Contents v
Configuring Basic Content Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319
Configuring Basic Content Switching Setup . . . . . . . . . . . . . . . . . . . . . . . . . .319
Modifying the Existing Content Switching Configuration . . . . . . . . . . . . . . .328
Customizing a Content Switching Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334
Setting Case Sensitivity in Policy Evaluation. . . . . . . . . . . . . . . . . . . . . . . . . .335
Setting the Precedence of Evaluation of Policy . . . . . . . . . . . . . . . . . . . . . . . .336
Setting Dependency of CS Vserver State on the State of Target LB Vservers. . .
338
Protecting the NetScaler against Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
Configuring Backup Vserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339
Diverting Excess Traffic to a Backup Vserver. . . . . . . . . . . . . . . . . . . . . . . . .341
Configuring a URL for Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342
Managing Client Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343
Redirecting Client Requests to a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344
Enabling Delayed Cleanup of Vserver Connections . . . . . . . . . . . . . . . . . . . .345
Rewriting Ports and Protocols for Redirection. . . . . . . . . . . . . . . . . . . . . . . . .346
Inserting the IP Address and Port of a Vserver in the Request Header . . . . . .346
Setting a Time-out Value for Idle Client Connections. . . . . . . . . . . . . . . . . . .348
Chapter 7 Secure Sockets Layer (SSL) Acceleration
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
How SSL Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351
Configuring SSL Offloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352
Enabling the SSL Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353
Configuring an SSL Virtual Server for Basic SSL Offloading . . . . . . . . . . . .354
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359
Managing Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360
Obtaining a Certificate from a Certificate Authority . . . . . . . . . . . . . . . . . . . .361
Exporting Existing Certificates and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . .364
Generating a New Certificate and Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369
Creating a Chain of Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373
Managing Certificates and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375
Managing Global Site Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376
Importing and Exporting SSL Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . .378
Configuring Client Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Generating Client Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381
Converting Certificates into PKCS#12 Format . . . . . . . . . . . . . . . . . . . . . . . .381
Configuring Client Certificate-Based Authentication on the NetScaler . . . . .382
Managing Server Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385
vi Installation and Configuration Guide - Volume 1
Managing Certificate Revocation Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386
Configuring an Existing CRL on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . 386
Configuring CRL Refresh Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387
Synchronizing CRLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389
Creating a CRL on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390
Customizing the SSL Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392
Configuring Diffe-Hellman (DH) Parameters. . . . . . . . . . . . . . . . . . . . . . . . . 394
Configuring Ephemeral RSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395
Configuring Session Reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Configuring Cipher Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396
Configuring SSLv2 Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398
Configuring SSL Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Configuring Advanced SSL Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399
Managing SSL Actions and Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Creating SSL Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401
Configuring Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403
Creating SSL Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409
Binding SSL Policies to a Virtual Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410
Configuring Some Commonly Used SSL Configurations . . . . . . . . . . . . . . . . . . 411
Configuring SSL Offloading with End-to-End Encryption. . . . . . . . . . . . . . . 411
Configuring Transparent SSL Acceleration. . . . . . . . . . . . . . . . . . . . . . . . . . . 414
Configuring the SSL feature with HTTP on the Front End and SSL on the Back-
end. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419
Configuring SSL Offloading with Other-TCP Protocols . . . . . . . . . . . . . . . . 421
Configuring SSL Bridging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423
Configuring the SSL Feature for Common Used Deployment Scenarios . . . . . . 426
Configuring an SSL Virtual Server for Load Balancing. . . . . . . . . . . . . . . . . 426
Configuring a Secure Content Switching Server. . . . . . . . . . . . . . . . . . . . . . . 428
Chapter 8 FIPS
How FIPS Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437
Configuring a FIPS system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Configuring the HSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438
Managing FIPS Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Creating FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Exporting FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440
Importing FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441
Importing External Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442
Configuring a Certificate Signing Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444
Configuring a High Availability (HA) FIPS system. . . . . . . . . . . . . . . . . . . . . . . 445
Contents vii
Managing Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446
Chapter 9 Optimizing Performance
Understanding and Configuring Client Keep-Alive . . . . . . . . . . . . . . . . . . . . . . .449
How Client Keep-Alive Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450
Configuring Client Keep-Alive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451
Modifying the Client Keep-Alive Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453
Understanding and Configuring TCP Buffering . . . . . . . . . . . . . . . . . . . . . . . . . .454
How TCP Buffering Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455
Configuring TCP Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457
Modifying the TCP Buffering Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459
Understanding and Configuring Compression. . . . . . . . . . . . . . . . . . . . . . . . . . . .461
How Compression Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .462
Configuring the Compression Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .464
Modifying an Existing Compression Setup . . . . . . . . . . . . . . . . . . . . . . . . . . .467
Verifying the Compression Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . .470
Customizing a Compression Setup with Policies and Actions. . . . . . . . . . . . .473
Configuring Compression for Commonly Used Deployment Scenarios. . . . .489
Configuring TCP Window Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .503
Configuring Selective Acknowledgement (SACK). . . . . . . . . . . . . . . . . . . . . . . .504
Chapter 10 Protection Features
How Citrix NetScaler Enforces Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507
How Content Filtering Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .508
Configuring Content Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
Enabling Content Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
Disabling Content Filtering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509
Creating Content Filter Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510
Creating Content Filter Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510
Binding and Unbinding the Filter Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511
Configuring Content Filtering for a Commonly Used Deployment Scenario.512
Configuring Layer 3-4 Denial of Service (SYN) Protection. . . . . . . . . . . . . . . . .517
How the System Protects Against DoS Attack. . . . . . . . . . . . . . . . . . . . . . . . .517
Using SYN Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518
How Surge Protection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519
Configuring Surge Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .521
Disabling and Re-enabling Surge Protection . . . . . . . . . . . . . . . . . . . . . . . . . .521
Setting Threshold for Surge Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .522
Configuring Surge Protection for a Commonly Used Deployment Scenario .525
viii Installation and Configuration Guide - Volume 1
How Priority Queuing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525
Configuring Priority Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Enabling Priority Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Creating the Priority Queuing Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526
Binding and enabling the Priority Queuing Policies . . . . . . . . . . . . . . . . . . . . 528
Verify the configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
Setting up Weighted Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528
How Layer 7 Denial of Service Protection Works . . . . . . . . . . . . . . . . . . . . . . . . 529
Limitations of the Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530
How DoS Protection Affects Other Features. . . . . . . . . . . . . . . . . . . . . . . . . . 530
Configuring DoS Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531
Tuning the Client Detection/JavaScript Challenge Response Rate. . . . . . . . . 533
Guidelines for HTTP DoS Protection Deployment. . . . . . . . . . . . . . . . . . . . . 534
Chapter 11 Web Server Logging
How Web Server Logging Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537
Configuring Web Server Logging Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Enabling Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538
Using CLI Commands to View Web Server Logging Status . . . . . . . . . . . . . 538
Modifying the Default Buffer Size at the GUI. . . . . . . . . . . . . . . . . . . . . . . . . 539
Modifying the Default Buffer Size at the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 539
Installing the NSWL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540
Installing on the Solaris Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . 541
Installing on the Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . . . . . 542
Installing on the FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . . . . . 542
Installing on the MAC Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543
Installing on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . . . . 544
NSWL Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544
Configuring Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546
Modifying the Web Server Log Configuration File . . . . . . . . . . . . . . . . . . . . 546
Defining Log Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548
Adding the IP Addresses of the System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551
Starting Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Stopping Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552
Log File Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555
Custom Log Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560
Apache Log Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564
Checklist for Configuring Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . 565
Contents ix
Chapter 12 Configuring Audit Server Logging
How Audit Server Logging Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .567
Configuring the Citrix NetScaler Audit Server Log . . . . . . . . . . . . . . . . . . . . . . .568
Audit Server Logging Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .569
Configuring Global Audit Server Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .570
Configuring Audit Server Action and Policy. . . . . . . . . . . . . . . . . . . . . . . . . .571
Globally Binding the Audit Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572
Installing the Audit Server Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572
Installing on the Linux Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . .574
Uninstalling on the Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . . .574
Installing on the FreeBSD Operating System. . . . . . . . . . . . . . . . . . . . . . . . . .575
Uninstalling on the FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . . .575
Installing on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . . . .576
Uninstalling on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . .576
Audit Server Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .577
Configuring Audit Server Logging on a Server Computer . . . . . . . . . . . . . . . . . .578
Defining Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .579
Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .580
Adding the IP Addresses of the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .583
Verifying Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584
Starting Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584
Stopping Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584
Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585
Checklist for Configuring Audit Server Logging. . . . . . . . . . . . . . . . . . . . . . .585
Commonly Used Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .586
Chapter 13 Advanced Network Configuration
Reverse Network Address Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .591
RNAT Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .592
RNAT in USIP, USNIP, and LLB Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . .600
Viewing NAT Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .600
Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .602
Enabling and Disabling Dynamic Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . .603
Using RIP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603
Using OSPF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .607
Using BGP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .612
x Installation and Configuration Guide - Volume 1
Route Health Injection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616
Enabling RHI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617
Limiting Host Route Advertising for VIPs . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
Advertising Networks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618
Viewing Routes Learned Through Dynamic Routing Protocols. . . . . . . . . . . 619
Link Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619
Monitoring Routers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Destination IP-Based Persistence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620
Load Balancing Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621
Implementing RNAT with Link Load Balancing . . . . . . . . . . . . . . . . . . . . . . 621
Configuring Link LB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622
Configuring the Backup Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625
Configuring RNAT with Link Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . 629
Path MTU Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633
IP Tunneling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
NetScaler as an Encapsulator (Load Balancing with DSR mode) . . . . . . . . . 634
NetScaler as a Decapsulator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634
IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639
Understanding IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642
Types of IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644
Neighbor Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645
IPv6 on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646
Enabling and Disabling IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647
Adding IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648
Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649
Adding an IPv6 Vserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Managing Static Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650
Neighbor Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652
Router Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
Viewing Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653
VLAN Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Simple Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654
Host Header Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657
Chapter 14 URL Rewrite
How URL Rewriting Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661
Contents xi
Configuring URL Rewriting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .662
Enabling URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .662
Setting the NetScaler Behaviour for Undefined Events. . . . . . . . . . . . . . . . . .662
Configuring a Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .663
Creating a Rewrite Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664
Binding Rewrite Policies to a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . .665
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666
Managing Rewrite Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666
Bypassing the Safety Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667
Creating Rewrite Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667
Modifying an Existing Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671
Removing an Existing Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671
Managing Rewrite Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672
Setting the Undefined Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672
Removing an Existing Rewrite Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672
Configuring the Rewrite Feature for Commonly Used Deployment Scenarios . .673
Example 1: Inserting the Client IP Address as an HTTP Header . . . . . . . . . .674
Example 2: Delete Old X-Forwarded-For Headers . . . . . . . . . . . . . . . . . . . . .675
Example 3: Tagging Secure and Unsecure Connections . . . . . . . . . . . . . . . . .676
Example 4: Mask the HTTP Server Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . .677
Example 5: Redirect an External URL to an Internal URL . . . . . . . . . . . . . . .678
Example 6: Migrating Apache Rewrite Module Rules . . . . . . . . . . . . . . . . . .679
Example 7: Marketing Keyword Redirection. . . . . . . . . . . . . . . . . . . . . . . . . .681
Example 8: Redirect Queries to the Queried Server. . . . . . . . . . . . . . . . . . . . .681
Example 9: Home Page Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .682
Chapter 15 HTML Injection
Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685
How HTML Injection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685
Configuring HTML Injection to Insert Data in the HTTP Header . . . . . . . . . . . .686
Enabling the HTML Injection Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .686
Injecting Data into the HTTP Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .687
Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .690
Configuring HTML Injection to Insert Data into the HTTP Body . . . . . . . . . . . .692
Internal Variables used for HTML Injection . . . . . . . . . . . . . . . . . . . . . . . . . .692
Configuring Prebody Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .694
Configuring Postbody Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .695
Specifying Files to be used for Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . .696
Injecting Data into the HTTP Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .697
xii Installation and Configuration Guide - Volume 1
Configuring the HTML Injection Feature for Commonly Used Applications. . . 700
Measuring Application Performance Using a Citrix EdgeSight for NetScaler
Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700
Enabling the HTML Injection Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Specifying Files to be used for Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702
Injecting Data into the HTTP Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703
Chapter 16 Responder
Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
How Responder Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707
Configuring the Responder Feature with a Respondwith Action. . . . . . . . . . . . . 708
Enabling the Responder Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708
Setting the NetScaler Behavior for Undefined Events . . . . . . . . . . . . . . . . . . 709
Configuring Respondwith Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710
Configuring Responder Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711
Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713
Configuring the Responder Feature with a Redirect Action. . . . . . . . . . . . . . . . . 715
Configuring Redirect Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715
Managing Responder Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Bypassing the Safety Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716
Modifying an Existing Responder Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717
Removing an Existing Responder Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
Managing Responder Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
Setting the Undefined Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718
Removing an Existing Responder Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719
Appendix A API Reference
Introduction to the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721
Benefits of API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Hardware and Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722
API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723
The NSConfig Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724
Examples of API Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Example: Setting the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
Example: Querying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726
The Web Service Definition Language (WSDL) . . . . . . . . . . . . . . . . . . . . . . . . . 728
Creating Client Applications Using the NSConfig.wsdl File . . . . . . . . . . . . . 728
Filter WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729
xiii Installation and Configuration Guide - Volume 1
Securing API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731
Appendix B Converting Certificate and Keys
OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Converting from PKCS#12 to .PEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733
Transforming a IIS 4.0 Exported Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735
Appendix C Warning and Safety Messages
Appendix D SystemHealth Counters
Appendix E Introducing the Citrix NetScaler Hardware Platforms
Hardware Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
Citrix NetScaler 7000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747
Citrix NetScaler 9010 and 9010 FIPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749
Citrix NetScaler 10010. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752
Citrix NetScaler 12000 and 12000-10G. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754
Citrix NetScaler MPX 5500. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756
Citrix NetScaler MPX 7500 and MPX 9500. . . . . . . . . . . . . . . . . . . . . . . . . . 758
Citrix NetScaler MPX 9700, MPX 10500, and MPX 12500 . . . . . . . . . . . . . 761
Citrix NetScaler MPX 15000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763
Citrix NetScaler MPX 17000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765
Citrix Platform Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767
Appendix F Clearing the Configuration
Appendix G Understanding the LCD Panel
Special Display Screens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Booting Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Startup Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772
Out-of-Service Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Regular Display Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Configuration Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
Alert Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773
HTTP Statistics Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774
Network Traffic Statistics Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775
CPU Load, Memory, and Connections Screen . . . . . . . . . . . . . . . . . . . . . . . . 775
Port Information Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776
xiv Installation and Configuration Guide - Volume 1
Appendix H Configuring Secure Access
Appendix I FIPS Approved Algorithms and Ciphers
Appendix J Resetting a Locked HSM
Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789
CHAPTER 2
Managing the Citrix NetScaler
This chapter describes how to manage the Citrix NetScaler. The chapter provides
instructions on performing common tasks, including configuring SNMP,
managing system users and groups, and configuring a number of other features.
Topics in this chapter include:
• SNMP
• Users and Groups
• Role-Based Authorization Command Policies
• Configuring Clock Synchronization
• System Logging
• Path Maximum Transmission Unit Discovery
• Autodetected Services
SNMP
The system supports SNMP for a wide range of network management functions.
The following subsections explain which SNMP features are supported, and how
to configure SNMP support on the NetScaler.
HowIt Works
The following figure is a conceptual diagram that shows a network with a
NetScaler that has SNMP enabled and configured. In the diagram, each SNMP
network management application uses SNMP to communicate with the SNMP
agent on the NetScaler. The SNMP agent then searches the MIB to collect the
data requested by the network management application, and provides the
information to the application.
xvi Installation and Configuration Guide - Volume 1
NetScaler Supporting SNMP
To configure SNMP support on the NetScaler, you will use GUI to do the
following:
• Assign access privileges to network management applications and their
users.
• Specify NetScaler information that can be displayed from the NetScaler
SNMP MIB.
• Specify SNMP traps that track various parameters, such as CPU usage and
interfaces status.
The NetScaler supports enterprise-specific MIBs. They are:
• A subset of standard MIB-2 groups. Provides the MIB-2 groups
SYSTEM, IF, ICMP, UDP, SNMP.
• A system enterprise MIB. Provides NetScaler-specific configuration and
statistics.
Chapter 2 Managing the Citrix NetScaler xvii
The SNMP agent on the NetScaler supports SNMP version 1 (SNMPv1), SNMP
version 2 (SNMPv2), and SNMP version 3 (SNMPv3). As a result, the SNMP
agent operates in bilingual mode, allowing it to handle SNMPv2 queries, such as
Get-Bulk. The SNMP agent also sends out 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.
Configuring SNMP V1 and V2
This section describes configuring SNMP V1 and V2. Before you can use SNMP
in the NetScaler, you must configure it to allow the appropriate SNMP managers
access, and provide it with the necessary NetScaler-specific information. The
configuration process consists of these tasks:
• Set the access control list for SNMP managers.
• Set the SNMP community, which defines access privileges (Read
operation).
• Set the NetScaler’s MIB variables: NetScaler name, contact person for that
NetScaler and NetScaler location.
• Set which traps will be enabled and where trap notifications will be
displayed. You can also set the source IP of the SNMP trap to MIP or SNIP.
• Set the threshold level, (the level at which an event is recorded and an alarm
is generated) for all traps. The threshold level defines which set of events
will generate an alarm (notification message) to an SNMP network
management application.
• If you want the SNMP service to respond to SNMP queries on IPs other
than the NSIP, add the additional IPs to the NetScaler configuration.
• Import the appropriate SNMP MIB files.
• If the HP OpenView SNMP manager is installed on your workstation,
copy the NS-MIB-smiv2.mib file from the NetScaler Product CD, /
Utilities/SNMP/HP_OpenView directory, or download it from the
FTP site ftp.netscaler.com.
• If the WhatsUpGold SNMP manager is installed on your workstation,
copy the traps.txt and mib.txt files from the NetScaler Product CD, /
Utilities/SNMP/WhatsUpGold directory, or download it from the
FTP site ftp.netscaler.com.
xviii Installation and Configuration Guide - Volume 1
Note: For information regarding the Username and Password used to
connect to the FTP site, contact the NetScaler product support group.
Adding SNMP Manager
This section covers the procedure for adding a SNMP Manager. You also
configure the management application, which complies with SNMP version 1 or
SNMP version 2, to access to the NetScaler. The netmask parameter can be used
to grant access from entire subnets. Up to a maximum of 100 network
management hosts or networks can be added.
Note: If you do not configure at least one SNMP manager, the NetScaler
accepts and responds to SNMP queries from all IPs on the network. If you
configure one or more SNMP managers, it accepts and responds to only SNMP
queries from those specific IPs.
To add a SNMP Manager, use the parameters listed in the following table:
In the following example, a SNMP manager having IP address 10.102.29.5 and
subnet mask 255.255.255.0 is created.
To add an SNMP manager
1. In the left pane, expand System, click SNMP and click Managers. The
Managers page appears on the right pane.
2. Click Add. The Create Manager dialog box appears.
3. In the IP Address text box, type the IP address. For example, 10.102.29.5.
4. Click Add.
To add an SNMP manager using the NetScaler command line
At the NetScaler command prompt, type:
add snmp manager 10.102.29.5
Parameter Description
IP Address The IP/Network address of the
management station.
Netmask The subnet of management stations.
Chapter 2 Managing the Citrix NetScaler xix
Configuring SNMP Traps and Alarms
This section describes configuring SNMP Traps and Alarms. In addition to
providing information on specific request, the NetScaler can be configured to
display an alarm, or notification message, in a window on a designated computer
or computers whenever a particular type of event occurs. This type of notification
is called an SNMP trap, and it helps administrators monitor the NetScaler and
respond promptly to any issues.
Note: SNMP manager to listen for traps with this community name. The default
community name is “public”.
You can configure the NetScaler to send SNMP traps with source IP other than
NSIP. You can set the source IP of an SNMP trap to either MIP or SNIP.
The NetScaler supports two types of generic SNMP traps and 57 types of
enterprise-specific traps. A maximum of 5 IP addresses can be entered for
enterprise-specific trap destinations. A maximum of five IP addresses can be
entered for generic trap destinations. If more than 10 authentication traps are
generated within 20 seconds, no traps will be generated for the next 60 seconds.
The following table shows the generic traps that the NetScaler supports, with
brief descriptions:
The following table shows the specific SNMP traps that the NetScaler supports,
with brief descriptions:
Generic trap Name Description
authenticationFailure An SNMP management application without access
privileges attempts to access the NetScaler.
coldStart An SNMP entity, acting in an agent role, reinitializes itself
and its configuration may have been altered.
linkUp This trap indicates that the sending protocol entity
recognizes that one of the communication links represented
in the agent's configuration has come up.
linkDown This trap indicates that the sending protocol entity
recognizes a failure in one of the communication links
represented in the agent's configuration.
Specific Trap Name Description
averageCpuUtilization This trap indicates that the average CPU usage in
the multi-processor NetScaler has exceeded the
high threshold.
averageCpuUtilizationNormal This trap indicates that the average CPU usage in
the multi-processor NetScaler has come back to
normal after exceeding the predefined threshold .
xx Installation and Configuration Guide - Volume 1
changeToPrimary This trap indicates that the NetScaler is now
operating in the primary mode.
changeToSecondary This trap indicates that the NetScaler is now
operating as a secondary node.
cpuUtilization This trap indicates that CPU utilization exceeds
the predefined threshold.
cpuUtilizationNormal CPU utilization has returned to normal after
exceeding the predefined threshold and
generating a cpuUtilization trap.
diskUsageHigh This trap indicates that disk usage has gone high.
diskUsageNormal This trap indicates that disk usage has returned to
normal.
entityup The state of the interface, vserver, or physical
service changes to UP.
entitydown The state of the interface, vserver, or physical
service changes to DOWN.
fanSpeedLow This trap indicates that a fan speed has gone
below an alarm threshold.
Note: The fan speed varies from 4000
through 6500 on all platforms. An alarm
threshold of 25% of the minimum is
recommended.
fanSpeedNormal This trap indicates that a fan speed has returned
to normal.
interfaceThroughputLow This trap indicates that interface throughput is
low.
interfaceThroughputNormal This trap indicates that interface throughput has
returned to normal.
maxClients The number of clients for a service reaches the
maximum number allowed for that service.
maxClientsNormal The number of clients for a service falls below
70% of the maximum number allowed for that
service after a maxClients trap has been
generated.
memoryUtilization Memory utilization exceeds the predefined
threshold.
memoryUtilizationNormal Memory utilization returns to normal after a
memoryUtilization trap has been generated.
Specific Trap Name Description
Chapter 2 Managing the Citrix NetScaler xxi
monRespTimeoutAboveThresh This trap is sent when the response timeout for a
monitor probe exceeds the configured threshold.
monRespTimeoutBelowThresh This trap is sent when the response timeout for a
monitor probe comes back to normal, less than
the threshold set.
netscalerLoginFailure This trap is sent to the configured SNMP
managers every time an user's login to the
NetScaler fails.
NetScalerConfigChange A change has been made to your NetScaler
configuration.
Note: This trap is not generated when the
configuration is being restored from the
ns.conf file.
netScalerConfigSave This trap is sent when the configuration on the
NetScaler is saved.
serviceRequestRate The request rate on a service exceeds the
predefined threshold.
serviceRequestRateNormal The request rate on a service returns to normal
after a serviceRequestRate trap is generated.
serviceRxBytesRate This trap is sent when the request bytes/s of a
service exceeds a threshold value.
serviceRxBytesRateNormal This trap is sent when the request bytes/s of a
service returns to normal.
serviceTxBytesRate This trap is sent when the response bytes/s of a
service exceeds a threshold value.
serviceTxBytesRateNormal This trap is sent when the response bytes/s of a
service returns to normal.
serviceSynfloodRate This trap is sent when the number of
unacknowledged syns for a service exceeds a
threshold value.
serviceSynfloodNormal This trap is sent when the number of
unacknowledged syns for a service returns to
normal.
sslCertificateExpiry This trap is sent as an advance notification when
an SSL certificate is due to expire.
svcGrpMemberRequestRate This trap is sent when the request rate on a
service group member exceeds a threshold value.
svcGrpMemberRequestRateNormal This trap is sent when the request rate on a
service group member returns to normal.
Specific Trap Name Description
xxii Installation and Configuration Guide - Volume 1
svcGrpMemberRxBytesRate This trap is sent when the request bytes per
second of a service group exceeds a threshold
value.
svcGrpMemberRxBytesRateNormal This trap is sent when the request bytes per
second of a service group returns to normal.
svcGrpMemberTxBytesRate This trap is sent when the response bytes per
second of a service group exceeds a threshold
value.
svcGrpMemberTxBytesRateNormal This trap is sent when the response bytes per
second of a service group returns to normal.
svcGrpMemberSynfloodRate This trap is sent when the number of
unacknowledged SYN packets for a service
group exceeds a threshold value.
svcGrpMemberSynfloodNormal This trap is sent when the number of
unacknowledged SYN packets for a service
group returns to normal.
svcGrpMemberMaxClients This trap is sent when the number of clients hits
the maxClients value for a service group member.
svcGrpMemberMaxClientsNormal This trap is sent when the number of clients falls
below 70% of maxClients value for a service
group member.
synflood The rate at which unacknowledged SYN packets
are received exceeds the predefined threshold.
synfloodNormal The rate at which unacknowledged SYN packets
are received returns to normal after a synflood
trap has been generated.
temperatureHigh This trap indicates that a temperature has gone
high. The temperature is measured in degree
centigrade (
0
C).
temperatureNormal This trap indicates that a temperature has
returned to normal.
vServerRequestRate The request rate on a vserver exceeds the
predefined threshold. By default, this threshold
is.
vServerRequestRateNormal The request rate on a vserver returns to normal
after a vServerRequestRate trap is generated.
vserverRxBytesRate This trap is sent when the request bytes/s of a
vserver exceeds a threshold value.
vserverRxBytesRateNormal This trap is sent when the request bytes/s of a
vServer returns to normal.
vserverTxBytesRate This trap is sent when the response bytes/s of a
vserver exceeds a threshold value.
Specific Trap Name Description
Chapter 2 Managing the Citrix NetScaler xxiii
For more information on NetScaler health alarms, refer to the appendix on
NetScaler Health Counters.
Adding SNMP Trap
The SNMP traps are asynchronous events generated by the agent to indicate the
state of the NetScaler. The destination to which these traps should be sent by the
NetScaler is configured through the following procedure:
To add a SNMP Trap, use the parameters listed in the following table:
In the following example, a SNMP trap, with trap destination IP address
10.102.29.3 and trap class, specific, is created.
vserverTxBytesRateNormal This trap is sent when the response bytes/s of a
vServer returns to normal.
vserverSynfloodRate This trap is sent when the number of
unacknowledged syns for a vserver exceeds a
threshold value.
vserverSynfloodNormal This trap is sent when the number of
unacknowledged syns for a vserver returns to
normal.
voltageLow This trap indicates that a voltage has gone low.
voltageNormal This trap indicates that a voltage has returned to
normal.
voltageHigh This trap indicates that a voltage has gone high.
Note: The three traps voltageLow,
voltageNormal, and voltageHigh are based
on v33main and v33stby (mV). The normal
value ranges from 2970mV through
3630mV.
Parameter Description
Trap Class The Trap type. The Generic type causes
the standard SNMP traps supported by
the NetScaler to be sent to the
destination, while the Specific trap type
sets the destination for specific traps.
Possible values: generic, specific
Trap Destination The IP address of the trap destination.
Specific Trap Name Description
xxiv Installation and Configuration Guide - Volume 1
To add an SNMP Trap
1. In the left pane, expand System, click SNMP and click Traps. The Traps
page appears on the right pane.
2. Click Add. The Add Trap dialog box appears.
3. In the IP Address text box, type the IP address. For example, 10.102.29.3.
4. Click Add.
To add an SNMP Trap using the NetScaler command line
At the NetScaler command prompt, type:
add SNMP trap specific 10.102.29.3
Modifying SNMP Traps
This section covers procedure for modifying SNMP traps. This section covers the
following topics:
• Setting the Trap Destination Port
• Setting the SNMP Version of the Trap PDU to be Sent
• Setting the Source IP of the SNMP Traps
• Setting the Community String
• Setting the Severity of the Trap
Setting the Trap Destination Port
This section covers procedure for setting the destination port of the trap. The trap
destination port is the one on which the SNMP manager receives traps. If this is
not configured correctly the traps will not reach the SNMP manager.
To set the destination port, use the parameters listed in the following table:
In the following example, the SNMP destination port is set to 163.
The following table summarizes the parameters values:
Parameter Description
Destination Port The destination port of the SNMP
trap. Default value: 162
Minimum value: 1
Parameter Description
Destination Port The destination port of the SNMP trap.
Default value: 162 Minimum value: 1
Chapter 2 Managing the Citrix NetScaler xxv
To set the trap destination port
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page, select the trap for which you want to set the trap
destination port.
3. In the Destination Port, type a destination port, for example, 163.
4. Click OK.
To set the trap destination port using the NetScaler command line
At the NetScaler command prompt, type:
set snmp trap specific 10.102.29.3 destPort 163
Setting the SNMP Version of the Trap PDU to be Sent
This section covers procedure for setting the SNMP Version. The SNMP version
is sent with the trap PDU.
To set SNMP version, use the parameters listed in the following table:
In the following example, the SNMP version, V1, option is selected:
To set SNMP version of the trap
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page select the trap for which you want to set the
SNMP version to be sent with the trap.
3. In the Version, select a SNMP Version, for example, V1.
4. Click OK.
Version The SNMP version of the trap PDU to
be sent.
Source IP The source IP of the SNMP traps.
Community Name SNMP trap community string Default
value: public.
Parameter Description
Version The SNMP version of the trap PDU to
be sent.
Parameter Description
xxvi Installation and Configuration Guide - Volume 1
Setting the Source IP of the SNMP Traps
You can configure the NetScaler to send SNMP traps with source IP other than
NSIP. You can set the source IP of an SNMP trap to either MIP or SNIP.
To set the source IP of the SNMP traps, use the parameters listed in the following
table:
In the following example, an IP address, 10.102.29.54 is set for the source IP of
SNMP trap:
To set the source IP of the SNMP trap
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page select the trap for which you want to set the
community string.
3. In the source IP text box, type an IP address. For example, 10.102.29.54.
4. Click OK.
Setting the Community String
This section covers procedure for setting the community string. The community
string is sent with the trap PDU.
To set community string of the SNMP traps, use the parameters listed in the
following table:
To set the community string
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page select the trap for which you want to set the
community string.
3. In the Community Name text box, type the name of the SNMP string
which you want to include in the SNMP traps. For example, com1.
4. Click OK.
Parameter Description
Source IP The source IP of the SNMP traps.
Parameter Description
Community Name The SNMP trap community string. The
default value is public.
Chapter 2 Managing the Citrix NetScaler xxvii
Setting the Severity of the SNMP Trap
You can configure a NetScaler to send specific traps based on severity, to the
SNMP manager. There are 5 severity types: Critical, Major, Minor, Warning,
Informational. These severity types are only tags which are for your ease. The
trap is sent only when the severity of the alarm matches the severity configured in
traps.
To set minimum severity of the SNMP traps, use the parameters listed in the
following table:
To set the severity of the trap
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page select the trap for which you want to set the
minimum severity.
3. Click Open. The Modify SNMP Trap dialog box appears.
4. In Severity, select a severity option. For example, Major.
5. Click Ok.
Removing a SNMP Trap
This section covers procedure for removing SNMP traps. When a trap is removed
the trap messages are no longer send to this trap destination.
To remove a SNMP trap
1. In the left pane, expand System, click SNMP, and then click Traps. The
SNMP Traps page appears on the right pane.
2. In the SNMP Traps page, select the trap which you want to remove.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
Configuring SNMP Alarm
This section covers procedure for configuring SNMP Alarms. This section covers
the following topic:
Parameter Description
Severity The minimum severity of the alarms to
be sent to this trap destination. By
default all traps will be sent to this trap
destination.
xxviii Installation and Configuration Guide - Volume 1
• Setting the Severity of the SNMP Alarm
• Disabling a SNMP Alarm
• Enabling a SNMP Alarm
Setting the Severity of the SNMP Alarm
This section describes procedure for setting the severity of the SNMP alarms.
There are 5 severity types: Critical, Major, Minor, Warning, Informational. These
severity types are only tags which are for your ease. The trap is sent only when
the severity of the alarm matches the severity configured in traps.
To set minimum severity of the SNMP traps, use the parameters listed in the
following table:
In the following example, an IP address, 10.102.29.54 of type subnet IP address
and subnet mask 255.255.255.0 is created.
To set the severity of the alarm
1. In the left pane, expand System, click SNMP, and click Alarms. The
SNMP Alarms page appears on the right pane.
2. Click Open. The Configure SNMP Alarm dialog box appears.
3. In Severity, select a severity option. For example, Major.
4. Click Ok.
Disabling an SNMP Alarm
This section covers disabling of SNMP alarms. When you disable a SNMP alarm,
the NetScaler will not generate corresponding trap messages when some events
occur.
For example when you disable Login-Failure SNMP alarm, the NetScaler will not
generate a trap message when a login failure happens in the NetScaler.
To disable an SNMP alarm
1. In the left pane, expand System, click SNMP, and click Alarms. The
Alarms page appears on the right pane.
2. In the Alarms page, select a SNMP alarm which you want to disable. For
example, Login-Failure.
Parameter Description
Severity The severity level of this alarm.
Possible values: Critical, Major, Minor,
Warning, Informational.
Chapter 2 Managing the Citrix NetScaler xxix
3. Click Disable.
Enabling a SNMP Alarm
This section covers procedure for enabling SNMP alarms. When you enable a
SNMP alarm, the NetScaler will generate corresponding trap messages when
some events occur. Some NetScaler alarms are enabled by default.
To enable alarms
1. In the left pane, expand System, click SNMP, and click Alarms. The
Alarms page appears on the right pane.
2. In the Alarms page, select a disabled SNMP alarm which you want to
enable. For example, Login-Failure.
3. Click Enable.
Removing SNMP Managers
This section covers procedure for removing of SNMP manager. When you
remove a SNMP manager from the NetScaler the manager can no longer query
the NetScaler.
Note: If there is no SNMP manager configured in the NetScaler, network
management applications from any host computer can access the NetScaler.
In the following example, a SNMP manager having IP address 10.102.29.5 and
subnet mask 255.255.255.0 is removed.
To remove a SNMP manager
1. In the left pane, expand System, click SNMP, and then click Managers.
The SNMP Managers page appears on the right pane.
2. In the SNMP Managers page, select the manager which you want to
remove.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
Adding a SNMP Community
This section covers procedure for adding a SNMP community string. You add
SNMP community string to grant access to an SNMP network management
application to manage the NetScaler. The community also defines the specific
management tasks that you can perform. Use the following procedure to set the
management privileges for the network management application.
xxx Installation and Configuration Guide - Volume 1
To add a SNMP community, use the parameters listed in the following table:
In the following example, a community, Com_All, is added with access
permission ALL.
To add a community string
1. In the left pane, expand System, click SNMP, and then click Community.
The SNMP Community page appears in the right pane.
2. Click Add. The Add SNMP Community dialog appears.
3. In the Community String text box, type a name for the community to be
added. For example, Com_All.
4. In Permission, select ALL option.
5. Click Create.
Removing a SNMP Community
This section covers procedure for removing community string. when you remove
a community string, the SNMP managers are not able to use the community to
manage the NetScaler.
In the following example, a community, Com_All, is removed.
To remove a community string
1. In the left pane, expand System, click SNMP, and click Community. The
SNMP Community page appears on the right pane.
2. In the SNMP Community page, select the community which you want to
remove. For example, Com_All.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
Configuring SNMP V3
This section describes configuring SNMP V3. This section covers the following
topics:
• How It Works
Parameter Description
Community Name The SNMP community string.
Permissions The access privileges. Possible
values: GET, GET NEXT, GET
BULK, ALL.
Chapter 2 Managing the Citrix NetScaler xxxi
• Configuring SNMP V3
HowIt Works
Simple Network Management Protocol Version 3 (SNMPv3) is based on the
basic structure and architecture of SNMPv1 and SNMPv2. However, SNMPv3
enhances the basic architecture to incorporate administration and security
capabilities such as authentication, access control, data integrity check, data
origin verification, message timeliness check, and data confidentiality.
Salient Features
SNMPv3 provides security features such as message-level security and access
control. To implement these features, SNMPv3 introduces the following:
• User-based Security Model (USM)
• View-based Access Control Model (VACM)
User-based Security Model
User-based Security Model (USM) provides message-level security. It enables
you to configure users and security parameters at the agent and the manager to
ensure:
• Data integrity: To protect messages from being modified during
transmission through the network.
• Data origin verification: To authenticate the user who sent the message
requests.
• Message timeliness: To protect against message delays or replays.
• Data confidentiality: To protect the content of messages from being
disclosed to unauthorized entities or individuals.
View-based Access Control Model
View-based Access Control Model (VACM) allows you to configure access rights
to a specific subtree of the MIB based on various parameters such as security
level, security model, user name, and view type. It enables you to configure
agents to provide different levels of access to the MIB to different managers.
SNMPv3 Security Entities
The Citrix NetScaler supports the following entities that enable you to implement
the security features of SNMPv3:
• SNMP Engine
• SNMP Views
xxxii Installation and Configuration Guide - Volume 1
• SNMP Groups
• SNMP Users
SNMP Engine
SNMP engines are service providers that reside in the SNMP agent. They provide
services such as sending or receiving and authenticating messages. SNMP
engines are uniquely identified using engine IDs.
SNMP Views
SNMP views restrict user access to specific portions of the MIB. SNMP views
are used to implement access control.
SNMP Groups
SNMP groups are logical aggregations of SNMP users. They are used to
implement access control and to define the security levels. You can configure an
SNMP group to set access rights for users assigned to that group, thereby,
restricting the users to specific views.
SNMP Users
SNMP users are the SNMP managers that are configured at the agent to access
the MIB. Each SNMP user is assigned to an SNMP group.
These entities function together to implement the SNMPv3 security features.
Views are created to allow access to subtrees of the MIB. Then, groups are
created with the required security level and access to the defined views. Finally,
users are created and assigned to the groups. The configuration of these entities is
explained in the next section.
Configuring SNMP V3
To implement message authentication and access control, you need to:
• Set the Engine ID
• Configure Views
• Configure Groups
• Configure Users
The following sections describe the tasks in detail:
Note: For information on the parameters used in these tasks, refer to the
Command Reference Guide or the MAN pages.
Chapter 2 Managing the Citrix NetScaler xxxiii
Setting the Engine ID
As mentioned in the previous section, the SNMP engine ID uniquely identifies an
SNMP engine. The NetScaler has an unique engineID based on the MAC address
of one of its interfaces. It is not necessary to override this engineID. However, if
you want to change this engine ID, then you can reset it.
To set the Engine ID, use the parameters listed in the following table:
To set the engine ID
1. In the left pane, expand System, click SNMP, and click Users. The SNMP
Users page appears on the right pane.
2. Click Configure Engine ID. The Configure Engine ID dialog box
appears.
3. In the Engine ID text box, type an engine ID. For example,
8000173f0300c095f80c68.
4. Click OK.
Adding SNMP View
This section covers removing of SNMP view. SNMP views are used to
implement access control.
To add a SNMP View, use the parameters listed in the following table:
To add a SNMP view
1. In the left pane, expand System, click SNMP, and then click View. The
SNMP View page appears on the right pane.
2. Click Add. The Add SNMP View dialog box appears.
3. In the Name text box, type a name for the SNMP view you want to add. For
example, View1.
4. In the Subtree text box, type the subtree of the MIB.
5. Click Create.
Parameter Description
EngineID The engine ID of the SNMP agent.
Parameter0 Description
Name The name of the SNMP view.
Subtree The subtree of the MIB.
xxxiv Installation and Configuration Guide - Volume 1
Adding SNMP Group
You need to configure an SNMP group to set access rights for users assigned to
that group.
To add a SNMP Group, use the parameters listed in the following table:
To add a SNMP group
1. In the left pane, expand System, click SNMP, and then click Group. The
SNMP Groups page appears on the right pane.
2. Click Add. The Add SNMP Group dialog box appears.
3. In the Name text box, type a name for the SNMP group you want to add.
For example, View1.
4. In Read View Name, select a configured SNMP view, which you want to
associated to the Group.
5. Click Create and click Close.
Adding SNMP User
You need to configure users at the agent, and assign each user to a group.
To add a SNMP user, use the parameters listed in the following table:
To add a SNMP user
1. In the left pane, expand System, click SNMP, and then click Users. The
SNMP Users page appears on the right pane.
2. Click Add. The Add SNMP User dialog box appears.
3. In the Name text box, type a name for the SNMP user you want to add. For
example, user1.
4. In Group Name, select a configured SNMP group, which you want the
user to be part of.
Parameter Description
Name The name of the SNMP view.
Read View The SNMP view to be associated with
this group.
Parameter Description
Name The name of the SNMP user.
Read View The SNMP view to be associated with
this user.
Chapter 2 Managing the Citrix NetScaler xxxv
5. Click Create and click Close.
Note: The view, group, and user configuration are synchronized and propagated
to the secondary node in an HA pair. However, the engineID is neither propagated
nor synchronized as it is unique to each NetScaler.
Users and Groups
The NetScaler allows you to create users and groups, for managing access and
allowing individual user’s access to match their duties and needs. This section
explains how to create and manage these users and groups.
Howit Works
The NetScaler allows you to create users and groups, for managing access and
allowing individual users access to match their duties and needs.
To manage the day-to-day tasks to your NetScaler, you should create NetScaler
user accounts and groups, and associate each user with the appropriate groups.
An user account is a logon / password combination used by a specific person or
process to log on to the NetScaler.
A group is a set of user accounts to which a specific set of command policies
applies.
A command policy is a rule that allows or prohibits an user or group to access or
modify a specific part of the NetScaler configuration.
Before you configure users and groups, you must understand the role of the
system global scope. Within the NetScaler operating system, a scope is a category
of user accounts and groups that meet certain criteria. System global is the set of
all user accounts and groups on the NetScaler except for the nsroot user account.
System global policies and parameters apply to all user accounts and groups
except for the nsroot user account.
Before you can create and apply command policies, you must create the user
accounts and groups to which those policies can then be applied.
All NetScalers are configured with a default user account, the nsroot user
account. The following are important characteristics of this user account:
• The default administrator user account (nsroot) is immutable, and always
has full NetScaler privileges.
xxxvi Installation and Configuration Guide - Volume 1
• The nsroot user account is not subject to any policy which is configured on
the NetScaler. This means that command and authentication polices cannot
be used to modify the nsroot user's access to the NetScaler.
• The nsroot user account cannot be bound in to group memberships.
• The nsroot user account's default password is nsroot. It is strongly advised
that you change your NetScaler’s nsroot password immediately on
powering it up for the first time.
You use the nsroot user account during initial installation and configuration of the
NetScaler, and for certain types of troubleshooting. You should not log on as
nsroot for other purposes. Instead, you should create individual user accounts and
groups for administrators, and create command policies that define access and
privileges for each user account.
Configuring Users and Groups
This section explains how to create and manage users and groups, and covers the
following procedure:
• Adding an User Account
• Adding a NetScaler Group
• Binding Users to a Group
• Verifying the Configuration
Adding an User Account
This section covers procedure for adding an user account. An user account is a
logon / password combination used by a specific person or process to log on to
the NetScaler.
To add an user account, use the parameters listed in the following table:
In the following example, a NetScaler user, johnd, is created.
To add an user account
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
Parameter Description
User Name The name you want to assign to user
account.
Password The user password you want to assign
to this user account.
Chapter 2 Managing the Citrix NetScaler xxxvii
2. Click Add. The Create User dialog box appears.
3. In the User Name text box, type a name for the user you want to create, for
example, johnd.
4. In the Password text box, type a password you want to assign to the user
account.
5. In the Confirm Password text box, type the password again that you have
typed in the Password text box.
6. Click Create.
Adding Groups
This section covers procedure for adding groups. A group is a set of user accounts
to which a specific set of command policies applies
To add a group, use the parameters listed in the following table:
In the following example, a NetScaler group, Managers, is created.
To add a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. Click Add. The Create Group dialog box appears.
3. In the Group Name text box, type a name for the group you want to create.
For example, Managers.
4. Click Create.
Binding User to a Group
You bind a NetScaler user account to a NetScaler group to which you want to
associate that user account by using the following procedure. You can bind each
user account to more than one group. Binding your user accounts to multiple
groups may allow more flexibility when applying command policies, which are
discussed in section custom based policies.
To bind users to a group, use the parameters listed in the following table:
Parameter Description
Group Name The name for the NetScaler group.
Parameter Description
User Name The name for the NetScaler user to be
bound to the group.
xxxviii Installation and Configuration Guide - Volume 1
In the following example, the user account, johnd, is bound to the group,
Managers.
To bind an user to a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. Click Open. The Configure Group dialog box appears.
3. Under the Member of section, select the user you want to bind to the
group, from the Available Users table and click Add.
4. The bound users are shown in Configured Users.
Once the NetScaler users and groups are created, you can view details about
them.
Verifying the Configuration
This section covers procedure for viewing the details of the created user and
groups. This section covers the following topics:
• Viewing an User
• Viewing a Group
Viewing an user
This section covers procedure for viewing NetScaler users. In the following
example, you will view the user, johnd.
To view an user
1. In the left pane, expand System and click Users.
2. The System Users page appears on the right pane with all the configured
users.
Viewing a Group
This section covers procedure for viewing NetScaler groups. In the following
example, you will view the user, Managers.
To view a group
1. In the left pane, expand System and click Group.
2. The System Groups page appears on the right pane with the configured
groups.
Chapter 2 Managing the Citrix NetScaler xxxix
Managing Users and Groups
This section covers procedure for managing users and groups.
Changing User Password
This section covers the procedure for changing the password for user accounts
configured in the NetScaler.
To change the NetScaler user password, use the parameters listed in the following
table:
In the following example, the password of user account, johnd, is changed.
To change the user password
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
2. Select the user account for which you want to change the password. For
example, johnd.
3. Click Open. In the Password text box, type a password you want to assign
to the user account.
4. In the Confirm Password text box, type the password again which you
have provided in the Password text box.
5. Click OK.
Note: When you enter the password when adding an user account, it is
displayed in clear text. However, NetScaler user passwords are encrypted on the
NetScaler.
Resetting the Default Administrator (nsroot) Password
If you have lost the nsroot password, you can recover it as described in this
section.
The nsroot account provides complete access to all features of the NetScaler.
Therefore, to preserve security, the nsroot account should be used only when
necessary, and only individuals whose duties require full access should know the
nsroot account password. Also for security, it is advisable to change the nsroot
password frequently. If you lose the password, you can reset it as described here.
Parameter Description
Password The password you assign for the user
account.
xl Installation and Configuration Guide - Volume 1
To reset the nsroot password, you must boot the NetScaler into single user mode,
mount the file systems in read/write mode, and remove the set NetScaler user
nsroot entry from the ns.conf file. This process does not actually recover your
nsroot password, but it does allow you to reset it to the default setting, nsroot.
You can then choose a new password.
To reset the nsroot password
1. Connect a computer to the NetScaler serial port, and log on.
Note: You cannot log on via ssh to perform this procedure; you must connect
directly to the NetScaler.
As the operating system starts, it displays the following message:
Hit [Enter] to boot immediately, or any other key for command prompt.
Booting [kernel] in #seconds.
2. Press the space bar.
The following message is displayed:
Type ‘?’ for a list of commands, ‘help’ for more detailed help.
ok
3. Type boot -s, and press the Enter key to start the system in single user
mode.
After the system boots, it displays the following message:
Enter full pathname of shell or RETURN for /bin/sh:
4. Press the <Enter>key to display the #prompt, and type the following
command at the prompt to mount the file systems:
mount /dev/ad0s1a /flash
5. Using a text editor of your choice, edit the /flash/nsconfig/ns.conf file and
remove the set system user nsroot entry.
6. Save the file and exit the text editor.
7. Type reboot and press the Enter key to reboot the NetScaler.
When the NetScaler completes rebooting, it prompts for username and
password.
8. Log on as nsroot, with the password nsroot.
Once logged in to the NetScaler, you will be required to enter a new nsroot
user password.
9. Follow the prompts to change the password.
Chapter 2 Managing the Citrix NetScaler xli
10. Exit the config ns menu with option.
Removing User Accounts
This section covers procedure for removing the user accounts from the NetScaler.
If your user account has the rights to remove another user, then you can remove
another user account in the NetScaler. The nsroot account cannot be removed by
any user and also the nsroot user can remove any other user account.
In the following example, the group, Managers, is removed from the NetScaler.
To remove an user account
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
2. In the System Users page, select the user account which you want to
remove. For example, johnd.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
Removing Groups
This section covers procedure for removing groups from the NetScaler. When
you remove a group, all the users and command policies which are currently
bound to the group, are unbound.
In the following example, the group, Managers, is removed from the NetScaler.
To remove a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. In the System Groups page, select the group which you want to remove.
For example, Managers.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
Role-Based Authorization Command Policies
This section covers the functions of role-based authorization command policies
(RBAC) and how to create and manage them.
xlii Installation and Configuration Guide - Volume 1
HowIt Works
Command policies are rules that control what individual users may access and do
on the NetScaler. The NetScaler users and groups functions allow you to define
who has access to the NetScaler. Command policies allow you to define what
parts of the NetScaler configuration an user or group is permitted to access and
modify. In other words, command policies regulate which commands, command
groups, vservers, and other elements NetScaler users and groups are permitted to
use.
Configuring RBAC
This section covers configuring role based command policies (RBAC).
Here are the key points to keep in mind when defining and applying command
policies.
• No global command policies may be created on the NetScaler. Command
policies must be bound directly to NetScaler users and groups.
• Users or groups with no associated command policies are subject to the
default DENY -ALL command policy, and will therefore be unable to
execute any commands until the proper command policies are bound to
them.
• All users inherit the policies of the groups to which they belong.
• When you bind it to an user account or group, you must assign priorities to
a command policy. This allows the NetScaler to determine which policy has
priority when two or more conflicting policies apply to the same user
accounts or groups.
• The following commands are available to any user by default and are
unaffected by any command policies you specify:
help cli, show cli attribute, clear cli prompt, alias, unalias, batch, source,
help, history, man, quit, exit, whoami, config, set cli mode, unset cli mode,
show cli mode, set cli prompt, and show cli prompt.
Using Built-in Command Policies
Four default command policies are available on the NetScaler. The following lists
these policies:
Policy Name Description
read-only Allows read-only access to all show commands except for the NetScaler
command group show commands and show runningconfig and
show ns.conf commands.
Chapter 2 Managing the Citrix NetScaler xliii
When creating command policies, you must bind them to the user accounts and
groups to which they apply.
• If the built-in command policies provide the levels of access control you
need, proceed to Section : Binding Command Policies to Users and Groups.
• If you need different levels of control than are provided by the built-in
command policies, proceed to Section , “Creating Custom Based Command
Policies.”
Creating CustomBased Command Policies
This section covers procedure for custom based policies.
Note: Regular expression support is offered for those users with the resources
to maintain more customized expressions and those deployments that require the
flexibility that regular expressions offer. For most users, the built-in command
policies discussed in Section , “Binding Built-in Command Policies to Users and
Groups,” should be sufficient. Users who need additional levels of control, but
are unfamiliar with regular expressions, may want to use only simple expressions,
such as those in the examples provided in this section, to maintain policy
readability.
When you use a regular expression to create a command policy, keep the
following in mind.
• When you use regular expressions to define commands that will be affected
by a command policy, you must enclose the commands in double quotes.
For example, if you want to create a command policy named allowShow
that includes all commands that begin with show, you should type the
following:
“^show .*$”
If you want to create a command policy that includes all commands that
being with rm, you should type the following:
operator Allows read-only access as above, and in addition allows access to
enable and disable commands on services and servers. This policy also
allows access to set services and servers as ‘accessdown.’
network Permits total NetScaler access, excluding NetScaler commands, the
shell command, and the show ns.conf and sh runningconfig
commands.
superuser Grants full NetScaler privileges, giving exactly the same privileges as
the nsroot user.
Policy Name Description
xliv Installation and Configuration Guide - Volume 1
DENY “^rm .*$”
• Regular expressions used in command policies are case insensitive.
The following table gives examples of regular expressions:
The following shows the command specifications for each of the built-in
command policies:
The following examples show how you can use the command specification
regular expressions .The default_deny_override command policy is
especially useful, since it allows you to override the default NetScaler-level
DENY rule and grant access only to the specific user accounts and groups that
need it.
Command Specification Matches these Commands
“^r m\ s+. *$” All remove actions, because all remove actions begin
with the rm string, followed by a space and
additional parameters and flags.
“^show\ s+. *$” All show commands, because all show actions begin
with the show string, followed by a space and
additional parameters and flags.
“^shel l $” The shell command alone, but not combined with
any other parameters or flags.
“^add\ s+vser ver \ s+. *$” All create a vserver actions, which consist of the add
vserver command, followed by a space and
additional parameters and flags.
“^add\ s+( l b\ s+vser ver ) \ s+
. *”
All create an lb vserver actions, which consist of the
add lb vserver command, followed by a space and
additional parameters and flags.
“^set \ s+l b\ s+. *$” All commands that configure load balancing settings
at the command group level.
Policy Name Command Specification Regular Expression
read-only ( ^man. *) | ( ^show\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns
r unni ngConf i g) . *) | ( ^st at . *)
operator ( ^man. *) | ( ^show\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns
r unni ngConf i g) . *) | ( ^st at . *) | ( ^set . *-
accessdown. *) | ( ^( enabl e| di sabl e) ( ser ver | ser vi ce) . *)
network ^( ?! shel l ) \ S+\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns
r unni ngConf i g) . *
superuser . *
Chapter 2 Managing the Citrix NetScaler xlv
Binding Command Policies to Users and Groups
Once you have defined your command policies, you must bind them to the
appropriate user accounts and groups.
When you create each binding, you must also set a priority on the policy so that
the system can determine which command policy to follow when two or more
applicable command policies are in conflict.
The order in which command policies are evaluated:
• Command policies bound directly to user and the corresponding groups are
evaluated based on the priority number. A command policy with a lower
priority number is evaluated before one with a higher priority number.
Therefore, any privileges the lower-numbered command policy explicitly
grants or denies are not overridden by a higher-numbered command policy
• When two command policies one bound to an user account and other bound
to a group have the same priority number then the command policy bound
directly to the user account is evaluated first.
Binding Command Policies to an user
To bind users to a group, use the parameters listed in the following table:
In the following example, a command policy is bound to the user, johnd.
To bind command policies to an user
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
2. Select an user for which you want to bind command policies. For example,
johnd.
3. Click Open. The Configure Group dialog box appears. The Member of
section shows a list of command policies that can be bind to the group.
4. In the Active column, select the check box against the policy that you want
to bind, change the priority in the Priority list box, for example, 1, and
click OK.
Parameter Description
User Name The user account
Command Policies The name of the command policy you
want to bind to the user account.
xlvi Installation and Configuration Guide - Volume 1
Binding Command Policies to a Group
To bind users to a group, use the parameters listed in the following table:
In the following example, a command policy is bound to the group, Managers.
To bind command policies to a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. Select a group for which you want to bind command policies. For example,
Managers.
3. Click Open. The Configure Group dialog box appears. The Member of
section shows a list of command policies that can be bind to the group.
4. In the Active column, select the check box against the policy that you want
to bind, change the priority in the Priority list box, for example, 1, and
click OK.
User Accounts and Command Policies
The following example will show you how you create a complete set of user
accounts, groups, and command policies, and then bind each policy with the
appropriate groups and users. The company, Example Manufacturing, Inc., has
three users who will access the NetScaler:
• John Danilov. The IT manager. J ohn needs to see all parts of the NetScaler
configuration, but does not need to modify anything.
• Maria Ramirez. The lead IT administrator. Maria needs to be able to see
and modify all parts of the NetScaler configuration except for NetScaler
commands (which local policy dictates must be performed while logged on
as nsroot).
• Michael Baldrock. The IT administrator in charge of load balancing.
Michael needs to be able to see all parts of the NetScaler configuration, but
needs to modify only the load balancing functions.
The following table shows the breakdown of network information, user account
names, group names, and command policies for the example company:
Parameter Description
User Name The user account
Command Policies The name of the command policy you
want to bind to the user account.
Chapter 2 Managing the Citrix NetScaler xlvii
The following description walks you through the process of creating a complete
set of user accounts, groups, and command policies on Example Manufacturing,
Inc., NetScaler, ns01.example.net.
The discussion includes procedures for binding the appropriate user accounts and
groups to one another, and binding appropriate command policies to the user
accounts and groups.
This procedure illustrates how you can use prioritization to grant precise access
and privileges to each user in the IT department.
The example assumes that initial installation and configuration have already been
performed on the NetScaler.
To create johnd, mariar, and michaelb user accounts
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
2. Click Add. The Create User dialog box appears.
3. In the User Name text box, type johnd.
4. In the Password text box, type a password you want to assign to the user
account.
5. In the Confirm Password text box, type the password again that you have
typed in the Password text box.
6. Click Create.
7. Repeat step2 -6 to create user accounts and passwords for Maria Ramirez
and Michael Baldrock.
Note: You would, of course, assign different passwords for these users to
protect the security of the NetScaler. For optimal security, passwords should
include a mix of upper- and lower-case letters, numbers, and symbols.
Field Value Note
NetScaler hostname ns01.example.net
User accounts johnd
mariar
michaelb
John Danilov, IT manager
Maria Ramirez, IT administrator
Michael Baldrock, IT administrator
Groups Managers
SysOps
All managers
All IT administrators
Command Policies read_all
modify_lb
modify_all
Allow complete read-only access
Allow modify access to load balancing
Allow nearly complete modify access
xlviii Installation and Configuration Guide - Volume 1
To add groups
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. Click Add. The Create Group dialog box appears.
3. In the Group Name text box, type Managers.
4. Click Create.
5. Repeat step1-4 to create a group named SysOps.
To bind users to a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
2. Select the group Managers.
3. Click Open. The Configure Group dialog box appears.
4. Under the Member of section, select the user johnd from the Available
Users table and click Add to bind to the Managers.
5. The bound user johnd is shown in Configured Users.
6. Repeat step1-5 to bind users mariar and michaelb to the group SysOps.
To add command policies
1. In the left pane, expand System and click Command Policies. The
Command Policies page appears on the right pane.
2. Click Add. The Create Command Policies dialog box appears.
3. In the Policies Name text box, type read_all.
4. In the Action list, select Allow.
5. In the Command Spec, enter “(^show\s+(?!system)(?!ns ns.conf)(?!ns
runningConfig).*)|(^stat.*)”, with the help of policy components.
6. Click Create.
7. Repeat step 1-5, to create command policy named modify_lb with action as
Allow and having command spec “^set\s+lb\s+.*$”
8. Repeat step 1-5, to create command policy named modify_all with action
as Allow and having command spec “^\S+\s+(?!system).*”
To bind command policy to a group
1. In the left pane, expand System and click Groups. The System Groups
page appears on the right pane.
Chapter 2 Managing the Citrix NetScaler xlix
2. Select the group Managers.
3. Click Open. The Configure Group dialog box appears. The Member of
section shows a list of command policies that can be bind to the group.
4. In the Active column, select the check box against the read_all policy,
change the priority in the Priority list box to1, and click OK.
Note: Assigning a priority of 1 to this binding ensures that any other command
policy assigned to this group or to an individual account will take priority. This
allows you to use this policy to grant default NetScaler-wide read access to any
part of the Application Switch configuration.
5. Repeat step 1-4, to bind the read_all command policy to the SysOps group,
also assigning it a priority of 1.
To bind command policies to an user
1. In the left pane, expand System and click Users. The System Users page
appears on the right pane.
2. Select the user account michaelb.
3. Click Open. The Configure User dialog box appears. The Member of
section shows a list of command policies that can be bind to the user.
4. In the Active column, select the check box against the modify_lb policy,
change the priority in the Priority list box to5, and click OK.
Note: Assigning a priority of 5 to this binding ensures that it will take priority
over any “background” command policy with a priority of 1, but it will not take
priority over a command policy with an assigned priority greater than 5.
The configuration you've just created results in the following:
• J ohn Danilov, the IT manager, has read-only access to the entire NetScaler,
but cannot make modifications.
• Maria Ramirez, the IT lead, has near-complete access to all areas of the
NetScaler configuration, having to log on only to perform NetScaler-level
commands.
• Michael Baldrock, the IT administrator responsible for load balancing, has
read-only access to the NetScaler configuration, and can modify the
configuration options for load balancing.
l Installation and Configuration Guide - Volume 1
As mentioned earlier, the set of command policies that applies to a specific user is
a combination of command policies applied directly to the user's account, plus
command policies applied to the group(s) of which the user is a member.
Each time an user enters a command, the operating system searches the command
policies for that user until it finds a policy with an explicit ALLOW or DENY
action that matches the command. When it finds a match, the operating system
stops its command policy search and allows or denies access to the command.
If the operating system finds no matching command policy, it denies the user
access to the command, in accordance with the NetScaler’s default deny policy.
Note: When placing an user into multiple groups, take care not to cause
unintended user command restrictions or privileges. To avoid these conflicts,
when organizing your users in groups, it's good to bear in mind the NetScaler's
command policy search procedure and policy ordering rules.
Configuring Clock Synchronization
You can configure your NetScaler to synchronize its local clock with a Network
Time Protocol (NTP) server. This will ensure that its clock has the same date and
time settings as the other servers on your network.
To enable clock synchronization on your NetScaler
1. Log on to the NetScaler CLI.
2. Switch to the shell prompt.
3. Copy the ntp.conf file from the /etc directory to the /nsconfig
directory. If it already exists in the /nsconfig directory, ensure that you
remove the following entries from the ntp.conf file:
restrict localhost
restrict 127.0.0.2
These entries are required only if you want to run the device as a time
server. However, this feature is not supported on the NetScaler.
4. Edit /nsconfig/ntp.conf, and add the IP address for the desired NTP
server under the file’s server and restrict entries.
5. Create a file and name it rc.netscaler in the /nsconfig directory, if
the file does not already exist in the directory.
6. Edit /nsconfig/rc.netscaler, and add the following entry.
Chapter 2 Managing the Citrix NetScaler li
/usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/
ntpd.log &
This entry starts the ntpd service, checks the ntp.conf file, and logs
messages in the /var/log directory.
Note: When the time difference between the NetScaler and the time
server is more than 1000 sec, the ntpd exits with a message to the
NetScaler log. To avoid this, you need to start ntpd with the -g option,
which will forcibly sync 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 dont want to forcibly sync the time due to the large difference, you
can set the date manually and then start ntpd again.
You can check the time difference between the NetScaler and the time
server by executing the following command in the shell:
ntpdate -q <IP address or domain name of the NTP
server>
7. Reboot the NetScaler to enable clock synchronization.
Note: If you want to restart the NetScaler at a later time but start the time
synchronization process, run the following command from the shell
prompt:
/usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/
ntpd.log &
This command starts the time synchronization process. However, if you
want the process to start every time the NetScaler is restarted, ensure that
you have added it to the rc.netscaler file, as described in step 6.
If you do not have a local NTP server, you can find a list of public, open access,
NTP servers at the official NTP site, http://www.ntp.org, under Public Time
Servers List. Before configuring your NetScaler to use a public NTP server, be
sure to read the Rules of Engagement page, (link included on all Public Time
Servers pages).
lii Installation and Configuration Guide - Volume 1
NetScaler Logging
This section gives instructions for logging on the NetScaler, and for configuring
the logging features of the NetScaler.
The NetScaler allows you to customize logging of NetScaler and SSL VPN
access events to the needs of your site. You can direct these logs either to files on
the NetScaler, or to external log servers.
The NetScaler uses the Audit Server Logging feature for logging the states and
status information collected by different modules in the kernel as well as in the
user-level daemons. For more information on the Audit Server Logging feature,
refer to the chapter Audit Server Logging.
You can customize two logging functions for NetScaler events—messaging and
syslog. The NetScaler’s internal event message generator that passes log entries
to the syslog server. The syslog server accepts these log entries and logs them.
Logging NetScaler Events
This subsection describes how to configure NetScaler event logging.
Logging of NetScaler and VPN events is enabled by default. To disable logging
of NetScaler and VPN events, you must add the entries described below to the
end of the /nsconfig/rc.conf file, with each entry on a separate line. If the file does
not already exist, you must create it.
Caution: For High Availability (HA) installations, NetScaler logging
configurations are not automatically propagated across an HA pair. You must
either manually copy the configuration files to the HA peer, or repeat your file
creations and modifications on the peer.
Disabling Events Logging
To disable NetScaler events logging, add the following entry to the end of the /
nsconfig/rc.conf file, on a separate line:
nssyslog_enable="NO"
To disable VPN events logging, add the following entry to the end of the /
nsconfig/rc.conf file, on a separate line:
nsvpnl og_enabl e=" NO"
Disabling Syslog
The syslog daemon is enabled by default. For disabling syslog, add the following
entry to the end of the /nsconfig/rc.conf file, on a separate line:
Chapter 2 Managing the Citrix NetScaler liii
sysl ogd_enabl e=" NO"
Customizing Syslog
This section explains how to modify the syslog configuration of your NetScaler.
Editing Syslog File
To customize the syslog configuration, you begin by copying the base syslog.conf
file from /etc to /nsconfig/syslog.conf. When the NetScaler restarts, the
dynamically generated /etc directory is recreated, and your customized
syslog.conf file is used instead of the base version.
Overriding nssyslog Local Facility
NetScaler messages are configured to use the syslog local0 facility, logging to /
var/log/ns.log. To override this, you must make two edits. First, you add the
following line to /nsconfig/rc.conf:
nssysl og_f l ags=" - s sysl ogf aci l i t y=0 - s sysl og=1 - d event wai t "
You must create a new file if one does not already exist. Now, replace the local
facility value, syslogfacility=0, with the desired level. For example, to configure
the local2 facility for NetScaler logs, your new entry for the syslogfacility value
should read syslogfacility=2.
Next, you must edit the syslog configuration to reflect the new value. If you have
not previously copied /etc/syslog.conf to /nsconfig, do so now. You then open /
nsconfig/syslog.conf in a text editor, and change the following line to use the new
local facility value:
l ocal 0. * / var / l og/ ns. l og
For example, if you want to use the local2 facility, change local0.* to local2.*.
Note: When editing syslog.conf, be sure to use tabs as field separators.
Overriding nsvpn Local Facility
By default, VPN messages are configured to use the syslog local1 facility,
logging to /var/log/nsvpn.log. To use another syslog local facility for VPN
logging, you must change entries in two files.
First, edit the /nsconfig/rc.conf file, creating a new file if it does not already exist.
In this file, add the following line, changing the syslogfacility value to your
desired syslog local facility number:
nsvpnl og_f l ags=" - s sysl ogf aci l i t y=1 - s sysl og=1 - d accessl ogs"
liv Installation and Configuration Guide - Volume 1
For example, if you want to use the local4 facility instead of the default local1
facility, you must change the syslogfacility entry to syslogfacility=4.
Next, you need to update /nsconfig/syslog.conf to reflect the new local logging
facility value. To do this, edit /nsconfig/syslog.conf and change the following line
to use the new local facility value:
l ocal 1. * / var / l og/ nsvpn. l og
For example, if you want to use the local4 syslog facility for VPN event logging,
you must change the facility entry to local4.* in this line.
Configuring Logging to External log host
This section describes configuring the NetScaler and VPN logging to an external
host.
If you prefer to have syslog send messages to an external log host instead of to
local files, you will need to remove the log file specifications in your /nsconfig/
syslog.conf file for both of the local facilities, replacing them with the loghost
hostname or IP address of the remote syslog host, as shown below.
l ocal 0. * @10. 100. 3. 53
l ocal 1. * @10. 100. 3. 53
You must also configure the syslog server to accept log entries from both of these
logging facilities. Consult your syslog server documentation to determine how to
do this. For most UNIX-based servers using the standard syslog software, you
must add a local facility configuration line for both the ns.log and nsvpn.log log
files to the syslog.conf configuration file. The facility values must correspond
with those configured on the NetScaler.
Configuring Log File Rotation
Log files on the NetScaler are automatically rotated at regular intervals. If you
change the names of your log files, you must update the rotation configuration to
reflect the new names, so that the correct files will be rotated. You can also
customize other aspects of the rotation configuration for your log files.
You can find the file that controls log rotation at /etc/newsyslog.conf. To make
changes to this file, copy the file from /etc/newsyslog.conf to /nsconfig/
newsyslog.conf if newsyslog.conf does not already exist in the /nsconfig
directory. Edit the /nsconfig/newsyslog.conf file, and reboot the NetScaler to
implement your changes.
If you need to update a log file name, you edit the appropriate file name in the left
column. The remaining columns control the log rotation parameters. If you need
to customize the log rotation parameters, you can refer to the FreeBSD manpage
on newsyslog(8), because the NetScaler logging facility uses the same file
formats and syntax.
Chapter 2 Managing the Citrix NetScaler lv
Path MaximumTransmission Unit Discovery
This section covers the NetScaler path maximum transmission unit (MTU)
discovery feature of the NetScaler.
HowIt Works
PMTU discovery is a method for dynamically learning the maximum
transmission unit of any Internet channel. This discovered PMTU is then used by
the TCP or UDP layer to create packets of an optimum size for that channel. This
avoids fragmentation overhead on the routers in the path, and reassembly
overhead on the receiving server.
PMTU discovery is an operation mode in the NetScaler. This mode enables the
NetScaler to interoperate with other routers participating in PMTU Discovery. In
a typical topology, the NetScaler is deployed in front of the servers it manages,
and either manages connections from clients on behalf of these servers
(transparent mode), or manages connections with the servers and clients
independently (end-point mode).
The NetScaler in End-Point Mode
In end-point mode, the NetScaler separately manages connections to the servers it
manages and clients that contact those servers separately.
For client connections, the NetScaler uses an MSS of 1460 bytes, meaning that
the MSS of packets sent to the client is a minimum of 1460 bytes, as received
from the client. If the network contains a router that fragments the packet into
multiple datagrams because of MTU mismatches, the router sends an ICMP error
to the NetScaler. The NetScaler does not pass the error to the servers it manages,
but parses it and determines an MTU appropriate for that particular client.
The NetScaler then updates the MTU database with the lower MTU. Thereafter, it
uses the new MTU value for all new connections to that client.
The NetScaler in Transparent Mode
In transparent mode, if a managed server sets the DF bit and sends a datagram,
and Path MTU is smaller than the size of the datagram, the NetScaler receives an
ICMP error. When the NetScaler is operating in MIP mode, it adjusts the MTU to
the MIP and updates the MTU database so that the lower MTU is used for
subsequent connections. All packets subsequently sent via that connection have
the DF bit unset.
Note: This affects all clients using that MIP, not just the client that generated
the ICMP error.
lvi Installation and Configuration Guide - Volume 1
In USIP mode, when an ICMP error message is received, the NetScaler translates
it and sends it to the managed server. The managed server updates the MTU for
that destination, and subsequent datagrams are sent with the lowered MTU. The
MTU value for that client is also updated in the NetScaler. All new connections
then use the lowered MTU.
Enabling PMTU Discovery
This section covers procedure to enable the PMTU Discovery feature in the
NetScaler. The NetScaler does not participate in PMTU Discovery by default,
you have to enable this feature. The default PMTU size is 576 bytes.
To enable PMTU discovery
1. In the left pane, expand System, then click Settings. The Settings page
appears in the right pane.
2. Under Modes & Features click modes. The Configure Modes dialog box
appears.
3. Select the Path MTU Discovery option and click OK
Note: To disable PMTU discovery, clear thePath MTU Discovery option and
click OK.
Autodetected Services
When the NetScaler is deployed in transparent mode, it provides an autodetection
service, where it automatically detects back-end Web servers. The following are
some scenarios:
Configuring Global HTTP port
When the NetScaler is using transparent mode connection multiplexing, you can
configure global HTTP port(s) on the NetScaler with no virtual IP addresses
(VIPs) or services.
What are the allowable service types? In this case, the client directly accesses the
back-end web server using the server’s IP address. If the destination port matches
the configured global HTTP port(s), then the NetScaler dynamically detects the
information it needs. You can configure several such vservers simultaneously.
To create a vserver for autodetecting transparent HTTP services
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
Chapter 2 Managing the Citrix NetScaler lvii
2. Click Add. The Create Virtual Servers (Load Balancing) dialog box
appears.
3. In the Name, IP Address, and Port text boxes, type LBhttp and 80
respectively.
4. In the IP Address and Port text box, type ‘*’.
5. In the Protocol drop-down list box select HTTP.
6. Click Create and then click Close. The vserver you created appears in the
Load Balancing Virtual Servers page.
Configuring Cache-Redirection
The NetScaler is deployed in transparent or reverse cache redirection topology,
and the cache redirection virtual server mode is set to cache. When the NetScaler
detects that the cache is down, it automatically redirects requests to the origin
server(s).
Configuring Transparent SSL
In transparent mode connection multiplexing, you configure wildcard *.443
port(s) on the NetScaler with no virtual IP addresses (VIPs) or services.
For the client to access the back-end server, L2 mode needs to be enabled on the
NetScaler. The client directly accesses the backend web server using the server’s
IP address. If the destination port matches the configured wildcard *.443 port(s),
the NetScaler dynamically detects and learns the necessary information.
To create a vserver for autodetecting transparent SSL services
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. Click Add. The Create Virtual Servers (Load Balancing) dialog box
appears.
3. In the Name, IP Address, and Port text boxes, type LBssl and 443
respectively.
4. In the IP Address and Port text box, type ‘*’.
5. In the Protocol drop-down list box select SSL.
6. Click Create and then click Close. The vserver you created appears in the
Load Balancing Virtual Servers page.
lviii Installation and Configuration Guide - Volume 1
CHAPTER 1
Introduction
This chapter describes the objectives of the Citrix NetScaler Installation and Configuration Guide - Volume
1, how it is organized, its intended audience, and its document conventions.
In This Chapter
• About This Guide
• New in This Release
• Audience
• Additional Product Support
• Document Conventions
• Getting Service and Support
• Documentation Feedback
• Related Documentation
About This Guide
This guide covers the steps involved in installation and configuration of the NetScaler and all the
commonly used features. The features covered in this guide are:
• High Availability
• Load Balancing
• Content Switching
• Secure Sockets Layer (SSL) Acceleration
• FIPS
• Client Keep-Alive
• TCP Buffering
• Compression
• Surge Protection
2 Installation and Configuration Guide - Volume 1
• Priority Queuing
• Layer 7 Denial of Service Protection
• Content Filtering Works
• Layer 3-Layer 4 Denial of Service (SYN) Protection
• Surge Protection
• Web Server Logging
• Audit Server Logging
• Reverse NAT
• MAC-Based Forwarding
• Route Health Injection
• VLAN
• Link Aggregation
• Link Load Balancing
• Dynamic Routing
• IPv6
• URL Rewrite
• HTML Injection
• Responder
Audience
This guide is intended for system and network administrators who install and configure complex
networking equipment. While sales and marketing professionals might find the conceptual information
useful, they are advised to refer to the white papers, product brochures, and other literature on our Web site
for more details.
Additional Product Documentation
The NetScaler documentation set consists of the following:
• Citrix NetScaler Quick Start Guide - Provides instructions for installing the hardware. Includes
instructions for rack mounting the chassis, fixing SFPs and XFPs, connecting the cables, and
connecting to the power supply.
• Citrix NetScaler Getting Started Guide - Describes how to initially set up and configure a Citrix®
NetScaler®. It begins with an overview of the core architecture, followed by details about the product
line, installation and deployment instructions, and hands-on labs that cover commonly used features.
• Citrix NetScaler Migration Guide - Applies to users upgrading the system software. Covers upgrade
and downgrade procedures, new commands and APIs, command and API changes.
Chapter 1 Introduction 3
• Citrix NetScaler Installation and Configuration Guide, Volume 2 - Covers the steps involved in
configuring the advanced features. The features covered in this guide are:
• Domain Name System (DNS)
• Global Server Load Balancing (GSLB)
• Cache Redirection
• Firewall Load Balancing
• Integrated Caching
• SureConnect
• Citrix NetScaler Command Reference Guide - Provides detailed descriptions of all the CLI
commands. The contents of this guide are identical to the man pages.
• Citrix NetScaler Release Notes - Covers enhancements, new features, known issues, and limitations.
• Citrix NetScaler Advanced Policy Guide - Covers the policy infrastructure which includes both the
Policy Expressions (PE) and Policy Infrastructure (PI) languages. Includes examples drawn from
real-life configurations.
• Citrix Application Firewall Guide - Covers the features, configuration, and maintenance of both the
standalone Citrix Application Firewall and the integrated Citrix NetScaler Application Firewall
feature.
• Access Gateway Enterprise Edition Administrator’s Guide - Administrator manual for configuring
Access Gateway Enterprise Edition.
• Citrix Secure Access Client User Guide for Java - User manual for using Secure Access for J ava.
• Citrix Secure Access Client User Guide for Windows - User manual for using Secure Access for
Windows.
The NetScaler guides are provided as Adobe Portable Document Format (PDF) files. You can locate this
documentation on your product CD or on the Citrix Support Web site at http://support.citrix/com/.
Document Conventions
This documentation uses the following typographic conventions.
Note: Procedures in this guide are examples that you can enter to get your NetScaler up and running. You
can literally follow the examples, including the sample values, and later enter your own values to customize
your configuration. For complete information about configuration options, refer to the Command Reference
Guide.
Convention Meaning
Boldface Commands that you type exactly as shown.
Italics New terms, words that would otherwise be enclosed in quotation marks, and
placeholders for information or parameters that you provide. For example,
FileName in a command means you type the actual name of a file.
Monospace Text displayed in a text file and commands used at the NetScaler Command
Line Interface (CLI).
4 Installation and Configuration Guide - Volume 1
Getting Service and Support
Citrix provides technical support primarily through the Citrix Solutions Network (CSN). Our CSN partners
are trained and authorized to provide a high level of support to our customers. Contact your supplier for
first-line support, or check for your nearest CSN partner at http://support.citrix.com/.
In addition to the CSN program, Citrix offers a variety of self-service, Web-based technical support tools
from its Knowledge Center at http://support.citrix.com/.
Knowledge Center features include:
• A knowledge base containing thousands of technical solutions to support your Citrix environment
• An online product documentation library
• Interactive support forums for every Citrix product
• Access to the latest hotfixes and service packs
• Security bulletins
• Online problem reporting and tracking (for organizations with valid support contracts)
Another source of support, Citrix Preferred Support Services, provides a range of options with which you
can customize the level and type of support for your organization's Citrix products.
Additional Maintenance Support
In addition to the standard support options, all NetScalers are available with Silver and Gold maintenance
options. If you purchase either of these options, you receive documentation with special Citrix Technical
Support numbers you can call.
Silver Maintenance Option
The Silver maintenance option provides unlimited system support for one year. This option provides basic
coverage hours, one assigned support account manager for nontechnical relations management, four named
contacts, and advanced replacement for materials.
Technical support is available at the following times:
• North America, Latin America, and the Caribbean: 8 A.M. to 9 P.M. U.S. Eastern Time, Monday
through Friday
• Asia (excluding J apan): 8 A.M. to 6 P.M. Hong Kong Time, Monday through Friday
• Australia and New Zealand: 8 A.M. to 6 P.M. Australian Eastern Standard Time (AEST), Monday
through Friday
• Europe, Middle East, and Africa: 8 A.M. to 6 P.M. Coordinated Universal Time (Greenwich Mean
Time), Monday through Friday
Gold Maintenance Option
The Gold maintenance option provides unlimited system support for one year. Support is available 24 hours
a day, 7 days a week. There is one assigned support account manager for nontechnical relations
management, and there are six named contacts.
Chapter 1 Introduction 5
Subscription Advantage
Your product includes a one-year membership in the Subscription Advantage program. The Citrix
Subscription Advantage program gives you an easy way to stay current with the latest software version and
information for your Citrix products. Not only do you get automatic access to download the latest feature
releases, software upgrades, and enhancements that become available during the term of your membership,
you also get priority access to important Citrix technology information.
You can find more information on the Citrix Web site at http://www.citrix.com/services/ (on the Support
menu, click Subscription Advantage).
You can also contact your sales representative, Citrix Customer Care, or a member of the Citrix Solutions
Advisors program for more information.
Knowledge Center Watches
You can set up alerts to have the Citrix Knowledge Center notify you if a topic you are interested in is
updated.
To set up an alert, log on to the Citrix Support Web site at http://support.citrix.com.
After you are logged on, under Products, select a product. Under Alerts, click Add to your Alerts. To
remove an alert, go to the Knowledge Center product and click Remove from your Alerts.
Education and Training
Citrix offers a variety of instructor-led and Web-based training solutions. Instructor-led courses are offered
through Citrix Authorized Learning Centers (CALCs). CALCs provide high-quality classroom learning
using professional courseware developed by Citrix. Many of these courses lead to certification.
Web-based training courses are available through CALCs, resellers, and from the Citrix Web site.
Information about programs and courseware for Citrix training and certification is available at http://
www.citrix.com/edu/.
Documentation Feedback
You are encouraged to provide feedback and suggestions so that we can enhance the documentation. You
can provide feedback in one of the following ways:
• Send e-mail to nsdocs_feedback@citrix.com with the subject line “Installation and Configuration
Guide - Feedback.” Be sure to include the following information in your e-mail: document name,
page number, and product release version.
• Fill out the documentation feedback form at http://support.citrix.com/docfeedback/.
• Navigate to the Knowledge Center home page (http://support.citrix.com) and do the following:
A. On the Knowledge Center home page, click Citrix Application Delivery and click a release
of your choice.
B. On the Citrix Application Delivery Software <release number> page, on the
Documentation tab, click the guide name and click Article Feedback.
C. On the Documentation Feedback page, complete the form and click Submit.
6 Installation and Configuration Guide - Volume 1
Related Documentation
The following guides and release notes are available for Access Gateway Enterprise Edition and
WANScaler products. All documents are available at http://support.citrix.com/.
For information about Citrix Access Gateway Enterprise Edition, the following guides are available:
• Citrix Access Gateway Enterprise Edition Administrator’s Guide
• Getting Started with Citrix Access Gateway Enterprise Edition
• Citrix Access Gateway Enterprise Edition Pre-Installation Checklist
• Citrix Secure Access Client User Guide for Java
• Citrix Secure Access Client User Guide for Windows
• Citrix Secure Gateway to Access Gateway Migration Guide
For information about Citrix WANScaler system, the following guides are available:
• Citrix WANScaler Appliances Installation and User’s Guide
• Citrix WANScaler Quick Installation Guide
CHAPTER 2
High Availability
This chapter describes basic and advanced configuration procedures for the High
Availability (HA) feature of the Citrix NetScaler System. Topics include:
• How High Availability Works
• Configuring a Basic High Availability Setup
• Considerations for a High Availability Setup
• Customizing an High Availability Setup
• Improving the Reliability of a High Availability Setup
• Configuring the State of a Node
• Troubleshooting HA Issues
How High Availability Works
If you have two systems, you can deploy them in a configuration where one
system accepts connections and manages servers, while the second system
monitors the first. If, for any reason, the first system is unable to accept
connections, the second system takes over. A high availability configuration
prevents downtime and ensures uninterrupted service when a system ceases to
function.
The secondary system monitors the primary system by sending periodic messages
to the primary system (often called heartbeat messages or health checks) to
determine if it is accepting connections. When a health check fails, the secondary
system retries the connection for a specified period, after which it determines that
the primary system is not functioning normally. The secondary system then takes
over for the primary system (a process called failover).
After a failover, all clients must reestablish their connections to the managed
servers, but the session persistence rules are maintained as they were before the
failover.
8 Installation and Configuration Guide - Volume 1
With Web server logging persistence enabled, no log data is lost due to the
failover. For logging persistence to be enabled, the log server configuration must
carry entries for both systems in the log.conf file. For details of setting up logging
persistence, see Chapter 12, "Web Server Logging."
The following figure shows a network configuration with an HA pair:
Systems in High Availability mode
With Web server logging persistence enabled, no log data is lost due to the
failover. For logging persistence to be enabled, the log server configuration must
carry entries for both systems in the log.conf file. For details of setting up logging
persistence, see Chapter 12, "Web Server Logging."
Considerations for a High Availability Setup
Note the following requirements for configuring systems in an HA setup:
• The passwords for the default administrator accounts (nsroot) on both
systems in an HA pair must be the same. However, the operating system
does not automatically synchronize these passwords. Therefore, when you
change the password of the nsroot account on one system, you must also
perform the change manually on the other system.
• Entries in the configuration file (ns.conf) on both the primary and the
secondary system must match, with the following exceptions:
• The primary and the secondary systems must each be configured with
their own unique NetScaler IPs (NSIPs.)
Chapter 2 High Availability 9
• In an HA pair, the node ID and associated IP address of one system
must point to the other system. For example, if you have two systems,
NS1 and NS2, then you must configure NS1 with a the unique node
ID and the IP address of NS2, and you must configure NS2 with a
unique node ID and the IP address of NS1.
• If you create or copy a configuration file on either system using a method
other than the direct GUI or the CLI (for example, SSL certificates, or
changes to startup scripts), you must create or copy the configuration file
onto both the primary and the secondary systems.
• You must configure Remote Procedural Call (RPC) node passwords on
both systems in an HA pair. Initially, all systems are configured with the
same RPC node password. RPC nodes are internal system entities used for
system-to-system communication of configuration and session information.
For security, you should change the default RPC node passwords.
One RPC node exists on each system. This node stores the password, which
is checked against the password provided by the contacting system.
In order to communicate with other systems, each system requires
knowledge of those systems, including how to authenticate on those
systems. RPC nodes maintain this information, which includes the IP
addresses of the other systems, and the passwords used to authenticate on
each.
RPC nodes are implicitly created when adding a node or adding a Global
Server Load Balancing (GSLB) site. You cannot create or delete RPC nodes
manually.
Note: If the systems in a high availability setup are configured in one-arm
mode, you must disable all system interfaces except the one connected to the
switch or hub.
Configuring High Availability
This section describes how to configure a basic high availability setup. The
following topics are covered:
• Configuring a Basic High Availability Setup
• Modifying an Existing High Availability Setup
10 Installation and Configuration Guide - Volume 1
Configuring a Basic High Availability Setup
This section describes procedures to configure two systems in a high availability
setup, as illustrated in the following figure:
Two systems connected in an HA setup
In the figure, systems NS1 and NS2 are on the same subnet. To config-
ure the systems in high availability mode, you must configure one sys-
tem as primary and the other as secondary. You will need to perform the
following procedures, as described in the sections that follow:
• Add a node
• Disable HA monitor for unused interfaces
• Save the configuration
• Verify the configuration
Adding a Node
This section describes how to add a node in an HA setup. The new node is
identified by a unique ID and its NSIP. The maximum number of node IDs for
systems in a high availability setup is 64.
Chapter 2 High Availability 11
To add a node, use the parameters described in the followint table:
To add a node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Add. The Add Node dialog box appears.
4. In the ID text box, type an ID. For example, type 3.
5. In the IP Address textbox, type an IP Address, for example, 10.102.29.170.
6. Click Create. The Add Node dialog box is appears, as shown in the
following figure:
Adding a node
To add a node using the NetScaler command line
At the NetScaler command prompt, type:
add HA node 3 10.102.29.170
Disabling HA Monitor for Unused Interfaces
You must disable the HA monitor for interfaces in the system that are not
connected or being used for traffic.
Parameter Description
Node ID The unique number that identifies the
node to be added. The minimum value is
1 and the maximum value is 64.
IP Address The IP Address of the node to be added.
12 Installation and Configuration Guide - Volume 1
To disable an HA monitor, use the parameters described in the following table:
To disable HA monitor for an unused interface
1. In the left pane, expand Network and click Interfaces. The Interfaces
page appears in the right pane.
2. Select the interfacewhich you want to disable the HA monitor.
3. Click Open. The Configure Interface dialog box appears.
4. In the HA Monitoring select the OFF option.
5. Click OK. The Modify Interface box appears, as shown in the following
figure:
Disabling HA monitor
To disable HA monitor using the NetScaler command line
At the NetScaler command prompt, type:
set interface 1/3 -haMonitor OFF
Parameter Description
Interface Number The interface number represented in the <slot/port>
notation.
Chapter 2 High Availability 13
Saving the Configuration
This section describes how to save the configuration for a basic HA setup.
To save the configuration
1. In the GUI screen, click Save. A pop-up window appears.
2. Click Yes to save the configuration.
Note: To ensure that each system in the configuration has the same settings,
you should synchronize your SSL certificates, startup scripts, and other
configuration files with those on the primary system..
To save the configuration using the NetScaler command line
At the NetScaler command prompt, type:
save ns config
Verifying the Configuration
To verify your configuration, you can view the node and check its status in the
local system. One node will be primary and other will be secondary.
To view the configuration
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears, with the primary and the
secondary nodes displayed.
To view the configuration using the NetScaler command line
At the NetScaler command prompt, type:
sh ha node
Modifying an Existing HA Setup
This section describes the procedures to modify an existing high availability
configuration. The following topics are covered:
• Disabling a Node
• Enabling a Node
• Removing a Node
14 Installation and Configuration Guide - Volume 1
Disabling a Node
You can only disable a secondary node. When you disable a secondary node, it
stops sending heartbeat messages to the primary node. The primary node
therefore can longer check the status of the secondary node.
To disable a node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the secondary node and click Open. The Configure Node Dialog
box appears.
4. Under High Availability Status, select the DISABLED (Do not
participate in HA) option.
5. Click OK. The Configure Node dialog box is shown in the following
figure:
Disabling a secondary node
To disable a node using the NetScaler command line
At the NetScaler command prompt, type:
Chapter 2 High Availability 15
set HA node -hastatus DISABLED
Enabling a Node
When you enable a node, the node takes part in the high availability
configuration. You can only enable a secondary node.
To enable a node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the secondary node and click Open. The Configure Dialog box
appears.
4. Under High Availability Status, select the ENABLED (Actively
participates in HA) option.
5. Click OK and click Close.
To enable a node using the NetScaler command line
At the NetScaler command prompt, type:
set ha node -hastatus ENABLED
Removing a Node
When you remove a node, the nodes are no longer in high availability
configuration.
To remove a node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the node that you want to remove.
4. Click Remove. The Remove pop-up window appears.
5. Click Yes.
To remove a node using the NetScaler command line
At the NetScaler command prompt, type:
r mha node 3
16 Installation and Configuration Guide - Volume 1
Customizing an High Availability Setup
This section describes the steps to customize a high availability setup. The
following topics are covered:
• Configuring the Communication Intervals
• Configuring Synchronization
• Configuring Command Propagation
• Forcing a Node to Failover
Configuring the Communication Intervals
This section describes the procedure to configure the communication intervals in
a high availability configuration. The hello interval is the interval at which the
heartbeat messages are sent to the peer node. The dead interval is the time interval
after which the peer node is marked DOWN if heartbeat packets are not received.
The heartbeat messages are UDP packets sent to port 3003 of the other system in
an HA pair.
To set the hello and the dead intervals, use the parameters listed in the following
table:
To set the hello and dead intervals
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the node for which you want to change the hello interval.
4. Click Open. The Configure Dialog box appears.
5. Under Interval, in the Hello Interval (msecs) within the Interval frame,
type the interval, for example, 400.
6. In the Dead Interval (secs), type the interval, for example, 6.
Parameter Description
Hello Interval The time interval between successive
heartbeat messages in milliseconds. The
default value is 200. The minimum value
is 200, and maximum value is 1000.
Dead Interval The time duration in seconds after which
a node is declared dead if there is no
response to heartbeat messages. The
default value is 3, the minimum value is
3, and the maximum value is 60.
Chapter 2 High Availability 17
7. Click OK.
To set the hello and dead intervals using the NetScaler command line
At the NetScaler command prompt, type:
set HA node -helloInterval 400 -deadInterval 6
Configuring Synchronization
Synchronization is a process of pulling the configuration of the primary node by
the secondary node. The purpose of the synchronization process is to ensure that
there is no loss of configuration information between the primary and the
secondary nodes, irrespective of the number of failovers that occur. The port
number 3010 is used for synchronization.
The synchronization process is triggered in the following circumstances:
• When a secondary node in an HA setup comes up after a restart
• When the primary node becomes secondary after a failover occurred in an
HA setup
Disabling or Enabling Synchronization
HA synchronization is enabled by default in each node in an HA pair. You can
enable or disable HA synchronization on either node in an HA pair.
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the local node.
4. Click Open. The Configure Dialog box appears.
5. Under HA Synchronization, clear the Secondary node will fetch the
configuration from Primary option.
6. Click OK and then click Close.
Note: To enable HA synchronization, in step 5 above, you must select
Secondary node will fetch the configuration from Primary.
To disable or enable automatic synchronization using the NetScaler
command line
At the NetScaler command prompt, type:
set HA node -haSync ENABLED
18 Installation and Configuration Guide - Volume 1
or
set HA node -haSync DISABLED
Forcing the Secondary Node to Synchronize with the
Primary Node
In addition to automatic synchronization, the system supports forced
synchronization. You can force the synchronization from either the primary or the
secondary node. When you force synchronization from the secondary node, it
will start synchronizing its configuration with the primary node.
However, if synchronization is already in progress, forced synchronization will
fail and the system will display a warning. Forced synchronization will also fail in
the following circumstances:
• when you force synchronization on a standalone system
• when the secondary node is disabled
• when HA synchronization is disabled in the secondary node
To force the secondary node to synchronize with the primary node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Force Synchronization.
To force synchronization using the NetScaler command line
At the NetScaler command prompt, type:
force HA sync
Configuring Command Propagation
In an HA setup, any command issued on the primary node will propagate
automatically to the secondary node. When a command is issued on the primary,
the command is first propagated to and executed on secondary, and then executed
on the primary. If the command propagation fails due to some reason or command
execution fails on the secondary after command propagation, the primary node
will still execute the command and an error will be logged. Port number 3011 is
used for command propagation.
In an HA pair configuration, command propagation is enabled by default on both
the primary and secondary nodes. You can enable or disable command
propagation on either node in an HA pair. If you disable command propagation in
the secondary node, it command is effective only on the primary node.
Chapter 2 High Availability 19
Note: Afte re-enabling propagation, remember to force synchronization
When you disable propagation in the primary node, commands executed on the
primary node are no longer propagated to the secondary node.
When you disable propagation on a primary node after synchronization has been
successfully completed, commands executed on the primary node are not
propagated to the secondary node. However, if synchronization occurs during this
period, the configuration-related changes that you made when propagation was
disabled are synchronized with the secondary node. This is also true for cases
where propagation is disabled while synchronization is in progress.
To disable or enable command propagation
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Select the local node.
4. Click Open. The Configure Dialog box appears.
5. Under HA Propagation, clear the Primary node will propagate
configuration to the Secondary option .
6. Click OK.
Note: To enable HA synchronization, in Step 5 you must select the Primary
node will propagate configuration to the Secondary.
To disable or enable command propagation using the NetScaler command
line
At the NetScaler command prompt, type:
set HA node -haProp ENABLED
or
set HA node -haProp DISABLED
20 Installation and Configuration Guide - Volume 1
Forcing a Node to Failover
One scenario where you might want to force a failover is when you need to
replace or upgrade your primary system in an HA setup. You can force failover
either from the primary or the secondary system. A forced failover is not
propagated or synchronized. To view the synchronization status after a forced
failover, you can view the status of the node.
A forced failover will fail in the following circumstances:
• when you force failover on a standalone system
• when the secondary node is disabled
• when the secondary node is configured to remain as secondary
Forcing the Primary Node to Failover
If you force failover on the primary system, the primary becomes the secondary
system and the secondary becomes the primary. Forced failover is only possible
when the primary system can determine that the secondary system is UP. If the
Secondary system is DOWN, the force failover command returns the error
message "Operation not possible due to invalid peer state. Rectify and retry." If
the secondary system is in the claiming state or inactive, it returns the message
"Operation not possible now. Please wait for system to stabilize before retrying."
To force the primary node to failover
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Force Failover. The Warning pop-up window appears.
4. Click Yes.
To force the primary node to failover using the NetScaler command line
At the NetScaler command prompt, type:
force HA failover
Chapter 2 High Availability 21
Forcing the Secondary Node to Failover
When you execute the force failover command from the secondary system, then
the secondary system becomes the primary system and the primary node becomes
the secondary system. Force failover happens only if the secondary system’s
health is good or if it is not configured to stay secondary. If the secondary system
cannot become the primary system, or if secondary system was configured to stay
secondary using the staysecondary option, the system displays the message
“Operation not possible as my state is invalid. View the node for more
information.”
To force the secondary node to failover
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Force Failover. A Warning pop-up window appears.
4. Click Yes.
To force the secondary node to failover using the NetScaler command line
At the NetScaler command prompt, type:
force HA failover
Forcing Failover When Nodes are in Listen Mode
When the two nodes of an HA pair are running different versions of the system
software, the node running the higher version switches to the listen mode. In this
mode, neither command propagation or synchronization work.
Before upgrading the system software on both nodes, you should test the new
version on one of the nodes. To do this, you will need to force a failover on the
system that has already been upgraded. The upgraded system then takes over as
the primary node, but neither command propagation or synchronization occurs.
Also, all connections need to be re-established.
To force failover when nodes are in listen mode
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Force Failover. A Warning pop-up window appears.
4. Click Yes.
22 Installation and Configuration Guide - Volume 1
To force failover when nodes are in listen mode using the NetScaler
command line
At the NetScaler command prompt, type:
force HA failover
Improving the Reliability of a High Availability Setup
This section describes how to configure the Virtual MAC address (VMAC) and
high availability when nodes are in different subnets. This section also describes
link redundancy and route monitors, system functions that can be helpful in a
cross-network HA configuration, and the health check process used by a system
to ensure that its partner node is up and running.
The section covers the following topics:
• Configuring Virtual MAC Addresses
• Configuring High Availability for Nodes in Different Subnets
• Configuring Link Redundancy
• Configuring Route Monitors
• HA Health Check Computation
Configuring Virtual MAC Addresses (VMAC)
The Virtual MAC address (VMAC) is a floating entity shared by the primary and
the secondary nodes in an HA setup.
In an HA setup, the primary node owns all of the floating IP addresses such as the
MIP, SNIP, VIP and so on. The primary node responds to Address Resolution
Protocol (ARP) requests for these IP addresses with its own MAC address. As a
result, the ARP table of an external device (for example, an upstream router) is
updated with the floating IP address and the primary node's MAC address.
When a failover occurs, the secondary node takes over as the new primary node.
It then uses the Gratuitous ARP (GARP) to advertise the floating IP addresses
that it acquired from the primary. The MAC address that the new primary
advertises is the MAC address of the new primary's own interface.
Some devices (notably a few routers) do not accept GARP messages generated by
the Citrix NetScaler system. As a result, some external devices will retain the old
IP to MAC mapping advertised by the old primary node. This may result in a site
going down.
Chapter 2 High Availability 23
You can overcome this problem by configuring a VMAC on both nodes of an HA
pair. When you do this, both nodes possess identical MAC addresses. Therefore,
when failover occurs, the MAC address of the secondary node remain unchanged,
and the ARP tables on the external devices do not need to be updated.
As mentioned earlier, the VMAC is a user-defined MAC address that is shared by
the primary and secondary nodes. To create a VMAC, you need to first create a
Virtual Router ID (VRID) and bind it to an interface. (In an HA setup, you need
to bind the VRID to the interfaces on both nodes.) Once the VRID is bound to an
interface, the system generates a VMAC with the VRID as the last octet.
The generic VMAC is of the form 00:00:5e:00:01:<VRID>. For example, if you
create a VRID with a value of 60 and bind it to an interface, the resulting VMAC
is 00:00:5e:00:01:3c, where 3c is the hex representation of the VRID. You can
create 255 VRIDs with values from 1 to 254.
This section covers the following procedures:
• Adding a Virtual MAC Addresses
• Binding Interfaces to the Virtual MAC Address
• Verifying the VMAC Configuration
Adding a VMAC
The example scenario described in this section illustrates the configuration of a
VMAC on a standalone system, with a VRID value of 100.
To add a virtual MAC, use the parameters in the following table:
To add a VMAC
1. In the left pane, expand Network and click VMAC. The VMAC page
appears in the right pane.
2. Click Add. The Add VMAC appears, as shown in the figure below.
3. In the Virtual Router ID text box, type a number, for example, 100.
4. Click Create.
Parameter Description
Virtual Router ID Each VMAC is identified by a VRID.
Minimum value is 1 and maximum is
255.
Interface Number. The interface number represented in the
<slot/port>notation to be bound to the
VMAC.
24 Installation and Configuration Guide - Volume 1
.
Adding VMAC
To add a VMAC using the NetScaler command line
At the NetScaler command prompt, type:
add vrID 60
Binding Interfaces to the VMAC
The following procedure illustrates the steps to bind the VRID to interface 1/1.
You cannot bind multiple VRIDs to an interface.
To bind an interface to a VMAC, use the parameters listed in the following table:
To bind interfaces to the VMAC
1. In the left pane, expand Network and click VMAC. The VMAC page
appears in the right pane.
2. Click Open. The Configure VMAC dialog box appears.
Parameter Description
Virtual Router ID. Each VMAC is identified by a VRID.
Minimum value is 1 and maximum is
255
Interface Name The interface name represented in the
<slot/port>notation to be bound to the
VMAC.
Chapter 2 High Availability 25
3. Select the desired interfaces from the Available Interfaces table and click
Add. For example, 1/1, 1/2, and 1/3.
4. The interfaces are bound to the VMAC and appear in theConfigured
Interfaces table.
5. Click OK.
To bind interfaces to the VMAC using the NetScaler command line
At the NetScaler command prompt, type:
bind vrid 100 ifnum 1/1 1/2 1/3
Verifying the VMAC Configuration
To verify the VMAC configuration, perform the following steps as described in
the procedures that follow:
• View the VMACs
• View the interfaces bound to the VMAC
To view VMACs
1. In the left pane, expand Network and click VMAC.
2. The VMAC page appears, with all the available VMACs displayed.
To view VMACs using the NetScaler command line
At the NetScaler command prompt, type:
sh vrID
To view the interfaces bound to the VMAC
1. In the left pane, expand Network and click VMAC.
2. The VMAC page appears, with all the available VMACs.
3. Select a VMAC, for example 100, the bound interface are displayed in the
bottom of the page.
To view the interfaces bound to the VMAC using the NetScaler command
line
At the NetScaler command prompt, type:
sh vrID 100
26 Installation and Configuration Guide - Volume 1
Managing VMACs
This section describes procedures for unbinding the interfaces from a VMAC and
deleting the created VMAC from the system.
To unbind interfaces from a VMAC
1. In the left pane, expand Network and click VMAC. The VMAC page
appears in the right pane.
2. Select a VMAC, for example 100, and click Open. The Configure VMAC
dialog box appears.
3. In the Configured Interfaces table, select the interfaces you want to
unbind from the VMAC, for example 1/2 and 1/3.
4. Click Remove. The interfaces are unbound from the VMAC and appear in
the Available Interfaces table.
5. Click OK.
To unbind interfaces from a VMAC using the NetScaler command line
At the NetScaler command prompt, type:
unbind vrID 100 1/2 1/3
To remove a VMAC
1. In the left pane, expand Network and click VMAC. The VMAC page
appears in the right pane.
2. Select the VRID that you want to remove from the system, for example
100.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes. The selected VRID is removed.
To remove a VMAC using the NetScaler command line
At the NetScaler command prompt, type:
rm vrid 100
Chapter 2 High Availability 27
Configuring High Availability Nodes in Different
Subnets
The earlier section "Configuring a Basic High Availability Setup" covered a
typical HA deployment where both systems in an HA pair reside on the same
subnet. This section describes an HA pair configuration where the two systems
reside on different subnets. The section provides sample configurations, and a list
of the differences between HA configurations within one subnet, and
configurations across networks.
The following figure shows an HA deployment with the two systems located in
different subnets:
HA over a routed network
In the figure, the systems NS1 and NS2 are connected to two separate routers R3
and R4 on two different subnets. The systems exchange heartbeat packets through
the routers. This configuration could be expanded to accommodate deployments
involving any number of interfaces.
28 Installation and Configuration Guide - Volume 1
Note: If you use static routing on your network, you must add static routes
between all the systems to ensure that heartbeat packets are sent and received
successfully. (If you use dynamic routing on your systems, static routes are
unnecessary.)
If the nodes in an HA pair reside on two separate networks, the secondary node
must have an independent network configuration. This means that nodes on
different networks cannot share entities such as MIPs, SNIPs, VLANs, and
routes. This type of configuration, where the nodes in an HA pair have different
configurable parameters, is known as Independent Network Configuration (INC)
or Symmetric Network Configuration (SNC).
The following table describes the parameters that you must set on each node in an
INC:
When two nodes of an HA pair reside on different subnets, each node must have a
different network configuration. Therefore, to configure two independent systems
to function as an HA pair, you must specify an INC mode during the
configuration process. To specify an INC mode, perform the following steps, as
described in the sections that follow:
• Add a node with inc option enabled
• Disable HA monitor for unused interfaces
• Save the configuration
Configurable Parameters Behavior
IPs (NSIP/MIP/SNIPs) Node-specific. Active only on that unit.
VIP Floating.
Vlans Node-specific. Active only on that unit.
Routes Node-specific. Active only on that unit. LLB route is
floating.
ACLs Floating (Common). Active on both units.
Dynamic routing Node-specific. Active only on that unit. The secondary
node should also run the routing protocols and peer
with upstream routers.
L2 mode Floating (Common). Active on both units.
L3 mode Floating (Common). Active on both units.
Reverse NAT (RNAT) Node-specific. RNAT with VIP, because NATIP is
floating.
Chapter 2 High Availability 29
Adding a Node
This section describes the procedure to add a node in a different subnet than the
local node, using the parameters listed in the following table:
To add a node
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Add. The Add Node dialog box appears.
4. In the ID text box, type an ID, for example, 3.
5. In the IP Address textbox, type an IP Address, for example, 10.102.29.170.
6. Under Independent Network Configuration, select Nodes in an HA pair
would have its network configuration.
7. Click Create.
To add a node using the NetScaler command line
At the NetScaler command prompt, type:
add HA node 3 10.102.29.170 - inc ENABLED
Disabling HA Monitor in Interfaces
You must disable the HA monitor for interfaces in the system that are not
connected or being used for traffic.
To disable HA MON in the interfaces, use the interface number parameter, as
described in the following table:
To disable HA monitor for an unused interface
1. In the left pane, expand Network and click Interfaces. The Interfaces
page appears in the right pane.
Parameter Description
Node ID The unique number that identifies the
node to be added. Minimum value is 1
and maximum value is 64.
IP Address The IP Address of the node to be added.
Parameter Description
Interface number The interface number (represented in the
<slot/port>notation)
30 Installation and Configuration Guide - Volume 1
2. Select the interfacefor which you want to disable the HA monitor.
3. Click Open. The Configure Interface dialog box appears.
4. In the HA Monitoring section select the OFF option.
5. Click OK.
To disable HA monitor using the NetScaler command line
At the NetScaler command prompt, type:
set interface 1/3 -haMonitor OFF
Saving the Configuration
The following procedure describes the steps to save the configuration in the
system.
To save the configuration
1. In the GUI screen, click Save. A pop-up window appears.
2. Click Yes to save the configuration.
To save the configuration using the NetScaler command line
At the NetScaler command prompt, type:
save ns config
Configuring Link Redundancy
Link redundancy is a way to prevent failover by grouping interfaces so that when
one interface fails, other functioning interfaces will still be available.
The section "Configuring High Availability for Nodes in Different Subnets"
describes a scenario in which the first interface on the primary system, NS1, fails,
triggering failover, even though it can still serve client requests via its second
link. The link redundancy feature allows you to group the two interfaces into a
failover interface set (FIS), and prevent the failure of a single link from causing
failover to the secondary system unless all of the interfaces on the primary system
are nonfunctional.
Each interface in an FIS maintains independent bridge entries. HA MON
interfaces that are not bound to an FIS are known as critical interfaces (CI)
because if any of them fails, failover is triggered.
Adding a Failover Interface Set (FIS)
This section describes the procedure to add a Failover Interface Set (FIS) in the
system.
Chapter 2 High Availability 31
To add a FIS
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Failover Interface Set tab. The Failover Interface Set page
appears.
3. Click Add. The Create FIS dialog box appears.
4. In the Name text box, type a name for the FIS to be created, for example,
FIS1.
5. Click Create. The Create FIS dialog box appears, as shown in the
following figure:
Creating FIS
To add a FIS using the NetScaler command line
At the NetScaler command prompt, type:
add fis FIS1
Binding the Interfaces to an FIS
To bind interfaces to the Failover Interface Set, use the parameters listed in the
following table:
Parameter Description
FIS Name The name of the FIS to which interfaces
are to be bound.
32 Installation and Configuration Guide - Volume 1
To bind interfaces to the FIS
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Failover Interface Set tab. The Failover Interface Set page
appears.
3. Click Open. The Configure FIS dialog box appears.
4. Select interfaces from the Available Interfaces table and click Add.
5. The interfaces are bound to the Failover Interface Set and appear in the
Configured Interfaces table.
6. Click OK.
To bind interfaces using the NetScaler command line
At the NetScaler command prompt, type:
bind fis FIS1 1/1 1/2 1/3
Verifying the Created FIS
This section describes how to an FIS that you have created.
To view an FIS
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Failover Interface Set tab. The Failover Interface Set page
appears, with all the configured FISs displayed.
To view an FIS using the NetScaler command line
At the NetScaler command prompt, type:
sh fis FIS1
Managing Link Redundancy
This section describes how to unbind interfaces from an FIS, and how to remove
an FIS.
Interface Number The interface number (represented in the
<slot/port>notation) to be bound to the
FIS.
Parameter Description
Chapter 2 High Availability 33
Unbinding an Interface fromthe FIS
This following sample procedure illustrates the steps to unbind interfaces from an
FIS. An unbound interface becomes a critical interface (CI) if it is enabled and
HA MON is on.
To unbind an interfaces from the FIS
To unbind interfaces from the Failover Interface Set, use the parameters in the
following table:
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Failover Interface Set tab. The Failover Interface Set page
appears.
3. Select the FIS from which you want the interfaces to be unbound.
4. Click Open. The Configure FIS dialog box appears.
5. In the Configured Interfaces table, select the interface you want to unbind
from the FIS, and click Remove.
6. The interface is unbound from the Failover Interface Set and is shown in
theAvailable Interfaces table.
7. Click OK.
To unbind an interfaces from the FIS using the NetScaler command line
At the NetScaler command prompt, type:
unbind fis FIS1 1/1 1/2
Removing the FIS
The following sample procedure describes the steps to remove an FIS that you
have created. Once the FIS is removed, its interfaces become CIs.
To remove a Failover Interface Set, use the parameter in the following table:
Parameter Description
FIS Name The name of the FIS from which the
interfaces are to be unbound.
Interface Name The interface name (represented in the
<slot/port>notation.)
Parameter Description
FIS Name The name of the FIS that is to be
removed.
34 Installation and Configuration Guide - Volume 1
To remove a FIS
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Failover Interface Set tab. The Failover Interface Set page
appears.
3. Select the FIS that you want to remove. For example, select FIS1
4. Click Remove. The Remove pop-up window appears.
5. Click Yes. The selected Failover Interface Set is removed.
To remove a FIS using the NetScaler command line
At the NetScaler command prompt, type:
rm fis FIS1
Configuring Route Monitors
You can make the HA state independent of the system internal routing table,
whether or not dynamically learned routes are present. The procedure requires
using route monitors. If the route is present on which the route monitor is bound,
the node can become primary. If the route is absent, the node will always remain
as secondary.
Note: Route monitors are neither propagated by nodes, or exchanged during
synchronization.
In an HA configuration, a route monitor on each system watches the internal
routing table to make sure that an entry for the other system is always present.
This is especially important when using dynamic routing, because a router error
can make an HA node believe that the other node is down, when it is not. When
the nodes of an HA pair reside on different networks, the HA state of a node
depends on its reachability.
Before the route monitor runs, you must save the configuration.
Note: Clearing the configuration does not delete the route monitors on a
system. You must remove the route monitors manually.
Binding a Route Monitor to an HA Node
This section describes how to add a route monitor in the system.
Chapter 2 High Availability 35
To add a route monitor, use the parameters in the following table:
To add a route monitor
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Route Monitors tab. The Route Monitors page appears.
3. Click Configure. The Bind / Unbind Route Monitor(s) dialog box
appears.
4. In the Network text box, type a network IP, for example, 10.102.29.30
5. In the Netmask text box, type a netmask, for example,255.255.255.0
6. Click Add . The Route Monitor is added and appears in the Configured
Route Monitors table.
7. Click OK. The Bind / Unbind Route Monitor(s) dialog box is shown in
the following figure:
Adding a route monitor
Note: When a route monitor is not bound to a node, the HA state (primary or
secondary) of the node is determined solely by the state of the interfaces.
Parameter Description
Network The network prefix of the route to
be monitored
Netmask The subnet for the network
36 Installation and Configuration Guide - Volume 1
To add a route monitor using the NetScaler command line
At the NetScaler command prompt, type:
bind ns node -routeMonitor 10.102.29.30 255.255.255.0
Verifying the Route Monitors
The following sample procedure describes the steps to verify the configured route
monitor in the system.
To view a route monitor
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Route Monitors tab. The Route Monitors page appears, with all
the configured route monitors displayed.
To view a route monitor using the NetScaler command line
At the NetScaler command prompt, type:
sh HA node
Removing Route Monitors
The following sample procedure describes the steps to remove a route monitor
from the system.
To remove a route monitor
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Route Monitors tab. The Route Monitors page appears.
3. Click Configure. The Bind / Unbind Route Monitor(s) dialog box
appears.
4. In the Configured Route Monitors table, select a Route Monitor to
remove.
5. Click Remove and click OK.
To remove a route monitor using the NetScaler command line
At the NetScaler command prompt, type:
bind ns node -routeMonitor 10.102.29.30 255.255.255.0
Chapter 2 High Availability 37
HA Health Check Computation
The following table summarizes the factors examined in a health check
computation:
• State of the CIs
• State of the FISs
• State of the route monitors
The following table summarizes the health check computation:
Configuring the State of a Node
This section describes how to configure the state of a secondary node to stay as
secondary, and the primary node to stay as primary.
Forcing the Secondary Node to Stay Secondary
In an HA setup, the secondary node can be forced to stay secondary, independent
of the state of the primary node.
For example, in an existing HA setup, suppose the primary node needs to be
upgraded, and that the process will take a few seconds. During the upgrade, the
primary node may go down for a few seconds, but you do not want the secondary
system to take over; you want it to remain the secondary node, even if it detects a
failure in the primary node.
When you force the secondary node to stay secondary, the secondary system will
remain as secondary even if the primary node goes down. Also, when you force
the status of a system in an HA pair to stay secondary, it does not participate in
HA state machine transitions. The status of the node is displayed as
"STAYSECONDARY."
Forcing the node to stay secondary works on both standalone and secondary
nodes. On a standalone node, you must use this option before you can add a node
to create an HA pair. When you add the new node, the existing node will continue
to function as the primary node, and the new node will become the secondary
node.
FIS CI Route Monitor Condition
N Y N If the system has any CIs, all of those CIs must be UP.
Y Y N If the system has any FISs, all of those FISs must be
UP.
Y Y Y If the system has any route monitors configured, all
monitored routes must be present in the FIS.
38 Installation and Configuration Guide - Volume 1
Note: When you force a system to stay as secondary, the forcing process is not
propagated or synchronized. It affects only the node on which the command is
executed.
To force the secondary node to stay secondary
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Open. The Configure Dialog box appears.
4. Under High Availability Status, select STAY SECONDARY.
5. Click OK.
To force the secondary node to stay secondary using the NetScaler
command line
At the NetScaler command prompt, type:
set node -hastatus STAYSECONDARY
Forcing the Primary Node to Stay Primary
In an HA setup, you can force the primary node can be forced to stay primary
even after failover. You can enable this option can enabled either on a primary
node in an HA pair or on a standalone system.
On a standalone system, you must execute the option before you can add a node
to create an HA pair. When you add the new node, the new node becomes the
primary node. The existing node stops processing traffic and becomes the
secondary node in the HA pair.
To force the primary node to stay primary
1. In the left pane, expand System and click High Availability. The High
Availability page appears in the right pane.
2. Click the Nodes tab. The Nodes page appears.
3. Click Open. The Configure Dialog box appears.
4. Under High Availability Status, select STAY PRIMARY.
5. Click OK.
Chapter 2 High Availability 39
To force the secondary node to stay secondary using the NetScaler
command line
At the NetScaler command prompt, type:
set node -hastatus STAYPRI MARY
Troubleshooting HA Issues
This section gives troubleshooting tips for the following issues in a high
availability setup:
• Improper synchronization of VLAN configuration in high availability
systems. In HA pairs, synchronization does not work properly if only one
system has a VLAN configured. To prevent this problem, configure your
VLANs after you configure your systems as an HA pair, and be ensure that
you configure them both.
• Retrieving a lost configuration. If the primary system is unable to send
the configuration to the secondary system due to a network error, the
secondary system may not have an accurate configuration and may not
behave correctly when failover occurs. If this happens, you can retrieve the
current configuration from the configuration backup on the hard disk of the
primary system. The operating system saves the last four copies of the
ns.conf file in the /nsconfig directory as ns.conf.0, ns.conf.1, ns.conf.2, and
ns.conf.3. The ns.conf.0 file contains the current configuration.
To retrieve the current system configuration:
1. Exit from the CLI to FreeBSD by typing the following command and
pressing the Enter key:
> shell
The FreeBSD shell prompt appears, as shown below.
#
2. Copy the latest backup file to /nsconfig/ns.conf, using the following
command:
# cp ‘ls -t /nsconfig/ns.conf.? | head -1` /nsconfig/ns.conf
If you perform a configuration using the NSConfig utility, it is not propagated. If
you create a configuration using NSconfig, you must repeat the configuration
steps separately for each node in an HA pair.
40 Installation and Configuration Guide - Volume 1
CHAPTER 3
Basic Network Configuration
Overview
This chapter describes the basic networking features of the Citrix NetScaler
System (system) and provides instructions for configuring them.
Topics include:
• Configuring System-Owned IP Addresses
• Configuring Modes of Packet Forwarding
• Proxying Connections
• Configuring VMAC
• Configuring Access Control Lists
• Configuring Bridge Tables
Configuring System-Owned IP Addresses
The system communicates with other devices using a set of IP addresses. These
IP addresses enable the system to abstract servers and to multiplex connections.
The system owns the following IP addresses:
• NetScaler IP address (NSIP). The NetScaler IP address is the IP address of
the Citrix NetScaler system. The system is managed by using this IP
address.
• Subnet IP address (SNIP). Subnet IP address is the IP address that an
external host residing on another subnet uses to access a system. The
system determines the next hop for a service from the routing table and if
the IP address of the hop is within the range of SNIPs, the system uses
SNIP to source traffic to the service.
• Mapped IP address (MIP). Mapped IP addresses (MIP) are used for
external connections from the system. MIP can be considered as a default
SNIP when a SNIP cannot be used.
42 Installation and Configuration Guide - Volume 1
• Virtual IP address/Vserver IP address (VIP). The virtual server IP address
(VIP) is the IP address associated with a vserver. This IP address is optional
and can be used when you create a vserver.
• GSLB site IP address (optional). The GSLB site IP address is the IP
address associated with a GSLB site. This IP address is optional and can be
used when you create a GSLB site.
Creating the NetScaler IP Address
The NetScaler IP address (also called management IP address) is the IP address
of the system. By default, the system is managed using this IP address. The
system can only have a single NSIP. You must add this IP address when you
configure the system for the first time. If you modify this IP address, you must
reboot the system.
Note: Configuring the NetScaler IP address is mandatory.
The following example describes the procedure to set the NSIP address to
10.102.29.170, subnet mask to 255.255.255.0, and host name to NS170.
To configure the NetScaler IP address using the configuration utility
1. In the Navigation Pane, click NetScaler. The System Information page
appears in the Details Pane.
2. Click Setup Wizard. The Setup Wizard dialog box appears.
3. Click Next. The IP Addresses page appears.
4. Under System IP Address Configuration, in the IP Address, Netmask,
and Host Name text boxes, type the IP address, subnet mask, and the host
name, for example, 10.102.29.170, 255.255.255.0, and NS170.
5. Follow the instructions provided in the Setup Wizard to complete the
configuration.
To configure the NetScaler IP address using the NetScaler command line
At the NetScaler command prompt, type:
set ns conf i g - i paddr ess 10. 102. 29. 170 - net mask 255. 255. 255. 0
Configuring IP Address Types
The section describes the basic instructions that you must follow to configure
system-owned IP addresses. This section describes the procedures to configure
the following types of IP addresses:
Chapter 3 Basic Network Configuration 43
• Subnet IP address
• Mapped IP address
• Virtual server IP address
• GSLB site IP address
To create an IP address, use the parameters listed in the following table.
The following example describes the procedure to create an IP address
10.102.29.54 of type subnet IP address and subnet mask 255.255.255.0.
To configure an IP address using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Click Add. The Create IP dialog box appears.
3. In the IP Address and Netmask text boxes, type the subnet IP address and
mask, for example, 10.102.29.54 and 255.255.255.0.
4. Click Create and click Close. The subnet IP address you created appears in
the IPs page. This is shown in the following figure.
IP Page
Parameters Description
IP Address The IP address of the entity. This is a mandatory parameter.
Netmask The netmask associated with the IP.
type The type of the IP address. The valid options for this parameter
are SNIP, VIP, MIP, and GSLBsiteIP. The default value is SNIP.
The parameter does not provide an NSIP option, as NSIP must be
configured using a different procedure.
For more information about the procedure to configure NSIP, see
the section “Creating the NetScaler IP Address” on page 42.
44 Installation and Configuration Guide - Volume 1
To configure an IP address using the NetScaler command line
At the NetScaler command prompt, type:
add ns i p 10. 102. 29. 54 255. 255. 255. 0
Creating Subnet IP Addresses
You can use the subnet IP address to access a system from an external host that is
residing on another subnet. When you add a subnet IP address, a route
corresponding to the subnet IP address is added in the route table. The system
determines the next hop for a service from the routing table and if the IP address
of the hop is within the range of SNIPs, the system uses SNIP to source traffic to
the service. When many SNIPs cover the IP addresses of the next hops based on
their netmasks, the SNIPs are used in round robin manner.
It is not mandatory to specify the subnet IP address (SNIP) when you initially
configure the system. To create a subnet IP address, you must follow the
procedure described in the section, “Configuring IP Address Types” on page 42.
This IP address is used in connection management and server monitoring.
In a multiple-subnet scenario, the NSIP, mapped IP, and IP address of a server can
exist on different subnets. In such a multiple-subnet scenario, you can configure
separate IP addresses (subnet IP addresses) on the system. The source IP address
of a packet sent from the system is the SNIP.
When the system is configured with multiple subnets, you can enable the Use
SNIP (USNIP) mode to use an appropriate SNIP as the source IP for all packets
originating from the system. This eliminates the need to configure additional
routes on devices such as servers. By default, use SNIP mode is enabled. Use the
following procedure to disable use SNIP mode.
To disable use SNIP using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Clear the Use Subnet IP check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To disable use SNIP using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns mode usni p
Chapter 3 Basic Network Configuration 45
When you enable the use SNIP mode, the system uses the use SNIP as the source
IP address for outgoing packets, as shown in the following figure.
SNIP mode
The following procedure describes the steps to enable use SNIP mode and ensure
that the system uses the appropriate subnet IP address to connect to back-end
servers.
To enable use SNIP using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Select the Use Subnet IP check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To enable use SNIP using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns mode usni p
46 Installation and Configuration Guide - Volume 1
Creating Mapped IP Addresses
Mapped IP addresses (MIP) and SNIP are used for external connections from the
system. But, MIPs are used for server-side connections when appropriate SNIPs
cannot be used or when the use subnet IP address option is globally disabled on
the system. When a SNIP has a subnet that doesn’t cover the IP address of the
next hop, the MIPs are used in a round robin manner irrespective of the netmask.
You must specify at least one MIP address when you configure the system for the
first time. If the mapped IP address is the first in the subnet, the system adds a
route entry, with this IP address as the gateway to reach the subnet. You can
create or delete a mapped IP address (MIP) during runtime without rebooting the
system. To create a mapped IP address, follow the procedure described in the
section “Configuring IP Address Types” on page 42.
An MIP does not necessarily exist on the NSIP subnet. However, it is customary
to add MIPs on the NSIP subnet. If the system has only one MIP, and you are
required to change it, first create a new MIP before removing the old one.
When MIPs and SNIPs are used for many connections, there is limit on the
number of connections to the system For more information about the number of
connections, see “Appendix”.
Creating Virtual Server IP Addresses
The virtual server IP address (VIP) is the IP address associated with a vserver.
Like SNIP, it is not mandatory to specify the VIP when you initially configure the
system. You can host the same vserver on multiple systems residing on the same
broadcast domain by using ARP and ICMP attributes. To create a virtual server IP
address, follow the procedure described in the section, “Configuring IP Address
Types” on page 42.
You must create a virtual server when you configure the load balancing setup on
the system. A virtual server uses a VIP to communicate with other entities in the
load balancing setup. For more information about configuring the load balancing
setup, see the chapter on load balancing in the Installation and Configuration
Guide. To create virtual server IP addresses, use the virtual IP parameter
described in the following table.
Parameters Description
Virtual IP Use this option to set (enable or disable) the vserver attribute for
this IP entity. The valid options for this parameter are ENABLED
and DISABLED. The default value is ENABLED.
Chapter 3 Basic Network Configuration 47
Creating GSLB Site IP Addresses
When configuring a GSLB local site, you use the GSLB site IP. To create the
GSLB Site IP address, follow the procedure described in the “Creating GSLB
Site” section of the “Global Server Load Balancing” chapter. For more
information on creating a GSLB site IP address, see the “Global Server Load
Balancing” chapter.
Modifying IP Addresses
The system can be accessed and managed using services such as Tel-net, SSH,
GUI, and FTP. You can utilize these services using the NetScaler IP address
(NSIP), Mapped IP addresses (MIP), and Subnet IP addresses (SNIP). However,
you cannot disable these services for SNIP. To modify IP addresses, use the
parameters described in the following table.
Note: Telnet and FTP are disabled on the system for security reasons. To enable
them, contact the customer support. After the services are enabled, you can apply
the controls at the IP level.
Parameters Descriptions
Telnet Use this option to set (enable or disable) the state of telnet access
to this IP entity. The valid options for this parameter are
ENABLED and DISABLED. The default value is ENABLED.
FTP Use this option to set (enable or disable) the state of FTP access
to this IP entity. The valid options for this parameter are
ENABLED and DISABLED. The default value is ENABLED.
GUI Use this option to set GUI access to this IP entity. The valid
options for this parameter are ENABLED, SECUREONLY, and
DISABLED. The default value is ENABLED.
SSH Use this option to set (enable or disable) the state of SSH access
to this IP entity. The valid options for this parameter are
ENABLED and DISABLED. The default value is ENABLED.
SNMP Use this option to set (enable or disable) the state of SNMP
access to this IP entity. The valid options for this parameter are
ENABLED and DISABLED. The default value is ENABLED.
Management Access Use this option to set (enable or disable) the state of
management access to this IP entity. The valid options for this
parameter are ENABLED and DISABLED. The default value is
DISABLED.
48 Installation and Configuration Guide - Volume 1
The following table provides a summary of the interaction between management
access and specific service settings. It provides information on the state of the
service configured on the system, and its impact on the state of the service when
configured at the IP level.
By default, management access is enabled for NSIP. Therefore, you cannot
control management access for NSIP. However, you can control management
access to NSIP using ACLs. The system does not support management access to
VIPs. The following table provides an overview of the IP addresses used as
source IP addresses in outbound traffic.
The following table provides an overview of the services available on these IP
addresses.
If management access for an IP address is disabled, existing connections that use
this IP address are not terminated. However, if you close the session, you cannot
initiate a connection. To configure the system to respond to these services using a
specific IP address, you need to enable a specific management service. The
following example describes the procedure to modify an IP address 10.102.29.54.
Management access control is enabled. This procedure does not affect the
existing connections.
Management Access Telnet (State configured on
the system)
Telnet (State configured at the
IP level)
Enable Enable Enable
Enable Disable Disable
Disable Enable Disable
Disable Disable Disable
Application/ IP NSIP MIP SNIP VIP
ARP Yes Yes Yes No
Server side traffic No Yes Yes No
RNAT No Yes Yes Yes
ICMP PING Yes Yes Yes No
Application/ IP NSIP MIP SNIP VIP
SNMP Yes Yes Yes No
System Access Yes Yes Yes No
Chapter 3 Basic Network Configuration 49
To modify an IP address using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to modify, for example, 10.102.29.54.
3. Click Open. The Configure IP dialog box appears.
4. Under Application Access Control, select theEnable Management
Access control to support the below listed applications check box.
5. Click OK.
To modify an IP address using the NetScaler command line
At the NetScaler command prompt, type:
set ns i p 10. 102. 29. 54 - mgmt Access enabl ed
Controlling Address Resolution Protocol
The purpose of controlling Address Resolution Protocol (ARP) is to disable the
system from generating gratuitous ARP for the vserver, or responding to ARP
requests for the vserver when the vserver is UP.
After you add an IP address, the system sends gratuitous ARP (GARP), then
responds to ARP requests. This is true when you add any of the following IP
addresses: the NetScaler IP address, mapped IP address, virtual server IP address,
and subnet IP address. Controlling GARP is useful when you need to switch
between two vservers on two different devices. When you switch between
vservers, the system does not perform the following:
• Generate GARP
• Respond to ARP
Controlling ARP is useful when you move vservers from another traffic
management device to the system (or vice versa). Controlling ARP is also useful
in scenarios where a single vserver is configured on two systems, and a device
upstream distributes or directs traffic to these systems by using direct server
return configuration. In these scenarios, the vserver must be UP, but it should not
generate GARP or respond to ARP requests. To control GARP/ARP behavior on
a per-IP basis, use the parameters listed in the following table.
Use the following procedure to control GARP/ARP behavior.
Parameters Description
ARP Use this option to set (enable or disable) ARP and gratuitous ARP
for the entity. The valid options for this parameter are ENABLED
and DISABLED. The default value is ENABLED.
50 Installation and Configuration Guide - Volume 1
To disable ARP using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to modify, for example, 10.102.29.5.
3. Click Open. The Configure IP dialog box appears.
4. Under Options, clear theARP check box.
5. Click OK.
To disable ARP using the NetScaler command line
At the NetScaler command prompt, type:
set ns i p 10. 102. 29. 54 - ARP di sabl ed
Note: You can disable ARP/GARP and ICMP controls only for an IP address
associated with a vserver.
Controlling PING Response
To control PING response, use the ICMP parameter described in the following
table.
Use the following procedure to control the response of a system to a PING
request on a system-owned IP address.
To disable PING responses using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to modify, for example, 10.102.29.54.
3. Click Open. The Configure IP dialog box appears.
4. Under Options, clear theICMP check box.
5. Click OK.
Parameters Description
ICMP Use this option to set ICMP responses for the entity. The valid
options for this parameter are ENABLED and DISABLED. The
default value is ENABLED.
Chapter 3 Basic Network Configuration 51
To disable PING responses using the NetScaler command line
At the NetScaler command prompt, type:
set ns i p 10. 102. 29. 54 - I CMP di sabl ed
Note: You can control ARP and ICMP attributes for a VIP only. These
attributes are enabled for the other system-owned IP addresses.
Managing IP Addresses
This section describes the procedures to perform the following:
• Remove an IP Address
• Enable and Disable an IP Address
The section also provides information on when you must follow these procedures
and their impact on the network.
Removing an IP Address
You can remove the IP addresses that you created. (But, NSIP cannot be
removed.) The following table provides information on the processes you must
follow to remove the various types of IP addresses.
IP Address Type Implications
Subnet IP address (SNIP) If the IP address being removed is the last IP address in the
subnet, the associated route from the route table is deleted.
If the IP address being removed is the gateway in the
corresponding route entry, the gateway for that subnet
route is changed to another IP address (system-owned IP
address).
Mapped IP address (MIP) When SNIP exists for the system, you can remove the
MIPs. The system uses NSIP and SNIP to communicate to
back-end servers when the MIP is removed. Therefore,
you also need to enable use SNIP. For information on
enabling and disabling use SNIP, refer to the section
“Creating Subnet IP Addresses” on page 44.
Virtual Server IP address
(VIP)
To remove a VIP, you must first remove the vserver
associated with it, as the vserver uses this VIP for
communication. For more information on removing the
vserver, see the “Load Balancing” chapter of the
Installation and Configuration Guide.
GSLB-Site-IP address To remove a GSLB site IP address, you must first remove
the site associated with it, as the site uses this IP address to
communicate. For more information about removing the
site, see the “Global Server Load Balancing” chapter of the
Installation and Configuration Guide, Volume 2.
52 Installation and Configuration Guide - Volume 1
The following example describes the procedure to remove an IP address,
10.102.29.54. Follow this procedure to remove MIP, GSLB site IP address, and
SNIP. To remove VIP, first remove the vserver associated with the VIP, and then
follow this procedure.
To remove an IP address using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to remove, for example, 10.102.29.54.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove an IP address using the NetScaler command line
At the NetScaler command prompt, type:
r mns i p 10. 102. 29. 54
Enabling and Disabling an IP Address
This section describes the procedures to enable and disable the IP address. You
can only disable VIP. When the VIP is disabled, the vserver using the VIP goes
down. When the vserver is down, it does not respond to ARP, ICMP, and L4
service requests. You can enable or disable the following services of SNIP and
MIP:
• FTP
• Telnet
• SNMP
The following procedure describes the steps to disable an IP address 10.102.29.5
of type virtual IP (VIP). To create a VIP see the section “Creating Virtual Server
IP Addresses” on page 46.
To disable an IP address using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to disable, for example, 10.102.29.5.
3. Click Disable.
Chapter 3 Basic Network Configuration 53
To disable an IP address using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns i p 10. 102. 29. 5
Use the following procedure to enable the IP address.
To enable an IP address using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane.
2. Select the IP address that you want to enable, for example, 10.102.29.5.
3. Click Enable.
To enable an IP address using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns i p 10. 102. 29. 5
Verifying the Configuration
You can view the properties of the configured IP addresses such as IP address,
state, type, and mode. The details of the configured IP addresses can be used to
troubleshoot any fault in the configuration.
To view the properties of IP addresses using the configuration utility
1. In the Navigation Pane, expand Network and click IPs. The IPs page
appears in the Details Pane. The details of the available network interfaces
appear in this page.
2. Verify that the configured IP address 10.102.29.5 appears.
3. Select the IP address 10.102.29.5 and in the Details section, verify that the
parameters displayed are as configured.
To view the IP addresses using the NetScaler command line
At the NetScaler command prompt, type:
sh ns i p
Configuring Static ARP
The attributes of an IP address (such as gratuitous ARP [GARP] and PING)
control the Layer 3 behavior of the system. This section covers the control of
GARP and PING.
This section covers the parameters and procedures to perform the following:
54 Installation and Configuration Guide - Volume 1
• Adding ARP entries to the ARP table
• Removing ARP entries from the ARP table
• Viewing the ARP tables
Adding Static ARP Entries
This section describes the procedures to add entries in the ARP table. To add ARP
entries to the ARP table, use the parameters listed in the following table.
Use the following procedure to add the IP address 10.102.29.54, MAC address
00:aa:10:12:13:ef, and network interface 1/8 to an ARP table.
To create an ARP entry using the configuration utility
1. In the Navigation Pane, expand Network and click ARP Table. The ARP
Table page appears in the Details Pane.
2. Click Add. The Add ARP entry dialog box appears.
3. In the IP Address, MAC Address, and Interface Number text boxes, type
the IP address, MAC address and network interface number that you want
to add to the ARP table, for example, 10.102.29.54, 00:aa:10:12:13:ef, and
1/8.
Parameters Description
IP Address The IP address of the server.
MAC Address The MAC address of the server. Type the MAC address with
colons (:) as shown in the example below.
Interface Number The physical interface for the ARP entry. Use the show interface
command to view the valid interface names.
Chapter 3 Basic Network Configuration 55
4. Click Create and click Close. The ARP entries you added appear in the
ARP Table page. This is shown in the following figure.
ARP Table page
To create an ARP entry using the NetScaler command line
At the NetScaler command prompt, type:
add ar p - I PAddr ess 10. 102. 29. 54 - mac 00: aa: 10: 12: 13: ef - i f num1/ 8
Note: When you create a static ARP entry and if the IP address, port or MAC
address change, you need to remove or manually adjust the static entry.
Therefore, creating static ARP entries are not recommended unless necessary.
Removing Static ARP Entries
The following example describes the procedure to remove the IP address
10.102.29.54 from an ARP table.
To remove an ARP entry using the configuration utility
1. In the Navigation Pane, expand Network and click ARP Table. The ARP
Table page appears in the Details Pane.
2. Select the ARP entry that you want to remove, for example, 10.102.29.54.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove an ARP entry using the NetScaler command line
At the NetScaler command prompt, type:
r mar p 10. 102. 29. 54
56 Installation and Configuration Guide - Volume 1
Verifying the Configuration
You can view the properties of the ARP entries such as IP address, MAC address,
interface, VLAN, and origin. The details of the configured ARP entries can be
used to troubleshoot any fault in the configuration.
To view the ARP entries of IP addresses using the configuration utility
1. In the Navigation Pane, expand Network and click ARP Table. The ARP
Table page appears in the Details Pane. The details of the available ARP
entries appear in this page.
2. Verify that the configured ARP entry 10.102.29.54 appears.
3. Select the IP address 10.102.29.54 and in the Details section, verify that the
parameters displayed are as configured.
To view the ARP entries using the NetScaler command line
At the NetScaler command prompt, type:
sh ar p
Configuring Modes of Packet Forwarding
The system uses the following modes to forward the packets it receives:
• Layer 2 Mode
• Layer 3 Mode
• MAC Based Forwarding Mode
Chapter 3 Basic Network Configuration 57
Enabling and Disabling Layer 2 Mode
Layer 2 mode controls the Layer 2 forwarding (bridging) function. When this
mode is enabled, packets that are not destined for the system MAC address are
bridged or processed, as shown in the following figure.
Interaction between the Layer 2 and Layer 3 modes
By default, Layer 2 mode is disabled. When Layer 2 mode is disabled, the system
drops packets that are not destined for its MAC address. If another Layer 2 device
is installed in parallel with the system, Layer 2 mode must be disabled to prevent
bridging (Layer 2) loops. To enable the layer 2 mode, use the following
procedure.
To enable the Layer 2 mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Select the Layer 2 Mode check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To enable the Layer 2 mode using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns mode l 2
58 Installation and Configuration Guide - Volume 1
To disable the layer 2 mode, use the following procedure.
To disable the Layer 2 mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Clear the Layer 2 Mode check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To disable the Layer 2 mode using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns mode l 2
Note: The system does not support spanning tree protocol, and therefore when
L2 mode is enabled, you should not connect two interfaces on the system to the
same broadcast domain to avoid loops.
Enabling and Disabling Layer 3 Mode
Layer 3 mode controls the layer 3 forwarding function. By default, Layer 3 mode
is enabled. When you enable Layer 3 mode, the system performs a route table
lookup and forwards the packets that are not destined to any system-owned IP
addresses. When you disable Layer 3 mode, the system drops received packets if
the packets are not destined to the system-owned IP address. This is illustrated in
the figure “Interaction between the Layer 2 and Layer 3 modes” on page 57. To
enable layer 3mode, use the following procedure.
To enable Layer 3 mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Select the Layer 3 Mode (IP Forwarding) check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
Chapter 3 Basic Network Configuration 59
To enable Layer 3 mode using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns mode l 3
To disable Layer 3 mode, use the following procedure.
To disable the Layer 3 mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Clear the Layer 3 Mode (IP Forwarding) check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To disable Layer 3 mode using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns mode l 3
Enabling and Disabling MAC-Based Forwarding
Mode
You can use MAC-based forwarding to process traffic more efficiently and avoid
multiple-route/ARP lookups when forwarding packets. The system remembers
the MAC address of the source. To avoid multiple lookups, the system caches
from the ARP lookup table, the source MAC address for every connection, and
returns the data to the same MAC address.
MAC-based forwarding is useful when you use VPN devices, because the system
ensures that the traffic flowing through the VPN passes through the same VPN
device. The packets can be routed differently otherwise.
60 Installation and Configuration Guide - Volume 1
The following topology diagram illustrates the process of MAC-based
forwarding.
Working of MAC-based forwarding mode
When MAC-based forwarding is enabled, the system caches the MAC address of:
• The source (a transmitting device such as router, firewall, or VPN device)
of the inbound connection.
• The server that responds to the requests.
When a server replies through the system, the system 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. The
process bypasses the route table lookup and ARP lookup functions. However,
when the system initiates a connection, it uses the route and ARP tables for the
lookup function. When you need to use the direct server return configurations,
you must enable MAC-based forwarding. For more information about direct
server return configurations, see the “Load Balancing” chapter.To enable MAC-
based forwarding, use one of the following procedures.
To enable MAC-based forwarding using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Select the MAC Based Forwarding check box.
Chapter 3 Basic Network Configuration 61
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To enable MAC-based forwarding using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns mode mbf
Some deployment topologies may require the incoming and outgoing paths to
flow through different routers. In these situations, MAC-based forwarding breaks
this 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 make the default router of the system the
outgoing router. MBF should be disabled in the following situations:
• When you configure link load balancing because asymmetric traffic flows
are desired because of link costs.
• When a server uses network interface card (NIC) teaming without using
LACP (802.1ad Link Aggregation). To enable MAC-based forwarding in
this situation, you must use a layer 3 device between the NetScaler system
and server.
Note: MBF can be enabled when the server uses NIC teaming with
LACP because the virtual interface uses one MAC address.
• When firewall clustering is used. Firewall clustering assumes that ARP is
used to resolve the MAC address for inbound traffic. Sometimes the
inbound MAC address can be a non-clustered MAC address and should not
be used for inbound packet processing.
When MBF is disabled, the system uses L2 or L3 connectivity to forward the
responses from servers to the clients. Thus, depending on the route table, the
routers used for outgoing connection and incoming connection can be different.
In case of reverse traffic (response from the server):
• If the source and destination are on different subnets, the system uses the
route lookup to locate the source.
• If the source is on the same subnet as the destination, the system looks up
the ARP table to locate the network interface and forwards the traffic to it.
If the ARP table does not exist, the system requests the ARP entries.
To disable MAC-based forwarding, use one of the following procedures.
62 Installation and Configuration Guide - Volume 1
To disable MAC-based forwarding using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Clear the MAC Based Forwarding check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To disable MAC-based forwarding using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns mode mbf
Proxying Connections
When a client initiates a connection, the system terminates the client connection
that it receives. The system then initiates a connection to an appropriate server
and sends the packet to the server. The system does not perform this action for the
service types UDP or ANY. For more information about the service types, see the
“Load Balancing” chapter of the Installation and Configuration Guide, Volume 1.
The system can process the packet before initiating the connection with a server,
depending on the configuration of the system. To facilitate secure access of server
resources, the system changes the source and destination IP addresses of a packet
before sending the packet to the server.
Chapter 3 Basic Network Configuration 63
Selecting the Destination IP Address
Traffic arriving at the system can be bound to a vserver or to a service. The
system handles traffic to vservers and services differently. The system terminates
traffic bound to vservers and changes the vserver IP address (VIP) to the IP
address of the server before forwarding the traffic to the server. This is illustrated
in the following figure.
Proxying Connections to VIPs
Packets bound to a service are sent directly to the appropriate server, and the
system does not modify the destination IP addresses.
Selecting the Source IP Address
The mapped IP address (MIP), source IP address (SIP), and subnet IP address
(SNIP) are used as source IP addresses to establish a connection with a server.
By default, the system terminates traffic bound to vservers and configured
services. Then, it changes the source IP address of the packet to the mapped IP
address (MIP) and sends the packet to the appropriate server. This default
behavior is illustrated in the figure “Proxying Connections to VIPs” on page 63.
64 Installation and Configuration Guide - Volume 1
Configuring the Use Source IP Mode
Many e-commerce applications that use web server logging require the original
client IP addresses recorded in the web server logs. The system can forward the
source IP address of the client to the server without masking it, to ensure that the
client IP address appears in the logs. The Use Source IP mode (USIP) is used for
such applications.
When USIP mode is enabled, the system forwards each packet to the appropriate
server without changing the source IP address. This is illustrated in the following
figure.
USIP Mode
When USIP mode is enabled for HTTP protocols, the system provides limited
connection reuse, WAN latency, and denial of service (SYN) attack prevention
benefits. When USIP mode is disabled, the system uses mapped IP addresses and
subnet IP addresses to establish server-side connections. USIP mode has the
following restrictions:
• One-arm installations. You should not enable USIP mode if you install the
system in a one-arm configuration, because in a one-arm configuration the
system cannot bypass its own processing and sends responses directly to
Chapter 3 Basic Network Configuration 65
the client. If the IP address of the default gateway for a service is one of the
system-owned IP addresses, the traffic continues to flow through the
system and the response is also processed correctly.
• Concurrent connection limit. USIP mode supports up to 64,000 concurrent
connections for HTTP protocols (this applies to HTTP protocols only.) If
concurrent connections between the system and servers are expected to
exceed 64,000, you must disable USIP. To increase the number of
concurrent connections that USIP mode supports, you must contact
customer support because there is a method to override this behavior. The
concurrent connection limit does not impact services of the type TCP.
• Delay when disabling USIP. When you disable USIP mode, the existing
connections continue to use USIP mode. However, the new connections do
not use the source IP address. This delay avoids outages on long-lived
connections.
• Performance Impact on HTTP traffic. Usually, the HTTP connections on
the server side are reused for many clients. However, when USIP mode is
enabled, the connections may not be reused. Therefore, there can be a large
number of connections to the server (depending on the number of client
connections) that can impact performance. Further, if there are idle server
connections, the client connections may be blocked because the services are
serving the idle connections. Therefore, you need to set the limits on the
number of connection with care on services. We suggest you to configure
the HTTP server time-out on the service to a lower value than the default so
that idle client connections are cleared quickly on the server side. For more
information about setting an idle time-out value, see Load Balancing
chapter in Citrix NetScaler Installation and Configuration Guide,
Volume 1. In addition, you must configure persistence (any persistence type
such as source IP persistence) with USIP enabled to ensure that the same
server is selected and the client connection is reused. The service of type
TCP handles the traffic on one-to-one basis and therefore, the USIP option
doesn’t impact TCP services.
Note: It is recommended not to use Surge Protection (SP) with USIP.
You can either configure USIP mode for all services, or for a specific service. By
default, USIP mode is disabled. To enable USIP mode globally, use the following
procedure.
To enable Use Source IP mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
66 Installation and Configuration Guide - Volume 1
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Select the Use Source IP check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To enable USIP using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns mode USI P
To disable USIP mode, use the following procedure.
To disable Use Source IP mode using the configuration utility
1. In the Navigation Pane, expand System and click Settings. The Settings
page appears in the Details Pane.
2. In the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Clear the Use Source IP check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To disable USIP using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns mode USI P
Note: For services created after you enable USIP mode globally, the system
forwards the packet from the client to the server without changing the source IP
address unless you specifically disable the mode on individual services. When
you configure USIP mode for individual services, this setting takes precedence
over USIP enabled globally. If you enable USIP mode on individual services,
enabling or disabling USIP mode globally does not affect those settings -- the
global settings are ignored for those services. For more information about
configuring USIP mode, see the “Load Balancing” chapter of the Installation and
Configuration Guide, Volume 1. A new service inherits the global USIP settings.
When you configure the service setting on an individual service, the service
setting overrides the global setting.
Chapter 3 Basic Network Configuration 67
Configuring Network Interfaces
Network interfaces in the system are numbered in <slot>/<port>notation. You
can configure network interfaces in the following ways:
• Modify network interface characteristics such as speed, duplex mode, flow
control, monitoring, and so on.
• Enable or disable a network interface. The network interfaces are enabled
by default.
• Reset the specified network interface.
• Clear the statistics of the specified network interface. This does not reset
the network interface.
• View the configured settings of the network interfaces. If the network
interface number appears in the Interfaces page, then the information
shown applies only to that network interface. The information on the
loopback network interface appears in the Interfaces page.
To modify the network interfaces, use the parameters listed in the following table.
Parameters Description
ID The number of the network interface.
Speed The network interface number specifies the Ethernet
speed for the network interface. The default setting is
AUTO. This means that the system attempts to auto-
negotiate or auto-sense the line speed on this network
interface when the network interface is invoked. Setting
a speed other than AUTO on a network interface
requires the device at the other end of the link to be
configured identically. Mismatching speed and/or
duplex configurations on two ends leads to link errors,
packet losses, and so on. You must avoid mismatching
of the speed. Some network interfaces do not support
certain speeds. If you try to set a speed on a network
interface that does not support it, it is reported as an
error. The valid options for this parameter are AUTO,
10, 100, and 1000.
Duplex The duplex mode for the network interface. The default
setting is AUTO. This implies that the system attempts
to auto-negotiate for the duplex mode on this network
interface when the network interface is invoked. You
can also specify half and full duplex modes. It is
recommended to leave the speed as AUTO. If you force
duplex mode, you must manually configure duplex
mode and identical speed on both sides of the link. The
valid options for this parameter are AUTO, HALF, and
FULL.
68 Installation and Configuration Guide - Volume 1
Flow Control The required 802.3x flow control for the network
interface. You can specify OFF (the default), RX, TX,
RXTX, and ON (ON means “forced RXTX”). OFF is
available only for Fast Ethernet network interfaces. The
802.3x specifications do not define the flow control for
speeds 10MB and 100 MB. Gigabit Ethernet network
interfaces support flow control for these three possible
speeds. Real flow control status depends on the auto-
negotiation results. When flow control is ON, you must
use auto-negotiation so that the peer can negotiate the
flow control. You must then force the two-way flow
control for this network interface. Link parameter
mismatches must be avoided and checked, because they
can cause the system to drop packets, or the link may
not be accessible, and so on.
Auto Negotiate The state of auto negotiation for the specified network
interface. The valid options for this parameter are
DISABLED and ENABLED
HA Monitor The state of high availability configuration. This
parameter specifies the network interfaces that are
monitored for failing events. The valid options for this
parameter are ON and OFF. By default, this is set to ON
for all network interfaces. When ON in an HA
configuration, failover occurs when a network interface
fails. If a network interface is not being used, or if
failover is not required, select OFF. Also, if the network
interface is not used in the configuration, then you must
disable it.
Trunk The option to select whether this port is or is not a trunk
port for the network interface. The valid options for this
parameter are ON and OFF. By default, this is set to
OFF for all network interfaces. When ON, the traffic is
tagged for the VLANs bound to this network interface
including the native VLAN. If you require 802.1q
behavior with backward compatibility, you must set this
parameter to OFF.
LACP Mode LACP mode. The valid options for this parameter are
DISABLED, ACTIVE, and PASSIVE. The default
value is DISABLED
LACP Key LACP key. The minimum value is 1 and the maximum
value is 4
LACP Priority LACP port priority. The default value is 32768. The
minimum value is 1 and the maximum value is 65535.
LACP Time-out LACP timeout. The valid options for this parameter are
LONG and SHORT, and the default value is
NSA_LACP_TIMEOUT_LONG.
Alias The alias name for the network interface.
Parameters Description
Chapter 3 Basic Network Configuration 69
The following example describes the procedure to set the duplex of a network
interface 1/8 to full duplex.
To modify a network interface using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Select the network interface that you want to modify, for example, 1/8.
3. Click Open. The Modify Interface dialog box appears.
4. In the Duplex drop-down list, select FULL.
5. Click OK.
To modify a network interface using the NetScaler command line
At the NetScaler command prompt, type:
set i nt er f ace 1/ 8 - dupl ex f ul l
Note: The network interface configuration is neither synchronized nor
propagated, therefore you must perform the configuration on each unit in an HA
pair independently.
Managing Network Interfaces
This section describes the following procedures: removing the statistics of a
network interface, and enabling and disabling network interfaces. It also provides
information about when you must perform these tasks, and how they impact the
network.
Throughput Minimum required throughput for the network interface.
If you provide a throughput value greater than the actual
throughput value, the network interface fails.
Parameters Description
70 Installation and Configuration Guide - Volume 1
Enabling and Disabling Network Interfaces
This section describes the procedures to enable and disable network interfaces.
You must disable a network interface that is not connected to the network. If you
disable a network interface that is connected to the network, it cannot send or
receive packets. Disabling a network interface that is connected to the network in
a high availability setup can cause failover. For more information about high
availability, see the “High Availability” chapter of the Installation and
Configuration Guide. The following example describes the procedure to disable
the network interface 1/8.
To disable a network interface using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Select the network interface that you want to disable, for example, 1/8.
3. Click Disable.
To disable a network interface using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e i nt er f ace 1/ 8
The following example describes the procedure to enable the network interface 1/
8. By default, the network interfaces are enabled.
To enable a network interface using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Select the network interface that you want to enable, for example, 1/8.
3. Click Enable.
To enable a network interface using the NetScaler command line
At the NetScaler command prompt, type:
enabl e i nt er f ace 1/ 8
Resetting Network Interfaces
This section describes the procedure to reset network interfaces. network
interface settings are used to control parameters such as duplex, speed, and so on.
To renegotiate the parameters of a network interface, you must reset it. The
following example describes the procedure to reset the network interface 1/8.
Chapter 3 Basic Network Configuration 71
To reset a network interface
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. In the Interfaces page, select the network interface that must be reset. For
example, select 1/8.
3. Click Reset Interface.
To reset a network interface using the NetScaler command line
At the NetScaler command prompt, type:
r eset i nt er f ace 1/ 8
Removing the Statistics of a Network Interface
This section describes the procedure to remove the statistics of a network
interface. You can use network interface statistics to monitor parameters such as
packet sent and packet received. You can clear the statistics of a network interface
to monitor its statistics from the time the statistics are cleared. The following
example describes the procedure to clear the statistics of the network interface 1/
8.
To clear a network interface statistics using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Select the network interface whose statistics you want to clear, for example,
1/8.
3. Click Clear Statistics.
To clear a network interface statistics using the NetScaler command line
At the NetScaler command prompt, type:
cl ear i nt er f ace 1/ 8
Verifying the Configuration
This section describes how to view the configured network interfaces and the
statistics of the network interfaces. Viewing the configuration can help you
troubleshoot problem in the configuration.
72 Installation and Configuration Guide - Volume 1
Viewing Network Interfaces
You can view the properties of the configured network interfaces, such as
description, MAC address, uptime, and VMAC. Viewing the details of the
network interfaces help you troubleshoot configuration errors. The following
procedure describes the steps to view the properties of the network interfaces.
To view the network interfaces using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane. The details of the available
network interfaces appear in this page.
2. Verify that the configured interface 1/8 appears.
3. Select the interface 1/8 and in the Details section, verify that the parameters
displayed are as configured.
To view the properties of the network interfaces using the NetScaler
command line
At the NetScaler command prompt, type:
show i nt er f ace
Viewing the Statistics of a Network Interface
You can view the statistics such as Packet Statistics, Throughput Statistics, LACP
Statistics and Error Statistics of configured network interfaces. You can use the
statistics to check the health of the network interface. The following example
describes the steps to view the statistics of network interface 1/8.
To view the statistics of an Interface using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Select the network interface whose statistics you want to view, for example,
1/8.
3. Click Statistics. The Interface Statistics dialog box appears. This page
displays the following information about the selected network interface:
Packet Statistics, Throughput Statistics, LACP Statistics and Error
Statistics.
To view the statistics of the network interfaces using the NetScaler
command line
At the NetScaler command prompt, type:
st at i nt er f ace 1/ 8
Chapter 3 Basic Network Configuration 73
Configuring Link Aggregation
Link aggregation combines data coming from multiple ports into a single high-
speed link. Configuring the link aggregate channel increases the capacity and
availability of the communication channel between the system and other
connected devices. An aggregated link is also referred to as a “channel.” You can
configure the channels manually or using LACP. You must follow the procedures
described in the section to configure the channels.
Configuring Link Aggregation Manually
This section describes the procedures to configure a link aggregate channel
manually. Link aggregate channels increase the capacity and availability of the
communication channel. You must follow the procedures described in this section
to configure the link aggregate channels.
Topics include:
• Creating channels
• Binding a channel to a network interface
• Modifying channels
• Unbinding a channel from a network interface
• Removing channels
• Enabling and disabling channels
Creating Link Aggregate Channels
This section describes the procedure and parameters to create a link aggregate
channel. The state of the channel that you create is DOWN because the active
network interfaces are not bound to a channel. To create the channel, use the
channel ID parameter described in the following table.
Note: Adding a channel without specifying the network interface number
parameter can cause a failover.
The following example describes the procedure to create the channel with ID
LA/1.
Parameter Description
Channel ID LA channel name (in form LA/*)
74 Installation and Configuration Guide - Volume 1
To create a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Click Add. The Add Channel dialog box appears.
3. In the Channel ID drop-down list, select the link aggregate ID that you
want to add, for example, LA/1.
4. Click Create and click Close. The link aggregate channel you added
appears in the Channel page. This is shown in the following figure.
Link Aggregate Channels Page
To create a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
add channel LA/ 1 - i f num1/ 8
Binding a Network Interface to a Link Aggregate Channel
This section describes the procedure to bind a network interface to a link
aggregate channel. When a network interface is bound to a channel, the channel
parameters have precedence over the network interface parameters. (That is, the
network interface parameters are ignored.) a network interface can be bound only
to one channel.
Chapter 3 Basic Network Configuration 75
When a network interface is bound to a channel, it drops the VLAN
configuration. When network interfaces are bound to a channel manually or using
LACP, they are removed from the VLANs that they originally belonged to, and
are added to the default VLAN. However, you can bind the channel back to the
old VLAN, or to a new one. For example, if you bind the network interfaces 1/2
and 1/3 to a VLAN with ID 2, and then bind them to a channel LA/1, the network
interfaces are moved to the default VLAN, and you can bind them to VLAN 2.
The following example describes the procedure to bind the network interface 1/8
to a VLAN with ID 2. The following example describes the procedure to bind a
network interface 1/8 to the channel LA/1.
To bind a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel that you want to bind to a network interface, for
example, LA/1.
3. Click Open. The Modify Channel dialog box appears.
4. In the Available Interface list box, select the network interface, for
example, 1/8.
5. Click Add. The network interface you selected appears in the Configured
list.
6. Click OK.
To bind a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
bi nd channel LA/ 1 - i f num1/ 8
Modifying Link Aggregate Channels
This section describes the procedure and parameters to modify link aggregate
channels. To modify a link aggregate channel, use the parameters described in the
following table.
Parameters Descriptions
State The initial state for the channel. The valid options for this
parameter are ENABLED and DISABLED. The default value is
ENABLED.
Mode The initial mode for the channel. The valid options for this
parameter are MANUAL, AUTO, and DESIRED.
Connection
Distribution
The “connection” distribution mode for the channel. The valid
options for this parameter are DISABLED and ENABLED.
76 Installation and Configuration Guide - Volume 1
The following example describes the procedure to set the speed of the channel
LA/1 to 100.
To modify a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel that you want to modify, for example, LA/1.
3. Click Open. The Modify Channel dialog box appears.
4. Click the Settings tab and in the Speed drop-down list box, select the speed
that you want to configure, for example, 100.
5. Click OK.
To modify a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
set channel LA/ 1 - speed 100
Unbinding a Network Interface froma Link Aggregate Channel
This section describes the procedure to unbind a Link Aggregate Channel. The
following example describes the procedure to unbind the network interface 1/8
from the channel LA/1.
MAC Distribution The “MAC” distribution mode for the channel. The valid options
for this parameter are SOURCE, DESTINATION, and BOTH.
Speed The speed for the channel. The valid options for this parameter
are AUTO, 10, 100, and 1000.
Flow Control Flow control for the channel. The valid options for this parameter
are OFF, RX, TX, and RXTX.
HA Monitor The HA-monitoring control for the channel. The valid options for
this parameter are ON and OFF.
Trunk The option to select whether this port is a trunk port or not. By
default, this is set to OFF for all interfaces. When ON, the port
membership in all VLANs is tagged. If 802.1q behavior with
native VLAN is required, use the OFF setting for this variable.
The valid options for this parameter are ON and OFF. The default
value is OFF.
Alias The alias name for the channel.
Throughput Specify the minimum required throughput for the network
interface.
Parameters Descriptions
Chapter 3 Basic Network Configuration 77
To unbind a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel from which you want to unbind a network interface, for
example, LA/1.
3. Click Open. The Modify Channel dialog box appears.
4. In the Configured list box, select the network interface. For example,
select 1/8.
5. Click Remove. The channel that you have selected appears in the Available
Interface list.
6. Click OK.
To unbind a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
unbi nd channel LA/ 1 1/ 8
Removing Link Aggregate Channels
This section describes the procedure to remove a Link Aggregate Channel. When
a channel is removed, the network interfaces bound to it induce network loops
that decrease network performance. You must first disable a network interface
and then remove a channel. The following example describes the procedure to
remove the channel, LA/1.
To remove a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel that you want to remove, for example, LA/1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
r mchannel LA/ 1
78 Installation and Configuration Guide - Volume 1
Enabling and Disabling Link Aggregate Channels
This section describes the procedures to enable or disable link aggregate
channels. To avoid network loops, you must first disable a network interface
before disabling a channel. The following example describes the procedure to
disable the channel, LA/1.
To disable a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel that you want to disable, for example, LA/1.
3. Click Disable.
To disable a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e i nt er f ace LA/ 1
The following example describes the procedure to enable the channel, LA/1.
To enable a link aggregate channel using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane.
2. Select the channel that you want to enable, for example, LA/1.
3. Click Enable.
To enable a link aggregate channel using the NetScaler command line
At the NetScaler command prompt, type:
enabl e i nt er f ace LA/ 1
Configuring the Link Aggregate Channel Protocol
The Link Aggregation Control Protocol (LACP) allows network devices to
exchange link aggregation information. To perform this function, network
devices configured to use the LACP protocol exchange LACP Data Units
(LACPDU). To configure the link aggregate channel protocol, use the system
priority parameter described in the following table. This parameter sets the
priority of the system globally.
Parameters Description
System priority The possible values are 1 to 65535. The default value is
32768.
Chapter 3 Basic Network Configuration 79
When you configure the network interface, you can configure the following
LACP parameters
• LACP mode
• LACP time-out
• Port key
• Port priority
Note: LACP configurations are neither propagated nor synchronized.
By default, LACP is disabled on all network interfaces. You cannot use LACP to
modify channels that you created manually. Thus, you cannot enable LACP on
member network interfaces of a channel that you created manually. If LACP
creates a channel dynamically, you cannot create, bind, unbind, or remove
operations on that channel. However, you can configure parameters such as
distribution mode, etc. LACP dynamically creates a channel that is deleted when
LACP is disabled on all its member network interfaces. To enable LACP on a
network interface, you can use the procedure to modify the network interface as
described in the section “Managing Network Interfaces” on page 69.
When you enable LACP on a network interface, the system creates channels
dynamically. The system currently supports two channels, LA/1 and LA/2, based
on the LACP Key values. Therefore, if you enable LACP on a network interface
and set the LACP Key to 1, the network interface is automatically bound to the
channel LA/1.
Note: While enabling LACP on a network interface, you must simultaneously
specify the LACP Key.
The following example describes the procedure to configure the link aggregate
channel protocol with a system priority of 12.
To configure a link aggregate channel protocol using the configuration
utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Click Set LACP. The Configure LACP dialog box appears.
3. In the System Priority text box, type the priority you want to configure, for
example, 12.
4. Click OK.
80 Installation and Configuration Guide - Volume 1
To configure a link aggregate channel protocol using the NetScaler
command line
At the NetScaler command prompt, type:
set l acp - syspr i or i t y 12
Verifying the Configuration
This section describes how you can verify the Link Aggregate Channel that you
have configured. This is useful for troubleshooting.
Viewing the Link Aggregate Channel
You can view the properties such as channel ID, description, uptime, and VRID
of the configured channels. The following example describes the steps to view the
properties of the configured channels. The LACP settings appear as a part of the
output, and one channel is created with four network interfaces bound to it.
To view the link aggregate channels using the configuration utility
1. In the Navigation Pane, expand Network and click Channels. The
Channels page appears in the Details Pane. The details of the available
channels appear in this page.
2. Verify that the configured channel LA/1 appears.
3. Select the channel LA/1 and in the Details section, verify that the
parameters displayed are as configured.
To view link aggregate channels using the NetScaler command line
At the NetScaler command prompt, type:
show channel s
Viewing the Link Aggregate Channel Protocol
You can view the properties such as system priority and system MAC of the
configured channels. The details of the channels can be used to troubleshoot any
fault in the configuration. The following example describes the steps to view the
properties of the configured channels.
To view the link aggregate channel protocol using the configuration utility
1. In the Navigation Pane, expand Network and click Interfaces. The
Interfaces page appears in the Details Pane.
2. Click View LACP Details. The View LACP Details dialog box appears.
3. Click Close.
Chapter 3 Basic Network Configuration 81
To view the link aggregate channel protocol using the NetScaler command
line
At the NetScaler command prompt, type:
show l acp
Configuring VLANs
The system supports (Layer 2) port and IEEE802.1Q tagged VLANs. VLAN
configurations are useful when you need to restrict traffic to certain groups of
stations. You can configure a network interface as a part of multiple VLANs
using IEEE 802.1q tagging.
You can configure VLANs and bind them to IP subnets. The system then
performs IP forwarding between these VLANs (if it is configured as the default
router for the hosts on these subnets).
The system supports the following types of VLANs.
• Port-Based VLANs
• Default VLAN
• Tagged VLAN
Port-Based VLANs
The membership of a port-based VLAN is defined by a set of network interfaces
that share a common exclusive Layer 2 broadcast domain. You can configure
multiple port-based VLANs. By default, all network interfaces on the system are
members of VLAN 1.
If you apply 802.1q tagging to the port, the network interface belongs to a port-
based VLAN. Layer 2 traffic is bridged within a port-based VLAN, and Layer 2
broadcasts are sent to all members of the VLAN if Layer 2 mode is enabled.
When you add an untagged network interface as a member of a new VLAN, it is
removed from its current VLAN.
Default VLAN
By default, the network interfaces on the system are included in a single, port-
based VLAN as untagged network interfaces. This VLAN is the default VLAN,
and has a VID of 1. This VLAN exists permanently. This VLAN cannot be
deleted, and its VID cannot be changed.
When you add a network interface to a VLAN as an untagged member, the
network interface is automatically removed from the default VLAN and added to
this VLAN. If you unbind a network interface from its current port-based VLAN,
it is added to the default VLAN again.
Tagged VLAN support for the NetScaler IP Subnet
82 Installation and Configuration Guide - Volume 1
802.1q tagging (defined in the IEEE 802.1q standard) allows a networking device
(such as the system) to add information to a frame at Layer 2 to identify the
VLAN membership of the frame. Tagging allows network environments to have
VLANs that span multiple devices. A device that receives the packet reads the tag
and recognizes the VLAN to which the frame belongs. Some network devices do
not support receiving both tagged and untagged packets on the same network
interface, in particular force-10 switches.In such cases, you need to contact
customer support for assistance.
The network interface can be a tagged or untagged member of a VLAN. Each
network interface is an untagged member of one VLAN only (its native VLAN).
This network interface transmits the frames for the native VLAN as untagged
frames. a network interface can be a part of more than one VLAN if the VLAN is
added as a tagged member.
When you configure tagging, be sure to match the configuration of the VLAN on
both ends of the link. Thus, the port to which the system connects must be
configured with the VLAN as that of the network interface.
You can use the configuration utility to define a tagged VLAN (nsvlan) that can
have any ports bound as tagged members of the VLAN. Configuring this VLAN
requires a reboot of the system, and therefore must be done during initial network
configuration.
Note: This VLAN configuration is neither synchronized nor propagated,
therefore you must perform the configuration on each unit in an HA pair
independently. The best practise is to set the VLAN ID for an NSIP to 1.
Applying Rules to Classify Frames
Two types of rules are used to classify frames
• Ingress rules
• Egress rules
Ingress rules
Ingress rules classify each frame as belonging only to a single VLAN. When a
frame is received on a network interface, the following rules are applied to
classify the frame:
• If the frame is untagged, or has a tag value equal to 0, the VID of the frame
is set to the port VID (PVID) of the receiving interface, which is classified
as belonging to the native VLAN. (PVIDs are defined in the IEEE 802.1q
standard.)
• If the frame has a tag value equal to FFF, the frame is dropped.
Chapter 3 Basic Network Configuration 83
• The VID of the frame specifies a member of the VLAN. If the receiving
network interface is not this member, the frame is dropped. For example, if
a packet is sent from a subnet associated with VLAN ID 12 to a subnet
associated with VLAN ID 10, the packet is dropped. If an untagged packet
with VID 9 is sent from the subnet associated with VLAN ID 10 to a
network interface PVID 9, the packet is dropped.
Egress Rules
The following egress rules are applied:
• For the VID of the frame, frames are discarded if the transmission network
interface is not a member of the VLAN.
• During the learning process (per the IEEE 802.1q standard), the Src MAC
and VID are used to update the bridge lookup table of the system.
• A frame is discarded if the VLAN does not have any members. You can
define members that are the network interfaces configured in the VLAN.
Forwarding Packets on the System
The forwarding process on the system is similar to that on any standard switch.
However, the system performs forwarding only when Layer 2 mode is on. The
key features of the forwarding process are:
• Topology restrictions are enforced. Enforcement involves selecting each
network interface in the VLAN as a transmission port, based on the state of
the network interface, bridging restrictions (do not forward on the receiving
network interface), MTU restrictions, and so on.
• Frames are filtered based on the bridge table lookup (the FDB of the
system). The bridge table lookup is based on the destination MAC and the
VID. Packets addressed to the MAC address of the system are processed at
the upper layers.
• All broadcast and multicast frames are forwarded to each network interface
that is a member of the VLAN, but forwarding occurs only if L2 mode is
enabled. If L2 mode is disabled, the broadcast and multicast packets are
dropped. This is also true for MAC addresses that are not currently in the
bridging table.
• A VLAN entry has a list of member network interfaces that are part of its
untagged member set. When forwarding frames to these network interfaces,
a tag is not inserted in the frame.
• If the network interface is a tagged member of this VLAN, the tag is
inserted in the frame when forwarding frames.
84 Installation and Configuration Guide - Volume 1
When a user sends any broadcast or multicast packets without the VLAN being
identified (that is, during DAD for NSIP, ND6 for the next hop of the route), the
packet is sent out on all the network interfaces with appropriate tagging. ND6
usually identifies a VLAN, and a data packet is sent on this VLAN only. Port-
based VLANs are common for IPv4 and IPv6. For IPv6, prefix-based VLANs are
not currently supported.
Creating a VLAN
You can implement VLANs in the following environments:
• Single subnet
• Multiple subnets
• Single LAN
• VLANs (no tagging)
• VLANs (802.1q tagging)
When you create VLANs that have only untagged network interfaces as their
members, the total number of possible VLANs is limited to the number of
network interfaces available in the system. If more IP subnets are required with a
VLAN configuration, then 802.1q tagging must be used. To create a VLAN, use
the VLAN ID parameter described in the following table.
To create a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Click Add. The Create VLAN dialog box appears.
3. In the VLAN Id text box, type the ID of the VLAN, for example, 2.
Parameter Description
VLAN Identifiers (VIDs) Each VLAN has a VLAN identifier (VID). A VID is an
integer from 1 to 4094 that uniquely identifies the
VLAN to which a particular frame belongs. A
maximum of 4094 VLANs are supported on the system.
VID 1 is reserved for the default VLAN.
Chapter 3 Basic Network Configuration 85
4. Click Create and click Close. The VLAN you added appears in the
VLANs page. This is shown in the following figure.
VLANs Page
To create a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
add vl an 2
Configuring VLANs in an HA Setup
VLAN configuration requires the systems in a high-availability setup to have the
same hardware configuration. They must also be mirror images.
This is required when the configuration is synchronized between the systems, and
the result is identical actions on all the systems. For example, adding network
interface 0/1 to VLAN2 adds this network interface to VLAN 2 on all the
participating systems in the high-availability setup.
Note: If you use network interface-specific commands in an HA setup, the
configurations you perform are not propagated to the other system. You must
perform these commands on each system in an HA pair, to ensure that the
configuration of the two systems in the HA pair remains synchronized.
Configuring VLANs on a Single Subnet
You must first ensure that Layer 2 Mode is enabled. In this setup:
1. The default router for the system and the servers is Router 1.
2. The Layer 2 mode of the system must be enabled for the system to have
direct access to the servers. For more information about the procedure to
disable Layer 2 mode, see “Enabling and Disabling Layer 2 Mode” on page
57.
86 Installation and Configuration Guide - Volume 1
3. For this subnet, a virtual server can be configured for load balancing in the
system.
The following figure shows the single subnet environment
VLAN on a Single Subnet
To configure a VLAN on a single subnet, follow the procedure described in
“Creating a VLAN” on page 84. VLAN configuration parameters are not
required, because the network interfaces are members of this VLAN.
Chapter 3 Basic Network Configuration 87
Configuring VLANs on Multiple Subnets
To configure a single VLAN across multiple subnets, you must add a VIP for the
VLAN and configure the routing appropriately. The following figure shows a
single VLAN configured across multiple subnets.
Multiple Subnets in a Single VLAN
To configure a single VLAN across multiple subnets
1. Log on to the Configuration Utility.
2. Disable Layer 2 mode (OFF). For more information about the procedure to
disable Layer 2 mode, see “Enabling and Disabling Layer 2 Mode” on page
57.
3. Add a VIP. For more information about the procedure to add a VIP, see
“Creating Virtual Server IP Addresses” on page 46.
4. Configure RNAT ID. For more information about the procedure to
configure the RNAT ID, see the “Advanced Network Configuration”
chapter of the Installation and Configuration guide, Volume 2.
Note: The system only supports using the Creating Route procedure to add
multiple IP subnets in single-subnet VLAN configurations.
88 Installation and Configuration Guide - Volume 1
Configuring Multiple Untagged VLANS across Multiple Subnets
In environments with multiple untagged VLANs across multiple subnets, a
VLAN is configured with an IP subnet. a network interface is bound to one
VLAN only. The following figure shows this configuration.
Multiple Subnets with VLANs - No Tagging
To configure untagged VLANs across multiple subnets
1. Log on to the Configuration Utility.
2. Add VLAN 2. For more information about the procedure to create a
VLAN, see “Creating a VLAN” on page 84.
3. Bind the 1/ 2 network interface of the system to VLAN 2 as an untagged
network interface. For more information about the procedure to bind a
network interface to a VLAN, see “Binding a Network Interface to a
VLAN” on page 90.
4. Bind the IP address and netmask to VLAN 2. For more information about
the procedure to bind an IP address to a VLAN, see “Binding an IP Address
to a VLAN” on page 90.
Chapter 3 Basic Network Configuration 89
Configuring Multiple VLANs with 802.1q Tagging
In this environment, each VLAN is configured with a different IP subnet. Each
network interface is in one VLAN. One of the VLANs is set up as tagged. The
following figure shows this configuration.
Multiple VLANs with IEEE 802.1q Tagging
To configure multiple VLANs with 802.1q tagging
1. Log on to the Configuration Utility.
2. Add VLAN 2. For more information about the procedure to create a
VLAN, see “Creating a VLAN” on page 84.
3. Bind the 1/ 2 network interface of the system to VLAN 2 as an untagged
network interface. For more information about the procedure to bind a
network interface to a VLAN, see “Binding a Network Interface to a
VLAN” on page 90.
4. Bind the IP address and netmask to VLAN 2. For more information about
the procedure to bind an IP address to a VLAN, see “Binding an IP Address
to a VLAN” on page 90.
5. Add VLAN 3. For more information about the procedure to create a
VLAN, see “Creating a VLAN” on page 84.
90 Installation and Configuration Guide - Volume 1
6. Bind the 1/ 2 network interface of the system to VLAN 3 as a tagged
network interface. For more information about the procedure to bind a
network interface to a VLAN, see “Binding a Network Interface to a
VLAN” on page 90. For more information about the procedure to bind a
tagged network interface, see “Modifying a VLAN” on page 91.
7. Bind the IP address and netmask to VLAN 3. For more information about
the procedure to bind an IP address to a VLAN, see “Binding an IP Address
to a VLAN” on page 90.
Binding a Network Interface to a VLAN
When you bind a network interface to a VLAN, the network interface is moved
from the default VLAN. You can bind the network interfaces as tagged members
to the VLANs, if the network interfaces need to be a part of more than one
VLAN.
To bind a network interface to a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN to which you want to bind the network interface, for
example, 2.
3. Click Open. The Modify VLAN dialog box appears.
4. Under Interfaces, select the Active check box corresponding to the
interface that you want to bind to the VLAN, for example, 1/8.
5. Click OK.
To bind an interface to a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
bi nd vl an 2 - i f num1/ 8
Binding an IP Address to a VLAN
You can configure the system to forward traffic between VLANs at Layer 3. A
VLAN is associated with a single IP subnet. The hosts in a VLAN that belong to
a single subnet use the same subnet mask, and one or more default gateways
connected to that subnet.
Configuring Layer 3 for a VLAN is optional. It is used for IP forwarding (inter-
VLAN routing). Each VLAN has a unique IP address and netmask that define an
IP subnet for the VLAN. In an HA configuration, this IP address is shared with
the other systems.
The system forwards packets between configured IP subnets (VLANs).
Chapter 3 Basic Network Configuration 91
Note: When you configure the system, you must not create overlapping IP
subnets, as doing so impedes Layer 3 functionality.
Each VLAN is a unique Layer 2 broadcast domain. Two VLANs, each bound to
separate IP subnets, cannot be combined into a single broadcast domain.
Forwarding traffic between two VLANs requires a Layer 3 forwarding (routing)
device, such as the system.
For a VLAN, a route added in the route table defines the IP subnet for the VLAN.
A route is added for the gateway is a SNIP for the gateway. When you bind an IP
address to a VLAN, the system need not use the bound IP address to proxy the
traffic to the VLAN and can select SNIP or MIP.
Note: You must assign a netmask to the VIP address and then bind it to a
VLAN, or the binding procedure fails. To assign a netmask to a VIP use one of
procedures described in the “Configuring IP Address Types” section.
The following example describes the procedure to bind the IP address
10.102.29.54 to a VLAN with ID 2.
To bind an IP address to a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN for which you want to bind the IP address, for example, 2.
3. Click Open. The Modify VLAN dialog box appears.
4. Under IPs, select the Active check box corresponding to the IP address that
you want to bind to the VLAN, for example, 10.102.29.54.
5. Click OK.
To bind an IP address to a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
bi nd vl an 2 - I PAddr ess 10. 102. 29. 54 255. 255. 255. 0
Modifying a VLAN
This section describes the procedure to modify a VLAN. The following example
describes the procedure to configure a tagged network interface.
92 Installation and Configuration Guide - Volume 1
To modify a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN that you want to modify, for example, 2.
3. Click Open. The Modify VLAN dialog box appears.
4. Under Interfaces, select the Tagged check box corresponding to the
network interface that must be tagged, for example, 1/8.
5. Click OK.
To make a network interface a tagged member of a VLAN using the NetScaler
command line, you must first unbind the network interface from the VLAN, then
bind it as a tagged member as shown in the following procedure. For more
information about unbinding a network interface from a VLAN, see “Unbinding a
Network Interface from a VLAN” on page 92.
To modify a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
unbi nd vl an 2 - i f num1/ 8
bi nd vl an 2 - i f num1/ 8 - t agged
Managing a VLAN
This section describes the procedures to remove a VLAN, and to unbind a
network interface from a VLAN.
Unbinding a Network Interface froma VLAN
The following example describes the procedure to unbind the network interface
1/8 from a VLAN with ID 2.
To unbind a network interface from a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN from which you want to unbind the network interface, for
example, 2.
3. Click Open. The Modify VLAN dialog box appears.
4. Under Interfaces, clear the Active check box corresponding to the
interface that you want to unbind from the VLAN, for example, 1/8.
5. Click OK.
Chapter 3 Basic Network Configuration 93
To unbind an interface to a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
unbi nd vl an 2 - i f num1/ 8
Unbinding an IP Address froma VLAN
The following example describes the procedure to unbind the IP address
10.102.29.54 from a VLAN with ID 2.
To unbind an IP address from a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN from which you want to unbind the IP address, for
example, 2.
3. Click Open. The Modify VLAN dialog box appears.
4. Under IPs, clear the Active check box corresponding to the IP address that
you want to unbind from the VLAN, for example, 10.102.29.54.
5. Click OK.
To unbind an IP address to a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
unbi nd vl an 2 - I PAddr ess 10. 102. 29. 54 255. 255. 255. 0
Removing a VLAN
This section describes the procedure to remove a VLAN. When you remove a
VLAN, the network interfaces are bound to the default VLAN.
To remove a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN that you want to remove, for example, 2.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
r mvl an 2
94 Installation and Configuration Guide - Volume 1
Verifying the Configuration
This section describes the procedure to verify the VLAN that you have
configured. This is useful for troubleshooting.
Viewing VLANs
You can view the properties such as VLAN ID, members, and tagging of the
configured VLANs. The details of the VLANs can be used to troubleshoot any
fault in the configuration. The following example describes the steps to view the
properties of the VLANs.
To view VLANs using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane. The details of the available VLANs
appear in this page.
2. Verify that the configured VLAN with ID 2 appears.
3. Select the VLAN with ID 2 and in the Details section, verify that the
parameters displayed are as configured.
To view the VLAN using the NetScaler command line
At the NetScaler command prompt, type:
sh vl an
Viewing the Statistics of a VLAN
You can view the statistics of configured VLANs, such as packets received, bytes
received, packets sent, bytes sent, and so on. These statistics can be used to find
anonymous values and to help debug a VLAN. The following example describes
the steps to view the statistics of a VLAN with ID 2.
To view the statistics of a VLAN using the configuration utility
1. In the Navigation Pane, expand Network and click VLANs. The VLANs
page appears in the Details Pane.
2. Select the VLAN whose statistics you want to view, for example, 2.
3. Click Statistics. The VLAN Statistics dialog box appears. This page
displays the following information about the selected VLAN: Packets
received, Bytes Received, Packets sent, Bytes sent and so on.
To view the statistics of a VLAN using the NetScaler command line
At the NetScaler command prompt, type:
st at vl an 2
Chapter 3 Basic Network Configuration 95
Configuring VMAC
The primary and secondary nodes in a high availability (HA) setup share the
floating entity, Virtual MAC address (VMAC). The primary node owns the
floating IP addresses (such as MIP, SNIP, VIP, and so on). The primary node
responds to ARP requests for these IP addresses with its own MAC address.
Therefore, the ARP table of an external device, such as an upstream router, is
updated with the floating IP address and the MAC address of the primary node.
When a failover occurs, the secondary node takes over as the new primary node.
The secondary node uses GARP to advertise the floating IP addresses that it
learns from the primary node. The MAC address that the new primary advertises
is the MAC address of its own network interface. Some devices (a few routers) do
not accept these GARP messages. Therefore, these external devices retain the IP
address-to-MAC address mapping that the old primary node formerly advertised.
This may result in a GSLB site going down.
You must configure a VMAC on both nodes of an HA pair. This means that both
nodes have identical MAC addresses. When a failover occurs, the MAC address
of the secondary node remains unchanged, and the ARP tables on the external
devices do not need to be updated. For more information on the procedures to
configure a VMAC, see the “High Availability” chapter of the Installation and
Configuration guide, Volume 1.
Configuring Access Control Lists
You can configure Access Control Lists (ACLs) and configure the system to
compare incoming packets against the ACLs. If a packet matches an ACL rule,
the system applies the action specified by the rule. Otherwise, the system applies
the default action (ALLOW), and the packet is processed normally.
Two types of ACLs are available on the system,
• Simple ACLs
• Extended ACLs
96 Installation and Configuration Guide - Volume 1
Configuring Simple ACLs
Simple ACLs filter a packet based only on the source IP address and destination
port. Simple ACLs take precedence over extended ACLs. If a simple ACL returns
the DENY value, the system takes a simple ACL action. Otherwise, the extended
ACL is applied. This is illustrated by the following figure.
Simple and Extended ACLs FlowSequence
Creating Simple ACLs
The following example describes the procedure to create a simple ACL rule1 that
causes the system to drop IP packets that originate from the computer with IP
address 10.102.29.10.
This rule is an “all port” rule; that is, it is applied to packets from the configured
IP address directed to any port. After such a rule is configured, the system does
not allow you to configure a specific port rule using the same IP address, because
the “all port” rule overrides any specific port rule. However, if an “all port” rule is
not configured, you can configure multiple specific port rules on the system.
For example, after rule1 is created, if you attempt to configure rule2 as a port 80
rule, the system shows an error. However, you can add multiple specific port rules
if an “all port” rule is not configured for the same IP address. To create a simple
ACL, use the parameters described in the following table.
Parameters Description
Name The alphanumeric name of the ACL.
Source IP Address (subnet or
host)
The IP address of the source machine. You can also
specify a range or a specific address. You can specify an
IP address with a value of 0.0.0.0.
Chapter 3 Basic Network Configuration 97
To create a Simple ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click Add. The Add ACL dialog box appears.
3. In the Name and Source IP Address text boxes, type the name of ACL and
IP address, for example, rule1 and 10.102.29.10.
4. Click Create and click Close. The ACL you created appears in the ACLs
page. This is shown in the following figure.
ACLs Page
To create a simple ACL using the NetScaler command line
At the NetScaler command prompt, type:
add si mpl eacl r ul e1 deny - sr ci p 10. 102. 29. 10
Configuring an Expiry Time on Simple ACL
You can configure simple ACLs to be valid for a specified time. The specified
time for which the simple ACL is valid is known as Time to Live (TTL). ACLs
with TTLs are not saved when you save the configuration. To configure the TTL
value, use the TTL parameter described in the following table.
The following example illustrates the steps to configure a simple ACL with a
TTL value of 10 seconds. You can only configure the TTL value when you create
a simple ACL. You cannot modify the TTL value for the existing rule.
Parameters Description
TTL The time to expire this ACL (in seconds). The minimum
value is 1 and the maximum value is 0x7FFFFFFF.
98 Installation and Configuration Guide - Volume 1
To configure an expiry time using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click Add. The Add ACL dialog box appears.
3. In the Name, Source IP Address and TTL (secs) text boxes, type the name
of the ACL, the IP address, and the TTL, for example, Block_20,
10.102.29.20, and 10.
4. Click Create and click Close. The ACL you created appears in the ACLs
page.
To configure an expiry time using the NetScaler command line
At the NetScaler command prompt, type:
add si mpl eacl bl ock_20 deny - sr ci p 10. 102. 29. 11 - TTL 10
Removing Simple ACL
This section describes the procedure to remove simple ACLs.
To remove a simple ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Select the ACL that you want to remove, for example, rule1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a simple ACL using the NetScaler command line
At the NetScaler command prompt, type:
r emove si mpl eacl r ul e1
Clearing all Simple ACLs
This section describes the procedure to remove all configured ACLs.
To remove all simple ACLs using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click Clear. The Clear Simple ACL (s) pop-up window appears.
3. Click Yes.
Chapter 3 Basic Network Configuration 99
To remove all simple ACLs using the NetScaler command line
At the NetScaler command prompt, type:
cl ear si mpl eacl
Verifying the Configuration
This section describes the procedure to verify the ACLs that you have configured.
This is useful for troubleshooting.
Viewing an Simple ACL
You can view the properties such as name, action, and protocol of the configured
ACLs. The details of the ACLs can be used to troubleshoot any fault in the
configuration. The following example describes the steps to view the properties
of the ACLs.
To view the ACLs using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane. The details of the available ACLs appear in this
page.
2. Verify that the configured ACL rule1 appears.
3. Select the ACL rule1 and in the Details section, verify that the parameters
displayed are as configured.
To view the simple ACLs using the NetScaler command line
At the NetScaler command prompt, type:
show si mpl eacl
Viewing the Statistics of a Simple ACL
This section describes the procedure to view the statistics of an ACL. You can use
the statistics of the ACLs to find the anonymous values and debug the working of
the ACL.
To view the statistics of a simple ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Select the ACL whose statistics you want to view, for example, rule1.
3. Click Statistics. The ACL Statistics dialog box appears. This page displays
the following information about the selected simple ACL: Simple ACL
Hits, Allow Simple ACL Hits, Deny Simple ACL Hits, Bridge Simple ACL
Hits, and Simple ACL Misses.
100 Installation and Configuration Guide - Volume 1
To view the statistics of the simple ACLs using the NetScaler command line
At the NetScaler command prompt, type:
st at si mpl eacl
Configuring Extended ACLs
Extended ACLs can filter packets based on the parameters of the packet, such as
source IP address, source port, action, and so on. When you configure simple and
extended ACLs, the simple ACLs take precedence over the extended ACLs.
Creating Extended ACLs
This section describes the procedure to create extended ACLs. An ACL defines
the condition that a packet must satisfy for the system to process the packet,
bridge the packet, or drop the packet. These actions are known as “processing
modes.” The processing modes are:
• ALLOW - The system processes the packet.
• BRIDGE – The system bridges the packet to the destination without
processing it.
• DENY – The system drops the packet.
The system processes an IP packet directly when both of the following conditions
exist:
• ACLs are configured on the system.
• The IP packet does not match any of the ACLs
The system does not support outbound ACLs. For example, you create an ACL
that denies the packets from destination IP address 10.102.29.234. When the
system sends a ping request to 10.102.29.234, it is not evaluated by the blockping
ACL, because the traffic originated from the system. To configure an extended
ACL, use the parameters described in the following table.
Parameters Description
Name The alphanumeric name of the ACL.
Source IP Address (subnet or
host)
The IP address of the source machine. You can specify a
range or a specific address. You can also specify an IP
address with a value of 0.0.0.0.
Action The action associated with the ACL. The valid options
for this parameter are BRIDGE, DENY, and ALLOW.
Operator You can use the following operators while creating
ACLs: =and !=.
Chapter 3 Basic Network Configuration 101
You cannot create two ACLs with the same parameters. If you attempt to create a
duplicate, an error message appears.
Note: You must configure the simple ACL first, before configuring an extended
ACL.
The following example describes the procedure to create an ACL named rule.
The system drops the IP packets originating from the device when its source IP
address is between 10.102.0.0 and 10.102.255.255.
To create an extended ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and click Add. The Add ACL dialog box
appears.
3. In the Name text box, type the name of the ACL, for example, rule1.
4. In the Action and Operator list boxes, select the action and operator that
you want to configure, for example, DENY and =.
5. Under Source, in the Low and High text boxes, type the IP addresses, for
example, 10.102.0.0 and 10.102.255.255.
6. Click Create and click Close. The ACL you created appears in the ACLs
page. This is shown in the following figure.
Extended ACL Page
To create a extended ACL using the NetScaler command line
At the NetScaler command prompt, type:
add ns acl r ul e1 deny - sr ci p 10. 102. 0. 0- 10. 102. 255. 255
102 Installation and Configuration Guide - Volume 1
Applying an ACL
After you create an extended ACL, you must activate it using the following
procedure. This procedure re-applies all of the ACLs. For example, if you have
created the ACLs rule1 through rule10, and then you create rule11 ACL, all of the
ACLs (rule1 through rule11) are freshly applied. If a session has a DENY ACL
related to it, the session is destroyed.
You must apply this procedure after every action you perform on an ACL. For
example, you must follow this procedure after disabling an ACL.
Note: Extended ACLs created on the system do not work until they are applied.
To apply an ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and select the ACL that you want to apply, for
example, rule1.
3. Click Commit. TheApply ACL(s) pop-up window appears.
4. Click Yes.
To apply an ACL using the NetScaler command line
At the NetScaler command prompt, type:
appl y ns acl s
Managing ACLs
This section describes the parameters and procedures to remove, enable, and
disable simple and extended ACLs.
Removing Extended ACLs
This section describes the procedure to remove extended ACLs.
To remove a simple ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and select the ACL that you want to remove.
3. Click Remove. TheRemove pop-up window appears.
4. Click Yes.
Chapter 3 Basic Network Configuration 103
To remove an ACL using the NetScaler command line
At the NetScaler command prompt, type:
r mns acl r ul e1
Clearing all Extended ACLs
This procedure provides instruction to remove the configured extended ACLs.
To remove all extended ACLs using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab.
3. Click Clear. The Clear ACL (s) pop-up window appears.
4. Click Yes.
To remove all extended ACLs using the NetScaler command line
At the NetScaler command prompt, type:
cl ear ns acl
Enabling and Disabling an ACL
This section describes the procedures to enable or disable extended ACLs. By
default, the ACLs are enabled. This means that when ACLs are applied, the
system compares incoming packets against the configured ACLs. If an ACL is
not required to be part of the lookup table, but needs to be retained in the
configuration, it must be disabled before the ACLs are applied. After the ACLs
are applied, the system does not compare incoming packets against disabled
ACLs.
To disable an ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and select the ACL that you want to disable,
for example, rule1.
3. Click Disable.
To disable an ACL using the NetScaler command line
At the NetScaler command prompt, type:
di sabl e ns acl r ul e1
104 Installation and Configuration Guide - Volume 1
The example provides instruction to enable the ACL.
To enable an ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab.
3. Select the ACL that you want to enable, for example, rule1.
4. Click Enable.
To enable an ACL using the NetScaler command line
At the NetScaler command prompt, type:
enabl e ns acl r ul e1
Renumbering an ACL
This section describes the procedure to renumber ACLs. This procedure resets the
priorities of the ACLs to multiples of 10. For more information about priorities,
see “Modifying Extended ACLs” on page 104.
To renumber ACLs using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab.
3. Click Renumber Priority(s) ACL(s). The Renumber ACL pop-up window
appears.
4. Click Yes.
To renumber ACL using the NetScaler command line
At the NetScaler command prompt, type:
r enumber ns acl
Modifying Extended ACLs
This section describes the procedure to modify simple and extended ACLs. You
can configure the priority of an ACL. The priority (an integer value) defines the
order in which the system evaluates ACLs. All priorities are multiples of 10,
unless you configure a specific priority to an integer value. When you create an
ACL without specifying a priority, the system automatically assigns a priority
that is a multiple of 10.
Chapter 3 Basic Network Configuration 105
If a packet matches the condition defined by the ACL, the system performs an
action. If the packet does not match the condition defined by the ACL, the system
compares the packet against the ACL with the next-highest priority. To modify
the extended ACL, use the parameters listed in the following table.
Parameters Description
Source PORT The port address of the source machine. You can specify
a range or a specific port address. You can also specify a
port address with a value of 0.
Destination IP Address (subnet
or host)
The IP address of the destination machine. You can
specify a range or a specific address. You can also
specify an IP address with a value of 0.0.0.0.
Destination PORT The port address of the destination machine. You can
specify either a range or a specific port address. You can
also specify a port address with a value of 0.
Source MAC Address The MAC address of the source machine. Only the last
32 bits are considered during a lookup.
Protocol This is the protocol field in the IP header. The valid
options for this parameter are ICMP, IGMP, TCP, EGP,
IGP, ARGUS, UDP, RDP, RSVP, EIGRP, L2TP, and
ISIS.
Protocol Number The IP protocol number (decimal). The minimum value
is 1 and the maximum value is 255.
VLAN ID The VLAN ID present in the VLAN tag of the packet.
The minimum value is 1 and the maximum value is 255.
Interface This is the network interface on which the packet
arrived.
ICMP Type The ICMP message type. For example, to block
DESTINATION UNREACHABLE messages, you
must specify 3 as the ICMP type. For a complete list of
ICMP types, see http://www.iana.org/assignments/
icmp-parameters. The minimum value is 0 and the
maximum value is 255.
ICMP Code The ICMP message code. For example, to block
DESTINATION HOST UNREACHABLE messages,
specify 3 as the ICMP type and 1 as the ICMP code. For
a complete list of ICMP types, see http://www.iana.org/
assignments/icmp-parameters. The minimum value is 0
and the maximum value is 255.
State The state of the ACL. The valid options for this
parameter are ENABLED and DISABLED.
Priority The priority of the ACL. The minimum value is 0 and
the maximum value is 10240.
106 Installation and Configuration Guide - Volume 1
Consider the following example. Two ACLs, rule 1 and rule 2, are configured on
the system and automatically assigned priorities 20 and 30. You need to add a
third ACL, rule 3, to be evaluated immediately after Rule 1. Rule 3 must have a
priority between 20 and 30. In this case, you can specify the priority as 25.
The following procedure describes the steps to set the priority of rule1 to 20.
To modify the priority of an ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and select the ACL that you want to modify,
for example, rule1.
3. Click Open. TheConfigure ACL(s) dialog box appears.
4. In the Priority text box, type the priority that you want to configure on the
ACL, for example, 20.
5. Click OK.
To modify the priority of an ACL using the NetScaler command line
At the NetScaler command prompt, type:
set acl r ul e1 - pr i or i t y 10
Verifying the Configuration
This section describes the procedure to verify the ACLs that you have configured.
This can be useful for troubleshooting.
Viewing an Extended ACL
You can view the properties such as name, action, and protocol of the configured
ACLs. Use the following procedure to view the extended ACLs.
To view extended ACLs using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACLs tab. The details of the available ACLs appear in
this page.
3. Verify that the configured ACL rule1 appears.
4. Select the ACL rule1 and in the Details section, verify that the parameters
displayed are as configured.
Chapter 3 Basic Network Configuration 107
To view extended ACLs using the NetScaler command line
At the NetScaler command prompt, type:
show ns acl
Viewing the Extended Statistics of an ACL
Use the following procedure to view the statistics of the extended ACLs.
To view the statistics of an extended ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
appears in the Details Pane.
2. Click the Extended ACL tab and select the ACL whose statistics you want
to view, for example, rule1.
3. Click Statistics. The ACL Statistics dialog box appears. This page displays
the following information about the selected extended ACL: ACL Hits,
NAT ACL Hits, Allow ACL Hits, Deny ACL Hits, Bridge ACL Hits, and
ACL Misses.
To view the statistics of an extended ACL using the NetScaler command line
At the NetScaler command prompt, type:
st at ns acl r ul e1
Configuring Bridge Tables
This section describes the steps to configure bridge tables for bridging frames.
The system bridges frames based on bridge table lookup of the destination MAC
address and the VLAN ID. Packets addressed to the MAC address of the system
are processed at the upper layers. The forwarding process on the system is similar
to that on any standard switch. However, the system performs forwarding only
when Layer 2 mode is enabled. For more information about enabling Layer 2
mode, see “Enabling and Disabling Layer 2 Mode” on page 57.
Modifying Bridge Tables
This section describes the procedure to modify bridge tables. To modify the
bridge table, use the bridge age parameter described in the following table.
Parameter Description
Bridge Age The bridge ageing time in seconds. The default value is 300. The
minimum value is 60 and the maximum value is 300.
108 Installation and Configuration Guide - Volume 1
The following procedure describes the steps to configure the ageing time to 70
seconds.
To modify a bridge table using the configuration utility
1. In the Navigation Pane, expand Network and click Bridge Table. The
Bridge Table page appears in the Details Pane.
2. Select the MAC address for which you want to configure the ageing time,
for example, 00:12:01:0a:5f:46.
3. Click Change Ageing Time. The Change Ageing Time dialog box
appears.
4. In the Ageing Time (seconds) text box, type the ageing time, for example,
70.
5. Click OK. The MAC you selected is configured with the ageing time. This
is shown in the following figure.
Bridge Table Page
To modify a bridge table using the NetScaler command line
At the NetScaler command prompt, type:
set br i dget abl e - br i dgeAge 70
Verifying the Configuration
This section describes the procedure to verify a bridge table that you have
configured. This can be useful for troubleshooting.
Viewing the Properties of a Bridge Table
This section describes the procedure to view a bridge table.
Chapter 3 Basic Network Configuration 109
To view the bridge table using the configuration utility
1. In the Navigation Pane, expand Network and click Bridge Table. The
Bridge Table page appears in the Details Pane. The details of the available
bridge tables appear in this page.
2. Verify that the configured bridge table appears.
3. Select the configured bridge table and in the Details section, verify that the
parameters displayed are as configured.
To view the bridge table using the NetScaler command line
At the NetScaler command prompt, type:
show br i dget abl e
Viewing the Statistics of a Bridge Table
This section describes the procedure to view the bridging statistics.
To view the statistics of a bridge table using the configuration utility
1. In the Navigation Pane, expand Network and click Bridge Table. The
Bridge Table page appears in the Details Pane.
2. Select the MAC address for which you want to view the statistics, for
example, 00:12:01:0a:5f:46.
3. Click Statistics. The Bridge Statistics dialog box appears. This dialog box
displays the following information about the selected bridge table: Loops,
Collisions, and Interface Muted
To view the statistics of a bridge table using the NetScaler command line
At the NetScaler command prompt, type:
st at br i dge
110 Installation and Configuration Guide - Volume 1
CHAPTER 4
Load Balancing
This chapter describes the load balancing (LB) feature of a Citrix NetScaler. Load
balancing allows a NetScaler to distribute the client requests across multiple
servers. Load balancing improves server fault tolerance and end-user response
time. This chapter lists the basic and a few advanced settings that you can
configure on a NetScaler.
In This Chapter
• How Load Balancing Works
• Configuring Basic Load Balancing
• Customizing Load Balancing Configuration
• Protecting the Load Balancing Configuration against Failure
• Managing Client Traffic
• Managing and Monitoring Servers
• Managing a Large Scale Deployment
• Configuring Load Balancing for Commonly Used Protocols
• Configuring Load Balancing in Commonly Used Deployment Scenarios
• Troubleshooting Common Problems
How Load Balancing Works
The load balancing feature distributes client requests across multiple servers to
optimize resource utilization. In a real-world scenario with a limited number of
servers providing service to a large number of clients, a server can become
overloaded and degrade server performance. A NetScaler uses the load balancing
criteria to prevent bottlenecks by forwarding the client requests to the servers best
suited to handle them. Thus, the NetScaler balances the load on the servers.
112 Installation and Configuration Guide - Volume 1
To configure load balancing, you define virtual server (vserver) to proxy multiple
servers in a server farm and balance the load among them. The vserver identifies
the server using the load balancing criteria and directs incoming client requests to
it. When a client initiates a connection to the server, the vserver terminates the
client connection and initiates a new connection with the selected server to
perform load balancing.
The load balancing feature provides traffic management from layer 4 (TCP and
UDP) to layer 7 (FTP, HTTP, and HTTPS). Layer 7 protocol HTTP is aware of
Layer 4 protocol TCP.
A NetScaler uses a number of algorithms, called LB methods, to determine how
to distribute the load among the servers. The default load balancing method is the
Least Connections method.
A typical load balancing deployment consists of the entities described in the
following figure.
LB architecture
The entities that you must configure in a typical load balancing setup are:
• Vserver. An entity that is represented by using an IP address, a port, and a
protocol. The vserver IP address (VIP) is usually a public IP address. The
client sends connection requests to this IP address. The vserver represents a
bank of servers.
• Service. An entity that is represented by using an IP address, a port, and a
protocol. A service is a logical representation of a server or an application
running on a server. The services are bound to the vservers.
Chapter 4 Load Balancing 113
• Server object. An entity that is represented by using an IP address. The
server object is usually created when you create a service. The IP address of
the service is taken as the name of the server object. You can also create a
server object and then create services by using the server object.
• Monitor. An entity that tracks the health of the services. The NetScaler
periodically probes the servers using the monitor bound to each service. If a
server does not respond within a specified response timeout, and the
specified number of probes fails, the service is marked down. The
NetScaler then performs load balancing among the remaining services.
To configure load balancing, you must first create services. Then, you must create
vservers and bind services to the vservers. By default, the NetScaler binds a
monitor to each service. You can also assign weights to a service. The LB method
uses the assigned weight to select a service.
You can enable a NetScaler option to maintain persistent connections between
clients and servers. For instance, in e-commerce such as shopping card usage, the
server needs to maintain the state of the connection to track the transaction. To
maintain the state of connection, you must configure persistence on a vserver.
The NetScaler selects a server to process a client request and forwards all
subsequent requests to the selected server.
You can also specify persistence for a group of vservers. When you enable
persistence on the group, the client requests are directed to the same selected
server regardless of which vserver in the group receives the client request. When
the configured idle time for persistence elapses, any vserver in the group is
selected for the incoming client requests.
The following sections describe the steps to configure a complete load balancing
setup, for several deployment scenarios.
Configuring Basic Load Balancing
This section describes how to configure a basic but functional LB setup and
modify it. The tasks described here serve as a basis for all future configuration
tasks that you might perform. This section also covers the procedures to modify
the setup, including deleting, enabling, and disabling entities.
Topics include:
• Configuring a Basic Setup
• Modifying an Existing Load Balancing Configuration
114 Installation and Configuration Guide - Volume 1
Configuring a Basic Setup
This section describes the topology of a basic LB setup. It also describes how to
create the vservers and services using the basic topology. A basic LB setup uses
only the mandatory parameters, and serves as the first step in configuring the load
balancing feature on a NetScaler. The basic LB setup provides a simple and
functional LB configuration as described in the following section.
Understanding the Topology
In a load balancing setup, the NetScalers are logically located between the client
and the server farm. Load balancing is used to manage traffic flow to the servers
in the server farm. The following diagram shows the topology of a basic load
balancing configuration.
Basic load balancing topology
In the diagram, load balancing is used to manage traffic flow to the servers. The
vserver selects the service and assigns it to serve client requests. Consider a
scenario where the services Service-HTTP-1 and Service-HTTP-2 are created and
bound to the vserver named Vserver-LB-1. Vserver-LB-1 forwards the client
request to either Service-HTTP-1 or Service-HTTP-2. The NetScaler selects the
service for each request using the Least Connections load balancing method. The
following table lists the names and values of the basic entities that must be
configured on the NetScaler.
Entity Type Mandatory Parameters and Sample Values
Name IP Address Port Protocol
Vserver Vserver-LB-1 10.102.29.60 80 HTTP
Chapter 4 Load Balancing 115
The following figure shows the load balancing sample values and mandatory
parameters that are described in the preceding table.
Load balancing entity model
Enabling Load Balancing
To use the load balancing feature, you must enable load balancing. You can
configure load balancing entities though the load balancing feature is disabled.
However, the entities will not work.
To enable load balancing using the configuration utility
1. In the navigation pane, expand System and click Settings. The Settings
page appears in the details pane.
2. Under Modes & Features, click basic features. The Configure Basic
Features dialog box appears.
3. Select the Load Balancing check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
Services Service-HTTP-1 10.102.29.5 8083 HTTP
Service-HTTP-2 10.102.29.6 80 HTTP
Monitors Default None None None
Entity Type Mandatory Parameters and Sample Values
Name IP Address Port Protocol
116 Installation and Configuration Guide - Volume 1
To enable load balancing using the NetScaler command line
At the NetScaler command prompt, type:
enable feature lb
Creating Services
You can add, modify, bind, and remove services. Once configured, services are in
the disabled state until the NetScaler can reach the server on the network and
monitor its status. To create services, use the mandatory parameters as described
in the following table.
Before you create a service, you need to understand the service types and the
usage of each type. NetScaler supports the following service types:
• HTTP. For HTTP services and virtual servers. To enable the Layer 7
benefits for HTTP connections such as compression, content filtering,
caching, and Client Keep Alive, you can configure services and virtual
servers of type HTTP. Because HTTP is a TCP based application protocol,
you may alternatively use service type TCP, however, in this case, the
NetScaler will only perform Layer 4 load balancing and will not provide
the Layer 7 benefits listed above, as well as the following:
• Vserver IP Port Insertion
• Redirect Port Rewrite
• Push
• Redirect URL
• SSL. For HTTPS services and virtual servers. Select this service type to
configure the NetScaler to encrypt and decrypt (offload) SSL traffic.
Alternatively, you can use service types SSL_BRIDGE, SSL_TCP, or TCP,
Parameter Description
Name The name of the service. The service name must not be longer than 31
characters, and must not contain spaces. This setting cannot be
changed after the service is created.
Server Name or
IP address
The IP address of the service. When you provide the IP address of the
service, a server object is created with this IP address as its name. You
can also create a server and use the server name instead of the IP
address.
Service Type Behavior of the service. Select one of the following service types:
HTTP, SSL, FTP, TCP, SSL_TCP, UDP, SSL_BRIDGE, NNTP, DNS,
ANY, SIP-UDP, DNS-TCP, and RTSP.
Port The port on which the service listens. The port number must be a
positive number not greater than 65535.
Chapter 4 Load Balancing 117
however in these cases, the NetScaler performs only Layer 4 load
balancing, and the server must encrypt and decrypt the SSL traffic. Also,
with service type SSL_Bridge, SSL_TCP, and TCP no Layer 4-Layer 7
processing can be done, such as persistence based on HTTP information,
content switching, rewrite, etc., and the following options are not
supported:
• Vserver IP Port Insertion
• Push
• Redirect URL
• FTP. For FTP services and virtual servers. This setting ensures that the
NetScaler takes care of the specifics of the FTP protocol. Alternatively, you
can use service type TCP with the appropriate additional service type ANY
virtual server.
• TCP. For any TCP services or virtual servers for which a more specific
service type is not available. Alternatively, you can use service type ANY.
• SSL_TCP. For non-HTTP-based SSL services and virtual servers.
Alternatively, you can use service type TCP, however in this case,
NetScaler performs Layer 4 load balancing, but not SSL offloading and the
server must encrypt and decrypt the SSL traffic.
• UDP. For User Datagram Protocol services and virtual servers.
Alternatively, you can use service type ANY.
• SSL_BRIDGE. For services and virtual servers using the SSL protocol
when you do not want the NetScaler to encrypt or decrypt the SSL traffic.
Alternatively, you can use SSL_TCP for the service type.
• NNTP. For Network News Transfer Protocol services or virtual servers,
typically used for Usenet.
• DNS. For Domain Name System services and virtual servers. With service
type DNS, the NetScaler will validate the packet format of the DNS
requests and responses, it can cache the DNS responses, and it will be
possible to apply DNS policies to the service or vserver. Alternatively, you
can use service type UDP, but in this case the NetScaler will only perform
Layer 4 load balancing and will not provide the other benefits possible with
the DNS service type.
• ANY. For any TCP, UDP, and Internet control message protocol (ICMP)
services or virtual servers. The ANY parameter is used primarily with
firewall load balancing and link load balancing.
118 Installation and Configuration Guide - Volume 1
• SIP-UDP. For UDP-based Session Initiation Protocol (SIP) connections.
SIP initiates, manages, and terminates multimedia communications
sessions and has emerged as the standard for Internet telephony (VoIP).
Alternatively, you can use service type UDP, but in this case the NetScaler
performs only Layer 4 load balancing for SIP servers.
• DNS-TCP. For enabling the NetScaler to act as a proxy for TCP traffic sent
to DNS severs. With service type DNS-TCP, the NetScaler will validate the
packet format of the DNS requests and responses, and it can cache the DNS
responses. Alternatively, you can use service type TCP, but, the NetScaler
will not parse DNS queries and it will only perform Layer 4 load balancing
of external DNS name servers.
• RTSP. For Real Time Streaming Protocol services and virtual servers.
RTSP provides delivery of multimedia and other streaming data. Select this
type to support media streams, such as audio and video. Alternatively, you
can use service type TCP protocol, but in this case, the NetScaler will not
parse the RTSP traffic, it will perform Layer 4 load balancing only, and the
following options are not supported:
• RTSPID persistence
• RTSP Natting
• DHCPRA. For Dynamic Host Configuration Protocol (DHCP) services
and virtual servers. The DHCPRA service type can be used to relay DHCP
requests and responses between VLANs.
Note: For more information about SSL and SSL TCP service types, see the
“Secure Sockets Layer (SSL) Acceleration” chapter.
The following procedure describes the steps to create a service. The sample
values are listed in the topology summary table on Chapter 4, " 10.102.29.60".
To create a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Click Add. The Create Service dialog box appears.
3. In the Service Name, Server, and Port text boxes, type the name, IP
address, and port of the service, for example, Service-HTTP-1,
10.102.29.5, and 8083.
4. In the Protocol list, select the type of the service, for example, HTTP.
Chapter 4 Load Balancing 119
5. Click Create and click Close. The service you created appears in the
Services page, as shown in the following figure.
Services page
To create a service using the NetScaler command line
At the NetScaler command prompt, type:
add service Service-HTTP-1 10.102.29.5 HTTP 80
Creating Servers
A server object is an entity that is created when you create a service. The IP
address of the service is taken as the name of the server object. You can also
create a server object and then create services using the server object. To create a
server, use the parameters as described in the following table.
Use the following procedure to create a server.
To create servers using the configuration utility
1. In the navigation pane, expand Load Balancing and click Servers. The
Servers page appears in the details pane.
2. Click Add. The Create Servers dialog box appears.
Parameter Description
Name The name of the server. The server name must not be longer than 31
characters and must not contain spaces. This setting cannot be
changed after the server is created.
Domain Name
or IP address
The IP address or the domain name of the server for which a service
needs to be added. You need not specify the domain name if an IP
address is specified.
120 Installation and Configuration Guide - Volume 1
3. In the Name and IP Address / Domain name text boxes, type Server-1
and 10.102.29.18.
4. Click Create and click Close. The server you created appears in the
Servers page, as shown in the following figure.
Servers page
To create servers using the NetScaler command line
At the NetScaler command prompt, type:
add server Server-1 10.102.29.18
Creating a Vserver
After you create a service, create a vserver. You can add, modify, and remove
vservers. The state of the vserver that you create is down because the active
services are not bound to it. To create a vserver, use the parameters as described
in the following table.
Parameter Description
Name The name of the vserver. The vserver name must not exceed 31
characters and must not contain spaces. This setting cannot be
changed.
IP address The IP address of the vserver. This IP address (VIP) is usually a public
IP address and the clients send connection requests to this IP address.
Service Type Behavior of the service. Select one of the following service types:
HTTP, SSL, FTP, TCP, SSL_TCP, UDP, SSL_BRIDGE, NNTP, DNS,
ANY, SIP-UDP, DNS-TCP, and RTSP.
Port The port on which the vserver listens for client connections. The port
number must be between 0-65535.
Chapter 4 Load Balancing 121
The following example describes the procedure to create a vserver named
Vserver-LB-1. The sample values are listed in the topology summary table on
Chapter 4, " 10.102.29.60".
To create a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Click Add. The Create Virtual Server (Load Balancing) dialog box
appears.
3. In the Name, IP Address, and Port text boxes, type the name, IP address,
and port of the vserver, for example, Vserver-LB-1, 10.102.29.60, and 80.
4. In the Protocol list, select the type of the vserver, for example, HTTP.
5. Click Create and click Close. The vserver you created appears in the Load
Balancing Virtual Servers page, as shown in the following figure.
Load balancing virtual servers page
To create a vserver using the NetScaler command line
At the NetScaler command prompt, type:
add lb vserver Vserver-LB-1 HTTP 10.102.29.60 80
Binding the Services to the Vserver
After you have created vserver and services, you can bind the services to the
vserver. You can bind multiple services to a vserver. The state of the services
bound to the vserver determines the state of the vserver, as follows:
• If state of the bound services is down, the vserver is marked down.
122 Installation and Configuration Guide - Volume 1
• If state of one of the bound services is up or out of service, the state of the
vserver is up.
To load balance the incoming traffic, you must bind the services to vserver. In
most cases, services are bound to vservers of the same type, but you can bind
different types of services and vservers. The following table shows the supported
cases.
The following procedure describes the steps to bind the services to the vserver.
To bind a service to a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears. The services appear in the Services tab.
4. Select the Active check box next to the service that you want to bind to the
vserver, for example, Service-HTTP-1.
5. Click OK.
To bind a service to a vserver using the NetScaler command line
At the NetScaler command prompt, type:
bind lb vserver Vserver-LB-1 Service-HTTP-1
Note: You can bind a single service to multiple virtual servers.
Vserver Type Service Type Comment
HTTP SSL Back-end encryption
SSL HTTP SSL offloading
SSL_TCP TCP SSL offloading for other TCP (SSL decryption
without content awareness).
Chapter 4 Load Balancing 123
Verifying the Configuration
To verify the configuration, you need to view the load balancing entities and the
statistics of the entities in the configuration.
Viewing the Properties of the Server
You can view properties such as the name, state, and IP address of the configured
servers. The details of the server can be used to troubleshoot any mistake in the
configuration. The following procedure describes the steps to view the properties
of a server named Server-1.
To view the properties of servers using the configuration utility
1. In the navigation pane, expand Load Balancing and click Servers. The
Servers page appears in the details pane. The details of the available
servers appear on this page.
To view the properties of servers using the NetScaler command line
At the NetScaler command prompt, type:
show server server-1
Viewing the Properties of the Vserver
You can view properties such as the name, state, effective state, IP address, port,
protocol, method, and persistence of the configured vservers. The details of the
vserver can be used to troubleshoot any mistake in the configuration. The
following procedure describes the steps to view the properties of a vserver named
vserver-LB-1.
To view the properties of vservers using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane. The
details of the available vservers appear on this page.
To view the properties of vservers using the NetScaler command line
At the NetScaler command prompt, type:
show lb vserver Vserver-LB-1
Viewing the Statistics of a Vserver
You can view statistics such as the name, vserver IP address, port, vserver
protocol, state, and request rate of configured vservers. You can use the statistics
to troubleshoot the working of a vserver. The following procedure displays the
statistics of a vserver vserver-LB-1.
124 Installation and Configuration Guide - Volume 1
To view the statistics of a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver whose statistics you want to view, for example,
Vserver-LB-1.
3. Click Statistics to view the statistics of the vserver.
To view the statistics of a vserver using the NetScaler command line
At the NetScaler command prompt, type:
stat lb vserver Vserver-LB-1
Viewing the Properties of the Service
You can view the name, state, IP address, port, protocol, maximum client
connection, maximum requests per connection, and server type of the configured
services, and use this information to troubleshoot any mistake in the service
configuration. The following example describes the steps to view the properties
of a service named service-HTTP-1.
To view the properties of services using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears on the right page. The details of the available
services appear in this pane.
To view the properties of services using the NetScaler command line
At the NetScaler command prompt, type:
show service Service-HTTP-1
Viewing the Statistics of a Service
You can view the rate of requests, responses, request bytes, response bytes,
current client connections, requests in surge queue, current server connections,
and so on using the service statistics. The following procedure displays the
statistics of a service named Service-HTTP-1.
To view the statistics of a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service whose statistics you want to view, for example,
Service-HTTP-1.
3. Click Statistics. The statistics appear in a new window.
Chapter 4 Load Balancing 125
To view the statistics of a service using the NetScaler command line
At the NetScaler command prompt, type:
stat service Service-HTTP-1
Viewing the Bindings of a Service
You can view the list of vservers to which the service is bound. The binding
information also provides the name, IP address, port and state of the vservers to
which the services are bound. You can use the binding information to
troubleshoot any problem in the binding the services to vservers. The following
procedure displays the binding information for a service.
To view the bindings of a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service whose binding information you want to view, for
example, Service-HTTP-1.
3. Click Show Bindings. The bindings of the service you selected appear in
the Bindings Info for Service: Service-HTTP-1 dialog box.
To view the bindings of a service using the NetScaler command line
At the NetScaler command prompt, type:
show service bindings Service-HTTP-1
Modifying an Existing Load Balancing
Configuration
This section describes how to modify the basic LB setup you configured
previously. This section also describes the impact of modifying an entity in the
basic LB setup. Modifying a basic LB setup allows you manage the entities
configured in the setup. You can perform tasks such as enabling, disabling, and
removing entities in the basic LB setup to modify the setup, using the procedures
described in this section.
Managing Servers
This section describes how to manage the servers you create in a basic LB setup.
After creating servers, you can enable, disable, or remove them. Each task that
you perform has an impact on the services that use the server, as described in the
following sections.
126 Installation and Configuration Guide - Volume 1
Removing a Server
When you create a service, a server with the IP address of the service is created, if
the server does not exist. If you remove the server, the service is also deleted. The
following example describes the steps to remove a server with IP address
10.102.29.5.
To remove a server using the configuration utility
1. In the navigation pane, expand Load Balancing and click Servers. The
Servers page appears in the details pane.
2. Select the server that you want to remove, for example, 10.102.29.5.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a server using the NetScaler command line
At the NetScaler command prompt, type:
rm server 10.102.29.5
Enabling and Disabling Servers
You can disable a server to disable the services that use the server object. When
you refresh the NetScaler, after you disable the server, the state of the services
appears as Going Out of Service. When a server is disabled with specific wait
time the server handles the established connections only and rejects the new
connections. To disable a server, use the Wait Time parameter as described in the
following table.
The following example describes the steps to disable the server, 10.102.29.5 after
30 seconds.
To disable a server using the configuration utility
1. In the navigation pane, expand Load Balancing and click Servers. The
Servers page appears in the details pane.
2. Select the server that you want to disable, for example, 10.102.29.5.
3. Click Disable. The Wait Time pop-up window appears.
4. Type the wait time after which the server is to be disabled, for example 30.
5. Click Enter.
Parameter Description
Wait Time The time in seconds, after which the server is marked
down.
Chapter 4 Load Balancing 127
To disable a server using the NetScaler command line
At the NetScaler command prompt, type:
disable server 10.102.29.5 30
When you enable the server and refresh the NetScaler, the services associated
with the server are also enabled. The following example describes the steps to
enable the server 10.102.29.5.
To enable a server using the configuration utility
1. In the navigation pane, expand Load Balancing and click Servers. The
Servers page appears in the details pane.
2. Select the server that you want to enable, for example, 10.102.29.5.
3. Click Enable. The Enable pop-up window appears.
4. Click Yes.
To enable a server using the NetScaler command line
At the NetScaler command prompt, type:
enable server 10.102.29.5
Managing Services
This section describes how to manage the services after you create them in a basic
LB setup. Managing the services allows you to modify the working of the basic
LB setup. You can perform tasks such as enabling, disabling, and removing
services after you create the services. Each task that you perform has an impact
on the basic LB setup as described in the following sections.
Removing a Service
You can remove a service when it is no longer used. When you remove a service,
it is unbound from the vserver and deleted from the NetScaler.
To remove a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service that you want to remove, for example, Service-HTTP-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a service using the NetScaler command line
At the NetScaler command prompt, type:
128 Installation and Configuration Guide - Volume 1
rm service Service-HTTP-1
Enabling and Disabling Services
By default, the configured services are enabled. You can disable a service when
you do not want to use the service. To disable a service, you must specify a wait
time. If you do not specify the wait time, the service is disabled immediately after
you disable it. During the shutdown period, the state of a service appears as
Going Out of service. When a service is disabled with specific wait time the
service handles the established connections only and rejects the new connections.
To disable a service, use the Wait Time parameter as described in the following
table.
The following example describes the steps to disable the service Service-HTTP-1
after 30 seconds.
To disable a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service that you want to disable, for example, Service-HTTP-1.
3. Click Disable. The Wait Time pop-up window appears.
4. In the Wait Time pop-up window, type the wait time after which the
service is to be disabled, for example, 30.
5. Click Enter.
To disable a service using the NetScaler command line
At the NetScaler command prompt, type:
disable service Service-HTTP-1 30
You can also enable the services individually. The following example describes
the steps to enable the service Service-HTTP-1.
To enable a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service that you want to enable, for example, Service-HTTP-1.
3. Click Enable. The Enable pop-up window appears.
Parameter Description
Wait Time The time in seconds, after which the services representing
the server are marked down.
Chapter 4 Load Balancing 129
4. Click Yes.
To enable a service using the NetScaler command line
At the NetScaler command prompt, type:
enable service Service-HTTP-1
Managing an LB Vserver
This section describes how to manage the vservers after you create them.
Managing the vservers allows you to modify the working of the entities in a basic
LB setup. You can perform tasks such as enabling, disabling, and removing
vservers after you create them. You can also unbind a service from a vserver.
Each task that you perform has an impact on the basic LB setup, as described in
the following sections.
Unbinding a Service froma Vserver
When you unbind a service from a vserver, the NetScaler does not consider the
service for load balancing. The following example describes the steps to unbind
the service Service-HTTP-1 from the vserver Vserver-LB-1.
To unbind a service from a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver from which you want to unbind a service, for example,
Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears. The services appear in the Services tab.
4. Clear the Active check box next to the service that you want to unbind from
the vserver, for example, Service-HTTP-1.
5. Click OK.
To unbind a service from a vserver using the NetScaler command line
At the NetScaler command prompt, type:
unbind lb vserver Vserver-LB-1 Service-HTTP-1
130 Installation and Configuration Guide - Volume 1
Removing a Vserver
You need to remove a vserver only when you no longer require the vserver. To
remove a vserver, you must first unbind the services from the vserver, and then
remove the vserver. If you remove all the vservers from the NetScaler, the
NetScaler does not accept any new connections. The following example describes
the steps to delete the vserver Vserver-LB-1.
To remove a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver that you want to remove, for example, Vserver-LB-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a vserver using the NetScaler command line
At the NetScaler command prompt, type:
rm lb vserver Vserver-LB-1
Enabling and Disabling Vservers
You can disable a vserver for maintenance. If you disable the vserver, the state of
the vserver changes to Out of Service. In this state, the vserver cannot accept
new connections, but it continues to serve requests on existing connections.
To disable a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver that you want to disable, for example, Vserver-LB-1.
3. Click Disable. The Disable pop-up window appears.
4. Click Yes.
To disable a vserver using the NetScaler command line
At the NetScaler command prompt, type:
disable lb vserver Vserver-LB-1
Chapter 4 Load Balancing 131
By default, the vservers are enabled.
To enable a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver that you want to enable, for example, Vserver-LB-1.
3. Click Enable. The Enable pop-up window appears.
4. Click Yes.
To enable a vserver using the NetScaler command line
At the NetScaler command prompt, type:
enable lb vserver Vserver-LB-1
Note: In the disabled state, a vserver continues to exist on the network. The
NetScaler continues to respond to ARP and ICMP requests directed to the IP
address of the vserver.
Customizing Load Balancing Configuration
This section describes how to customize a basic LB setup to meet your
requirements. You can perform the optional tasks such as the following: change
the load balancing criteria, maintain persistent connection between the client and
the server, and assign weights to the services. Customizing a basic LB setup
allows you to change the working of the basic LB setup, as described in the
following sections.
132 Installation and Configuration Guide - Volume 1
Changing the Load Balancing Algorithm
The Load Balancing algorithm (LB method) defines a criterion that the NetScaler
uses to select the server to which it sends client requests. When the selected
server reaches the configured criteria, the NetScaler selects a different server.
Load Balancing Granularity refers to the criteria that the NetScaler uses to decide
the load balancing method in a given situation. The NetScaler performs request-
based, connection-based, or time-based load balancing, depending on the
protocol of the service (s) it is load balancing. The following table describes the
types of load balancing, and the criteria that determine when each method is used.
You can change the load balancing algorithm using the procedure described in
this section. To configure LB method, use the LB Method parameter as described
in the following table.
Protocol Load
balancing
Granularity Description
HTTP or HTTPS HTTP
Request
based
Server selection is done for every HTTP request
independent of TCP connections.
TCP Connections
based
Server selection is done for every new TCP
connection.
UDP and Other IP
protocols
Time based Server selection is done on a UDP packet. On
selection of a server, a session is created between the
server and a client, for a specified period of time.
When the time expires, the session is deleted and
server selection is done for other packets, even if the
packets come from the same client.
Parameter Description
LB Method The load balancing method for the vserver. The valid
options for this parameter are:
ROUNDROBIN, LEASTCONNECTION,
LEASTRESPONSETIME, URLHASH, DOMAINHASH,
DESTINATIONIPHASH, SOURCEIPHASH,
SRCIPDESTIPHASH, LEASTBANDWIDTH,
LEASTPACKETS, TOKEN, SRCIPDESTIPHASH,
CUSTOMLOAD.
The default LB method is LEASTCONNECTION.
Chapter 4 Load Balancing 133
The following example describes the steps to set the vserver Vserver-LB-1 to use
the least connection method to select the services for load balancing.
To set LB methods using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure an LB method, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Method and Persistence tab. In the list under LB Method, select
Least Connection.
5. Click OK.
To set LB methods using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -lbMethod LeastConnection
Understanding SlowStart
When you configure a NetScaler to use a metric-based LB method such as Least
Connections, Least Response Time, Least Bandwidth, Least Packets, or Custom
Load, the LB method will initially start out as Round Robin for what is called a
slow start.
As mentioned earlier, NetScaler appliances use the configured load balancing
method to determine the appropriate service for forwarding an incoming request.
Load balancing environments are dynamic, and the NetScaler needs to manage
the events that may overload the server. For example, when you configure the
Least Connections LB method, the NetScaler selects the service that has the least
number of connections. If a new server is added to the server farm, the NetScaler
selects the new server with the least number of connections, and, therefore, may
overload the new server.
To avoid overloading servers, the NetScaler performs slow start. During the slow
start phase, the NetScaler distributes requests by using Round Robin, regardless
of the metric-based LB method configured on the virtual server. However, the
weight assigned on the services is used by Round Robin. After the number of
incoming requests or connections per second exceeds a given threshold, the
NetScaler stops slow start and operates using the configured load balancing
method.
Slow start occurs when:
134 Installation and Configuration Guide - Volume 1
• You configure a new metric-based load balancing method.
• You bind a service to the vserver.
• The state of the server changes from DOWN to UP.
To compute slow start, the number of services bound to the vserver is multiplied
by 100. For a new virtual server with the LB method determined by dynamic
traffic parameters, slow start allows time to collect a valid data sample before the
correct method is applied.
Note: When slow start is in operation, the output for the show l b vser ver
<vser ver name>command will specify the current method as Round Robin.
In GSLB setup, metric-based load balancing methods do not work correctly if
MEP is DOWN except Custom Load LB method, and they will operate only in
RoundRobin. For Custom Load if MEP is DOWN and custom load monitors that
use SNMP to get statistics are bound to service, Custom Load LB method is used
for load balancing. If local load monitors bound to service and MEP is DOWN,
then Round Robin is used. For more information about GSLB, see Citrix
NetScaler Installation and Configuration Guide.
Configuring the Least Connection Method
When the NetScaler is configured to use the least connection method, it selects
the service with the least number of active connections to ensure that the load of
the active requests is balanced on the services. This method is the default load
balancing method because it provides the best performance. For TCP, HTTP,
HTTPS and SSL_TCP services, the following connections are also considered for
the least connections method:
• Active connections to a service. Active connections represent the requests
sent by the client to a service. But in case of HTTP and HTTPS services,
active connections represent only the outstanding HTTP or HTTPS
requests to services.
• Waiting connections to a service in the Surge Queue. Connections can
build up in the surge queue at any time because of any of the following
reasons:
• A connection limit exists on the service
• The Surge Protection feature is configured
• The server does not open new connections as in case of Apache’s
connection limit.
Chapter 4 Load Balancing 135
When a NetScaler uses the least connections method, it considers
such waiting connections as belonging to a service. Therefore, it
does not open new connections to the selected service in a timely
manner.
For UDP services, the connections considered for the least connections method
include all sessions between the client and a service. These sessions are logical,
time-based entities, and are created for the UDP packet that arrives first. When
the UDP packet arrives first, the session is created for the combination of the
source IP address and port, and the destination IP address and port.
The following example shows how a NetScaler selects a service for load
balancing by using the least connections method. Consider three services,
Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3:
• Service-HTTP-1 is handling three active transactions.
• Service-HTTP-2 is handling 15 active transactions.
• Service-HTTP-3 is not handling any active transactions.
The following figure illustrates how the NetScaler uses the least connections
method and forwards the requests to the three services.
Least connections mechanism
The NetScaler selects the service by using the value (N) of the following
expression:
N =Number of active transactions
136 Installation and Configuration Guide - Volume 1
The requests are delivered as follows:
• Service-HTTP-3 receives the first because the service is not handling any
active transactions.
Note: The service with no active transaction is selected first.
• Service-HTTP-3 receives the second and third requests because the service
has least number of active transactions.
• Service-HTTP-1 receives the fourth request. Because Service-HTTP-1 and
Service-HTTP-3 have same number of active transactions, the NetScaler
performs load balancing in a round robin manner. Therefore,
Service-HTTP-3 receives the fifth request, Service-HTTP-1 receives the
sixth request, Service-HTTP-3 receives the seventh request, and
Service-HTTP-1 receives the eighth request and so on.
Service-HTTP-2 is not considered for load balancing because it is loaded more
(handling 15 active transactions) as compared to the other two services. However,
if Service-HTTP-2 completes the active transactions, the NetScaler considers the
service for load balancing. Also, when the services are handling the same number
of active transactions, the NetScaler selects the service in a round robin manner.
The manner in which a service receives requests based on the N value is
summarized in the following table.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
Request-1 Service-HTTP-3
(N =0)
N =1 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-3
(N =1)
N =2
Request-3 Service-HTTP-3
(N =2)
N =3
Request-4 Service-HTTP-1
(N =3)
N =4 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
Request-5 Service-HTTP-3
(N =3)
N =4
Request-6 Service-HTTP-1
(N =4)
N =5
Request-7 Service-HTTP-3
(N =4)
N =5
Request-8 Service-HTTP-1
(N =5)
N =6
Chapter 4 Load Balancing 137
Selection of services by using the least connections method when weights are
assigned to the services
The NetScaler also performs load balancing by using the number of connections
when weights are assigned to services. The NetScaler selects the service by using
the value (N
w
) of the following expression:
N
w
= (Number of active transactions) * (10000 / weight)
The following example shows how the NetScaler selects a service for load
balancing by using least connections method when the weights are assigned to
services.
In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2,
Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a
weight of 4. The requests are delivered as follows:
• Service-HTTP-3 receives the first because the service is not handling any
active transactions.
Note: If services are not handling any active transactions, the NetScaler
selects them in a round robin manner irrespective of the weights assigned to
them.
• Service-HTTP-3 receives the second, third, fourth, fifth, sixth, and seventh
requests because the service has least N
w
value.
• Service-HTTP-1 receives the eighth request. Because Service-HTTP-1 and
Service-HTTP-3 have same N
w
value, the NetScaler performs load
balancing in a round robin manner. Therefore, Service-HTTP-3 receives the
ninth request.
Service-HTTP-2 is selected for load balancing when it completes the active transactions
or when the N value of other services (Service-HTTP-1 and Service-HTTP-3) is equal to
15.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
138 Installation and Configuration Guide - Volume 1
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-3
(N
w
=0)
N
w
=2500 Service-HTTP-3 has
the least N
w
value.
Request-2 Service-HTTP-3
(N
w
=2500)
N
w
=5000
Request-3 Service-HTTP-3
(N
w
=5000)
N
w
=7500
Request-4 Service-HTTP-3
(N
w
=7500)
N
w
=10000
Request-5 Service-HTTP-3
(N
w
=10000)
N
w
=12500
Request-6 Service-HTTP-3
(N
w
=12500)
N
w
=15000
Request-7 Service-HTTP-1
(N
w
=15000)
N
w
=20000 Service-HTTP-1 and
Service-HTTP-3
have the same N
w

values.
Request-8 Service-HTTP-3
(N
w
=15000)
N
w
=17500
Service-HTTP-2 is selected for load balancing when it completes the active transactions
or when the N
w
value of other services (Service-HTTP-1 and Service-HTTP-3) is equal
to 50000.
Chapter 4 Load Balancing 139
The following figure illustrates how the NetScaler uses the least connections
method when weights are assigned to the services.
Least connections mechanismwhen weights are assigned
To configure the Least Connection method, perform the steps described in the
section “Changing the Load Balancing Algorithm” on page 132. Under LB
Method, select Least Connection.
Configuring the Round Robin Method
When the NetScaler is configured to use the round robin method, it rotates
incoming requests to the managed servers, regardless of the load. For example,
the first request is sent to Service-HTTP-1, the second to Service-HTTP-2, the
third to Service-HTTP-3, and so on. When requests have been sent to all of the
servers, the cycle begins again from Service-HTTP-1.
140 Installation and Configuration Guide - Volume 1
The following figure illustrates how the NetScaler uses the round robin method
and forwards requests to the three services.
Round robin mechanism
A NetScaler also performs weighted round robin if different weights are assigned
to the services. For example, Service-HTTP-1 is set to a weight of 2,
Service-HTTP-2 to a weight of 3, and Service-HTTP-3 to a weight of 4, and the
services are bound to Vserver-LB-1. The requests are delivered as follows:
• Service-HTTP-1 receives the first request.
• Service-HTTP-2 receives the second request.
• Service-HTTP-3 receives the third request.
• Service-HTTP-1 receives the fourth request.
• Service-HTTP-2 receives the fifth and sixth request.
• Service-HTTP-3 receives the seventh, eighth, and ninth requests.
Note: You can configure weights on services to prevent multiple services from
using the same server, overloading the server.
Chapter 4 Load Balancing 141
A new cycle then begins, using the same pattern. The following figure illustrates
the weighted round robin method.
Round robin mechanismwhen weights are configured
To configure the round robin method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select Round Robin.
Configuring the Least Response Time Method
When the NetScaler is configured to use the least response time method, it selects
the service with the least number of active connections and the least average
response time. You can configure this method for HTTP and SSL type of services
only. The response time (also called Time to First Byte, or TTFB) is the time
interval between sending a request packet to a service and receiving the first
response packet from the service. The NetScaler uses response code 200 to
calculate TTFB.
The following example shows how a NetScaler selects a service for load
balancing by using the least response time method. Consider three services,
Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3.
• Service-HTTP-1 is handling three active transactions and TTFB is two
seconds.
• Service-HTTP-2 is handling seven active transactions and TTFB is one
second.
• Service-HTTP-3 is not handling any active transactions and TTFB is two
second.
142 Installation and Configuration Guide - Volume 1
The following figure illustrates how the NetScaler uses the least response time
method and forward requests to the three services.
Least response time mechanism
The NetScaler selects the service by using the value (N) of the following
expression:
N =Number of active transactions * TTFB
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first request because the service is not
handling any active transaction.
Note: The service with no active transaction is selected first.
• Service-HTTP-3 receives the second and third requests because the service
has the least N value.
• Service-HTTP-1 receives the fourth request. Because Service-HTTP-1 and
Service-HTTP-3 have same N value, the NetScaler performs load balancing
in a round robin manner. Therefore, Service-HTTP-3 receives the fifth
request.
• Service-HTTP-2 receives the sixth request because the service has the least
N value.
Chapter 4 Load Balancing 143
• Service-HTTP-1 receives the seventh request. Because Service-HTTP-1,
Service-HTTP-2, and Service-HTTP-3 have same N value, the NetScaler
performs load balancing in a round robin manner. Therefore, Service-
HTTP-2 receives the eighth request.
The manner in which a service receives requests based on the N value is
summarized in the following table.
Selection of services by using the least response time method when weights
are assigned
The NetScaler also performs load balancing by using the number of connections,
TTFB, and weights if different weights are assigned to the services. The
NetScaler selects the service by using the value (N
w
) of the following expression:
N
w
= (N) * (10000 / weight)
The following example shows how the NetScaler selects a service for load
balancing by using the least response time method when weights are assigned on
the services. In the preceding example, suppose Service-HTTP-1 is assigned a
weight of 2, Service-HTTP-2 is assigned weight of 3, and Service-HTTP-3 is
assigned weight of 4.
Request received Service selected Current N
(Number of active
transaction *
TTFB) value
Remarks
Request-1 Service-HTTP-3
(N =0)
N =2 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-3
(N =2)
N =4
Request-3 Service-HTTP-3
(N =3)
N =6
Request-4 Service-HTTP-1
(N =6)
N =8 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
Request-5 Service-HTTP-3
(N =6)
N =8
Request-6 Service-HTTP-2
(N =7)
N =8 Service-HTTP-2 has
the least N value.
Request-7 Service-HTTP-1
(N =8)
N =15 Service-HTTP-1,
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
Request-8 Service-HTTP-2
(N =8)
N =9
144 Installation and Configuration Guide - Volume 1
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first request because it is not handling any
active transaction.
Note: If services are not handling any active transactions, the NetScaler
selects them irrespective of the weights assigned to them.
• Service-HTTP-3 receives the second, third, fourth, and fifth requests
because the service has the least N
w
value.
• Service-HTTP-2 receives the sixth request because the service has the least
N
w
value.
• Service-HTTP-3 receives the seventh request because the service has the
least N
w
value.
• Service-HTTP-2 receives the eighth request because the service has the
least N
w
value.
Service-HTTP-1 has the least weight and the N
w
value is the highest. Therefore,
the NetScaler does not select it for load balancing.
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-3
(N
w
=0)
N
w
=2500 Service-HTTP-3 has
the least N
w
value.
Request-2 Service-HTTP-3
(N
w
=2500)
N
w
=5000
Request-3 Service-HTTP-3
(N
w
=5000)
N
w
=15000
Request-4 Service-HTTP-3
(N
w
=15000)
N
w
=20000
Request-5 Service-HTTP-3
(N
w
=20000)
N
w
=25000
Request-6 Service-HTTP-2
(N
w
=23333.34)
N
w
=26666.67 Service-HTTP-2 has
the least N
w
value.
Request-7 Service-HTTP-3
(N
w
=25000)
N
w
=30000 Service-HTTP-3 has
the least N
w
value.
Chapter 4 Load Balancing 145
The following figure illustrates how the NetScaler uses the least response time
method when weights are assigned on the services.
Least response time mechanismwhen weights are assigned
To configure the least response time method, perform the steps described in the
section “Changing the Load Balancing Algorithm” on page 132. Under LB
Method, select Least Response Time.
Request-8 Service-HTTP-2
(N
w
=26666.67)
N
w
=33333.34 Service-HTTP-2 has
the least N
w
value.
Service-HTTP-1 is selected for load balancing when it completes the active transactions
or when the N
w
value of other services (Service-HTTP-2 and Service-HTTP-3) is equal
to 105000.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
146 Installation and Configuration Guide - Volume 1
Configuring the Least Response Time Method Using
Monitors
When the NetScaler is configured to use the least response time method with
monitors, it selects the service with the least number of active transactions and the
fastest average response time of monitors. In this load balancing method the
NetScaler uses the existing monitoring infrastructure. Therefore, before you use
this method, you must bind application-specific monitors to each service, and
enable LRTM mode on these monitors. The NetScaler then makes load balancing
decisions based on the response times received from the monitoring probes. For
more information about configuring monitors, see the section “Configuring
Monitors in an LB Setup” on page 223.
Least response time method with monitors can be used to select non-HTTP and
non-HTTPS services unlike the least response time method without monitors.
You can also use this method when several monitors are bound to a service. The
vserver reads the response times of all monitors and calculates an average
response time for each service. Monitors determine response times according to
different protocols.
The following table summarizes how response times are calculated for various
monitors.
Monitor Response Time Calculation
PING Time difference between the ICMP ECHO request and the ICMP
ECHO response.
TCP Time difference between the SYN request and the SYN+ACK
response.
HTTP Time difference between the HTTP request (after the TCP
connection is established) and the HTTP response.
TCP-ENV Time 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 configuration.
HTTP-ECV Time difference between the HTTP request and the HTTP
response.
UDP-ECV Time difference between the UDP send string and the UDP receive
string.
A udp-ecv monitor without the receive string is considered to have
an incorrect configuration.
DNS Time difference between a DNS query and the DNS response.
TCPS Time difference between a SYN request and the SSL handshake
completion.
FTP Time difference between the sending of the user name and the
completion of user authentication.
Chapter 4 Load Balancing 147
The following example shows how the NetScaler selects a service for load
balancing by using the least response time method with configured monitors.
Consider three services, Service-HTTP-1, Service-HTTP-2, and
Service-HTTP-3.
• Service-HTTP-1 is handling three active transactions and the response time
is five seconds.
• Service-HTTP-2 is handling seven active transactions and the response
time is one second.
• Service-HTTP-3 is not handling any active transactions and the response
time is two seconds.
The following figure illustrates how the NetScaler uses the least response time
method and forward requests to the three services when monitors are configured
to calculate the response time.
Least response time mechanismusing monitors
HTTPS (monitors
HTTPS requests)
Time difference is same as the HTTP monitor.
HTTPS-ENV
(monitors HTTPS
requests)
Time difference is same as the HTTP-ECV monitor.
USER Time difference between the time when a request is sent to the
dispatcher and the time when the dispatcher responds.
Monitor Response Time Calculation
148 Installation and Configuration Guide - Volume 1
The NetScaler selects the service by using the value (N) of the following
expression:
N =Number of active transactions * Response time that is determined by the
monitor
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first request because the service is not
handling any active transaction.
Note: The service with no active transaction is selected first.
• Service-HTTP-3 receives the second, third, and fourth requests because the
service has the least N value.
• Service-HTTP-2 receives the fifth request because the service has the least
N value.
• Now both Service-HTTP-2 and Service-HTTP-3 have the same N value, so
the NetScaler performs load balancing in a round robin manner. Therefore,
Service-HTTP-3 receives the sixth request.
• Service-HTTP-2 receives the seventh and eighth requests because the
service has the least N value.
Service-HTTP-1 is not considered for load balancing because it is loaded more
(the highest N value) as compared to the other two services. However, if
Service-HTTP-1 completes the active transactions, the NetScaler considers the
service for load balancing.
The manner in which a service receives requests based on the N value is
summarized in the following table.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
Request-1 Service-HTTP-3
(N =0)
N =2 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-3
(N =2)
N =4
Request-3 Service-HTTP-3
(N =4)
N =6
Request-4 Service-HTTP-3
(N =6)
N =8
Chapter 4 Load Balancing 149
Selection of services by using the least response time method when weights
are assigned
The NetScaler also performs load balancing by using the number of active
transactions, response time, and weights, if different weights are assigned to the
services. The NetScaler selects the service by using the value (N
w
) of the
following expression:
N
w
= (N) * (10000 / weight)
The following example shows how the NetScaler selects a service for load
balancing by using the least response time method when weights are assigned to
the services.
In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2,
Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a
weight of 4.
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first request because it is not handling any
active transaction.
Note: If services are not handling any active transactions, the NetScaler
selects them irrespective of the weights assigned to them.
• Service-HTTP-3 receives the second, third, and fourth, requests because the
service has the least N
w
value.
• Service-HTTP-2 receives the fifth request because the service has the least
N
w
value.
Request-5 Service-HTTP-2
(N =7)
N =8 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
Request-6 Service-HTTP-3
(N =8)
N =10
Request-7 Service-HTTP-2
(N =8)
N =9 Service-HTTP-2 has
the least N value.
Request-8 Service-HTTP-1
(N =9)
N =10
Service-HTTP-1 is selected for load balancing when it completes the active transactions
or when the N value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to
15.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
150 Installation and Configuration Guide - Volume 1
• Service-HTTP-3 receives the sixth request because the service has the least
N
w
value.
• Service-HTTP-2 receives the seventh and the eighth requests because the
service has the least N
w
value.
Service-HTTP-1 has the least weight and the highest N
w
value. Therefore, the
NetScaler does not select it for load balancing.
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-3
(N
w
=0)
N
w
=5000 Service-HTTP-3 has
the least N
w
value.
Request-2 Service-HTTP-3
(N
w
=5000)
N
w
=10000
Request-3 Service-HTTP-3
(N
w
=15000)
N
w
=20000
Request-4 Service-HTTP-3
(N
w
=20000)
N
w
=25000
Request-5 Service-HTTP-2
(N
w
=23333.34)
N
w
=26666.67 Service-HTTP-2 has
the least N
w
value.
Request-6 Service-HTTP-3
(N
w
=25000)
N
w
=30000 Service-HTTP-3 has
the least N
w
value.
Request-7 Service-HTTP-2
(N
w
=23333.34)
N
w
=26666.67 Service-HTTP-2 has
the least N
w
value.
Request-8 Service-HTTP-2
(N
w
=25000)
N
w
=30000 Service-HTTP-2 has
the least N
w
value.
Service-HTTP-1 is selected for load balancing when it completes the active transactions
or when the N
w
value of other services (Service-HTTP-2 and Service-HTTP-3) is equal
to 75000.
Chapter 4 Load Balancing 151
The following figure illustrates how the NetScaler uses the least response time
method when weights are assigned on the services.
Least response time mechanismusing monitors when weights are assigned
To configure the Least response time method using monitors, perform the steps
described in the section “Changing the Load Balancing Algorithm” on page 132.
Under LB Method, select LRTM.
Configuring the Hash Methods
You can use hashing methods in a cache environment where a cache serves a
wide range of content from the Internet or origin servers. Caching the requests
reduces the request and response latency and ensures better resource utilization
(CPU) at the cache. The NetScaler provides the following hashing methods:
• URL hash method
• Domain hash method
• Destination IP hash method
• Source IP hash method
• Source IP Destination IP hash method
• Source IP Source Port hash method
• Call ID hash method
152 Installation and Configuration Guide - Volume 1
When the NetScaler is configured to use the hashing methods, it selects a service
based on the hashed value of the parameter used in that method. The NetScaler
caches the hashed value of the parameter. The subsequent requests that use the
same parameter constitute a cache hit. The NetScaler forwards these requests to
the same service. If the state of a service that is selected based on the hashed
value is DOWN or if the service is deleted, the requests that must be sent to that
service are hashed again. The NetScaler then sends these requests to the
remaining services. Also, the NetScaler updates the cache and, therefore, its
performance is degraded during high traffic.
Note: It is recommended that when you adjust server pools by removing
services, you should adjust the pools during low traffic periods to enable the
caches to repopulate without impacting the performance.
Chapter 4 Load Balancing 153
Configuring the URL Hash Method
When the NetScaler is configured to use the URL hash method, it selects a
service based on the hashed value of an incoming HTTP URL. The NetScaler
caches the hashed value of the URL, and subsequent requests that use the same
URL make a cache hit and are forwarded to the same service. By default, the
NetScaler calculates the hash value based on the first 80 bytes of the URL. You
must specify the Hash Length parameter to calculate a different URL value. If the
NetScaler cannot accurately parse the incoming request, it uses the round robin
method for load balancing. Consider a scenario where three services are bound to
a vserver and the URL hash method is configured. The services are Service-
HTTP-1, Service-HTTP-2, and Service-HTTP-3, and the hash value is URL1.
When the services are UP, URL1 is sent to Service-HTTP-1 using the hashing
result. If Service-HTTP-1 is down, the URL1 is sent to Service-HTTP-2 using the
secondary hash result, as shown in the following figure.
URL hashing
If Service-HTTP-1 and Service-HTTP-2 are down, URL1 is sent to
Service-HTTP-3. If the services are then UP, URL1 is sent to the services in the
following ways:
• If the Service-HTTP-2 is up, the URL1 is sent to Service-HTTP-2.
• If the Service-HTTP-1 is up, the URL1 is sent to Service-HTTP-1.
• If Service-HTTP-1 and Service-HTTP-2 are up at the same time, URL1 is
sent to Service-HTTP-1.
154 Installation and Configuration Guide - Volume 1
To configure the URL hash method, use the Hash Length parameter as described
in the following table.
To configure the URL hash method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select URL Hash.
Configuring the Domain Hash Method
When the NetScaler is configured to use the domain hash method, it selects a
service based on the hashed value of the domain name in the HTTP request. The
domain name is taken either from the incoming URL or from the Host header of
the HTTP 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 HTTP request does not
contain a domain name, the NetScaler defaults to the round robin method for that
request.
The hash value is calculated using the name length or hash length value,
whichever is smaller. By default, the NetScaler 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, use the Hash Length parameter.
To configure the domain hash method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select Domain Hash.
Configuring the Destination IP Hash Method
When the NetScaler is configured to use the destination IP hash method, it selects
a service based on the hashed value of the destination IP address. You can use the
subnet mask parameter to mask the destination IP address and then calculate the
hash value. When the requests from different networks arrive at the NetScaler, it
identifies the requests belonging to a subnet using the subnet mask and forwards
the requests to the same server based on the hashed value.
Parameter Description
Hash Length The number of bytes that are hashed in the URL or domain
name. Valid values are from 1 to 4K bytes. The default is
80 bytes. It must not exceed 4096 bytes.
Chapter 4 Load Balancing 155
This method is appropriate for use with the cache redirection feature of the
NetScaler. For more information about cache redirection, see the “Cache
Redirection” chapter in Citrix NetScaler Installation and Configuration Guide.
To configure the destination IP hash method, use the Netmask parameter as
described in the following table.
To configure the destination IP hash method, perform the steps described in the
section “Changing the Load Balancing Algorithm” on page 132. Under LB
Method, select Destination IP Hash.
Configuring the Source IP Hash Method
When the NetScaler is configured to use the source IP hash method, it selects a
service based on the hashed value of the client IP address. You must use the
optional subnet mask parameter to direct the requests from source IP addresses
that belong to a particular network, to one server. To configure the source IP hash
method, perform the steps described in the section “Changing the Load Balancing
Algorithm” on page 132. Under LB Method, select Source IP Hash.
Configuring the Source IP Destination IP Hash Method
When the NetScaler is configured to use the source IP destination IP hash
method, it selects a service based on the hashed value of the source and
destination IP addresses. Hashing is symmetric, so it yields the same value if the
source and destination IP addresses are reversed. This ensures that all packets
flowing from a particular client to the same destination are directed to the same
server. To configure the source IP destination IP hash method, perform the steps
described in the section “Changing the Load Balancing Algorithm” on page 132.
Under LB Method, select Source IP Destination IP Hash.
Configuring the Source IP Source Port Hash Method
When the NetScaler is configured to use the source IP source port hash method, it
selects the server based on the hash value of the source IP and source port of the
incoming request. This ensures that all packets on a particular connection are
directed to the same server. This method is used in the connection Mirroring and
firewall load balancing. For more information about connection Mirroring, see
the section “Configuring Stateful Connection Failover” on page 191.
To configure the source IP source port hash method, perform the steps described
in the section “Changing the Load Balancing Algorithm” on page 132. Under LB
Method, select Source IP Source Port Hash.
Parameter Description
Netmask Masks the destination IP address before calculating the
hash value so that all IP addresses belonging to a particular
network are directed to the same server.
156 Installation and Configuration Guide - Volume 1
Configuring the Call ID Hash Method
When the NetScaler is configured to use the call ID hash method, it selects the
service based on the hash value of the call ID in the SIP header, so that a
particular SIP session is directed to the same proxy server. This method is
applicable for SIP load balancing. For more information about SIP load
balancing, see the section “Monitoring SIP Services” on page 235. To configure
the call ID hash method, perform the steps described in the section “Changing the
Load Balancing Algorithm” on page 132. Under LB Method, select Call ID
Hash.
Configuring the Least Bandwidth Method
When the NetScaler is configured to use the least bandwidth method, it selects the
service that is currently serving the least amount of traffic, measured in megabits
per seconds (Mbps). The following example shows how the NetScaler selects a
service for load balancing by using the least bandwidth method.
Example:
Consider three services, Service-HTTP-1, Service-HTTP-2, and
Service-HTTP-3.
• Service-HTTP-1 has 3 Mbps bandwidth.
• Service-HTTP-2 has 5 Mbps bandwidth.
• Service-HTTP-3 has 2 Mbps bandwidth.
Chapter 4 Load Balancing 157
The following figure illustrates how the NetScaler uses the least bandwidth
method to forward requests to the three services.
Least bandwidth mechanism
The NetScaler selects the service by using the bandwidth value (N) which is the
sum of the number of bytes transmitted and received per 14 second. If each
request requires 1 Mbps bandwidth, the NetScaler delivers the requests as
follows:
• Service-HTTP-3 receives the first request because the service has the least
N value.
• Now Service-HTTP-1 and Service-HTTP-3 have same N value and the
NetScaler performs load balancing in a round robin manner.
Service-HTTP-1 receives the second request, Service-HTTP-3 receives the
third request, Service-HTTP-1 receives the fourth request, Service-HTTP-3
receives the fifth request, Service-HTTP-1 receives the sixth request.
• Now Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same N
value and the NetScaler performs load balancing in a round robin manner.
So, Service-HTTP-2 receives the seventh request, and
Service-HTTP-3 receives the eighth request.
158 Installation and Configuration Guide - Volume 1
The manner in which a service receives requests based on the N value is
summarized in the following table.
Selection of services by using the least bandwidth method when weights are
assigned
The NetScaler also performs load balancing by using the bandwidth and weights
if different weights are assigned to the services. The NetScaler selects the service
by using the value (N
w
) of the following expression:
N
w
= (N) * (10000 / weight)
The following example shows how the NetScaler selects a service for load
balancing by using the least bandwidth method when weights are assigned on the
services.
Example:
In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2,
Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a
weight of 4.
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first second, third, fourth, and fifth requests
because the service has the least N
w
value.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
Request-1 Service-HTTP-3
(N =2)
N =3 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-1
(N =3)
N =4 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
Request-3 Service-HTTP-3
(N =3)
N =4
Request-4 Service-HTTP-1
(N =4)
N =5
Request-5 Service-HTTP-3
(N =4)
N =5
Request-6 Service-HTTP-1
(N =5)
N =6 Service-HTTP-1,
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
Request-7 Service-HTTP-2
(N =5)
N =6
Request-8 Service-HTTP-3
(N =5)
N =6
Chapter 4 Load Balancing 159
• Service-HTTP-1 receives the sixth request because the service has the least
N
w
value.
• Service-HTTP-3 receives the seventh request because the service has the
least N
w
value.
• Service-HTTP-2 receives the eighth request because the service has the
least N
w
value.
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-3
(N
w
=5000)
N
w
=5000 Service-HTTP-3 has
the least N
w
value.
Request-2 Service-HTTP-3
(N
w
=5000)
N
w
=7500
Request-3 Service-HTTP-3
(N
w
=7500)
N
w
=10000
Request-4 Service-HTTP-3
(N
w
=10000)
N
w
=12500
Request-5 Service-HTTP-3
(N
w
=12500)
N
w
=15000
Request-6 Service-HTTP-1
(N
w
=15000)
N
w
=20000 Service-HTTP-1 and
Service-HTTP-3
have the same N
w

value.
Request-7 Service-HTTP-3
(N
w
=15000)
N
w
=17500
Request-8 Service-HTTP-2
(N
w
=16666.67)
N
w
=20000 Service-HTTP-2 has
the least N
w
value.
160 Installation and Configuration Guide - Volume 1
The following figure illustrates how the NetScaler uses the least bandwidth
method when weights are assigned on the services.
Least bandwidth mechanismwhen weights are assigned
To configure the least bandwidth method, perform the steps described in the
section “Changing the Load Balancing Algorithm” on page 132. Under LB
Method, select Least Bandwidth.
Configuring the Least Packets Method
When the NetScaler is configured to use the least packets method, it selects the
service that is currently serving the least packets in last 14 seconds second. The
following example shows how the NetScaler selects a service for load balancing
by using the least packets method.
Example:
Consider three services, Service-HTTP-1, Service-HTTP-2, and
Service-HTTP-3.
• Service-HTTP-1 is handling three packets in last 14 seconds.
• Service-HTTP-2 is handling five packets in last 14 seconds.
• Service-HTTP-3 is handling two packets in last 14 seconds.
Chapter 4 Load Balancing 161
The following figure illustrates how the NetScaler uses the least packets method
and forward requests to the three services.
Least packets mechanism
The NetScaler selects the service by using the number of packets (N) which is the
sum of number of packets transmitted and received in last 14 seconds.
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first request because the service has the least
N value.
• Now Service-HTTP-1 and Service-HTTP-3 have same N value and the
NetScaler performs load balancing in a round robin manner.
Service-HTTP-1 receives the second request, Service-HTTP-3 receives the
third request, Service-HTTP-1 receives the fourth request, Service-HTTP-3
receives the fifth request, Service-HTTP-1 receives the sixth request.
• Now Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same N
value and the NetScaler performs load balancing in a round robin manner.
So, Service-HTTP-2 receives the seventh request, and
Service-HTTP-3 receives the eighth request.
162 Installation and Configuration Guide - Volume 1
The manner in which a service receives requests based on the N value is
summarized in the following table.
Selection of services by using the least packets method when weights are
assigned
The NetScaler also performs load balancing by using the number of packets, and
weights if different weights are assigned to the services. The NetScaler selects the
service by using the value (N
w
) of the following expression:
N
w
= (N) * (10000 / weight)
The following example shows how a NetScaler selects a service for load
balancing by using the least packets method when weights are assigned on the
services.
Example:
In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2,
Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a
weight of 4.
The NetScaler delivers the requests as follows:
• Service-HTTP-3 receives the first second, third, fourth, and fifth requests
because the service has the least N
w
value.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
Request-1 Service-HTTP-3
(N =2)
N =3 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-1
(N =3)
N =4 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
Request-3 Service-HTTP-3
(N =3)
N =4
Request-4 Service-HTTP-1
(N =4)
N =5
Request-5 Service-HTTP-3
(N =4)
N =5
Request-6 Service-HTTP-1
(N =5)
N =6 Service-HTTP-1,
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
Request-7 Service-HTTP-2
(N =5)
N =6
Request-8 Service-HTTP-3
(N =5)
N =6
Chapter 4 Load Balancing 163
• Service-HTTP-1 receives the sixth request because the service has the least
N
w
value.
• Service-HTTP-3 receives the seventh request because the service has the
least N
w
value.
• Service-HTTP-2 receives the eighth request because the service has the
least N
w
value.
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-3
(N
w
=5000)
N
w
=5000 Service-HTTP-3 has
the least N
w
value.
Request-2 Service-HTTP-3
(N
w
=5000)
N
w
=7500
Request-3 Service-HTTP-3
(N
w
=7500)
N
w
=10000
Request-4 Service-HTTP-3
(N
w
=10000)
N
w
=12500
Request-5 Service-HTTP-3
(N
w
=12500)
N
w
=15000
Request-6 Service-HTTP-1
(N
w
=15000)
N
w
=20000 Service-HTTP-1 and
Service-HTTP-3
have the same N
w

value.
Request-7 Service-HTTP-3
(N
w
=15000)
N
w
=17500
Request-8 Service-HTTP-2
(N
w
=16666.67)
N
w
=20000 Service-HTTP-2 has
the least N
w
value.
164 Installation and Configuration Guide - Volume 1
The following figure illustrates how the NetScaler uses the least packets method
when weights are assigned on the services.
Least packets mechanismwhen weights are assigned
To configure the least packets method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select Least Packets.
Configuring the Token Method
When the NetScaler is configured to use the token method, it selects a service
based on the value of a token extracted from the client request. You can configure
the location and size of the token. For subsequent requests with the same token,
the NetScaler chooses the same server that handled the initial request.
This method is content aware. This means that it operates differently for the TCP,
HTTP, and HTTPS service types. For HTTP or HTTPS services, the token is
found in the HTTP headers or the URL or the BODY using the configured
expressions.
Parameter Description
Rule The string value. The string can be an existing rule name,
or it can be an inline expression with a maximum of 256
characters. The default string value is none. The maximum
length of the string value is 14999.
Chapter 4 Load Balancing 165
Expressions can be Classic or Advanced. Advanced expressions do not need to
have rules. For more information about expressions, see the chapter “Policies and
Expressions” in the Citrix NetScaler Installation and Configuration Guide.
For example, if you are load balancing a set of servers that contain Web content,
and you want to configure the NetScaler to search for the token inside a URL
query in each request. The NetScaler searches the token inside the URL query
after matching the string token.
For HTTP services, the NetScaler searches for the configured token in the first 24
KB of the TCP payload. For non-HTTP (TCP, SSL, and SSL_TCP) services, the
NetScaler 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.
To configure the location and size of the token, use the parameters as described in
the following table.
You can use this load balancing method across vservers of different types to
ensure that requests presenting the same token are directed to the services on the
same servers, regardless of the protocol used.
For example, the server server-1 has two services Service-HTTP-1 and Service-
TCP-1, and the server server-2 has two services Service-HTTP-2 and Service-
TCP-2. The TCP services are bound to Vserver-LB-2, and the HTTP services are
bound to Vserver-LB-1.
Parameters Descriptions
Data Length The length of the token in bytes. This parameter is applicable to
TCP virtual servers when the Token method is selected. The
minimum value is 0 and the maximum value is 100.
Data Offset Offset of the data to be taken as a token. This parameter is
applicable to the TCP type virtual servers when the Token load
balancing method is used and must be within the first 24k of the
client TCP data. The minimum value is 0, and the maximum value
is 25400.
166 Installation and Configuration Guide - Volume 1
A request sent to Vserver-LB-1 with the token “AA” selects the service Service-
HTTP-1 (bound to server-1) to process the request. A different request sent to
Vserver-LB-2 with the same token “AA” directs this request to the service
Service-TCP-1, as shown in the following figure.
Working of token method
To configure the token method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select Token. You must configure a rule to configure a token.
To configure a rule using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver, Vserver-LB-1 and click Open. The Configure Virtual
Server (Load Balancing) dialog box appears.
3. Click the Method and Persistence tab and under LB Method, select
Token. The Rule text box appears.
4. Click Configure and the Create Expression dialog box appears.
5. Under Expression, click Add. The Add Expression dialog box appears.
6. In the Qualifier and Operator lists, select URLQUERY and CONTAINS
and in the Value text box, type AA.
7. Click OK and click Close. The expression you created appears in the
Expression list box.
Chapter 4 Load Balancing 167
8. Click Create. The expression you created appears in the Rule text box.
Click OK.
Configuring the CustomLoad Method
Generally, the NetScaler selects a service that is not handling any active
transaction. If the services are handling active transactions, the NetScaler selects
a service based on its load. A special type of monitor, known as a load monitor,
calculates the load on each service in the network. The load monitors do not mark
the state of a service; however, they take the service out of the load balancing
decision. Custom load balancing is performed on server parameters such as CPU
usage, memory, and response time. For more information about load monitors,
see “Configuring Load Monitors” on page 252. The following diagram illustrates
how a load monitor operates.
Working of load monitors
The load monitor uses an SNMP probe to calculate the load on the service. To
accomplish this, the monitor sends an SNMP GET request to the server. This
request contains one or more object IDs (OID). The server then sends back an
SNMP GET response with metrics corresponding to the SNMP OIDs. The
monitor calculates the load on each service based on the metrics in the response
message and parameters such as pre-configured threshold and weight as
described later in the chapter.
The load monitor calculates the load on a service using the following parameters:
• Metrics values retrieved through SNMP probes that exist as tables in the
NetScaler
• Threshold value set for each metric
• Weight assigned to each metric
168 Installation and Configuration Guide - Volume 1
The following example shows how the NetScaler selects a service for load
balancing by using the custom load method.
Example:
Consider three services, Service-HTTP-1, Service-HTTP-2, and
Service-HTTP-3.
• Service-HTTP-1 is using 20 MB of memory.
• Service-HTTP-2 is using 70 MB of memory.
• Service-HTTP-3 is using 80 MB of memory.
The servers can export metrics such as CPU and memory usage. The load monitor
sends an SNMP GET request containing the OIDs 1.3.6.1.4.1.5951.4.1.1.41.1.5,
1.3.6.1.4.1.5951.4.1.1.41.1.4, and 1.3.6.1.4.1.5951.4.1.1.41.1.3 to the servers.
The three services respond to the request. The NetScaler compares the exported
metrics to select Service-HTTP-1 because it has more memory for processing
requests. The following figure illustrates how the NetScaler uses the custom load
method and forward requests to the three services.
Customload mechanism
The NetScaler selects the service by using the load (N). If each request uses 10
MB memory, the NetScaler delivers the requests as follows:
• Service-HTTP-1 receives the first, second, third, fourth, and fifth requests
because the service has the least N value.
• Now, Service-HTTP-1 and Service-HTTP-2 have same load and the
NetScaler selects the service in round robin manner. Therefore,
Chapter 4 Load Balancing 169
Service-HTTP-2 receives the sixth request and Service-HTTP-1 receives
the seventh request.
• Now, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same
load and the NetScaler selects the service in round robin manner. Therefore,
Service-HTTP-1 receives the eighth request.
The manner in which a service receives requests based on the N value is
summarized in the following table.
Selection of services by using the custom load method when weights are
assigned
The NetScaler also performs load balancing by using the load on services, and
weights if different weights are assigned to the services. The NetScaler selects the
service by using the value (N
w
) of the following expression:
N
w
= (N) * (10000 / weight)
The following example shows how the NetScaler selects a service for load
balancing by using the custom load method when weights are assigned on the
services.
Request received Service selected Current N
(Number of active
transaction) value
Remarks
Request-1 Service-HTTP-1
(N =20)
N =30 Service-HTTP-3 has
the least N value.
Request-2 Service-HTTP-1
(N =30)
N =40
Request-3 Service-HTTP-1
(N =40)
N =50
Request-4 Service-HTTP-1
(N =50)
N =60
Request-5 Service-HTTP-1
(N =60)
N =70
Request-6 Service-HTTP-1
(N =70)
N =80 Service-HTTP-2 and
Service-HTTP-3
have the same N
values.
Request-7 Service-HTTP-2
(N =70)
N =80
Request-8 Service-HTTP-1
(N =80)
N =90 Service-HTTP-1,
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
170 Installation and Configuration Guide - Volume 1
Example:
In the preceding example, suppose Service-HTTP-1 is assigned a weight of 4,
Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a
weight of 2. If each request uses 10 MB memory, the NetScaler delivers the
requests as follows:
• Service-HTTP-1 receives the first, second, third, fourth, fifth, sixth,
seventh, and eighth requests because the service has the least N
w
value.
• Service-HTTP-2 receives the ninth request because the service has the least
N
w
value.
Service-HTTP-3 has the highest N
w
value and is not considered for load
balancing.
The manner in which a service receives requests based on the N
w
value is
summarized in the following table.
Request received Service selected Current N
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
Request-1 Service-HTTP-1
(N
w
=50000)
N
w
=75000 Service-HTTP-1 has
the least N
w
value.
Request-2 Service-HTTP-1
(N
w
=5000)
N
w
=100000
Request-3 Service-HTTP-1
(N
w
=15000)
N
w
=125000
Request-4 Service-HTTP-1
(N
w
=20000)
N
w
=150000
Request-5 Service-HTTP-1
(N
w
=23333.34)
N
w
=175000
Request-6 Service-HTTP-1
(N
w
=25000)
N
w
=200000
Request-7 Service-HTTP-1
(N
w
=23333.34)
N
w
=225000
Request-8 Service-HTTP-1
(N
w
=25000)
N
w
=250000
Request-9 Service-HTTP-2
(N
w
=233333.34)
N
w
=266666.67 Service-HTTP-2 has
the least N
w
value.
Service-HTTP-1 is selected for load balancing when it completes the active transactions
or when the N
w
value of other services (Service-HTTP-2 and Service-HTTP-3) is equal
to 400000.
Chapter 4 Load Balancing 171
The following figure illustrates how the NetScaler uses the custom load method
when weights are assigned on the services.
CustomLoad mechanismwhen weights are assigned
To configure the custom load method, perform the steps described in the section
“Changing the Load Balancing Algorithm” on page 132. Under LB Method,
select Custom Load.
Configuring Persistent Connections Between
Clients and Servers
The NetScaler initially selects a server by using the LB methods. With persistence
configured, enabling the NetScaler to send any subsequent client requests to the
selected server, the server can access state information for that client.
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 NetScaler uses the load balancing methods to select a new service, and
the new service becomes persistent for subsequent requests from the client. If the
state selected service is out of service, it continues to serve the outstanding
requests, but doesn’t allow new requests or connections directed to it. After the
shutdown period elapses, no new requests or connections are directed to the
service and the existing connections are closed.
172 Installation and Configuration Guide - Volume 1
You can configure different types of persistence on the NetScaler. The following
table lists the persistence types and indicates if the persistence type consumes
resources.
Configuring Persistence Types
If the configured persistence cannot be maintained because of lack of resources
on the NetScaler, 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 vservers. The
following table shows the relationship.
To configure persistence, you must use the parameters as described in the
following table.
Persistence Type Persistent Connections
Source IP, SSL Session ID, Rule, DESTIP,
SRCIPDESTIP
250 K
CookieInsert, Custom Server ID, URL
passive
Memory limit. In case of CookieInsert, if
time out is not 0, any number of
connections are allowed until limited by
memory.
Persistence Type HTTP HTTPS TCP User
Datagram
Protocol
(UDP)/IP
SSL_Bridge
Source IP YES YES YES YES YES
CookieInsert YES YES NO NO NO
SSL Session ID NO YES NO NO YES
URL passive YES YES NO NO NO
Custom Server ID YES YES NO NO NO
Rule YES YES NO NO NO
SRCIPDESTIP NA NA YES YES NA
DESTIP NA NA YES YES NA
Parameter Description
Persistence Type Persistence type for the vserver. The valid options for this
parameter are:
SOURCEIP, COOKIEINSERT, SSLSESSION, RULE,
URLPASSIVE, CUSTOMSERVERID, DESTIP,
SRCIPDESTIP, CALLID, NONE (default)
Chapter 4 Load Balancing 173
The following example describes the steps to set SOURCEIP persistence on the
vserver Vserver-LB-1, with a persistence mask of 255.255.255.255 and a timeout
of 2 minutes.
To configure persistence on vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure persistence, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Method and Persistence tab.
5. In the Persistence list, select SOURCEIP.
6. In the PersistMask and Timeout text boxes type the subnet mask and
timeout values, for example, 255.255.255.255 and 2.
7. Click OK.
To configure persistence on vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -persistenceType SOURCEIP
Configuring Persistence Based on Source IP Addresses
the NetScaler selects a service based on the load balancing method, and uses the
source IP address of the selected service to send the subsequent requests. The
NetScaler creates a session between the client and the servers using the IP
address. Using persistence based on source IP address overloads the servers
because the connections are routed through the single gateway. In the multiple
proxy environments, the client requests arrive at a Web site with different IP
addresses. This restriction is known as Mega Proxy problem. You can use
CookieInsert persistence to solve this problem.
Persistence Mask Persistence Mask is used to specify if the persistence is IP-
based. The default value is 255.255.255.255. If you set 0
using this parameter the complete IP address is used for
persistence.
Timeout The time period for which persistence is in effect for a
specific client. The default value is 2 minutes, and the
maximum value that can be configured is 1440 minutes.
Parameter Description
174 Installation and Configuration Guide - Volume 1
You can set a timeout value for this type of persistence that specifies the inactivity
period for the session. When the timeout value expires, the session is discarded,
and a new server is selected based on the configured load balancing method.
To configure persistence based on Source IP Addresses, perform the steps
described in the section “Configuring Persistence Types” on page 172. In the
Persistence list, select SOURCEIP.
Configuring Persistence Based on HTTP Cookies
The NetScaler adds an HTTP cookie into the Set-Cookie header field of the
HTTP response. The cookie contains information about the service where the
HTTP requests must be sent. The client stores the cookie and includes it in all
subsequent requests. The NetScaler uses this cookie to select the service for
subsequent requests. You can use this persistence on vservers of type HTTP or
HTTPS.
The NetScaler inserts the cookie NSC_XXXX=<ServiceIP ><ServicePort>
where
• NSC_XXXX is the vserver ID that is derived from the vserver name
• ServiceIP is a representation of the IP address of the service
• ServicePort is a representation of the port of the service
ServiceIP and ServicePort are encrypted and inserted. When the NetScaler
receives a cookie, it decrypts the cookie.
Note: If the client is not allowed to store the HTTP cookie, the subsequent
requests do not have the HTTP cookie, and persistence is not honored.
By default, the NetScaler sends an HTTP cookie with version 0, in compliance
with the Netscape specification. The NetScaler can also send HTTP cookies with
version 1, in compliance with RFC 2109.
You can configure a timeout value for persistence that is based on HTTP cookies.
Note the following:
• If HTTP cookie version 0 is used, the NetScaler inserts the absolute
Coordinated Universal Time (GMT) of the cookie expiration time (the
“expires” attribute of the HTTP cookie) that is calculated as the sum of the
current GMT time on the NetScaler, and the timeout value.
• If an HTTP cookie version 1 is used, the NetScaler inserts a relative
expiration time (“Max-Age” attribute of the HTTP cookie). In this case, the
client software calculates the actual expiration time.
Chapter 4 Load Balancing 175
Note: Most client software currently installed (Microsoft Internet Explorer and
Netscape browsers) understand HTTP cookie version 0; however, some HTTP
proxies understand HTTP cookie version 1.
When you set the timeout value to 0, the NetScaler does not specify the expiration
time, regardless of the HTTP cookie version used. The expiration time depends
on the client software, and such cookies are not valid when the software is shut
down. This persistence type does not consume any NetScaler resources. Hence, it
can accommodate an unlimited number of persistent clients.
To configure persistence based on HTTP Cookie, perform the steps described in
the section “Configuring Persistence Types” on page 172. In the Persistence list,
select COOKIEINSERT.
Configuring Persistence Based on SSL Session IDs
the NetScaler creates a session-based persistence on the arriving SSL Session ID
that is part of the SSL handshake process. The requests with the same SSL
session ID are directed to the initially selected service. This persistence is used
for SSL bridge type of services and the NetScaler does not encrypt or decrypt
data when it forwards the requests to the services. The NetScaler must maintain
the data structures to keep track of the sessions. Thus, the persistence type
consumes NetScaler resources. Also, if the SSL sessions re-negotiate the session
IDs during the transactions, the persistence based on SSL session-id does not
function correctly.
The timeout value for this type of persistence is as described in the section
“Configuring Persistence Based on Source IP Addresses” on page 173. To
configure persistence based on SSL session IDs, perform the steps described in
the section “Configuring Persistence Types” on page 172. In the Persistence list,
select SSLSESSION.
Configuring Persistence Based on User-Defined Rules
the NetScaler maintains persistence based on the contents of the matched rule.
This persistence type requires configuration of a payload expression or a policy
infrastructure expression. The expression is evaluated and if the request matches
the criteria, a persistence session is created. The subsequent client requests are
directed to the previously selected server. To configure rule-based persistence,
use the Rule parameter as described in the following table.
Parameter Description
Rule The string value used to set the RULE persistence type.
The string can be an existing rule name, or it can be an
inline expression with a maximum of 256 characters. The
default value is none. The maximum length is 14999.
176 Installation and Configuration Guide - Volume 1
Example: Payload Expression
The expression, “httpheader User-Agent contains MyBrowser” directs any client
requests containing, “User-Agent: MyBrowserV1.1” to the initially selected
server.
Example: Advanced Expression
The expression, “HTTP.REQ.HEADER (“User-Agent”).CONTAINS
(“MyBrowser”) directs client requests containing, “User-Agent:
MyBrowserV1.1” to the initially selected server.
The timeout value for this type of persistence is as described in the section
“Configuring Persistence Based on Source IP Addresses” on page 173. To
configure persistence based on user-defined rules, perform the steps described in
the section “Configuring Persistence Types” on page 172. In the Persistence list,
select RULE.
Configuring Persistence based on Server-IDs in URLs
the NetScaler can maintain persistence based on the server ID in the URLs. In a
technique called URL passive persistence type, the NetScaler extracts the server
ID from the server response and embeds it in the URL query of the client request.
The server ID is its IP address and port specified as a hexadecimal number. The
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 the “Policies and
Expressions” chapter in the Citrix NetScaler Installation and Configuration
Guide, Volume 1.
Note: If the server ID cannot be extracted from the client requests, server
selection is based on the load balancing method.
Example: Payload Expression
The expression, URLQUERY cont ai ns si d=configures the NetScaler to
extract the server ID from the URL query of a client request, after matching token
si d=. Thus, a request with the URL
http://www.citrix.com/ index.asp?&sid=c0a864100050 is directed to the server
with the IP address 10.102.29.10 and port 80.
The timeout value does not affect this persistence type. This persistence type is
maintained as long as the server ID can be extracted from the client requests. This
persistence type does not consume any NetScaler resources, so it can
accommodate an unlimited number of persistent clients.
Chapter 4 Load Balancing 177
To configure persistence based on server IDs in a URL, perform the steps
described in the section “Configuring Persistence Types” on page 172. In the
Persistence list, select URLPASSIVE.
Configuring Persistence based on Server-IDs in Client Requests
the NetScaler maintains persistence based on the Server ID that you provide. The
persistence type requires you to provide the server ID and embeds the server ID
in the response. The NetScaler extracts the server ID from subsequent requests
and uses it to choose a server. The Server ID value must be in the range 0 through
65535. You must configure the same number in the NetScaler for the
corresponding service. This persistence type is called Custom Server ID
persistence.
The Custom Server ID persistence type requires a payload expression, or an
advanced expression to be configured that specifies the location of the Server ID
in the client requests. For more information about expressions, see the “Policies
and Expressions” chapter.
Note the following:
• If a Server ID cannot be extracted from the client requests, server selection
is performed based on the load balancing method.
• Avoid using the same Server ID for multiple services.
Example: Payload Expression
Two servers, server-1 and server-2 are configured, where server-1 has the Server-
ID=5 and server-2 has the Server-ID=6. The services in these servers are bound to
the vserver Vserver-LB-1.
The expression “URLQUERY contains sid=” configures the NetScaler to extract
the Server-ID from the URL query of the client requests, after matching token
“sid=”. Thus a request with the URL http://www.citrix.com/ index.asp?&sid=6
that arrives on Vserver-LB-1 is directed to the server server-2.
The timeout value does not affect this persistence type. Persistence is maintained
for as long as a Server ID can be extracted from the client requests. This
persistence type does not consume any NetScaler resources, so it can
accommodate an unlimited number of persistent clients.
To configure persistence based on server IDs in client requests, perform the steps
described in the section “Configuring Persistence Types” on page 172. In the
Persistence list, select CUSTOMSERVERID.
Configuring Persistence Based on Destination IP Addresses
This persistence type is used with link load balancing. With DESTIP configured,
the NetScaler chooses a service based on the configured load balancing method.
It then directs all subsequent packets to the selected service.
178 Installation and Configuration Guide - Volume 1
The timeout value for this type of persistence is as described in the section
“Configuring Persistence Based on Source IP Addresses” on page 173. To
configure persistence based on destination IP addresses, perform the steps
described in the section “Configuring Persistence Types” on page 172. In the
Persistence list, select DESTIP.
Configuring Persistence Based on Source and Destination IP
Addresses
With SRCIPDESTIP configured, the NetScaler chooses a service based on the
configured load balancing method and directs subsequent packets with the same
source and destination IP addresses to the same service.
The timeout value for this type of persistence is as described in the section
“Configuring Persistence Based on Source IP Addresses” on page 173. To
configure persistence based on source and destination IP addresses, perform the
steps described in the section “Configuring Persistence Types” on page 172. In
the Persistence list, select SRCIPDESTIP.
Configuring Backup Persistence
The NetScaler uses the backup persistence option when the primary persistence
fails. For example, the primary persistence type is set to Cookie Insert, and
backup persistence is set to Source IP. When the client browsers do not support
cookies, Source IP persistence is used. To set the Backup persistence option to
Source IP, you must set the primary persistence to Cookie Insert.
Note: If the traffic comes from behind a NAT device or proxy, the traffic
appears to come from a single source IP address and cannot distributed evenly.
Backup persistence has a timeout value that you can set only when the primary
persistence type is set to COOKIEINSERT, and the backup persistence type is set
to SOURCEIP. To configure backup persistence, use the backup persistence
parameter as described in the following table.
Parameter Description
Backup Persistence The backup persistence type for the group. The valid
options for this parameter are SOURCEIP and NONE.
Chapter 4 Load Balancing 179
The following example describes the steps to set the primary persistence for
vserver Vserver-LB-1 to CookieInsert and the backup persistence to SOURCEIP.
The timeout and the backup persistence timeout are set to 20 minutes. The subnet
mask is set to 255.255.255.255.
To set backup persistence for a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure backup persistence, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Method and Persistence tab.
5. In the Persistence list, select COOKIEINSERT and in the Timeout text
box type the timeout value, for example, 20.
6. In the Backup Persistence list, select the backup persistence that you want
to configure, for example, SOURCEIP.
7. In the Backup Timeout and Netmask text boxes type the backup timeout
value and netmask, for example, 20 and 255.255.255.255 Click OK.
To set backup persistence for a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -persistenceType CookieInsert
-persistenceBackup SourceIP
Configuring Persistence Groups
You can aggregate vservers into groups and specify a persistence method. You
bind vservers using different protocols in one group and configure persistence
across the different protocols. When persistence is set on the group of vservers,
client requests are directed to the same selected server, regardless of the vserver
in the group that receives the client request. When persistence is set on the group
of vserver, it overrides the persistence set on individual vservers.
Note: When all vservers are removed from the group, the group is also
removed.
180 Installation and Configuration Guide - Volume 1
The persistence types allowed on the groups of vservers are:
• Source IP
• Cookie Insert
If you set Cookie Insert persistence, the domain attribute of the HTTP cookie is
configured. This setting causes the client software to add the HTTP cookie into
client requests if different vservers have different public host names. For more
information about Cookie Insert persistence type, see the section “Configuring
Persistence Based on HTTP Cookies” on page 174.
After you set persistence for the entire group, you cannot change it for individual
vservers in the group. If you set persistence on the group of vservers, and a new
vserver is added to the group, the persistence of the new vserver is changed to
persistence of the group.
Note: If you set group persistence to NONE, the persistence on the individual
virtual servers is applied.
To create groups of virtual servers, use the parameters as described in the
following table.
The following example describes the steps to create the vserver group Vserver-
Group-1 and bind the vserver Vserver-LB-1 to Vserver-Group-1. The persistence
type is Source IP, and the persistence mask is 255.255.255.255. The timeout is 2
minutes.
To create a vserver group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Persistency
Groups. The Persistency Groups page appears in the details pane.
2. Click Add. The Create Virtual Server Group dialog box appears.
Parameters Descriptions
Name The unique name of the group. This name must not exceed
31 characters.
Persistence Type The Persistence type for the group. The valid options for
this parameter are: SOURCEIP, COOKIEINSERT, and
NONE.
Persistence Mask The netmask to be applied when the persistency type is
SOURCEIP.
Timeout The time period for which the persistence is in effect for a
specific client. The value ranges from 2 to 1440 minutes.
The default value is 2minutes. The maximum value is
1440 minutes (1 day).
Chapter 4 Load Balancing 181
3. In the Group Name text box type the name, for example,
Vserver-Group-1.
4. In the Persistence list, select a persistence type, for example, SOURCEIP.
5. In the Persistence Mask and Timeout text boxes type the persistence mask
and timeout values, for example, 255.255.255.255 and 2.
6. Under Virtual Server List, in the Available Virtual Server list box, select
the vserver that you want to bind to the group, for example, Vserver-LB-1.
7. Click Add. Vserver-LB-1 appears in the Configured Virtual Server list
box.
8. Click Create and click Close. The vserver group you created appears in the
Persistence Groups page, as shown in the following figure.
Persistence groups page
To create a vserver group using the NetScaler command line
At the NetScaler command prompt, type:
bind lb group Vserver-Group-1 Vserver-LB-1 -persistenceType
CookieInsert
You can change the backup persistence, backup persistence timeout, and cookie
domain value. To modify the persistence groups use the parameters as described
in the following table.
Parameters Descriptions
Persistence Backup The backup persistence type for the group. The valid
options for this parameter are: SOURCEIP and NONE
Backup Persistence
Timeout
The maximum time for which the backup persistence is in
effect for a specific client. The default value is 2minutes.
The maximum value is 1440 minutes.
182 Installation and Configuration Guide - Volume 1
The following example describes the steps to set the vserver group Vserver-
Group-1 with persistence type COOKIEINSET, backup persistence type
SOURCEIP, and backup persistence mask 255.255.255.255.
To modify a vserver group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Persistence
Groups. The Persistence Groups page appears in the details pane.
2. Select the vserver group that you want to modify for example,
Vserver-Group-1.
3. Click Open. The Configure Virtual Server Group dialog box appears.
4. In the Backup Persistence list, select the type of backup persistence, for
example, SOURCEIP.
5. In the Persistence Mask text box, type the subnet mask, for example,
255.255.255.255.
6. Click OK.
To modify a vserver group using the NetScaler command line
At the NetScaler command prompt, type:
set lb group vserver-Group-1 -PersistenceBackUP SourceIP
-persistMask 255.255.255.255
Configuring the Redirection Mode
The redirection mode determines the destination address to forward the incoming
traffic. The NetScaler provides the following redirection modes:
• IP based (default)
• MAC based
By default, the NetScaler uses IP based mode. You can set MAC based
forwarding in case of direct server return topology, link load balancing, and
firewall load balancing.
Cookie Domain The domain attribute of the HTTP cookie.
Parameters Descriptions
Chapter 4 Load Balancing 183
For more information on MAC based forwarding, see the Basic Network
Configuration chapter of Installation and Configuration guide. To configure the
redirection mode for the load balancing setup, you must use the parameter listed
in the following table.
The following example describes the steps to configure the MAC Based
redirection mode for the vserver Vserver-LB-1.
To set a vserver for redirection using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure the redirection mode, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Under Redirection Mode, select the MAC Based radio button.
6. Click OK.
To set a vserver for redirection using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -m MAC
Parameter Description
Redirection Mode The LB mode.
If the value is specified as IP-based, then destination IP
address is changed to the IP address of the server and the
traffic is sent to the servers.
If the value is MAC-based, the destination MAC address is
changed to the MAC address of the server and the traffic is
sent to the server. The destination IP address is not
changed.
184 Installation and Configuration Guide - Volume 1
Assigning Weights to Services
You can assign weights to services to prioritize the services. If you use a load
balancing method (for example, round robin) that supports weighting of servers,
you must assign a weight to the service. Assigning weights to services allows the
NetScaler to balance the load on the service using the weights. The services with
less weight serve least requests. The following table describes the load balancing
methods and the manner in which the NetScaler selects the services when you
configure weights.
To configure weight, use the Weights parameter as described in the following
table.
The following example describes the steps to assign relative weight of 10 to the
service Service-HTTP-1.
To set a vserver to assign weights to services using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver, for example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears. The services appear in the Services tab.
Load Balancing Methods Selection of services when weights are configured
Round Robin The NetScaler selects services sequentially with the
highest weight.
Least Connections The NetScaler selects services with the least number of
active transactions and the highest weight.
Least Response Time and
Least Response Time Method
using Monitors
The NetScaler selects services with the least number of
active transactions, the fastest average response time,
and the highest weight.
Least Bandwidth The NetScaler selects services with the least traffic and
the highest weight.
Least Packets The NetScaler selects services with the least number of
packets and the highest weight.
Least Load The NetScaler selects services with the least load and
the highest weight.
Hashing and Token The NetScaler does not use weights to select services.
Parameter Description
Weights The weight for the specified service. The minimum value is
1 and the maximum value is 100.
Chapter 4 Load Balancing 185
4. In the Weights spin box, type or select the weight of a service, for example,
10 next to Service-HTTP-1.
5. Click OK.
To set a vserver to assign weights to services using the NetScaler command
line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -weight 10 Service-HTTP-1
Protecting the Load Balancing Configuration against
Failure
This section describes procedures to protect the LB setup against failure. The LB
setup can fail when a vserver fails, or when the vserver is unable to handle
excessive traffic. Protecting the LB setup against failure helps ensure the
availability of the setup.
Topics include:
• Redirecting Client Requests to an Alternate URL
• Configuring a Backup LB Vserver
• Diverting Excess Traffic to a Backup LB Vserver
• Configuring Stateful Connection Failover
Redirecting Client Requests to an Alternate URL
You can configure a redirect URL to communicate the status of the NetScaler in
the event that a vserver (only of type HTTP or HTTPS) is down or disabled. This
URL can be a local or remote link. The NetScaler uses HTTP 302 redirect.
Redirects 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.
Note: If a load balancing vserver is configured with both a backup vserver and
a redirect URL, the backup vserver takes precedence over the redirect URL. A
redirect is used when the primary and backup vservers are down.
186 Installation and Configuration Guide - Volume 1
To configure a vserver to redirect client requests to a URL, use the Redirect URL
parameter as described in the following table.
The following example describes the steps to set the vserver Vserver-LB-1 to
redirect client requests to the URL
http://www.newdomain.com/mysite/maintenance.
To configure a vserver to redirect the client request to a URL using the
configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure redirect URL, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Redirect URL text box, type the URL, for example,
http://www.newdomain.com/mysite/maintenance.
6. Click OK.
To configure a vserver to redirect the client request to a URL using the
NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -redirectURL
http://www.newdomain.com/mysite/maintenance
Configuring a Backup LB Vserver
If the primary vserver is marked down or disabled, the NetScalers directs the
connections or client requests to a backup vserver that forwards the client traffic
to the services. It can also send a notification message to the client regarding the
site outage or maintenance. The backup vserver is a proxy and is transparent to
the client.
Parameter Description
Redirect URL The URL where traffic is redirected if the vserver in the
NetScaler becomes unavailable. This value must not
exceed 127 characters. The domain specified in the URL
must not match the domain specified in the domain name
argument of a content switching policy. If the same domain
is specified in both arguments, the request is redirected
continuously to the same unavailable vserver in the
NetScaler, and the user cannot get the requested content.
Chapter 4 Load Balancing 187
Note: If a load balancing vserver is configured with both a backup vserver and
a redirect URL, the backup vserver takes precedence over the redirect URL. A
redirect is used when the primary and backup vservers are down.
You can configure a backup vserver when you create a vserver, or when you
change the optional parameters of an existing vserver. You can also configure a
backup vserver for an existing backup vserver, thus creating cascaded backup
vservers. The maximum depth of cascading backup vservers is 10. The NetScaler
searches for a backup vserver that is up and accesses that vserver to deliver the
content.
Note: If the backup vserver does not exist, an error message appears.
You can use redirect URL on the primary when the primary and the backup
vservers are down or have reached their threshold for handling requests. When a
service bound to the vserver is in an out of service state, use the redirect URL on
the vserver.
To configure a backup vserver, use the Name parameter as described in the
following table.
The following example describes the steps to set the existing Vserver-LB-2 as a
backup to Vserver-LB-1. The vserver Vserver-LB-2 is created, with IP address
10.102.29.5 and protocol HTTP.
To set a backup vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure the backup vserver, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
Parameter Description
Name The name of the backup vserver. You can create a vserver
and specify the name, IP address, port, and type as
described in “Creating a Vserver” on page 120. You can
use the name of the vserver as a backup vserver.
188 Installation and Configuration Guide - Volume 1
5. In the Backup Virtual Server list, select the backup vserver, for example,
Vserver-LB-2.
6. Click OK.
To set a backup vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -backupVserver Vserver-LB-2
Diverting Excess Traffic to a Backup LB Vserver
The spillover option diverts new connections arriving at a vserver to a backup
vserver when the number of connections to the vserver exceeds the configured
threshold value. The threshold value is dynamically calculated, or you can set the
value. The number of established connections (in case of TCP) at the vserver is
compared with the threshold value. When the number of connections reaches the
threshold, new connections are diverted to the backup vserver.
You can also use tunnels to divert connections to the backup vserver. For more
information, see “NetScaler as a Decapsulator” on page 634.
You can configure persistence with spillover. In this configuration, connections
are diverted to the backup vserver based on the persistence settings configured on
the backup vserver. These connections are not moved back to the vserver. The
vserver accepts new client connections.
If the backup vservers reach the configured threshold and are unable to take the
load, the primary vserver diverts all requests to the redirect URL. If a redirect
URL is not configured on the primary vserver, subsequent requests are dropped.
To configure spillover, use the parameters described in the following table.
Parameter Description
Method Type of spillover used to divert traffic to the backup
vserver when the vserver reaches the spillover threshold.
The valid options for this parameter are: CONNECTION,
DYNAMICCONNECTION, BANDWIDTH, and NONE.
Threshold For the CONNECTION (or) DYNAMICCONNECTION
spillover type, the Threshold value is the maximum
number of connections a vserver can handle prior to
spillover. For the BANDWIDTH spillover type, the
Threshold value is the amount of incoming and outgoing
traffic (in kilobits per second) that a vserver can handle
before spillover occurs. The minimum value is 1, and the
maximum value is 4294967294.
Persistence The spillover persistence state. If you enable spillover
persistence, the NetScaler maintains sourceIP-based
persistence over primary vserver and backup vservers. The
valid options for this parameter are: enabled and disabled.
The default value is disabled.
Chapter 4 Load Balancing 189
The following example describes the steps to configure the vserver Vserver-LB-1
to divert new connections to the backup vserver Vserver-LB-2 when the number
of connections exceeds the threshold value 1000.
To set a vserver to divert new connections to a backup vserver using the
configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure the spillover, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Method list, select the type of spillover, and in Threshold text box
type the threshold value, for example, Connection and 1000.
6. Under Spillover, select the Persistence check box, and in Persistence
Timeout (min) text box type the timeout, for example, 2.
7. Click OK.
To set a vserver to divert new connections to a backup vserver using the
NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -soMethod Connection -soThreshold 1000
-soPersistence enabled -soPersistenceTimeout 2
Configuring Connection-Based Spillover
Connection-based spillover allows you to configure a maximum threshold for the
number of active client connections on a vserver. When the client connections
exceed the configured threshold limit, new client connections are diverted to the
backup vserver.
Persistence Timeout
(minutes)
This value sets the timeout for spillover persistence. The
default value is 2 minutes. The minimum value is 2
minutes, and the maximum value is 1440 minutes.
Parameter Description
190 Installation and Configuration Guide - Volume 1
To configure connection-based spillover, follow the steps described in the section
“Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the Method
list, select Connection.
Note: GSLB vservers do not support connection-based spillover.
Configuring Dynamic Spillover
Dynamic spillover depends on the maximum client setting configured on the
services. If the number of client connections at the vserver exceeds the sum of the
maximum client values, the new connections are diverted to the services of the
backup vserver.
To configure dynamic spillover, you must enable it on a vserver. You must
configure the services with appropriate maximum client values. If the value for
maximum client is set to 0, the spillover limit is treated as infinity, and spillover
never occurs. To configure dynamic spillover, follow the steps described in the
section “Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the
Method list, select Dynamic connection.
For example, you create a vserver, a backup vserver, and two services, and bind
the services to the vserver. Then you can configure dynamic spillover on the
primary vserver.
Note: Content-based vservers do not support dynamic spillover.
Configuring Bandwidth-based Spillover
Bandwidth-based spillover allows you to configure a bandwidth threshold value.
When the bandwidth of the vserver exceeds the bandwidth threshold value, the
NetScaler diverts new connections to a backup vserver. For example, if you
create a vserver, a backup vserver, and two services, and bind the services to the
vserver, you can configure bandwidth spillover on the primary vserver.
You can also configure the backup vserver with a threshold value. When the
threshold for the backup vserver is reached, the NetScaler diverts new client
connections to the next backup vserver.
To configure bandwidth-based spillover, follow the steps described in the section
“Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the Method
list, select Bandwidth.
Chapter 4 Load Balancing 191
Configuring Stateful Connection Failover
The NetScaler enables TCP or UDP connections to survive a failover event in
High Availability (HA) mode. This functionality is called connection failover.
This section provides an overview of connection failover, and instructions for
configuring it. The following topics are discussed:
• Understanding connection failover
• Configuring high availability
• Configuring connection failover
• Disabling connection failover
Understanding Connection Failover
The Citrix NetScaler provides two modes of connection failover. They are:
• Stateless connection failover
• Stateful connection failover
Stateless connection failover
Stateless connection failover supports only the service type ANY. Stateless
connection failover functions if USIP is enabled, and if Source IP persistence or
Source IP Source Port Hash LB method is configured. In this mode, the nodes in
the HA configuration do not exchange any information about connections.
Stateful connection failover
When stateful connection failover is configured, TCP connections established
through the primary NetScaler remain active after a failover. The new primary
NetScaler obtains information about connections established before the failover
and continues to provide service to those connections. The new primary
NetScaler synchronizes its data with the new secondary NetScaler using an
internal framework called the session stateful failover.
Stateful connection failover supports a number of service types, such as TCP,
UDP, ANY, FTP, and SSL_BRIDGE. All load balancing (LB) methods and LB
persistence types applicable to these service types are also supported. However,
the following are not supported:
• LB methods such as URLHASH, DOMAINHASH, CALLIDHASH, and
LRTM
• LB persistence types such as COOKIEINSERT, RULE, URLPASSIVE,
CUSTOMSERVERID, and CALLID
192 Installation and Configuration Guide - Volume 1
Both stateless and stateful connection failover are configured on LB vservers, but
cannot be configured on content-switching vservers. Mapped (SNIP), Use Source
IP, and domain-based service configurations are supported under both modes of
connection failover.
A basic HA configuration with connection failover contains the entities described
in the following figure.
Connection failover entity diagram
To create an HA configuration, you must add a secondary NetScaler to the
primary NetScaler. In the event of a failover, the secondary NetScaler takes over
as the primary NetScaler and begins accepting client connections. You can add an
LB vserver and TCP services on the primary NetScaler, as shown in the entity
diagram, and the same configuration is propagated to the secondary NetScaler.
You can then configure connection failover on the required LB vservers.
The following table describes how connection failover affects three features of
the NetScaler.
Functionality Impact of Connection Failover
SYN Protection If failover occurs after the NetScaler issues SYN-ACK,
but before it receives the final ACK, the connection is not
supported by connection failover. The client must reissue
the request to establish the connection.
Surge Protection If failover occurs before a connection with the server is
established, the new primary NetScaler establishes a
connection with the server. It also retransmits all packets
held in the course of surge protection.
Access server in DOWN state Access DOWN functionality takes precedence over
stateless connection failover, if it is enabled.
Chapter 4 Load Balancing 193
The following configurations are not supported under connection failover:
• Reverse NAT.
• Transparent services.
• Compression.
• SSLVPN.
• SSL offload.
• Application firewall.
• Independent Network Configuration (INC) HA mode.
• TCP buffering.
• The connection failover feature does not synchronize IP fragments, if the
failover occurs when IP fragments are being reassembled.
Configuring High Availability
To configure connection failover, you must first configure HA and set up a
primary and secondary NetScaler. To configure HA, see the section “Configuring
High Availability” in the “High Availability” chapter.
Configuring Connection Failover
After adding a secondary node and configuring HA, you can choose to configure
either stateless or stateful connection failover. You can configure connection
failover on any of the LB vservers.
To configure connection failover, use the parameters described in the following
table.
The following procedure describes the steps to configure a connection failover on
an LB vserver. The connection failover state is set to Stateful.
Parameter Description
Stateless Sets the state of connection failover on the virtual server
to Stateless. Stateless supports only the service type
ANY.
Stateful Sets the state of connection failover on the virtual server
to Stateful. Stateful supports the service types TCP, UDP,
ANY, FTP, and SSL_BRIDGE. Stateful connection
failover synchronizes connections between nodes in an
HA configuration.
Disable Disables connection failover.
194 Installation and Configuration Guide - Volume 1
To configure a connection failover using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure connection failover, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Connection Failover drop-down list, select Stateful.
6. Click OK.
To configure a connection failover using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -connFailover stateful
Disabling Connection Failover
The following procedure describes the steps to disable connection failover. When
connection failover is disabled on a vserver, the resources allocated to the vserver
are freed.
To disable a connection failover using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure a connection failover,
for example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Connection Failover drop-down list box, select Disable.
6. Click OK.
To disable a connection failover using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -connFailover disable
Chapter 4 Load Balancing 195
Managing Client Traffic
This section describes how to manage client traffic. Maintaining client
connections helps to ensure the availability of the services. This section includes
procedures for configuring the NetScaler to use cache and other tasks to improve
response and direct client requests based on priority.
Topics include:
• Configuring Sessionless LB Vservers
• Redirecting HTTP Requests to a Cache
• Directing Requests Based on Priority
• Directing Requests to a Custom Web Page
• Enabling Delayed Cleanup of Vserver Connections
• Rewriting Ports and Protocols for HTTP Redirection
• Inserting the IP Address and Port of a Vserver in the Request Header
The following section uses the example of an LB setup with:
• A vserver named Vserver-LB-1, of type ANY, and IP address 10.102.29.7
• A service named Service-ANY-1, of type ANY, and IP address 10.102.29.1,
bound to the vserver Vserver-LB-1
Configuring Sessionless LB Vservers
When the NetScaler performs load balancing, it creates and maintains a number
of sessions between the client and servers. In scenarios such as DSR setup or IDS
load balancing, the NetScaler can perform load balancing without creating
sessions. To prevent creation of sessions, you must configure a sessionless
vserver in the NetScaler. The sessionless vserver does not allocate any resources
on the NetScaler, thereby saving the memory that the specific deployment
consumes.
When you enable the sessionless option, the NetScaler performs load balancing
on a per-packet basis. When a sessionless vserver is configured, the sessionless
vserver forwards the packets to a server selected using load balancing methods.
While forwarding the packet, the NetScaler changes the destination MAC address
to the server MAC address.
For sessionless load balancing to operate correctly, you must perform the
following tasks:
• Enable MBF mode
196 Installation and Configuration Guide - Volume 1
• Enable MAC mode on the sessionless LB vserver
• Enable USIP mode on services (because the IP address of the source is not
changed)
Sessionless load balancing has the following limitations:
• Sessionless LB can only be used for load balancing in a direct server return
deployment, and in IDS load balancing.
• The least connections method cannot be used in sessionless mode.
• A vserver of type ANY or UDP can be configured as a sessionless vserver.
To configure a sessionless vserver, use the Sessionless parameter as described in
the following table.
The following example describes the steps to configure the vserver Vserver-LB-1
for sessionless load balancing. The service Service-ANY-1 is configured with
Use Source IP enabled.
To set a sessionless vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure sessionless load
balancing, for example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Under Redirection Mode, select the MAC mode radio button.
6. Select the Sessionless check box.
7. Click OK.
To set a sessionless vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -m MAC -sessionless enabled
Parameter Description
Sessionless Enable sessionless load balancing. The valid options for the
Sessionless parameter are: enabled and disabled. The
default value is disabled.
Chapter 4 Load Balancing 197
Redirecting HTTP Requests to a Cache
The NetScaler provides the cache redirection option for transparently redirecting
HTTP requests to a cache. A cache stores frequently requested HTTP content.
When you configure cache redirection on a vserver, the NetScaler sends
cacheable HTTP requests to the transparent caches and non-cacheable HTTP
requests to the origin Web servers. For more information on cache redirection, see
the “Cache Redirection” chapter of the Installation and Configuration Guide. To
configure cache redirection, use the Cache Redirection parameter as described in
the following table.
To set cache redirection on a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure cache redirection, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Select the Cache Redirection check box.
6. Click OK.
To set cache redirection on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -cacheable yes
Parameter Description
Cache Redirection Enables the vserver to route requests to the cache
redirection vserver before sending them to the configured
servers. The valid options for this parameter are: yes and
no. The default value is no.
198 Installation and Configuration Guide - Volume 1
Directing Requests Based on Priority
the NetScaler provides the priority queuing option for prioritizing client requests
to serve important requests first. The NetScaler places the requests in a queue
based on the configured priority, thereby providing an uninterrupted flow of
transactions through surges or attacks. For more information on priority queuing,
see the “Priority Queuing” chapter in the Installation and Configuration Guide.
To configure priority queuing, use the Priority Queuing parameter as described in
the following table.
To set priority queuing on a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure priority queuing, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Select the PQ check box.
6. Click OK.
To set priority queuing on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -pq yes
Note: You must set priority queuing globally for it to function correctly. For
more information on configuring priority queuing globally, see the “Protection”
chapter of the Installation and Configuration Guide.
Parameter Description
Priority Queuing Enable priority queuing on the specified vserver. The valid
options for this parameter are: on and off. The default value
is off.
Chapter 4 Load Balancing 199
Directing Requests to a CustomWeb Page
To ensure the response from an application through the delays because of server
capacity or processing speed, the NetScaler provides sure connect option. Sure
connect eliminates the gap between the client expectations and their browsing
experience, and improves the real and perceived availability of a Web site. For
more information about sure connect, see the sure connect chapter of Installation
and Configuration Guide. To configure sure connect, use the sure connect
parameter as described in the following table.
To set Sure Connect on a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure sure connect, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Select the SC check box.
6. Click OK.
To set Sure Connect on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -sc yes
Note: For sure connect to function correctly, you must set it globally. For more
information about configuring sure connect globally, see “Sure Connect” chapter
of the Installation and Configuration Guide.
Parameter Description
Sure Connect Enable Sure Connect on the specified vserver. The valid
options for this parameter are: ON and OFF. The default
value is OFF.
200 Installation and Configuration Guide - Volume 1
Enabling Delayed Cleanup of Vserver
Connections
You must not enable the down flush state setting on the vservers and services that
must complete their transactions and their connections must not be flushed. You
can enable the setting on the vservers and services whose connections can be
flushed when they marked down.
The state of a vserver depends on the states of the services bound to it. The state
of each service depends on the monitors bound to it. Sometimes services do not
respond to monitors and are marked down. If the server is slow or busy, the
monitoring probes time out and the service is marked as down. A vserver is
marked as down only when all services bound to it are marked as down. You can
configure vservers to either immediately terminate all connections or allow the
connections to go through when they go down. You can use this setting when a
service is marked as down due to a slow server.
The following table summarizes the impact of this setting on a configuration
consisting of a vserver and two services. The vserver Vserver-LB-1 has two
services, Service-TCP-1 and Service-TCP-2 bound to it. The vserver intercepts
two connections, C1 and C2, and redirects them to Service-TCP-1 and Service-
TCP-2 respectively. In the table, E and D denote the state of the downStateFlush
setting, where E represents Enabled and D represents Disabled.
Note: In case of HTTP services, the down state flush setting is effective only
when the client is connected to the server.
Vserver-LB-1 Service-TCP-1 State of Connections
E E Both client and server connections are terminated.
E D Both client and server connections are terminated.
In case of HTTP services, both client and server
connections are terminated only if the transaction
is active. If the transaction is not active, only client
connections are terminated.
D E Both client and server connections are terminated.
In case of HTTP services, both client and server
connections are terminated only if the transaction
is active. If the transaction is not active, only
server connections are terminated.
D D Both client and server connections are not
terminated.
Chapter 4 Load Balancing 201
You can extend this logic to larger configurations. To configure down state flush,
use the down state flush parameter as described in the following table.
To set down state flush on a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure down state flush, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Select the Down state flush check box.
6. Click OK.
To set down state flush on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -downStateFlush enabled
Rewriting Ports and Protocols for HTTP
Redirection
The vservers and servers may use different ports and when the server responds
with a redirect, you must configure the NetScaler to rewrite the port and the
protocol. By default, this setting is enabled. This setting affects HTTP traffic
only. When this setting is enabled on a vserver, the NetScaler rewrites the port
using the port settings of the vserver. This setting can be used in the following
scenarios:
• The vserver is of type HTTP and the services are of type SSL
• The vserver is of type SSL and the services are of type HTTP
• The vserver port is different than the service port
Parameter Description
down state flush Perform delayed cleanup of connections on this vserver.
The valid options for this parameter are: enabled and
disabled. The default value is enabled.
202 Installation and Configuration Guide - Volume 1
When the requests are of type HTTP and the services are of type SSL, the
NetScaler rewrites the port of the HTTP requests to that of SSL and forwards the
requests to the SSL services. Then, the NetScaler rewrites the port of the HTTPS
responses to that of HTTP and forwards them to the client. This is summarized in
the following table.
When the requests are of type SSL and the services are of type HTTP, the
NetScaler rewrites the port of the SSL requests to that of HTTP and forwards the
requests to the HTTP services. Then, the NetScaler rewrites the port of the HTTP
responses to that of HTTPS and forwards them to the client.
When both requests and responses are of same type the NetScaler rewrites the
port using the same port value. For more information about SSL redirects, see the
“Secure Sockets Layer (SSL) Acceleration” chapter in Installation and
Configuration Guide. To configure a vserver for HTTP redirection, you must use
the redirect port rewrite parameter listed in the following table.
To set HTTP redirection on a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure HTTP redirection, for
example, Vserver-LB-1.
Redirect URL URL after port rewrite
Case 1 - Redirect port rewrite enabled and vserver on port 80
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/
Case 1 - Redirect port rewrite enabled and vserver on port 8080.
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/
Parameter Description
Redirect Port Redirect The state of port rewrite while performing HTTP redirect.
The valid options for this parameter are: enabled and
disabled. The default value is disabled.
Chapter 4 Load Balancing 203
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. Select the Redirect Port Rewrite check box.
6. Click OK.
To set HTTP redirection on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -redirectPortRewrite enabled
Inserting the IP Address and Port of a Vserver in
the Request Header
You can configure the NetScaler to add the IP address and port number of a
vserver to the HTTP requests that are sent to the server. This setting allows
applications running on the server to identify the vserver that sent the request.
This option is not supported for wildcard vservers or dummy vservers. If the
primary vserver is down and the backup vserver is up, the configuration settings
of the backup vserver are added to the client requests. If you want the same
header tag to be added, irrespective of whether the requests are from the primary
vserver or backup vserver, then you must configure the required header tag on
both vservers.
204 Installation and Configuration Guide - Volume 1
To configure a vserver to add the IP address and port to the client requests, use the
Vserver IP Port Insertion parameter as described in the following table.
The following example describes the steps to configure the NetScaler to add the
IP address and port number of the vserver Vserver-LB-1 to HTTP requests that
are forwarded to the servers.
To insert the IP address and port of the vserver in the client requests using
the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure vserver port insertion,
for example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Vserver IP Port Insertion list, select the VIPADDR or
V6TOV4MAPPING.
Parameter Description
Vserver IP Port Insertion The virtual IP and port header insertion option for the
vserver.
VIPADDR-Header contains the vserver IP address and port
number without any translation.
If VIPADDR is not specified, the header is inserted with
the name specified in the default header tag vip-header and
the vserver IP and port are inserted in the request with the
default header tag vip-header.
If VIPADDR is specified, the header is inserted with the
user-specified name in vipHeader. The vserver IP and port
are inserted in the request with the user-specified header
tag vipHeader.
OFF- The virtual IP and port header insertion option is
disabled. The vserver and port number are not
inserted.
V6TOV4MAPPING - Header contains the mapped IPv4
address corresponding to the IPv6 address of the vserver
and the port number.
An IPv6 address can be mapped to a user-specified IPv4
address. The valid options for this parameter are: OFF,
VIPADDR, and V6TOV4MAPPING The default value is
OFF.
Chapter 4 Load Balancing 205
6. Type the port header in a text box next to Vserver IP Port Insertion box.
7. Click OK.
To insert the IP address and port of the vserver in the client requests using
the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -insertVserverIPPort VipAddr
Setting a Time-out Value for Idle Client Connections
You can configure the vserver with a timeout value to terminate any idle client
connections when the configured time elapses. When you configure this setting,
the NetScaler waits for the time you specify, and if the client is idle after the
configured time, the NetScaler closes the client connection. To set a timeout value
for idle client connections, use the client parameter as described in the following
table.
The following example describes the steps to set the timeout value for idle client
connections to 100 seconds.
To set a timeout value for idle client connections using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver for which you want to configure vserver port insertion,
for example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Advanced tab.
5. In the Client Timeout (secs) text box, type the timeout value, for example,
100.
6. Click OK.
To set a timeout value for idle client connections using the NetScaler
command line
At the NetScaler command prompt, type:
Parameters Descriptions
Client Timeout (Secs) The idle time (in seconds) after which the client connection is
terminated. The default value is 180sec for HTTP/SSL-based
services and 9000sec for TCP-based services.
206 Installation and Configuration Guide - Volume 1
set lb vserver Vserver-LB-1 -cltTimeout 100
Managing and Monitoring Servers
This section describes how to manage and monitor servers. Managing and
monitoring servers allows the NetScaler to determine the state of the service. You
can perform management tasks such as protect the services against traffic surges,
ensure the server response, and enable access to the services that are down. You
can also configure monitors and modify them.
Topics include:
• Configuring Services for Load Balancing
• Configuring Monitors
• Monitoring Applications and Services Using Prebuilt Monitors
• Monitoring Applications and Services Using Customized Monitors
• Configuring Support for Third-party Load Balancers Using SASP
Configuring Services for Load Balancing
This section describes how to manage the servers by configuring the services
with advanced settings. Advanced configuration settings allow you to protect the
servers against traffic surges, ensure the server response, improve client
responses, and so on.
Protecting Applications on the Servers Against a Traffic
Surge
the NetScaler provides the surge protection option to maintain the capacity of a
server or cache. The NetScaler regulates the flow of client requests to servers and
controls the number of clients that can simultaneously access the servers. The
NetScaler blocks any surges passed to the server, thereby preventing overloading
of the server. For more information about surge protection, see the “Surge
Protection” chapter of the Installation and Configuration Guide. To configure
surge protection, use the surge protection parameter as described in the following
table.
Parameters Descriptions
Surge protection The state of surge protection for the service. The valid options
for this parameter are: ON and OFF. The default value is off.
Chapter 4 Load Balancing 207
To set surge protection on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure surge protection, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Others, select the Surge Protection check box.
6. Click OK.
To set surge protection on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -sp on
Note: For surge protection to function correctly, you must enable it globally.
For more information about configuring surge protection globally, see the
“Protection” chapter of the Installation and Configuration Guide.
Directing Requests to a CustomWeb Page
the NetScaler provides the sure connect option to ensure the response from an
application. Sure connect is described in the section “Directing Requests to a
Custom Web Page” on page 199. To configure sure connect, use the sure connect
parameter as described in the following table.
To set sure connect on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure sure connect, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
Parameters Descriptions
Sure Connect The state of sure connect for the service. This parameter is
supported for legacy purposes only. It has no effect on the
NetScaler, and its only valid value is OFF. The valid options
for this parameter are: ON and OFF. The default value is OFF.
For more information about the sure connect parameter, see
the “Sure Connect” chapter.
208 Installation and Configuration Guide - Volume 1
4. Click the Advanced tab.
5. Under Others, select the Sure Connect check box.
6. Click OK.
To set sure connect on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -sc on
Note: For sure connect to function correctly, you must set it globally. For more
information about configuring sure connect globally, see the “Sure Connect”
chapter of the Installation and Configuration Guide.
Enabling Delayed Cleanup of Service Connections
When delayed cleanup of service connections is enabled, the NetScaler performs
a delayed cleanup of the connections on a service that is down. This setting is
described in the section “Enabling Delayed Cleanup of Vserver Connections” on
page 200. To configure down state flush, use the down state flush parameter as
described in the following table.
To set down state flush on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure down state flush, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Others, select the Down state flush check box.
6. Click OK.
To set down state flush on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -downStateFlush enabled
Parameters Descriptions
Down State Flush Perform delayed clean up of connections on this service. The
valid options for this parameter are: enabled and disabled. The
default value is enabled.
Chapter 4 Load Balancing 209
Enabling Access to Services When Down
You can enable access to a service when it is disabled or down. When you enable
Layer 2 or Layer 3 modes, the NetScaler bridges the packets sent to the services.
However, when the requests are forwarded to the services that are down, the
request packets are dropped. When you enable this setting and the request packets
are sent to the services that are down, the packets are bridged.
Note: For the NetScaler to bridge the packets sent to the down services, enable
Layer 2 or Layer 3 modes with the access down parameter. For more information
about Layer 2 and Layer 3 modes, see the “Basic Network Configuration” chapter
of the Installation and Configuration Guide.
To configure access down, use the access down parameter as described in the
following table.
To set access down on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure access down, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Others, select the Access Down check box.
6. Click OK.
To set access down on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -accessDown yes
Parameters Descriptions
Access Down Allows access to disabled or down services. If this option is
enabled, all packets to this service are bridged. If this option is
disabled, the packets are dropped. The valid options for this
parameter are: yes and no. The default value is no.
210 Installation and Configuration Guide - Volume 1
Enabling TCP Buffering of Response
the NetScaler provides a TCP buffering option that buffers only the responses
from the server. This enables the NetScaler to deliver server responses to the
client at the speed of the client NetScaler. The NetScaler allocates 0-4095 MB of
memory for TCP buffering, and 4-20480 KB of memory per connection. To
enable TCP buffering of server data, use the TCP Buffering parameter as
described in the following table.
To set TCP Buffering on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure TCP buffering, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the TCP Buffering check box.
6. Click OK.
To set TCP Buffering on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -TCPB yes
Note: TCP buffering set at the service level takes precedence over the global
setting. For more information about configuring TCP buffering globally, see
“Performance” chapter of the Installation and Configuration Guide.
Enabling Compression
The NetScaler provides the compression option to transparently compress the
HTML and text files. The NetScaler has a set of built-in compression policies and
uses them to compress the files. The compression policies act on the service
bound to the vserver and determine whether the response is compressible. The
compressible content is compressed and sent to the client.
Parameters Descriptions
TCP Buffering The state of the TCP buffering feature for the service. The
valid options for this parameter are: yes and no. The default
value is no.
Chapter 4 Load Balancing 211
Compression reduces the amount of data delivered to the browser and improves
client response time. To enable compression on a service, use the compression
parameter as described in the following table.
To set compression on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure compression, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Compression check box.
6. Click OK.
To set compression on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -CMP yes
Note: For compression to function correctly, you must enable it globally. For
more information about configuring compression globally, see the “Performance”
chapter of the Installation and Configuration Guide.
Parameters Descriptions
Compression The state of the HTTP compression feature for the service. The
valid options for this parameter are: yes and no. The default
value is no.
212 Installation and Configuration Guide - Volume 1
Maintaining Client Connection for Multiple Client
Requests
You can configure services to maintain client connection for multiple client
requests by using the client keep-alive parameter. If the server closes the
connection, the setting keeps the connection between the client and the NetScaler
open. This setting allows services to serve multiple client requests on a single
client connection. If you do not enable this setting, the client may open a new
connection for every request to the server. The client keep-alive setting saves
packet round trip time to establish connections and close the connections. This
setting also reduces the time to complete each transaction. Client keep-alive can
be set only on HTTP or SSL service types. For more information about client
keep-alive, see the “Performance” chapter of the Installation and Configuration
Guide. To enable client keep-alive, use the Client Keep-Alive parameter as
described in the following table.
To set client keep-alive on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure client keep-alive, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Client Keep-Alive check box.
6. Click OK.
To set client keep-alive on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -CKA yes
Note: Client-keep alive set at the service level takes precedence over the global
setting. For more information about configuring Client-keep alive globally, see
the “Performance” chapter of the Installation and Configuration Guide.
Parameters Descriptions
Client Keep-Alive The state of the Client Keep-Alive feature for the service. The
valid options for this parameter are: yes and no. The default
value is no.
Chapter 4 Load Balancing 213
Inserting the IP Address of the Client in the Request
Header
A NetScaler uses the mapped IP address to connect to the server. The server uses
the NetScaler IP address to send the responses. The server is not aware of the
client. The header of the packets sent to the server has the NetScaler IP address as
the destination address, as shown in the following figure.
IP header
When you enable client IP setting, the NetScaler inserts the client IP address
while forwarding the requests to the server. The server inserts this client IP in the
header of the responses. The server is thus aware of the client, as shown in the
following figure.
IP header when CIP insertion enabled
214 Installation and Configuration Guide - Volume 1
To insert the IP address of the client in the client request, use the parameters as
described in the following table.
The following example describes the steps to insert the client IP address while
forwarding the client request to the server.
To insert client IP address in the client request using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to add the client IP address in the
request, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Client IP check box.
6. In the Header text box, type the header tag, for example,
X-Forwarded-for.
7. Click OK.
To insert client IP address in the client request using the NetScaler
command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -CIP enabled X-forwarded-for
Parameters Descriptions
Client IP The Client IP header addition option for the service. The valid
options for this parameter are: enabled and disabled. The
default value is disabled.
Client IP Header The name of the HTTP header used. You must specify the IP
address of the client. If client IP insertion is enabled and the
client IP header is not specified, then the NetScaler sets the
client IP header. The default is blank (NetScaler uses a blank
HTTP header).
Chapter 4 Load Balancing 215
Setting Server ID to Maintain Persistent Connections
Configuring the custom server ID persistence type requires that you set a server
ID. The persistence type embeds the server ID that servers provide in the
response. The NetScaler extracts the server ID from subsequent requests and uses
it to choose a server. To set the server ID, use the server ID parameter as
described in the following table.
The following example describes the steps to set the server ID to 11.
To insert the server ID in the response from the server using the
configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to set the server ID, for example,
Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. In the ServerID text box, type the ID of the server, for example, 11.
6. Click OK.
To insert the server ID in the response from the server using the NetScaler
command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -serverID 11
Parameters Descriptions
Server ID The identifier for the service. This is used when the persistence
type is set to Custom Server ID. The minimum value is 0 and
the maximum value is 65535.
216 Installation and Configuration Guide - Volume 1
Using the Source IP Address of the Client When
Connecting to the Server
When you enable this setting, the NetScaler forwards the packet from the client to
the server without changing the source IP address. To configure use source IP
address (USIP), use the use source IP address parameter as described in the
following table.
You can use this option when you cannot insert the client IP address, for example,
non-HTTP services.
To use IP address of the client using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to use the source IP address, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Use Source IP check box.
6. Click OK.
To use IP address of the client using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -usip yes
Note: For USIP to function correctly, you must set it globally. For more
information about configuring USIP globally, see the “Basic Network
Configuration” chapter of the Installation and Configuration Guide.
Parameters Descriptions
Use Source IP Address Use the client IP address option as the source IP address when
the NetScaler connects to the server. With this option set, the
NetScaler uses the client IP address for server connection. The
valid options for this parameter are: yes and no. The default
value is no.
Chapter 4 Load Balancing 217
Setting a Limit on the Number of Client Connections
You can specify a maximum limit for the number of client connections that the
server can handle. The NetScaler opens the client connections to the servers until
this limit is reached. When the maximum limit of client connections is reached,
the monitor probes are skipped and the server is not used for load balancing. To
limit the number of client connections, use the Maximum Clients parameter as
described in the following table.
Note: Connections that are closing are not considered for this limit.
For more information on Maximum Client, see the section “Load Balancing with
Domain-Name Based Services” on page 287.
To set a limit the number of client connections using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure the maximum number of
client connections, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Thresholds, in the Max Client text box, type the maximum number
of client connections, for example, 100.
6. Click OK.
To set a limit the number of client connections using the NetScaler
command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -maxClient 1000
Parameters Descriptions
Maximum Clients The maximum number of open connections to the service. The
default value is 0. The maximum value is 4294967294.
218 Installation and Configuration Guide - Volume 1
Setting a Limit on Number of Requests Per Connection
to the Server
In some scenarios, servers have issues when the connections are reused for many
requests. You can use the max request option to limit the number of requests sent
on a single connection to the server. You can use the max request option for
HTTP or SSL. To limit the number of requests, use the maximum requests
parameter as described in the following table.
To limit the number of client requests using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure the maximum number of
client requests, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Thresholds, in the Max Requests text box, type the maximum
number of client requests, for example, 100.
6. Click OK.
To limit the number of client requests using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -maxReq 100
Setting a Threshold Value for Monitors
The threshold value for the monitor specifies a value that determines the state of
the service as UP. The NetScaler determines the state of the service as UP only
when the sum of the monitors that are UP is equal to or greater than the threshold
value you configured on the service. To set the monitor threshold, use the monitor
threshold parameter as described in the following table.
Parameters Descriptions
Maximum Requests The maximum number of requests that can be sent on a
persistent connection to the service. The default value is 0. The
minimum value is 0 and maximum value is 65535. ‘0’
specifies that there is no limit on the maximum requests that
are sent on a persistent connection.
Parameters Descriptions
Monitor Threshold The monitoring threshold. The default value is 0. The
minimum value is 0 and maximum value is 65535.
Chapter 4 Load Balancing 219
To set monitor threshold on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure monitor threshold, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. In the Monitor Threshold text box, type the monitor threshold, for
example, 100.
6. Click OK.
To set monitor threshold on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -monThreshold 100
Setting a Time-out Value for Idle Client Connections
You can configure the service with a timeout value to terminate any idle client
connections when the configured time elapses. If the client is idle during the
configured time, the NetScaler closes the client connection. To set a timeout value
for idle client connections, use the client parameter as described in the following
table.
The following example describes the steps to set the timeout value for idle client
connections to 100 seconds.
To set a timeout value for idle client connections using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure the timeout value for
client connections, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
Parameters Descriptions
Client The idle time (in seconds) after which the client connection is
terminated. The default value is 180sec for HTTP/SSL-based
services and 9000sec for TCP-based services.
220 Installation and Configuration Guide - Volume 1
5. Under Idle Timeout (secs), in the Client text box, type the timeout value,
for example, 100.
6. Click OK.
To set a timeout value for idle client connections using the NetScaler
command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -cltTimeout 100
Setting a Time-out Value for Idle Server Connections
You can configure the service with a timeout value to terminate any idle server
connections when the configured time elapses. If the server is idle during the
configured time, the NetScaler closes the server connection. To set a timeout
value for idle server connections, use the server parameter as described in the
following table.
The following example describes the steps to set the timeout value for idle server
connections to 100 seconds.
To set a timeout value for idle server connections using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure the timeout value for
server connections, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Idle Timeout (secs), in the Server text box, type timeout value, for
example, 100.
6. Click OK.
To set a timeout value for idle server connections using the NetScaler
command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -svrTimeout 100
Parameters Descriptions
Server The idle time (in seconds) after which the server connection is
terminated. The default value is 360. The maximum value is
31536000.
Chapter 4 Load Balancing 221
Setting a Limit on the Bandwidth Usage by Clients
In some scenarios, the servers may have limited bandwidth to handle client
requests, and may become overloaded. You can specify a maximum limit on the
bandwidth that the server can handle. The NetScaler forwards requests to the
servers until this limit is reached. To set a limit on bandwidth, use the maximum
bandwidth parameter as described in the following table.
The following example describes the steps to set the maximum bandwidth that
the client can use for the service Service-HTTP-1 to 100 kilobits.
To set a limit bandwidth usage on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure maximum bandwidth
usage, for example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Thresholds, in the Max Bandwidth text box, type the maximum
bandwidth, for example, 100.
6. Click OK.
To set a limit bandwidth usage on the service using the NetScaler command
line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -maxBandwidth 100
Parameters Descriptions
Maximum Bandwidth The maximum bandwidth allowed for the service. The
maximum bandwidth parameter is an inbound setting, and is
used on incoming requests. The unit of measurement is
kilobits.
222 Installation and Configuration Guide - Volume 1
Redirecting Client Requests to a Cache
You can configure a service to redirect client requests to a cache, and then
forward the request to the servers. To set cache redirection, use the parameters
described in the following table.
The following example describes the steps to set cache redirection for the service
Service-HTTP-1.
To set cache redirection on the service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to configure cache redirection, for
example, Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Cache Redirection Options, in Cache Type list, select the type of
cache, for example, Regular Server.
6. Select the Enable Cache Redirection check box.
7. Click OK.
To set cache redirection on the service using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-HTTP-1 -cacheable yes
Parameters Descriptions
Cache Redirection The vserver routes a request to another vserver on the same
NetScaler, then forwards the request to the configured servers.
The vserver used for transparent cache redirection determines
if the request is directed to the cache servers or the configured
servers. By default, this argument is disabled. The valid
options for this parameter are: yes, and no. The default value is
no.
Cache Type The cache type option supported by the cache server. The valid
options for this parameter are: transparent, reverse, and
forward.
Chapter 4 Load Balancing 223
Configuring Monitors
Monitors periodically check the state of a service. The NetScaler does not
consider services that are marked down for load balancing. A monitor allows the
NetScaler to accurately evaluate services. You can bind multiple monitors of any
type to a service to determine its state. Monitors specify the types of requests sent
to the server, and the expected response from the server. Monitors periodically
probe the servers and check if they receive a response within the configured time.
If the monitor does not receive a response in the configured time, and if the
configured number of probes fail, it determines the server as DOWN.
Topics include:
• Configuring Monitors in an LB Setup
• Modifying Monitors
• Managing Monitors
Configuring Monitors in an LB Setup
This section describes the procedures to configure monitors in an LB setup, and
the tasks to create and bind the monitors to the services. After the monitors are
bound to the services, they periodically probe the services to determine the state
of the services. The following table lists the names and values of the basic entities
that are configured on the NetScaler, as described in the “Configuring a Basic
Setup” on page 114.
Entity Type Name IP Addresses Port Protocol
Vserver Vserver-LB-1 10.102.29.60 80 HTTP
Services Service-HTTP-1 10.102.29.5 80 HTTP
Service-HTTP-2 10.102.29.6 80 HTTP
Monitors Monitor-HTTP-1 None None HTTP
224 Installation and Configuration Guide - Volume 1
The following figure shows the monitors and how they operate.
Working of monitors
Creating Monitors
The NetScaler provides a set of built-in monitors. The NetScaler also allows you
to create custom monitors based on the default monitors. To create monitors, use
the parameters as described in the following table.
Parameters Description
Monitor Name The unique name of the monitor. This name must not exceed
31 characters.
Monitor Type The type of monitor. The valid options for this parameter are:
PING, TCP, HTTP, TCP-ECV, HTTP-ECV, UDP-ECV, DNS,
FTP, RADIUS, USER, HTTP-INLINE, SIP-UDP, LOAD,
FTP-EXTENDED, SMTP, SNMP, NNTP, MYSQL, LDAP,
POP3, CITRIX-XML-SERVICE, and CITRIX-WEB-
INTERFACE
Interval The frequency at which the probe is sent to a service. The
interval must be greater than the response timeout. The
minimum value is 1 millisecond and the maximum value is
160 seconds. The default value is 5 seconds.
Chapter 4 Load Balancing 225
The following example describes the steps to create a monitor monitor-HTTP-1,
of type HTTP, with a time interval of 340 seconds.
To create a monitor using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Click Add. The Create Monitor dialog box appears.
3. In the Name and Interval text boxes type the name and interval value of
the monitor, for example, monitor-HTTP-1 and 340.
4. In the Type list, select the type of the monitor, for example, HTTP.
5. In the list next to the Interval text box, select Seconds.
6. Click Create and click Close. The monitor you created appears in the
Monitors page, as shown in the following figure.
Monitors page
To create a monitor using the NetScaler command line
At the NetScaler command prompt, type:
add lb mon monitor-HTTP-1 HTTP
Binding Monitors to Services
After creating a monitor, you can bind it to a service. For the NetScaler to monitor
the servers, the monitors must be bound to the service. The NetScaler sends
periodic requests to the server. The servers must send a response prior to the
configured response timeout. If the configured number of probes fail, the server is
marked down, and the next probe is sent when the configured downtime elapses.
The destination of the probe may be different than the server IP address and port.
226 Installation and Configuration Guide - Volume 1
You can bind multiple monitors to a service and the status of the service is
determined using the results of the bound monitors. The following example
describes the steps to bind the monitor monitor-HTTP-1 to the service
Service-HTTP-1.
To bind a monitor to a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service for which you want to bind the monitor, for example,
Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Under Available, in the Monitors list box, select the monitor you want to
bind the service, for example, monitor-HTTP-1.
5. Click Add. The monitor appears in the Configured box.
6. Click OK.
To bind a monitor to a service using the NetScaler command line
At the NetScaler command prompt, type:
bind mon monitor-HTTP-1 Service-HTTP-1
Modifying Monitors
You can modify the configured monitors. If you change a monitor that is bound to
multiple services, monitoring of the bound services changes. You can modify a
monitor that you created using the parameters listed in this section. Two sets of
parameters apply to monitors:
• Parameters that apply to all monitors, regardless of type
• Parameters that are specific to a monitor type
This section describes the parameters that apply to all monitors. To modify
monitors, you can use the parameters listed in the following table.
Parameter Description
LRTM The state of the response time calculation of probes. The
valid options for this parameter are: enabled and disabled.
The default value is disabled.
Deviation Deviation from the learned response time for dynamic
response time monitoring. The maximum value is 348
minutes.
Chapter 4 Load Balancing 227
Response Timeout The duration of the interval for which the NetScaler waits
before it marks the probe as failed. The response timeout
must be less than the value specified in the interval
parameter.
The UDP-ECV monitor type does not decide the probe
failure using the response timeout. The NetScaler
considers the probe as successful for the UDP-ECV
monitor type when the server response matches the criteria
that the send and receive options set, or if the response is
not received from the server.
The send option specifies the data that must be sent to the
server in the probe, and the receive option specifies the
server response criteria for the probe to succeed. The
unreachable error from the service causes probe failure.
The minimum value is 10 milliseconds. The maximum
value is 159 seconds. The default value is 2 seconds.
Response Timeout
Threshold
The monitor response timeout threshold. If the response
time for the monitoring probes exceeds the threshold, a
trap is sent. The response timeout is given as a percentage.
The minimum value is 1 and the maximum value is 100.
Retries The number of consecutive probes failures after which the
NetScaler determines the service as down. The default
value is 3.
Down Time The wait duration until the next probe after the service is
marked down. The minimum value is 10 milliseconds and
the maximum value is 160 seconds. The default value is
30 seconds.
Destination IP Address The IP address to which the probe is sent. If the
destination IP address is set to 0, the destination IP address
is set to the bound service. The default is 0.0.0.0.
Destination Port The TCP/UDP port to which the probe is sent. If the
destination port is set to 0, the destination port is the port
of the service to which the monitor is bound. For a USER
monitor, this port is the port sent in the HTTP request to
the dispatcher. This option is ignored if the monitor is of
the PING type. For information about user monitors, see
“Configuring User Monitors” on page 248.
State The state of the monitor. If the monitor is disabled, this
monitor type probe is not sent for the services. If the
monitor is bound, the state of this monitor is not
considered when the state of the service is determined.
The valid options for this parameter are: enable and
disable. The default value is enabled.
Reverse The state of reverse probe criterion check. The valid
options for this parameter are: yes and no. The default
value is no.
Parameter Description
228 Installation and Configuration Guide - Volume 1
The following example describes the steps to configure the monitor monitor-
HTTP-1 with an interval of 50 milliseconds and a response time of 20
milliseconds.
To modify an existing monitor using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Select the monitor that you want to modify, for example,
monitor-HTTP-1.
3. Click Open. The Configure Monitor dialog box appears.
4. In the Interval and Response Timeout text boxes, type the interval and
response timeout values, for example, 50 and 20.
5. In the list next to Interval text box, select Milli Seconds.
6. In the list next to Response Timeout text box, select Milli Seconds.
7. Click OK.
To modify an existing monitor using the NetScaler command line
At the NetScaler command prompt, type:
set mon monitor-HTTP-1 HTTP -interval 50 milli
-resptimeout 20 milli
Transparent The state of the monitor bound for transparent devices,
such as firewalls, based on the responsiveness of the
services behind them. If monitoring of transparent devices
is enabled, the destination IP address must be specified.
The probe is sent to the specified destination IP address
using the MAC address of the transparent device. The
valid options for this parameter are: yes and no. The
default value is no.
Secure The state of the secure monitoring of services. SSL
handshake is performed on the established TCP
connection. Applicable for TCP based monitors only. The
valid options for this parameter are: yes and no. The
default value is no.
Application Name of the application that must be executed to check
the state of the service.
Site Path URL of the logon page.
Parameter Description
Chapter 4 Load Balancing 229
Managing Monitors
This section describes how to manage the monitors you create. You can change
the bindings of the monitors, or enable, disable, and remove monitors. You can
also unbind monitors from services and service groups.
Enabling and Disabling Monitors
By default, monitors bound to services and service groups are enabled. If you
disable a monitor bound to a service, the state the service is determined using the
other monitors bound to the service. If the service is bound to only one monitor,
and if you disable the monitor, the state of the service is determined using the
default monitor. The following example describes the steps to disable the monitor
monitor-HTTP-1.
To disable a monitor using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Select the monitor that you want to disable, for example,
monitor-HTTP-1.
3. Click Disable. The Disable pop-up window appears.
4. Click Yes.
To disable a monitor using the NetScaler command line
At the NetScaler command prompt, type:
disable lb mon Service-HTTP-1
When you enable a monitor, the monitor begins probing the services to which it is
bound. The following example describes the steps to enable the monitor
monitor-HTTP-1.
To enable a monitor using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Select the monitor that you want to enable, for example, monitor-HTTP-1.
3. Click Enable. The Enable pop-up window appears.
4. Click Yes.
To enable a monitor using the NetScaler command line
At the NetScaler command prompt, type:
enable lb mon Service-HTTP-1
230 Installation and Configuration Guide - Volume 1
Unbinding Monitors
You can unbind monitors from a service and service group. When you unbind a
monitor from the service group, the monitors are unbound from the individual
services that constitute the service group. When you unbind a monitor from a
service or a service group, the monitor does not probe the service or the service
group. When you unbind the configured monitors from a service or a service
group, the default monitor is bound to the service and the service group. The
default monitors then probes the service or the service groups. The following
example describes the steps to unbind the monitor monitor-HTTP-1 from the
service Service-HTTP-1.
To unbind a monitor from a service using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service from that you want to unbind the monitor, for example,
Service-HTTP-1.
3. Click Open. The Configure Service dialog box appears.
4. Under Configured, select the monitor that you want to unbind from the
service, for example, monitor-HTTP-1.
5. Click Remove. Under Available, the available monitors appear in the
Monitors list box.
6. Click OK.
To unbind a monitor from a service using the NetScaler command line
At the NetScaler command prompt, type:
unbind mon monitor-HTTP-1 Service-HTTP-1
Removing Monitors
You can remove a monitor that you have configured. If a monitor is bound to a
service, it cannot be removed. Therefore, you must first unbind the monitor from
the service and then remove it. When you remove monitors bound to a service,
the default monitor is bound to the service. You cannot remove default monitors.
The following example describes the steps to remove the monitor
monitor-HTTP-1.
To remove a monitor using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
Chapter 4 Load Balancing 231
2. Select the monitor that you want to remove, for example,
monitor-HTTP-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a monitor using the NetScaler command line
At the NetScaler command prompt, type:
rm lb monitor monitor-HTTP-1 HTTP
Viewing Monitors
You can view the services and service groups bound to the monitor. You can
verify the settings of the monitors to troubleshoot the configuration.The
following procedure describes the steps to view the bindings of a monitor to the
services and service groups.
To view monitor bindings using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. In the Monitors page, select the monitor for which you want to view the
binding information, for example, monitor-HTTP-1.
3. Click Show Bindings. The binding information for the monitor that you
selected appears in the Binding Info for Monitor: monitor-HTTP-1
dialog box.
To view monitor bindings using the NetScaler command line
At the NetScaler command prompt, type:
show lb monbindings monitor-HTTP-1
To view monitors using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane. The details of the available
monitors appear on this page.
To view monitors using the NetScaler command line
At the NetScaler command prompt, type:
show lb mon monitor-HTTP-1
232 Installation and Configuration Guide - Volume 1
Monitoring Applications and Services Using
Prebuilt Monitors
This section describes the built-in monitors. You cannot modify the built-in
monitors. You can only bind the built-in monitors to the services. However, you
can create a custom monitor based on the built-in monitors. To create and bind
monitors to the services, see the section “Configuring Monitors in an LB Setup”
on page 223, to create and bind the monitors to the services.
Monitoring TCP-based Applications
The NetScaler has a set of default monitors (tcp-default and ping-default). After a
service is created on the NetScaler, the appropriate default monitor is bound to it,
so that the service can be used immediately (if it is up):
• The TCP-default monitor is bound to all TCP services
• The ping-default monitor is bound to all non-TCP services
You cannot delete, or modify default monitors. When you bind any monitor to the
service, the default monitor is unbound from the service. The following table
gives information about monitor types, parameters, and monitoring procedures.
The NetScaler provides a built-in monitor for each monitor type.
Type Specific Parameters Procedure
TCP (tcp) Not applicable The NetScaler establishes a 3-way handshake
with the monitor destination, and then closes
the connection.
If the NetScaler 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
(http)
httprequest
[“HEAD /”] - HTTP
request that is sent to the
service.
respcode [200] - A set of
HTTP response codes are
expected from the service.
The NetScaler establishes a 3-way handshake
with the monitor destination.
After the connection is established, the
NetScaler sends HTTP requests, and then
compares the response code in the response
from the service, with the configured set of
response codes.
TCP-ECV
(tcp-ecv)
send [""] - is the data that is
sent to the service. The
maximum permissible
length of the string is 512 K
bytes.
recv [""] - expected
response from the service.
The maximum permissible
length of the string is 128 K
bytes.
The NetScaler establishes a 3-way handshake
with the monitor destination.
When the connection is established, the
NetScaler uses the send parameter to send
specific data to the service and expects a
specific response through the receive
parameter.
Chapter 4 Load Balancing 233
To configure prebuilt monitors for TCP-based applications, see “Configuring
Monitors in an LB Setup” on page 223. To create a monitor, you must provide
values for the required parameters.
Monitoring SSL Services
The monitors periodically check the SSL servers. The NetScaler has four built-in
secure monitors: TCPS, HTTPS, TCPS-ENV, and HTTPS-ENV. You can use the
secure monitors to check the HTTP and non-HTTP traffic. The secure monitors
work as follows:
HTTP-
ECV
(http-ecv)
send [""] - HTTP data is
sent to the service
recv [""] - the expected
HTTP response data from
the service
The NetScaler establishes a 3-way handshake
with the monitor destination.
When the connection is established, the
NetScaler uses the send parameter to send the
HTTP data to the service and expects the
HTTP response that the receive parameter
specifies. (HTTP body part without including
HTTP headers).
Empty response data matches any response.
Expected data may be anywhere in the first
24K bytes of the HTTP body of the response.
UDP-
ECV
(udp-ecv)
send [""] - data that is sent
to the service.
recv [""] - expected
response from the service.
When the receive string is specified:
If the response matches the receive string, the
service is marked as up.
Consequently, if the response matches the
receive string for a reverse monitor, the
service is marked as down.
Also, the service is marked as down if an
“icmp port unreachable” message is received.
When the receive string is not specified:
A service is marked as up whether or not a
response is received. However, the service is
marked as down if an “icmp port unreachable”
message is received. For LRTM monitors,
when no response is received, the response
time is the response timeout for the monitor.
When the UDP monitors detect an ICMP port
unreachable error, the service is marked as
down immediately.
PING
(ping)
Not Applicable The NetScaler sends an ICMP echo request to
the destination of the monitor and expects an
ICMP echo response.
Type Specific Parameters Procedure
234 Installation and Configuration Guide - Volume 1
TCPS - the NetScaler establishes a TCP connection. After the connection is
established, the NetScaler performs an SSL handshake with the server. After the
handshake is over, the NetScaler closes the connection.
HTTPS - the NetScaler establishes a TCP connection. After the connection is
established, the NetScaler performs an SSL handshake with the server. When the
SSL connection is established, the NetScaler sends HTTP requests over the
encrypted channel and checks the response codes.
TCPS-ECV - the NetScaler establishes a TCP connection. After the connection
is established, the NetScaler performs SSL handshake with the server. When the
SSL connection is established, the NetScaler sends specific data using the send
parameter to the service on the encrypted channel and expects a specific
encrypted response. The response is decrypted, and the data is verified through
the receive parameter.
HTTPS-ECV - the NetScaler establishes a TCP connection. After the connection
is established, the NetScaler performs an SSL handshake. When the SSL
connection is established, the NetScaler sends the encrypted HTTP request
specified using the send parameter to the service, and expects the encrypted
HTTP response (HTTP body part, not including HTTP headers). This response is
decrypted and compared with the expected response specified using the receive
parameter. The following table describes the monitor types for monitoring SSL
services.
To configure prebuilt monitors to check the state of SSL services, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create monitors.
Monitor type Probe Success criteria (Direct condition)
TCP TCP connection
SSL handshake
Successful TCP connection established
and successful SSL handshake.
HTTP TCP connection
SSL handshake
Encrypted HTTP request
Successful TCP connection is established,
successful SSL handshake is performed,
and expected HTTP response code in
server HTTP response is encrypted.
TCP-ECV TCP connection
SSL handshake
Data sent to a server is
encrypted
Successful TCP connection is established,
successful SSL handshake is performed,
and expected TCP data is received from
the server.
HTTP-ECV TCP connection
SSL handshake
Encrypted HTTP request
Successful TCP connection is established,
successful SSL handshake is performed,
and expected HTTP data is received from
the server.
Chapter 4 Load Balancing 235
Monitoring FTP Services
The FTP monitor opens a connection to an FTP server to determine the state of
the service. During an FTP session, two connections are opened between the FTP
monitor and FTP server: The FTP monitor opens the control connection to
transfer commands between the monitor and the FTP server. Then the FTP server
opens the data connection to transfer files between the FTP monitor and the
server. The FTP monitor connects to the FTP server, checks the response code,
and sends a command to the FTP server. If the FTP monitor receives a response in
the specified time, the FTP services are marked up. The NetScaler establishes a
TCP connection to the service. After a connection is established, the NetScaler
logs in to the FTP server using the specified username and password. To monitor
FTP services, use the parameters as described in the following table.
The NetScaler has a monitor of type FTP-EXTENDED that provides a script to
the FTP server. The FTP server executes the script and the responds to the query.
Using the response, the FTP-EXTENDED monitor determines the state of the
service. The following table describes the parameter you must use to configure
FTP - EXTENDED monitors.
To configure prebuilt monitors to check the state of FTP services, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create monitors of type FTP or FTP - EXTENDED.
Monitoring SIP Services
The Session Initiation Protocol (SIP) is an application layer control protocol
established by the IETF. It is designed to initiate, manage, and terminate
multimedia communications sessions, and has emerged as the standard for
Internet telephony (VoIP).
Parameters Descriptions
User Name User name used in the probe.
Password Password used in monitoring.
Parameters Descriptions
File Name File name to be used for FTP-EXTENDED monitor.
236 Installation and Configuration Guide - Volume 1
SIP messages can be transmitted over TCP or UDP. SIP messages are of two
types: request messages and response messages. The following table summarizes
the formats of these messages:
The traffic in an SIP-based communication system is routed through dedicated
devices and applications (entities). In a multimedia communication session, these
entities exchange messages.
Message Type Components Details
Request Method Invite, Ack, Options, Bye, Cancel, Register
Request URI Represents the subject, media type, or urgency of
sessions initiated. The common format is:
sip:user:password@host:port;uri-
parameters?headers
SIP version The SIP version being used
Response SIP version The SIP version being used
Status code A 3-digit integer result code. The possible values
are:
1xx: Information Responses. For example: 180,
Ringing
2xx: Successful Responses. For example: 200, OK
3xx: Redirection Responses. For example: 302,
Moved Temporarily
4xx: Request Failures Responses. For example:
403, Forbidden
5xx: Server Failure Responses. For example: 504,
Gateway Time-out
6xx: Global Failure Responses. For example: 600,
Busy Everywhere
Reason-phrase Textual description of the status code
Chapter 4 Load Balancing 237
One of the most common scenarios for SIP is VoIP, where SIP is used to set up
the session. The usage scenario described in the following section illustrates the
role of the messages and entities in an SIP-based communication system.
SIP mechanism
User Agent (UA) is the entity that initiates the call. The UA can be an SIP
softphone (a PC-based application), or an SIP phone.
To initiate a call, the UA sends an INVITE request to the previously configured
SIP Proxy server. The INVITE request contains the details of the destination,
such as the destination URI and Call ID. In the figure, the UA (Caller A) sends an
INVITE request to Proxy A.
When the proxy server receives the INVITE request, it sends a 100 (Trying)
response to the UA that initiated the call. It also performs a DNS lookup to locate
the SIP proxy server of the destination domain. After the SIP proxy server of the
destination domain is located, the SIP proxy at the source domain sends the
INVITE request to it. Here, Proxy A sends a 100 (Trying) response to Caller A
and an INVITE request to Proxy B.
When the SIP proxy server of the destination domain receives the INVITE
request from the SIP proxy server of the source domain, it responds with a 100
(Trying) response. It then sends the INVITE request to the destination UA. In this
case, Proxy B sends a 100 (Trying) response to Proxy A and an INVITE request
to Caller B.
238 Installation and Configuration Guide - Volume 1
When the destination UA receives the INVITE request, it alerts Caller B and
responds with a 180 (ringing) response. This response is routed back to the source
UA through the proxies.
When caller B accepts the call, the destination UA responds with a 200 (OK)
response. This implies that caller B has answered the call. This response is routed
back to the source UA via the proxies. After the call is set up, the UAs
communicate directly without the proxies.
The following table describes the entities of an SIP-based communication system
and their roles.
You can configure the NetScaler to load balance SIP requests to a group of SIP
proxy servers. To do this, you need to create an LB vserver with the LB method
set to Call-ID hash, then bind to it the services representing the SIP proxies.
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 a domain name
to the SIP header that resolves to the IP address of the SIP vserver. Also, the SIP
proxies must communicate with a common database to share registration
information.
This section describes the role of the NetScaler when configured to perform SIP
load balancing in the two most commonly used topologies:
• One-arm direct server return (DSR) mode
• Inline DSR mode
For more information about DSR mode, see the section “Configuring Load
Balancing in Direct Server Return Mode” on page 295.
Entity Role
User Agent (UA) SIP User Agents generate requests and respond to incoming
requests. A UA that generates requests is known as a User
Agent Client (UAC). The UA that responds to requests is
known as the User Agent Server (UAS). In the preceding
example, Caller A was the UAC and Caller B was the UAS.
Proxy Server Proxies receive and route SIP requests based on the URI.
They can selectively rewrite parts of the request message
before forwarding it. They also handle registrations,
invitations to UAs, and apply call policies.
Redirect Server Redirect servers send routing information to the SIP proxy
servers.
Registrar Server Registrar servers provide location information to UAs and
proxy servers.
Back-to-Back User
Agent (B2BUA)
Back-to-Back User Agents (B2BUA) are combination of
UAS and UAC.
Chapter 4 Load Balancing 239
Understanding SIP in One-armDSR Mode
In DSR mode, the NetScaler receives SIP requests from the UAs, and routes the
requests to the appropriate SIP proxy using the LB method. The SIP proxies send
the responses to the destination SIP proxies, bypassing the NetScaler as
illustrated in the following figure.
SIP in one-armmode
The flow of requests and responses in this scenario is as follows:
1. The UA, Caller A, sends an INVITE request to the NetScaler. The
NetScaler, using the LB method, routes the request to Proxy 2.
2. Proxy 2 receives the INVITE request from the NetScaler and responds with
a 100 (Trying) message.
3. Proxy 2 performs a DNS lookup to obtain the IP address of the destination
SIP proxy at domainB.com. It then sends the INVITE request to the
destination proxy.
4. The destination proxy responds with a 100 (Trying) message and sends the
INVITE request to the destination UA, Caller B. The destination UA,
Caller B, begins to ring and responds with a 180 (Ringing) message. This
message is sent to Caller A through the NetScaler and the Proxy 2. After the
user accepts the call, Caller B responds with a 200 (OK) message that is
propagated to Caller A via the NetScaler and the Proxy 2.
5. After Caller B accepts the call, the UAs (Caller A and Caller B)
communicate independently.
240 Installation and Configuration Guide - Volume 1
Understanding SIP in Inline DSR Mode
In inline DSR mode, the NetScaler is placed between the router and the SIP
proxy, as illustrated in the following figure.
SIP in inline mode
The flow of requests and responses is as follows:
1. The UA, Caller A, sends an INVITE request to the NetScaler. The
NetScaler, based on the LB method, routes the request to Proxy 2.
2. Proxy 2 receives the INVITE request from the NetScaler and responds with
a 100 (Trying) message.
3. Proxy 2 performs a DNS lookup to obtain the IP address of the destination
SIP proxy at domainb.com. It then propagates the INVITE request to the
destination proxy through the NetScaler.
4. the NetScaler performs RNAT, replaces the source IP address in the
INVITE request with the NAT IP address, and forwards the INVITE
request to the destination SIP proxy.
5. The destination proxy responds with a 100 (Trying) message and sends the
INVITE request to the destination UA, Caller B. The destination UA,
Caller B, begins to ring and responds with a 180 (Ringing) message. This
message is sent to Caller A through the NetScaler and the Proxy 2. After the
user accepts the call, Caller B responds with a 200 (OK) message that is
propagated to Caller A via the NetScaler and the Proxy 2.
Chapter 4 Load Balancing 241
6. After the user accepts the call, the UAs (Caller A and Caller B)
communicate independently.
To monitor SIP services, use the parameters as described in the following table.
To configure prebuilt monitors to check the state of SIP server, see “Configuring
Monitors in an LB Setup” on page 223. You must provide values for the required
parameters to create a monitor of type SIP.
Monitoring RADIUS Services
The RADIUS monitor periodically checks the state of the RADIUS server using
the RADIUS protocol. The NetScaler sends the RADIUS packets to the RADIUS
server. The RADIUS server authenticates the RADIUS clients using the
authentication information in the RADIUS database. Based on the authentication,
the RADIUS server sends the response to the NetScaler. The following are the
expected responses from the RADIUS server:
• If the client and the server have a similar configuration, the server must
send an Access-Accept response. The response code for Access-Accept is
2. This is the default code that the NetScaler uses.
• If there is a mismatch in the username, password, or secret key, the server
sends an Access-Reject response. The response code for Access-Reject is 3.
To monitor RADIUS services, use the parameters as described in the following
table.
Parameters Descriptions
Maximum Forwards SIP packet max-forwards. Default value: 1 Minimum
value: 0 Maximum value: 255.
SIP Method SIP method to be used for the query. Possible values:
OPTIONS, INVITE, REGISTER Default value:
OPTIONS.
SIP URI SIP method string, sent to the server. For example
“OPTIONS sip:sip.test.”
SIP Register URI SIP user to be registered.
Parameters Descriptions
User Name Username on the
RADIUS/NNTP/FTP/FTP-EXTENDED/MYSQL/POP3
server. This user name is used in the probe.
Password Password used in monitoring RADIUS/NNTP/FTP/FTP-
EXTENDED/MYSQL/POP3/LDAP servers.
RADIUS Key The shared secret key value that the RADIUS server uses
during client authentication.
242 Installation and Configuration Guide - Volume 1
You must perform the following configurations in the RADIUS server:
1. Add the username and password of the client to the database where the
RADIUS daemon searches for authentication.
2. Add the IP address and secret key of the client to the respective RADIUS
database.
3. Add the IP addresses that originate from the RADIUS packets to the
RADIUS database. If the NetScaler has more than one Mapped IP, or if
SNIP is used, you must add the same secret key for all of the IP addresses.
If the client IP address is not added into the database, the server discards the
packets.
The RADIUS server can send an access-reject response for any mismatch in
username, password, or secret key. To configure prebuilt monitors to check the
state of RADIUS server, see “Configuring Monitors in an LB Setup” on page
223. You must provide values for the required parameters to create a monitor of
type RADIUS.
Monitoring DNS Services
The DNS monitors use the DNS protocol to determine the state of the DNS
server. The DNS monitor sends a DNS query to the server that resolves the query
to an IP address. The resolved IP address is then checked against the list of
previously configured IP addresses. The IP address list can contain a maximum of
five IP addresses.
RADIUS NAS ID The NAS-ID that is encapsulated in the payload when an
access request is made.
RADIUS NA SIP The 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.
Parameters Descriptions
Chapter 4 Load Balancing 243
If the resolved IP address matches at least one of the IP addresses in the IP
address list, the DNS service is marked as up. If the resolved IP does not match
any of the IP addresses in the list, the DNS service is marked as down. To monitor
DNS services, use the parameters as described in the following table.
To configure prebuilt monitors to check the state of the DNS server, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create a monitor of type DNS.
Monitoring LDAP Services
LDAP monitors use the LDAP protocol to determine the state of the services. The
LDAP monitors authenticate and send a query to the LDAP server to locate an
entity in the LDAP server. The LDAP monitors determine the state of the LDAP
services using the response of the LDAP server.
The LDAP monitors can specify a location (using the Base DN parameter) in the
directory hierarchy where the LDAP server starts the query. You can also specify
an attribute of the target entity. The LDAP server uses the fields that the monitor
provides to search for the target entity. If the search is successful, the health check
is considered good and the service is marked up. If the LDAP server does not
locate the entry, a failure message is sent to the LDAP monitors and the service is
marked down. To monitor LDAP services, use the parameters as described in the
following table.
Parameters Descriptions
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.
Query Type The type of DNS query that is sent. Possible values:
Address, Zone.
IP Address List of IP addresses that are checked against the response
to the DNS monitoring probe. Applicable only to the DNS
monitors.
Parameters Descriptions
Base DN 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.
Bind DN BDN name for the LDAP monitor.
Filter Filter for the LDAP monitor.
244 Installation and Configuration Guide - Volume 1
To configure prebuilt monitors to check the state of the LDAP server, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create a monitor of type LDAP.
Monitoring MySQL Services
The MySQL monitor sends a query to the MySQL server to locate an entity in the
database and determines the state of the MySQL services using the response from
the database. If the entity exists in the database, the health check is considered
good and the service is marked up. If the entity is not found in the database, a
failure message is sent to the MySQL monitors and the service is marked down.
To monitor MySQL services, use the parameters as described in the following
table.
To configure prebuilt monitors to check the state of the MySQL server, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create a monitor of type MySQL.
Monitoring SNMP Services
The SNMP monitor periodically probes the SNMP devices for performance and
fault data. SNMP monitors check the SNMP agent running on an SNMP device.
You must specify an OID (enterprise identification ID) when you configure the
monitor. SNMP monitor sends a query to the SNMP devices for an OID and
compares the response to the OID that you provide. The SNMP monitors
determine the state of the SNMP services using the response.
If the SNMP device does not have the OID that you specified, the SNMP monitor
determines the state of the service as DOWN. To monitor SNMP services, use the
parameters as described in the following table.
Password Password used in monitoring LDAP servers.
Attribute Attribute for the LDAP monitor.
Parameters Descriptions
Database Database that is used for the MYSQL monitor.
SQL Query SQL query that is used for the MYSQL monitor.
Parameters Descriptions
SNMP OID OID that is used for the SNMP monitor.
SNMP Community Community that is used for the SNMP monitor.
SNMP Threshold Threshold that is used for the SNMP monitor.
Parameters Descriptions
Chapter 4 Load Balancing 245
To configure prebuilt monitors to check the state of SNMP device, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create a monitor of type SNMP.
Monitoring NNTP Services
The NNTP monitor periodically probes NNTP servers to determine the state of
the NNTP servers. The NNTP monitor specifies the name and password to access
the NNTP servers. The NNTP monitor connects to the NNTP server to check for
the existence of a particular Internet newsgroup. If the newsgroup exists, the
NNTP services are marked up. The NNTP monitor records the number of news
items in the newsgroup. The monitor also can write a test message to the
newsgroup. To monitor NNTP services, use the parameters as described in the
following table.
To configure prebuilt monitors to check the state of NNTP services, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create monitors of type NNTP.
Monitoring POP3 Services
The POP3 monitor uses the POP3 protocol to check the following:
• A POP3 client opens a connection with a POP3 server.
• The POP3 server responds with the correct codes.
• The POP3 server responds within a required number of seconds.
To monitor POP3 services, use the parameters as described in the following table.
SNMP Version SNMP version that is used for load monitoring. The valid
options for this parameter are V1 and V2.
Parameters Descriptions
User Name Username on the
RADIUS/NNTP/FTP/FTP-EXTENDED/MYSQL/POP3
server. This user name is used in the probe.
Password Password used in monitoring RADIUS/NNTP/FTP/FTP-
EXTENDED/MYSQL/POP3/LDAP servers.
Group Group name to be queried for NNTP monitor.
Parameters Descriptions
User Name Username POP3 server. This user name is used in the
probe.
Parameters Descriptions
246 Installation and Configuration Guide - Volume 1
To configure prebuilt monitors to check the state of POP3 services, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create monitors of type POP3.
Monitoring SMTP Services
The SMTP monitor uses the SMTP protocol to check the outgoing mail services.
The servers use the SMTP protocol to deliver e-mail messages. The SMTP
monitor connects to the SMTP server and conducts a sequence of handshakes to
ensure that the server is operating correctly. To monitor SMTP services, use the
parameters described in the following table.
To configure prebuilt monitors to check the state of SMTP services, see
“Configuring Monitors in an LB Setup” on page 223. You must provide values
for the required parameters to create monitors of type SMTP.
Monitoring Citrix Presentation Server Component
You can use Citrix Presentation Server (CPS) component monitors to check
various services of the CPS (XML-SERVICE, WEB Interface). These monitors
are used in data centers where CPS systems are installed.
To create monitors for XML-SERVICE and WEB Interface services, see
“Creating Monitors” on page 224.
Password Password used in monitoring POP3 servers.
Script Name The path and name of the script to execute.
Dispatcher IP Address The IP address of the dispatcher to which the probe is sent.
Dispatcher Port The port of the dispatcher to which the probe is sent.
Parameters Descriptions
User Name Username SMTP server. This user name is used in the
probe.
Password Password used in monitoring SMTP servers.
Script Name The path and name of the script to execute.
Dispatcher IP Address The IP Address of the dispatcher to which the probe is
sent.
Dispatcher Port The port of the dispatcher to which the probe is sent.
Parameters Descriptions
Chapter 4 Load Balancing 247
Monitoring Applications and Services Using
Customized Monitors
This section describes the customized monitors, and how you can use them to
check the state of applications and services. The NetScaler provides customized
monitors that determine the state of services based on the load on the service,
network traffic of the service, or user-defined scripts. The customized monitors
are the load monitors, inline monitors, and user monitors. Customized monitors
also allow you to define scripts and use the scripts to determine the state of the
service.
Configuring Inline Monitors
Inline monitors analyze and probe the responses from the servers only when the
client requests are sent to the server. They do not probe if the responses from the
servers are deduced from traffic of the servers that are up. When there are no
client requests to the server, inline monitors use the configured URL to probe the
server as a regular HTTP monitor.
The inline monitor is of type HTTP-INLINE and can only be configured to work
with HTTP and HTTPS services. Inline monitors cannot be bound to HTTP or
HTTPS GSLB remote or local services. These services represent vservers.
Inline monitors also have a timeout value and a retry count on failure of probes.
You can select one of the following action types that the NetScaler takes 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. This setting breaks any persistent connections to the service. This
action also logs the event and displays the counters.
After the service is down, the service remains in the down state for the configured
down time. After the down time, the configured URL is used to probe to check if
the service is up. If the probe succeeds, the state of the service is changed to up.
Traffic is directed to the service, and URL probes and traffic are sent to monitor
to check the state of the service, as needed. To configure inline monitors, see
“Configuring Monitors in an LB Setup” on page 223.
248 Installation and Configuration Guide - Volume 1
Configuring User Monitors
User monitors extend the scope of custom monitors. You can create user monitors
to track the health of customized applications and protocols that the NetScaler
does not support originally. The following diagram illustrates how the user
monitor works.
User monitors
As illustrated in the figure, a user monitor requires the following components.
Dispatcher
A dispatcher is a process on the NetScaler that listens to monitoring requests. It
can be on the loopback IP address (127.0.0.1) and port 3013. These dispatchers
are also known as internal dispatchers.
A dispatcher may also be a Web server that supports CGI. Such dispatchers are
also known as external dispatchers. They are used for custom scripts that do not
run on the FreeBSD environment, such as .NET scripts.
Note: Communication between the monitor and the dispatcher can use HTTPS
if you enable the “secure” option on the monitor. However, the internal dispatcher
understands only HTTP, and cannot use HTTPS.
In a high availability setup, the dispatcher runs on both the primary and secondary
NetScalers. The dispatcher remains inactive on the secondary NetScaler.
Chapter 4 Load Balancing 249
Script
The script is a program that sends out custom probes to the back-end entity and
returns the response code to the dispatcher. The NetScaler is bundled with sample
scripts for commonly used protocols. The scripts exist in the /nsconfig/monitors
directory. If you want to add a new script, add the script in the location /nsconfig/
monitors. If you want to customize an existing script, copy the script with a new
name and modify the script. For the scripts to function correctly, the name of the
script file must not exceed 63 characters, and the maximum number of script
arguments is 512. To debug the script, you must run it using the nsumon-debug.pl
on the Command Line Interface (CLI). You must use the script name (with its
arguments), IP address, and the port as the arguments of the nsumon-debug.pl
script.
Working of User Monitors
To track the status of the server, the monitor sends an HTTP POST request to the
configured dispatcher. This POST request contains the IP address and port of the
server, and the script that must be executed.
The dispatcher executes the script as a child process, with user-defined
parameters (if any). Then, the script sends a probe to the server. The script sends
the status of the probe (response code) to the dispatcher. The dispatcher converts
the response code to an HTTP response and sends it to the monitor. Based on the
HTTP response, the monitor marks the service as up or down.
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.
The HTTP response codes are summarized in the following table.
HTTP Response code Meaning
200 - success Probe success.
503 - service unavailable Probe failure.
404 - not found Script not found or cannot execute.
500 - Internal server error Internal error/resource constraints in dispatcher (out of
memory, too many connections, unexpected system error, or
too many processes). The service does not go down.
400 - bad request Error parsing HTTP request.
502 - bad gateway Error decoding script's response.
250 Installation and Configuration Guide - Volume 1
To monitor user service, use the parameters as described in the following table.
You can use a custom user monitor with the internal dispatcher. Consider a
scenario where you need to track the health of a server based on the presence of a
file on the server. The following figure illustrates this scenario.
Using a user monitor with the internal dispatcher
A possible solution can be to use a Perl script that initiates an FTP session with
the server and checks for the presence of the file. You can then create a user
monitor that uses the Perl script. The NetScaler includes such a Perl script
(nsftp.pl), located in the /nsconfig/monitors/ directory.
Parameters Descriptions
Script Name The path and name of the script to execute.
Script Arguments The strings that are added in the POST data. They are
copied to the request verbatim.
Dispatcher IP Address The IP Address of the dispatcher to which the probe is
sent.
Dispatcher Port The port of the dispatcher to which the probe is sent.
Chapter 4 Load Balancing 251
You can use a user monitor with an external dispatcher. Consider a scenario
where you must track the health of a server based on the state of an SMTP service
on another server. This scenario is illustrated in the following figure.
Using a user monitor with an external dispatcher
A possible solution would be to create a Perl script that checks the state of the
SMTP service on the server. You can then create a user monitor that uses the Perl
script. To configure user monitors, see “Configuring Monitors in an LB Setup” on
page 223.
252 Installation and Configuration Guide - Volume 1
Configuring Load Monitors
Load monitors use the SNMP polled OIDs to calculate the load on the services.
The load monitor uses the IP address of the service or the destination IP address
for polling. The load monitor sends an SNMP query to the server, specifying the
OID for a metric. The metrics can be CPU, memory, or number of server
connections. The server responds to the query with a metric value. The metric
value in the response is compared with the threshold value. The NetScaler
considers the service for load balancing only if the metric is less than the
threshold value. The service with the lowest load value is considered for handling
client requests. The following figure illustrates a load monitor configured for the
services described in the basic LB setup, as discussed in the section “Configuring
a Basic Setup” on page 114.
Working of load monitors
Note: The load monitor does not determine the state of the service. It only
enables the NetScaler to consider the service for load balancing.
To configure the load monitor, use the metric table parameter as described in the
following table.
Parameters Descriptions
Metric Table Metric table to use for the metrics that must be bound. The
maximum value is 99.
Chapter 4 Load Balancing 253
To configure load monitors, see “Configuring Monitors in an LB Setup” on page
223. You must select the metric table to configure load monitors. The following
sections describe the steps to configure metrics.
Configuring Metrics for Load Assessments
For load assessment, the load monitor considers server parameters known as
metrics. These metrics are defined within the metric tables in the NetScaler.
Metric tables can be of two types:
• Local: By default, this table exists in the NetScaler. It consists of four
metrics: connections, packets, response time, and bandwidth. The
NetScaler specifies these metrics for a service, and SNMP queries are not
originated for these services. These metrics cannot be changed.
• Custom: A user-defined table. Each metric is associated with an object
identifier (OID).
By default, the NetScaler generates the following tables:
• Netscaler
• RADWARE
• CISCO-CSS
• LOCAL
• FOUNDRY
• ALTEON
You can either add the NetScaler-generated metric tables, or you can add tables of
your own choosing, as shown in the following table. The values in the metric
table are provided only as examples. In an actual scenario, consider the real
values for the metrics.
Threshold Value for a Metric
You can set the threshold value for each metric. The threshold value enables the
NetScaler to select a service for load balancing, if the metric value for the service
is less than the threshold value. The threshold value also determines the load on
each service.
Metric Name OIDs Weight Threshold
CPU 1.2.3.4 2 70
Memory 4.5.6.7 3 80
Connections 5.6.7.8 4 90
254 Installation and Configuration Guide - Volume 1
Weight for a Metric
To calculate the load for one or more metrics, you can assign a weight to each
metric. The default weight is 1. The weight represents the priority given to each
metric. If the weight is high, the priority is high. The NetScaler chooses a service
based on the SOURCEIPDESTIP hash algorithm.
Creating Metric Tables
You can create metric tables to configure the metrics for load balancing. The
metric table defines a set of metrics that determine the state of the server. To
create metric table, use the Metric Table Name parameter as described in the
following table.
The following example describes the steps to create a metric table
Table-Custom-1.
To create a metric table using the configuration utility
1. In the navigation pane, expand Load Balancing and click Metric Tables.
The Metric Tables page appears in the details pane.
2. Click Add. The Create Metric Table dialog box appears.
3. In the Metric Table Name text box, type the name of the metric table, for
example, Table-Custom-1.
4. Click Create and click Close. The metric table you created appears in the
Metric Tables page, as shown in the following figure.
Metric table page
Parameters Descriptions
Metric Table Name The name of the metric table. This name must not exceed
31 characters.
Chapter 4 Load Balancing 255
To create a metric table using the NetScaler command line
At the NetScaler command prompt, type:
add metricTable Table-Custom-1
Binding Metrics to Metric Tables
You can bind each metric to a metric table. The metrics can be any SNMP OID.
The load monitor uses the metrics bound to the metric table to calculate the load
on the services. The following example describes the steps to bind the metric
1.3.6.1.4.1.5951.4.1.1.41.1.5 with SNMP OID 11 to the metric table
Table-Custom-1.
To bind metrics to a metric table using the configuration utility
1. In the navigation pane, expand Load Balancing and click Metric Tables.
The Metric Tables page appears in the details pane.
2. Select the metric table to which you want to bind the metrics, for example,
Table-Custom-1.
3. Click Open. The Configure Metric Table dialog box appears.
4. In the Metrics and SNMP OID text boxes, type metric and SNMP OID for
the metric table, for example, 1.3.6.1.4.1.5951.4.1.1.41.1.5 and 11.
5. Click Add. The metric appears in the Bound Metrics list box.
6. Click OK.
To bind metrics to a metric table using the NetScaler command line
At the NetScaler command prompt, type:
bind metricTable Table-Custom-1 1.3.6.1.4.1.5951.4.1.1.41.1.5 11
Removing a Metric Table
The following example describes the steps to delete the metric table
Table-Custom-1.
To remove a metric table using the configuration utility
1. In the navigation pane, expand Load Balancing and click Metric Tables.
The Metric Tables page appears in the details pane.
2. Select the metric table that you want to remove, for example,
Table-Custom-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
256 Installation and Configuration Guide - Volume 1
To remove a metric table using the NetScaler command line
At the NetScaler command prompt, type:
rm metricTable Table-Custom-1
Unbinding a Metric Table
The following example describes the steps to unbind the metrics
1.3.6.1.4.1.5951.4.1.1.41.1.5 with SNMP OID 11 from the metric table.
To unbind metrics from a metric table using the configuration utility
1. In the navigation pane, expand Load Balancing and click Metric Tables.
The Metric Tables page appears in the details pane.
2. Select the metric table from which you want to unbind the metrics, for
example, Table-Custom-1.
3. Click Open. The Configure Metric Table dialog box appears.
4. In the Bound Metrics list box, select the metrics that you want to unbind
from the table, for example, 1.3.6.1.4.1.5951.4.1.1.41.1.5.
5. Click Remove and click OK.
To unbind metrics from a metric table using the NetScaler command line
At the NetScaler command prompt, type:
unbind metricTable Table-Custom-1 1.3.6.1.4.1.5951.4.1.1.41.1.5
Viewing the Properties of a Metric Table
You can view all the metric tables that are configured. You can view the details
such as name and type of the metric tables to determine if the metric table is
internal or configured.
To view the metric tables using the configuration utility
1. In the navigation pane, expand Load Balancing and click Metric Tables.
The Metric Tables page appears in the details pane. The details of the
available metric table appear on this page.
To view the metric tables using the NetScaler command line
At the NetScaler command prompt, type:
show metricTable Table-Custom-1
Chapter 4 Load Balancing 257
Configuring Support for Third-party Load
Balancers Using SASP
The Server Application State Protocol (SASP) allows the NetScaler to perform
load balancing based on the weights of the services. A WLM (work load
manager) agent runs on each of the servers and relays performance data to the
EWLM. The EWLM (enterprise work load manager) uses this data to
dynamically calculate the weight for each server. The EWLM uses the PUSH
model to send the dynamically calculated weights to the NetScaler (because the
NetScaler supports the PUSH model).
The prerequisites for dynamic weight calculation are:
• The EWLM is configured as an entity within the NetScaler.
• A connection is established between the EWLM and the vserver.
• The services bound to the vserver are registered in the EWLM.
The following diagram shows how SASP facilitates load balancing decisions
using the Group Workload Manager:
SASP load balancing
258 Installation and Configuration Guide - Volume 1
Communication between the NetScaler and EWLM is achieved through a set of
SASP messages. When the NetScaler is connected to the EWLM, a
set l bst at e message is sent to the EWLM to indicate that the connection is
established. After the connection is established, the NetScaler sends a registration
message to the EWLM. This message conveys that all the services are registered
with the EWLM. The EWLM responds with a registration success or failure
message.
A connection is established only when a vserver is bound to the WLM in the
NetScaler. After all the services are registered, the EWLM starts sending weight
data to the NetScaler using the sendweight message. The WLM that is connected
to each of the services sends the weight messages to the EWLM, as shown in the
figure above. The weight is calculated for the registered services only.
the NetScaler waits for two minutes (default wait time) to receive the weight
message from the EWLM. If the NetScaler receives the weight message within
two minutes, the weight is dynamically calculated from the incoming weight
message. If not, the NetScaler considers the user configured weights for making
load balancing decisions.
If a service is disabled in the NetScaler, a set member st at e message is sent to
the EWLM conveying that the disabled service is not considered for load
balancing. The NetScaler sends a deregistration message to the EWLM to
deregister or remove the disabled service. The EWLM responds with a
deregistration success or failure message.
Chapter 4 Load Balancing 259
The following example describes the steps to bind the services Service-HTTP-1
and Service-HTTP-2 to the vserver Vserver-LB-1. Vserver-LB-1 forwards the
client request to either of the two services Service-HTTP-1 or Service-HTTP-2.
The NetScaler selects the service for each request using the Least Connections
load balancing method. A workload manager Wlm-1 is created and bound to
Vserver-LB-1. The following figure shows the LB entities and the values of the
parameters.
WLM entity model
Creating Work Load Manager
You can create a work load manager to dynamically calculate the load on each
service. The NetScaler uses the load data to select services for load balancing. To
create a work load manager, use the parameters described in the following table.
Parameters Descriptions
Name The unique name of the work load manager. This name
must not exceed 31 characters.
IP Address The IP address of the work load manager.
LB unique identifier The unique identifier for the NetScaler to communicate to
the work load manager.
Port The port of the work load manager. The port number must
be a positive number and must not exceed 65535.
260 Installation and Configuration Guide - Volume 1
The following example describes the steps to create the work load manager Wlm-
1 with IP address 10.102.29.30, and LB unique identifier 11.
To create a work load manager using the configuration utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
2. Click Add. The Create Work Load Manager dialog box appears.
3. In the Name, IP Address, LB Unique Identifier, Port, and Keep Alive
Timeout (minutes) text boxes, type the corresponding values, for example,
Wlm-1, 10.102.29.30, 11, 80, and 2.
4. Click Create and click Close. The work load manager you created appears
in the Work Load Managers page, as shown in the following figure.
Work load manager page
To create a work load manager using the NetScaler command line
At the NetScaler command prompt, type:
add lb wlm wlm-1 10.102.29.30 -LBUID 11
Binding Vserver to Work Load Manager
The work load manager assigns weight to the service on which it runs. The
NetScaler requires a connection to balance the load on the services. When you
bind a vserver to a WLM, the connection is established and the NetScaler uses the
vserver to balance the services. The following example describes the steps to bind
the vserver Vserver-LB-1 to the work load manager Wlm-1.
Chapter 4 Load Balancing 261
To bind a vserver to a work load manager using the configuration utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
2. Select the work load manager for which you want to bind the vserver, for
example, Wlm-1.
3. Click Open. The Configure Work Load Manager dialog box appears.
4. Under Virtual Servers, in the Available list box, select the vserver that you
want to bind to the work load manager, for example, Vserver-LB-1.
5. Click Add. Under Virtual Servers, Vserver-LB-1 appears in the
Configured list box.
6. Click OK.
To bind a vserver to a work load manager using the NetScaler command line
At the NetScaler command prompt, type:
bind lb wlm wlm-1 Vserver-LB-1
Modifying the Work Load Manager
The NetScaler periodically probes the work load manger. You can modify the
time interval that the NetScaler uses to probe the WLM. To modify the time
period, use the keep alive timeout parameter as described in the following table.
The following example describes the steps to set the keep alive timeout value of
Wlm-1 to 20 minutes.
To modify a work load manager using the configuration utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
2. Select the workload manager that you want to modify, for example, Wlm-1.
3. Click Open. The Configure Work Load Manager dialog box appears.
4. In the Keep Alive Timeout (minutes) text box, type the timeout value, for
example, 20.
5. Click OK.
Parameters Descriptions
Keep Alive Timeout The idle time period after which the NetScaler probes the
work load manager. The value ranges from 2 to 1440
minutes. The default value is 2 minutes and the maximum
value is 1440 minutes.
262 Installation and Configuration Guide - Volume 1
To modify a work load manager using the NetScaler command line
At the NetScaler command prompt, type:
set lb wlm wlm-1 -KATimeout 20
Managing the Work Load Manager
This section describes how to manage the work load manager after you create it
in the LB setup. Managing the work load manager allows the NetScaler to use the
manually configured weights on the services. You can perform tasks such as
removing or unbinding the work load manager from the vserver.
Removing a Work Load Manager
You must remove a work load manager when you no longer require the NetScaler
to dynamically calculate the load on the service. When the work load manager is
removed the NetScaler uses the manually configured weights of the service to
balance the load. The following example describes the steps to remove the work
load manager Wlm-1.
To remove a work load manager using the configuration utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
2. Select the workload manager that you want to remove, for example,
Wlm-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a work load manager using the NetScaler command line
At the NetScaler command prompt, type:
rm lb wlm wlm-1
Unbinding a Work Load Manager
When you unbind a work load manager from a vserver, the NetScaler uses the
manually configured weights of the service to select the service. The following
example describes the steps to unbind the vserver Vserver-LB-1 from the work
load manager Wlm-1.
To unbind a vserver from a work load manager using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
Chapter 4 Load Balancing 263
2. Select the workload manager for which you want to unbind a vserver, for
example, Wlm-1.
3. Click Open. The Configure Work Load Manager dialog box appears.
4. Under Virtual Servers, in the Configured box, select the vserver that you
want to unbind from the work load manager, for example, Vserver-LB-1.
5. Click Remove. Under Virtual Servers, Vserver-LB-1 appears in the
Available box.
6. Click OK.
To unbind a vserver from a work load manager using the NetScaler
command line
At the NetScaler command prompt, type:
unbind lb wlm wlm-1 vservre-LB-1
Viewing a Work Load Manager
You can view the name, IP address, state, port, LB unique identifier, and keep
alive timeout of the configured work load mangers. Viewing the details of the
configuration is useful to check your setup.
To view work load managers using the configuration utility
1. In the navigation pane, expand Load Balancing and click Work Load
Managers. The Work Load Managers page appears in the details pane.
The details of the available work load managers appear in the Work Load
Managers page.
To view work load managers using the NetScaler command line
At the NetScaler command prompt, type:
show lb wlm wlm-1
Managing a Large Scale Deployment
This section describes procedures to create groups of vservers and services, to
create a range of vservers and services, and to translate or mask vserver and back-
end server IP addresses.
Creating groups of vservers and services enables you to easily manage the LB
setup. You can perform several tasks on such groups, including setting
persistence for the group of vservers, binding the monitors for the service groups,
and so forth.
264 Installation and Configuration Guide - Volume 1
Creating a range of vservers and services of identical type in a single procedure
improves the speed of the LB configuration. You can also use this option to avoid
repeating steps when you create services or vservers of the same type.
Translating or masking an IP address enables you to take down servers and make
changes to your infrastructure without extensive reconfiguration of your server
and virtual server definitions.
Topics include:
• Configuring a Range of Vservers and Services
• Configuring Service Groups
Configuring a Range of Vservers and Services
When you configure load balancing, you can also create ranges of vservers and
services. This procedure allows you to configure load balancing more quickly
than if you configure vservers and services individually.
For example, you can use a single procedure to create three virtual servers using
port 80: vserverx, vservery, and vserverz, at IPs 10.102.29.31, 10.102.29.32, and
10.102.29.33.
When more than one argument uses a range, all of the ranges must be of the same
size. For example, when adding vserverx and vservery, you must use two ranges,
each containing two elements: [x-y] and [1-2].
If your configuration has a large number of virtual servers, you can add them all
to the configuration at once and save considerable time. The following are the
types of ranges you can specify when adding services and vservers to your
configuration:
• Numeric ranges. Instead of typing a single number, you can type a range
that includes the numbers in the range; in this case, 20, 21, 22, 23, 24, and
25.
In the following example, a range of servers is created, with IP addresses
10.102.29.[30-35]. The IP addresses within the range are included; in this
case, 10.102.29.30, 10.102.29.31, 10.102.29.32, 10.102.29.33,
10.102.29.34, and 10.102.29.35.
• Alphabetic ranges. Instead of typing a literal letter, you can substitute a
range for any single letter, for example, [C-G]. This results in all letters in
the range being included, in this case C, E, F, and G.
For example, if you have three vservers named vserverx, vservery, and
vserverz, instead of configuring them separately, you can type vserver [x-z]
to configure them all.
Chapter 4 Load Balancing 265
Note: For this procedure to work, the IP addresses of the services must be
consecutive.
To create a range of vservers and services, use the parameters as described in the
following table.
The following example describes the steps to create a range of vservers from
10.102.29.30 to 10.102.29.35.
To create range of vservers using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Click Add Range. The Create Virtual Server (Load Balancing) - Range
dialog box appears.
3. In the Name Prefix, IP Address Range, and Port text boxes, type the
vserver name, IP address range, and port, for example, vserver,
10.102.29.30, and 80.
4. In the text box next to the IP Address Range text box, type the last value of
the last vserver, for example, 35.
5. In the Protocol drop-down list box, select the protocol type, for example,
HTTP.
6. Click Create and click Close. The range of vservers you created appears in
the Load Balancing Virtual Servers page.
To create range of vservers using the NetScaler command line
At the NetScaler command prompt, type:
add lb vserver Vserver-LB-2 http -range 5 10.102.29.30 80
The following example describes the steps to create a range of services from
10.102.29.102 to 10.102.29.104
Parameters Description
Name Allow for the creation and manipulation of a range of
vservers. Ranges specify a consecutive array of entities.
The command will return an error if the ranges differ.
IP Address range Specifies an address range. When adding a range of
entities, dependent arguments must specify a matching
range.
266 Installation and Configuration Guide - Volume 1
To create range of services using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Click Add Range. The Create Services (Range) dialog box appears.
3. In the IP Address Range and Port text boxes, type the start value of the IP
address range and the port, for example, 10.102.29.102, and 80.
4. In the text box next to the IP Address Range text box, type the last value of
the last service, for example, 104.
5. In the Protocol drop- down list box, select the protocol type, for example,
HTTP.
6. Click Create and click Close. The range of services you created appears in
the Services page.
To create range of vservers using the NetScaler command line
At the NetScaler command prompt, type:
add lb vserver Vserver-LB-2 http -range 5 10.102.29.30 80
Configuring Service Groups
Configuring service groups allows you to manage multiple servers with ease. A
service group is a representation of one or more services. You can add servers and
services to the service groups. You can create, modify, and manage service
groups.
Note: Domain-based and transparent service groups are not supported.
Creating Service Groups
You can create a service group and add services to it. You can also modify,
monitor, and remove service groups. The NetScaler allows you to configure 4096
service groups. To create a service group, use the parameters in the following
table.
Parameter Description
Name The name of the service group. The service name must not
exceed 31 characters. This parameter cannot be changed
Service Type This parameter determines the behavior of the service
group. The valid options are: HTTP, TCP, FTP, UDP, SSL,
SSL_TCP, SSL_BRIDGE, NNTP, DNS, and ANY
Chapter 4 Load Balancing 267
The following example describes the steps to create a service group
Service-Group-1 of type HTTP.
To create a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Click Add. The Create Service Group dialog box appears.
3. In the Service Group Name text box, type name of the service group, for
example, Service-Group-1.
4. In the Protocol list, select the protocol type, for example, HTTP.
5. Click Create and click Close. The service group you created appears in the
Service Groups page, as shown in the following figure.
Service group page
To create a service group using the NetScaler command line
At the NetScaler command prompt, type:
add servicegroup Service-Group-1 HTTP
Binding a Service Group to a Vserver
When you bind a service group to a vserver, the member services are bound to the
vserver. The following example describes the steps to bind the service group
Service-Group-1 to a vserver Vserver-LB-1.
To bind a service group to a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
268 Installation and Configuration Guide - Volume 1
2. Select the vserver to which you want to bind the service group, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Services Groups tab. The service groups appear in the Services
Groups tab.
5. Select the Active check box next to the service group that you want to bind
to the vserver, for example, Service-Group-1.
6. Click OK.
To bind a service group to a vserver using the NetScaler command line
At the NetScaler command prompt, type:
bind lb vserver Vserver-LB-1 Service-Group-1
Binding a Member to a Service Group
Adding servers to a service group enables the service group to manage the
servers. You can add the servers to a service group using the IP addresses or
names of the servers. When you add a server to the service group using the IP
address, the server is created with the IP address as its name. The following
example describes the steps to add a server with IP address 10.102.29.30, and
port 80 to the service group Service-Group-1.
To add members to a service group using IP address (using the
configuration utility)
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group for which you want to bind members, for example,
Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. Under Specify Member (s), select the IP Based radio button.
5. In the IP Address text box, type the IP address, for example, 10.102.29.30.
6. In the Port text box type the port, for example, 80
7. Click Add. The service appears under Configured Members.
8. Click OK.
To add members to a service group using IP address (using the NetScaler
command line)
At the NetScaler command prompt, type:
Chapter 4 Load Balancing 269
bind servicegroup Service-Group-1 10.102.29.30 80
You can also bind a server to the service group using the name of the server. The
following example describes the steps to bind a member Server-50 to the service
group Service-Group-1.
To bind members to a service group using names of servers (using the
configuration utility)
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group for which you want to bind members, for example,
Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. Under Specify Member (s), select the Server Based radio button.
5. In the Server Name list, select a server, for example, Server-50.
6. In the Port text box type the port, for example, 80.
7. Click Add. The service appears under Configured Members.
8. Click OK.
To bind members to a service group using names of servers (using the
NetScaler command line)
At the NetScaler command prompt, type:
bind servicegroup Service-Group-1 Server-50 80
Binding a Monitor to a Service Group
You can bind and unbind monitors from the service groups. Monitors periodically
probe the servers in the service group and update the state of the service groups.
The following example describes the steps to bind the ping monitor to the service
group Service-Group-1.
To bind monitor to a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group for which you want to bind monitors, for example,
Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. Click the Monitors tab.
270 Installation and Configuration Guide - Volume 1
5. Under Available, in the Monitors list box, select a monitor type, for
example, ping.
6. Click Add. The service appears under Configured.
7. Click OK.
To bind monitor to a service group using the NetScaler command line
At the NetScaler command prompt, type:
bind mon monitor-HTTP-1 Service-Group-1
Modifying a Service Group
You can modify attributes of service group members. You can set several
attributes of the service group, such as: maximum client, sure connect, and
compression. The 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. To modify a service group, use the
parameters described in the following table.
Parameters Descriptions
Cache Type The cache server supports the cache type option. The valid options
are: TRANSPARENT, REVERSE, and FORWARD.
Maximum Client The maximum number of open connections to each service in the
service group. The default value is 0. The maximum value is
4294967294.
Maximum
Requests
The maximum number of requests that can be sent over a
persistent connection to a service in the service group. The default
value is 0. The minimum value is 0. The maximum value is 65535.
Cacheable Specifies whether a vserver used in the NetScaler 9000 load
balancing or content switching feature routes a request to the
vserver (used in transparent cache redirection) on the same
NetScaler 9000 before sending it to the configured servers. The
vserver used for transparent cache redirection determines if the
request is directed to the cache servers or the configured servers.
Do not specify this argument if a cache type is specified. By
default, this argument is disabled. The valid options are: yes and
no. The default value is no.
Client IP Enables or disables insertion of the Client IP header for services in
the service group. The valid options for this parameter are: enabled
and disabled. The default value is disabled.
Client IP Header The client IP header. If client IP insertion is enabled and the client
IP header is not specified, then the NetScaler sets the value of the
Client IP header.
Chapter 4 Load Balancing 271
The following example describes the steps to set the maximum client parameter
to 5000 for the service group Service-Group-1.
Note: Any parameter you set on the service group is applied to the member
servers in the group, and not to individual services.
Use Source IP Enables or disables use of the client IP address as the source IP
address while connecting to the server. By default, the NetScaler
uses a mapped IP address for its server connection. However, with
this option, you can tell the Netscaler 9000 to use the client's IP
address when it communicates with the server. Possible values: yes
and no. Default value: no.
SC The state of SureConnect on this service group. This parameter is
supported for legacy purposes only; it has no effect, and the only
valid value is OFF. Possible values: ON and OFF. Default value:
OFF.
SP Whether surge protection needs to be enabled on this service
group. Possible values: ON and OFF. Default value: OFF.
Client Timeout The idle time in seconds after which the client connection is
terminated. Default value: 180. Maximum value: 31536000.
Server Timeout The idle time in seconds after which the server connection is
terminated. The default value is 360. The maximum value is
31536000.
CKA The state of the Client Keep-Alive feature for the services in the
service group. The valid options for this parameter are: yes and no.
The default value is no.
TCPB The state of the TCP Buffering feature for the services in the
service group. The valid options for this parameter are: yes and no.
The default value is no.
CMP The state of the HTTP Compression feature for the services in the
service group. The valid options for this parameter are: yes and no.
The default value is no.
Maximum
Bandwidth
A positive integer that identifies the maximum bandwidth in
kilobits allowed for the services in the service group.
Monitor Threshold The monitoring threshold. The default value is 0. The minimum
value is 0 and maximum value is 65535.
State The state of the service group after it is added. The valid options
for this parameter are: enabled and disabled. The default value is
enabled.
DownStateFlush Perform delayed cleanup of connections on this service group. The
valid options for this parameter are: enabled and disabled. The
default value is enabled.
Parameters Descriptions
272 Installation and Configuration Guide - Volume 1
To modify a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group that you want to modify, for example,
Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. Click the Advanced tab.
5. In the Max Clients text box, type the maximum number of clients, for
example, 5000.
6. Click OK.
To modify a service group using the NetScaler command line
At the NetScaler command prompt, type:
set servicegroup Service-Group-1 -maxClient 5000
Managing Service Groups
This section describes how to manage the service groups after you create them in
the LB setup. Managing the service group enables you to change the settings of
the services in the service group. You can perform tasks such as enabling,
disabling, and removing service groups. You can also unbind members from the
service group.
Removing a Service Group
When you remove a service group, the servers bound to the group retain their
individual settings and continue to exist on the NetScaler. The following example
describes the steps to delete the service group Service-Group-1.
To remove a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group that you want to remove, for example,
Service-Group-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a service group using the NetScaler command line
At the NetScaler command prompt, type:
rm servicegroup Service-Group-1
Chapter 4 Load Balancing 273
Unbinding a Member froma Service Group
When you unbind a member from the service group, the attributes set on the
service group do not apply to the members. The member services retain their
individual settings and continue to exist on the NetScaler. The following example
describes the steps to unbind a server with IP address 10.102.29.30, and port 80
from the service group Service-Group-1.
To unbind members from a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group from which you want to unbind members, for
example, Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. In the Configured Members list box, select a service, for example,
10.102.29.30.
5. Click Remove and click OK.
To unbind members from a service group using the NetScaler command line
At the NetScaler command prompt, type:
unbind servicegroup Service-Group-1 10.102.29.30 80
Unbinding a Service Group froma Vserver
When you unbind a service group from a vserver, the member services are
unbound from the vserver and continue to exist on the NetScaler. The following
example describes the steps to unbind the service group Service-Group-1 from a
vserver Vserver-LB-1.
To unbind a service group from a vserver using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
The Load Balancing Virtual Servers page appears in the details pane.
2. Select the vserver from which you want to unbind the service group, for
example, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Services Groups tab. The service groups appear in the Services
Groups tab.
274 Installation and Configuration Guide - Volume 1
5. Clear the Active check box next to the service group that you want to
unbind from the vserver, for example, Service-Group-1.
6. Click OK.
To unbind a service group from a vserver using the NetScaler command line
At the NetScaler command prompt, type:
unbind lb vserver Vserver-LB-1 Service-Group-1
Unbinding Monitors fromService Groups
When you unbind a monitor from a service group, the monitor no longer probes
the individual services that constitute the group. The following example describes
the steps to unbind the monitor monitor-HTTP-1 from the service group
Service-Group-1.
To unbind a monitor from a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group from which you want to unbind the monitor, for
example, Service-Group-1.
3. Click Open. The Configure Service Group dialog box appears.
4. In the Configure Service Group dialog box, click the Monitors tab.
5. Under Configured, select the monitor that you want to unbind from the
service group, for example, monitor-HTTP-1.
6. Click Remove. The monitor appears under Available in the Monitors list
box.
7. Click OK.
To unbind a monitor from a service group using the NetScaler command
line
At the NetScaler command prompt, type:
unbind mon monitor-HTTP-1 Service-Group-1
Enabling and Disabling a Service Group
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, the service
groups are enabled. The following example describes the steps to disable the
service group Service-Group-1 after a wait time of 30 seconds.
Chapter 4 Load Balancing 275
To disable a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group that you want to disable, for example,
Service-Group-1.
3. Click Disable. The Wait Time pop-up window appears.
4. In the Wait Time pop-up window type the wait time value,
for example, 30.
5. Click Enter.
To disable a service group using the NetScaler command line
At the NetScaler command prompt, type:
disable servicegroup Service-Group-1
The following example describes the steps to enable the service group
Service-Group-1.
To enable a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group that you want to enable,
for example, Service-Group-1.
3. Click Enable. The Enable pop-up window appears.
4. Click Yes.
To enable a service group using the NetScaler command line
At the NetScaler command prompt, type:
enable servicegroup Service-Group-1
Viewing the Properties of a Service Group
You can view the following settings of the configured service groups: name, IP
address, state, protocol, maximum client connections, maximum requests per
connection, maximum bandwidth, and monitor threshold. Viewing the details of
the configuration can be helpful for troubleshooting your configuration. The
following example describes the steps to view the service group Service-Group-1.
276 Installation and Configuration Guide - Volume 1
To view the properties of a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane. This pane displays
the details of all the available service groups.
To view the properties of a service group using the NetScaler command line
At the NetScaler command prompt, type:
show servicegroup Service-Group-1
Viewing Service Group Statistics
You can view the following data using the service group statistics link: rate of
requests, responses, request bytes, response bytes, and so on. The NetScaler uses
the statistics of a service group (rate of requests, responses, and so on) to balance
the load on the services. The following example describes the steps to view the
statistics of a service group Service-Group-1.
To view the statistics of a service group using the configuration utility
1. In the navigation pane, expand Load Balancing and click Service Groups.
The Service Groups page appears in the details pane.
2. Select the service group for which statistics you want to view, for example,
Service-Group-1.
3. Click Statistics. The statistics of the service group you selected appears in a
new window.
To view the statistics of a service group using the NetScaler command line
At the NetScaler command prompt, type:
stat servicegroup Service-Group-1
Translating the IP Address of a Domain-Based
Server
To simplify maintenance on a NetScaler and on the domain-based servers that are
connected to it, you can configure IP address masks and translation IP addresses.
These functions work together to parse incoming DNS packets and substitute a
new IP address for a DNS-resolved IP address.
When configured for a domain-based server, IP address translation enables the
NetScaler 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.
Chapter 4 Load Balancing 277
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. Note that 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. The mask blocks particular octets in the original server's
IP address. The DNS-resolved IP address is transformed to a new IP address by
applying the translation IP 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.
Note that the 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. The following table summarizes the parameters for configuring a
server IP address mask:.
Translation IP Parameters
Parameters Descriptions
Server Name
(serverName)
The name of the domain-based server.
IP Address / Domain Name
(serverDomainName)
The server's domain name (for example,
www.example.com).
Note that for IP address translation, the domain name is
required.
Translation IP Address
(translationIP)
The IP address (relevant octets only) to which the resolved
ip for the server needs to be translated. (for example,
11.12.0.0).
Translation Mask
(translationMask)
The mask determines the number of bits in the translation
IP address that are to be considered when applying the
transformation.
For example, if you want an original server IP of
10.20.30.40 to be translated to 11.12.30.40, you could
specify the mask 255.255.0.0.
278 Installation and Configuration Guide - Volume 1
Note: Translation of the IP address is only possible for domain-based servers.
You cannot use this feature for IP-based servers. Note also that the address pattern
can be based on IPv4 addresses only.
To configure a translation IP address for a server using the configuration
utility
1. In the navigation pane, expand Load Balancing and click Servers.
2. Click Add.
3. In theServer Name field, enter a name.
4. In theIP Address / Domain Name field, enter the server's domain name.
Do not enter an IP address if you are entering a mask.
5. In theTranslation IP Address field, enter the IP address of a server on the
same subnet.
6. In theTranslation Mask field, enter a valid mask (for example,
255.255.0.0).
7. Click Create.
To configure a translation IP address for a server using the NetScaler
command line
At the NetScaler command prompt, type:
add server serverName serverDomainName -translationIp
translationIPAddress -translationMask netMask -state
ENABLED|DISABLED
Example
add server myMaskedServer www.example.com -translationIp
10.10.10.10 -translationMask 255.255.0.0 -state ENABLED
Masking a Virtual Server IP Address
You can configure a mask and a pattern instead of a fixed IP address for a virtual
server. This enables traffic that is directed to any of several IP addresses to be
rerouted to a particular virtual server. For example, you can configure a mask that
allows the first three octets of an IP address to be variable, so that traffic to
111.11.11.198, 22.22.22.198, and 33.33.33.198 are all sent to the same virtual
server.
Chapter 4 Load Balancing 279
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. The mask allows the traffic to continue to flow without
extensive reconfiguration of your virtual servers.
The mask for a virtual server IP address works somewhat differently from the IP
pattern definition for a server as described in “Translating the IP Address of a
Domain-Based Server” on page 276. For a virtual server IP address mask, a non-
zero mask is interpreted as an octet that is considered (in the case of a server, 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 that the NetScaler 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
NetScaler 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. The following is an example:
• Destination IP address in the incoming packet: 10.102.27.189
• IP address pattern: 10.102.0.0
• IP mask: 255.255.0.0
• Constructed (final) destination IP address: 10.102.27.189. The first 16 bits
in the original destination IP address match the IP address pattern for this
virtual server, so this incoming packet can be considered by this virtual
server.
If a destination IP address matches the IP patterns in more than one virtual server,
the longest match takes precedence. The following is an example:
• Virtual Server 1: IP pattern 10.10.0.0, IP mask 255.255.0.0
• Virtual Server 2: IP pattern 10.10.10.0, IP mask 255.255.255.0
• Destination IP address in the packet: 10.10.10.45.
• Selected virtual server: Virtual Server 2. This virtual server has more bits
that are considered when compared to Virtual Server 1.
Note that ports are also considered if a tie-breaker is required.
280 Installation and Configuration Guide - Volume 1
The following table summarizes the parameters for a virtual server IP address
mask:
Note: You cannot convert a virtual server with a fixed IP address to a pattern-
based virtual server, and you cannot convert a pattern-based virtual server to one
with a fixed IP address.
To configure a virtual server IP address mask using the configuration utility
1. In the navigation pane, expand Load Balancing and click Virtual Servers.
2. Click Add.
3. In the Create Virtual Server dialog box, enter a name in the Name field.
4. In the Protocol field, select HTTP.
5. In the Port field, enter the listen port.
6. In the IP Pattern field, enter a pattern for an IP address (for example,
11.11.0.0). The fixed part of the pattern must be entered in contiguous
octets. Enter zeros for the pattern values that can vary in the IP address.
7. In the IP Mask field, enter a standard network mask (for example,
255.255.0.0). Use non-zero mask values for the portion of the IP address
that constitutes the fixed part of the pattern.
Virtual Server IP Address Mask Parameters
Parameters Descriptions
Name
(name)
The name of the load balancing virtual server.
Protocol
(ht t p)
A value of HTTP.
Port
(port)
The listen port for the virtual server.
Pattern Based (Configuration utility only.) Option to select if the virtual server is
to be pattern-based.
IP Pattern
(- i pPat t er n)
The IP address pattern for the virtual server. You must supply
either the initial or the trailing octets (for example, 11.11.00.00).
IP Mask
(- i pMask)
A network mask for the IP address. Non-zero values indicate the IP
address octets that are to be passed through. For example, for an IP
address pattern of 11.11.00.00, you might specify a mask of
255.255.0.0.
Chapter 4 Load Balancing 281
To configure a virtual server IP address mask using the NetScaler command
line
At the NetScaler command prompt, type:
add lb vserver lbVserverName http -ipPattern ipAddressPattern -
ipMask ipMask listenPort
Examples
Pattern matching based on prefix octets:
add lb vserver myLBVserver http -ippattern 10.102.0.0 -ipmask
255.255.0.0 80
Pattern matching based on trailing octets:
add lb vserver myLBVserver1 http -ippattern 0.0.22.74 -ipmask
0.0.255.255 80
Modify a pattern-based virtual server:
set lb vserver myLBVserver1 -ippattern 0.0.22.74 -ipmask
0.0.255.255
Configuring Load Balancing for Commonly Used
Protocols
This section describes the procedures to configure a functional LB setup for
common applications, including: load balancing for FTP servers, DNS servers,
SSL servers. The procedures discussed include creating the entities of the LB
setup and configuring appropriate monitors.
Topics include:
• Load Balancing for a Group of FTP Servers
• Load Balancing a Group of SSL Servers
• Load Balancing DNS Servers
• Load Balancing with Domain-Name Based Services
• Load Balancing a Group of SIP Servers
282 Installation and Configuration Guide - Volume 1
Load Balancing for a Group of FTP Servers
the NetScaler distributes client requests across the FTP servers to balance the
load on the FTP servers. When you initiate a control connection to the FTP
server, the NetScaler selects the FTP server and forwards incoming requests to it.
The FTP server opens a data connection to the client for information exchange. In
this way the NetScaler balances the load on the FTP servers. The following figure
describes the topology of an LB configuration to load balance a group of FTP
servers.
Basic LB topology for FTP servers
In the figure, the services Service-FTP-1, Service-FTP-2, and Service-FTP-3 are
bound to the vserver Vserver-LB-1. Vserver-LB-1 forwards the connection
request to one of the services using the Least Connections load balancing method.
Subsequent requests are forwarded to the service that the NetScaler initially
selected for load balancing. The following table lists the names and values of the
basic entities configured on the NetScaler.
Entity Type Name IP Address Port Protocol
Vserver Vserver-LB-1 10.102.29.25 21 FTP
Services Service-FTP-1 10.102.29.21 21 FTP
Service-FTP-2 10.102.29.22 21 FTP
Service-FTP-3 10.102.29.23 21 FTP
Monitors FTP None None None
Chapter 4 Load Balancing 283
The following figure shows the LB entities, and the values of the parameters that
need to be configured on the NetScaler.
Load balancing FTP servers entity model
To transfer a file, you must open a control connection to the FTP server. The
NetScaler selects an FTP server using the load balancing principle, and opens a
control connection to the selected FTP server. The FTP server also opens a data
connection that you can use to access the required file. The NetScaler can also
provide a passive FTP option to access the FTP servers from outside a firewall.
When you use this option and initiate a control connection to the FTP server, the
FTP server also initiates a control connection. You can then initiate a data
connection to transfer a file through the firewall.
The following sections describe the tasks required to implement this scenario:
1. Configuring a basic LB setup to load balance FTP server
2. Configuring FTP monitors
Configuring a Basic LB Setup to Load Balance FTP
Servers
To create services and vservers of type FTP, follow the procedure described in the
section “Configuring a Basic Setup” on page 114. Name the entities and set the
parameters to the values described in the Name and Value columns of the table in
the previous section.
284 Installation and Configuration Guide - Volume 1
Configuring FTP Monitors
When you configure a basic LB setup, a default monitor is bound to the services.
Next, bind the FTP monitor to the services by following the procedure described
in the section “Binding Monitors to Services” on page 225.
To configure FTP monitors using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Click Add. The Create Monitor dialog box appears.
3. In the Name and Interval text boxes, type monitor-FTP-1 and 340.
4. In the Type list, select FTP. In the Username and Password text boxes,
type User.
5. Click Create and click Close. The monitor monitor-FTP-1 that you
created appears in the Monitors Page.
To configure FTP monitors using the NetScaler command line
At the NetScaler command prompt, type:
add lb monitor monitor-FTP-1 FTP -interval 360 -userName User
-password User
Load Balancing a Group of SSL Servers
To load balance a group of SSL servers, see the SSL chapter of Installation and
Configuration guide.
Chapter 4 Load Balancing 285
Load Balancing DNS Servers
the NetScaler load balances DNS requests across the DNS servers. When you
request DNS resolution of a domain name, the NetScaler uses the load balancing
principle to select the DNS server. The DNS server then resolves the domain
name and returns the IP address as the response. The NetScaler can also cache the
responses, and can use the cached information to forward subsequent requests.
Load balancing the DNS servers improves the response of the DNS to client
requests. For more information about DNS and caching DNS records, see the
“DNS” chapter of the Installation and Configuration Guide. The following figure
describes the topology of an LB configuration that load balances a group of DNS
servers.
Basic LB topology for DNS servers
In the figure, the services Service-DNS-1, Service-DNS-2, and Service-DNS-3
are bound to the vserver Vserver-LB-1. The vserver Vserver-LB-1 forwards the
client request to one of the services using the least connections load balancing
method. The following table lists the names and values of the basic entities
configured on the NetScaler.
Entity Type Name IP Address Port Protocol
Vserver Vserver-LB-1 10.102.29.13 53 DNS
286 Installation and Configuration Guide - Volume 1
The following figure shows the LB entities and the values of the parameters that
need to be configured on the NetScaler.
Load balancing DNS servers entity model
The following sections describe the tasks to implement this scenario. The tasks
include the following:
1. Configuring a basic LB setup to load balance DNS servers
2. Monitoring DNS Servers
Configuring a Basic LB Setup Load Balance DNS
Servers
Using the procedure described in the section “Configuring a Basic Setup” on
page 114, create services and vservers of type, DNS. Name the entities, and set
the parameters to the values described in the Name and Value columns of the
table in the previous section.
Services Service-DNS-1 10.102.29.14 53 DNS
Service-DNS-2 10.102.29.15 53 DNS
Service-DNS-3 10.102.29.16 53 DNS
Monitors monitor-DNS-1 None None None
Entity Type Name IP Address Port Protocol
Chapter 4 Load Balancing 287
Monitoring DNS Servers
When you configure a basic LB setup, the default ping monitor is bound to the
services. To bind the DNS monitor to the services, you can also use the procedure
described in the section “Binding Monitors to Services” on page 225. The
following procedure describes the steps to create a monitor monitor-DNS-1 that
maps a domain name to the IP address based on a query.
To configure DNS monitors using the configuration utility
1. In the navigation pane, expand Load Balancing and click Monitors. The
Monitors page appears in the details pane.
2. Click Add. The Create Monitor dialog box appears.
3. In the Name and Interval text boxes, type monitor-DNS-1 and 340.
4. In the Type list, select DNS.
5. In the Query text box, type www.citrix.com and in the Query Type list
box, select ADDRESS.
6. In the text box below the Query Type list box, type 10.102.29.66, and click
Add. The new IP appears in the IP Address box.
7. Click Create and click Close. The monitor-DNS-1 you created appears in
the Monitors page.
To configure DNS monitors using the NetScaler command line
At the NetScaler command prompt, type:
add lb monitor monitor-DNS-1 DNS -query www.citrix.com
-queryType Address -IPAddress 10.102.29.66
Load Balancing with Domain-Name Based
Services
To create a service in a basic LB setup, you must provide an IP address.
Alternatively, you can create a server with a domain name. The server name
(domain name) can be resolved using a name server, or by adding an authoritative
DNS record (A record) on the NetScaler.
When you change the IP address of the server, the name server resolves the
domain name to the new IP address. The monitor 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.
288 Installation and Configuration Guide - Volume 1
Note: When you change the IP address of the server, the corresponding service
is marked down for the first client request. The name server resolves the service
IP address to the changed IP address for the subsequent requests.
The domain-name based services have the following restrictions:
• The maximum domain name length is 255 characters.
• The Maximum Client parameter is used to configure a service that
represents the domain name-based server. For example, a maxClient of
1000 is set for the services bound to a vserver. When the connection count
at the vserver reaches 2000, the DNS resolver changes the IP address of the
services. But because the connection counter on the service is not reset, the
vserver cannot take any new connections until all the old connections are
closed.
• When the IP address of the service changes, persistence is difficult to
maintain.
• If the domain name resolution fails due to a timeout, the NetScaler uses the
old information (IP address).
• When monitoring detects that a service is down, the NetScaler performs a
DNS resolution on the service (representing the domain name-based server)
to obtain a new IP address.
• Statistics are collected on a service, and are not reset when the IP address
changes.
• If a DNS resolution returns a code of “name error” (3), the NetScaler marks
the service down and changes the IP address to zero.
Chapter 4 Load Balancing 289
the NetScaler distributes client requests across the domain name-based services to
balance the load on the servers. When the NetScaler receives a request for a
service, it selects the target service. In this way, the NetScaler balances the load
on the services. The following figure describes the topology of an LB
configuration that load balances a group of domain-name based servers (DBS).
Basic LB topology for DBS servers
The services Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 are bound
to the vserver Vserver-LB-1. The vserver Vserver-LB-1 uses the least
connections method to choose the service. The IP address of the service is
resolved using the name server Vserver-LB-2.
The following table lists the names and values of the basic entities configured on
the NetScaler.
Entity Type Name IP Address Port Protocol
Vserver Vserver-LB-1 10.102.29.17 80 HTTP
Vserver-LB-2 10.102.29.20 53 DNS
Servers server-1 10.102.29.18 80 HTTP
server-2 www.citrix.com 80 HTTP
Services Service-HTTP-1 server-1 80 HTTP
Service-HTTP-2 server-2 80 HTTP
Service-HTTP-2 10.102.29.19 80 HTTP
Monitors Default None None None
290 Installation and Configuration Guide - Volume 1
The following figure shows the LB entities and the values of the parameters that
need to be configured on the NetScaler.
Load balancing DBS servers entity model
The following sections explain the following procedures required to implement
the scenario described above:
1. Configuring a basic LB setup to load balance a domain name-based server
2. Configuring a name server
Configuring a Basic LB Setup
Using the procedure described in the section “Configuring a Basic Setup” on
page 114, create the services and the vservers of type HTTP. Name the entities
and set the parameters under the Name and Value columns in the table in the
previous section.
Adding a Name Server
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.
Name Server None 10.102.29.19 None None
Entity Type Name IP Address Port Protocol
Chapter 4 Load Balancing 291
To add a name server using the configuration utility
1. In the navigation pane, expand DNS and click Name Servers. The Name
Servers page appears in the details pane.
2. Click Add. The Create Name Server dialog box appears.
3. Select the DNS Virtual Server radio button.
4. In the DNS Virtual Server drop-down list, select the name server, for
example, Vserver-LB-2.
Note: Click New if you want to create a new load balancing vserver. The
Create Virtual Server (Load Balancing) dialog box appears.
5. Click Create and click Close.
To add a name server using the NetScaler command line
At the NetScaler command prompt, type:
add dns nameServer Vserver-LB-2
You can also add an authoritative name server that resolves the domain name to
an IP address. For more information about configuring name servers, see the
DNS chapter of the Installation and Configuration Guide.
292 Installation and Configuration Guide - Volume 1
Load Balancing a Group of SIP Servers
This section describes how the NetScaler load balances SIP servers. The
NetScaler balances the load on the SIP servers by distributing client requests
across the SIP servers. Load balancing the SIP servers improves the performance
of Internet telephony. You can also enable RPORT on the NetScaler. For more
information about RPORT, see the “Advanced Network Configuration” chapter
of the Installation and Configuration Guide. The following figure describes the
topology of an LB setup configured to load balance a group of SIP servers.
SIP load balancing
In the sample scenario in this section, the services Service-SIP-1 and
Service-SIP-2 are bound to the vserver Vserver-LB-1. The following table lists
the names and values of the entities that you need to configure on the NetScaler in
inline mode.
Entity Type Name IP Address Port Protocol
Vserver Vserver-LB-1 10.102.29.65 80 SIP
Services Service-SIP-1 10.102.29.10 80 SIP
Service-SIP-2 10.102.29.20 80 SIP
Monitors Default None 80 SIP
Chapter 4 Load Balancing 293
The following figure shows the LB entities and the values of the parameters to be
configured on the NetScaler.
Load balancing SIP servers entity model
The following sections describe the procedures to implement this scenario:
1. Configuring a basic LB setup to load balance SIP servers
2. Configuring RNAT
3. Configuring SIP parameters
Configuring a Basic LB Setup to Load Balance SIP
Servers
Using the procedure described in the section “Configuring a Basic Setup” on
page 114, create services and vservers of type SIP. Name the entities and set the
parameters using the values described in the Name and Value columns of the
table in the previous section.
Configuring RNAT
The following procedure describes the steps to configure RNAT.
To configure RNAT using the configuration utility
1. In the navigation pane expand Network, and expand Routing. Click
Routes. The Routes page appears in the details pane.
2. Click Add. The Create Route dialog box appears.
294 Installation and Configuration Guide - Volume 1
3. In the Network, Netmask, and Gateway IP text boxes type 10.102.29.0,
255.255.255.0, and 10.102.29.50.
4. Click Create and click Close.
To configure RNAT using the NetScaler command line
At the NetScaler command prompt, type:
add route 10.102.29.0 255.255.255.0 10.102.29.50
Configuring SIP Parameters
When you enable RNAT, the NetScaler sends SIP responses to the IP address and
port that the client uses to send the request. The NetScaler also adds the RPORT
tag in the VIA header of the message. The NetScaler compares the values of the
source and destination ports of the request packets with the RNAT source port
and RNAT destination port. If one of the values matches, the NetScaler updates
the VIA header with the RPORT setting. You must enable this setting when
RPORT is not configured on either of the clients. The following procedure
describes the steps to configure SIP parameters.
To configure SIP parameters using the configuration utility
1. In the navigation pane, click Load Balancing. The Load Balancing page
appears in the details pane.
2. Click SIP Parameters. The Set SIP Parameters dialog box appears.
3. In RNAT Source Port text box, type 5060.
4. Select the Enable Add RPort VIP check box.
5. Click OK.
To configure SIP parameters using the NetScaler command line
At the NetScaler command prompt, type:
set sipParameters -rnatSrcPort 5060
Chapter 4 Load Balancing 295
Configuring Load Balancing in Commonly Used
Deployment Scenarios
This section describes the procedures to configure a functional LB setup for some
common deployment scenarios. You can follow the instructions in this section to
implement load balancing in a direct return server setup, one-arm setup, or inline
setup (two-arm). The procedures described in this section include creating the
entities of the LB setup, and configuring the appropriate path for requests and
response flow.
Topics include:
• Configuring Load Balancing in Direct Server Return Mode
• Configuring Load Balancing in Direct Server Return mode using IP
Tunneling
• Configuring Load Balancing in Direct Server Return mode using TOS
• Configuring Load Balancing in One-arm Mode
• Configuring Load Balancing in the Inline Mode
• Load Balancing of Intrusion Detection System Servers
Configuring Load Balancing in Direct Server
Return Mode
Load balancing in DSR mode allows the server to respond to clients directly
using a return path that does not flow through the NetScaler. However, the
NetScaler can continue to perform health checks on the application ports. In a
high-data volume environment, sending the server traffic directly to the client in
DSR mode increases the overall packet handling capacity of the NetScaler,
because the packets do not flow through the NetScaler. DSR mode supports the
following topologies:
• The NetScaler in one-arm mode
• The NetScaler in two-arm mode (also called inline mode)
The following sections describe the topology and configuration of one-arm and
two-arm modes. Note the following:
• The NetScaler ages out sessions based on idle timeout
• Because the NetScaler does not proxy TCP connection (that is it does not
send SYN-ACK to the client), it does not completely shut out syn-attack.
By using the SYN packet rate filter, you can control the rate of SYNs to the
296 Installation and Configuration Guide - Volume 1
server. To control the rate of SYNs, set a threshold for the rate of SYNs. To
get protection from SYN attack, configure the NetScaler to proxy TCP
connection but that would require the reverse traffic to flow through the
NetScaler.
In the example scenario, the services Service-ANY-1, Service-ANY-2, and
Service-ANY-3 are created and bound to the vserver Vserver-LB-1. The vserver
load balances the client request to a service, and the service responds to clients
directly, bypassing the NetScaler. The following table lists the names and values
of the entities configured on the NetScaler in DSR mode.
The following figure shows the LB entities and values of the parameters to be
configured on the NetScaler.
Entity model for load balancing in DSR mode
The following sections describe the tasks required to implement this scenario:
1. Enabling MAC based forwarding mode
Entity Type Name IP Address Protocol
Vserver Vserver-LB-1 10.102.29.94 ANY
Services Service-ANY-1 10.102.29.91 ANY
Service-ANY-2 10.102.29.92 ANY
Service-ANY-3 10.102.29.93 ANY
Monitors TCP None None
Chapter 4 Load Balancing 297
2. Configuring a basic LB setup
3. Customizing the LB setup for DSR mode
Enabling MAC-Based Forwarding
For the NetScaler to function in DSR mode, the destination IP in the client
request is unchanged. The destination MAC is changed to the selected server
MAC address. This setting enables the server to determine the client MAC
address for forwarding requests to the client while bypassing the server. The
following procedure describes the steps to enable MAC-based forwarding.
To enable MAC-based forwarding using the configuration utility
1. In the navigation pane, expand System and click Settings. The Settings
page appears in the details pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Select the MAC Based Forwarding check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
5. Click Yes.
To enable MAC-based forwarding using the NetScaler command line
At the NetScaler command prompt, type:
enable ns mode MAC
Configuring a Basic LB Setup in DSR Mode
Using the procedure described in the section “Configuring a Basic Setup” on
page 114, create the services and the vservers. Name the entities and set the
parameters using the values described in the Name and Value columns of the
table in the previous section.
Customizing the LB setup in DSR Mode
After you configure the LB setup, you must customize the LB setup for DSR
mode. You need to set the redirection mode to allow the server to determine the
client MAC address for forwarding responses and bypass the NetScaler. The
following sections describe the procedures to configure the LB setup for DSR
mode.
298 Installation and Configuration Guide - Volume 1
Configuring the LB Method and Redirection Mode
After you create an LB setup, you must configure the correct LB method, for
example, the SOURCEIP Hash method with a sessionless vserver. The NetScaler
does not maintain the state of the connection. You must also configure MAC-
based redirection as described in the following procedure.
To configure LB method and redirection mode for a sessionless vserver
using the configuration utility
1. In the left navigation pane, expand Load Balancing and click Virtual
Servers. The Load Balancing Virtual Servers page appears in the details
pane.
2. Select the vserver, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
4. Click the Method and Persistence tab. Under LB Method, select
SOURCEIP Hash.
5. Click the Advanced tab. Under Redirection Mode, select the MAC Based
radio button.
6. Select the Sessionless check box and click OK.
To configure LB method and redirection mode for a sessionless vserver
using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -lbMethod SourceIPHash -m MAC
-sessionless enabled
Enabling USIP Mode
To determine the client IP address, you need to enable the USIP mode on the
service. The service uses this address to forward the responses. The following
procedure describes the steps to enable use source IP mode for each service
bound to the vserver.
To set a service to use source IP address using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service, Service-ANY-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Use Source IP check box.
Chapter 4 Load Balancing 299
6. Click OK.
7. Repeat steps 1-5 for the services Service-ANY-2 and Service-ANY-3.
To set a service to use source IP address using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-ANY-1 -usip yes
Note: For USIP to function correctly, you must set it globally. For more
information about configuring USIP globally, see the “Basic Network
Configuration” chapter of the Installation and Configuration Guide.
Configuring LINUX Servers in DSR Mode
This section provides steps to configure the NetScaler in DSR mode.
To configure LINUX server in DSR mode
1. Create a loop back interface with the NetScalers VIP (10.101.4.94) on all
the servers participating in the DSR cluster.
2. At the Linux OS prompt, type the following commands:
i f conf i g dummy0 up
i f conf i g dummy0: 0 i net 10. 101. 4. 94 net mask 255. 255. 255. 255 up
echo 1 > / pr oc/ sys/ net / i pv4/ conf / dummy0/ ar p_i gnor e
echo 2 > / pr oc/ sys/ net / i pv4/ conf / dummy0/ ar p_announce
Configuring Load Balancing in Direct Server
Return mode using IP Tunneling
Load Balancing in DSR mode enables a server to directly respond to the client
using a return path that does not flow through the NetScaler. When an IP packet is
sent from a client to the NetScaler, the destination IP address of the packet is the
NetScaler VIP (Virtual IP address). If the back-end server is on the same network
as the NetScaler, the NetScaler forwards the packets after processing it.
However, if the NetScaler and the back-end servers are not on the same network
and are connected via a router, the NetScaler forwards the packet to the router
after encapsulating it with additional header information for the router.
The encapsulated information enables the router to route the packet to the
appropriate back-end server. If that information was not added, the packet is re-
routed to the NetScaler as the destination IP is the NetScaler VIP, resulting in a
loop.
300 Installation and Configuration Guide - Volume 1
In this scenario, the NetScaler is the encapsulator i.e., it adds the additional outer
header information to the packet and sends it to the router via the tunnels. The
back-end servers’ decapsulate the data packet as illustrated in the diagram.
NS as an Encapsulator
In the example, the services, Service-ANY-1, Service-ANY-2, and Service-ANY-
3 are created and bound to the vserver, Vserver-LB-1. The vserver load balances
the client request to a service, and the service responds to clients directly,
bypassing the NetScaler. The following table lists the names and values of the
entities configured on the NetScaler in DSR mode.
The following sections describe the tasks required to implement this scenario:
Entity Type Name IP Address Protocol
Vserver Vserver-LB-1 206.86.120.50 ANY
Services Service-ANY-1 10.10.10.70 ANY
Service-ANY-2 10.10.10.80 ANY
Service-ANY-3 10.10.10.90 ANY
Monitors PING None None
Chapter 4 Load Balancing 301
1. Configuring a basic LB setup
2. Customizing the LB setup for DSR mode on Layer 3
• Configuring the Re-direction Mode
• Configuring the Monitor for Tunneling
• Customize the IP Tunnel Parameter Globally
Configuring a basic LB Setup for Layer3
Using the procedure described in the section “Configuring a Basic Setup” on
page 158, create the services and the vservers. Name the entities and set the
parameters using the values described in the Name and Value columns of the
table specified.
Customizing the LB Setup for DSR mode on Layer3
After you configure the LB setup, you must customize the LB setup for DSR
mode by configuring the redirection mode, and the monitor. The following
sections describe the procedures to configure the LB setup for DSR mode.
Configuring the Re-direction mode for DSR Layer 3
To customize the LB setup for DSR mode, you must first set the redirection mode
to allow the server to decapsulate the data packet and then respond directly to the
client and bypass the NetScaler.
To configure the redirection mode for the vserver using the configuration
utility
1. In the left navigation pane, expand Load Balancing and click Virtual
Servers.
2. In the Load Balancing Virtual Servers page, select the vserver, Vserver-
LB-1 and click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, click the
Advanced tab. Under Redirection Mode, select the IP Tunnel Based
radio button.
4. Click OK.
To configure the redirection mode for the vserver using the NetScaler
command line
At the NetScaler command prompt, type:
set lb vserver VserverName -m Value
302 Installation and Configuration Guide - Volume 1
Example
set lb vserver Vserver-LB-1 -m IPTunnel
Configuring the Transparent Monitor for Tunneling
After specifying the re-direction mode, you must enable the NetScaler to
transparently monitor the server. This enables the NetScaler to probe packets
having the destination IP set to VIP and tunnel them to the server.
To configure the transparent monitor for tunneling using the configuration
utility
1. In the left navigation pane, expand Load Balancing and click Monitors.
2. In the Monitors page, select the monitor (tcp, for instance), and click Add.
3. In the Create Monitor dialog box, in the Name and Destination IP
textboxes, enter the monitor name and the destination IP address (for
example, PING1 and 206.86.120.50).
4. In the Type list, select the type of monitor (for example, PING).
5. To configure the monitor to be transparent, select the Transparent check
box.
6. To configure the monitor for tunneling, select the IP Tunnel check box.
7. Click OK.
To configure the transparent monitor for tunneling using the NetScaler
command line
At the NetScaler command prompt, type:
add monitor MonitorName Type -destip DestinationIP Address –
IPTunnel Value
Example
add monitor mon1 PING –destip 206.86.120.50 –IPTunnel Yes
Customizing the IP Tunnel globally
After specifying the re-direction mode, and the monitor, you can make some
global changes that impact the behavior of the NetScaler. For more information
on how to customize the IP tunnel globally, see Customizing the IP Tunnel
globally.
Chapter 4 Load Balancing 303
Configuring Load Balancing in Direct Server
Return mode using TOS
Load Balancing in DSR mode enables a server to directly respond to the client
using a return path that does not flow through the NetScaler.
For example, when an IP packet is sent from a client to the NetScaler, the
destination IP address of the packet is the NetScaler VIP (Virtual IP address).
When the back-end server is not on the same network and is connected via a
router, the NetScaler forwards the packet to the router after modifying the header.
The destination IP address of the packet, the NetScaler VIP, is modified to specify
the back-end server IP address. The differentiated services (DS) field of the
packet is set to an encoded value of the VIP.
Differentiated services (DS), previously known as TOS (Type of Service), is a
field that is part of the packet header and is used by upper layer protocols for
optimizing the path for a packet. The DS information is used by the back-end
servers to derive the VIP from the encoded VIP. In this scenario, the NetScaler
adds the additional DS information to the packet and sends it to the back-end
server. The back-end servers' then respond directly to the client bypassing the
NetScaler as illustrated in the diagram.
304 Installation and Configuration Guide - Volume 1
Before you configure TOS
The TOS feature is specifically customized for a controlled environment.
Following are the features of the controlled environment.
• The environment must not have any stateful devices such as stateful
Firewall, TCP gateways in the path between the NetScaler and the back-end
servers.
• Routers at all the entry points of the network must remove the DS field
from all incoming packets to make sure that the server does not confuse
other traffic with a value in the DS field.
• Each server can have only 63 VIPs.
• Care must be taken to make sure that the intermediate router does not send
out an ICMP error message regarding fragmentation. The client will not
understand the message as the source ip address will be the IP address of
the back-end server and not the VIP of the NetScaler.
• TOS is valid only for IP based servers.
In the example, the services, Service-ANY-1 is created and bound to the vserver,
Vserver-LB-1. The vserver load balances the client request to a service, and the
service responds to clients directly, bypassing the NetScaler. The following table
lists the names and values of the entities configured on the NetScaler in DSR
mode.
The following sections describe the tasks required to implement this scenario:
1. Configuring a basic LB setup
2. Customizing the LB setup for DSR mode on Layer 3
• Configuring the Re-direction Mode
• Configuring the Monitor for TOS (Optional)
• Configuring the Back-end Servers for DSR Mode
Entity Type Name IP Address Protocol
Vserver Vserver-LB-1 10.102.33.91 ANY
Services Service-ANY-1 10.102.100.44 ANY
Monitors PING None None
Chapter 4 Load Balancing 305
Configuring a basic LB Setup for Layer3
Using the procedure described in the section “Configuring Basic Load
Balancing” on page 113, create the services and the vservers. Name the entities
and set the parameters using the values described in the Name and Value columns
of the table specified.
Customizing the LB Setup for DSR mode on Layer3
After you configure the LB setup, you must customize the LB setup for DSR
mode by configuring the redirection mode. You can also optionally configure a
monitor to transparently check the health of the application. The following
sections describe the procedures to configure the LB setup for DSR mode.
Configuring the Re-direction mode for DSR Layer 3
To customize the LB setup for DSR mode, you must first set the redirection mode
to allow the server to decapsulate the data packet and then respond directly to the
client and bypass the NetScaler.
To configure the redirection mode for the vserver using the configuration
utility
1. In the left navigation pane, expand Load Balancing and click Virtual
Servers.
2. In the Load Balancing Virtual Servers page, select the vserver, Vserver-
LB-1 and click Open.
3. In the Configure Virtual Server (Load Balancing) dialog box, click the
Advanced tab. Under Redirection Mode, select the TOS radio button.
4. In the TOS Id textbox, enter a value for the TOS ID, (for example, 3).
5. Click OK.
To configure the redirection mode for the vserver using the NetScaler
command line
At the NetScaler command prompt, type:
set lb vserver VserverName -m Value -tosId Value
Example
set lb vserver Vserver-LB-1 -m TOS -tosId 3
Configuring the Transparent Monitor for TOS
After specifying the re-direction mode, you can optionally enable the NetScaler
to transparently monitor the server. This enables the NetScaler to transparently
monitor the application running on VIP (alias IP) on the back-end servers.
306 Installation and Configuration Guide - Volume 1
To configure the transparent monitor for TOS using the configuration utility
1. In the left navigation pane, expand Load Balancing and click Monitors.
2. In the Monitors page, select the monitor (tcp, for instance), and click Add.
3. In the Create Monitor dialog box, in the Name and Destination IP
textboxes, enter the monitor name and the destination IP address (for
example, PING and 10.102.33.91).
4. In the Type list, select the type of monitor (for example, PING).
5. To configure the monitor for TOS, select the TOS check box.
6. In the TOS Id textbox, enter the same TOS Id that you had entered for the
vserver (for example, 3.)
7. Click OK.
To configure the transparent monitor for TOS using the NetScaler command
line
At the NetScaler command prompt, type:
add monitor Moni t or Name Type - destip Dest i nat i onI P Addr ess - tos
Val ue - tosId Val ue
Example
add monitor mon1 PING -destip 10.102.33.91 -tos Yes -tosId 3
Configuring the Back-end Servers for DSR Mode
This section provides steps to configure the back-end servers (Linux, for
example) in DSR mode.
To configure LINUX server in DSR mode
1. Create a loop back interface with the NetScaler VIP (10.102.33.91) on all
the servers participating in the DSR cluster.
At t he Li nux OS pr ompt , t ype t he f ol l owi ng commands:
echo 1 > / pr oc/ sys/ net / i pv4/ conf / et h0/ ar p_i gnor e
echo 2 > / pr oc/ sys/ net / i pv4/ conf / et h0/ ar p_announce
r out e add - host 10. 102. 33. 91 gw 10. 102. 100. 44
2. Run the software that re-maps the TOS id to VIP.
Chapter 4 Load Balancing 307
Note: Add the correct mappings to the software before running it. In the
preceding commands, the LINUX server uses eth0 to connect to the network.
When you use this command, type the name of the interface that your LINUX
server uses to connect to the network.
Configuring Load Balancing in One-armMode
In a one-arm setup, you connect the NetScaler to the network through a single
interface. This is one of the simplest deployment scenarios, where the router, the
servers and the NetScaler are connected to the same switch. The client can access
the server directly, bypassing the NetScaler, if the client knows the IP address of
the server. Client requests at the switch are forwarded to the NetScaler, and the
NetScaler selects the server. This is shown in the following topology diagram.
Load balancing in one-armmode
In the example scenario, the services Service-ANY-1, Service-ANY-2, and
Service-ANY-3 are created and bound to the vserver Vserver-LB-1. The vserver
load balances the client request to a service. The following table lists the names
and values of the entities configured on the NetScaler in one-arm mode.
Entity Type Name IP Address Protocol
Vserver Vserver-LB-1 10.102.29.94 ANY
308 Installation and Configuration Guide - Volume 1
The following figure shows the LB entities and values of the parameters that need
to be configured on the NetScaler.
Entity model for load balancing in one-armmode
To configure an LB setup in one-arm mode, use the procedure described in the
section “Configuring a Basic Setup” on page 114 and create services and
vservers. Name the entities and set the parameters to the values as described in
the Name and Value columns of the table in the previous section.
Services Service-ANY-1 10.102.29.91 ANY
Service-ANY-2 10.102.29.92 ANY
Service-ANY-3 10.102.29.93 ANY
Monitors TCP None None
Entity Type Name IP Address Protocol
Chapter 4 Load Balancing 309
Configuring Load Balancing in the Inline Mode
In a two-arm setup, you deploy the NetScaler to the network through more than
one interface. In the two-arm setup, the NetScaler is connected between the
servers and the client. Traffic from the clients passes through the NetScaler to
access the server. Client requests at the switch are forwarded to the NetScaler, and
the NetScaler selects the server. This is shown in the following topology diagram.
Load Balancing in Inline Mode
The configuration and the entity diagram for inline mode are the same as
described in the section “Configuring Load Balancing in One-arm Mode” on
page 307.
310 Installation and Configuration Guide - Volume 1
Load Balancing of Intrusion Detection System
Servers
The NetScaler supports load balancing of the Intrusion Detection System (IDS)
servers. The servers and clients are connected through a switch that has port
mirroring enabled. The client sends requests to the server. Because port mirroring
is enabled on the switch, these packets are copied or sent to the vserver port. The
NetScaler then selects an IDS server based on the LB method and balances the
load on it as shown in the following topology diagram.
Load balancing IDS servers
Currently, the NetScaler supports load balancing of passive IDS devices only. The
following section describes load balancing of IDS servers (illustrated in the
preceding diagram):
1. The client request is routed to the server. A switch with a mirroring port
enabled forwards these packets to the server. The source IP address is the IP
address of the client, and the destination IP address is the IP address of the
server. The source MAC address is the MAC address of the router and the
destination MAC address is the MAC address of the server.
2. The traffic that flows through the switch is mirrored to the NetScaler. The
NetScaler uses the layer 3 information (source IP address and destination IP
address) to forward the packet for balancing the load on IDS servers. An
IDS server is selected and the packet is sent to the server without changing
the source IP address or destination IP address, but the source MAC address
Chapter 4 Load Balancing 311
and the destination MAC address are changed to the MAC address of the
selected IDS server.
Note: You can configure the SRCIPHASH, DESTIPHASH, or
SRCIPDESTIPHASH load balancing methods. It is recommended to use the
SRCIPDESTIPHASH method because the packets flowing from the client to a
service on the NetScaler must go to a single IDS server.
Suppose, Service-ANY-1, Service-ANY-2, and Service-ANY-3 are created and
bound to Vserver-LB-1. The vserver balances the load on the services. The
following table lists the names and values of the entities configured on the
NetScaler.
Note: You can configure the NetScaler to balance the load on IDS servers in the
inline mode or in the one-arm mode.
Entity Type Name IP Address Port Protocol
Vserver Vserver-LB-1 * * ANY
Services Service-ANY-1 10.102.29.101 * ANY
Service-ANY-2 10.102.29.102 * ANY
Service-ANY-3 10.102.29.103 * ANY
Monitors Ping None None None
312 Installation and Configuration Guide - Volume 1
The following figure shows the LB entities and values of the parameters to be
configured on the NetScaler.
Entity model for load balancing IDS servers
The following sections describe the tasks required to implement this scenario:
1. Enabling MAC based forwarding mode
2. Configuring a basic LB setup
3. Customizing the LB setup for IDS mode
Enabling MAC-Based Forwarding
The following procedure describes the steps to enable MAC-based forwarding.
Note: You must disable the layer 2 and layer 3 modes on the NetScaler for the
IDS load balancing.
To enable MAC-based forwarding using the configuration utility
1. In the navigation pane, expand System and click Settings. The Settings
page appears in the details pane.
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Select the MAC Based Forwarding check box.
4. Click OK. The Enable/Disable Feature(s)? message appears.
Chapter 4 Load Balancing 313
5. Click Yes.
To enable MAC-based forwarding using the NetScaler command line
At the NetScaler command prompt, type:
enable ns mode MAC
Configuring a Basic LB Setup for IDS Configuration
Using the procedure described in the section “Configuring a Basic Setup” on
page 114, create the services and the vservers and bind them. Name the entities
and set the parameters using the values described in the Name and Value columns
of the table in the previous section. To create a vserver with * as its IP address
using the configuration utility, in the Create Virtual Server (Load Balancing)
dialog box, clear the Directly Addressable check box.
Note: To configure the vserver with * as its IP address and port use the
procedure described in the section “Configuring a Basic Setup” on page 114 with
the step described above.
Customizing the LB Setup for IDS Configuration
After you configure the LB setup, you must customize the LB setup for IDS
configuration. The following sections describe the procedures to configure the
LB setup for IDS configuration.
Configuring the LB Method and Redirection Mode
After you create an LB setup, you must configure the correct LB method (for
example, the SRCIPDESTIP Hash method on a sessionless vserver) and enable
MAC mode. The NetScaler does not maintain the state of the connection and only
forwards the packets to the IDS servers without processing them. The destination
IP address and port remains unchanged because the vserver is in the MAC mode.
To configure LB method and redirection mode for a sessionless vserver
using the configuration utility
1. In the left navigation pane, expand Load Balancing and click Virtual
Servers. The Load Balancing Virtual Servers page appears in the details
pane.
2. Select the vserver, Vserver-LB-1.
3. Click Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
314 Installation and Configuration Guide - Volume 1
4. Click the Method and Persistence tab. Under LB Method, select
SRCIPDESTIP Hash.
5. Click the Advanced tab. Under Redirection Mode, select the MAC Based
radio button.
6. Select the Sessionless check box and click OK.
To configure LB method and redirection mode for a sessionless vserver
using the NetScaler command line
At the NetScaler command prompt, type:
set lb vserver Vserver-LB-1 -lbMethod SourceIPDestIPHash -m MAC
-sessionless enabled
Enabling USIP Mode
The client IP address is needed to process the requests on the IDS servers and,
therefore, you must enable the USIP mode on the service. The server uses the
client IP address and not MIP or SNIP to forward these requests to the selected
service. The following procedure describes the steps to enable use source IP
mode for each service bound to the vserver.
To set a service to use source IP address using the configuration utility
1. In the navigation pane, expand Load Balancing and click Services. The
Services page appears in the details pane.
2. Select the service, Service-ANY-1.
3. Click Open. The Configure Service dialog box appears.
4. Click the Advanced tab.
5. Under Settings, select the Use Source IP check box.
6. Click OK.
7. Repeat steps 1-5 for the services Service-ANY-2 and Service-ANY-3.
To set a service to use source IP address using the NetScaler command line
At the NetScaler command prompt, type:
set service Service-ANY-1 -usip yes
Note: For USIP to function correctly, you must set it globally. For more
information about configuring USIP globally, see the “Basic Network
Configuration” chapter of the Installation and Configuration Guide.
Chapter 4 Load Balancing 315
Troubleshooting Common Problems
• When a metric bound to the monitor is present in the local and custom
metric tables, add the local prefix to the metric name if the metric is chosen
from the local metric table. If the metric is chosen from the custom table, no
prefix needs to be added.
• If the metric table is modified (for example, if the OID for the metric is
changed), the change is reflected in the monitoring table. SNMP queries
originating from the monitor then use the new OID.
• Load monitors cannot decide the state of the service. Therefore, setting a
weight on the load monitors is inappropriate.
• If multiple load monitors are bound to a service, then the load on the service
is the sum of all the values on the load monitors bound to it. For load
balancing to work properly, you must bind the same set of monitors to all
the services.
• When you bind a service to a vserver where the LB method is
CUSTOMLOAD, and if the service is up, then the vserver is put to initial
round robin (RR). It continues to be in RR if the service has no custom load
monitors, or if at least one of the custom load monitors is not up.
• If you disable a load monitor bound to the service, and if the service is
bound to a vserver, then the vserver goes to RR.
• If you disable a metric-based binding, and if this is the last active metric,
then the specific vserver goes to RR. A metric is disabled by setting the
metric threshold to zero.
• When a metric bound to a monitor crosses the threshold value, then that
particular service is not considered for load balancing.If all the services
have reached the threshold, then the vserver goes into RR and an error
message “5xx - server busy error” is received.
• All the services that are bound to a vserver where the LB method is
CUSTOMLOAD must have load monitors bound to them.
• The OIDs must be scalar variables.
• For successful load balancing, the interval must be as low as possible.
If the interval is high, the time period for retrieving the load value
increases. As a result, load balancing takes place using improper
values.
• The CUSTOMLOAD load balancing method also follows startup
RR.
316 Installation and Configuration Guide - Volume 1
• A user cannot modify the local table.
• A maximum of 10 metrics from a custom table can be bound to the
monitor.
CHAPTER 5
Content Switching
This chapter describes the content switching (CS) feature of a Citrix NetScaler.
Content switching allows a NetScaler to distribute the client requests across
multiple servers based on the content that the client is accessing. This chapter
describes the basic and advanced settings that you can configure on a NetScaler.
In This Chapter
• How Content Switching Works
• Configuring Basic Content Switching
• Customizing a Content Switching Setup
• Protecting the NetScaler against Failure
• Managing Client Connections
How Content Switching Works
When you configure content switching, you specify which types of requests are to
be directed to which virtual servers. For example, you can configure a NetScaler
to direct requests for dynamic content, such as URLs with a suffix of .asp, .dll, or
.exe, to one server and direct requests for static content to another server. You can
also configure the NetScaler to perform content switching based on TCP/IP
headers and payload.
In addition, the NetScaler directs requests based on various client attributes.
Some of the client attributes that the NetScaler uses to determine the destination
Web server include:
• Device Type. The NetScaler examines the User-Agent or custom HTTP
header in the client request for the type of device from which the request is
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 PC is directed to a different
server that is capable of serving content that a PC user can view.
318 Installation and Configuration guide
• Language. The NetScaler examines the Accept-Language HTTP header in
the client request and determines the language used by the client’s browser.
The NetScaler then sends the request to a server that serves content in that
language. For example, using content switching based on language; the
NetScaler can send someone who wants to read a French version of a
newspaper to a server with the French version of the newspaper. It can send
someone else who wants to read the English version of the same newspaper
to a server with the English version of the newspaper.
• Cookie. The NetScaler examines a cookie and directs the request to a
server with customized content. For example, if the cookie indicates that
the client is a gold club member, the request is directed to a faster server or
one with special content for gold club members. If the cookie indicates that
the user is not a gold club member, the request is directed to a slower server
or one with different content for the general public.
• HTTP Method. The NetScaler examines the HTTP header for the method
used and sends the client request to the appropriate 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.
A typical content switching deployment consists of the entities described in the
following figure.
Content Switching Architecture
A typical content switching configuration consists of a content switching virtual
server (vserver), a load balancing (LB) setup with load balancing vservers 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 vservers. This process creates a content group, which is a group of
all vservers and policies involved in a particular content switching configuration.
Content switching is only applicable to HTTP, HTTPS, and TCP transactions. For
HTTPS transactions, you must enable SSL Offload.
Chapter 5 Content Switching 319
When a request reaches the content switching vserver, it applies the associated
content switching policies to that request. The content switching vserver routes
the request to the load balancing vserver. The load balancing vserver sends it to
the service. When binding a policy to the content switching vserver, you assign a
priority to it. The priority of the policy defines the order in which the policy is
evaluated.
Content switching vservers can only send requests to other vservers. If you are
using an external load balancer, you must create a load balancing vserver for it
and bind its vserver as a service to the content switching vserver.
Configuring Basic Content Switching
This section describes how to configure a basic but functional content switching
setup and how to modify it. The tasks described here serve as a basis for all future
configuration tasks that you might perform. This section also covers the
procedures to modify the setup, including deleting, enabling, and disabling
entities.
Topics include:
• Configuring Basic Content Switching Setup
• Modifying the Existing Content Switching Configuration
Configuring Basic Content Switching Setup
This section describes the topology of a basic content switching setup. It also
describes how to create the content switching vservers and bind policies to them
using the basic topology. A basic content switching setup uses only the
mandatory parameters and serves as the first step in configuring the content
switching feature on a NetScaler. The basic content switching setup provides a
simple and functional content switching configuration as described in the
following sections.
320 Installation and Configuration guide
Understanding the Topology
In a content switching setup, the NetScalers are logically located between the
client and the server farm. Policies are used to manage traffic flow to the servers
in the server farm. The following diagram shows the topology of a basic content
switching configuration.
Basic content switching topology
The content switching requires load balancing and knowledge of how to
configure a load balancing setup. For information about load balancing, see the
“Load Balancing” chapter. In this example scenario, a content switching vserver
Vserver-CS-1 is created and it uses the load balancing vserver Vserver-LB-1 to
balance the load on the services bound to Vserver-LB-1. The following table lists
the names and values of the basic entities that must be configured on the
NetScaler.
Entity Type Mandatory Parameters and Sample Values
Name IP Address Port Protocol
Vserver Vserver-CS-1 10.102.29.161 80 HTTP
Vserver-LB-1 10.102.29.60 80 HTTP
Services Service-HTTP-1 10.102.29.5 8083 HTTP
Service-HTTP-2 10.102.29.6 80 HTTP
Monitors Default None None None
Chapter 5 Content Switching 321
The following figure shows the content switching sample values and mandatory
parameters that are described in the preceding table.
Content switching entity model
Enabling Content Switching
You can configure content switching entities when the content switching feature
is disabled. However, you must enable content switching for the entities to work.
To enable content switching using the configuration utility
1. In the navigation pane, expand System and click Settings. The Settings
page appears in the details pane.
2. Under the Modes & Features group, click basic features. The Configure
Basic Features dialog box appears.
3. Select the Content Switching check box.
4. Click OK, and the Enable/Disable Features(?) dialog box appears.
5. Click Yes.
To enable content switching using the NetScaler command line
At the NetScaler command prompt, type:
enable feature cs
322 Installation and Configuration guide
Creating Content Switching Vservers
You can add, modify, and remove vservers. When you create a content switching
vserver, it is UP by default. To create a content switching vserver, use the
parameters as described in the following table.
To add a content switching vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Click Add. The Create Virtual Server (Content Switching) dialog box
appears.
3. In the Name, IP Address, and Port text boxes, type the name, IP address,
and port of the vserver, for example, Vserver-CS-1, 10.102.29.161, and 80.
Parameter Description
Name The name of the content switching vserver. The vserver name must not
exceed 31 characters and must not contain spaces. This setting cannot
be changed.
IP address The IP address of the vserver. This IP address (VIP) is usually a public
IP address and the clients send connection requests to this IP address.
Service type This parameter determines the behavior of the service. Choose one of
the following service types:
• HTTP - for HTTP services
• TCP - for non-RFC implementation or HTTP services
• FTP - for FTP services. This setting ensures that the
NetScaler takes care of the specifics of the FTP
protocol.
• SSL - for HTTPS services. Select this type to encrypt
the traffic between the NetScaler and the server.
Port The port on which the vserver listens for client connections. The port
number must be between 0-65535.
Chapter 5 Content Switching 323
4. In the Protocol list, select the type of the vserver, for example, HTTP.
5. Click Create and click Close. The vserver you created appears in the
Content Switching Virtual Servers page, as shown in the following
figure.
Content switching virtual servers page
To create a vserver using the NetScaler command line
At the NetScaler command prompt, type:
add cs vserver Vserver-CS-1 HTTP 10.102.29.161 80
Configuring a Load Balancing Setup
The content switching vserver diverts the traffic to the load balancing vserver.
The load balancing vserver then balances the load across the servers. To
configure a basic load balancing setup, you need to perform the following tasks:
• Create load balancing vservers
• Create services
• Bind services to the load balancing vserver
To learn how to configure a load balancing setup, see the “Load Balancing”
chapter. You need to have a basic load balancing setup for your content switching
setup to work.
Creating Content Switching Policies
A content switching policy defines a criterion that specifies which content
switching vserver receives a client request and is directed to a load balancing
vserver. These policies are applied in the sequence of the priorities assigned to
them. Policies are created using expressions and rules.
324 Installation and Configuration guide
The policies can be:
• URL-based policies. The NetScaler selects the content group based on
matching the incoming URL with the configured URLs. The NetScaler
returns the most appropriate URL-based (usually the longest matching
configured URL) content group among the configured URLs.
• Rule-based policies. The NetScaler selects the content group with the first
matching rule in the configured order. For multiple matching rules, no
specific precedence is set and is based on the order in which the rules are
configured. You can create rule-based policies by using policy expressions.
For more information about policy expressions, see the Advanced Policy
Guide.
To create a policy, use the parameters as described in the following table.
The following procedure describes steps to create a policy named Policy-CS-1
that is evaluated when the NetScaler receives an HTTP request that contains
“sports” in the URL and the domain name matches www. xyz.com.
To create a content switching policy using the configuration utility
1. In the navigation pane, expand Content Switching and click Policies. The
Content Switching Policies page appears in the details pane.
2. Click Add. The Create Content Switching Policy dialog box appears.
3. In the Name text box, type the name of the policy, for example,
Policy-CS-1.
Parameter Description
Policy Name The name of the new content switching policy. The name of the
policy must not be longer than 31 characters.
URL The URL, with wildcards. Specify the string value in this format:
// [[prefix ] [*]] [.suffix]
Domain The domain name. Specifies that the NetScaler selects a content
group based on domain name matches. The string value can
range to 63 characters.
Chapter 5 Content Switching 325
4. Select URL. In the Value text box, type the string value, for example,
/sports.
5. In the Domain text box, type the string value, for example,
www.xyz.com.
6. Click Create and click Close. The policy you created appears in the
Content Switching Policies page as shown in the following figure.
Content switching policies page
To create a content switching policy using the NetScaler command line
At the NetScaler command prompt, type:
add cs policy Policy-CS-1 -url /sports/* -domain www.xyz.com
Binding Policies to the Content Switching Vserver
The NetScaler evaluates the policies to direct the traffic to the servers. After you
have created the content switching vserver and policy, you can bind the policy to
the content switching vserver so that the vserver evaluates the policy and routes
the traffic to the load balancing vserver. You can create rule-based policies by
using advanced policy expressions. For more information about advanced policy
expressions, see the Advanced Policy Guide. After a policy that uses an advanced
expression is bound to a CS vserver, you cannot bind policies using classic policy
expressions to that vserver. Priorities are compulsory for advanced policies.
Duplicate priorities are not supported.
326 Installation and Configuration guide
You can also configure policies using GoTo expressions. These expressions
always resolve to a number. This number corresponds to the priority of another
policy. As a result, when a GoTo expression is evaluated a different policy is
invoked. Policies with GoTo expressions do not have LB vservers bound to them.
The GoTo expression will fail if the resulting priority is not assigned to a policy,
the GoTo expression does not evaluate to a number, or the GoTo expression
evaluates to a number lower than its own priority. GoTo expressions can only be
configured for advanced expressions. They cannot be used with classic
expressions. When a GoTo expression fails, the default target vserver is selected.
To bind a policy, use the parameters as described in the following table.
The following procedure describes the steps to bind a content switching policy to
the content switching vserver.
To bind a policy to a content switching vserver using the configuration
utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver to which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears. The policies appear in the Policies tab.
4. Select the Active check box next to the policy that you want to bind to the
vserver, for example, Policy-CS-1.
5. Click the Target box next to the policy and select the load balancing
vserver that you want configure for the content switching vserver, for
example, Vserver-LB-1.
6. Click OK.
Parameter Description
Priority Priority with which the policy is to be bound. The minimum
value is 1 and the maximum value is 2147483647.
gotoPriorityExpression Expression specifying the priority of the next policy which is
evaluated after the current policy rule evaluates to TRUE. If
you don’t specify the gotoPriorityExpression or if it is the last
expression then the policy bank evaluation ends. If the
gotoPriorityExpression is next expression, the next policy in
the priority order is evaluated. If the gotoPriorityExpression
evaluates to the priority of the current policy then the next
policy in the priority order is evaluated. If the
gotoPriorityExpression evaluates to the priority of a policy in
the list then that policy will be evaluated next. The maximum
length is 1500.
Chapter 5 Content Switching 327
To bind a policy to a content switching vserver using the NetScaler
command line
At the NetScaler command prompt, type:
bind cs vserver Vserver-CS-1 Vserver-LB-1 -policyname Policy-CS-1
Verifying the Configuration
To verify the configuration, you need to view the properties of the content
switching vservers and content switching policies and the statistics of the entities
in the configuration.
Viewing the Properties of Content Switching Vservers
You can view properties such as the name, state, IP address, and port of the
configured content switching vservers. The details of the vserver can be used to
troubleshoot any error in the configuration. The following procedure describes
the steps to view the properties of a content switching vserver named
vserver-CS-1.
To view the properties of content switching vservers using the
configuration utility
In the navigation pane, expand Content Switching and click Virtual Servers.
The Content Switching Virtual Servers page appears in the details pane. The
details of the available vservers appear on this page.
To view the properties of content switching vservers using the NetScaler
command line
At the NetScaler command prompt, type:
show cs vserver
Note: To view the properties of a content switching vserver use the command
show cs vserver Vserver-CS-1
328 Installation and Configuration guide
Viewing Load Balancing Configuration
You can view the properties and the statistics of the entities in the load balancing
configuration. To learn how to view the entities and the statistics of a load
balancing setup, see the “Load Balancing” chapter.
Viewing Content Switching Policies
You can view properties such as the name, URL, expression, and domain of the
configured content switching policies. The details of the policies can be used to
troubleshoot any error in the configuration. The following procedure describes
the steps to view the properties of a content switching policy named Policy-CS-1.
To view the properties of content switching policies using the configuration
utility
In the navigation pane, expand Content Switching and click Policies. The
Content Switching Policies page appears in the details pane. The details of the
available policies appear on this page.
To view the properties of content switching policies using the NetScaler
command line
At the NetScaler command prompt, type:
show cs policy
Note: To view the properties of a content switching policy use the command
show cs policy Policy-CS-1
Modifying the Existing Content Switching
Configuration
Most environments that use content switching are more complex than the basic
setup and require more specialized configuration and sophisticated policies that
use more complex expressions. This section describes how to modify the basic
content switching setup you configured previously. This section also describes
the impact of modifying an entity in the basic content switching setup. You can
perform tasks such as enabling, disabling, and removing entities in the basic
content switching setup, using the procedures described in this section.
Chapter 5 Content Switching 329
Managing Content Switching Vserver
This section describes how to manage the content switching vservers after you
create them. Managing the content switching vservers involves modifying the
entities in a basic content switching setup. You can perform tasks such as
enabling, disabling, and removing content switching vservers after you create
them. You can also unbind a content switching policy from a content switching
vserver. Each task that you perform has an impact on the basic content switching
setup, as described in the following sections.
Unbinding a Content Switching Policy fromthe Content
Switching Vserver
When you unbind a policy from a content switching vserver, the NetScaler does
not evaluate the policy to direct the traffic to the servers. The following procedure
describes the steps to unbind a policy Policy-CS-1 from the content switching
vserver Vserver-CS-1.
To unbind a policy from a content switching vserver using the configuration
utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver from which you want to unbind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears. The policies appear in the Policies tab.
4. Clear the Active check box next to the policy that you want to unbind from
the vserver, for example, Policy-CS-1.
5. Click OK.
To unbind a policy from a content switching vserver using the NetScaler
command line
At the NetScaler command prompt, type:
unbind cs vserver Vserver-CS-1 -policyname Pocily-CS-1
330 Installation and Configuration guide
Removing Content Switching Vservers
You need to remove a content switching vserver only when you no longer require
the vserver. When you remove a content switching vserver, the NetScaler unbinds
all policies from the content switching vserver, and then removes the content
switching vserver. If you remove all the content switching vservers from the
NetScaler, the NetScaler does not perform content switching. The following
example describes the steps to delete the content switching vserver Vserver-CS-1.
To remove a content switching vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver that you want to remove, for example, Vserver-CS-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a content switching vserver using the NetScaler command line
At the NetScaler command prompt, type:
rm cs vserver Vserver-CS-1
Enabling and Disabling Content Switching Vservers
You can disable a content switching vserver for maintenance. If you disable the
content switching vserver, the state of the content switching vserver changes to
Out of Service. In this state, the content switching vserver does not respond to
the clients with 200 OK.
To disable a vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver that you want to disable, for example, Vserver-CS-1.
3. Click Disable. The Disable pop-up window appears.
4. Click Yes.
To disable a vserver using the NetScaler command line
At the NetScaler command prompt, type:
disable cs vserver Vserver-CS-1
Chapter 5 Content Switching 331
By default, the vservers are enabled.
To enable a vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver that you want to enable, for example, Vserver-CS-1.
3. Click Enable. The Enable pop-up window appears.
4. Click Yes.
To enable a vserver using the NetScaler command line
At the NetScaler command prompt, type:
enable cs vserver Vserver-CS-1
Managing Load Balancing Configuration
After you set up a basic load balancing configuration, you can manage the entities
you created in the basic load balancing setup. You can enable, disable, or remove
the entities. Each task that you perform has an impact on the services that use the
server, as described in the following sections. To learn how to manage the entities
of a load balancing setup, see the “Load Balancing” chapter.
Managing Content Switching Policy
This section describes how to manage the content switching policies after you
create them. You can perform tasks such as modifying and removing content
switching policies after you create them. You can also unbind a content switching
policy from a content switching vserver. Each task that you perform has an
impact on the basic content switching setup, as described in the following
sections.
Modifying Content Switching Policies
You can modify an existing policy or create new policies and bind them to the
vserver. You can configure rules or change the URL of the policy. To modify a
policy, use the parameters as described in the following table.
Parameter Description
URL The URL, with wildcards. Specify the string value in the
following format: // [[prefix ] [*]] [.suffix]
332 Installation and Configuration guide
You can create different policies based on the URL. URL-based policies can be of
different types as described in the following table.
Rule The condition for applying this policy. Expression names
separated by the logical operators || and &&. Expression names
may be grouped using parentheses. If the expression contains
blanks (e.g., between an expression name and a logical operator),
then the entire argument must be enclosed in double quotes.
Domain The domain name. The string value can range to 63 characters.
Type of URL-based
policy
Description
Domain and Exact URL Specifies that the NetScaler selects a content group if the
domain name and URL match. The incoming requests must
match the configured domain name and configured URL (an
exact prefix matches if only the prefix is configured or an
exact match of the prefix and suffix if both the prefix and
suffix are configured).
Example:
add cs policy Policy-CS-1 -url /sports/
tennis/index.html -domain "www.domainxyz.com"
Domain and Wild Card
URL
Specifies that the NetScaler selects a content group based on a
match of the exact domain name and a partial prefix of the
URL.
Example:
add cs policy Policy-CS-1 -url /*.jsp
-domain "www.domainxyz.com"
Domain Only Specifies that the NetScaler selects a content group based on
domain name matches. The incoming requests must match the
configured domain name.
Example:
add cs policy Policy-CS-1 -domain
"www.domainxyz.com"
Exact URL Specifies that the NetScaler selects a content group based on
whether the incoming URL matches the configured URL
policy rule. If only a URL prefix rule is configured, then an
exact prefix match should occur with the incoming URL. If a
URL prefix and suffix-based rule is configured, an exact prefix
and suffix match should occur with the incoming URL. Below
are two examples of exact URL-based policies.
Example:
add cs policy Policy-CS-1 -url
/sports/tennis/index.html
Parameter Description
Chapter 5 Content Switching 333
To modify a content switching policy using the configuration utility
1. In the navigation pane, expand Content Switching and click Policies. The
Content Switching Policies page appears in the details pane.
2. Select the policy that you want to modify, for example, Policy-CS-1.
3. Click Open. The Configure Content Switching Policies dialog box
appears.
4. In the Domain text box, type the domain name for example,
www.domainxyz.com.
5. Click OK.
To modify a content switching policy using the configuration utility
At the NetScaler command prompt, type:
set cs policy Policy-CS-1 -domain “www.domainxyz.com”
Prefix Only (Wild Card
URL)
Specifies that the NetScaler selects the content group based on
a match of the partial prefix of the URL. All the incoming
URLs must start with the configured prefix.
Example:
add cs policy Policy-CS-1 -url /sports*
sports/*” matches all URLs under /sports “/sports*” matches
all URLs whose prefix match “/sports” starting from the
beginning of a URL
Suffix Only (Wild Card
URL)
Specifies that the NetScaler selects a content group if all
incoming URLs match the configured URL suffix.
Example:
add cs policy Policy-CS-1 -url /*.jsp
“/*.jsp” matches all URLs whose file extension is “jsp”
Prefix and Suffix (Wild
Card URL)
Specifies that the NetScaler selects a content group based on a
partial URL match. All incoming URLs start with the
configured prefix, which must match the configured suffix.
Example:
add cs policy Policy-CS-1 -url
/sports/*.jsp
“/sports/*.jsp” matches all URLs under “/sports/” that also
have the file extension of “jsp”
Type of URL-based
policy
Description
334 Installation and Configuration guide
Note: You can configure content switching using classic policy expressions or
using advanced policy expressions. The rule-based policies use the policy
expressions. For more information about configuring policy expressions, see the
Advanced Policy Guide.
Removing Content Switching Policies
You need to remove a content switching policy when you no longer require the
policy. When you remove a bound content switching policy, the NetScaler
unbinds the policy from the content switching vserver, and then removes the
content switching policy. The following example describes the steps to delete the
content switching policy Policy-CS-1.
To remove a content switching policy using the configuration utility
1. In the navigation pane, expand Content Switching and click Policies. The
Content Switching Policies page appears in the details pane.
2. Select the policy that you want to remove, for example, Policy-CS-1.
3. Click Remove. The Remove pop-up window appears.
4. Click Yes.
To remove a content switching policy using the NetScaler command line
At the NetScaler command prompt, type:
rm cs policy Policy-CS-1
Customizing a Content Switching Setup
This section describes how to customize a basic content switching setup to meet
your requirements. You can perform the optional tasks such as setting case
sensitivity in policy evaluation and setting the precedence of policy evaluation.
Customizing a basic content switching setup is described in the following
sections.
Topics include:
• Setting Case Sensitivity in Policy Evaluation
• Setting the Precedence of Evaluation of Policy
• Setting Dependency of CS Vserver State on the State of Target LB Vservers
Chapter 5 Content Switching 335
Setting Case Sensitivity in Policy Evaluation
You can configure the content switching vserver to send traffic to different target
severs based on the case of the URL. When character case sensitivity setting is
configured, the NetScaler evaluates the policy to match the incoming requests
including the character capitalization. If this setting is not configured, the
NetScaler ignores the case of the URL and evaluates the policy to match the
incoming requests. To set case sensitivity, use the parameter described in the
following table.
To configure case sensitivity using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. Select Case Sensitivity check box.
6. Click OK.
To configure a content switching vserver to redirect the client request to a
URL using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -caseSensitive ON
Parameter Description
Case Sensitive The URL lookup case option on the content switching vserver. If
the case sensitivity of a content switching virtual server is set to
'ON', the URLs /a/1.html and /A/1.HTML are treated differently,
and can be switched to different targets with appropriate content
switching policies. If the case sensitivity is set to 'OFF', the
URLs /a/1.html and /A/ 1.HTML are treated the same, and are
switched to the same target. The possible values are ON and
OFF. The default value: ON
336 Installation and Configuration guide
Setting the Precedence of Evaluation of Policy
This section describes how precedence works with URL-based and rule-based
policies and explains how to configure precedence.
Precedence with URL-based policies
Set URL-based precedence if the content type is same for all clients. However, if
different types of content must be provided based on client attributes you must
use rule-based precedence. If there are multiple matching URLs for the incoming
request, the precedence (priority) for URL-based policies is as follows:
1. Domain and exact URL
2. Domain, prefix, and suffix
3. Domain and suffix
4. Domain and prefix
5. Domain only
6. Exact URL
7. Prefix and suffix
8. Suffix only
9. Prefix only
10. Default
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 vserver, 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.
Chapter 5 Content Switching 337
Precedence with rule-based policies
If you configure precedence based on rules, which is the default setting, the
request is tested based on the rule-based policies you have configured. If the
request does not match any rule-based policies, or if the content group selected
for the incoming request is down, then the request is processed in the following
manner:
• If a default group is configured for the content switching vserver, 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 can set rule-based precedence on any of the several client attributes.
For example, if you set rule-based precedence on the browser type attribute
different content is provided to the client.
You can configure both URL-based policies and rule-based policies for the same
content switching vserver. To set precedence, use the parameter described in the
following table.
To set precedence using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
Parameter Description
Precedence This sets the precedence between RULE-based and URL-based
policies on the content switching virtual server. The default
precedence is RULE. With the precedence set to RULE,
incoming requests are evaluated against the content switching
policies created with the -rule argument (using the add cs policy
CLI command). If none of the rules match, the URL in the
request is evaluated against the content switching policies
created with the -url argument (using the add cs policy CLI
command). The possible values are RULE and URL. The default
value is RULE
338 Installation and Configuration guide
5. Under Precedence, select URL.
6. Click OK.
To set precedence using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -Precedence URL
Setting Dependency of CS Vserver State on the
State of Target LB Vservers
You can set the state of a CS vserver to be dependent on the state of target LB
vservers that are bound to the CS vserver. If this dependency is enabled, and a
default LB vserver is bound to the CS vserver, the CS vserver’s state is dependent
only on the state of the default LB vserver. If the dependency is enabled and no
default LB vserver is bound to the CS vserver, the CS vserver’s state is dependent
on the state of the target LB vservers bound to the CS vserver: In this case, the CS
vserver is up only when all target LB vservers are up, and the CS vserver is down
if any target LB vserver is down.
If this setting is not specified, the NetScaler ignores the state of target LB
vservers when displaying the state of the CS vserver. To configure state
dependency, use the parameter described in the following table.
To set the state dependency of a CS vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to create a state dependency, for
example, Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. Select the State Update check box.
Parameter Description
State Update The option to set CS vserver state dependency on the state of
target LB vservers.If the state dependency of a CS vserver is set
to ‘ENABLED,’ then the NetScaler indicates that the CS vserver
is up only when a target LB vserver is also up. If the state
dependency of a CSvserver is set to ‘DISABLED,’ then the
NetScaler ignores the state of target LB vservers when
displaying the state of the CS vserver. The possible values are
ENABLED and DISABLED. The default value: DISABLED.
Chapter 5 Content Switching 339
6. Click OK.
To configure the state dependency of a CS vserver using the NetScaler
command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -stateupdate ENABLED
Protecting the NetScaler against Failure
The content switching setup can fail when a content switching vserver fails, or
when the content switching vserver is unable to handle excessive traffic.
Protecting the content switching setup against failure helps ensure the availability
of the setup.
Topics include:
• Configuring Backup Vserver
• Diverting Excess Traffic to a Backup Vserver
• Configuring a URL for Redirection
Configuring Backup Vserver
If the primary content switching vserver is marked down or disabled, the
NetScaler directs the connections or client requests to a backup vserver that
forwards the client traffic to the load balancing vserver. It can also send a
notification message to the client regarding the site outage or maintenance. You
can also configure a backup load balancing vserver that handles the client traffic
when the content switching vserver is down. The backup vserver is a proxy and is
transparent to the client.
Note: If a content switching vserver is configured with both a backup vserver
and a redirect URL, the backup vserver takes precedence over the redirect URL.
A redirect is used when the primary and backup vservers are down.
You can configure a backup vserver when you create a content switching vserver,
or when you change the optional parameters of an existing content switching
vserver. You can also configure a backup vserver for an existing backup vserver,
thus creating a cascade of backup vservers. The maximum depth of cascading
backup vservers is 10. The NetScaler searches for a backup vserver that is in the
UP state and accesses that content switching vserver to deliver the content.
340 Installation and Configuration guide
Note: If the backup vserver does not exist, an error message appears.
You can use a redirect URL on the primary vserver when the primary and the
backup vservers are down or have reached their threshold for handling requests.
The following table describes the parameter required to configure a backup
vserver.
The following example describes the steps to set the existing Vserver-CS-2 as a
backup to Vserver-CS-1. The vserver Vserver-CS-2 is created with IP address
10.102.29.163 and protocol HTTP.
To set a backup vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. In the Backup Virtual Server list, select the backup vserver, for example,
Vserver-CS-2.
6. Click OK.
To set a backup vserver using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -backupVserver Vserver-CS-2
Parameter Description
Name The name of the backup vserver. You can create a vserver
and specify the name, IP address, port, and type as
described in “Creating Content Switching Vservers” on
page 322. You can use the name of the content switching
vserver as a backup vserver.
Chapter 5 Content Switching 341
Diverting Excess Traffic to a Backup Vserver
The spillover option diverts new connections arriving at a content switching
vserver to a backup content switching vserver when the number of connections to
the content switching vserver exceeds the configured threshold value. The
threshold value is dynamically calculated, or you can set the value. The number
of established connections (in case of TCP) at the vserver is compared with the
threshold value. When the number of connections reaches the threshold, new
connections are diverted to the backup content switching vserver.
If the backup content switching vservers reach the configured threshold and are
unable to take the load, the primary content switching vserver diverts all requests
to the redirect URL. If a redirect URL is not configured on the primary content
switching vserver, subsequent requests are dropped. For more information about
redirect URL, see the section “Configuring a URL for Redirection” on page 342.
To configure spillover, use the parameters described in the following table.
The following example describes the steps to configure the content switching
vserver Vserver-CS-1 to divert new connections to the backup content switching
vserver vserver-CS-2 when the number of connections exceeds the threshold
value 1000.
Parameter Description
Method Type of spillover used to divert traffic to the backup
content switching vserver when the vserver reaches the
spillover threshold. The valid options for this parameter
are: CONNECTION, BANDWIDTH, and NONE. For
more information about how each of these methods work,
see the “Load Balancing” chapter.
Threshold For the CONNECTION spillover type, the Threshold value
is the maximum number of connections a vserver can
handle prior to spillover. For the BANDWIDTH spillover
type, the Threshold value is the amount of incoming and
outgoing traffic (in kilobits per second) that a vserver can
handle before spillover occurs. The minimum value is 1,
and the maximum value is 4294967294.
Persistence The spillover persistence state. If you enable spillover
persistence, the NetScaler maintains source IP-based
persistence over primary vserver and backup content
switching vservers. The valid options for this parameter
are: enabled and disabled. The default value is disabled.
Persistence Timeout
(minutes)
This value sets the timeout for spillover persistence. The
default value is 2 minutes. The minimum value is 2
minutes, and the maximum value is 1440 minutes.
342 Installation and Configuration guide
To set a content switching vserver to divert new connections to a backup
vserver using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. In the Method list, select the type of spillover, and in Threshold text box
type the threshold value, for example, Connection and 1000.
6. Under Spillover, select the Persistence check box, and in Persistence
Timeout (min) text box, type the timeout, for example, 2.
7. Click OK.
To set a content switching vserver to divert new connections to a backup
vserver using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -soMethod Connection -soThreshold 1000
-soPersistence enabled -soPersistenceTimeout 2
Configuring a URL for Redirection
You can configure a redirect URL to communicate the status of the NetScaler in
the event that a content switching vserver (only of type HTTP or HTTPS) is down
or disabled. This URL can be a local or remote link. The NetScaler uses HTTP
302 redirect.
Redirects 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.
Note: If a content switching vserver is configured with both a backup vserver
and a redirect URL, the backup vserver takes precedence over the redirect URL.
A redirect is used when the primary and backup vservers are down.
Chapter 5 Content Switching 343
The following table describes the parameter required for configuring a vserver to
redirect client requests to a URL.
The following example describes the steps to set the content switching vserver
Vserver-CS-1 to redirect client requests to the URL
http://www.newdomain.com/mysite/maintenance.
To configure a content switching vserver to redirect the client request to a
URL using the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. In the Redirect URL text box, type the URL, for example,
http://www.newdomain.com/mysite/maintenance.
6. Click OK.
To configure a content switching vserver to redirect the client request to a
URL using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -redirectURL
http://www.newdomain.com/mysite/maintenance
Managing Client Connections
Maintaining client connections helps to ensure the availability of the services.
This section includes procedures for configuring the NetScaler to use cache and
other tasks to improve response and direct client requests based on priority.
Parameter Description
Redirect URL The URL where traffic is redirected if the vserver in the
NetScaler becomes unavailable. This value must not
exceed 127 characters. The domain specified in the URL
must not match the domain specified in the domain name
argument of a content switching policy. If the same domain
is specified in both arguments, the request is redirected
continuously to the same unavailable vserver in the
NetScaler, and the user cannot get the requested content.
344 Installation and Configuration guide
Topics include:
• Redirecting Client Requests to a Cache
• Enabling Delayed Cleanup of Vserver Connections
• Rewriting Ports and Protocols for Redirection
• Inserting the IP Address and Port of a Vserver in the Request Header
• Setting a Time-out Value for Idle Client Connections
Redirecting Client Requests to a Cache
The NetScaler provides the cache redirection option for transparently redirecting
HTTP requests to a cache. A cache stores frequently requested HTTP content.
When you configure cache redirection on a content switching vserver, the
NetScaler sends cacheable HTTP requests to the transparent caches and
non-cacheable HTTP requests to the origin Web servers. For more information
about cache redirection, see the “Cache Redirection” chapter of the Installation
and Configuration Guide. To configure cache redirection, use the Cache
Redirection parameter as described in the following table.
To set cache redirection on a content switching vserver using the
configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. Select the Cacheable check box.
6. Click OK.
Parameter Description
Cacheable Enables the content switching vserver to route requests to
the cache redirection vserver before sending them to the
configured servers. The valid options for this parameter
are: yes and no. The default value is no.
Chapter 5 Content Switching 345
To set cache redirection on a content switching vserver using the NetScaler
command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -cacheable yes
Enabling Delayed Cleanup of Vserver
Connections
You can enable the setting on the Web servers whose connections can be flushed
when they are marked down. You must not enable the down flush state setting on
the application servers that must complete their transactions and their connections
must not be flushed. For more information about the down flush state setting, see
the “Load Balancing” chapter. To configure down state flush, use the down state
flush parameter as described in the following table.
To set down state flush on a content switching vserver using the
configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. Select the Down state flush check box.
6. Click OK.
To set down state flush on a vserver using the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -downStateFlush enabled
Parameter Description
down state flush Perform delayed cleanup of connections on this vserver.
The valid options for this parameter are: enabled and
disabled. The default value is enabled.
346 Installation and Configuration guide
Rewriting Ports and Protocols for Redirection
When the server responds with HTTP redirection, the NetScaler rewrites the port
and the protocol. By default, this setting is disabled. This setting affects SSL
traffic only. When this setting is enabled on a content switching vserver, the
NetScaler rewrites the port using the port settings of the content switching
vserver. For more information about SSL redirects, see the “Secure Sockets Layer
(SSL) Acceleration” chapter. To configure a vserver for HTTP redirection, you
must use the redirect port rewrite parameter listed in the following table.
To set redirection on a content switching vserver using the configuration
utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. Select the Redirect Port Rewrite check box.
6. Click OK.
To set redirection on a content switching vserver using the NetScaler
command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -redirectPortRewrite enabled
Inserting the IP Address and Port of a Vserver in
the Request Header
You can configure the NetScaler to add the IP address and port number of a
content switching vserver to the HTTP requests that are sent to the server. This
setting allows applications running on the server to identify the content switching
vserver that sent the request.
Parameter Description
Redirect Port Redirect SSL redirect port rewrite. The valid options for this
parameter are: enabled and disabled. The default value is
disabled.
Chapter 5 Content Switching 347
This option is not supported for wildcard vservers or dummy vservers. If the
primary content switching vserver is down and the backup content switching
vserver is marked up, the configuration settings of the backup content switching
vserver are added to the client requests. If you want to add the same header tag,
regardless of whether the requests are from the primary content switching vserver
or backup content switching vserver, then you must configure the required header
tag on both vservers.
To configure a vserver to add the IP address and port to the client requests, use the
Vserver IP Port Insertion parameter as described in the following table.
The following example describes the steps to configure the NetScaler to add the
IP address and port number of the vserver Vserver-CS-1 to HTTP requests that
are forwarded to the servers.
To insert the IP address and port of the vserver in the client requests using
the configuration utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
Parameter Description
Vserver IP Port Insertion The virtual IP and port header insertion option for the
vserver.
VIPADDR-Header contains the vserver IP address and port
number without any translation.
If VIPADDR is not specified, the header is inserted with
the name specified in the default header tag vip-header and
the vserver IP and port are inserted in the request with the
default header tag vip-header.
If VIPADDR is specified, the header is inserted with the
user-specified name in vipHeader. The vserver IP and port
are inserted in the request with the user-specified header
tag vipHeader.
OFF- The virtual IP and port header insertion options are
disabled. The vserver and port number are not inserted.
V6TOV4MAPPING - Header contains the mapped IPv4
address corresponding to the IPv6 address of the vserver
and the port number.
An IPv6 address can be mapped to a user-specified IPv4
address. The valid options for this parameter are: OFF,
VIPADDR, and V6TOV4MAPPING. The default value is
OFF.
348 Installation and Configuration guide
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
5. In the Vserver IP Port Insertion list, select the VIPADDR or
V6TOV4MAPPING.
6. Type the port header in a text box next to Vserver IP Port Insertion box.
7. Click OK.
To insert the IP address and port of the vserver in the client requests using
the NetScaler command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -insertVserverIPPort VipAddr
Setting a Time-out Value for Idle Client
Connections
You can configure the content switching vserver with a timeout value to terminate
any idle client connections when the configured time elapses. If the client is idle
after the configured time, the NetScaler closes the client connection. To set a
timeout value for idle client connections, use the client parameter as described in
the following table.
The following example describes the steps to set the timeout value for idle client
connections to 100 seconds.
To set a timeout value for idle client connections using the configuration
utility
1. In the navigation pane, expand Content Switching and click Virtual
Servers. The Content Switching Virtual Servers page appears in the
details pane.
2. Select the vserver for which you want to bind the service, for example,
Vserver-CS-1.
3. Click Open. The Configure Virtual Server (Content Switching) dialog
box appears.
4. Click the Advanced tab.
Parameters Descriptions
Client Timeout (Secs) The idle time (in seconds) after which the client connection is
terminated. The default value is 180sec for HTTP/SSL-based
services and 9000sec for TCP-based services.
Chapter 5 Content Switching 349
5. In the Client Timeout (secs) text box, type the timeout value, for example,
100.
6. Click OK.
To set a timeout value for idle client connections using the NetScaler
command line
At the NetScaler command prompt, type:
set cs vserver Vserver-CS-1 -cltTimeout 100
350 Installation and Configuration guide
CHAPTER 6
Secure Sockets Layer (SSL)
Acceleration
Overview
This chapter describes SSL acceleration on the NetScaler. The topics covered
include:
• How SSL Works
• Configuring SSL Offloading
• Managing Certificates
• Configuring Client Authentication
• Managing Certificate Revocation lists
• Customizing the SSL Configuration
• Managing SSL Actions and Policies
• Configuring Some Commonly Used SSL Configurations
• Configuring the SSL Feature for Commonly Used Deployment Scenarios
How SSL Works
Processing secure SSL transactions can consume a large portion of a Web server’s
CPU capacity, degrading performance and increasing end-user response times.
SSL acceleration transparently improves the performance of Web sites that
conduct SSL transactions. The SSL protocol works seamlessly with a variety of
HTTP and TCP data types, and provides a secure channel for these data
transactions.
A NetScaler configured with SSL acceleration is placed in front of a Web server,
where it intercepts SSL transactions on behalf of the server, processes the SSL
transactions, applies the NetScaler’s load balancing and content switching
policies, then relays the transactions to the servers.
352 Installation and Configuration Guide - Volume 1
The following figure shows an implementation of the SSL feature.
SSL entity diagram
To configure SSL, you must first create an SSL virtual server and services on the
NetScaler. Then, 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
the certificate bound to the virtual server. The SSL virtual server then forwards
the decrpyted data to the other entities on the NetScaler for appropriate
processing. SSL services are a virtual representation of the physical servers on the
internal network that offload SSL processing to the NetScaler.
Note: FIPS-related options for some of the procedures described in this
document are specific to a FIPS-enabled Application Switch. See the FIPS Guide
for more information about configuring a FIPS-enabled Application Switch
Configuring SSL Offloading
SSL offloading diverts the CPU-intensive SSL encryption/decryption tasks from
the local Web server to the NetScaler, thereby freeing Web server resources to
handle requests for content. SSL offloading ensures the secure delivery of Web
applications without degrading performance. Once the SSL traffic is decrypted, it
can be processed using any standard services on the NetScaler.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 353
This section explains the procedures to configure basic SSL offloading on the
NetScaler. The following tasks are covered:
• Enabling the SSL Feature
• Configuring an SSL Virtual Server for Basic SSL Offloading
• Verifying the Configuration
Enabling the SSL Feature
You should enable the SSL feature on the NetScaler before any SSL processing is
carried out. (You can configure SSL-based entities on the NetScaler without
enabling the SSL feature, but they will not work until you enable SSL.)
The SSL feature is located under Basic Features in the Citrix NetScaler
Configuration Utility.
To enable the SSL feature
1. In the left pane, expand System, then click Settings. The Settings page
appears in the right pane.
2. In the Modes & Features group, click the Basic Features link. The
Configure Basic Features dialog box appears.
3. Select the SSL Offloading check box, then click OK. When the Enable/
Disable Feature(s)? message box appears, click Yes.The SSL feature is
enabled on the NetScaler.
To enable the SSL feature using the NetScaler command line
At the NetScaler command prompt, type:
enable ns feature ssl
354 Installation and Configuration Guide - Volume 1
Configuring an SSL Virtual Server for Basic SSL
Offloading
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 NetScaler
allows the back-end servers to process a greater number of requests. This is
illustrated in the following figure..
Basic SSL offloading
Note: For TCP traffic, follow the procedures given below, but create TCP
services instead of HTTP services.
To configure SSL for basic SSL offloading, you need to set the parameters as
described in the sections that follow.
The procedures describe the steps to configure the SSL feature in a basic SSL
offload setup where an SSL virtual server Vserver-SSL-1 offloads SSL traffic
directed to two HTTP services, Service-HTTP-1 and Service-HTTP-2.
Adding HTTP-based Services
A service on the NetScaler represents a physical web server in the network. Once
configured, services are in the disabled state until the NetScaler can reach the
server on the network and monitor its status.
The following procedure describes the steps to configure two HTTP based
services, Service-HTTP-1 and Service-HTTP-2 with IP addresses 10.102.20.30
and 10.102.20.31.
To add an HTTP-based service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Click Add. The Create Service dialog box appears.
3. In the Service Name text box, type the name of the service being added, for
example, Service-HTTP-1.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 355
4. Under Server, type the IP address of the server to be associated with this
service, for example, 10.102.20.30.
Note: If the server has been configured already, in step 4, select the
configured server to be associated with the service.
5. Under Protocol, select HTTP.
Note: For TCP services, under Protocol, select TCP.
6. In the Port text box, type the port number for the HTTP service to use, for
example, 80.
7. Click Create, then click Close. The HTTP service you configured appears
in the Services page.
To create the second service, repeat the procedure for the service name Service-
HTTP-2 with IP address 10.102.20.31.
To add an HTTP-based service using the NetScaler command line
At the NetScaler command prompt, type:
add service Service-HTTP-1 10.102.20.30 HTTP 80
Adding an SSL-based Virtual Server
Secure sessions require establishing a connection between the client computer
and an SSL-based virtual server on the NetScaler.
SSL processing is then carried out on the incoming traffic at the virtual server.
Therefore, before enabling the SSL virtual server on the NetScaler, you need to
bind a valid SSL certificate to the SSL virtual server.
The procedure that follows describes the steps to configure an SSL-based virtual
server with IP address 10.102.29.50 and protocol SSL, listening on port 443.
To add an SSL-based virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Click Add. The Create Virtual Server (SSL Offload) dialog box appears.
3. In the Name text box, type the name of the virtual server to be created, for
example Vserver-SSL-1.
4. In the IP Address text box, type the IP address of the virtual server, for
example, 10.102.29.50.
356 Installation and Configuration Guide - Volume 1
5. Under Protocol, select SSL.
6. In the Port text box, type the port number for the virtual server to use, for
example, 443.
7. Click Create, then click Close. The virtual server you created appears in
the SSL Offload Virtual Servers page.
Note: The SSL virtual server you create is shown as down because a certificate-
key pair has not been bound to it, and there are no services bound to it.
To add an SSL-based virtual server using the NetScaler command line
At the NetScaler command prompt, type:
add vserver Vserver-SSL-1 SSL 10.102.29.50 443
Binding the HTTP Services to the Virtual Server
After decrypting the incoming data, the SSL virtual server forwards the data to
the services that are bound to the virtual server. Data transfer between the
NetScaler and the servers can be encrypted or in clear text.
Note: If the data transfer between the NetScaler and the server is encrypted, the
entire transaction is secure from end to end. For details about configuring the
NetScaler for end to end security, refer to the section Configuring SSL Offloading
with End-to-End Encryption.
The following procedure describes the steps to bind the services Service-HTTP-1
and Service-HTTP-2 to the virtual server Vserver-SSL-1.
To bind a service to a virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Select the virtual server Vserver-SSL-1, then click Open. The Configure
Virtual Server (SSL Offload) dialog box appears.
3. Click the Services tab, then select the checkboxes next to the services
Service-HTTP-1 and Service-HTTP-2.
4. Click OK. The services Service-HTTP-1 and Service-HTTP-2 are bound to
the virtual server Vserver-SSL-1.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 357
Note: The load balancing feature on the NetScaler should be enabled before
binding multiple services to a virtual server. For details on enabling features on
the NetScaler, refer the Enabling the SSL Feature section.
To bind a service to a virtual server using the NetScaler command line
At the NetScaler command prompt, type:
bind lb vserver Vserver-SSL-1 Service-HTTP-1
bind lb vserver Vserver-SSL-1 Service-HTTP-2
Binding an SSL Certificate Key Pair to the Virtual Server
An SSL certificate is an integral element of the SSL encryption and decryption
process. The certificate is used during SSL handshaking to determine the cipher
that will be used for SSL processing, and also to establish the identity of the SSL
server.
You can either use a valid, existing SSL certificate that you have on the
NetScaler, or you can create your own SSL certiifcate on the NetScaler.
Intermediate certificates created using a FIPS key on the NetScaler cannot be
bound to an SSL virtual server.
Note: We recommend that you use a valid SSL certificate that has been issued
by a trusted certificate authority. Invalid certificates and self-created certificates
will not be compatible with all client NetScalers.
The following procedure describes the steps to bind an existing SSL certificate,
SSL-Certkey-1 to the virtual server Vserver-SSL-1.
To bind an SSL certificate key pair to a virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. From the list of virtual servers, select the virtual server you want to bind the
certificate key pair to. For example, select Vserver-SSL-1, then click
Open. The Configure Virtual Server (SSL Offload ) dialog box appears.
3. Click the SSL Settings tab. In the Available area, select the certificate key
pair that you want to bind to the virtual server. For example, select SSL-
Certkey-1 and click Add. The certificate key pair appears in the
Configured area.
4. Click OK. The certificate pair is bound to the virtual server.
358 Installation and Configuration Guide - Volume 1
To bind an SSL certificate key pair to a virtual server using the NetScaler
command line
At the NetScaler command prompt, type:
bind ssl certkey SSL-Certkey-1 Vserver-SSL-1
Adding a Certificate Key Pair
Before a certificate can be used for SSL processing, it must be paired with its
corresponding key. The certificate key pair that you create is then bound to the
virtual server and used for SSL processing.
To add a certificate key pair
1. In the left pane, expand SSL and click Certificates. The SSL Certificates
page appears in the right pane.
2. Click Add. The Install Certificate dialog box appears.
3. In the Name text box, type the name of the certificate key pair you want to
add, for example, Certkey-SSL-1.
4. Under Details, select Remote System.
Note: Both the certificate and the key must be present in the same
location. To use a certificate present on the local system, in Step 4 above,
select Local System.
5. Select the Browse button next to Certificate Filename. The NetScaler file
browser appears.
Note: You will not be able to load the FIPS key from a local storage
device such as a hard disk or flash memory. FIPS keys should always be
loaded from the HSM.
6. Select the certificate you want to use and click the Select button.
7. Select the Browse button next to Key Filename. The NetScaler file
browser appears.
8. Select the key you want to use and click the Select button.
Note: To encrypt the key used in the certificate key pair, in the Password
text box, type the password to be used for encryption.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 359
9. Click Install. The certificate key pair you created appears in the SSL
Certificates window.
To add a certificate key pair using the NetScaler command line
At the NetScaler command prompt, type:
add ssl certkey Certkey-SSL-1 -cert Cert-SSL-1 -key Key-SSL-1
FIPS based systems do not support external keys (non-FIPS keys). On a FIPS
system, you will not be able to load keys from a local storage device such as a
hard disc or flash memory.
The following example describes steps to load a certificate and associate it with
its corresponding FIPS key that resides within the HSM.
add ssl cer t key Cer t key- SSL- FI PS - cer t Cer t - SSL- Fi ps. pem- f i pskey
Key- SSL- FI PS. pem
Verifying the Configuration
This section explains how to verify the SSL settings you have configured.
Viewing the SSL settings can be useful for troubleshooting.
Viewing the Properties of the Configured Service
You can view the properties of the services created on the NetScaler to ensure that
the settings configured have been saved accurately.
To view the properties of the configured service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Verify that the configured service Service-HTTP-1 is displayed.
3. Select the service Service-HTTP-1 and in the Details section, verify that
the parameters are accurately configured.
To view the properties of the configured service using the NetScaler
command line
At the NetScaler command prompt, type:
show service Service-HTTP-1
Viewing the Properties of the Vserver
You can view the properties of the virtual servers you have created on the
NetScaler to confirm that the settings have been saved accurately.
360 Installation and Configuration Guide - Volume 1
To view the properties of the configured vserver
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offlload Virtual Servers page appears in the right pane.
2. Verify that the configured virtual server Vserver-SSL-1 is displayed and is
Enabled.
3. Select the virtual server Vserver-SSL-1 and in the Details section, verify
that the parameters are accurately configured.
To view the properties of the configured vserver using the NetScaler
command line
At the NetScaler command prompt, type:
show vserver Vserver-SSL-1
Viewing the Properties of the Certificate Key Pairs
You can view the properties of the certificate-key pairs created on the NetScaler,
to confirm that the settings are accurately configured.
To view the properties of the configured certificate key pairs
1. In the left pane, expand SSL, then click Certificates. The SSL Certificates
page appears in the right pane.
2. Verify that the configured certificate key pair, Certkey-SSL-1 is displayed.
3. Select the certificate key pair Certkey-SSL-1 and in the Details section,
verify that the parameters are accurately configured.
To view the properties of the configured certificate key pairs using the
NetScaler command line
At the NetScaler command prompt, type:
show ssl certkey Certkey-SSL-1
Managing Certificates
To configure the SSL feature, you need a certificate and a private key for the Web
server. An SSL certificate is a digital data form (X509) that identifies a company
(domain) or an individual. An SSL key is the private component of the public-
private key pair used in asymmetric key encryption (public key encryption).
Note: The Application Switch supports a certificate size of up to 2,048 bits
(RSA/DSA).
Chapter 6 Secure Sockets Layer (SSL) Acceleration 361
You can obtain the SSL certificate and key in one of three ways
• From an authorized Certificate Authority (CA), such as VeriSign.
• Use an existing SSL certificate and key.
• Generate a new SSL certificate and key on the Application Switch.
Obtaining a Certificate froma Certificate Authority
To obtain an SSL certificate from an authorized certificate authority (CA),
you must create a Certificate Signing Request (CSR) and submit it to the CA.
The following procedures describe how to create a CSR that you can submit
to a CA to obtain a valid certificate.
Creating a Private Key
Every SSL certificate has a private key associated with it. This key is an integral
part of the encryption process and is required by the SSL certificate.
The NetScaler allows you to create either an RSA or DSA key which you can
then use to create a CSR and obtain a certificate.
To create an RSA key
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create RSA Key. The Create RSA Key dialog box appears.
3. In the Key Filename text box, type the name of the RSA key, for example,
Key-RSA-1.
Note: By default, SSL certificates and keys are stored in the /nsconfig/ssl
directory on the NetScaler. If you want to store them elsewhere, use the
browse button to navigate to the desired location.
4. In the Key Size (Bits) text box, type the size in bits of the key, for example,
1024.
5. Click Create, then click Close. The RSA key you created is saved on the
NetScaler.
To create an RSA key using the NetScaler command line
At the NetScaler command prompt, type:
create ssl rsakey Key-RSA-1 1024
362 Installation and Configuration Guide - Volume 1
To create a DSA key
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create DSA Key. The Create DSA Key dialog box appears.
3. In the Key Filename text box, type the name of the DSA key, for example,
Key-DSA-1.
Note: SSL certificates and keys are stored by default in the /nsconfig/ssl
directory on the NetScaler. If you want to store them elsewhere, use the
browse button to navigate to the required location.
4. In the Key Size (Bits) text box, type the size in bits of the key, for example,
1024.
5. Click Create, then click Close. The DSA key you created is saved on the
NetScaler.
To create an DSA key using the NetScaler command line
At the NetScaler command prompt, type:
create ssl dsakey Key-DSA-1 1024
For added security, you can encrypt your SSL key using the DES or triple DES
(3DES) algorithm. The DES and triple DES options are valid only for keys stored
in PEM format, not for keys stored in DER format.
Caution: Make sure you limit access to your private key. Anyone who has
access to your private key can generate a new CSR and obtain a new certificate
using your identity.
The certificate that you receive from the CA is valid only with the private key
used to create the CSR. The private key is required to add the certificate on the
NetScaler.
Creating a Certificate Signing Request
The certificate signing request (CSR) is a collection of details, including the
domain name, other important company details, and the private key to be used to
create the certificate. To avoid generating an invalid certificate, you need to
ensure that the details provided are accurate.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 363
To create a certificate signing request
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create Certificate Request. The Create Certificate Request dialog
box appears.
3. In the Request File Name text box, type the name of the CSR, for example
Certificate-Request-1.
4. In the Key File Name text box, type the name of the key to be used to
create the CSR, for example, Key-RSA-1.
Note: You can use the browse button to navigate to the saved key on the
NetScaler.
5. Select the format the key was saved in. For example, PEM.
6. In the PEM Passphrase (For Encrypted Key), type the password used to
encrypt the key.
7. Under Distinguished Name Fields, enter relevant information for each
parameter. The information you enter will form the Distinguished Name
(DN) of the company (Web site).
8. Click Create, then click Close. The certificate signing request you created
is saved on the NetScaler in the specified location.
To create a certificate signing request using the NetScaler command line
At the NetScaler command prompt, type:
create ssl certreq Certificate-Request-1 -keyFile Key-RSA-1
Next, you need to send the CSR to a CA for authentication and signing. Most
CAs accept certificate submissions by email. The CA will return a valid
certificate to the email address you used to submit the CSR.
Once you have obtained the signed certificate from a CA, install the certificate
and its corresponding private key on the NetScaler.
Note: For information on configuring a chain of certificates that to be sent on
behalf of an SSL virtual server, refer to the section Creating a Chain of
Certificates.
364 Installation and Configuration Guide - Volume 1
Exporting Existing Certificates and Keys
Instead of purchasing new certificates and keys, you can use versions from an
existing secure server. The following sections describe the procedures to transfer
a certificate and key from a secure server.
Note: For further instructions on exporting keys and certificates, refer to the
documentation of the server you are exporting from.
Key and certificate names cannot contain spaces or special characters other than
those supported by the Unix file system. Be sure to follow the appropriate naming
convention when you save the exported key and certificate.
The NetScaler supports two encoding formats for keys and certificates: PEM and
DER. You must convert the certificate or key file to one of these formats before
you install them.
Exporting Certificates froman Apache mod_SSL Server
The location of the key and certificate files is listed in the $APACHEROOT/conf/
httpd.conf file. The default key is available in $APACHEROOT/conf/ssl.key/
*.key, and the default certificate is available in $APACHEROOT/conf/ssl.crt/
*.crt.
Transfer the certificate and key to the NetScaler and follow the installation
procedure as described above.
Note: Use an FTP client to transfer the certificate and the key to the NetScaler
in binary mode.
Exporting certificates and keys fromApacheSSL
The locations of the key and certificate files are listed in $APACHESSLROOT/
conf/httpd.conf. The default key is available in $APACHEROOT/certs/*.key, and
the default certificate is available in $APACHEROOT/certs/*.crt.
Transfer the certificate and key to the NetScaler and follow the installation
procedure as described above.
Note: Use an FTP client to transfer the certificate and the key to the server in
binary mode.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 365
Exporting Certificates and Keys froma Stronghold
Server
The locations of the key and certificate files are listed in the
$STRONGHOLDROOT/conf/httpd.conf file. The default key is available in
$STRONGHOLDROOT/conf/ssl.key/*.key and the default certificate is
available in $STRONGHOLDROOT/conf/ssl.crt/*.crt.
Transfer the certificate and key to the NetScaler and follow the installation
procedure as mentioned above.
Note: Use an FTP client to transfer the certificate and the key to the NetScaler
in binary mode.
Exporting Certificates and Keys froman IIS 4 Server on
Windows NT
The certificate file is stored in the directory that was specified when the
certificate was downloaded from the CA.
To export the certificate from an IIS 4 server on Windows NT
1. Double-click the certificate file to open the viewer, then click the Details
tab.
2. Click Copy to file. The Certificate Manager Export wizard appears.
3. Click Next. Select the DER-encoded binary X.509 button.
4. Click Next. Type the File Name and Location to store the certificate in the
DER format.
5. Click Next, then click Finish.
6. When the notice of succesful completion appears, click OK.
7. Exit the Certificate Manager Export wizard.
8. Close theCertificate Viewer.
Note: The certificate is exported in DER format.
The keys are located within the Key Ring in the key manager program.
366 Installation and Configuration Guide - Volume 1
To export a key from an IIS 4 server on Windows NT
1. Click the Start button, navigate to Programs>Windows NT 4.0 Option
Pack>Microsoft Internet Information Server, then click Internet
Service Manager. The Microsoft Management Console appears.
2. Navigate to the Web site using the object list.
3. Right-click the Web site object and click Properties in the shortcut menu.
4. Click theDirectory Security tab.
5. In the Secure Communication panel, click Edit.
6. Click the Key Manager, then select the key to export.
7. On the Key menu, point to Export Key, then click Backup File.
8. Read the security warning, then click OK.
9. Select a file name and location to store the key, then click Save.
10. Exit the Internet Service Manager.
The key and certificate file are exported from an IIS server in PKCS#12 (.PFX)
format. Convert these to either the PEM or DER format, and install them on the
NetScaler as described in the section Binding an SSL Certificate Key Pair to
the Virtual Server.
Note: For more information on converting the certificate from the PKCS#12
format to the DER or PEM format, refer to the section Importing SSL
Certificates.
Exporting Certificates froman IIS 5 Server on Windows
2000
To install certificates and keys from an IIS 5 server on Windows 2000, first export
the certificate and key, then transform the key and certificate, and install the key
and certificate on the NetScaler, as described in the following procedure.
To export certificates and keys from an IIS 5 server on Windows 2000
1. Run the Internet Service manager by doing one of the following:
• Click Start, select Programs/Administrative Tools, and click
Internet Service Manager.
or
• Open Control Panel > Administrative Tools > Internet Service
Manager.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 367
2. Right-click the Web site object, then click Properties in the shortcut menu.
3. Click theDirectory Security tab.
4. In the Secure Communications panel, click View Certificate. The
Certificate Viewer appears.
5. Click the Details tab, then click Copy to File.
6. In the Certificate Export wizard, click Next. The Export Private Key
screen appears.
7. Select Yes to export the private key, then click Next. The Export File
Format screen appears.
8. Select Personal Information Exchange—PKCS#12 (pfx) and any
optional choices, then click Next. The Password screen appears.
9. In the Password and Confirm Password text boxes, type the password,
then click Next. The File to Export screen appears.
10. Type the complete path and file name to the location where you want to
save the certificate and key files, then click Next. The Completing the
Certificate Export Wizard screen appears.
Note: Alternatively, click the browse button and use the Windows
Explorer controls to navigate to the folder and file.
11. Click Finish.The files are saved in the specified location.
The key and certificate file exported from IIS 5 are in PKCS#12 (.PFX) format
and must be converted to PEM or DER format before being loaded on the
NetScaler. For more information on converting the certificate format, refer to the
section Importing SSL Certificates.
Exporting Certificates and Keys fromSun iPlanet
To export certificates from Sun iPlanet, you must use the pk12util utility provided
by Sun Microsystems.
Before you export the certificate using the pk12util utility, you need to do the
following
• Determine the name of the certificate and/or key pairs you wish to extract
(export). The default name is Server-Cert.
• Write down the password that was used to protect the database. You will
need to provide this password to access the contents of the databases.
368 Installation and Configuration Guide - Volume 1
• Locate the folder where following certificate and key databases are stored:
server_root/alias/<serverid-hostname>-key3.db for the key file, and
server_root/alias/<serverid-hostname>-cert7.db for the certificate
Use the following command to export certificates from Sun iPlanet
pk12ut i l - o {out put f i l ename} - n {cer t i f i cat e name} - d {cer t db
di r ect or y} [ - P {cer t db name pr ef i x}]
The following procedure describes the steps to export the certificate, mySite-
cert.db and the key, mySite-key.db, from an iPlanet Web server
To export a certificate and key from the Sun iPlanet server
1. Enter the following command:
pk12ut i l - o out put . p12 - n Ser ver - Cer t - d
c: \ i Pl anet \ ser ver _r oot \ al i as\ - P mySi t e-
2. At the prompt “NSS Certificate DB”: (enter db password) , type the
password or pin.
3. At the prompt (enter output password), type the password for the PKCS12
file.
4. At the prompt (re-enter output password), re-type the password. The
pk12util utility displays the message “PKCS12 EXPORT
SUCCESSFUL”
You must provide the complete path to the pk12util binary in the command line
interface’s search path. Also put the lib directory ($WEBSERVER_ROOT/bin/
https/lib by default} in front of the LD_LIBRARY_PATH environment
variable.
For a Solaris server using the Bourne shell, the command to be used is
expor t LD_LI BRARY_PATH=${WEBSERVER_ROOT}/ bi n/ ht t ps/
l i b: $LD_LI BRARY_PATH
If the error message “Bad database error without -d option” appears, use the -d
switch to point to the directory where the certificate and key databases are
located.
The default names for the certificate and key databases on an iPlanet server are
cert7.db and key3.db. iPlanet may prefix the server name with the full machine
name for the administrator server and any additional virtual servers that you have
defined. In this case, you must include the -P switch with the argument: https-
hostname.domain.com-hostname.
The exported certificate will be saved in PKCS#12 format and must be converted
to PEM or DER format before you install it on the NetScaler.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 369
Exporting Certificates and Keys fromBEA WebLogic
Server
On a BEA WebLogic server, the configured certificate and key are stored in the
weblogic.properties file, under weblogic.security.certificate.server, which is a per
server directory.
To export the certificate file and private key file from the WebLogic server
1. Identify the file where the certificate and key are stored. The path to this file
should be displayed in the weblogic.properties file, in the following fields:
• The weblogic.security.key.server property field contains the name of
the private key file.
• The weblogic.security.certificate.server property field contains the
name of the certificate file received from the CA.
2. Use an FTP client to transfer the certificate and key in binary mode to the
NetScaler.
The certificate and key file must be transferred to the NetScaler in the same
format. In some versions of BEA WebLogic Server (for example, version 5.0.1),
the server allows the key to be exported in DER format and the certificate in PEM
format. In such cases, you can convert the DER-encoded key to PEM format
using the following OpenSSL tool command:
openssl pkcs8 - i n keyf i l e. der - i nf or mDER - out keyf i l e. pem- out f or m
PEM
Once the certificate and key files are transferred to the NetScaler, install the
certificate key pair using the procedures described in the section Binding an SSL
Certificate Key Pair to the Virtual Server.
Generating a NewCertificate and Key
This section provides procedures for creating new certificates and keys on the
NetScaler.
You configure SSL certificates to identify a domain or an individual in a secure
connection. The NetScaler supports SSL certificates that self-signed or signed by
a trusted certifying authority.
The NetScaler can act as a certifying authority and provide options for creating a
certificate request, an encryption key, and signing certificates.
Generating a Key
This section describes how to generate a key on the NetScaler that can be used for
creating certificates
370 Installation and Configuration Guide - Volume 1
Generating an RSA Key
For details, see the “To create an RSA key” in the section section Creating a
Private Key.
Generating a DSA Key
For details, see the “To create an DSA key” in the section Creating a Private Key.
Generating a DH Key
The DH key exchange feature enables support for Diffie-Hellman (DH) key
exchange for an SSL virtual server or SSL service on the NetScaler. By default,
this feature is disabled.
You need to enable this feature to support ciphers that use DH as the key
exchange algorithm.
The following procedure describes the steps to create a 512 bit DH key, Key-DH-
1 with its DH generator set to 2.
To generate a DH key
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Under Tools, click Create Diffe-Hellman (DH) Key. The Create DH
Param dialog box appears.
3. In the DH Filename (with path) text box, type the name of the DH key file
being created. For example, type Key-DH-1.
4. In the DH Parameter Size (Bits) text box, type the size, in bits of the DH
parameter being configured. For example, type 512.
Note: The DH key size ranges from 512 to 2048 bits.
5. Under DH Generator, select the value of the DH generator. For example,
select 2.
To generate a DH key using the NetScaler command line
At the NetScaler command prompt, type:
create ssl dhparam Key-DH-1 512 -gen 2
Generating a Certificate Signing Request
This section describes how to create a certificate signing request (CSR) that you
can send to a CA to obtain a certificate.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 371
Generating Self- Signed Certificates
You can create self-signed certificates using the Citrix NetScaler's built-in CA
tools suite. Because these certificates are signed by the NetScaler itself, and not
by an actual CA, you should not use them in a production environment, but only
for testing purposes. If you attempt to use a self-signed certificate in a production
environment, users will receive a "certificate invalid" warning each time the
virtual server is accessed.
The Citrix NetScaler allows you to create the following types of certificates
• Root-CA Certificates
• Intermediate CA Certificates
• Server Certificates
• Client Certificates
To create a Root-CA certificate
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create Certificate. The Create Certificate dialog box appears.
3. In the Certificate File Name text box, type the name of the certificate
being created, for example, Cert-RootCA-1.
Note: Instead of typing the certificate name, you can use the browse
button to launch the NetScaler file browser and select the file visually.
4. Select the check box next to the file format of the certificate, for example,
PEM.
5. Select the check box next to the type of certificate being created, for
example Root-CA.
6. In the Certificate Request File Name text box, type the name of CSR
created for the certificate, for example, type Certificate-Request-1.
7. In the Key File Name text box, type the name of the key next to the CSR,
for example, Key-RSA-1.
8. Select the radio button next to the format in which the key has been created,
for example, select PEM.
9. In the PEM Passphrase (For Encrypted Key) text box, type the password
used ot encrypt the key.
372 Installation and Configuration Guide - Volume 1
10. In the Validity Period (Number of Days) text box, type the duration in
days the certificate is valid for, for example, 365.
11. Click Create, then click Close. The Root-CA certificate you created is
saved on the NetScaler.
To create a Root-CA certificate using the NetScaler command line
At the NetScaler command prompt, type:
create ssl cert Root-CA Certificate-Request-1 PEM ROOT_CERT -
keyFile Key-RSA-1 -keyForm PEM -days 365
To create an Intermediate-CA, server or client certificate
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create Certificate. The Create Certificate dialog box appears.
3. In the Certificate File Name text box, type the name of the certificate
being created, for example, Cert-IntermediateCA-1.
Note: Instead of typing the filename, you can use the browse button to
launch the NetScaler file browser and select the file visually.
4. Select the check box next to the file format of the certificate, for example,
PEM.
5. Select the check box next to the type of certificate being created, for
example Intermediate-CA.
6. In the Certificate Request File Name text box, type the name of CSR
created for the certificate, for example, Certificate-Request-2.
7. In the Validity Period (Number of Days) text box, type the duration in
days the certificate is valid for, for example, 365.
8. In the CA-Certificate File Name text box, type the name of the CA
certificate that will issue this intermediate certificate. For example, Cert-
RootCA-1.
9. Select the radio button next to the format in which the CA certificate has
been created, for example, PEM.
10. In the CA Key File Name text box, type the name of the key corresponding
to the CA certificate, for example, Key-RSA-1.
11. Select the radio button next to the format in which the key has been created,
for example, PEM.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 373
12. In the PEM Passphrase (For Encrypted CA Key) text box, type the
password used to encrypt the key.
13. In the CA Serial Number File text box, type the name of the file to store
the serial number of the CA certificate in, for example, Serial-CA-1.
14. Click Create, then click Close. The Intermediate-CA certificate you
created is saved on the NetScaler.
To create an Intermediate-CA certificate using the NetScaler command line
At the NetScaler command prompt, type:
create ssl cert Intermediate-CA Certificate-Request-2 PEM INTM_CERT
-CAcert Root-CA -CAcertForm PEM -days 365
Note: To create server and client certificates, in step 5, select the radio button
next to Server Certificate and Client Certificate and in step 10, select the
corresponding intermediate certificate instead of a root certificate.
Creating a Chain of Certificates
If the server certificate is issued by an intermediate CA (not recognized by
standard Web browsers as a trusted CA), the CA certificate(s) must be sent to the
client with the server’s own certificate in order for the SSL handshake to proceed
successfully. Otherwise, the browser terminates the SSL session, after it fails to
authenticate the server certificate.
You must create a chain of certificates that will be sent to the client during the
SSL handshake. This chain links the server certificate to its issuer (the
intermediate CA). In order for this to work, the intermediate CA certificate file
must already be installed in the NetScaler.
Note: The NetScaler supports sending a maximum of 10 certificates in the
chain of certificates sent to the client (one server certificate and nine CA
certificates).
374 Installation and Configuration Guide - Volume 1
The following figure shows how certificates are linked in a chain.
Linking of a Certificate Chain
The following procedure illustrates the steps to link the server certificate Cert-
Server to the intermediate CA certificates Cert-Intermediate-A, Cert-
Intermediate-B and Cert-Intermediate-C.
This procedure assumes that all certificates required for the procedure have been
configured correctly on the NetScaler.
To create a certificate chain
1. In the left pane, expand SSL, then click Certificates. The SSL Certificates
page appears in the right pane.
2. Select the server certificate you want to link, for example, Cert-Server,
then click the Link buttton. The Link Server Certificate dialog box
appears.
3. Under CA Certificate Name, select the CA certificate to be linked to, for
example, Cert-Intermediate-A.
4. Click OK. The server certificate is now linked to the intermediate
certificate.
To create a certificate chain using the NetScaler command line
At the NetScaler command prompt, type:
link ssl certkey Cert-Server Cert-Intermediate-A
Repeat this procedure for intermediate certificates Cert-Intermediate-A and Cert-
Intermediate-B where Cert-Intermediate-A is linked to Cert-Intermediate-B and
Cert-Intermediate-B is linked to Cert-Intermediate-C.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 375
Managing Certificates and Keys
Certificates and their corresponding keys are stored on the NetScaler in either the
PEM or DER format, and are installed on the NetScaler as a certificate key pair.
The following sections describe how to customize an installed certificate key pair.
Replacing an Existing Server Certificate
Removing or unbinding a certificate from an SSL virtual server or an SSL service
will cause server downtime. The Citrix NetScaler allows certificate key pair
bound to SSL virtual servers or SSL services to be updated automatically, without
unbinding existing certificates and causing downtime.
To update an existing certificate key pair
1. In the left pane expand SSL, then click Certificates. The SSL Certificates
page appears in the right pane.
2. Select the certificate you want to update, for example Certkey-SSL-1, then
click Update. The Update Certificate dialog box appears.
3. Use the Browse button next to the Certificate Filename and the Key
Filename and select the new certificate and key files respectively.
4. In the Password text box, type the password used to encrypt the new key.
5. Click OK. The server certificate Certkey-SSL-1 is now updated with the
new certificate and key files.
To update an existing certificate key pair using the NetScaler command line
At the NetScaler command prompt, type:
update ssl certkey Certkey-SSL-1 Certificate-SSL-New -key Key-SSL-
New
Enabling the Expiry Monitor
An expiry monitor configured on the NetScaler provides advance notification to
the administrator before a certificate configured on the NetScaler is due to expire.
The following procedure describes how to create a monitor that uses the
certificate key pair Certkey-SSL-1 to notify the administrator 60 days before the
certificate expires
To enable an expiry monitor for a certificate
1. In the left pane expand SSL, then click Certificates. The SSL Certificates
page appears in the right pane.
2. Select the certificate you want to update, for example Certkey-SSL-1, then
click Update. The Update Certificate dialog box appears.
376 Installation and Configuration Guide - Volume 1
3. Select the Enable radio button.
4. In the Notification Period text box, type the required notification period
value, for example, 60.
Note: The notification period parameter can be set to any value between
10 and 100 days and the default notification period is 30 days.
5. Click OK. An expiry monitor is now configured for the certificate.
To enable an expiry monitor for a certificate using the NetScaler command
line
At the NetScaler command prompt, type:
set ssl certkey -expiryMonitor ENABLED -notificationPeriod 60
After you configure an expiry monitor, reporting is carried out through the syslog
and nsaudit logs by default. If you want to create SNMP alerts for the same
scenario, you must configure them separately.
Disabling Domain Checks
By default, when the Citrix NetScaler updates an SSL certificate, it checks for
matching domain names. For example, if you have a certificate issued to
abc.com, and you are updating it with a certificate issued to def.com, the
certificate update fails.
You can configure the NetScaler to ignore this domain check, so that SSL
certificates can be updated across domains.
To disable domain check for a certificate
1. In the left pane expand SSL, then click Certificates. The SSL Certificates
page appears in the right pane.
2. Select the certificate you want to update, for example Certkey-SSL-1, then
click Update. The Update Certificate dialog box appears.
3. Click the No Domain Check checkbox, then click OK. The domain check
for the certificate is now disabled.
To disable domain check for a certificate using the NetScaler command line
At the NetScaler command prompt, type:
update ssl certkey -noDomainCheck
Managing Global Site Certificates
A global site certificate is a special-purpose server certificate that allows export-
restricted browsers to upgrade to 128-bit strong encryption .
Chapter 6 Secure Sockets Layer (SSL) Acceleration 377
The global site certificate consists of a server certificate and an accompanying
intermediate-CA certificate. Export versions of browsers use 40-bit encryption to
initiate connections to SSL Web-servers. The server responds to connection
requests by sending its certificate. The client and server then decide on an
encryption strength based on the server certificate type:
• If the server certificate is a normal certificate and not a global site
certificate, the export client and server complete the SSL handshake and
use 40-bit encryption for data transfer.
• If the server certificate is a global site certificate (and if the export client
feature is supported by the browser), the export client automatically
upgrades to 128-bit encryption for data transfer.
If the server certificate is a global site certificate, the server sends its certificate,
along with the accompanying intermediate-CA certificate. The browser first
validates the intermediate-CA certificate using the Root-CA certificates that
come installed in browsers. On successful validation of the intermediate-CA
certificate, the server certificate is validated using the intermediate-CA
certificate. On successful validation, the browsers renegotiate (upgrade) the SSL
connection to 128-bit encryption.
With Microsoft Server Gated Cryptography (SGC), if the Microsoft IIS server is
configured with an SGC certificate, export clients that receive the certificate
renegotiate to 128-bit encryption.
Importing a Global Site Certificate
To import a global site certificate, first export the certificate and server key from
the Web server. Then, before importing the global site certificate, export (convert)
the certificate and key to PEM format.
Note: For more instructions on exporting certificates and keys for your server
type, see the section Exporting an Existing Certificate and Key. .
To import a global site certificate
1. Using a text editor, copy the server certificate and the accompanying
intermediate-CA certificate into two separate files.
The individual PEM encoded certificate will begin with the header -----
BEGIN CERTIFICATE----- and end with the trailer -----END
CERTIFICATE-----.
2. Use an FTP client to transfer the server certificate, intermediate-CA
certificate, and server-key to the NetScaler.
378 Installation and Configuration Guide - Volume 1
3. Use the following command to identify the server certificate and
intermediate-CA certificate from the split files. The NetScaler comes with
the openssl tool installed in /usr/bin.
At the FreeBSD shell prompt, enter the following command:
openssl x509 –i n cer t . pem- t ext | mor e
Where cert.pem is one of the split certificate files.
Read the Subject field in the command output. For example,
Subject: C=US, ST=Oregon, L=Portland, O=Foobar, Inc., OU=IT,
CN=www.foobar.com
If the CN field in the Subject matches the domain-name of your Web site,
then this is the server certificate and the other certificate is the
accompanying intermediate-CA certificate.
4. Add the server certificate (and its private key) on the NetScaler. For details
on creating a certificate key pair on the NetScaler, refer to the section
Adding a Certificate Key Pair.
5. Add the intermediate-CA certificate on the NetScaler. Use the server
certificate you created in step 4 to sign this intermediate certificate. For
details on creating an Intermediate-CA certificate on the NetScaler, refer to
the section Generating Self- Signed Certificates.
Note: An intermediate-CA certificate does not require a key.
6. Bind the server certificate to the SSL virtual server. For details on binding
the server certificate to the SSL virtual server, refer to the section Binding
an SSL Certificate Key Pair to the Virtual Server.
Importing and Exporting SSL Certificates
All SSL certificates on the NetScaler are stored and used in PEM or DER format.
However, other applications (such as client browsers, and some external secure
servers) use SSL certificates saved using various PKCS (public key cryptography
standard) formats. The NetScaler supports the PKCS#12 format for storing
certificates, which is the personal information exchange syntax standard. To
allow the NetScaler to inter-operate with these applications, the NetScaler
includes a tool for importing and exporting SSL certificates.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 379
Importing SSL Certificates
The SSL certificate import tool enables you to import certificates from the
PKCS#12 format to either the PEM or the DER formats. For additional security,
the private key of the imported certificates can be encrypted using the DES or the
DES3 algorithms before storing the certificates on the NetScaler.
The following procedure describes the steps to import a PKCS#12 certificate
Cert-Import-1.pfx into the NetScaler in the PEM format and store it as Cert-
Import-1.pem. The private key is further encrypted using the DES algorithm
using the passphrase “ImportPassphrase”.
To import certificates from the PKCS#12 format
1. In the left pane expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Import PKCS#12. The Import PKCS12 dialog box appears.
3. In the Output File Name text box, type the name of the file to be created,
for example, Cert-Import-1.pem.
4. In the PKCS12 File Name text box, type the name of the certificate file to
be imported, for example, Cert-Import-1.pfx
Note: You can navigate the file system on the NetScaler using the the
Browse button.
5. In the Import Password box, type the password that was used to create the
PKCS file.
6. Under Encoding Format, select the type of algorithm to be used to encrypt
the private key of the imported certificate, for example, DES.
7. In the PEM Passphrase text box, type the password, if any, used to encrypt
the key, for example, ImportPassphrase.
Note: The PEM Passphrase option is displayed only if either the DES or
the DES3 encoding formats are chosen.
8. In the Verify PEM Passphrase text box, type the same passphrase again
for confirmation.
9. Click OK. The client certificate you imported is saved on the NetScaler.
To import certificates from the PKCS#12 format using the NetScaler
command line
At the NetScaler command prompt, type:
380 Installation and Configuration Guide - Volume 1
convert ssl pkcs12 Cert-Import-1.pem -import -pkcs12File Cert-
Import-1.pfx -des
Exporting SSL Certificates
The SSL certificate export tool enables you to export certificates saved in PEM or
DER format to the PKCS#12 format. Certificates commonly need to be exported
to PKCS#12 format in order to install them in a client browser that will be used
for client authentication.
The following procedure describes the steps to export a client certificate Cert-
Client-1 into the PKCS#12 format as Cert-Client-1.pfx. The password used while
exporting is ExportPassword and the private key is encrypted using the
passphrase PEMPassphrase.
To export certificates to the PKCS#12 format
1. In the left pane expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Export PKCS#12. The Export PKCS12 dialog box appears.
3. In the PKCS12 File Name text box, type the name of the PKCS file to be
created, for example, Cert-Client-1.pfx.
Note: To select an existing file on the NetScaler, click the Browse button
and navigate to the required file.
4. In the Certificate File Name text box, type the name of the certificate to be
converted, for example Cert-Client-1.
5. In the Key File Name text box, type the name of the key file associated
with the certificate, for example, Key-Client-1.
6. In the Export Password text box, type the password to encrypt the
exported key with, for example, ExportPassword.
7. In the PEM Passphrase text box, type the password, if any, used to encrypt
the key, for example, PEMPassphrase.
8. Click OK. The client certificate you exported is saved on the NetScaler.
To export certificates to the PKCS#12 format using the NetScaler command
line
At the NetScaler command prompt, type:
convert ssl pkcs12 Cert-Client-1.pfx -export -certFile Cert-Client-
1 -keyFile Key-Client-1
Chapter 6 Secure Sockets Layer (SSL) Acceleration 381
Configuring Client Authentication
With client authentication enabled on an SSL virtual server, the NetScaler asks
for the client certificate during SSL handshake for secure connection requests
being sent to this virtual server. The NetScaler checks the certificate for normal
constraints, such as issuer signature and expiration date.
Note: In order for the NetScaler to verify issuer signatures, the CA certificate
for the client certificate must be installed on the NetScaler.
If the certificate is valid, the NetScaler allows the client to access all secure
resources. But if the certificate is found to be old, corrupt, or absent, the
NetScaler drops the client request during the SSL handshake. However, an
administrator can configure the NetScaler to proceed with the handshake even if
the client does not provide a valid certificate.
The NetScaler verifies the client certificate by first forming a chain of certificates,
starting with the client certificate and ending with the root CA certificate for the
client (for example, VeriSign). This chain includes the client certificate. The root
CA certificate may contain one or more intermediate CA certificates (if the client
certificate is not directly issued by the root CA).
In order for the client authentication feature to work properly The CA certificates
used in client certificate verification (root CA and any intermediate CA
certificates) must be installed in the NetScaler and bound to the SSL virtual
server
This section describes the procedures involved in configuring client
authentication on the NetScaler.
Generating Client Certificates
A client certificate includes details about the specific client system that will
create secure sessions with the NetScaler. (Details of the client system are
provided in the certificate.) Each client certificate is unique, and should only be
used by one client system.
To generate a client certificate, follow the procedure described in the section
Generating Self- Signed Certificates.
Converting Certificates into PKCS#12 Format
Client certificates created on the NetScaler are stored in PEM or DER format, and
need to be converted to PKCS#12 format before they are installed on the client
system.
382 Installation and Configuration Guide - Volume 1
For details on converting a certificate from PEM or DER format to PKCS#12
format, refer to the section Exporting SSL Certificates.
Configuring Client Certificate-Based
Authentication on the NetScaler
By default, client authentication is disabled on the NetScaler. The procedure
described in this section illustrates how to configure client authentication.
You can configure the NetScaler to continue with SSL handshake even if the
certificate is old, corrupt, or absent. To do this, you need to configure an optional
client certificate check. However, if you set the client certificate check option to
Mandatory, the NetScaler terminates SSL handshake if the SSL client provides an
invalid certificate.
Before changing the client certificate check to Optional, be sure to define proper
access control policies.
Note: This command does not enable client authentication globally for all SSL
virtual servers.
To enable client certificate-based authentication on the NetScaler
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Select the virtual server for which you want to configure client certificate-
based authentication, then click Open.
3. Click the SSL Settings tab, then click SSL Parameters. The Configure
SSL Params dialog box appears.
4. In the Others group, select the Client Authentication check box.
5. Under Client Certificate, click Mandatory.
Note: To configure optional client authentication, select Optional in step 5
above.
6. Click OK, and in the Configure Virtual Server (SSL Offload) dialog box,
click OK. The virtual server is now configured for client authentication.
To enable client certificate-based authentication on the NetScaler using the
NetScaler command line
At the NetScaler command prompt, type:
Chapter 6 Secure Sockets Layer (SSL) Acceleration 383
set ssl vserver Vserver-SSL-1 -clientAuth ENABLED -clientCert
MANDATORY
Binding a CA Certificate to the Virtual Server
The client certificate used for client authentication must be issued by a CA
certificate present on the NetScaler. This certificate should be bound to the virtual
server on the NetScaler that will carry out client authentication.
You must bind the CA certificate to an SSL virtual server in such a way that the
NetScaler can form a complete certificate chain when it verifies the client
certificate. Otherwise, certificate chain formation fails and the client is denied
access even if its certificate is valid.
You can bind CA certificates to the SSL virtual server in any order. The NetScaler
forms the proper order during client certificate verification
The following illustration shows an SSL virtual server with three CA certificates
bound to it: Cert-CA_A, Cert-CA-B, and the root CA. In the figure, Cert-CA_A
is issued by Cert-CA-B, and Cert-CA-B is issued by the root CA.
During client authentication, the client certificate issued by Cert-CA-A, or Cert-
CA-B, or the root CA is properly verified. .
Complete Certificate Chain: All Certificates Bound
To bind the CA certificate to the virtual server, follow the procedure described in
the section Binding an SSL Certificate Key Pair to the Virtual Server.
Repeat this procedure to bind an additional CA certificate or root CA certificate
to the SSL virtual server.
384 Installation and Configuration Guide - Volume 1
To create a chain of certificates on the NetScaler, refer to the section Creating a
Chain of Certificates.
Installing Client Certificates in the Client Browser
The client certificate that you generated and converted to PKCS#12 format in the
foregoing procedures should be installed in the client browser that will be used to
access the secure server. During the SSL handshake, the browser displays a
dialog box where you can select the client certificate to use for client
authentication
To install a client certificate in Internet Explorer
1. Transfer the PKCS#12 converted client certificate to the client computer.
2. Launch Internet Explorer and navigate to Tools > Internet Options. The
Internet Options dialog box appears.
3. Click the Content tab, then in the Certificates group, click Certificates.
The Certificates dialog box appears.
4. Under Intended Purpose, select Client Authentication.
5. Click the Personal tab, then click the Import button. The Certificate
Import Wizard appears.
6. Follow the instructions in the Certificate Import Wizard. The client
certificate you imported appears in the list of Personal certificates.
7. Click Close, and in the Internet Options window, click OK.
To install a client certificate in Mozilla Firefox
1. Transfer the PKCS#12 converted client certificate to the client computer.
2. Launch the Firefox browser and navigate to Tools > Options. The Options
dialog box appears.
3. Click the Advanced icon, then click the Encryption tab.
4. In the Certificates group, click the View Certificates button. The
Certificate Manager dialog box appears.
5. Click the Your Certificates tab, then click the Import button. The
Windows Explorer appears.
6. Select the client certificate, then click Open. The imported client certificate
appears in the Your Certificates list.
7. Click OK. The client certificate is now installed in the Mozilla Firefox
browser.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 385
Managing Server Authentication
By default, the NetScaler will not authenticate the Web server's certificate. It is
assumed that the Web server's certificate is trusted by the NetScaler that performs
SSL acceleration on behalf of the Web server.
However, in certain SSL deployments where data is encrypted end-to-end using
SSL, you can authenticate the server. In such a situation, the NetScaler becomes
the SSL client and carries out a secure transaction with the SSL server.
To enable server authentication, you should bind the CA certificate that signed
the server's certificate to the SSL service on the NetScaler as a CA.
The following procedure describes the steps to enable server authentication on
the service Service-SSL-1 and then bind the CA certificate Cert-CA-1 to the
service as a CA certificate.
To enable server certificate authentication
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Select the service for which you want to enable server authentication for,
for example, Service-SSL-1, then click Open. The Configure Service
dialog box appears.
3. Click the SSL Settings tab, then click SSL Parameters. The Configure
SSL Params dialog box appears.
4. In the Others group, select the Server Authentication check box.
5. Click OK. Server authentication is now enabled for the service.
To enable server certificate authentication using the NetScaler command
line
At the NetScaler command prompt, type:
set ssl service Service-SSL-1 -serverAuth ENABLED
To bind the CA certificate to the service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Select the service for which you want to enable server authentication, for
example, Service-SSL-1, then click Open. The Configure Service dialog
box appears.
3. Under Available Certificates, select the CA certificate you want to bind,
for example Cert-CA-1, then click Add as CA.
4. Click OK. The CA certificate is now bound to the SSL service.
386 Installation and Configuration Guide - Volume 1
To bind the CA certificate to the service using the NetScaler command line
At the NetScaler command prompt, type:
bind ssl service Service-SSL-1 -certkeyName Cert-CA-1
Managing Certificate Revocation Lists
A certificate issued by a CA typically remains valid until its expiration date.
However, in some circumstances, the CA may revoke the issued certificate before
the expiration date (for example, when an owner's private key is compromised, a
company's or individual's name changes, or the association between the subject
and the CA changes).
The CA releases a Certificate Revocation List (CRL) identifying invalid
certificates by serial number and issuer. CRLs play an important role in client
authentication. In the absence of a CRL, client certificates revoked before their
expiration dates would pass the authentication check. CRLs prevent this is from
happening.
Certificate authorities issue CRLs on a regular basis. You can configure the
NetScaler to use a CRL to block client requests that present invalid certificates.
Note: By default, CRLs are stored in the /var/netscaler/ssl directory on the
NetScaler.
Configuring an Existing CRL on the NetScaler
Ensure that the CRL file is present in the local storage NetScaler (HDD). In the
case of an HA setup, the CRL file must be present on both NetScalers, and the
directory path should be the same on both NetScalers
To add a CRL on the NetScaler
1. In the left pane, expand SSL and click CRL. The CRL page appears in the
right pane.
2. In the CRL Name text box, type the name of the CRL being added, for
example, CRL-1.
3. In the CRL File text box, type the name of the CRL file being added, for
example, SSL_CRL.pem.
Note: To select an existing file on the NetScaler, click the Browse button
and navigate to the required file.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 387
4. Select the radio button next to the format of the CRL file being added, for
example, select PEM.
5. Under CA Certificate, select the CA certificate next to the CRL file.
Note: The CA certificate should be installed before loading the CRL.
To add a CRL on the NetScaler using the command line
At the NetScaler command prompt, type:
add ssl crl CRL-1 SSL_CRL.pem -inform PEM
Configuring CRL Refresh Parameters
The NetScaler can refresh CRLs from a Web location or an LDAP directory. The
NetScaler will fetch the CRL from the specified location and update its database.
To configure CRL refresh on the NetScaler, use the parameters in the following
table.
Parameter Description
Method The CRL refresh method.
Binary Ensure that the CRL file is transferred using the binary
mode.
Server IP The IP address of the LDAP server.
Port The port number used by the LDAP or the HTTP
server.
URL The URL of the CRL file on the HTTP server used for
CRL refresh.
This parameter is only used for CRL refresh with the
HTTP method.
Base DN The path to the CRL file on the LDAP server.
Scope Specifies the level below the Base DN where the CRL
file should be searched.
If the scope is set to One, the CRL file search is carried
out upto one level lower than the Base DN in the LDAP
file structure.
If the scope is set to Base, the CRL file search is carried
out at the level of the Base DN in the LDAP file
structure.
Bind DN The user name for authentication on the LDAP server.
This is used if there are user accounts created on the
LDAP server.
388 Installation and Configuration Guide - Volume 1
When you specify refresh parameters and an LDAP server, the CRL does not
have to be present on the local hard disk drive at the time you execute the
command. The first refresh will store a copy on the local hard disk drive, in the
path specified by the CRL File parameter. The default path for storing the CRL is
/var/netscaler/ssl.
The following procedure describes the steps to refresh the CRL file from the
LDAP server 10.217.130.2, listening on port 389. The CRL file is searched at the
Base DN "dc=flyers, dc=ctxs."
To configure CRL auto refresh using LDAP
1. In the left pane, expand SSL, then click CRL. The CRL page appears in
the right pane.
2. Select the configured CRL for which you want to update refresh
parameters, then click Open. The Configure CRL dialog box appears.
3. Select the Enable CRL Auto Refresh check box.
4. In the CRL Auto Refresh Parameters group, under Method, select
LDAP.
5. In the Server IP field, type 10.217.130.2
6. In the Port text box, type 389.
7. In the Base DN text box, type “dc=flyers, dc=ctxs”.
8. Under Interval, select NOW.
Note: If the new CRL has been refreshed in the external repository before
its actual update time as specified by the LastUpdate field of the CRL, you
should immediately refresh the CRL on the NetScaler.
9. Click Create. The CRL for which you configured refresh parameters
appears in the CRL page.
To configure CRL auto refresh using LDAP using the NetScaler command
line
At the NetScaler command prompt, type:
set ssl crl CRL-1 -refresh ENABLED -server 10.217.130.2 -method
LDAP -port 389 -baseDN “dc=flyers, dc=ctxs” -interval NOW
Password The password corresponding to the Bind DN for
authentication on the LDAP server.
Parameter Description
Chapter 6 Secure Sockets Layer (SSL) Acceleration 389
The following procedure describes the steps to refresh a CRL file from an HTTP
server listening on port 80 at the location specified by the URL http://
10.102.19.190/CA1.crl
To configure CRL auto refresh using HTTP
1. In the left pane, expand SSL, then click CRL. The CRL page appears in
the right pane.
2. Select the configured CRL for which you want to update refresh
parameters, then click Open. The Configure CRL dialog box appears.
3. Select the Enable CRL Auto Refresh check box.
4. In the CRL Auto Refresh Parameters group, under Method, select
HTTP.
5. In the URL text box, type http://10.102.19.190/CA1.crl.
6. In the Port text box, type 80.
7. Under Interval, select NOW.
Note: If the new CRL has been refreshed in the external repository before
its actual update time as specified by the LastUpdate field of the CRL, you
should refresh it immediately on the NetScaler.
8. Click Create. The CRL for which you configured refresh parameters
appears in the CRL page.
To configure CRL auto refresh using HTTP using the NetScaler command
line
At the NetScaler command prompt, type:
set ssl crl CRL-1 -refresh ENABLED -url http://10.102.19.190/
CA1.crl -method HTTP -port 80 -interval NOW
Synchronizing CRLs
When the NetScaler performs SSL acceleration, it uses the most recently
distributed CRL to prevent clients with revoked certificates from accessing secure
resources.
If CRLs are updated often, the NetScaler needs an automated mechanism to fetch
the latest CRLs from the repository. You can configure the NetScaler to update
CRLs automatically at a specified refresh interval or time
390 Installation and Configuration Guide - Volume 1
The NetScaler maintains an internal list of CRLs that need to be updated at
regular intervals. At these specified intervals, it scans the list for CRLs that need
to be updated, then connects to the remote LDAP server or HTTP server and
retrieves the latest CRLs. It then replaces the local CRL list with the new CRLs.
Note: If the initial CRL refresh fails, all client-authentication connections with
the same issuer as the CRL are rejected as REVOKED until the CRL is
successfully refreshed.
To synchronize the CRL at a specific time, use the parameters in the following
table.
Note: If you provide an invalid number for the day of the month or day of the
week, the NetScaler adjusts it to the nearest valid value and performs the refresh
on that day.
You can set the exact time of day the CRL is refreshed, using the parameters
under the Time group. Specify time in 24-hour format (HH:MM).
Creating a CRL on the NetScaler
You can revoke and create CRLs for certificates you have created, or for
certificates whose CA certificate you own. To create a CRL on the NetScaler, you
need to perform the following tasks:
Interval Days
Monthly Set the day of the month the CRL refresh will be done.
For example, if you want the refresh to be done on the 15th of
every month, under Days, select 15.
Weekly Set the day of the week the CRL refresh will be done. (Sunday=1,
Monday=2, Tuesday=3, Wednesday=4, Thursday=5, Friday=6
and Saturday=7)
For example, if you want the refresh to be done on tuesday every
week, under Days, select 3.
Daily Set the Daily argument if you want the CRL refresh to be carried
out every day.
Now Use the Now argument when a CRL has been refreshed in the
LDAP repository before the update time specified in the
LastUpdate field of the CRL. The Now argument forces an
immediate refresh of the CRL on the NetScaler
Never Specify the number of days after which the CRL should be
refreshed.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 391
• Revoke invalid certificates
• Create a CRL
The NetScaler stores the serial number of revoked certificates in an index file.
The file is updated for each certificate that is revoked by the CA. The NetScaler
creates the index file the first time you revoke a certificate.
To revoke a certificate and create a CRL, use the parameters in the following
table.
The following procedure describes the steps to revoke two invalid certificates
Cert-Invalid-1 and Cert-Invalid-2 created by the CA Cert-CA-1 whose
corresponding private key is Key-CA-1.
The serial numbers for these certificates will be stored in the index file File-
Index-1. The index file is then used to create a CRL, CRL-1.
To revoke an invalid certificate
1. In the left pane expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
Parameter Description
CA Certificate File
Name
The name of the CA certificate that signed the certificate being
revoked.
In case of CRL creation, this field specifies the name of the CA
certificate that is creating the CRL.
CA Key Name The name of the private key corresponding to the CA certificate.
CA Key Password The password used to encrypt the CA private key, if any.
Index File Name The name of the index file that stores the serial number of all
revoked certificates.
This file is created on the NetScaler (if not present) when the first
certificate is revoked.
Choose Operation The operation to be performed.
Revoke Certificate - Revokes the specified invalid certificate on
the NetScaler.
Generate CRL - Generates a CRL for all revoked certificates on
the NetScaler.
Certificate File Name The name of the invalid certificate to be revoked. The certificate
is revoked only if it was created using the CA certificate specified
in the CA Certificate File Name field.
CRL File Name The name of the CRL file being created. This file is specific to the
CA certificate named in the CA Certificate File Name field. This
file only contains details of certificates issued by the specified CA
certificate.
392 Installation and Configuration Guide - Volume 1
2. Click CRL Management. The CRL Management dialog box appears.
3. In the CA Certificate File Name text box, type Cert-CA-1.
4. In the CA Key File Name text box, type Key-CA-1.
5. In the Index File Name text box, type File-Index-1.
6. Under Choose Operation, select Revoke Certificate.
7. In the Certificate File Name text box, type Cert-Invalid-1.
8. Click Create. The invalid certificate Cert-Invalid-1 is now revoked and its
serial number updated in the specified index file.
Repeat this procedure for the second certificate, Cert-Invalid-2.
To revoke a certificate using the NetScaler command line
At the NetScaler command prompt, type:
create ssl crl Cert-CA-1 Key-CA-1 File-Index-1 -revoke Cert-
Invalid-1
To create a CRL
1. In the left pane expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click CRL Management. The CRL Management dialog box appears.
3. In the CA Certificate File Name text box, type Cert-CA-1.
4. In the CA Key File Name text box, type Key-CA-1.
5. In the Index File Name text box, type File-Index-1.
6. Under Choose Operation, select Generate CRL.
7. In the CRL File Name text box, type CRL-1.
8. Click Create. The CRL CRL-1 is created on the NetScaler.
To create a CRL using the NetScaler command line
At the NetScaler command prompt, type:
create ssl crl Cert-CA-1 Key-CA-1 File-Index-1 -genCRL CRL-1
Customizing the SSL Configuration
You can use SSL virtual servers and SSL services independently for different
deployments. This section describes the procedures to customize the configured
virtual servers or services in such deployments.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 393
Note: The customizations described in this section are for an SSL virtual server,
or an individual SSL service, but not for global SSL system settings.
To customize the SSL configuration for an SSL virtual server, first launch the
Configure SSL Params dialog box as described below
To customize the SSL configuration for an SSL virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Select the virtual server for which you want to customize SSL settings, for
example, Vserver-SSL-1, then click Open. The Configure Virtual Server
(SSL Offload) dialog box appears.
3. Click the SSL Settings tab, then click SSL Parameters. The Configure
SSL Params dialog box appears.
To customize the SSL configuration for an SSL virtual server using the
NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1
To customize the SSL configuration for an SSL service, first launch the
Configure SSL Params dialog box as described below
To customize the SSL configuration for an SSL service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Select the service for which you want to customize SSL settings, for
example, Service-SSL-1, then click Open. The Configure Service dialog
box appears.
3. Click the SSL Settings tab, then click SSL Parameters. The Configure
SSL Params dialog box appears.
To customize the SSL configuration for an SSL service using the NetScaler
command line
At the NetScaler command prompt, type:
set ssl service Service-SSL-1
394 Installation and Configuration Guide - Volume 1
Configuring Diffe-Hellman (DH) Parameters
The DH key exchange feature enables support for Diffie-Hellman (DH) key
exchange for an SSL virtual server or SSL service on the NetScaler. DH key
exchange is disabled by default. You must enable this feature if you need to
support ciphers that use DH as the key exchange algorithm
To configure DH key exchange, use the parameters in the following
table.
In the following example, the DH parameters are configured to refresh the DH
key after every 1000 sessions.
To configure DH Parameters
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the DH Param group, select the DH check box.
3. In the Refresh Count text box, type 1000.
4. Click OK. The DH parameters are now configured to refresh the DH key
after every 1000 sessions.
To configure DH Parameters using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -dh ENABLED -dhCount 1000
Parameter Description
DH Enable or disable DH key exchange support
Refresh Count The refresh count for regeneration of the DH private-
public key pair. The default value is zero (0), which
specifies infinite use (no refresh).
If the refresh count is set, the DH public and private key
pairs are re-generated after the usage count for the key
pair reaches the configured refresh count.
The refresh count is a positive integer value whose
value can either be 0 or any other number greater than
500..
File Path The complete path name of the DH parameter file to be
installed. The default path is /nsconfig/ssl
Chapter 6 Secure Sockets Layer (SSL) Acceleration 395
Configuring Ephemeral RSA
This section describes the procedures to enable support for ephemeral
RSA key exchange for an SSL virtual server or SSL service. By
default, this feature is enabled, with the refresh count set to zero
(infinite use).
Ephemeral RSA allows export clients to communicate with the secure
server even if the server certificate does not support export clients
(1024-bit certificate).
If you want to prevent export clients from accessing the secure Web
object and/or resource, you need to disable the ephemeral RSA key
exchange feature.
To configure Ephemeral RSA, use the parameters in the following
table.
The following procedure describes the steps to configure the ephemeral RSA
parameters to refresh the eRSA key after every 1000 sessions.
To configure Ephemeral RSA
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the Ephemeral RSA group, select the eRSA check box.
3. In the Refresh Count text box, type 1000.
4. Click OK. The ephemeral RSA parameters are now configured to refresh
the eRSA key after every 1000 sessions.
To configure Ephemeral RSA using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -eRSA ENABLED -eRSACount 1000
Parameter Description
eRSA Enable or disable the ephemeral RSA feature.
Refresh Count The refresh count for regeneration of the RSA private-
public key pair. The default value is zero (0), which
specifies infinite use (no refresh).
If the refresh count is set, the eRSA key is re-generated
after the usage count for the key pair reaches the
configured refresh count.
The refresh count is a positive integer whose value can
either be 0 or any other number greater than 500.
396 Installation and Configuration Guide - Volume 1
Configuring Session Reuse
For SSL transactions, establishing the initial SSL handshake requires
CPU-intensive public key encryption operations. Most handshake
operations are associated with the exchange of the SSL session key
(client key exchange message).
Session reuse is enabled by default. Enabling session reuse reduces the
server load, improves response time, and increases the number of SSL
transactions per second (TPS) that can be supported by the server. With
session reuse enabled, session key exchange is avoided for session
resumption requests received from the client.
To configure session reuse, use the parameters as in the following table
The following procedure describes the steps to reuse SSL sessions for 600
seconds before clearing them from the cache.
To configure session reuse
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the Session group, select the Reuse check box.
3. In the Timeout text box, type 600.
4. Click OK. The NetScaler is now configured to reuse SSL sessions for 600
seconds.
To configure session reuse using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -sessReuse ENABLED -sessTimeout 600
Configuring Cipher Redirection
During SSL handshake, the SSL client (browser) announces the suite of ciphers
that it supports, in the configured order of cipher preference. The SSL server then
selects from the cipher list a cipher that matches its own list of configured
ciphers.
Parameter Description
Reuse Enable or disable SSL reuse.
Timeout The timeout value in seconds. After the timeout passes,
the session is cleared from the cache.
The value is a positive integer whose default value is
300 seconds.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 397
If the ciphers announced by the client do not match those configured on the SSL
server, the SSL handshake fails, and the failure is announced by a cryptic error
message displayed in the browser. These messages rarely mention the exact cause
of the error.
With cipher redirection, you can configure an SSL virtual server to deliver
accurate, meaningful error messages when SSL handshake fails. When SSL
handshake fails, the NetScaler redirects the user to a previously configured URL,
or displays an internally generated error page if no URL is configured.
Note: You can configure cipher redirection only for SSL virtual servers, not for
SSL services.
To configure cipher redirection, use the parameters in the following
table.
The following procedure describes the steps to redirect the client to http://
redirectURL in case of a cipher suite mismatch.
To configure cipher redirection
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the Cipher Redirect group, select the Enable check box.
3. In the Redirect URL text box, type http://redirectURL
4. Click OK. The NetScaler is now configured to redirect clients in case of a
cipher suite mismatch.
To configure cipher redirection using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -cipherRedirect ENABLED -cipherURL
http://redirectURL
Parameter Description
Enable Enable or disable the Cipher Redirect feature.
Redirect URL The URL where the client should be redirected in the
case of a cipher suite mismatch.
398 Installation and Configuration Guide - Volume 1
Configuring SSLv2 Redirection
During an SSL handshake, if the SSL protocol version supported by the
client is not acceptable to the server, the server displays a cryptic error
message. You can configure the server to display a precise error
message (user-configured or internally generated) advising the client
on the next action to be taken. Configuring the server to display this
message requires that you set up SSLv2 redirection.
The SSLv2 redirect feature is enabled by default (because the SSLv2
protocol is disabled by default for an SSL vserver/service).
To configure SSLv2 redirection, use the parameters in the following
table.
The following procedure describes the steps to redirect the client to http://
sslv2URL for clients that support only the SSLv2 protocol.
To configure SSLv2 redirection
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the SSLv2 Redirect group, select the Enable check box.
3. In the SSLv2 URL text box, type http://sslv2URL
4. Click OK. The NetScaler is now configured to redirect clients that only
support the SSLv2 protocol.
To configure SSLv2 redirection using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -sslv2Redirect ENABLED -sslv2URL
http://sslv2URL
Parameter Description
Enable Enable or disable the SSLv2 redirect.feature.
SSLv2 URL The URL where the client is redirected in case of a
protocol mismatch.
The target IP address must not be the same as the SSL
VIP for which the SSLv2 redirect feature is enabled, or
the client will go into an infinite loop of redirects.
For example, if you have configured SSLv2 redirection
for the secure domain https://www.foobar.com, you
should not have the redirect URL configured as:
https://www.foobar.com/error.html
The preferred way is to redirect to a dummy SSL VIP
or an HTTP VIP.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 399
Configuring SSL Protocol Settings
The NetScaler supports the SSLv2, SSLv3, and TLSv1 protocols. Each of these
can be set on the NetScaler as required.
To configure SSL protocol settings, use the parameters in the following
table.
The following procedure describes the steps to configure support for the TLSv1
protocol.
To configure TLSv1 protocol support
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the SSL Protocol group, select the TLSv1 check box.
3. Click OK.The NetScaler now supports the TLSv1 protocol.
To configure TLSv1 protocol support using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -tls1 ENABLED
Configuring Advanced SSL Settings
To configure advanced SSL settings,use the parameters in the
following table
Parameter Description
SSLv3 Enable or disable support for the SSLv3 protocol
TLSv1 Enable or disable support for the TLSv1 protocol
SSLv2 Enable or disable support for the SSLv2 protocol
Parameter Description
400 Installation and Configuration Guide - Volume 1
The following procedure describes the steps to enable SSL redirect on the
NetScaler
To enable SSL redirect
1. Launch the Customize SSL Params dialog box, as described earlier.
2. In the Others group, select the SSL Redirect check box.
3. Click OK. SSL redirect is now enabled on the NetScaler.
To enable SSL redirect using the NetScaler command line
At the NetScaler command prompt, type:
set ssl vserver Vserver-SSL-1 -sslRedirect ENABLED
SSL Redirect This function enables or disables SSL (HTTPS)
redirects for the SSL virtual server. This is required so
that messages from the server are redirected properly.
The redirect message from the server provides the new
location for the moved object. This is contained in the
Location HTTP header field. For example, Location:
http://www.moved.org/here.html.
For an SSL session, if the client browser receives this
message, the browser tries to connect to the new
location. This breaks the secure SSL session, because
the object has moved from a secure site (https://) to an
unsecured one (http://). Generally, browsers display a
warning message on the screen and prompt the user to
continue or disconnect.
When enabled, the SSL redirect function automatically
converts all such http:// redirect messages to https://.
This does not break the client SSL session.
SSL Redirect Port Rewrite Insert into the SSL header, the port on which the port
rewrite is being performed
Client Authentication Enable or disable client certificate-based
authentication.
Client Certificate Select whether the client certificate check is optional or
mandatory.
Server Authentication Enable or disable back-end server authentication. This
setting is applicable to SSL services only.
Clear Text Port This option is used in the SSL Transparent mode (*:443
SSL VIP) to set the clear text data port. The NetScaler
uses this port to send decrypted clear text data to the
back-end Web servers.
The clear text data port can only be set on SSL virtual
servers. The data port is valid only for wildcard IP (*)-
based SSL offloading.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 401
Managing SSL Actions and Policies
SSL actions and policies are used to configure vSSL customizations such as SSL
insertions, support for outlook Web access, and per-directory client
authentication. This section describes the procedures involved in creating these
SSL actions and policies and binding them to configured SSL virtual servers and
SSL transparent services.
Creating SSL Actions
To create an SSL action, you need to launch the Create SSL Action dialog box,
then create specific SSL actions using the procedures in the sections below.
To launch the Create SSL Action dialog box
1. In the left pane, expand SSL, then click Policies. The SSL page appears in
the right pane.
2. Click the Actions tab. The SSL Actions page appears.
3. Click Add. The Create SSL Action dialog box appears.
To launch the Create SSL Action dialog box using the Netscaler command
line
At the NetScaler command prompt, type:
add ssl action
Configuring Per-Directory Client Authentication
You can configure client-side authentication on a per-directory basis. In such a
configuration, the client authentication is not carried out as part of the initial SSL
handshake. Instead, client authentication is configured as an SSL action, and
bound to the SSL virtual server or service using the policy infrastructure.
In the event of a policy match, SSL handshake is initiated and client
authentication is carried out.
The following procedure describes the steps to create an SSL action Action-SSL-
ClientAuth to configure per-directory client authentication.
To configure per directory client authentication
1. Launch the Create SSL Action dialog box as described above.
2. In the Name text box, type Action-SSL-ClientAuth.
3. In the Client Authentication group, select Enabled.
4. Click Create, then click Close. The action Action-SSL-ClientAuth that you
created appears in the SSL Actions page.
402 Installation and Configuration Guide - Volume 1
To configure per directory client authenticatoin using the NetScaler
command line
At the NetScaler command prompt, type:
add ssl action -clientAuth DOCLIENTAUTH
Configuring Support for Outlook Web Access
If your system uses an Outlook Web-access (OWA) server, you must insert a
special header field, FRONT-END-HTTPS: ON, in HTTP requests directed to the
OWA servers. This is required for the OWA servers to generate URL links as
https:// instead of http://.
Note: You can only enable Outlook Web Access support for HTTP-based SSL
vservers and services. You can not apply it for TCP-based SSL vservers and
services.
The following procedure describes the steps to create an SSL action, Action-SSL-
OWA that enables support for outlook Web access on the NetScaler.
To create an SSL action to enable OWA support
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-OWA.
3. In the Outlook Web Access group, select Enabled from the drop-down
list.
4. Click Create, then click Close. The action Action-SSL-OWA appears in
the SSL Actions page.
Note: Outlook Web Access support is applicable only for SSL virtual server
based configurations and transparent SSL service based configurations and not
for SSL configurations with backend encryption.
To create an SSL action to enable OWA support using the NetScaler
command line
At the NetScaler command prompt, type:
add ssl action -OWASupport ENABLED
Chapter 6 Secure Sockets Layer (SSL) Acceleration 403
Configuring Insertion
Because the NetScaler offloads all SSL-related processing from the servers,
the servers only receive HTTP traffic. The NetScaler receives and processes
all SSL data and does not pass it to the servers.
Under certain circumstances, a user may want certain SSL information to be
passed on to the servers. For example, security audits of recent SSL transactions
require the client subject name (contained in an X509 certificate) to be logged at
the server. This data is inserted into the HTTP header as a name-value pair and
sent to the server.
The entire client certificate can be inserted into the HTTP header, if required, or
only the specific fields from the certificate can be inserted, such as subject, issuer,
and so on.
Configuring Client Certificate Insertion
The client certificate can be inserted in the HTTP header of the request being sent
to the Web server. The certificate is inserted in ASCII (PEM) format. You can
enable Client Certificate Insertion only for HTTP-based SSL vservers and
services. You cannot apply it to TCP-based SSL vservers and services
Note: Before client certificate insertion can be carried out, client authentication
must be enabled.
The following procedure describes the steps to create an SSL action Action-SSL-
ClientCert that inserts a new header X-CLIENT-CERT into the HTTP header
whose value will contain the entire client certificate.
To insert the client certificate
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-ClientCert.
3. In the Client Certificate group, select Enabled from the drop-down list.
4. In the Certificate Tag text box, type X-CLIENT-CERT.
5. Click Create, then click Close. The Action-SSL-ClientCert action appears
in the SSL Actions page.
To insert the client certificate using the NetScaler command line
At the NetScaler command prompt, type:
add ssl action Action-SSL-ClientCert -clientCert ENABLED -
clientHeader “X-CLIENT-CERT”
404 Installation and Configuration Guide - Volume 1
Configuring Client Certificate Serial Number Insertion
You can configure the NetScaler to insert the client certificate's serial number in
the HTTP header of requests being sent to the Web server.You can only enable
this insertion for HTTP-based SSL vservers and services. You can not apply it for
TCP-based SSL vservers and services.
Note: Client authentication must be enabled before client certificate serial
number insertion can be carried out.
The following procedure describes the steps to create an SSL action Action-SSL-
SerialNumber that inserts a new header X-SERIAL-NUMBER into the HTTP
header whose value contains the client certificate’s serial number.
To insert the client certificate serial number
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-SerialNumber.
3. In the Client Certificate Serial Number group, select Enabled from the
drop down list.
4. In the Serial Number Tag text box, type X-SERIAL-NUMBER.
5. Click Create, then click Close. The action Action-SSL-SerialNumber
appears in the SSL Actions page.
To insert the client certificate serial number using the NetScaler command
line
At the NetScaler command prompt, type:
add ssl action Action-SSL-SerialNumber -clientcertSerialNumber
ENABLED -certSerialHeader “X-SERIAL-NUMBER”
Client Certificate Subject Name (DN) Insertion
You can configure the NetScaler to insert the client certificate's subject name
(also known as Domain Name [DN]) in the HTTP header of the request being
sent to the Web server. You can enable this insertion only for HTTP-based SSL
vservers and services. You cannot apply it to TCP-based SSL vservers and
services.
Note: Client authentication must be enabled before client certificate subject
name insertion can be carried out.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 405
The following procedure describes the steps to create an SSL action Action-SSL-
SubName that will insert a new header X-SUBJ ECT-NAME into the HTTP
header whose value will contain the client certificate’s subject name.
To insert the client certificate subject name
1. Launch the Create SSL Action dialog box as described earlier.
2. In the Name text box, type Action-SSL-SubName.
3. In the Client Certificate Subject (DN) group, select Enabled from the
drop-down list.
4. In the Subject Tag text box, type X-SUBJ ECT-NAME.
5. Click Create, then click Close. The action Action-SSL-SubName appears
in the SSL Actions page.
To insert the client certificate subject name using the NetScaler command
line
At the NetScaler command prompt, type:
add ssl action Action-SSL-SubName -clientcertSubject ENABLED -
certSubjectHeader “X-SUBJECT-NAME”
Configuring Client Certificate Hash Insertion
You can configure the NetScaler to insert the client certificate's hash (signature)
in the HTTP header of the request being sent to the Web server. You can only
enable this insertion for HTTP-based SSL vservers and services. You cannot
apply it to TCP-based SSL vservers and services.
Note: Client authentication must be enabled before client certificate hash
insertion can be carried out.
The following procedure describes the steps to create an SSL action Action-SSL-
CertHash that will insert a new header X-CERT-HASH into the HTTP header
whose value contains the client certificate's hash value.
To insert the client certificate hash
1. Launch the Create SSL Action dialog bo,x as described earlier.
2. In the Name text box, type Action-SSL-CertHash.
3. In the Client Certificate Hash group, select Enabled from the drop-down
list.
4. In the Hash Tag text box, type X-CERT-HASH.
406 Installation and Configuration Guide - Volume 1
5. Click Create, then click Close. The action Action-SSL-CertHash appears
in the SSL Actions page.
To insert the client certificate hash using the NetScaler command line
At the NetScaler command prompt, type:
add ssl action Action-SSL-CertHash -clientcertHash ENABLED -
certHashHeader “X-CERT-HASH”
Configuring Client Certificate Issuer Insertion
You can configure the NetScaler to insert the client certificate’s issuer in the
HTTP header of the request being sent to the Web server. You can only enable
this insertion for HTTP-based SSL vservers and services. You cannot apply it for
other TCP-based SSL vservers and services.
Note: Client authentication must be enabled before client certificate issuer
insertion can be carried out.
The following procedure describes the steps to create an SSL action Action-SSL-
Issuer that inserts a new header X-ISSUER-NAME into the HTTP header whose
value contains the client certificate's issuer tag.
To insert the client certificate issuer tag
1. Launch the Create SSL Action dialog box as described earlier.
2. In the Name text box, type Action-SSL-Issuer.
3. In the Client Certificate Issuer group, select Enabled from the drop down
list.
4. In the Issuer Tag text box, type X-ISSUER-NAME.
5. Click Create, then click Close. The action Action-SSL-Issuer appears in
the SSL Actions page.
To insert the client certificate issuer tag using the NetScaler command line
At the NetScaler command prompt, type:
add ssl action Action-SSL-Issuer -clientCertIssuer ENABLED -
certIssuerHeader “X-ISSUER-NAME”
Chapter 6 Secure Sockets Layer (SSL) Acceleration 407
Configuring SSL Session ID Insertion
You can configure the NetScaler to insert the SSL session ID in the HTTP header
of the request being sent to the Web-server. You can only enable this insertion for
HTTP based SSL vservers and services. You cannot apply it for other TCP based
SSL vservers and services.
The following procedure describes the steps to create an SSL action Action-SSL-
SessionID is created which inserts a new header X-SESSION-ID into the HTTP
header whose value contains the SSL session ID of the client-side SSL session..
To insert the SSL session ID
1. Launch the Create SSL Action dialog box as described earlier.
2. In the Name text box, type Action-SSL-SessionID.
3. In the Session-ID group, select Enabled from the drop down list.
4. In the Session ID Tag text box, type X-SESSION-ID.
5. Click Create, then click Close. The action Action-SSL-SessionID appears
in the SSL Actions page.
To insert the SSL session ID using the NetScaler command line
At the NetScaler command prompt, type:
add ssl action Action-SSL-SessionID -sessionID ENABLED -
sessionIDHeader X-SESSION-ID
Configuring Cipher Suite Insertion
You can configure the NetScaler to insert the cipher suite name negotiated during
the SSL handshake into the HTTP header of the request being sent to the Web
server. The NetScaler will insert the Cipher-name, SSL protocol, the export/non-
export string, and cipher strength bit depending on the type of the browser
connecting to the SSL virtual server/service. For example, Cipher-Suite: RC4-
MD5 SSLv3 Non-Export 128-bit.
You can only enable this insertion for HTTP-based SSL vservers and services.
You cannot apply it for other TCP-based SSL vservers and services.
The following procedure describes the steps to create an SSL action Action-SSL-
Cipher that inserts a new header X-CIPHER-SUITE into the HTTP header whose
value contains the cipher suite negotiated during the SSL handshake.
To insert the cipher suite
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-Cipher.
3. In the Cipher Suite group, select Enabled from the drop-down list.
408 Installation and Configuration Guide - Volume 1
4. In the Cipher Tag text box, type X-CIPHER-SUITE.
5. Click Create, then click Close. The action Action-SSL-Cipher appears in
the SSL Actions page.
To insert the cipher suite using the NetScaler command line
At the NetScaler command prompt, type:
add ssl action Action-SSL-Cipher -cipher ENABLED -cipherHeader X-
CIPHER-SUITE
Configuring Client Certificate Not Before Date Insertion
You can configure the NetScaler to insert the client certificate’s not-before date in
the HTTP header of the request being sent to the Web server. You can only enable
this insertion for HTTP-based SSL vservers and services. You cannot apply it for
other TCP-based SSL vservers and services.
Note: Client authentication must be enabled before client certificate not-before
date insertion can be carried out.
The following procedure describes the steps to creat an SSL action Action-SSL-
NotBefore is created that inserts a new header X-NOT-BEFORE into the HTTP
header whose value contains the client certificate's not-before date.
To insert the client certificate not before date
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-NotBefore.
3. In the Client Certificate Not Before Date group, select Enabled from the
drop-down list.
4. In the Not Before Tag text box, type X-NOT-BEFORE.
5. Click Create, then click Close. The action Action-SSL-NotBefore appears
in the SSL Actions page.
To insert the client certificate not before date using the NetScaler command
line
At the NetScaler command prompt, type:
add ssl action Action-SSL-NotBefore -clientCertNotBefore ENABLED -
certNotBeforeHeader X-NOT-BEFORE
Chapter 6 Secure Sockets Layer (SSL) Acceleration 409
Configuring Client Certificate Not After Date Insertion
You can insert the client certificate’s not-after date in the HTTP header of the
request being sent to the Web server. You can only enable this insertion for
HTTP-based SSL vservers and services. You cannot apply it for other TCP-based
SSL vservers and services.
Note: Client authentication must be enabled before client certificate not-after
date insertion can be carried out.
The following procedure describes the steps to create an SSL action Action-SSL-
NotAfter is created that inserts a new header X-NOT-AFTER into the HTTP
header whose value contains the client certificate's not-after date.
To insert the client certificate not after date
1. Launch the Create SSL Action dialog box, as described earlier.
2. In the Name text box, type Action-SSL-NotAfter.
3. In the Client Certificate Not After Date group, select Enabled from the
drop-down list.
4. In the Not After Tag text box, type X-NOT-AFTER.
5. Click Create, then click Close. The action Action-SSL-NotAfter appears in
the SSL Actions page.
To insert the client certificate not after date using the NetScaler command
line
At the NetScaler command prompt, type:
add ssl action Action-SSL-NotAfter -clientCertNotAfter ENABLED -
certNotBeforeHeader X-NOT-AFTER
Creating SSL Policies
To create SSL policies, use the parameters in the following table.
Parameter Description
Name The name of the SSL policy. This is a mandatory
parameter and cannot be changed. The name must not
exceed 31 characters.
Rule / Expression The configured rule against which incoming traffic is
evaluated to decide whether the policy should be
triggered or not.
410 Installation and Configuration Guide - Volume 1
To create an SSL policy
1. In the left pane, expand SSL, then click Policies. The SSL page appears in
the right pane.
2. Click Add. The Create SSL Policy dialog box appears.
3. In the Name text box, type the name of the SSL Policy, for example,
Policy-SSL-1.
4. Under Request Action, select the configured SSL action that you want to
associate with this policy, for example, Action-SSL-1.
5. Under General Named Expressions, choose the built-in general
expression ns_true, then click Add Expression. The expression ns_true
appears in the Expression text box.
Note: The ns_true general expression applies the policy to all successful (200
OK) responses generated by the NetScaler. However, if you need to filter specific
responses, you can create policies with a higher level of detail. For information
on configuring granular policy expressions, see the "Policies and Expressions"
chapter.
Click OK, then click Close. The SSL policy that you created, Policy-SSL-1,
appears in the SSL Policies page.
To create an SSL policy using the NetScaler command line
At the NetScaler command prompt, type:
add ssl policy Policy-SSL-1 -rule ns_true -reqAction Action-SSL-1
Binding SSL Policies to a Virtual Server
The SSL policies that are configured on the NetScaler need to be bound to a
virtual server that intercepts traffic directed to the virtual server. 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.
The following procedure describes the steps to bind the SSL policy Policy-SSL-1,
configured in the previous section, to the SSL virtual server Vserver-SSL-1 on
the NetScaler.
Request Action The name of the action to be performed in the event of a
policy match. The SSL actions configured on the
NetScaler are listed in the Request Action drop-down
box.
Parameter Description
Chapter 6 Secure Sockets Layer (SSL) Acceleration 411
To bind an SSL policy to a vserver
1. In the left pane, expand SSL Offload and click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. From the list of virtual servers, select the virtual server that you want to
bind the responder policy to. For example, select Vserver-SSL-1, then
click Open. The Configure Virtual Server (SSL Offload) dialog box
appears.
3. Select the Policies tab. The policies configured on the NetScaler appear.
4. Select the check box next to Policy-SSL-1.
5. Click OK. The SSL policy Policy-SSL-1 is bound to the virtual server
Vserver-SSL-1.
To bind an SSL policy to a virtual server using the NetScaler command line
At the NetScaler command prompt, type:
bind ssl vserver Vserver-SSL-1 -policyName Policy-SSL-1
Note: You can bind SSL policies globally or to custom bind points on the
NetScaler. For more information on binding policies on the NetScaler, refer to the
“Policies and Expressions” chapter.
Configuring Some Commonly Used SSL Configurations
The SSL feature aims at ensuring that data transactions through the NetScaler
remain secure. This section describes common SSL configurations, and how to
customize the SSL feature for your own deployment.
Configuring SSL Offloading with End-to-End
Encryption
A simple SSL acceleration device terminates SSL traffic (HTTPS), decrypts the
SSL records, and forwards the clear text (HTTP) traffic to the back-end Web
servers. The clear text traffic is vulnerable to being spoofed, read, stolen, or
compromised by individuals who succeed in gaining access to the back-end
network devices or Web servers. The SSL acceleration feature provides end-to-
end security by re-encrypting the clear text data and using secure SSL sessions to
communicate with the back-end Web servers
412 Installation and Configuration Guide - Volume 1
The following figure illustrates end-to-end SSL encryption configured on the
NetScaler
End-to-end SSL encryption
When the NetScaler receives SSL traffic, it terminates the client's SSL session
and provides hardware acceleration for SSL session creation and data decryption
operations.
The data flow in a NetScaler configured for back-end encryption proceeds as
follows:
• The client connects to a secure site, (for example, https://
www.mysite.com ) configured on the NetScaler (the SSL VIP).
• When the sytem receives the HTTPS request, it decrypts the request and
applies layer 4-7 content switching techniques and load-balancing policies,
then selects the best back-end Web server to serve the request.
• The NetScaler opens an SSL session with the selected server.
• After establishing the SSL session, the NetScaler encrypts the client's
request and sends it securely via the SSL session to the Web server.
• The NetScaler decrypts all encrypted response packets from the Web
server, then re-encrypts the response data using the client-side SSL session
and sends it to the client.
The SSL session multiplexing technique reuses the existing SSL sessions with the
back-end Web servers, thus avoiding CPU-intensive key exchange (full
handshake) operations. This reduces the overall number of SSL sessions on the
server, while maintaining end-to-end security.
Note: For TCP traffic, follow the procedures given in the sections that follow,
but create SSL_TCP services instead of SSL services.
To configure SSL with end-to-end encryption, set the parameters as described in
the following sections.
The following procedure describes the steps to configure the SSL feature in a
basic SSL offload set up where an SSL virtual server Vserver-SSL-2 offloads
SSL traffic directed to two SSL services, Service-SSL-1 and Service-SSL-2.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 413
Adding SSL-based Services
The following procedure describes the steps to configure two SSL based services,
Service-SSL-1 and Service-SSL-2 with IP addresses 10.102.20.30 and
10.102.20.31, using port number 443
To add an SSL-based service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Click Add. The Create Service dialog box appears.
3. In the Service Name text box, type the name of the service being added, for
example, Service-SSL-1.
4. In the Server text box, type the IP address of the server to be associated
with this service, for example, 10.102.20.30.
Note: If the server has been configured already, under Server, select the
configured server to be associated with the service.
5. Under Protocol, select SSL.
Note: For TCP services, under Protocol, select SSL_TCP.
6. In the Port text box, type the port number for the SSL service to use, for
example, 443.
7. Click Create, then click Close. The SSL service you configured appears in
the Services page.
To create the second service, repeat the procedure, but use the service name
Service-SSL-2 and IP address 10.102.20.31.
To add an SSL-based service using the NetScaler command line
At the NetScaler command prompt, type:
add service Service-SSL-1 10.102.20.30 SSL 443
Adding an SSL-based Virtual Server
Follow the procedure in the section Adding an SSL-based Virtual Server to add a
virtual server Vserver-SSL-2 with an IP address of 10.102.10.20.
414 Installation and Configuration Guide - Volume 1
Binding the SSL Services to the Virtual Server
The following procedure describes the steps to bind the services Service-SSL-1
and Service-SSL-2 to the virtual server Vserver-SSL-2.
To bind a service to a virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Select the virtual server Vserver-SSL-2, then click Open. The Configure
Virtual Server (SSL Offload) dialog box appears.
3. Click the Services tab, then select the check boxes next to the services
Service-SSL-1 and Service-SSL-2.
4. Click OK. The services Service-SSL-1 and Service-SSL-2 are bound to the
virtual server Vserver-SSL-2.
To bind a service to a virtual server using the NetScaler command line
At the NetScaler command prompt, type:
bind lb vserver Vsever-SSL-2 Service-SSL-1
bind lb vserver Vserver-SSL-2 Service-SSL-2
Binding an SSL Certificate Key Pair to the Virtual Server
To bind an SSL certificate key pair to the virtual server Vserver-SSL-2, follow
the procedures described in the section Binding an SSL Certificate Key Pair to
the Virtual Server.
Configuring Transparent SSL Acceleration
In a transparent SSL acceleration setup, SSL clients access secure Web services
using the Web server's IP address. The NetScaler is transparent to the clients and
there is no need for a virtual IP address on the NetScaler that is different from the
server IP address.
Transparent SSL acceleration is useful for running multiple applications on the
server with the same public IP and also SSL acceleration without using an
additional public IP.
In this scenario, clients can access different applications using the server's public
IP address(es). The NetScaler offloads SSL traffic processing from the Web
server and sends either clear text or encrypted traffic (depending on the
configuration) to the back-end Web server. All other protocol traffic is transparent
to the NetScaler and is bridged to the back-end Web servers. Thus, other
applications running on the server are unaffected.
There are two modes of transparent SSL acceleration:
Chapter 6 Secure Sockets Layer (SSL) Acceleration 415
• Service-based transparent access, where the service type can be SSL or
SSL_TCP
• Virtual server-based transparent access with a wildcard IP address (*:443)
Note: SSL_TCP service is used for non-HTTPS services, for example SMTPS,
IMAPS, and so on.
Comparison of transparent SSL Accelaration Modes
The table below compares SSL service-based acceleration with wildcard IP-based
transparent SSL acceleration.
Configuring Service-based Transparent SSL
Acceleration
Enabling transparent SSL acceleration using SSL service mode causes an SSL or
SSL_TCP service to be configured with the IP address of the actual back-end
Web server. In this configuration, the NetScaler terminates and offloads all SSL
processing and sends clear text data to the back-end Web server.
The service-based mode allows detailed configuration control at the level of
individual services -- you can configure each service with a different certificate,
or with a different clear text port. You can also select individual services for SSL
acceleration.
SSL Service Based SSL VIP with Wildcard
IP
Configuration control level Individual service Web server farm
Number of back-end servers
supported
1server per service No limit
Nnumber of secure Web sites that
can be configured
No limit One secure Web site can be
configured if specific IP-
based SSL Vservers are not
configured.
In addition to the global
*:443 SSL Vserver, if
specific IP:443 SSL
Vservers are configured,
then these Vservers can be
part of different secure
domains.
Back-end encryption Not supported Supported
One-arm mode Not supported Not supported
Load balancing of back-end servers N/A Not supported
416 Installation and Configuration Guide - Volume 1
The following figure illustrates a sevice-based transparent SSL configuration..
Service-based transparent SSL acceleration
You can apply service-based transparent SSL acceleration to data that use
different protocols. Set the clear text port of the SSL service to the port on which
the clear text data transfer between the SSL service and the server will occur.
To configure service-based transparent SSL acceleration for secure HTTP-based
data, configure the parameters as described in the following sections.
The following procedure describes the steps to configure the SSL feature in a
service-based transparent SSL setup. An SSL service, Service-SSL-Transparent
is created that offloads SSL traffic directed to the Web server 192.168.1.100. The
clear text data between the SSL service and the Web server is transferred using
port 8080.
Enabling the SSL and Load Balancing Features
Follow the procedure given in the section Enabling the SSL Feature and enable
the SSL and Load Balancing features on the NetScaler.
Creating an SSL Service and Setting its Clear Text Port
Create an SSL service Service-SSL-Transparent with an IP address of
192.168.1.100 and set its clear text port to 8080.
The clear text port of the service should be set when the service is being created
to enable transparent SSL acceleration.
For details on creating SSL services on the NetScaler, refer to the section Adding
SSL-based Services.
Note: The following example sets the clear text port for HTTP-based data. To
set the clear text port for non-HTTP data, choose the appropriate protocol in the
corresponding steps of the procedure.
Binding an SSL Certificate to the Service
Because the encrypted data in this configuration needs to be decrypted by the
SSL service, you must bind an SSL certificate to the service and then use the
certificate for the SSL handshake.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 417
The following procedure describes the steps to bind the SSL certificate Certkey-1
to the SSL service Service-SSL-Transparent.
For instructions on creating a certificate key pair on the NetScaler, refer to the
section Adding a Certificate Key Pair.
To bind an SSL certificate to a SSL service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. From the list of configured services, select the service to which you want to
bind the certificate key pair. For example, select Service-SSL-
Transparent, then click Open. The Configure Service dialog box appears.
3. Select the SSL Settings tab. The configured certificate key pairs configured
on the NetScaler are listed in the Available area.
4. Select the certificate key pair that you want to bind to the service and click
Add. The certificate key pair appears in the Configured area.
5. Click OK. The certificate pair is bound to the SSL service.
To bind an SSL certificate to a SSL service using the NetScaler command
line
At the NetScaler command prompt, type:
bind certkey Service-SSL-Transparent Certkey-SSL-1 -service
Configuring a Virtual Server-based Acceleration with a
Wildcard IP Address (*:443)
When you enable global transparent SSL acceleration using an SSL virtual server,
an *: 443 ("any IP address and port number 443") virtual server is configured on
the NetScaler. The virtual server can use the SSL protocol for HTTP-based data,
or the SSL_TCP protocol for non-HTTP-based data.
The virtual server terminates and offloads all SSL processing and sends either
clear text or encrypted data to the back-end Web server, depending on the
configuration.
It is easy to configure an SSL virtual server in wildcard IP address mode, because
you can enable SSL acceleration for multiple servers that host secure content of a
Web site; to do so, simply add an *: 443 SSL/SSL_TCP virtual server to the
NetScaler, and bind the certificate for the secure Web site to this virtual server.
In this mode, a single-digital certificate is required for the entire secure Web site,
instead of one certificate per server. This results in significant cost savings on
SSL certificates and renewals. Wildcard IP address mode also enables centralized
certificate management
418 Installation and Configuration Guide - Volume 1
Configuring an SSL Virtual Server with a Wildcard IP Address
The following sections explain how to configure a wildcard SSL virtual server on
the NetScaler with the clear text port set to the TCP port of the Web servers to
which the clear text is to be sent. The NetScaler will terminate and offload all
SSL processing, and send clear text data to the Web servers on the port you have
configured as the clear text port.
The configured wildcard server will automatically learn the servers configured on
the NetScaler, therefore you do not need to configure services for a wildcard
virtual server.
To configure transparent virtual server-based SSL acceleration for secure HTTP-
based data, set the parameters as described in the following sections.
The following procedure describes the steps to configure a wild card virtual
server Vserver-SSL-WildCard with its clear text port set to 8080.
Enabling the SSL and Load Balancing Features
To enable the SSL and load balancing features on the NetScaler, follow the
procedure in the section Enabling the SSL Feature.
Configuring a Wildcard SSL Virtual Server
A wildcard (*:443) virtual server intercepts incoming traffic directed to any IP
address and port number 443.
The following procedure describes the steps to create a wild card virtual server
Vserver-SSL-WildCard on the NetScaler.
To configure a wildcard virtual server
1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL
Offload Virtual Servers page appears in the right pane.
2. Click Add. The Create Virtual Server (SSL Offload) dialog box appears.
3. In the Name text box, type the name of the virtual server to be created, for
example Vserver-SSL-WildCard.
4. In the IP Address text box, type *.
5. Under Protocol, select SSL.
6. In the Port text box, type the port number for the virtual server to use. For
example, type 443.
7. Click Create, then click Close. The virtual server you created appears in
the SSL Offload Virtual Servers page.
To configure a wildcard virtual server using the NetScaler command line
At the NetScaler command prompt, type:
Chapter 6 Secure Sockets Layer (SSL) Acceleration 419
add vserver Vserver-SSL-WildCard SSL * 443
Setting the Clear text Port for the Wildcard Virtual Server
Set the clear text port of the wildcard virtual server Vserver-SSL-WildCard to
8080.
To set the clear text port on an SSL virtual server, refer to the section Configuring
Advanced SSL Settings.
Note: This example describes the preocedure to set the clear text port for
HTTP-based data. To set the clear text port for non-HTTP data, substitute the
appropriate choices in the procedure.
Binding an SSL Certificate Key Pair to the Virtual Server
Follow the procedures in the section Binding an SSL Certificate Key Pair to the
Virtual Server to bind an SSL certificate key pair to the virtual server Vserver-
SSL-WildCard.
Configuring SSL VIP-based Transparent Access with
End-To-End Encryption
The following sections explain how to configure a wildcard SSL virtual server on
the NetScaler with no clear text port specified. The NetScaler will terminate and
offload all SSL processing and send the encrypted data to the Web servers on the
port configured on the wildcard virtual server, using a secure SSL session.
Note: In this scenario, the SSL acceleration feature runs at the back end using
the default configuration, with all 34 ciphers available.
To configure end-to-end encryption on a global transparent wildcard virtual
server, follow the procedure in the sectionConfiguring a Virtual Server-based
Acceleration with a Wildcard IP Address (*:443) but do not configure a clear text
port on the virtual server.
Configuring the SSL feature with HTTP on the
Front End and SSL on the Back-end.
In this setup, an HTTP virtual server is configured on the NetScaler with SSL
services bound to the virtual server. The NetScaler receives HTTP requests from
the client on the configured HTTP virtual server, encrypts the data received, and
sends the encrypted data to the Web servers using a secure SSL session.
420 Installation and Configuration Guide - Volume 1
This configuration is useful when you need complete end-to-end security and
interaction with certain devices that can communicate only in clear text (for
example, caching devices).
The following figure shows the configuration
HTTP on the front end and SSL on the back-end
The following sections describe the procedures to configure an HTTP virtual
server on the front end, with SSL services on the back end.
The following procedure describes the steps to configure an HTTP virtual server
Vserver-HTTP-1 with an IP address 192.168.1.100 running on port 80, and bind
to it two SSL services, Service-SSL-1 with IP address 192.168.10.20 and
Service-SSL-2 with IP address 192.168.10.30 to it.
Enabling the SSL and Load Balancing Features
Follow the procedure in the section Enabling the SSL Feature and enable the SSL
and Load Balancing features on the NetScaler.
Creating SSL Services
Create two SSL services Service-SSL-1 and Service-SSL-2 with IP addresses
192.168.10.20 and 192.168.10.30.
For a detailed explanation of creating SSL services on the NetScaler, refer to the
section Adding SSL-based Services.
Adding an HTTP Virtual Server
Create a load balancing HTTP virtual server Vserver-HTTP-1 with IP address
192.168.1.100 running on port 80.
To create a HTTP virtual server
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. Click Add. The Create Virtual Servers (Load Balancing) dialog box
appears.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 421
3. In the Name, IP Address, and Port text boxes, type Vserver-HTTP-1,
192.168.1.100, and 80.
4. Under Protocol, select HTTP.
5. Click Create and click Close. The vserver you created appears in the Load
Balancing Virtual Servers page.
To create a HTTP virtual server using the NetScaler command line
At the NetScaler command prompt, type:
add lb vserver Vserver-LB-1 HTTP 192.168.1.100 80
Binding SSL Services to the HTTP Virtual Server
The following procedure describes the steps to bind the SSL services Service-
SSL-1 and Service-SSL-2 to the virtual server Vserver-HTTP-1.
To bind a service to an HTTP virtual server
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. Select Vserver-HTTP-1 and click Open. The Configure Virtual Server
(Load Balancing) dialog box appears. The services appear in the Services
tab.
3. Select the Active check box next to Service-SSL-1 and click OK.The SSL
service is bound to the HTTP virtual server.
To bind a service to an HTTP virtual server using the NetScaler command
line
At the NetScaler command prompt, type:
bind lb vserver Vserver-HTTP-1 Service-SSL-1
Note: To bind the SSL service Service-SSL-2 to the virtual server, repeat the
procedure but in step 3, select the check box next to Service-SSL-2.
Configuring SSL Offloading with Other-TCP
Protocols
In addition to the HTTPS protocol, the NetScaler supports SSL acceleration for
other TCP-based application protocols. However, only simple requests and
response-based TCP application protocols are supported. Applications that insert
the server's IP address and port information in their payload are currently not
supported (for example, FTPS).
422 Installation and Configuration Guide - Volume 1
Note: The STARTTLS feature for SMTP is currently not supported.
Two modes are supported for SSL acceleration of Other-TCP protocols.
• SSL acceleration without end-to-end encryption
• SSL acceleration with end-to-end encryption
Configuring SSL_TCP Based Offloading
You can only configure SSL_TCP-based offloading if the SSL virtual server that
receives incoming traffic is of type SSL_TCP, and the services that it sends traffic
are of type TCP.
SSL_TCP-based offloading is required if you need to configure the NetScaler to
offload secure TCP-based traffic (such as SFTP) destined to a TCP-based server.
To configure SSL_TCP-based offloading, follow the procedure described in the
section Configuring an SSL Virtual Server for Basic SSL Offloading but create
TCP services instead of HTTP services, and create an SSL_TCP virtual server
instead of an SSL virtual server.
Configuring SSL_TCP Based Offloading with End-to-
End Encryption
You can only configure SSL_TCP-based offloading with end-to-end encryption if
the SSL virtual server that receives incoming traffic is of type SSL_TCP, and the
services that it sends traffic to are also of type SSL_TCP.
SSL_TCP-based offloading with end-to-end encryption is required if the
NetScaler must offload secure TCP-based traffic (such as SFTP) destined to a
TCP-based server.
To configure SSL_TCP-based offloading, follow the procedure described in the
section Configuring SSL Offloading with End-to-End Encryption but create an
SSL_TCP virtual server instead of an SSL virtual server.
Configuring End-to-End Encryption for TCP Based Data
The NetScaler can provide SSL acceleration with back-end encryption for non-
SSL TCP traffic arriving from the client. In this case, the client requests are
formatted as clear text, and the NetScaler forwards them to the appropriate TCP
server after encryption.
To configure end-to-end encryption for TCP-based data, follow the procedure
described in the section Configuring the SSL feature with HTTP on the Front End
and SSL on the Back-end. but create a TCP virtual server instead of an HTTP
virtual server.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 423
Configuring SSL Bridging
SSL bridge functionality allows all secure traffic to be transparently bridged
directly to the back-end Web server. The NetScaler does not accelerate this
traffic. In this scenario, the Web server must handle all SSL-related processing.
To configure SSL bridging, you need to enable the load balancing feature on the
NetScaler.
Note: It is advisable to use this configuration only if an acceleration unit (for
example, a PCI-based SSL accelerator card) is installed in the Web server to
handle the SSL processing overhead.
In an SSL bridge setup, the NetScaler is configured to load balance and maintain
server persistency for secure requests. Other features, such as content switching,
Sure ConnectTM, and cache redirection do not work, because the traffic passing
through the SSL accelerator is encrypted..
The following figure illustrates this configuration
NetScaler configured for SSL bridging
Because the NetScaler does not carry out any SSL processing in an SSL bridging
setup, there is no need for SSL certificates.
To configure SSL bridging, configure the parameters as described in the sections
that follow.
The sections that follow describe how to configure SSL bridging. The procedures
explain the steps to configure SSL bridging on a NetScaler with two
SSL_BRIDGE services (Service-SSL_Bridge-1 and Service-SSL_Bridge-2 with
IP addresses 192.168.1.100 and 192.168.1.101), and bind them to an
SSL_BRIDGE virtual server Vserver-SSL_Bridge-1, with IP address
192.168.1.10.
Enabling the Load Balancing Feature
You can find the load balancing feature under Basic Features on the Citrix
NetScaler.
424 Installation and Configuration Guide - Volume 1
To enable the load balacing feature
1. In the left pane, expand System, then click Settings. The Settings page
appears in the right pane.
2. In the Modes & Features group, click the Basic Features link. The
Configure Basic Features dialog box appears.
3. Select the Load Balancing check box, then click OK. When the Enable/
Disable Feature(s)? message appears, Click Yes.The Load Balancing
feature is enabled on the NetScaler.
To enable the load balacing feature using the NetScaler command line
At the NetScaler command prompt, type:
enable ns feature lb
Configuring SSL_BRIDGE Services
The following procedure describes the steps to create two SSL_BRIDGE services
Service-SSL_Bridge-1 and Service-SSL_Bridge-2 with IP addresses
192.168.1.100 and 192.168.1.101 respectively.
To create an SSL_BRIDGE service
1. In the left pane, expand SSL Offload, then click Services. The Services
page appears in the right pane.
2. Click Add. The Create Service dialog box appears.
3. In the Service Name, Server and Port text boxes, type Service-
SSL_Bridge-1, 192.168.1.100 and 443.
Note: If the server is already configured, under Server, select the
configured server to associated with the service.
4. Under Protocol, select SSL_BRIDGE.
5. Click Create, and click Close. The SSL_BRIDGE service you configured
appears in the Services page.
To create an SSL_BRIDGE service using the NetScaler command line
At the NetScaler command prompt, type:
add service Service-SSL_Bridge-1 192.168.1.100 SSL_BRIDGE 443
Note: To create the service Service-SSL_Bridge-2, repeat the procedure, but in
step 3, type Service-SSL_Bridge-2, 192.168.1.101 and 443 respectively.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 425
Configuring an SSL_BRIDGE Virtual Server
The following procedure describes steps to create an SSL_BRIDGE virtual server
Vserver-SSL_Bridge-1 with IP address 192.168.1.10.
To create an SSL_BRIDGE virtual server
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. Click Add. The Create Virtual Servers (Load Balancing) dialog box
appears.
3. In the Name, IP Address, and Port text boxes, type Vserver-SSL_Bridge-
1, 192.168.1.10, and 443.
4. Under Protocol select SSL_BRIDGE.
5. Click Create and click Close. The virtual server you created appears in the
Load Balancing Virtual Servers page.
To create an SSL_BRIDGE virtual server using the NetScaler command line
At the NetScaler command prompt, type:
add vserver Vserver-SSL_Bridge-1 SSL_BRIDGE 192.168.1.10 443
Binding Services to the Virtual Server
The following procedure describes the steps to bind the SSL_BRIDGE services
Service-SSL_Bridge-1 and Service-SSL_Bridge-2 to the virtual server Vserver-
SSL_Bridge-1.
To bind an SSL_BRIDGE service to an SSL_BRIDGE virtual server
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. Select Vserver-SSL_Bridge-1 and click Open. The Configure Virtual
Server (Load Balancing) dialog box appears and lists the configured
SSL_BRIDGE services appear in the Services tab.
Note: The services tab only shows services of type SSL_BRIDGE; no
other services configured on the NetScaler are listed..
3. Select the Active check box next to Service-SSL_Bridge-1 and click
OK.The SSL_BRIDGE service is bound to the SSL_BRIDGE virtual
server.
To bind an SSL_BRIDGE service to an SSL_BRIDGE virtual server using the
NetScaler command line
426 Installation and Configuration Guide - Volume 1
At the NetScaler command prompt, type:
bind lb vserver Vserver-SSL_Bridge-1 Sevice-SSL_Bridge-1
Note: To bind the SSL_BRIDGE service Service-SSL_Bridge-2 to the virtual
server, repeat the procedure, but in step 3 select the check box next to Service-
SSL_Bridge-2.
Configuring the SSL Feature for Common Used
Deployment Scenarios
The following section describes some common deployment scenarios for the SSL
feature. The values for various parameters (such as IP addresses, site names,
certificates, and so on) are specific to the lab network at Citrix.
Configuring an SSL Virtual Server for Load
Balancing
When the NetScaler receives a client request, it performs load balancing in the
following sequence
• The NetScaler chooses a Web server, based on the load balancing policies
you have configured.
• The request is then sent to the server IP address, based on the NetScaler's
mapped IP address.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 427
The example configuration discussed in the following sections illustrates a simple
load balancing SSL setup with two HTTP services bound to an SSL virtual server.
The load balancing policy type is the default (LEASTCONNECTION). The
following figure shows the topology of the setup.
SSL vserver used for load balancing
To configure load balancing on the NetScaler, you must first create an SSL-based
load balancing virtual server and two HTTP-based services, then bind the
services and an SSL certificate to the virtual server.
The following table lists the entities that you must configure to enable
load balancing on the NetScaler.
Enable the SSL and Load Balancing Features
For instructions to enable the SSL offloading and load balancing features on the
NetScaler, refer to the section Enabling the SSL Feature.
Entity Type Name Value
SSL Virtual Server Vserver-SSL-LB 192.168.1.10:443
HTTP Service Service-HTTP-1 192.168.1.100:80
Service-HTTP-2 192.168.1.101:80
SSL Certificate Certkey-1
428 Installation and Configuration Guide - Volume 1
Create HTTP Services
Create two HTTP services Service-HTTP-1 and Service-HTTP-2 with IP
addresses 192.168.1.100 and 192.168.1.101, and using port number 80.
For details on creating HTTP services, refer to the section Adding HTTP-based
Services.
Create an SSL Virtual Server
Create an SSL virtual server, Vserver-SSL-LB with IP address 192.168.1.10
running on port 443.
For details on creating an SSL virtual server, refer to the section Adding an SSL-
based Virtual Server.
Bind an SSL Certificate Key Pair to the Virtual Server
Bind the certkey Certkey-1 to the virtual server Vserver-SSL-LB.
For details on binding a certificate key pair to a virtual server, refer to the section
Binding an SSL Certificate Key Pair to the Virtual Server.
Bind the HTTP Services to the Virtual Server
Bind the HTTP services Service-HTTP-1 and Service-HTTP-2 to the virtual
server Vserver-SSL-LB.
For details on binding HTTP services to a virtual server, refer to the section
Binding the HTTP Services to the Virtual Server.
Configuring a Secure Content Switching Server
An SSL-based content switching virtual server can redirect incoming data traffic
to the appropriately configured servers based on the data traffic's content type.
The incoming client request is sent to the NetScaler and decrypted by the SSL
virtual server and the clear text request is forwarded to the content switching
virtual server. The NetScaler then chooses a Web server based on the content
switching policies you have configured. The request is then sent to the server IP
address using the NetScaler's mapped IP address.
The following procedure describes the steps to configuretwo address-based
virtual servers to perform load balancing on the HTTP services. One virtual
server, Vserver-LB-HTML, load balances the dynamic content (cgi,asp), and
other, Vserver-LB-Image, load balances the static content (gif,jpeg). The load-
balancing policy used is the default LEASTCONNECTION. A content-switching
SSL virtual server, Vserver-CS-SSL, is then created to peform SSL acceleration
and switching of HTTPS requests based on the configured content-switching
policies. The address-based virtual servers are bound to the SSL-based content
switching virtual servers using content switching policies.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 429
The following figure shows the topology of this scenario.
SSL vserver used for content switching
The following table summarizes the names and values of the entities that you
must configure on the NetScaler.
Entity Type Name Value
HTTP Service Service-HTTP-1 192.168.1.100:80
Service-HTTP-2 192.168.1.101:80
Service-HTTP-3 192.168.1.102:80
Service-HTTP-4 192.168.1.103:80
Load Balancing
Virtual Server
Vserver-LB-HTML 192.168.1.10:80
Vserver-LB-Image 192.168.1.20:80
SSL based CS Virtual
Server
Vserver-SSL-CS 10.102.1.100:443
Certificate Certkey-1
430 Installation and Configuration Guide - Volume 1
Enable the SSL, Load Balancing and Content Switching
Features
For information about the procedures to enable the SSL offloading, content
switching and load balancing features on the NetScaler, refer to the section
Enabling the SSL Feature.
Create HTTP Services
Create four HTTP services with the names, IP addresses and port numbers shown
in the following table.
For details on creating HTTP services, refer to the section Adding HTTP-based
Services.
Create Load Balancing Virtual Servers
Create two HTTP based load balancing virtual servers, Vserver-LB-HTML, with
IP address 192.168.1.10 to serve dynamic content, and create Vserver-LB-Image
with IP address 192.168.1.20 to serve static content.
The following procedure describes the steps to create an HTTP-based virtual
server, Vserver-LB-HTML, with IP address 192.168.1.10, using port 80.
To create a load balancing virtual server
1. In the left pane, expand Load Balancing and click Virtual Servers. The
Load Balancing Virtual Servers page appears in the right pane.
2. In the Load Balancing Virtual Servers page, click Add. The Create
Virtual Servers (Load Balancing) dialog box appears.
3. In the Name, IP Address, and Port text boxes, type Vserver-LB-HTML,
192.168.1.10, and 80 respectively.
4. Under Protocol, select HTTP.
5. Click Create and click Close. The virtual server that you have created,
appears in the Load Balancing Virtual Servers page.
To create a load balancing virtual server using the NetScaler command line
At the NetScaler command prompt, type
Name IP Address : Port
Service-HTTP-1 192.168.1.100:80
Service-HTTP-2 192.168.1.101:80
Service-HTTP-3 192.168.1.102:80
Service-HTTP-4 192.168.1.103:80
Chapter 6 Secure Sockets Layer (SSL) Acceleration 431
add lb vserver Vserver-LB-HTML HTTP 192.168.1.10 80
Note: To create the Vserver-LB-Image virtual server, repeat the procedure, but
in step 3, type Vserver-LB-Image, 192.168.1.20, and 80.
Bind the HTTP Services to the Virtual Server
Bind the HTTP services Service-HTTP-1 and Service-HTTP-2 to the virtual
server Vserver-SSL-HTML, and bind the services Service-HTTP-3 and Service-
HTTP-4 to the virtual server Vserver-SSL-Image.
For details on binding HTTP services to a virtual server, refer to the section
Binding the HTTP Services to the Virtual Server.
Create an SSL Based Content Switching Virtual Server
Create an SSL-based content switching virtual server, Vserver-CS-SSL, with IP
address 10.102.1.100, running on port 443. This is the virtual server that receives
incoming client requests and processes them based on the configured policies.
To add a content switching vserver
1. In the left pane, expand Content Switching and click Virtual Servers. The
Content Switching Virtual Servers page appears in the right pane.
2. In the right pane, click Add. The Create Virtual Server (Content
Switching) dialog box appears.
3. In the Name text box, type Vserver-CS-SSL.
4. In the IP Address text box, type 10.102.1.100.
5. Under Protocol, select SSL.
6. In the Port text box, type 443.
7. Click Create and click Close. The virtual server that you have created
appears in the Content Switching Virtual Servers page.
To add a content switching vserver using the NetScaler command line
At the NetScaler command prompt, type:
add cs vserver Vserver-CS-SSL 10.102.1.100 443
Creating Content Switching Policies
Create content switching policies that will send requests for different types of
content to different configured virtual servers on the NetScaler. These policies are
then bound to the content switching virtual server configured earlier.
432 Installation and Configuration Guide - Volume 1
For details about creating content switching policies on the NetScaler, refer to the
section Adding Content Switching Policies in the Content Switching chapter.
Bind an SSL Certificate Key Pair to the Virtual Server
Bind the certkey Certkey-1 to the virtual server Vserver-CS-SSL.
For details on binding a certificate key pair to a virtual server, refer to the section
Binding an SSL Certificate Key Pair to the Virtual Server.
Configuring a Secure Content Switching Server with
End-to-End Encryption
To ensure the security of communications between the content switching virtual
server and the Web servers, you can configure end-to-end encryption using the
secure content switching setup described earlier. In this setup, the static and
dynamic content servers both use SSL encryption.
Follow the procedure described in the section Configuring a Secure Content
Switching Server but create SSL services instead of HTTP services, and bind
them to the SSL virtual server.
You can also configure the NetScaler for SSL and content switching, with end-to-
end security only for confidential text-based data. With this setup, images and
other static content can travel in clear text format between the NetScaler and the
back-end Web-server.
To set up such a configuration, create SSL services to handle the text-based data
and HTTP services for images, thenfollow the procedure in the section
Configuring a Secure Content Switching Server.
In this type of setup, the dynamic content server uses back-end encryption, but
the static content servers communicate in clear text. Because *.gif and *.jpeg
images do not have to travel in encrypted format between the NetScaler and the
Web servers, you can bind HTTP services to the load balancing virtual servers
that serve static content.
Some advantages of such a setup are:
• Server overhead is decreased and response time is improved because the
static content servers communicate with the NetScaler in clear text.
• Overall site performance is improved by decreasing SSL overhead for
encryption, decryption, and other SSL activities involved in handling client
requests for static content.
Chapter 6 Secure Sockets Layer (SSL) Acceleration 433
Note: In the above configuration, the cache devices are configured to send all
cache-misses to the HTTP virtual server configured on the NetScaler. The
NetScaler re-encrypts the requests and sends them using the secure SSL session
to the SSL services bound to the HTTP virtual server.
Supported Cipher Suites
The following table lists the ciphers supported by the SSL
acceleration feature.
Table 1: Default Ciphers supported by the NetScaler
C
i
p
h
e
r

N
a
m
e
P
r
o
t
o
c
o
l
K
e
y

E
x
c
h
a
n
g
e
K
e
y

S
i
z
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
E
n
c
r
y
p
t
i
o
n
(
K
e
y

S
i
z
e
)
M
e
s
s
a
g
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
SSL3-RC4-MD5 SSLv3 RSA RSA RC4(128) MD5
SSL3-RC4-SHA SSLv3 RSA RSA RC4(128) SHA1
SSL3-DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1
TLS1-AES-256-CBC-SHA TLSv1 RSA RSA AES(256) SHA1
TLS1-AES-128-CBC-SHA TLSv1 RSA RSA AES(128) SHA1
SSL3-EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1
TLS1-DHE-DSS-RC4-SHA TLSv1 DH DSS RC4(128) SHA1
TLS1-DHE-DSS-AES-256-CBC-SHA TLSv1 DH DSS AES(256) SHA1
TLS1-DHE-DSS-AES-128-CBC-SHA TLSv1 DH DSS AES(128) SHA1
SSL3-EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1
TLS1-DHE-RSA-AES-256-CBC-SHA TLSv1 DH RSA AES(256) SHA1
TLS1-DHE-RSA-AES-128-CBC-SHA TLSv1 DH RSA AES(128) SHA1
434 Installation and Configuration Guide - Volume 1
Table 2: Additional Ciphers supported by the NetScaler
C
i
p
h
e
r

N
a
m
e
P
r
o
t
o
c
o
l
K
e
y

E
x
c
h
a
n
g
e
K
e
y

S
i
z
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
E
n
c
r
y
p
t
i
o
n
(
K
e
y

S
i
z
e
)
M
e
s
s
a
g
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
SSL3-RC4-MD5 SSLv3 RSA RSA RC4(128) MD5
SSL3-RC4-SHA SSLv3 RSA RSA RC4(128) SHA1
SSL3-DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1
SSL3-DES-CBC-SHA SSLv3 RSA RSA DES(56) SHA1
TLS1-EXP1024-RC4-SHA TLSv1 RSA(1024) RSA RC4(56) SHA1
Export
TLS1-EXP1024-DES-CBC-SHA TLSv1 RSA(1024) RSA DES(56) SHA1
Export
TLS1-AES-256-CBC-SHA TLSv1 RSA RSA AES(256) SHA1
TLS1-AES-128-CBC-SHA TLSv1 RSA RSA AES(128) SHA1
SSL3-EXP-RC4-MD5 SSLv3 RSA(512) RSA RC4(40) MD5
Export
SSL3-EXP-DES-CBC-SHA SSLv3 RSA(512) RSA DES(40) SHA1
Export
SSL3-EXP-RC2-CBC-MD5 SSLv3 RSA(512) RSA RC2(40) MD5
Export
SSL2-RC4-MD5 SSLv2 RSA RSA RC4(128) MD5
SSL2-DES-CBC3-MD5 SSLv2 RSA RSA 3DES(168) MD5
SSL2-RC2-CBC-MD5 SSLv2 RSA RSA RC2(128) MD5
SSL2-DES-CBC-MD5 SSLv2 RSA RSA DES(56) MD5
SSL2-RC4-64-MD5 SSLv2 RSA RSA RC4(64) MD5
SSL2-EXP-RC4-MD5 SSLv2 RSA(512) RSA RC4(40) MD5
Export
SSL3-EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1
SSL3-EDH-DSS-DES-CBC-SHA SSLv3 DH DSS DES(56) SHA1
TLS1-EXP1024-DHE-DSS-DES-
CBC-SHA
TLSv1 DH(1024) DSS DES(56) SHA1
Export
TLS1-DHE-DSS-RC4-SHA TLSv1 DH DSS RC4(128) SHA1
Chapter 6 Secure Sockets Layer (SSL) Acceleration 435
TLS1-EXP1024-DHE-DSS-RC4-
SHA
TLSv1 DH(1024) DSS RC4(56) SHA1
Export
TLS1-DHE-DSS-AES-256-CBC-
SHA
TLSv1 DH DSS AES(256) SHA1
SSL3-EXP-EDH-DSS-DES-CBC-
SHA
SSLv3 DH(512) DSS DES(40) SHA1
Export
TLS1-DHE-DSS-AES-128-CBC-
SHA
TLSv1 DH DSS AES(128) SHA1
SSL3-EDH-RSA-DES-CBC-SHA SSLv3 DH RSA DES(56) SHA1
SSL3-EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1
SSL3-EXP-EDH-RSA-DES-CBC-
SHA
SSLv3 DH(512) RSA DES(40) DES(40)
TLS1-DHE-RSA-AES-256-CBC-
SHA
TLSv1 DH RSA AES(256) SHA1
TLS1-DHE-RSA-AES-128-CBC-
SHA
TLSv1 DH RSA AES(128) SHA1
TLS1-EXP1024-RC4-MD5 TLSv1 RSA(1024) RSA RC4(56) MD5
Export
TLS1-EXP1024-RC2-CBC-MD5 TLSv1 RSA(1024) RSA RC2(56) MD5
Export
SSL2-EXP-RC2-CBC-MD5 SSLv2 RSA(512) RSA RC2(40) MD5
Export
SSL3-ADH-RC4-MD5 SSLv3 DH None RC4(128) MD5
SSL3-ADH-DES-CBC-SHA SSLv3 DH None DES(56) SHA1
SSL3-ADH-DES-CBC3-SHA SSLv3 DH None 3DES(168) SHA1
TLS1-ADH-AES-128-CBC-SHA TLSv1 DH None AES(128) SHA1
TLS1-ADH-AES-256-CBC-SHA TLSv1 DH None AES(256) SHA1
SSL3-EXP-ADH-RC4-MD5 SSLv3 DH(512) None RC4(40) MD5
Export
SSL3-EXP-ADH-DES-CBC-SHA SSLv3 DH(512) None DES(40) SHA1
Export
436 Installation and Configuration Guide - Volume 1
Table 3: Null Ciphers supported by the NetScaler
C
i
p
h
e
r

N
a
m
e
P
r
o
t
o
c
o
l
K
e
y

E
x
c
h
a
n
g
e
K
e
y

S
i
z
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
E
n
c
r
y
p
t
i
o
n
(
K
e
y

S
i
z
e
)
M
e
s
s
a
g
e
A
u
t
h
e
n
t
i
c
a
t
i
o
n
SSL3-NULL-MD5 SSLv3 RSA RSA None MD5
SSL3-NULL-SHA SSLv3 RSA RSA None SHA1
CHAPTER 7
FIPS
This chapter explains the FIPS-related functionality of the Citrix NetScaler
Application Switch. It explains what FIPS is, and how to configure the basic and
advanced configuration features.
Topics in this chapter include:
• How FIPS works
• Configuring a FIPS System
• Managing FIPS Keys
• Configuring a Certificate Signing Request
• Configuring a High Availability (HA) FIPS System.
How FIPS Works
FIPS (Federal Information Processing Standard) is a standard issued by the US
National Institute of Standards and Technologies. FIPS specifies the security
requirements for a cryptographic module utilized within a security system.
Security systems protect sensitive information in computer and
telecommunication systems. The FIPS system complies with the second version
of this standard, FIPS-140-2.
Note: Henceforth, all references to FIPS will imply FIPS-140-2.
The FIPS system adheres to the FIPS-140-2 Level 2 norms. The FIPS system is
equipped with a tamper-proof (tamper-evident) cryptographic module. This
cryptographic module is a Cavium CN1120-NFB card, designed to comply with
the FIPS 140-2 Level-2 and Level-3 norms. The Critical Security Parameters
(CSPs), primarily the server's private-key, are securely stored and generated
inside the cryptographic module (also referred to as the Hardware Security
Module /HSM). The CSPs are never accessed outside the boundaries of the HSM.
Only the super user on the system (nsroot) can to perform operations on the keys
stored inside the HSM.
438 Installation and Configuration Guide - Volume 1
The following table summarizes the differences between the Citrix NetScaler
system and the FIPS system.
Note: Only FIPS approved ciphers can be configured on a FIPS system. The
only non-FIPS cipher allowed is SSL3-RC4-SHA.
The following sections have been arranged in the order in which a user might
typically configure and use the FIPS system. However, certain sections have been
added to make the guide more comprehensive. .
Configuring a FIPS system
Configuring a FIPS system is similar to configuring a non-FIPS system. For
details, refer to the “Configuring the System” section in volume 1 of the
Installation and Configuration Guide. However, note that the processes differ,
due to the presence of the HSM on the FIPS system. As a result, you need to
configure the HSM immediately after completing the generic configuration
process.
Important: To install FIPS, see the Citrix NetScaler Migration Guide. In the
installation steps, use . / i nst al l ns - F command to install FIPS.
Configuring the HSM
The HSM is preconfigured with default values for the Security Officer password
and the User password. The default values are:
• Security Officer password - sopin123
• User password - userpin123
Note: When changing the SO password and the user password for the first time,
specify sopin123 as the old SO password.
Setting Citrix NetScaler Series FIPS
Key storage On the hard disk On the FIPS card
Cipher support All ciphers FIPS approved ciphers
Accessing Keys From the hard disk Not accessible
Chapter 7 FIPS 439
While the FIPS system can be used with these values, it is advisable to modify
them on the HSM before using it. The HSM can be configured only by the
system’s super user (nsroot) and should be configured before you run the FIPS
system for the first time.
Configuring the HSM allows you to specify the HSM-specific passwords. It also
erases all the existing data on the HSM.
Note: Due to security constraints, the system does not provide a means for
retrieving this password. Store a copy of the password safely. In the event of a
need to re-initialize the HSM, you will need to specify this password as the old
SO password.
The following sample procedure describes the steps to initialize the HSM and
change the Security Officer password from “sopin123” to “fipsso123”.
To configure the HSM
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the
right pane.
2. Click the Initialize HSM button. The Initialize HSM dialog box appears.
3. In the Security Officer (SO) Password text box, type fipssso123.
4. In the Old SO Password text box, type sopin123.
5. In the User Password text box, type userpin123.
6. In the HSM Label text box, type FIPS-140-2 Level-2.
7. Click OK. The security officer password is now changed.
To configure the HSM using the NetScaler command line
At the NetScaler command prompt, type:
set ssl fips -initHSM Level-2 fipssso123 sopin123 userpin123 -
hsmLabel FIPS-140-2
This command will erase all data on the FIPS card. You must save the
configuration (saveconfig) after executing this command.
Do you want to continue? (Y/N) y
Note: After the HSM is initialized, the current configuration of the system
needs to be saved. (If this is not done, the card will not function after a system
reboot.) Any subsequent attempt to change the SO password will cause the card
to be locked.
440 Installation and Configuration Guide - Volume 1
Managing FIPS Keys
Creating FIPS Keys
Once the HSM has been configured, you should create a FIPS key.
The following sample procedure describes the steps to create a FIPS key, Key-
FIPS-1 with a modulus value of 1024 and an exponent of F4.
To create a FIPS key
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the
right pane.
2. Click the FIPS Keys tab. The list of configured FIPS keys appear in the
FIPS keys page.
3. Click the Add button. The Create FIPS Key dialog box appears.
4. In the Fips Key Name dialog box, type Key-FIPS-1.
5. In the Modulus text box, type 1024.
6. Under Exponent, select F4.
7. Click Create. The FIPS key you just created is stored in the HSM of the
system.
To create a FIPS key using the NetScaler command line
At the NetScaler command prompt, type:
create fipskey Key-FIPS-1 -modulus 1024 -exponent f4
Exporting FIPS Keys
Once created, the FIPS key needs to be exported to the hard disk. The exported
key is secured using a strong asymmetric key encryption method..
The follwing sample procedure describes the steps to export the FIPS key Key-
FIPS-1 to the location /nsconfig/ssl/Key-FIPS-1.key. This key is then transferred
and imported on the target system.
To export a FIPS key
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the
right pane.
2. Click the FIPS Keys tab. The FIPS keys page appears.
3. Click the Export button. The Export FIPS key to a file dialog box
appears.
Chapter 7 FIPS 441
4. Under FIPS Key Name, select the key you want to export, for example,
Key-FIPS-1.
5. In the File Name text box, type the name of the file to be exported to, for
example, Key-FIPS-1.key.
Note: The exported file is stored in the /nsconfig/ssl directory by default.
If you choose to use any other directory, you must specify the complete
path to the location. You can also use the browse button to launch the file
explorer to navigate any location on the system.
6. Click Export. The FIPS key you exported is saved in the location you
specified.
To export a FIPS key using the NetScaler command line
At the NetScaler command prompt, type:
export fipskey Key-FIPS-1 -key Key-FIPS-1.key
Note: To avoid errors when importing a FIPS key, wen you export the FIPS
key, you need to ensure that the name of the key exported is the same as the
original key name when it was created.
It is recommended that you create a backup of any key created on the FIPS HSM,
because, once any key on the HSM is deleted, all of the certificates associated
with it are rendered useless. Also, once deleted, there is no way to create the same
key again.
Importing FIPS Keys
You can use an existing FIPS key with your FIPS system. However, the existing
FIPS key needs to be imported into its HSM.
In the following example, you will import the transferred file, Key-FIPS-1.key
into the system as a FIPS key with the same name.
To import a FIPS key
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the
right pane.
2. Click the FIPS Keys tab. The FIPS keys page appears.
3. Click the Import button. The Import as a FIPS Key dialog box appears.
4. Select the Import From FIPS key file.
442 Installation and Configuration Guide - Volume 1
5. In the FIPS Key Name text box, type the name of the FIPS key to be
created, for example, Key-FIPS-1.
6. In the Key File Name text box, type the name of the FIPS key to be
imported, for example, Key-FIPS-1.key.
Note: The default location is the /nsconfig/ssl directory. If the file is
located in another directory, you must specify the complete path to the
location. You can use also the browse button to launch the file explorer and
navigate to any location on the system.
7. Click Import. The FIPS key is now imported into the system.
To import a FIPS key using the NetScaler command line
At the NetScaler command prompt, type:
import fipskey Key-FIPS-1 -key Key-FIPS-1.key
Importing External Keys
In addition to transferring FIPS keys, you can also transfer external private keys
from the hard disk into the HSM. External keys are created outside the HSM, (for
example, using OpenSSL). To import an external key into the HSM, you need to
use an intermediate key (also known as a wrap key) within the HSM. Also, to
import an external key, you first need to convert it into the PKCS8 format. The
external key (in PKCS8 format) is encrypted with the wrap key before it is
imported into the HSM.
Generating a Wrap Key
The following sample procedure describes the steps to create a wrap key Key-
Wrap-1 with password wrapkey123 and salt string wrapsalt123.
To generate a wrap key
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in
the right pane.
2. Click the Wrap Keys tab. The list of configured wrap keys appears in the
Wrap Key page.
3. Click the Add button. The Create Wrap Key dialog box appears.
4. In the Wrap Key Name text box, type the name of the wrap key being
created, for example, Key-Wrap-1.
5. In the Password text box, type the password to be used for the wrap key,
for example wrapkey123.
Chapter 7 FIPS 443
6. In the Salt text box, type the salt string to be used for the wrap key, for
example wrapsalt123.
7. Click Create. The wrap key you created now appears in the Wrap Keys
page.
To generate a wrap key using the NetScaler command line
At the NetScaler command prompt type
create wrapkey Key-Wrap-1 -password wrapkey123 -salt wrapsalt123
Converting the External Key into the PKCS8 Format
The following sample procedure describest the steps to convert the external key
Key-External-1.pem on the system in the PKCS8 format as Key-PKCS8-1 .
To convert the external key into the PKCS8 format
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in
the right pane.
2. Click the FIPS Keys tab. The FIPS keys page appears.
3. Click the Import button. The Import as a FIPS Key dialog box appears.
4. Select the Import From Pkcs8 file.
5. Click the Convert button.The Convert Private Key to PKCS8 Format
dialog box appears.
6. In the Key Name (PKCS8 Format) text box, type the name of the file
where the converted key should be stored, for example, Key-PKCS8-1.
7. In the Private Key Path text box, type the path of the external key to be
converted, for example, Key-External-1.pem.
8. Under Key Format, select the format in which the external key is saved,
for example, PEM.
9. In the Password text box, type the password used to encrypt the key, for
example, FIPS-Password.
10. Click Convert. The external key is now converted to the PKCS8 format.
To convert the external key into the PKCS8 format
At the NetScaler command prompt, type:
convert pkcs8 Key-PKCS8-1 Key-External-1.pem -inform PEM
444 Installation and Configuration Guide - Volume 1
Importing an External Private Key as a FIPS Key
The following sample procedure describes the steps to import an external key,
Key-Pkcs8-1.key with a wrap key, Key-Wrap-1 and an initialization vector,
wrapkey123.
To import an external private key as a FIPS key
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in
the right pane.
2. Click the FIPS Keys tab. The FIPS keys page appears.
3. Click the Import button. The Import as a FIPS Key dialog box appears.
4. Select the Import From Pkcs8 file.
5. In the FIPS Key Name text box, type the name of the FIPS key to be
created, for example, Key-Pkcs8-1.
6. In the Key File Name text box, type the name of the FIPS key to be
imported, for example, Key-Pkcs8-1.key.
7. Under Wrap Key Name, select the wrap key to be used for the import, for
example, Key-Wrap-1.
8. In the IV text box, type the initialization vector to be used for importing the
key, for example, wrapkey123.
9. Click Create. The wrap key you created appears in the Wrap Keys page.
To import an external private key as a FIPS key
At the NetScaler command prompt, type:
import fipskey Key-Pkcs8-1 -key Key-Pkcs8-1.key -inform PEM -
wrapKeyName Key-Wrap-1 -iv wrapkey123
Note: For security reasons, delete the external private key from the hard disk
after you import it into the HSM.
Configuring a Certificate Signing Request
To create a certificate signing request
1. In the left pane, expand SSL, then click CA Tools. The CA Tools page
appears in the right pane.
2. Click Create Certificate Request. The Create Certificate Request dialog
box appears.
Chapter 7 FIPS 445
3. In the Request File Name text box, type the name of the CSR, for example
Certificate-Request-1.
4. In the Key File Name text box, type the name of the FIPS key to be used to
create the CSR, for example, Key-FIPS-1.
Note: You can use the browse button to navigate to the saved key on the
system.
5. Select the format the key was saved in, for example, PEM.
6. In the PEM Passphrase (For Encrypted Key), type the password used to
encrypt the key.
7. Under Distinguished Name Fields, enter relevant information for each
parameter. The information you enter will form the Distinguished Name
(DN) of the company (web site).
8. Click Create, then click Close. The certificate signing request you created
is saved on the system in the location you specified.
To create a certificate signing request using the NetScaler command line
At the NetScaler command prompt, type:
create certreq Certificate-Request-1 -fipskeyName Key-FIPS-1
Now send the CSR to a CA for authentication and signing. Most CAs accept
certificate submissions by email. The CA will return a valid certificate to the
email address you used to submit the CSR.
Once you have obtained the signed certificate from a CA, install the certificate
and its corresponding private key on the system.
Configuring a High Availability (HA) FIPS system
Note: To configure two systems in the high availability (HA) mode, refer to the
Accessing and Configuring a Citrix NetScaler chapter
The following configuration should be performed on the primary system in the
HA pair.
To configure a high availability FIPS system
1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in
the right pane.
446 Installation and Configuration Guide - Volume 1
1. Select the FIPS Info tab, then click the Enable SIM button. The Enable
HA Pair for SIM dialog box appears.
2. In the Certificate File Name text box, type the file name name and path on
the source system where the FIPS certificate shou