Citrix Netscaler Installation and Configuration Guide - Volume 1

CitrixNetScaler
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-
2001The 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
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
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
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
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
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 NetScalers 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.
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.
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.
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.
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.
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
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:
Destination Port The destination port of the SNMP
trap. Default value: 162
Minimum value: 1
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
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
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.
Version The SNMP version of the trap PDU to
be sent.
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
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
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.
Source IP The source IP of the SNMP traps.
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
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
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:
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
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.
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
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.
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.
4. Click Yes.
Configuring SNMP V3
This section describes configuring SNMP V3. This section covers the following
topics:
How It Works
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.
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.
Name The name of the SNMP view.
Read View The SNMP view to be associated with
this group.
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
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 users 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 NetScalers 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.
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
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:
Group Name The name for the NetScaler group.
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
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.
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
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.
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
2. In the System Users page, select the user account which you want to
remove. For example, johnd.
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
2. In the System Groups page, select the group which you want to remove.
For example, Managers.
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
^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
^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
^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
In the following example, a command policy is bound to the user, johnd.
To bind command policies to an user
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.
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
In the following example, a command policy is bound to the group, Managers.
To bind command policies to a group
2. Select a group for which you want to bind command policies. For example,
Managers.
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:
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
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
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
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
Chapter 2 Managing the Citrix NetScaler xlix
2. Select the group Managers.
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
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 NetScalers 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 files 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 eventsmessaging and
syslog. The NetScalers 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 servers 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 servers
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
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
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 Administrators 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).
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.
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 Administrators 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 Users 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.
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:
Modifying an Existing 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.
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
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.
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.
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
set interface 1/3 -haMonitor OFF
Interface Number The interface number represented in the <slot/port>
notation.
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
save ns config
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
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
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
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
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
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
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
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
3. Select the node that you want to remove.
5. Click Yes.
To remove a node using the NetScaler command line
r mha node 3
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
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.
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.
7. Click OK.
To set the hello and dead intervals using the NetScaler command line
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.
3. Select the local node.
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
set HA node -haSync ENABLED
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
3. Click Force Synchronization.
To force synchronization using the NetScaler command line
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.
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
3. Select the local node.
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
set HA node -haProp ENABLED
or
set HA node -haProp DISABLED
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
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
force HA failover
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 systems
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
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
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
3. Click Force Failover. A Warning pop-up window appears.
4. Click Yes.
To force failover when nodes are in listen mode using the NetScaler
command line
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.
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
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.
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.
.
Adding VMAC
To add a VMAC using the NetScaler command line
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
2. Click Open. The Configure VMAC dialog box appears.
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.
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
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
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
sh vrID 100
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
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
unbind vrID 100 1/2 1/3
To remove a VMAC
2. Select the VRID that you want to remove from the system, for example
100.
4. Click Yes. The selected VRID is removed.
To remove a VMAC using the NetScaler command line
rm vrid 100
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.
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.
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
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
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
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.
Interface number The interface number (represented in the
<slot/port>notation)
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
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
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.
To add a FIS
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
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:
FIS Name The name of the FIS to which interfaces
are to be bound.
To bind interfaces to the FIS
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
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
appears, with all the configured FISs displayed.
To view an FIS using the NetScaler command line
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.
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:
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
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:
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.)
FIS Name The name of the FIS that is to be
removed.
To remove a FIS
appears.
3. Select the FIS that you want to remove. For example, select FIS1
5. Click Yes. The selected Failover Interface Set is removed.
To remove a FIS using the NetScaler command line
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.
To add a route monitor, use the parameters in the following table:
To add a route monitor
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.
Network The network prefix of the route to
be monitored
Netmask The subnet for the network
To add a route monitor using the NetScaler command line
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
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
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
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
bind ns node -routeMonitor 10.102.29.30 255.255.255.0
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.
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
4. Under High Availability Status, select STAY SECONDARY.
5. Click OK.
To force the secondary node to stay secondary using the NetScaler
command line
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
4. Under High Availability Status, select STAY PRIMARY.
5. Click OK.
To force the secondary node to stay secondary using the NetScaler
command line
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.
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.
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
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
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.
To configure an IP address using the NetScaler command line
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
di sabl e ns mode usni p
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
dialog box appears.
3. Select the Use Subnet IP check box.
5. Click Yes.
To enable use SNIP using the NetScaler command line
enabl e ns mode usni p
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 doesnt 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.
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.
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
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
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
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.
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
To modify an IP address using the configuration utility
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
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.
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.
To disable ARP using the configuration utility
4. Under Options, clear theARP check box.
5. Click OK.
To disable ARP using the NetScaler command line
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
4. Under Options, clear theICMP check box.
5. Click OK.
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.
To disable PING responses using the NetScaler command line
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.
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
2. Select the IP address that you want to remove, for example, 10.102.29.54.
4. Click Yes.
To remove an IP address using the NetScaler command line
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
2. Select the IP address that you want to disable, for example, 10.102.29.5.
3. Click Disable.
To disable an IP address using the NetScaler command line
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
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
enabl e ns i p 10. 102. 29. 5
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
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
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:
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.
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.
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
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
Table page appears in the Details Pane.
2. Select the ARP entry that you want to remove, for example, 10.102.29.54.
4. Click Yes.
To remove an ARP entry using the NetScaler command line
r mar p 10. 102. 29. 54
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
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
To view the ARP entries using the NetScaler command line
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
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
2. Under Modes & Features, click modes. The Configure Modes dialog box
appears.
3. Select the Layer 2 Mode check box.
5. Click Yes.
To enable the Layer 2 mode using the NetScaler command line
enabl e ns mode l 2
To disable the layer 2 mode, use the following procedure.
To disable the Layer 2 mode using the configuration utility
appears.
3. Clear the Layer 2 Mode check box.
5. Click Yes.
To disable the Layer 2 mode using the NetScaler command line
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
appears.
3. Select the Layer 3 Mode (IP Forwarding) check box.
5. Click Yes.
To enable Layer 3 mode using the NetScaler command line
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
appears.
3. Clear the Layer 3 Mode (IP Forwarding) check box.
5. Click Yes.
To disable Layer 3 mode using the NetScaler command line
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.
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
dialog box appears.
3. Select the MAC Based Forwarding check box.
5. Click Yes.
To enable MAC-based forwarding using the NetScaler command line
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.
To disable MAC-based forwarding using the configuration utility
dialog box appears.
3. Clear the MAC Based Forwarding check box.
5. Click Yes.
To disable MAC-based forwarding using the NetScaler command line
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.
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.
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
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
doesnt 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
dialog box appears.
3. Select the Use Source IP check box.
5. Click Yes.
To enable USIP using the NetScaler command line
enabl e ns mode USI P
To disable USIP mode, use the following procedure.
To disable Use Source IP mode using the configuration utility
dialog box appears.
3. Clear the Use Source IP check box.
5. Click Yes.
To disable USIP using the NetScaler command line
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.
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.
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.
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.
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
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.
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
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
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
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
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.
To reset a network interface
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
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
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
cl ear i nt er f ace 1/ 8
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.
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
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
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
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
st at i nt er f ace 1/ 8
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.
Channel ID LA channel name (in form LA/*)
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
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.
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
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
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.
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.
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
2. Select the channel that you want to modify, for example, LA/1.
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
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.
To unbind a link aggregate channel using the configuration utility
2. Select the channel from which you want to unbind a network interface, for
example, LA/1.
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
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
2. Select the channel that you want to remove, for example, LA/1.
4. Click Yes.
To remove a link aggregate channel using the NetScaler command line
r mchannel LA/ 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
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
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
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
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.
System priority The possible values are 1 to 65535. The default value is
32768.
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
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.
To configure a link aggregate channel protocol using the NetScaler
command line
set l acp - syspr i or i t y 12
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
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
To view link aggregate channels using the NetScaler command line
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
2. Click View LACP Details. The View LACP Details dialog box appears.
3. Click Close.
To view the link aggregate channel protocol using the NetScaler command
line
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
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.
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.
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
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.
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.
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
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.
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.
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.
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
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.
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
3. Bind the 1/ 2 network interface of the system to VLAN 2 as an untagged
VLAN on page 90.
6. Bind the 1/ 2 network interface of the system to VLAN 3 as a tagged
VLAN on page 90. For more information about the procedure to bind a
tagged network interface, see Modifying a VLAN on page 91.
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
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
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).
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
2. Select the VLAN for which you want to bind the IP address, for example, 2.
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
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.
To modify a VLAN using the configuration utility
2. Select the VLAN that you want to modify, for example, 2.
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
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
2. Select the VLAN from which you want to unbind the network interface, for
example, 2.
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.
To unbind an interface to a VLAN using the NetScaler command line
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
2. Select the VLAN from which you want to unbind the IP address, for
example, 2.
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
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
2. Select the VLAN that you want to remove, for example, 2.
4. Click Yes.
To remove a VLAN using the NetScaler command line
r mvl an 2
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
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
To view the VLAN using the NetScaler command line
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
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
st at vl an 2
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
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.
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.
To create a Simple ACL using the configuration utility
1. In the Navigation Pane, expand Network and click ACLs. The ACLs page
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
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.
TTL The time to expire this ACL (in seconds). The minimum
value is 1 and the maximum value is 0x7FFFFFFF.
To configure an expiry time using the configuration utility
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.
page.
To configure an expiry time using the NetScaler command line
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
2. Select the ACL that you want to remove, for example, rule1.
4. Click Yes.
To remove a simple ACL using the NetScaler command line
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
2. Click Clear. The Clear Simple ACL (s) pop-up window appears.
3. Click Yes.
To remove all simple ACLs using the NetScaler command line
cl ear si mpl eacl
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
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
To view the simple ACLs using the NetScaler command line
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
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.
To view the statistics of the simple ACLs using the NetScaler command line
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.
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 !=.
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
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.
page. This is shown in the following figure.
Extended ACL Page
To create a extended ACL using the NetScaler command line
add ns acl r ul e1 deny - sr ci p 10. 102. 0. 0- 10. 102. 255. 255
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
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
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
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.
To remove an ACL using the NetScaler command line
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
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
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
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
di sabl e ns acl r ul e1
The example provides instruction to enable the ACL.
To enable an ACL using the configuration utility
3. Select the ACL that you want to enable, for example, rule1.
4. Click Enable.
To enable an ACL using the NetScaler command line
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
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
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.
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.
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.
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
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
set acl r ul e1 - pr i or i t y 10
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
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
To view extended ACLs using the NetScaler command line
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
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
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.
Bridge Age The bridge ageing time in seconds. The default value is 300. The
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
set br i dget abl e - br i dgeAge 70
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.
To view the bridge table using the configuration utility
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
To view the bridge table using the NetScaler command line
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
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
st at br i dge
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.
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
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
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.
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
To enable load balancing using the NetScaler command line
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,
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.
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.
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.
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
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.
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.
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
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
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.
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
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.
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
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
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).
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
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
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
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
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.
To view the statistics of a vserver using the configuration utility
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
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
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
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
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.
To view the statistics of a service using the NetScaler command line
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
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
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.
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
2. Select the server that you want to remove, for example, 10.102.29.5.
4. Click Yes.
To remove a server using the NetScaler command line
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
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.
Wait Time The time in seconds, after which the server is marked
down.
To disable a server using the NetScaler command line
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
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
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
2. Select the service that you want to remove, for example, Service-HTTP-1.
4. Click Yes.
To remove a service using the NetScaler command line
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
2. Select the service that you want to disable, for example, Service-HTTP-1.
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
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
2. Select the service that you want to enable, for example, Service-HTTP-1.
Wait Time The time in seconds, after which the services representing
the server are marked down.
4. Click Yes.
To enable a service using the NetScaler command line
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
2. Select the vserver from which you want to unbind a service, for example,
Vserver-LB-1.
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
unbind lb vserver Vserver-LB-1 Service-HTTP-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
2. Select the vserver that you want to remove, for example, Vserver-LB-1.
4. Click Yes.
To remove a vserver using the NetScaler command line
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
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
disable lb vserver Vserver-LB-1
By default, the vservers are enabled.
To enable a vserver using the configuration utility
2. Select the vserver that you want to enable, for example, Vserver-LB-1.
4. Click Yes.
To enable a vserver using the NetScaler command line
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.
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
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.
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.
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
2. Select the vserver for which you want to configure an LB method, for
example, Vserver-LB-1.
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
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:
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 Apaches
connection limit.
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
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.
(N =1)
N =2
(N =2)
N =3
(N =3)
N =4 Service-HTTP-1 and
Service-HTTP-3
have the same N
values.
(N =3)
N =4
(N =4)
N =5
(N =4)
N =5
(N =5)
N =6
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.
(Number of active
transaction) value
Remarks
The manner in which a service receives requests based on the N
w
value is
w

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

values.
(N
w
=15000)
N
w
=17500
or when the N
w
value of other services (Service-HTTP-1 and Service-HTTP-3) is equal
to 50000.
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.
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.
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.
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.
The following figure illustrates how the NetScaler uses the least response time
method and forward requests to the three services.
Least response time mechanism
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.
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.
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.
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
N
w
= (N) * (10000 / weight)
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.
(Number of active
transaction *
TTFB) value
Remarks
(N =0)
the least N value.
(N =2)
N =4
(N =3)
N =6
(N =6)
Service-HTTP-3
have the same N
values.
(N =6)
N =8
(N =7)
the least N value.
(N =8)
N =15 Service-HTTP-1,
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
(N =8)
N =9
Service-HTTP-3 receives the first request because it is not handling any
active transaction.
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.
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.
w
value is
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
(N
w
=0)
N
w
the least N
w
value.
(N
w
=2500)
N
w
=5000
(N
w
=5000)
N
w
=15000
(N
w
=15000)
N
w
=20000
(N
w
=20000)
N
w
=25000
(N
w
=23333.34)
N
w
=26666.67 Service-HTTP-2 has
the least N
w
value.
(N
w
=25000)
N
w
the least N
w
value.
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
Method, select Least Response Time.
(N
w
=26666.67)
N
w
the least N
w
value.
or when the N
w
to 105000.
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
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.
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.
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
expression:
N =Number of active transactions * Response time that is determined by the
monitor
Service-HTTP-3 receives the first request because the service is not
handling any active transaction.
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.
(Number of active
transaction) value
Remarks
(N =0)
the least N value.
(N =2)
N =4
(N =4)
N =6
(N =6)
N =8
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)
balancing by using the least response time method when weights are assigned to
the services.
weight of 4.
Service-HTTP-3 receives the first request because it is not handling any
active transaction.
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.
(N =7)
Service-HTTP-3
have the same N
values.
(N =8)
N =10
(N =8)
the least N value.
(N =9)
N =10
or when the N value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to
15.
(Number of active
transaction) value
Remarks
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.
w
value is
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
(N
w
=0)
N
w
the least N
w
value.
(N
w
=5000)
N
w
=10000
(N
w
=15000)
N
w
=20000
(N
w
=20000)
N
w
=25000
(N
w
=23333.34)
N
w
the least N
w
value.
(N
w
=25000)
N
w
the least N
w
value.
(N
w
=23333.34)
N
w
the least N
w
value.
(N
w
=25000)
N
w
the least N
w
value.
or when the N
w
to 75000.
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
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.
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.
To configure the URL hash method, use the Hash Length parameter as described
To configure the URL hash method, perform the steps described in the section
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
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.
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.
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
To configure the destination IP hash method, perform the steps described in the
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.
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.
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:
Service-HTTP-3.
Service-HTTP-1 has 3 Mbps bandwidth.
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.
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
N
w
= (N) * (10000 / weight)
balancing by using the least bandwidth method when weights are assigned on the
services.
Example:
weight of 4.
Service-HTTP-3 receives the first second, third, fourth, and fifth requests
w
value.
(Number of active
transaction) value
Remarks
(N =2)
the least N value.
(N =3)
Service-HTTP-3
have the same N
values.
(N =3)
N =4
(N =4)
N =5
(N =4)
N =5
(N =5)
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
(N =5)
N =6
(N =5)
N =6
N
w
value.
least N
w
value.
least N
w
value.
w
value is
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
(N
w
=5000)
N
w
the least N
w
value.
(N
w
=5000)
N
w
=7500
(N
w
=7500)
N
w
=10000
(N
w
=10000)
N
w
=12500
(N
w
=12500)
N
w
=15000
(N
w
=15000)
N
w
Service-HTTP-3
have the same N
w

value.
(N
w
=15000)
N
w
=17500
(N
w
=16666.67)
N
w
the least N
w
value.
The following figure illustrates how the NetScaler uses the least bandwidth
Least bandwidth mechanismwhen weights are assigned
To configure the least bandwidth method, perform the steps described in the
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:
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.
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.
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
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
N
w
= (N) * (10000 / weight)
balancing by using the least packets method when weights are assigned on the
services.
Example:
weight of 4.
Service-HTTP-3 receives the first second, third, fourth, and fifth requests
w
value.
(Number of active
transaction) value
Remarks
(N =2)
the least N value.
(N =3)
Service-HTTP-3
have the same N
values.
(N =3)
N =4
(N =4)
N =5
(N =4)
N =5
(N =5)
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
(N =5)
N =6
(N =5)
N =6
N
w
value.
least N
w
value.
least N
w
value.
w
value is
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
(N
w
=5000)
N
w
the least N
w
value.
(N
w
=5000)
N
w
=7500
(N
w
=7500)
N
w
=10000
(N
w
=10000)
N
w
=12500
(N
w
=12500)
N
w
=15000
(N
w
=15000)
N
w
Service-HTTP-3
have the same N
w

value.
(N
w
=15000)
N
w
=17500
(N
w
=16666.67)
N
w
the least N
w
value.
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
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.
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.
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.
Data Length The length of the token in bytes. This parameter is applicable to
TCP virtual servers when the Token method is selected. The
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.
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
select Token. You must configure a rule to configure a token.
To configure a rule using the configuration utility
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.
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
balancing by using the custom load method.
Example:
Service-HTTP-3.
Service-HTTP-1 is using 20 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,
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,
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
N
w
= (N) * (10000 / weight)
balancing by using the custom load method when weights are assigned on the
services.
(Number of active
transaction) value
Remarks
(N =20)
the least N value.
(N =30)
N =40
(N =40)
N =50
(N =50)
N =60
(N =60)
N =70
(N =70)
Service-HTTP-3
have the same N
values.
(N =70)
N =80
(N =80)
Service-HTTP-2,
and Service-HTTP-3
have the same N
values.
Example:
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.
w
value is
w

(Number of active
transactions) *
(10000 / weight)
value
Remarks
(N
w
=50000)
N
w
the least N
w
value.
(N
w
=5000)
N
w
=100000
(N
w
=15000)
N
w
=125000
(N
w
=20000)
N
w
=150000
(N
w
=23333.34)
N
w
=175000
(N
w
=25000)
N
w
=200000
(N
w
=23333.34)
N
w
=225000
(N
w
=25000)
N
w
=250000
(N
w
=233333.34)
N
w
the least N
w
value.
or when the N
w
to 400000.
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
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 doesnt 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.
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
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)
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
2. Select the vserver for which you want to configure persistence, for
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
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.
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.
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
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.
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.
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.
configure persistence based on user-defined rules, perform the steps described in
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.
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.
To configure persistence based on server IDs in a URL, perform the steps
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.
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
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.
configure persistence based on destination IP addresses, perform the steps
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.
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.
Backup Persistence The backup persistence type for the group. The valid
options for this parameter are SOURCEIP and NONE.
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
2. Select the vserver for which you want to configure backup persistence, for
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
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.
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.
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).
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
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
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.
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
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.
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
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
2. Select the vserver for which you want to configure the redirection mode, for
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
set lb vserver Vserver-LB-1 -m MAC
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.
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
2. Select the vserver, for example, Vserver-LB-1.
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.
Weights The weight for the specified service. The minimum value is
1 and the maximum value is 100.
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
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.
To configure a vserver to redirect client requests to a URL, use the Redirect URL
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
2. Select the vserver for which you want to configure redirect URL, for
appears.
5. In the Redirect URL text box, type the URL, for example,
6. Click OK.
To configure a vserver to redirect the client request to a URL using the
NetScaler command line
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.
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.
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
2. Select the vserver for which you want to configure the backup vserver, for
appears.
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.
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
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.
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
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.
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
2. Select the vserver for which you want to configure the spillover, for
appears.
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
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.
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.
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
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
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.
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.
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.
To configure a connection failover using the configuration utility
2. Select the vserver for which you want to configure connection failover, for
appears.
5. In the Connection Failover drop-down list, select Stateful.
6. Click OK.
To configure a connection failover using the NetScaler command line
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
2. Select the vserver for which you want to configure a connection failover,
for example, Vserver-LB-1.
appears.
5. In the Connection Failover drop-down list box, select Disable.
6. Click OK.
To disable a connection failover using the NetScaler command line
set lb vserver Vserver-LB-1 -connFailover disable
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
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 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
2. Select the vserver for which you want to configure sessionless load
balancing, for example, Vserver-LB-1.
appears.
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
set lb vserver Vserver-LB-1 -m MAC -sessionless enabled
Sessionless Enable sessionless load balancing. The valid options for the
Sessionless parameter are: enabled and disabled. The
default value is disabled.
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
To set cache redirection on a vserver using the configuration utility
2. Select the vserver for which you want to configure cache redirection, for
appears.
5. Select the Cache Redirection check box.
6. Click OK.
To set cache redirection on a vserver using the NetScaler command line
set lb vserver Vserver-LB-1 -cacheable yes
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.
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
To set priority queuing on a vserver using the configuration utility
2. Select the vserver for which you want to configure priority queuing, for
appears.
5. Select the PQ check box.
6. Click OK.
To set priority queuing on a vserver using the NetScaler command line
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.
Priority Queuing Enable priority queuing on the specified vserver. The valid
options for this parameter are: on and off. The default value
is off.
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
To set Sure Connect on a vserver using the configuration utility
2. Select the vserver for which you want to configure sure connect, for
appears.
5. Select the SC check box.
6. Click OK.
To set Sure Connect on a vserver using the NetScaler command line
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.
Sure Connect Enable Sure Connect on the specified vserver. The valid
options for this parameter are: ON and OFF. The default
value is OFF.
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.
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
2. Select the vserver for which you want to configure down state flush, for
appears.
5. Select the Down state flush check box.
6. Click OK.
To set down state flush on a vserver using the NetScaler command line
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
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.
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
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
2. Select the vserver for which you want to configure HTTP redirection, for
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/
Redirect Port Redirect The state of port rewrite while performing HTTP redirect.
disabled. The default value is disabled.
appears.
5. Select the Redirect Port Rewrite check box.
6. Click OK.
To set HTTP redirection on a vserver using the NetScaler command line
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.
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
2. Select the vserver for which you want to configure vserver port insertion,
appears.
5. In the Vserver IP Port Insertion list, select the VIPADDR or
V6TOV4MAPPING.
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.
6. Type the port header in a text box next to Vserver IP Port Insertion box.
7. Click OK.
the NetScaler command line
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
2. Select the vserver for which you want to configure vserver port insertion,
appears.
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
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.
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.
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.
To set surge protection on the service using the configuration utility
2. Select the service for which you want to configure surge protection, for
3. Click Open. The Configure Service dialog box appears.
5. Under Others, select the Surge Protection check box.
6. Click OK.
To set surge protection on the service using the NetScaler command line
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
To set sure connect on the service using the configuration utility
2. Select the service for which you want to configure sure connect, for
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.
5. Under Others, select the Sure Connect check box.
6. Click OK.
To set sure connect on the service using the NetScaler command line
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
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
To set down state flush on the service using the configuration utility
2. Select the service for which you want to configure down state flush, for
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
set service Service-HTTP-1 -downStateFlush enabled
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.
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
2. Select the service for which you want to configure access down, for
5. Under Others, select the Access Down check box.
6. Click OK.
To set access down on the service using the NetScaler command line
set service Service-HTTP-1 -accessDown yes
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.
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
To set TCP Buffering on the service using the configuration utility
2. Select the service for which you want to configure TCP buffering, for
5. Under Settings, select the TCP Buffering check box.
6. Click OK.
To set TCP Buffering on the service using the NetScaler command line
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.
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.
Compression reduces the amount of data delivered to the browser and improves
client response time. To enable compression on a service, use the compression
To set compression on the service using the configuration utility
2. Select the service for which you want to configure compression, for
5. Under Settings, select the Compression check box.
6. Click OK.
To set compression on the service using the NetScaler command line
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
Compression The state of the HTTP compression feature for the service. The
value is no.
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
To set client keep-alive on the service using the configuration utility
2. Select the service for which you want to configure client keep-alive, for
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
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.
Client Keep-Alive The state of the Client Keep-Alive feature for the service. The
value is no.
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
To insert the IP address of the client in the client request, use the parameters as
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
2. Select the service for which you want to add the client IP address in the
request, for example, Service-HTTP-1.
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
set service Service-HTTP-1 -CIP enabled X-forwarded-for
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).
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
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
2. Select the service for which you want to set the server ID, for example,
Service-HTTP-1.
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
set service Service-HTTP-1 -serverID 11
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.
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
2. Select the service for which you want to use the source IP address, for
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
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.
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
value is no.
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
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
2. Select the service for which you want to configure the maximum number of
client connections, for example, Service-HTTP-1.
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
set service Service-HTTP-1 -maxClient 1000
Maximum Clients The maximum number of open connections to the service. The
default value is 0. The maximum value is 4294967294.
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
To limit the number of client requests using the configuration utility
2. Select the service for which you want to configure the maximum number of
client requests, for example, Service-HTTP-1.
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
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.
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.
Monitor Threshold The monitoring threshold. The default value is 0. The
minimum value is 0 and maximum value is 65535.
To set monitor threshold on the service using the configuration utility
2. Select the service for which you want to configure monitor threshold, for
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
set service Service-HTTP-1 -monThreshold 100
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.
utility
2. Select the service for which you want to configure the timeout value for
client connections, for example, Service-HTTP-1.
Client The idle time (in seconds) after which the client connection is
5. Under Idle Timeout (secs), in the Client text box, type the timeout value,
for example, 100.
6. Click OK.
command line
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
To set a timeout value for idle server connections using the configuration
utility
2. Select the service for which you want to configure the timeout value for
server connections, for example, Service-HTTP-1.
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
set service Service-HTTP-1 -svrTimeout 100
Server The idle time (in seconds) after which the server connection is
terminated. The default value is 360. The maximum value is
31536000.
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
2. Select the service for which you want to configure maximum bandwidth
usage, for example, Service-HTTP-1.
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
set service Service-HTTP-1 -maxBandwidth 100
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.
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
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
2. Select the service for which you want to configure cache redirection, for
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
set service Service-HTTP-1 -cacheable yes
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.
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
Monitors Monitor-HTTP-1 None None HTTP
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.
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.
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
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.
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
2. Select the service for which you want to bind the monitor, for example,
Service-HTTP-1.
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
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.
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.
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.
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
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
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.
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
2. Select the monitor that you want to disable, for example,
monitor-HTTP-1.
4. Click Yes.
To disable a monitor using the NetScaler command line
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
2. Select the monitor that you want to enable, for example, monitor-HTTP-1.
4. Click Yes.
To enable a monitor using the NetScaler command line
enable lb mon Service-HTTP-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
2. Select the service from that you want to unbind the monitor, for example,
Service-HTTP-1.
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
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
2. Select the monitor that you want to remove, for example,
monitor-HTTP-1.
4. Click Yes.
To remove a monitor using the NetScaler command line
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
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
show lb monbindings monitor-HTTP-1
To view monitors using the configuration utility
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
show lb mon monitor-HTTP-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.
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.
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
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
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
and expected TCP data is received from
the server.
HTTP-ECV TCP connection
SSL handshake
Encrypted HTTP request
and expected HTTP data is received from
the server.
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
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).
User Name User name used in the probe.
Password Password used in monitoring.
File Name File name to be used for FTP-EXTENDED monitor.
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
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.
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.
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.
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.
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.
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.
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.
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.
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
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.
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.
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.
To configure prebuilt monitors to check the state of the LDAP server, see
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
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.
Database Database that is used for the MYSQL monitor.
SQL Query SQL query that is used for the MYSQL monitor.
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.
To configure prebuilt monitors to check the state of SNMP device, see
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
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.
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.
User Name Username POP3 server. This user name is used in the
probe.
To configure prebuilt monitors to check the state of POP3 services, see
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
To configure prebuilt monitors to check the state of SMTP services, see
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.
User Name Username SMTP server. This user name is used in the
probe.
Password Password used in monitoring SMTP servers.
Dispatcher IP Address The IP Address of the dispatcher to which the probe is
sent.
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.
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.
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.
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.
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.
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.
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.
Metric Table Metric table to use for the metrics that must be bound. The
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
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
Metric Table Name The name of the metric table. This name must not exceed
31 characters.
To create a metric table using the NetScaler command line
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
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
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
2. Select the metric table that you want to remove, for example,
Table-Custom-1.
4. Click Yes.
To remove a metric table using the NetScaler command line
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
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.
To unbind metrics from a metric table using the NetScaler command line
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
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
show metricTable Table-Custom-1
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
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.
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.
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.
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
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.
To bind a vserver to a work load manager using the configuration utility
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
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
2. Select the workload manager that you want to modify, for example, Wlm-1.
4. In the Keep Alive Timeout (minutes) text box, type the timeout value, for
example, 20.
5. Click OK.
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.
To modify a work load manager using the NetScaler command line
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
2. Select the workload manager that you want to remove, for example,
Wlm-1.
4. Click Yes.
To remove a work load manager using the NetScaler command line
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
2. Select the workload manager for which you want to unbind a vserver, for
example, Wlm-1.
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
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
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
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.
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.
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
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
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
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.
To create range of services using the configuration utility
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
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.
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
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
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
2. Select the vserver to which you want to bind the service group, for
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
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)
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)
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)
2. Select the service group for which you want to bind members, for example,
Service-Group-1.
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)
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
2. Select the service group for which you want to bind monitors, for example,
Service-Group-1.
4. Click the Monitors tab.
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
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
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.
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
CMP The state of the HTTP Compression feature for the services in the
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.
To modify a service group using the configuration utility
2. Select the service group that you want to modify, for example,
Service-Group-1.
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
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
2. Select the service group that you want to remove, for example,
Service-Group-1.
4. Click Yes.
To remove a service group using the NetScaler command line
rm servicegroup Service-Group-1
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
2. Select the service group from which you want to unbind members, for
4. In the Configured Members list box, select a service, for example,
10.102.29.30.
To unbind members from a service group using the NetScaler command line
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
2. Select the vserver from which you want to unbind the service group, for
appears.
4. Click the Services Groups tab. The service groups appear in the Services
Groups tab.
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
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
2. Select the service group from which you want to unbind the monitor, for
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
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.
To disable a service group using the configuration utility
2. Select the service group that you want to disable, for example,
Service-Group-1.
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
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
2. Select the service group that you want to enable,
for example, Service-Group-1.
4. Click Yes.
To enable a service group using the NetScaler command line
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.
To view the properties of a service group using the configuration utility
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
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
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
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.
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
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.
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
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.
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.
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
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
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.
To configure a virtual server IP address mask using the NetScaler command
line
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
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
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.
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
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
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.
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
Vserver Vserver-LB-1 10.102.29.13 53 DNS
The following figure shows the LB entities and the values of the parameters that
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
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
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
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.
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.
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.
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
The following figure shows the LB entities and the values of the parameters that
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
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
To add a name server using the configuration utility
1. In the navigation pane, expand DNS and click Name Servers. The Name
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
Note: Click New if you want to create a new load balancing vserver. The
Create Virtual Server (Load Balancing) dialog box appears.
To add a name server using the NetScaler command line
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.
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.
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
The following figure shows the LB entities and the values of the parameters to be
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
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
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.
3. In the Network, Netmask, and Gateway IP text boxes type 10.102.29.0,
255.255.255.0, and 10.102.29.50.
To configure RNAT using the NetScaler command line
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
set sipParameters -rnatSrcPort 5060
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
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
Entity model for load balancing in DSR mode
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
Monitors TCP None None
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.
appears.
5. Click Yes.
enable ns mode MAC
Configuring a Basic LB Setup in DSR Mode
page 114, create the services and the vservers. Name the entities and set the
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.
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.
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.
using the NetScaler command line
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
2. Select the service, Service-ANY-1.
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
set service Service-ANY-1 -usip yes
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
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.
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.
Monitors PING None None
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
page 158, create the services and the vservers. Name the entities and set the
table specified.
Customizing the LB Setup for DSR mode on Layer3
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
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
set lb vserver VserverName -m Value
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
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.
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.
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.
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
Monitors PING None None
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
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
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
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.
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
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.
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.
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.
Monitors TCP None None
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.
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
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.
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
The following figure shows the LB entities and values of the parameters to be
Entity model for load balancing IDS servers
1. Enabling MAC based forwarding mode
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.
appears.
5. Click Yes.
enable ns mode MAC
Configuring a Basic LB Setup for IDS Configuration
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.
using the configuration utility
Servers. The Load Balancing Virtual Servers page appears in the details
pane.
2. Select the vserver, Vserver-LB-1.
appears.
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.
using the NetScaler command line
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
2. Select the service, Service-ANY-1.
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
set service Service-ANY-1 -usip yes
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.
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 clients 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.
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.
Vserver Vserver-CS-1 10.102.29.161 80 HTTP
Vserver-LB-1 10.102.29.60 80 HTTP
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
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
enable feature cs
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.
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.
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
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.
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.
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.
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
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.
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
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
6. Click OK.
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 dont 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.
To bind a policy to a content switching vserver using the NetScaler
command line
bind cs vserver Vserver-CS-1 Vserver-LB-1 -policyname Policy-CS-1
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
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
show cs vserver
Note: To view the properties of a content switching vserver use the command
show cs vserver Vserver-CS-1
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
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.
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
details pane.
2. Select the vserver from which you want to unbind the service, for example,
Vserver-CS-1.
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
unbind cs vserver Vserver-CS-1 -policyname Pocily-CS-1
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
details pane.
2. Select the vserver that you want to remove, for example, Vserver-CS-1.
4. Click Yes.
To remove a content switching vserver using the NetScaler command line
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
details pane.
2. Select the vserver that you want to disable, for example, Vserver-CS-1.
4. Click Yes.
To disable a vserver using the NetScaler command line
disable cs vserver Vserver-CS-1
By default, the vservers are enabled.
To enable a vserver using the configuration utility
details pane.
2. Select the vserver that you want to enable, for example, Vserver-CS-1.
4. Click Yes.
To enable a vserver using the NetScaler command line
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.
URL The URL, with wildcards. Specify the string value in the
following format: // [[prefix ] [*]] [.suffix]
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
To modify a content switching policy using the configuration utility
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
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
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
2. Select the policy that you want to remove, for example, Policy-CS-1.
4. Click Yes.
To remove a content switching policy using the NetScaler command line
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
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
details pane.
Vserver-CS-1.
box appears.
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
set cs vserver Vserver-CS-1 -caseSensitive ON
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
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.
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
details pane.
Vserver-CS-1.
box appears.
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
5. Under Precedence, select URL.
6. Click OK.
To set precedence using the NetScaler command line
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 vservers 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 vservers 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
details pane.
2. Select the vserver for which you want to create a state dependency, for
example, Vserver-CS-1.
box appears.
5. Select the State Update check box.
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.
6. Click OK.
To configure the state dependency of a CS vserver using the NetScaler
command line
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.
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
details pane.
Vserver-CS-1.
box appears.
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
set cs vserver Vserver-CS-1 -backupVserver Vserver-CS-2
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.
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.
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.
To set a content switching vserver to divert new connections to a backup
vserver using the configuration utility
details pane.
Vserver-CS-1.
box appears.
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
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.
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
URL using the configuration utility
details pane.
Vserver-CS-1.
box appears.
5. In the Redirect URL text box, type the URL, for example,
6. Click OK.
URL using the NetScaler command line
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.
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.
Topics include:
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
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
details pane.
Vserver-CS-1.
box appears.
5. Select the Cacheable check box.
6. Click OK.
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.
To set cache redirection on a content switching vserver using the NetScaler
command line
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
details pane.
Vserver-CS-1.
box appears.
5. Select the Down state flush check box.
6. Click OK.
To set down state flush on a vserver using the NetScaler command line
set cs vserver Vserver-CS-1 -downStateFlush enabled
down state flush Perform delayed cleanup of connections on this vserver.
disabled. The default value is enabled.
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
details pane.
Vserver-CS-1.
box appears.
5. Select the Redirect Port Rewrite check box.
6. Click OK.
To set redirection on a content switching vserver using the NetScaler
command line
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.
Redirect Port Redirect SSL redirect port rewrite. The valid options for this
parameter are: enabled and disabled. The default value is
disabled.
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.
details pane.
Vserver-CS-1.
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.
box appears.
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.
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
utility
details pane.
Vserver-CS-1.
box appears.
Client Timeout (Secs) The idle time (in seconds) after which the client connection is
5. In the Client Timeout (secs) text box, type the timeout value, for example,
100.
6. Click OK.
command line
set cs vserver Vserver-CS-1 -cltTimeout 100
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 servers
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 NetScalers load balancing and content switching
policies, then relays the transactions to the servers.
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
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
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
enable ns feature ssl
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
3. In the Service Name text box, type the name of the service being added, for
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
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.
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
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
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.
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
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
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.
To bind an SSL certificate key pair to a virtual server using the NetScaler
command line
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
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.
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
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
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
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
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.
To view the properties of the configured vserver
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
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
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
show ssl certkey Certkey-SSL-1
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).
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
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
create ssl rsakey Key-RSA-1 1024
To create a DSA key
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
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.
To create a certificate signing request
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
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.
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.
procedure as described above.
Note: Use an FTP client to transfer the certificate and the key to the server in
binary mode.
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.
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.
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.
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 ExchangePKCS#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.
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
interfaces 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.
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
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
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
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.
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
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.
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
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
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.
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
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 servers 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).
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
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
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.
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
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
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
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
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
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
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 .
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.
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.
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
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
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
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
convert ssl pkcs12 Cert-Client-1.pfx -export -certFile Cert-Client-
1 -keyFile Key-Client-1
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.
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
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
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.
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.
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
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.
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
set ssl service Service-SSL-1 -serverAuth ENABLED
To bind the CA certificate to the service
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.
To bind the CA certificate to the service using the NetScaler command line
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.
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
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.
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.
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
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.
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.
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
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
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.
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
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.
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
create ssl crl Cert-CA-1 Key-CA-1 File-Index-1 -revoke Cert-
Invalid-1
To create a CRL
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
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.
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
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.
To customize the SSL configuration for an SSL virtual server using the
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
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.
To customize the SSL configuration for an SSL service using the NetScaler
command line
set ssl service Service-SSL-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
set ssl vserver Vserver-SSL-1 -dh ENABLED -dhCount 1000
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
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
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
set ssl vserver Vserver-SSL-1 -eRSA ENABLED -eRSACount 1000
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.
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
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
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.
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.
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
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
set ssl vserver Vserver-SSL-1 -cipherRedirect ENABLED -cipherURL
http://redirectURL
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.
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
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
set ssl vserver Vserver-SSL-1 -sslv2Redirect ENABLED -sslv2URL
http://sslv2URL
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.
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
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
set ssl vserver Vserver-SSL-1 -tls1 ENABLED
Configuring Advanced SSL Settings
To configure advanced SSL settings,use the parameters in the
following table
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
The following procedure describes the steps to enable SSL redirect on the
NetScaler
To enable SSL redirect
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
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.
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
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.
To configure per directory client authenticatoin using the NetScaler
command line
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
add ssl action -OWASupport ENABLED
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.
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
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
add ssl action Action-SSL-ClientCert -clientCert ENABLED -
clientHeader X-CLIENT-CERT
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.
SerialNumber that inserts a new header X-SERIAL-NUMBER into the HTTP
header whose value contains the client certificates serial number.
To insert the client certificate serial number
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
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.
SubName that will insert a new header X-SUBJ ECT-NAME into the HTTP
header whose value will contain the client certificates 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
To insert the client certificate subject name using the NetScaler command
line
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.
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.
5. Click Create, then click Close. The action Action-SSL-CertHash appears
To insert the client certificate hash using the NetScaler command line
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 certificates 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.
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
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
To insert the client certificate issuer tag using the NetScaler command line
add ssl action Action-SSL-Issuer -clientCertIssuer ENABLED -
certIssuerHeader X-ISSUER-NAME
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.
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
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
To insert the SSL session ID using the NetScaler command line
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.
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
2. In the Name text box, type Action-SSL-Cipher.
3. In the Cipher Suite group, select Enabled from the drop-down list.
4. In the Cipher Tag text box, type X-CIPHER-SUITE.
5. Click Create, then click Close. The action Action-SSL-Cipher appears in
To insert the cipher suite using the NetScaler command line
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 certificates 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
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
To insert the client certificate not before date using the NetScaler command
line
add ssl action Action-SSL-NotBefore -clientCertNotBefore ENABLED -
certNotBeforeHeader X-NOT-BEFORE
Configuring Client Certificate Not After Date Insertion
You can insert the client certificates 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.
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
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
To insert the client certificate not after date using the NetScaler command
line
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.
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.
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
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.
To bind an SSL policy to a vserver
1. In the left pane, expand SSL Offload and click Virtual Servers. The SSL
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
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
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.
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
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.
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
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.
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
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
bind lb vserver Vsever-SSL-2 Service-SSL-1
bind lb vserver Vserver-SSL-2 Service-SSL-2
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:
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
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.
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
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
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
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.
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
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 *.
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
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.
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.
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.
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
appears.
3. In the Name, IP Address, and Port text boxes, type Vserver-HTTP-1,
192.168.1.100, and 80.
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
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
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
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).
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.
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.
To enable the load balacing feature
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
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
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
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.
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
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
To create an SSL_BRIDGE virtual server using the NetScaler command line
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
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
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
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.
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
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.
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.
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
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
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
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.
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
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.
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
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.
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.
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
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
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-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
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-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
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
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.
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.
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
systems 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
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.
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
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
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
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
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
right pane.
3. Click the Import button. The Import as a FIPS Key dialog box appears.
4. Select the Import From FIPS key file.
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
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
the right pane.
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
convert pkcs8 Key-PKCS8-1 Key-External-1.pem -inform PEM
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
the right pane.
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
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
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
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
the right pane.
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 should be stored, for example,
3. In the Key Vector File Name text box, type the file name and path on the
source system where the FIPS key vector should be stored.
4. In the Target Secret File Name text box, type the location for storing the
secret data on the target system.
5. In the Source Secret File Name text box, type the location for storing the
secret data on the target system.
6. Click OK. The FIPS systems are now configured in the HA mode.
Note: The secret file on the source and target system is the file on the system
where the FIPS key is copied to before it is transferred or received.
When a non-FIPS system is started, the default certificate namely ns- ser ver -
cer t i f i cat e is loaded automatically. The certificate-key pair is used from the
default certificate-key files that are created when the build is installed. However,
on a FIPS system, a key cannot be loaded from HDD, and therefore, the default
ns- ser ver - cer t i f i cat e is not configured on the NetScaler.
To configure a certificate on the internal services for FIPS system, you need to
perform the one of the following:
Create a fipskey and a certificate. Then, load the certificate and associate it
with the fipskey as ns- ser ver - cer t i f i cat e. The FIPS key is
automatically bound to the internal services. For information on how to
create FIPS key, see Creating FIPS Keys on page 440.
Import an external key as fipskey. Then, load the certificate and associate it
with the fipskey as ns- ser ver - cer t i f i cat e. For information on
how to import an external key, see Importing FIPS Keys on page 441.
To create a certificate key pair
Chapter 7 FIPS 447
3. In the Name text box, type the name of the certificate key pair you want to
add.
4. In the Details section, select the Remote System.
Note: Both the certificate and the key should be present at the same
location. To use a certificate present on the local system, in Step 4 above,
select the Local System.
5. Select the Browse button next to Certificate Filename. The system file
browser appears.
6. Select the certificate you want to use and click Select.
7. Select the Browse button next to Key Filename. The system file browser
appears.
8. Select the key you want to use and click Select.
Note: To encrypt the key used in the certificate key pair, type the
password to be used for encryption in the Password text box.
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
add certkey CAcertkey -cert Certificate-FIPS-1.pem
Note: IThe FIPS system does not support external keys. As a result, on a FIPS
system, you will not be able to load keys from a local storage device such as a
hard disk or flash memory.
To bind an SSL certificate key pair to a virtual server
certificate key pair to. For example, select Vserver-SSL-1, then click
Open. The Configure Virtual Server (SSL Offload ) appears.
3. Select the SSL Settings tab. The list of configured certificate key pairs
configured on the system are displayed in the Available area.
4. Select the certificate key pair that you want to bind to the virtual server and
click Add. The certificate key pair appears in the Configured area.
5. Click OK. The certificate pair is bound to the virtual server.
To bind an SSL certificate key pair to a virtual server using the NetScaler
command line
bind ssl certkey SSL-Certkey-1 Vserver-SSL-1
CHAPTER 8
Optimizing Performance
The Citrix NetScaler system provides features such as client keep-alive, TCP
buffering, and compression to improve the performance of a transaction
management environment. Performance of any transaction management
environment depends on factors such as bandwidth usage, download time, speed
of the server and the client networks, and time consumed to complete a
transaction. Client keep-alive improves performance by reducing the time
consumed in a transaction and TCP buffering improves performance by adding a
speed-matching mechanism between the fast server network and the slow client
network. Compression improves performance by reducing both download time
and bandwidth usage. This chapter describes how these features work, and also
provides instructions to configure these features.
The topics covered in this chapter are:
Understanding and Configuring Client Keep-Alive
Understanding and Configuring TCP Buffering
Understanding and Configuring Compression
Understanding and Configuring Client Keep-Alive
Client keep-alive enables multiple client requests to be sent on a single client
connection. This feature helps in a transaction management environment where
the server closes the client connection after serving the response to the client. The
client has to open a new connection for each request to the server leading to a lot
of time being consumed for a transaction. The client keep-alive feature of the
system alleviates this problem by keeping the client-side connection open
between the client and the system even after the server closes the client
connection. This allows multiple client requests to be sent using a single
connection. Keeping the client-side connection open saves the packet round trips
associated with opening and closing a connection. This is most beneficial to SSL
sessions because this eliminates unnecessary termination and open sequences,
thus reducing the time taken for a transaction to occur.
Client keep-alive is useful under either of the following conditions:
when the server does not support client keep-alive
when the server supports client keep-alive but an application on the server
does not support client keep-alive.
The topics covered in this section are:
How Client Keep-Alive Works
Configuring Client Keep-Alive
Modifying the Client Keep-Alive Setup
HowClient Keep-Alive Works
Client keep-alive can be applied to all HTTP services globally, or to a specific
service such as HTTP or SSL. Note that client keep-alive applies only to HTTP
and HTTPS services.
The following diagram illustrates a typical client keep-alive deployment.
Client keep-alive entity model
As shown in this figure, to configure client keep-alive, you need to define
services and enable client keep-alive for those services. Services represent
applications on physical servers. The traffic from the client is intercepted by the
configured service and the client request is directed to the origin server. The
server sends the response and closes the connection between the server and the
system. If a Connection: Close header is sent, this header is mangled in the
client-side response, and the client-side connection is kept open. As a result, the
client does not have to open a new connection for the next request, instead the
connection to the server is reopened.
Origin
server
Service
Client
Citrix NetScaler system
Client requests
Response from server
Response sent to
client
With client
keep-alive
enabled
Chapter 8 Optimizing Performance 451
Note: If a server sends back two Connection: Close headers, only one is
edited. This results in significant delays on the client rendering of the object
because a client does not assume that the object has been delivered completely
until the connection is actually closed.
Configuring Client Keep-Alive
This section describes how to configure client keep-alive on the system. To
configure the client keep-alive feature you need to create a service and enable
client keep-alive for that service. The configuration example in this section is
based on a service-only scenario.
The following diagram illustrates the topology of a basic client keep-alive
configuration.
Basic topology
The following table summarizes the name and example value of the entity that
you must configure on the system.
Service Service-HTTP-1 10.102.29.191
The following diagram depicts the basic configuration of the client keep-alive
feature. It illustrates the traffic flow, the entities, and the parameters you need to
configure.
Entities configured in a client keep-alive setup
In this figure, a service Service-HTTP-1 is configured on the system, which
enables the system to keep the client-side connection open even after the server
has closed the connection between the server and the system.
Note that while configuring a service, if the client keep-alive option is not
explicitly specified, the services use the global settings for the client keep-alive.
The following table lists the mandatory parameters, their descriptions, and their
values that you must configure when creating a service.
The following procedure describes the steps to create a service Service-HTTP-1
with IP address 10.102.29.191, listening on port 80, and with protocol type
HTTP.
Name The name of the service. This is a mandatory parameter
and cannot be changed. The service name must not exceed
31 characters.
IP Address The IP address of the origin server, which the service
represents.
Port The port on which the service listens. The port number
must be a positive number not greater than 65535. The
minimum value is 1.
Service Type The type of service that is being added. This parameter
determines the behavior of the service. The possible values
are: HTTP, FTP, TCP, UDP, SSL, SSL_BRIDGE,
SSL_TCP, NNTP, ANY, SIP_UDP.
Origin
server
Service
Client
Client requests
Response sent to
client
Service-HTTP-1
10.102.29.191
To create a service with client keep-alive enabled
1. In the left pane, expand Load Balancing and click Services. The Services
3. In the Service Name and Server text boxes, type the name of the service
and the IP address of the server, for example, Service-HTTP-1 and
10.102.29.191.
4. In the Port text box, type the port number, for example, 80.
5. In the Protocol list, choose HTTP.
6. In the Advanced tab, under Settings, select the Override Global check
box, then select the Client Keep-Alive check box.
7. Click Create and click Close. The service that you create appears in the
Services page.
To create a service with client keep-alive enabled using the NetScaler
command line
add service Service-HTTP-1 10.102.29.191 HTTP 80 -CKA YES
Modifying the Client Keep-Alive Setup
You can modify the client keep-alive configuration by enabling or disabling client
keep-alive at the service level.
The topics covered in this section include:
Enabling or Disabling the Client Keep-Alive Mode Globally
Enabling or Disabling Client Keep-Alive for a Service
Enabling or Disabling the Client Keep-Alive Mode
Globally
The client keep-alive feature is disabled on the system by default. If you enable
client keep-alive globally, all new services inherit the global settings by default.
The following procedure describes the steps to enable or disable client keep-alive
globally.
To enable or disable the client keep-alive mode globally
1. In the left pane, expand System and click Settings. The Settings page
2. Under the Modes & Features group, click modes. The Configure Modes
dialog box appears.
3. Select or clear the Client Keep-Alive check box.
4. Click OK, and click Yes in the Enable/Disable Mode(s)? message box.
To enable or disable the client keep-alive mode globally using the NetScaler
command line
enable mode cka
disable mode cka
Enabling or Disabling Client Keep-Alive for a Service
You can enable or disable client keep-alive at the service level. Note that the
service level settings take precedence over the global settings. The following
procedure describes the steps to enable or disable client keep-alive at the service
level.
To enable or disable the client keep-alive mode for a service
2. Click the service for which you want to enable or disable client keep-alive,
for example, Service-HTTP-1, then click Open. The Configure Service
dialog box appears.
3. In the Advanced tab, under Settings, select or clear the Client Keep-Alive
check box.
4. Click OK. Client keep-alive is enabled or disabled for the service.
To enable or disable the client keep-alive mode for a service using the
set service Service-HTTP-1 -CKA YES
set service Service-HTTP-1 -CKA NO
Understanding and Configuring TCP Buffering
The TCP buffering feature of the Citrix NetScaler system buffers the servers
response and delivers it to the client at the clients speed, thus offloading the
server faster and thereby improving the performance of Web sites.
In transaction management, the overall performance depends on the performance
parameters of both the client and the server. Typically, the server is on a high-
bandwidth network and the performance of the transaction management system is
limited by the low bandwidth of the client network. As a result, the server spends
more time serving slow clients such as modem clients, and also retransmitting
packets on occasions when packets are lost due to the low bandwidth of the client
network. TCP buffering alleviates this problem by breaking the direct link
between the client and the server connections and adding a speed-matching
mechanism between the two. This makes the round trip between the system and
the server faster. With reduced round trip time, the server can serve content faster
and it no longer has to retransmit packets. The retransmission of packets is done
by the Citrix NetScaler system thus freeing up the server and server connections
for other tasks.
How TCP Buffering Works
Configuring TCP Buffering
Modifying the TCP Buffering Setup
HowTCP Buffering Works
TCP buffering buffers only the server's response to the clients. It works with all
application protocols running on TCP. TCP buffering also works with all network
topologies, including origin server deployment and one-arm mode.
The system configured with TCP buffering receives the response from the server
at the speed of the server network, buffers the server response upto a configured
buffer size, and forwards the response to the client at the client networks speed.
If the total buffer allocated for TCP Buffering becomes full, the system uses
window size manipulation in order to slow down the server, thus preventing
overflows and lost packets.
The following diagram illustrates the entities configured in a TCP buffering
setup.
TCP buffering entity model
As shown in this figure, to configure TCP buffering, you need to define services
and enable TCP buffering for those services. Services are entities that are logical
representations of applications on the physical servers. The traffic from the client
is intercepted by the configured service and the client request is directed to the
origin server. On receiving the response from the origin server, the service buffers
the response and forwards it to the client at the client networks speed.
TCP buffering is bypassed for features such as SSL, compression, and caching
because these features perform buffering inherently. When one or more of these
features are enabled on a given transaction, TCP buffering is not performed.
TCP buffering is also skipped for small responses that can fit in a single packet.
The following table lists the conditions when TCP buffering is performed.
Note: TCP buffering is performed for non-compressible and non-cacheable
responses from the server, even when compression and caching are enabled. TCP
buffering is internally disabled for the features mentioned in the table above
because those features indirectly provide TCP buffering benefit.
Conditions TCP Buffering
TCP buffering enabled and the response is not single packet YES
SSL transaction NO
Compressible response and compression enabled NO
Cacheable response and caching enabled NO
Origin
server
Service
Client
Client requests
at server networks
speed
Response sent to
client at client
networks speed
With TCP
buffering
enabled
Configuring TCP Buffering
This section describes how to configure TCP buffering on the system. To
configure TCP buffering you must create a service and enable TCP buffering for
that service. The following diagram illustrates the topology of a basic TCP
buffering configuration.
Basic topology
The following table summarizes the name and value of the entity that you must
configure on the system.
Service Service-HTTP 10.102.29.130
(with TCP buffering confi gured)
Internet
Router
Origin Server
Client
L2 switch
L2 switch
Client requests Server response
at server
networks speed
Response sent to
client at client
networks speed
The following diagram depicts the basic configuration of the TCP buffering
feature. It illustrates the traffic flow, the entities, and the parameters you must
configure.
Entities configured in a TCP buffering setup
In this figure, a service Service-HTTP is configured on the system, which enables
the system to buffer the response received from the origin server, and later send it
to the client at the client networks speed. Note that for a specific service, the
service-level setting takes precedence over the global settings.
The following table describes the mandatory parameters that you must configure
when creating a service.
The following procedure describes the steps to create a service when TCP
buffering is enabled on the system. It illustrates the steps to create a service
Service-HTTP, with IP address10.102.29.130, listening on port 80, and with
protocol type HTTP.
To create a service with TCP buffering enabled
Name The name of the service. This is a mandatory parameter and
cannot be changed. The service name must not exceed 31
characters.
IP Address The IP address of the origin server, which the service represents.
positive number not greater than 65535. The minimum value is
1.
Service Type The type of service that is being added. This parameter
determines the behavior of the service. The possible values are:
HTTP, FTP, TCP, UDP, SSL, SSL_BRIDGE, SSL_TCP, NNTP,
ANY, SIP_UDP.
Origin
server
Service
Client
Client requests
at server networks
speed
Response sent to
client at client
networks speed
Name: Service-HTTP
IP address:
10.102.29.130
and the IP address of the server, for example, Service-HTTP and
10.102.29.130.
6. In the Advanced tab, under Settings, select the Override Global check
box, then select the TCP Buffering check box.
7. Click Create and then click Close. The service that you create appears in
the Services page.
To create a service with TCP buffering enabled using the NetScaler
command line
add service Service-HTTP 10.102.29.130 HTTP 80 -TCPB YES
Modifying the TCP Buffering Setup
You can modify the TCP buffering configuration by enabling or disabling the
TCP buffering feature either globally or for a service. You can also set the
parameters used to configure the size and memory limit of the buffer.
Enabling or Disabling the TCP Buffering Mode Globally
Enabling or Disabling TCP Buffering for a Service
Setting the TCP Buffering Parameters
Enabling or Disabling the TCP Buffering Mode Globally
TCP buffering is disabled on the system by default. You can enable TCP
buffering globally and all new services inherit the global settings by default. The
following procedure describes the steps to enable or disable TCP buffering
globally on your system.
To enable or disable the TCP buffering mode globally
dialog box appears.
3. Select or clear the TCP Buffering check box.
4. Click OK, and click Yes in the Enable/Disable Mode(s)? message box.
To enable or disable the TCP buffering mode globally using the NetScaler
command line
enable mode TCPB
disable mode TCPB
Enabling or Disabling TCP Buffering for a Service
You can enable or disable TCP buffering at the service level. Note that the service
level settings take precedence over the global settings.
To enable or disable the TCP buffering mode for a service
2. Click the service for which you want to enable or disable TCP Buffering,
for example, Service-HTTP, then click Open. The Configure Service
dialog box appears.
3. On the Advanced tab, under Settings, select or clear the TCP Buffering
check box.
4. Click OK. The TCP Buffering feature is enabled or disabled for the service.
To enable or disable the TCP buffering mode for a service using the
set service Service-HTTP -TCPB YES
set service Service-HTTP -TCPB NO
Setting the TCP Buffering Parameters
You can configure the two parameters, buffer size and memory usage limit, to set
the size of the TCP buffer and the memory usage limit.
The following table describes the parameters you must configure when setting the
TCP buffering parameters.
Buffer Size The buffer size is measured in kilobytes and it specifies the size of
the TCP buffer per connection. The default size is 64KB.
To set the TCP buffering parameters
2. Under the Global Settings group, click global system settings. The
Configure Global Settings dialog box appears.
3. Under the TCP Buffering group, in the Buffer Size (Kilobytes) text box,
type the size of the TCP buffer you want to set, for example, 128.
4. In the Memory Usage Limit text box, type the maximum memory size that
you want to use for buffering, for example, 128.
5. Click OK. The values you have set are applied to the TCP buffering
parameters.
To set the TCP buffering parameters using the NetScaler command line
set tcpbufParam -size 128 -memLimit 128
Note: For best performance, the connection buffer size must be set so that the
majority of responses can fit into the TCP buffer. If integrated caching is not
active on a system, the memory usage limit must be increased to up to half the
total system memory in order to provide maximum amount of buffering capacity.
Understanding and Configuring Compression
The compression feature of the Citrix NetScaler system compresses HTTP
responses for browsers that are compression aware, thus improving the
performance of Web sites with compressible content.
Memory Usage Limit The memory usage limit parameter specifies the maximum
memory that can be used for buffering. The default memory limit is
64MB.
In a transaction management environment, users, very often, face problems such
as poor Web site performance, huge download time, and high bandwidth usage.
Also, Web site performance is affected by WAN latency and connection
bottlenecks. The Citrix NetScaler system alleviates these problems by
implementing lossless compression that reduces the number of packets of data
transmitted, thus reducing both download time and bandwidth usage for users. In
lossless compression, the exact original data is reconstructed from the
compressed data.
How Compression Works
Configuring the Compression Feature
Modifying an Existing Compression Setup
Verifying the Compression Configuration
Customizing a Compression Setup with Policies and Actions
Configuring Compression for Commonly Used Deployment Scenarios
HowCompression Works
Compression is implemented at origin sites with HTML or other compressible
content that is either statically or dynamically generated. The system compresses
content of the MIME types such as text/html, text/plain, text/xml, text/css, text/
rtf, application/msword, application/vnd.ms-excel, and application/vnd.ms-
powerpoint. HTTP compression is interpreted by popular browsers such as
Internet Explorer, Firefox, and Netscape.
Note: The system only compresses content of MIME types text/* excluding
text/xml by default. Also, responses for only GET and POST requests are
compressed.
The system configured with compression policies intercepts requests from
compression-aware clients and applies the compression policies to determine
whether the client can accept compressible content. After the system receives the
HTTP response from the server, the content is examined again to determine if it is
compressible. If the content is compressible, it is compressed, and the
compressed content is forwarded to the client. The response header is modified to
indicate the type of compression performed.
The following diagram illustrates a compression deployment in a transparent,
non-vserver mode where compression policies are enabled globally. This enables
the compression policies to act on any service irrespective of the vserver the
service is bound to.
Compression entity model
As shown in this figure, to configure compression, you need to define services
and compression polices. Services are entities that are logical representations of
applications on the physical servers. The compression policies enable the system
to identify the content that needs to be compressed. A compression policy
consists of an expression and an action. An expression is created to identify the
files entering the system, for example, HTML files, ASP files, or PDF files. An
action defines the action the system performs on the file identified by the
expression. For example, you can configure a compression policy comprising of
an expression that identifies PDF files and an action that compresses the PDF
files.
For more information on compression policies, see section Customizing a
Compression Setup with Policies and Actions on page 473.
Origin
server
Service
Client
CMP
policies
Client requests
Response from server Compressed response
You can also configure compression in a vserver mode where the compression
policies are bound to a load balancing vserver. This allows the compression
policies to be evaluated for only the services bound to that vserver and to simplify
policy bindings. This is illustrated in the following diagram.
Compression entity model in a vserver mode
As shown in the figure, in this deployment, you need to configure a vserver,
services, and compression policies, and bind the services and policies to the
vserver. A vserver is an entity that identifies the least loaded origin server and
directs client requests to the corresponding service. The system evaluates the
compression policies and determines whether the response is compressible. The
compressible content is compressed and sent to the client.
For more information on configuring compression in a vserver mode, see section
Compression in Inline Mode on page 490.
The subsequent sections provide instructions to configure compression in the
system, and describes various deployment scenarios.
Configuring the Compression Feature
This section describes how to configure the compression feature on the system.
When you configure compression on a Citrix NetScaler system, the system
compresses HTTP responses before serving it to the client. This section assumes
that you have prior knowledge of services and how they work.
The following diagram illustrates the topology of a basic compression
configuration.
Origin
server_1
Service_2
Client
CMP
policies
Client requests
Response from
server
Compressed
response
Service_1
LB Vserver
Origin
server_2
Response from
server
Basic topology
The following table summarizes the name and value of the entity that you need to
The following diagram depicts the basic configuration of the compression
feature. It illustrates the traffic flow, the entities, and the parameters you need to
configure.
Entities configured in a compression setup
In this figure, a service Service-HTTP-1 is configured on the system, and the
built-in policies act on this service to enable the system to compress the response
received from the origin server. Note that the built-in compression policies are
activated globally as soon as the compression feature is enabled on the system.
Perform the following steps to configure compression:
1. Enabling the Compression Feature
Service Service-HTTP-1 10.102.29.51
(with compression confi gured)
Internet
Router
Origin Server
Client
L2 switch
L2 switch
(compressible
content)
compressed
content
Origin
server
Service
Client
CMP
policies
Client requests
Response from
server
Compressed
response Name: Service-HTTP-1
IP address: 10.102.29.51
(In-built
policies)
2. Creating a Service
Enabling the Compression Feature
Compression is not enabled on the system by default. You must enable the
compression feature to allow compression of HTTP responses that is sent to the
client. The following procedure describes the steps to enable compression.
To enable the compression feature
1. In the left pane, expand System and click Settings.The Settings page
3. Select the Compression check box.
4. Click OK, and click Yes in the Enable/Disable Feature(s)? message box.
To enable the compression feature using the NetScaler command line
enable feature cmp
Creating a Service
You must create a service that logically represents the physical server. When a
service is created, it takes on the value of the compression feature operating at
that time.
when creating a service.
The following procedure describes the steps to create a service Service-HTTP-1
with IP address 10.102.29.51, listening on port 80, and with protocol type HTTP.
Name The name of the service. This is a mandatory parameter and cannot
be changed. The service name must not exceed 31 characters.
IP Address The IP address of the origin server, which the service represents.
positive number not greater than 65535. The minimum value is 1.
Service Type The type of service that is being added. This parameter determines
the behavior of the service. The possible values are: HTTP, FTP,
TCP, UDP, SSL, SSL_BRIDGE, SSL_TCP, NNTP, ANY, SIP_UDP.
To create a service
and the IP address of the server, for example, Service-HTTP-1 and
10.102.29.51.
6. Click Create and click Close. The service, which you have created, appears
in the Services page.
To create a service using the NetScaler command line
Modifying an Existing Compression Setup
This section describes various tasks you can perform to modify a compression
setup, for example, you can disable the compression feature on the system, or you
can enable or disable compression at the service level. You can also set the
compression parameters.
Disabling the Compression Feature
Enabling or Disabling Compression at the Service Level
Setting Compression Parameters
Disabling the Compression Feature
The system ceases to compress HTTP responses when you disable compression.
Disabling compression on the system does not disable compression at the service
level, although compression does not work. On disabling compression on the
system, a warning appears in the Configure Service dialog box at the service
level, as shown in the following figure:
Warning displayed on disabling compression globally
To disable the compression feature
3. Clear the Compression check box.
4. Click OK, and click Yes on the Enable/Disable Feature(s)? message box.
To disable the compression feature using the NetScaler command line
disable feature cmp
Enabling or Disabling Compression at the Service Level
You can enable or disable compression at the service level. However, for
compression to work, the compression feature must be enabled on the system
globally as well as at the service level.
To enable or disable compression at the service level
2. In the Services tab, click the service, for example, Service-HTTP-2, then
click Open.
3. In the Advanced tab, under Settings, select or clear the Compression
check box.
4. Click OK.
To enable or disable compression at the service level using the NetScaler
command line
set service Service-HTTP-2 -CMP YES
set service Service-HTTP-2 -CMP NO
Setting Compression Parameters
You can set different values for compression parameters, such as quantum size,
compression level, and server-side compression. The following table describes
the compression parameters that you can set.
To set the compression parameters
1. In the left pane, click Compression. The Compression page appears in the
right pane.
2. Click CMP Parameters. The Configure CMP Parameters dialog box
appears.
3. In the Quantum Size text box, type the quantum size you want to set, for
example, 20480.
COMPRESSION
PARAMETER
DESCRIPTION
Quantum Size This is the minimum quantum of data to compress.
The default value is 57344; the minimum value is 1;
the maximum value is 63488
Compression Level The compression level can be set to optimal,
bestspeed or bestcompression. The default value
is optimal.
Server-side Compression Compression at server side. This is enabled by
default.
4. In the Compression level list, click the level you want to set the
compression level to, for example, Best Speed.
5. Select or clear the Server-side compression check box to enable or disable
compression at the backend server, and click OK.
To set the compression parameters using the NetScaler command line
set cmp parameter -cmpLevel bestspeed -quantumSize 20480 -serverCmp
ON
Verifying the Compression Configuration
This section describes the different methods you can use to verify your
compression configuration. You can use various methods to view compression
statistics such as compression requests and compression ratio. You can also use
different methods to view the statistics of compression policies. This section
covers the following topics:
Viewing Compression Statistics
Viewing the Statistics of a Compression Policy
Viewing Compression Statistics
This section describes methods to view compression statistics such as
compression requests, compressible bytes received, compressed bytes
transmitted, and compression ratio. You can use any of the following methods to
view compression statistics:
Viewing Compression Statistics Using Configuration Utility
Viewing Compression Statistics Using the Statistical Utility
Viewing Compression Statistics Using SNMP
Viewing Compression Statistics Using CLI
Viewing Compression Statistics Using Configuration Utility
You can use the configuration utility to view detailed statistics of compression.
The statistics that you can view include compression requests, compressible bytes
received, compressible packets received, compressed bytes transmitted,
compressed packets transmitted, and compression ratio. The following procedure
describes the steps to view the summary and detailed statistics of compression
from the configuration utility.
To view the statistics of compression from the configuration utility
1. In the left pane, click Compression. The Compression page appears in the
right pane.
2. Click Statistics in the bottom right corner. The summary of compression
statistics appear in the Compression Statistics window.
3. Click Details. The detailed statistics of compression appears.
Viewing Compression Statistics Using the Statistical Utility
Another way to view detailed statistics of compression is from the statistical
utility. You can also view a graphical representation of compression requests per
second. The following procedure describes the steps to view the statistics of
compression using the statistical utility.
To view the details of the compression from the statistical utility
1. In the Statistical Utility, in the Select Group list, choose Compression.
The summary of the compression statistics appears.
2. Click the Details tab. The detailed statistics of compression appear.
3. Click the Chart tab. A graphical representation of the compression
statistics appears.
Note: For more information on the statistics and the charts, refer to the
statistical utility help.
Viewing Compression Statistics Using SNMP
You can view the following compression statistics using the SNMP network
management application:
Number of compression requests (OID: 1.3.6.1.4.1.5951.4.1.1.50.1)
Number of compressed bytes transmitted (OID:
1.3.6.1.4.1.5951.4.1.1.50.2)
Number of compressible bytes received (OID: 1.3.6.1.4.1.5951.4.1.1.50.3)
Number of compressible packets transmitted (OID:
1.3.6.1.4.1.5951.4.1.1.50.4)
Number of compressible packets received (OID:
1.3.6.1.4.1.5951.4.1.1.50.5)
Ratio of compressible data received and compressed data transmitted (OID:
1.3.6.1.4.1.5951.4.1.1.50.6)
Ratio of total data received to total data transmitted (OID:
1.3.6.1.4.1.5951.4.1.1.50.7)
Note: For more information on SNMP, see the chapter Managing the
Application Switch.
Viewing Compression Statistics Using CLI
You can also use the CLI to view detailed statistics of compression. The
following procedures describe the CLI command to view compression statistics
from the CLI.
To view the summary of compression statistics using the CLI, run the
following command:
st at cmp
To view the detailed statistics of compression, run the following command:
st at cmp - det ai l
Viewing the Statistics of a Compression Policy
This section describes the methods to view statistics of a compression policy.
Consider a scenario where the system evaluates the built-in policy,
ns_cmp_msapp, to compress response from the server. When the system
compresses the server response based on this policy, the policy gets hit. Every
time the policy is evaluated to compress any response, the policy is hit. To verify
whether the policy has been hit, you can view the statistics of the policy using
either of the following methods:
Viewing the Statistics of Compression Policy Using the Configuration
Utility
Viewing the Statistics of Compression Policy Using CLI
Viewing the Statistics of Compression Policy Using the
Configuration Utility
You can use the configuration utility to view detailed statistics of the compression
policy being evaluated by the system. The statistics that you can view are:
response action, rule, hits, bytes in, and bytes out. The following procedure
describes the steps to view the statistics of the policy ns_cmp_msapp from the
configuration utility.
To view the details of the compression policy from the configuration utility
1. In the left pane, expand Compression and click HTTP. The HTTP
Compression page appears in the right pane.
2. In the Policies tab, click the compression policy you want to view, for
example, ns_cmp_msapp. The configured parameters of the compression
policy appear in the Details section.
Viewing the Statistics of Compression Policy Using CLI
You can also use the CLI to view detailed statistics of the compression policy
configured on your system.You can view policy details such as the policy name,
rule, response action, bytes in, bandwidth saving, client transaction time, and
server response generation time. The following procedure describes the CLI
command to view the statistics of the policy ns_cmp_msapp from the CLI.
To view the statistics using the CLI, run the following command:
sh cmp pol i cy ns_cmp_msapp
The output of this command is:
Name: ns_cmp_msapp Rul e: ( ns_msi e && ( ns_mswor d | | ns_msexcel | |
ns_msppt ) )
Response act i on: COMPRESS Hi t s: 14
Byt es I n: . . . 4500 Byt es Out : . . . 4095
Bandwi dt h savi ng. . . 9. 00%Rat i o 1. 10: 1
Aver age Cl i ent t r ansact i on t i me. . . 1. 63 msec
Aver age ser ver r esponse gener at i on t i me. . . 1. 48 msec
Customizing a Compression Setup with Policies
and Actions
This section describes the procedures to customize the compression setup by
creating customized actions and policies, in addition to using built-in actions and
policies.The system enables several built-in policies when you enable
compression globally. However, compression policies can be customized to set
conditions under which compression is preformed. As mentioned earlier, a
compression policy consists of one or more expressions and an action. You can
use either the built-in actions or user-defined actions to set the action to be
performed by the policy.
Configuring Compression Actions
Configuring Compression Policies
Configuring Compression Actions
This section describes built-in compression actions and the procedures to
configure user-defined compression actions. A compression action defines the
action that the system performs on the HTTP response before forwarding it to the
client.
After evaluating the policies, the system needs to determine what action should
be performed on the files identified by the policies, that is, whether to compress
or not to compress the files, and the type of compression to be performed on the
files. Compression actions help the system to decide this action. Based on the
action that is associated with the policy being evaluated, the system compresses
or does not compress the response from the server.
You can use either the system-defined compression actions or create your own
compression actions. The compression feature in the Citrix NetScaler system
provides five system-defined compression actions. They are:
COMPRESS: When this action is set, the system uses the GZIP algorithm
to compress data for browsers that support either GZIP or both GZIP and
DEFLATE. Similarly, the system uses the DEFLATE algorithm to
compress data for browsers that support the DEFLATE algorithm. If the
browser does not support either algorithm, and the action has been set to
COMPRESS, the system does not compress data.
NOCOMPRESS: When this action is set, the system does not compress
data.
GZIP: When this action is set, the system uses the GZIP algorithm to
compress data for browsers that support GZIP compression. If the browser
does not support the GZIP algorithm and the action has been set to GZIP,
the system does not compress data.
DEFLATE: When this action is set, the system uses the DEFLATE
algorithm to compress data for browsers that support the DEFLATE
algorithm. If the browser does not support the DEFLATE algorithm, and
the action has been set to DEFLATE, the system does not compress data.
DELTA: Delta compression is a technique that encodes an updated file
with respect to one or several files called base files. The delta describes the
updated file in terms of the base files for the common sequences to be
copied and new sequences to be inserted. The recipient that receives the
encoding can reconstruct the updated file using the base files.
You can view the built-in compression actions in the HTTP Compression page
from the Configuration Utility.
To view the built-in compression actions
2. Click the Actions tab. The Actions area displays the built-in actions, as
shown in the following figure.
Built-in compression actions
Creating a Compression Action
You can create a compression action using the compression action types available
in the system. Later, you can associate the action you create with a compression
policy, thus enabling the system to perform the action, you have specified, on the
compressible content.
The following table lists the mandatory parameters that you must configure when
creating a compression action.
The following procedure describes the steps to create a compression action
Action-CMP-1 of type GZIP.
To create a compression action
Name The name of the compression action. This is a mandatory parameter
and cannot be changed.
Compression Type The type of compression action. The possible values are: compress,
gzip, deflate, delta, and nocompress.
2. Click the Actions tab, and then click Add. The Create Compression
Action dialog box appears.
3. In the Name text box, type the name of the action, for example, Action-
CMP-1.
4. In the Compression Type area, choose the compression type, for example,
GZIP.
5. Click Create and click Close. The compression action that you created
appears in the Actions tab on the HTTP Compression page. This is shown
To create a compression action using the NetScaler command line
add cmp action Action-CMP-1 GZIP
Actions tab on the HTTP compression page
Deleting a Compression Action
You can delete compression actions that are not associated with any compression
policy. If you attempt to delete an action that is associated with a policy, an error
message appears stating that the resource is in use. Also, note that only
customized compression actions can be deleted. If you attempt to delete a built-in
compression action, an error message appears stating that default actions cannot
be removed. The following procedure describes the steps to delete compression
action Action-CMP-1.
To delete a compression action
2. Click the Actions tab and select the compression action you want to delete,
for example, Action-CMP-1.
3. Click Remove, and then click Yes in the Remove message box. A message
appears in the status bar stating that the compression action has been
deleted. Also, the compression action ceases to appear in the HTTP
Compression page.
To delete a compression action using the NetScaler command line
rm cmp action Action-CMP-1
Viewing the Details of a Compression Action
You can view the details of the parameters such as the name and the compression
type of the compression actions from the Configuration Utility. The following
procedure describes the steps to view the details of a compression action Action-
CMP-1 using the configuration utility.
To view the details of a compression action
2. Click the Actions tab, then click the compression action for which you
want to view the details, for example, Action-CMP-1. The configured
parameters of the compression action appear in the Details section. This is
Details section in the Actions tab
Configuring Compression Policies
This section describes built-in compression policies and the procedures to
configure user-defined compression policies. A compression policy defines the
rules and actions to be performed by the system to compress the response from
the server.
When the system receives the HTTP response from the server, the system needs
to decide whether the content should be compressed before forwarding it to the
client. Policies play an integral role in enabling the system to make this decision.
Based on the policies configured, the system determines whether the content
should be compressed, and also, the type of compression that needs to be
performed on the compressible content. As mentioned earlier, a compression
policy consists of an expression to determine the file type to be compressed and
an action to determine the action to be performed on the file. You can use either
the built-in compression policies, or create your own compression policies.
The compression feature in the Citrix NetScaler system provides five system-
defined compression policies. These policies are activated globally when the
compression feature is enabled. The built-in compression policies can also be
bound to specific vservers.
The following table describes the built-in compression policies.
You can view the built-in compression policies in the HTTP Compression page
using the Configuration Utility. The following procedure describes the steps to
view built-in compression policies from the configuration utility.
Built-in Compression Policies Description
ns_nocmp_mozilla_47 This policy causes the system not to compress CSS files
when the request is sent from the Mozilla 4.7 Web
browser.
ns_cmp_mscss This policy causes the system to compress CSS files
when the request is sent from Microsoft Internet Explorer
Web browser.
ns_cmp_msapp This policy causes the system to compress files generated
by the following applications:
Microsoft Office Word
Microsoft Office Excel
Microsoft Office PowerPoint
ns_cmp_content_type This policy causes the system to compress data when the
response contains the header 'Content-Type' and contains
text.
ns_nocmp_xml_ie This policy causes the system not to compress when the
request is sent from Microsoft Internet Explorer with
response header 'Content-Type' and contains text or xml.
To view the built-in compression policies
2. Click the Policies tab. The Policies area displays the built-in expressions,
as shown in the following figure.
Built-in compression policies
Creating a Compression Policy with Default Values
You can create a compression policy using the default compression action types
and expressions available in the system.
when creating a compression policy with system-defined values.
The following procedure illustrates the steps to create a compression policy
Policy-CMP-1 that compresses any Microsoft Powerpoint file.
Policy Name The name of the compression policy. This is a mandatory
parameter and the value cannot be changed. The maximum length
of a policy name is 31 characters.
Response Action The type of compression action that needs to be performed when
the response matches the rules defined. The possible default values
are: compress, gzip, deflate, delta, and nocompress.
Expression The rule that the system evaluates to determine whether the HTTP
response needs to be compressed.
To create a compression policy with default values
2. On the Policies tab, click Add. The Create Compression Policy dialog
box appears.
3. In the Policy Name text box, type the name of the policy, for example,
Policy-CMP-1.
4. In the Response Action list, choose the compression action, for example,
COMPRESS.
5. Under Expression, in the Named Expressions list, choose General, then
choose the expression you want to add, for example, ns_msppt.
6. Click Add Expression. The expression you selected appears in the
Expression box.
7. Click Create and click Close. The compression policy that you create
appears in the Policies area on the HTTP Compression page.
To create a compression policy with default values using the NetScaler
command line
add cmp policy Policy-CMP-1 -resAction COMPRESS -rule ns_msppt
Creating a Compression Policy with User-Defined Values
You can create a compression policy using user-defined values for compression
action types and expressions.
when creating a compression policy with user-defined values.
The following procedure describes the steps to create a compression policy
Policy-CMP-2 that compresses any PDF file.
Policy Name The name of the compression policy. This is a mandatory parameter
and the value cannot be changed.
Response Action The type of compression action that needs to be performed when the
response matches the rules defined. The possible default values are:
compress, gzip, deflate, delta, and nocompress. You can also create
your own compression action.
Expression The rule that the system evaluates to determine whether the HTTP
response needs to be compressed.
To create a compression policy with user-defined values
box appears.
Policy-CMP-2
4. In the Response Action list, click New. TheCreate Compression Action
dialog box appears.
5. In the Name text box, type the name of the compression action, for
example, Action-CMP-2.
6. Click the compression type, for example, COMPRESS, and click Create.
The compression action you created appears in the Response Action list.
7. In the Expression area, click Add. The Add Expression dialog box
appears.
8. Choose the following options: Expression Type as General, Flow Type as
REQ, Protocol as HTTP, Qualifier as URL, and Operator as ==.
9. In the Value text box, type the value for the Qualifier, for example, /*.pdf.
10. Click OK and click Close. The expression you selected appears in the
Expression box.
appears in the Policies tab on the HTTP Compression page. This is shown
Compression policy in the HTTP Compression page
To create a compression policy with user-defined values using the
add cmp policy Policy-CMP-2 -resAction Action-CMP-2 -rule
REQ.HTTP.URL == /*.pdf
Setting the Priority of a Compression Policy
You can set the priority of a compression policy. The priority is indicated by an
integer that defines the order in which the compression policies are evaluated. A
policy with a lower priority value is evaluated first. The priority values for all
built-in policies are multiples of 10, unless set to an integer value by the user. The
priority value for a user-defined compression policy needs to be set explicitly.
The following procedure describes the steps to set the priority value of a user-
defined policy Policy-CMP-1 to 500.
To set the priority of a compression policy
2. On the Policies tab, click Global Bindings. The Bind/Unbind
Compression Policy(s) to Global dialog box appears.
3. Under Available, click the policy name, for example, Policy-CMP-1, and
click Add. The policy appears in the Configured box.
4. Double-click the Priority text box next to the policy Policy-CMP-1.
5. In the Priority box, type the priority value you want to set, for example,
500.
6. Click OK. The priority value that you have set appears in the Policies tab in
the HTTP Compression page. This is shown in the following figure.
Priority value of a compression policy
To set the priority of a compression policy using the NetScaler command
line
bind cmp global Policy-CMP-1 -priority 500
Setting the State of a Compression Policy
The state of a compression policy can be either enabled or disabled. The built-in
policies are enabled when the compression feature is enabled on the system.
However, by default, the state of a user-defined policy is disabled.
The following procedure describes the steps to set the state of the user-defined
policy Policy-CMP-2 to ENABLED.
To set the state of a compression policy
3. Under Available, click the policy name, for example, Policy-CMP-2, and
click Add. The policy appears in the Configured box. The State check box
corresponding to the selected policy is selected automatically.
4. Click OK. The state of the policy that you have set appears in the Policies
tab of the HTTP Compression page. This is shown in the following figure.
State of a compression policy
To set the state of a compression policy using the NetScaler command line
bind cmp global Policy-CMP-2 -state ENABLED
Binding a Compression Policy Globally
To enable a policy to act on any service configured on the system, you must
activate a compression policy globally. When you enable the compression
feature, all the built-in compression policies are bound globally. However, you
need to explicitly bind a user-defined policy.
The following procedure describes the steps to bind the user-defined policy
Policy-CMP-3 globally.
To bind a compression policy globally
3. Under Available, click the policy name that you want to bind, for example,
Policy-CMP-3.
4. Click Add. The policy appears in the Configured box.
5. Click OK. The Globally Bound? field of the policy that you have bound is
updated in the Policies tab on the HTTP Compression page. This is shown
Globally Bound field of the compression policy
To bind a compression policy globally using the NetScaler command line
bind cmp global Policy-CMP-3
Binding a Compression Policy to a Load Balancing Vserver
You can bind a compression policy to a load balancing vserver. If a policy is
bound only to a vserver, the policy is evaluated only by the services associated
with this vserver. However, if this policy is globally bound, in addition to being
bound to the vserver, other services can evaluate the policy.
The following procedure describes the steps to bind the user-defined policy
Policy-CMP-1 to the load balancing vserver Vserver-LB-1.
To bind a compression policy to a load balancing vserver
2. Click the name of the virtual server, for example, Vserver-LB-1, then click
Open. The Configure Virtual Server (Load Balancing) dialog box
appears.
3. Click the Policies tab and select the Active check box corresponding to the
compression policy you want to bind, for example, Policy-CMP-1.
4. Click OK. The compression policy is bound to the load balancing virtual
server.
To bind a compression policy to a load balancing server using the NetScaler
command line
bind lb vserver Vserver-LB-1 -policyName Policy-CMP-1
Modifying a Compression Policy
You can modify the actions and expressions associated with a user-defined policy.
However, you cannot make any modifications to the built-in compression
policies.
The following procedure describes the steps to modify the policy Policy-CMP-2
to change the action type to NOCOMPRESS and the value of the expression to /
*.html.
To modify a compression policy
1. In the left pane, expand Compression, then click HTTP. The HTTP
2. On the Policies tab, click the policy you want to modify, for example,
Policy-CMP-2, then click Open. The Configure Compression Policy
dialog box appears.
3. In the Response Action list, choose NOCOMPRESS.
4. In the Expression box, click the expression, then click Modify. The
Modify Expression dialog box appears.
5. In the Value text box, change the value of the Qualifier to /*.html.
6. Click OK. The expression you modified appears in the Expression box.
7. Click OK. The modified values of the policy appears in the Policies tab on
the HTTP Compression page.
To modify a compression policy using the NetScaler command line
set cmp policy Policy-CMP-2 -resAction NOCOMPRESS -rule
REQ.HTTP.URL == /*.html
Unbinding a Globally-Bound Compression Policy
You can unbind a globally-bound compression policy. However, after you unbind
the policy, it ceases to act on the services configured on the system. Note that you
cannot unbind an built-in compression policy.
The following procedure illustrates the steps to unbind the globally-bound policy,
Policy-CMP-2.
To unbind a globally-bound compression policy
3. In the Configured box, click the policy you want to unbind, for example,
Policy-CMP-2, then click Remove. The policy appears in the Available
box.
4. Click OK. The Globally Bound? field of the policy that you have bound is
updated in the Policies tab of the HTTP Compression page.
To unbind a globally-bound compression policy using the NetScaler
command line
unbind cmp global Policy-CMP-2
Unbinding a Compression Policy froma Load Balancing Vserver
You can unbind a compression policy that is bound to a load balancing vserver.
After unbinding the policy from the vserver, the policy ceases to act on the
services associated with that vserver. However, if the policy is globally bound, it
acts on the services of the vserver too.
The following procedure describes the steps to unbind the policy Policy-CMP-1
from the load balancing vserver Vserver-LB-1.
To unbind a compression policy from a load balancing vserver
2. Click the name of the virtual server, for example, Vserver-LB-1, then click
appears.
3. Click the Policies tab and clear the Active check box corresponding to the
compression policy you want to unbind, for example, Policy-CMP-1.
4. Click OK. The compression policy is unbound from the load balancing
virtual server.
To unbind a compression policy from a load balancing vserver using the
unbind lb vserver Vserver-LB-1 -policyName Policy-CMP-1
Removing a Compression Policy
You can remove a compression policy configured on the system if the policy is
not bound globally or to a vserver. If the compression policy is bound globally or
bound to a load balancing vserver, you must first unbind the policy. Note that you
cannot remove an built-in compression policy.
The following procedure describes the steps to remove the user-defined policy,
Policy-CMP-2.
To remove an unbound compression policy
2. On the Policies tab, click the policy you want to remove, for example,
Policy-CMP-2.
3. Click Remove, and click Yes in the Remove message box.
To remove an unbound compression policy using the NetScaler command
line
rm cmp policy Policy-CMP-2
Viewing the Details of a Compression Policy
You can view the details of the parameters configured for a compression policy
from the Configuration Utility.
The following procedure illustrates the steps to view the details of parameters
such as name, type of action, and the rule configured for the policy Policy-CMP-
2.
To view the details of a compression policy
2. On the Policies tab, click the compression policy you want to view, for
example, Policy-CMP-2. The configured parameters of the compression
policy appear in the Details area. This is shown in the following figure.
Detailed viewof a compression policy
Configuring Compression for Commonly Used
This section describes deployment scenarios where compression is configured
with other features such as load balancing and SSL.
Compression in Inline Mode
Compression with SSL
Compression in Inline Mode
This section explains how compression works and the procedures to configure
compression on a system operating in the inline mode. In an inline mode, the
network port of the Citrix NetScaler system is connected to the out-bound router
or switch and the server port is connected to the server-side switch or router. This
is shown in the following figure:
Compression in inline mode
In this example, the compression policies are bound to a load balancing vserver.
This allows the compression policies to act on the services bound to that vserver.
When the client request arrives, the compression policies determine whether the
client can accept compressed data. The system forwards the client request to the
server identified by the load balancing vserver. After the system receives the
response from the server, it determines whether the response is compressible
based on the compression policies configured. If the content is compressible, it is
compressed, and the compressed content is forwarded to the client.
The following model illustrates the entities you need to configure in this scenario.
(with LB and compression features
configured)
Internet
Router
Origin Server
Client
L2 switch
L2 switch
Vserver-LB: 10.102.29.120
Service-HTTP: 10.102.29.73
Policy-CMP
(compressible
content)
compressed
content
Compression in inline mode entity model
As shown in the figure, in this example, you need to configure the following: a
vserver, a service, and a compression policy, and bind the service and the policy
to the vserver. Traffic flows from the client to the vserver and is directed to the
appropriate service. The compression policy acts on that service and enables the
system to compress the response from the server if the response matches the
policy. The compressed response is sent to the client.
The following table summarizes the parameters and values of the entities you
must configure on the system operating in an inline mode.
Entity type Parameter Values
Vserver Name Vserver-LB
IP Address 10.102.29.120
Port 80
Service Type HTTP
Service Name Service-HTTP
IP Address 10.102.29.73
Port 80
Service Type HTTP
Policy Name Policy-CMP
Response Action COMPRESS
Client
CMP
policies
Client requests
Response from
server
Compressed
response
Service
LB Vserver
Origin
server
Service-HTTP
10.102.29.73
Vserver-LB
10.102.29.120
Policy-CMP
The following sections describe the procedures to configure compression in
inline mode:
1. Enable the Compression and Load Balancing Features
2. Add a Vserver for Load Balancing
3. Add a Service of Type HTTP
4. Bind the Service to the Load Balancing Vserver
5. Create a Compression Policy
6. Bind the Compression Policy to the Vserver
Enable the Compression and Load Balancing Features
To be able to configure the compression policies and the load balancing vservers
and services, you must enable both the compression and load balancing features.
The following procedure describes the steps to enable compression and load
balancing.
To enable the compression and load balancing features
3. Select the Compression and the Load Balancing check boxes.
To enable the compression and load balancing features using the NetScaler
command line
enable feature cmp lb
Expression Expression Type: General
Flow Type: REQ
Protocol: HTTP
Qualifier: URL
Operator: ==
Value: /*.asp
Add a Vserver for Load Balancing
You must add a vserver that identifies the physical server where the client request
should be sent. The following procedure describes the steps to create a vserver
named Vserver-LB with IP address 10.102.29.120, listening on port 80. The
protocol type is HTTP.
To add a load balancing virtual server
appears.
3. In the Name and IP Address text boxes, type Vserver-LB and
10.102.29.120.
6. Click Create and then click Close. The Load Balancing virtual server
Vserver-LB appears in the Load Balancing Virtual Servers page.
To add a load balancing virtual server using the NetScaler command line
add lb vserver Vserver-LB 10.102.29.120 HTTP 80
Add a Service of Type HTTP
You need to add a service of type HTTP to logically represent the physical server.
The following procedure describes the steps to create a service Service-HTTP
with 10.102.29.73 as the IP address of the server, listening on port 80.
Compression is enabled for the service by default because you have already
enabled compression on the system.
To add a service of type HTTP
3. In the Service Name and Server text boxes, type Service-HTTP and
10.102.29.73.
6. Click Create and then click Close. The service Service-HTTP appears in
the Services page.
To add a service of type HTTP using the NetScaler command line
add service Service-HTTP 10.102.29.73 HTTP 80
Bind the Service to the Load Balancing Vserver
To enable the vserver to select the service with least load to serve client requests,
you must bind the service to the load balancing vserver. The following procedure
describes the steps to bind the service Service-HTTP to the vserver Vserver-LB.
To bind the service to the vserver
2. Click Vserver-LB, then click Open. The Configure Virtual Server (Load
Balancing) dialog box appears.
3. On the Services tab, select the Active check box corresponding to Service-
HTTP.
4. Click OK. The service Service-HTTP is bound to the virtual server
Vserver-LB.
To bind the service to the vserver using the NetScaler command line
bind lb vserver Vserver-LB Service-HTTP
Create a Compression Policy
The following procedure describes the steps to create a policy Policy-CMP to
compress all ASP files that the server sends in response to the client request.
To create a compression policy
box appears.
3. In the Policy Name text box, type Policy-CMP.
4. In the Response Action list, choose COMPRESS.
5. In the Expression area, click Add. The Add Expression dialog box
appears.
6. Choose the following options: Expression Type as General, Flow Type as
REQ, Protocol as HTTP, Qualifier as URL, and Operator as ==.
7. In the Value text box, type /*.asp
8. Click OK and click Close. The expression you selected appears in the
Expression box.
appears on the Policies tab in the HTTP Compression page.
To create a compression policy using the NetScaler command line
add cmp policy Policy-CMP -resAction COMPRESS -rule REQ.HTTP.URL
== /*.asp
Bind the Compression Policy to the Vserver
You must bind the policy, you created in the previous step, to the vserver so that
the policy acts on the services associated with the vserver. The following
procedure describes the steps to bind the policy Policy-CMP to the vserver
Vserver-LB.
To bind the compression policy to the vserver
2. Click the name of the virtual server, for example, Vserver-LB, then click
appears.
compression policy you want to bind, for example, Policy-CMP.
server.
To bind the compression policy to the vserver using the NetScaler
command line
bind lb vserver Vserver-LB -policyName Policy-CMP
Compression with SSL
This section explains how compression works with SSL to compress content and
encrypt the compressed content. In this scenario, compression, SSL, and load
balancing are enabled on the system, as shown in the following figure.
Compression with SSL topology
In this example, the compression policies are bound to a load balancing vserver of
type SSL. This allows the compression policies to act on the services bound to
that vserver. The system performs compression based on the compressibility of
the response and compression awareness of the client. Compressed content is
encrypted before being forwarded to the client.
The following diagram illustrates the entities you must configure in this scenario.
(with LB, SSL, and compression
features configured)
Internet
Router
Origin Server
Client
L2 switch
L2 switch
Vserver-SSL: 10.102.29.50: 443
Service-SSL: 10.102.29.61: 443
Cert-SSL
Policy-CMP-1
(compressible
content)
compressed and
encrypted content
Compression with SSL entity model
As shown in the figure, in this example, you need to configure the following: a
vserver, a service, a compression policy, and an SSL certificate, and bind the
service, the policy, and the certificate to the vserver. Traffic flows from the client
to the vserver and is directed to the appropriate service. The compression policy
acts on that service and enables the system to compress the response from the
server if the response matches the policy. The SSL certificate enables the system
to encrypt the compressed content. The compressed response is sent to the client.
Note: If compression and SSL are enabled, content is flagged as Cache-
Control: no-cache, and foreign languages are defined using HTTP-Meta Equiv
headers, the content may not render properly due to a bug in Internet Explorer. To
work around this issue, use HTTP headers to specify the language instead of
HTML.
The following table summarizes the parameters and values of the entities that you
must configure on the system.
Vserver Name Vserver-SSL
IP Address 10.102.29.50
Port 443
Service Type SSL
Service Name Service-SSL
IP Address 10.102.29.61
Port 443
Service Type SSL
Client
CMP
policies
Client requests
Response from
server
Compressed
and
encrypted
response
Service
LB Vserver
Origin
server
Service-HTTP
10.102.29.61
Vserver-LB
10.102.29.50
Policy-CMP SSL
certificate Cert-SSL
The following sections describe the procedures to configure compression with
SSL:
1. Enable the Compression, Load Balancing, and SSL Features
2. Add a Vserver of Type SSL
3. Add a Service of Type SSL
4. Bind the Service to the Vserver
5. Create a Compression Policy
6. Bind the Compression Policy to the Vserver
7. Add an SSL Certificate
8. Bind the SSL Certificate to the Vserver
Enable the Compression, Load Balancing, and SSL Features
To create vservers, services, SSL certificates, and compression policies, you must
enable the compression, load balancing, and SSL features.
To enable the compression, load balancing, and SSL features
3. Select the Compression, Load Balancing, and SSL check boxes.
To enable the compression, load balancing, and SSL features using the
enable feature cmp lb ssl
Policy Name Policy-CMP-1
Response Action COMPRESS
Expression ns_msppt
SSL certificate Name Cert-SSL
Certificate Filename /nsconfig/ssl/s2-root.cert
Key Filename /nsconfig/ssl/s2-root.key
Add a Vserver of Type SSL
The following procedure describes the steps to create a vserver named Vserver-
SSL with IP address 10.102.29.50, listening on port 443. The protocol type is
SSL.
To add a load balancing vserver
appears.
3. In the Name and IP Address text boxes, type Vserver-SSL and
10.102.29.50.
5. In the Protocol list, choose SSL.
6. Click Create and then click Close. The Load Balancing virtual server
Vserver-SSL appears in the Load Balancing Virtual Servers page.
To add a load balancing vserver using the NetScaler command line
add lb vserver Vserver-SSL 10.102.29.50 SSL 443
Add a Service of Type SSL
The following procedure describes the steps to create a service of type SSL
named Service-SSL with 10.102.29.61 as the IP address of the server, listening on
port 443. Compression is enabled for the service by default because you have
already enabled compression on the system.
To add a service of type SSL
3. In the Service Name and Server text boxes, type Service-SSL and
10.102.29.61.
5. In the Protocol list, choose SSL.
6. Click the Advanced tab. The Advanced area appears.
7. Click Create and then click Close. The service Service-SSL appears in the
Services page.
To add a service of type SSL using the NetScaler command line
add service Service-SSL 10.102.29.61 SSL 443
Bind the Service to the Vserver
To enable the vserver to select the service with least load to serve client requests,
you must bind the service to the load balancing vserver. The following procedure
describes the steps to bind the service Service-SSL to the vserver Vserver-SSL.
To bind the service to the vserver
2. Click Vserver-SSL, then click Open. The Configure Virtual Server
(Load Balancing) dialog box appears.
3. In the Services tab, select the Active check box corresponding to Service-
SSL.
4. Click OK. The service Service-SSL is bound to the virtual server Vserver-
SSL.
To bind the service to the vserver using the NetScaler command line
bind lb vserver Vserver-SSL Service-SSL
Create a Compression Policy
The following procedure illustrates the steps to create a policy Policy-CMP-1 to
compress all Microsoft Powerpoint files that the server sends in response to the
client request.
To create a compression policy
box appears.
Policy-CMP-1.
4. In the Response Action list, choose the compression action, for example,
COMPRESS.
5. Under Expression, in the Named Expressions list, choose General, then
choose the expression you want to add, for example, ns_msppt.
6. Click Add Expression. The expression you selected appears in the
Expression box.
7. Click Create and click Close. The compression policy, which you have
created, appears in the Policies area on the HTTP Compression page.
To create a compression policy using the NetScaler command line
add cmp policy Policy-CMP-1 -resAction COMPRESS -rule ns_msppt
Bind the Compression Policy to the Vserver
In order for the policy to act on the services associated with the vserver, you must
bind the policy to the vserver. The following procedure describes the steps to bind
the policy Policy-CMP-1 to the vserver Vserver-SSL.
To bind a compression policy to a load balancing vserver
2. Click the name of the virtual server, for example, Vserver-SSL, then click
appears.
compression policy you want to bind, for example, Policy-CMP-1.
server.
To bind the compression policy to the vserver using the NetScaler
command line
bind lb vserver Vserver-SSL -policyName Policy-CMP-1
Add an SSL Certificate
To enable the system to encrypt the compressed content before sending it to the
client, you must add an SSL certificate. The following procedure describes the
steps to create a certificate named Cert-SSL.
To add an SSL certificate
3. In the Certificate-Key Pair Name text box, type the name of the
certificate, for example, Cert-SSL.
4. In the Certificate Filename text box, either type the path to the certificate
file, or browse and insert the path, for example, /nsconfig/ssl/s2-root.cert.
5. In the Key Filename text box, either enter the path to the key file or browse
and insert the path, for example, /nsconfig/ssl/s2-root.key.
6. Click Install and click Close. The certificate Cert-SSL appears in the SSL
Certificates page.
To add an SSL certificate using the NetScaler command line
add ssl certkey Cert-SSL -cert /nsconfig/ssl/s2-root.cert -key /
nsconfig/ssl/s2-root.key
Bind the SSL Certificate to the Vserver
You need to bind the certificate, you created in the previous step, to the vserver so
that the certificate acts on the services associated with the vserver. The following
procedure describes the steps to bind the certificate Cert-SSL to the vserver
Vserver-SSL.
To bind the SSL certificate to the vserver
2. Click Vserver-SSL, then click Open. The Configure Virtual Server
3. In the SSL Settings tab, under Available, select Cert-SSL-1 and click
Add. The certificate, Cert-SSL, appears in the Configured box.
4. Click OK. The certificate Cert-SSL is bound to the virtual server Vserver-
SSL.
To bind the SSL certificate using the NetScaler command line
bind ssl certkey Vserver-SSL Cert-SSL
Configuring TCP Window Scaling
TCP window scaling option increases the TCP receive window size beyond its
maximum value of 65,535 bytes. This TCP option is defined in RFC 1323. The
window scaling option is required for efficient transfer of data over Long Fat
Networks (LFNs).
A TCP window determines the amount of outstanding (unacknowledged by the
recipient) data a sender can send on a particular connection before it gets any
acknowledgment from the receiver. The main reason for the window is flow
control.
The window size field in the TCP header is 16 bits long, which limits the ability
of the sender to advertise a window size larger than 65535 or ( 2^16 - 1). The TCP
window scale extension expands the definition of the TCP window to 30 bits by
using a scale factor to carry this value in the 16 bit window field of the TCP
header. In NetScaler the window scale expands the definition of the TCP window
to 24 bits. The scale factor is carried in the new TCP window scale option. This
option is sent only in a SYN packet (a segment with the SYN bit on).
The new window size is calculated by the receiver:
[right shifting the bits of the received window size by the scale factor value]
which is equivalent to
[(2^scale factor) * received window size]
Before configuring window scaling, ensure that:
You do not set a high value for the Scale Factor because this could have
adverse effects on the NetScaler and the network.
You have enabled SACK (selective acknowledgement).
You do not configure window scaling unless you clearly know why you
want to change the window size.
Window scaling will work only when both hosts in the TCP connection
send a window scale option during connection establishment. If only one
side of a connection is sets this option, windows scaling will not be used for
that connection.
Each connection of the same session (such as, TCP session between Client
and NetScaler and TCP session between NetScaler and Server having the
same request/response) are independent Window Scaling sessions. It is
possible to have a window scaling between the client and a Citrix NetScaler
and not the a Citrix NetScaler and a server.
By default, the window scaling is not enabled. The following table describes the
parameters used to configure window scaling.
The following procedure includes example for illustrates a window scaling
configuration in which the window scaling option in the NetScaler is enabled and
the window scaling factor is set to 5.
To configure Window Scaling using the configuration utility
1. In the navigation pane, expand System, click Settings.
2. In the Settings page, under Global Settings, click global system settings.
3. In the Configure Global Settings dialog box, under TCP, select Windows
Scaling checkbox.
4. In the Factor textbox, type a windows scaling factor for example, 5.
5. Click Ok.
To configure Window Scaling using the NetScaler command line
set ns tcpParam -WS ( ENABLED | DISABLED ) -WSVal value
Example:
set ns tcpParam -WS ENABLED -WSVal 5
Configuring Selective Acknowledgement (SACK)
The NetScaler supports Selective Acknowledgement (SACK), as defined in RFC
2018. Using SACK, the data receiver (either a Citrix NetScaler or a client)
notifies the sender about all the segments that have been received successfully. As
a result, the sender (either a Citrix NetScaler or a client) needs to retransmit only
those segments that were lost during transmission. This improves the
performance of data transaction. SACK is important in Long Fat Networks
(LFNs).
By default, SACK is disabled. The following describes the procedure for
enabling SACK.
Windows scaling
factor
Used to define the new window size in window scaling.
The default value is 4. The minimum value is 0 and
maximum value is 8.
To enable Selective Acknowledgement (SACK) using the Configuration
Utility
1. In the navigation pane, expand System, click Settings.
2. In the Settings page, under Global Settings, click global system settings.
3. In the Configure Global Settings dialog box, select Selective
Acknowledgement checkbox. and click Ok.
To enable Selective Acknowledgement (SACK) using the NetScaler
command line
set ns tcpParam - SACK value
Example:
set ns tcpParam -SACK ENABLED
CHAPTER 9
Protection Features
This chapter describes how Citrix NetScaler System protects your servers from
malicious attacks with features like content filtering, protection against different
types of DoS attacks, surge protection, and priority queuing. The topics in this
chapter include:
How Citrix NetScaler Enforces Protection
How Content Filtering Works
Configuring Layer 3-4 Denial of Service (SYN) Protection
How Surge Protection Works
How Priority Queuing Works
How Layer 7 Denial of Service Protection Works
How Citrix NetScaler Enforces Protection
The Citrix NetScaler System provides continuous service availability through
application-level protection. The Citrix NetScaler System protection features
include:
Insulating from traffic surges
Ensuring that applications can continue to respond when servers are
working at capacity or applications are experiencing processing delays
Blocking of worm attacks by content-intelligent filtering
Protecting from wire-speed, application-level DoS attacks
Delivering applications securely
How Content Filtering Works
The content filtering feature of the system helps repel malicious attacks by
comparing incoming request against rules that you configure based on HTTP
URLs or headers.
Content filtering prevents unwanted requests from reaching the protected server.
The system can either drop a suspicious request or send an error page.
you can deploy an edge system with content-level filtering to prevent users from
accessing undesired content. You can configure the rules to either send an error
message or terminate a connection when the system finds the specified content in
the HTTP headers (URL or Host header).
Content filtering uses the traffic management logic to filter HTTP Web
transaction requests according to user-defined policies.
To configure filter policies, you must use Citrix NetScaler policy engine to create
rules based on the following combinations:
URL
URL query
URL token
HTTP method
HTTP version
Standard HTTP header
Standard HTTP header value
Custom HTTP header
Custom header value, and, or client source IP address
Note: For more information about policies, see the Policy Expressions Guide.
The content filtering feature supports the following request and response actions:
Request actions
Add: Adds an HTTP header
Reset: Terminates the connection
Forward: Redirects the request to a service
Drop: Drops the request
Chapter 9 Protection Features 509
Corrupt: Corrupts an HTTP header
Response actions
Add: Adds an HTTP header
ErrorCode: Returns a response code for a request
Corrupt: Corrupts an HTTP header
Configuring Content Filtering
This section describes the procedures to enable and configure content filtering
feature on the Citrix NetScaler System. The steps involved are:
Enable Content Filtering
Create Actions
Create Filter Policy
Bind the Filter Policy
Note: For information about configuring content filtering from the CLI, see the
Command Reference Guide.
Enabling Content Filtering
By default, content filtering is disabled. To enable the feature, change the system
settings as described in the following procedure.
To enable content filtering
1. In the left pane, expand System, and select Settings. The Settings page
2. Click basic features. The Configure Basic Features dialog box appears.
3. Select the Content Filtering check box, and click OK. The Enable/
Disable feature(s) dialog box appears. Click Yes.
A message in the status bar indicates that the selected feature is enabled.
Disabling Content Filtering
The following procedure describes the steps to disable the content filtering
feature.
To disable content filtering
2. Click basic features. The Configure Basic Features dialog box appears.
3. Clear the selection for the Content Filtering check box, and click OK. The
Enable/Disable feature(s) dialog box appears. Click Yes.
A message in the status bar indicates that the selected feature is disabled.
Creating Content Filter Action
The following procedure describes the steps to create a filter action.
To create a filter action
1. In the left pane, expand Protection Features, and select Filter. The Filter
2. Select the Actions tab and click Add. The Create Filter Action dialog box
appears.
3. In the Action Name text box, type a name, for example, actionReset.
4. In the Qualifier drop-down list, select an action, for example, Reset.
5. Click Create and click Close. The Actions list displays the action you
created and a message in the status bar indicates that the action is
configured.
Note: You can add multiple actions with different qualifiers.
Creating Content Filter Policy
The following procedure describes the steps to create a filter policy.
To create a content filtering policy
2. Click Add. TheCreate Filter Policy dialog box appears.
3. In the Filter Name text box, type a name, for example, filter-CF-1.
4. Select either of the action options, for example, Request Action, and in the
drop-down list, select the action to be performed on the request. For
example, RESET.
5. In the Expression frame, select an option from the Match Any Expression
drop-down list, for example, Match Any Expression.
6. Click Add. The Add Expression dialog box appears.
7. In the Expression Type drop-down list select an expression, for example,
General.
8. Select a Flow Type, Protocol, Qualifier, and Operator. For example,
REQ, HTTP, URL, and CONTAINS.
9. In the Value text box, type a value, for example, asp, and click OK. The
expression is added in the Expression text box. Repeat this step to add as
many expressions as you need to.
10. Click Close, and click Create on the Create Filter Policy dialog box. The
filter policy appears in the Filter list.
Note: You can add more than one filter policy to handle different requests
and responses.
11. Click Close.
Note: To remove a filter policy, select the policy in the Policies tab and click
Remove. The policy is deleted.
Binding and Unbinding the Filter Policy
You must bind the filter policies that you create before the system can use them.
You can bind the policies globally or locally to a particular vserver. Policies that
you bind globally are evaluated each time the traffic directed to a vserver matches
the conditions set in the policy. Policies that you bind to particular vservers are
evaluated only when the vserver to which the policy is bound receives the traffic
that matches the policy rule.
To globally bind a filter policy
2. In the Policies tab, select the policy that you want to bind and click Global
Bindings. The Bind/Unbind Filter Policies dialog box appears.
3. In the Available frame, in the Policy Name list box, select a policy, for
example, CF1, and click Add. The policy is added to the Configured list.
Note: To select multiple policies from the list, press the Ctrl key.
4. Click OK and click Close after you add the policies that you want to bind.
The policies you have bound display a check mark and Yes in the Globally
Bound column of the Policies tab.
To bind to a vserver
1. Expand the Load Balancing node and click Virtual Servers. The Load
Balancing Virtual Servers page appears in the right pane.
2. Select the vserver from the list to which you want to bind the content
filtering policy and click Open. The Configure Virtual Server (Load
3. Select the Policies tab and select the check box in the Active column for the
filter policy that you want to bind to the vserver, and click OK.
The content filtering policy is bound to the vserver.
To unbind a filter policy
2. In the Policies tab, click Global Bindings. The Bind/Unbind Filter
Policies dialog box appears.
3. In the Configured list, select the policy you want to unbind and click
Remove. The policy is moved from the Congfigured list to the Available
list.
4. Click OK. The Global Binding column value in the Policies tab changes to
No.
Configuring Content Filtering for a Commonly
Used Deployment Scenario
This section describes how to configure content filtering for a commonly used
deployment scenario. You can follow the instructions described in this section to
implement content filtering. if a requested URL contains root.exe or cmd.exe, the
content filtering policy, filter-CF-nimda is evaluated and the connection is
reset.You must do the following:
Enable content filtering
Enable Load Balancing
Create servers and services
Bind service to vserver
Create filter policy
Bind filter policy globally or to a vserver
The following table summarizes the parameters and values of the entities you
To enable content filtering
1. In the left pane, expand System, and click Settings. The Settings page
Entiry Type Parameter Value
Load Balancing vserver
(content filter server)
Name vserver-CF-1
IP Address 10.102.1.1
Protocol HTTP
Port 80
Service Service Name service-CF-1
Server 10.102.11.1
Protocol HTTP
Port 80
Filter Filter Name filter-CF-nimda
Request Action Reset
Expression Type General
Flow Type REQ
Protocol HTTP
Qualifier URL
Operator CONTAINS
Value cmd.exe
Value root.exe
3. Select the Content Filtering check box, and click OK. The Enable/
Disable feature(s) dialog box appears. Click Yes.
You must enable the load balancing feature if it is not already enabled to
configure the vservers and services.
To enable the load balancing feature
3. Select theLoad Balancing check box and click OK. The Enable/Disable
feature(s) dialog box appears. Click Yes.
To add a load balancing vserver
appears.
3. In the Name text box, type the name of the virtual server for example,
vserver-CF-1.
4. In the Protocol drop-down list, select HTTP.
5. Clear the Directly Addressable check box.
6. In the Method and Persistence tab, in the LB Method drop-down list,
select URL Hash.
7. Click Create and click Close. The load balancing vserver, which you have
created, appears in the Load Balancing Virtual Servers page.
and the IP address of the server, for example, service-CF-1 and 10.102.11.1.
5. In the Protocol drop-down list, select HTTP.
6. Click Create, and click Close. The service, which you have created,
appears in the Services page.
2. Click vserver-CF-1 and click Open. The Configure Virtual Server (Load
3. In the Services tab, select the Active check box corresponding to service-
CF-1 and click OK. The service service-CF-1 is bound to the vserver
vserver-CF-1.
To create a filter policy
1. In the left pane, expand Protection Features, and click Filter. The Filter
2. Click Add. TheCreate Filter Policy dialog box appears.
3. In the Filter Name text box, type the name, filter-CF-nimda.
4. Select the Request Action option, and in the drop-down list, select
RESET.
5. In the Expression frame, select Match Any Expression from the drop-
down list and click Add. The Add Expression dialog box appears.
6. In the Expression Type drop-down list select General.
7. In the Flow Type drop-down list, select REQ, in the Protocol drop-down
list, select HTTP, in the Qualifier drop-down list, select URL, and in the
Operator drop-down list, select CONTAINS.
8. In the Value text box, type cmd.exe, and click OK. The expression is added
in the Expression text box.
9. To create another expression, repeat Steps 7 and 8, and in the Value text
box, type root.exe, click OK and click Close.
10. Click Create on the Create Filter Policy dialog box. The filter policy
appears in the Filter list.
11. Click Close.
To globally bind the filter
2. In the Policies tab, select the policy that you want to bind and click Global
Bindings. The Bind/Unbind Filter Policies dialog box appears.
3. In the Available frame, in the Policy Name list box, select the policy filter-
CF-nimda, and click Add. The policy is added to the Configured list.
4. Click OK and click Close.
5. The policy you have bound displays a check mark and Yes in the Globally
Bound column of the Policies tab.
To bind the filter to the vserver
1. Expand the Load Balancing node and click Virtual Servers. The Load
Balancing Virtual Servers page appears in the right pane.
2. In the vservers list, select vserver-CF-1 to which you want to bind the
content filtering policy and click Open. The Configure Virtual Server
3. Select the Policies tab and in the Active column, select the check box
corresponding to the policy filter-CF-nimda, and click OK.
The content filtering policy is bound to the vserver.
To Verify the Configuration
The Hits counter gets incremented every time there is a request for a URL
containing root.exe or cmd.exe. To verify whether the policy is evaluated or not,
do one of the following:
At the Configuration Utility, expand Protection Features, click Filter, and
in the right pane, select the filter policy filter-CF-nimda. The bottom of the
pane displays the following:
Request Profile: RESET
Rule: REQ.HTTP.URL CONTAINS cmd.exe || REQ.HTTP.URL
CONTAINS root.exe
Hits: 0
At the command prompt, type the following command:
sh f i l t er pol i cy f i l t er - CF- ni mda
It displays the following output:
Name: f i l t er - CF- ni mda
Rul e: REQ. HTTP. URL CONTAI NS cmd. exe | | REQ. HTTP. URL CONTAI NS
r oot . exe
Request act i on: RESET
Response act i on:
Hi t s: 0
Note: The Hits parameter displays a numerical value that denotes the
number of times the policy is evaluated. In the preceding steps, the Hits
shows as zero because no request for the URL containing cmd.exe or
root.exe was made.
Configuring Layer 3-4 Denial of Service (SYN) Protection
This section explains how the system protects against Denial of Service (DoS)
attacks.
Note: Setting the SYN cookie logic requires no external configuration as it is
enabled by default.
Howthe SystemProtects Against DoS Attack
When a client attempts to establish a TCP connection to a server, the client and
server exchange a prescribed sequence of messages. This connection technique
applies to all TCP connections, for example, telnet, web, email.
The sequence for TCP connections is:
The client sends a SYN message to the server
The server acknowledges the SYN message by sending a SYN-ACK
message to the client
The client finishes establishing the connection by responding to the server
with an ACK message
When the sequence is complete, the connection between the client and server is
open, and data can be exchanged between the client and server.
A Scenario for DoS Attack
A potential for attack arises when the server has sent an acknowledgement (SYN-
ACK) to the client but has not received the ACK message from the client. This is
referred to as a half-open connection in the server.
The server system memory has a data structure that describes all pending
connections. This data structure is of a finite size but can be made to overflow
intentionally by creating too many half-open connections. By IP spoofing half-
open connections are created, in which the attacking system sends large number
of SYN messages to the victim server system. These messages appear to be
legitimate, but they reference a client system that does not respond to the SYN-
ACK messages.
The victim server system never receives the final ACK messages. The data
structures of the half-open connection on the victim server eventually fill up the
memory resources, and the system is unable to accept new incoming connections
until the table is emptied.
Typically, a time-out is associated with a pending connection, so that the open
connections eventually expire and the victim server system recovers. However,
the attacking system can continue to send IP-spoofed packets requesting new
connections faster than the victim server system can expire the pending
connections. The memory of the victim system is eventually exhausted and the
system may crash or hang, resulting in a denial of service to legitimate clients.
Using SYN Cookies
The Citrix NetScaler System defends against SYN flood attacks by using SYN
cookies. The Citrix NetScaler System sends cookies to the requesting client, but
does not keep the state on the system for the initiated session. Because no state is
kept, no memory is allocated in the system, and normal TCP communications
with legitimate clients continue uninterrupted.
The Citrix NetScaler SYN-cookie logic is always enabled. The system allocates
memory for a connection on receiving the final ACK packet for non-HTTP
traffic, and on receiving the HTTP request for HTTP traffic.
Advantages of SYN Cookie
SYN cookie logic in the system ensures the following:
The memory of the system is not wasted on false SYN packets; instead
memory is used to serve legitimate clients.
Normal TCP communications with legitimate clients continue
uninterrupted, even when the web site is under SYN flood attack.
Because the system allocates memory for the connection state only after it
receives the HTTP request, it prevents a Web site from experiencing idle
connection attacks.
How Surge Protection Works
This section describes how the Citrix NetScaler system uses the surge protection
feature to adjust traffic sent to the servers.
When a surge in client requests overloads a server, the server response becomes
slow, and is unable to respond to new requests. The surge protection feature
ensures that connections to the server occur at a rate that the server can handle.
The response rate depends on how surge protection is configured.
The system also tracks the number of connections to the server, and based on this
knowledge, it adjusts the rate at which it opens new server connections. The
following figure illustrates how surge protection is configured to handle traffic to
a Web site:
Note: If the system is installed at the edge of the network, where it interacts
with network devices on the client side of the Internet, the surge protection
feature must be disabled. Surge protection must also be disabled if Using Source
IP (USIP) mode of the system is enabled.
The following example and illustration show the request and response rates for
two cases. In one case, surge protection is disabled, and in the other it is enabled.
Case A: When a surge occurs with surge protection enabled, the server sends
proper responses to the requests. When the surge is over, the request rate matches
the response rate. This indicates that the server was not affected by the attack.
Case B: When surge protection is disabled and a surge occurs, the response rate is
reduced to zero. This indicates that the server has gone down. When the server
recovers from the crash, usually within several minutes, it begins sending spikes
of resets, which is an abnormal behavior. The server also responds to new
requests abnormally. With the next surge, the server goes down again. This
example shows how server response can be destroyed by a surge when the surge
protection feature is turned off.
The following figure illustrates the requests and response scenarios when surge
protection is in enabled mode and when it is in disabled mode.
Request/response rate
Configuring Surge Protection
The following section describes the procedures to configure surge protection.
Disabling and Re-enabling Surge Protection
The surge protection feature is enabled by default. When surge protection is
enabled, it is active for any service that you add.
To disable surge protection
2. Click advanced features. The Configure Advanced Features dialog box
appears.
3. Clear the selection from the Surge Protection check box, and click OK.
4. Click Yes on the Enable/Disable Feature(s) dialog box. A message in the
status bar indicates that the feature is disabled.
To re-enable surge protection
appears.
3. Select the Surge Protection check box, and click OK.
4. Click Yes on the Enable/Disable Feature(s) dialog box. A message in the
status bar indicates that the feature is enabled.
To disable surge protection for a particular service
1. In the left pane, expand Load Balancing, and select Services. The list of
configured services display in the right pane.
2. Select the service for which you want to disable the surge protection feature
and click Open. The Configure Service dialog box appears.
3. Click the Advanced tab and scroll down.
4. In the Others frame, clear the selection from the Surge Protection check
box, and click OK.
A message in the status bar indicates that the service is successfully
configured.
Note: Surge protection works only when both the feature and the service setting
are enabled.
Setting Threshold for Surge Protection
To set the rate at which the system opens connections to the server, you must
configure the threshold and throttle values for surge protection.
To set the threshold for surge protection
2. Click global system settings. The Configure Global Settings dialog box
appears.
3. In the Base Threshold text box, enter a numeric value, for example, 200.
Base Threshold: Specifies the maximum number of server
connections that can be open before surge protection is activated. The
maximum number of server connections that can be configured is
32,767.
4. In the Throttle drop-down list, select an item, for example, normal.
Throttle: Specifies the rate at which the system allows connections
to the server to be opened.
aggressive: Specify this option when the connection-handling
and surge-handling capacity of the server is low and the
connection needs to be opened in a stringent manner. When you
set aggressive, the base threshold is set to a default value of 16.
normal: Specify this option when there is no external load
balancer behind the system or downstream. The base threshold
is set to a value of 200. Normal is the default throttle option.
relaxed: Specify this option when the system performs load
balancing, and when the web servers can handle a high number
of surge connections. The base threshold is set to a value of
500.
5. Click OK. A message in the status bar indicates that the global settings are
configured.
The following figure shows the surge protection curves that result from setting
the throttle rate to relaxed, normal, or aggressive. Depending on the configuration
of the server capacity, you can set base threshold values to generate appropriate
surge protection curves.
The following paragraphs explain how your configuration settings affect the
behavior of surge protection:
If you do not specify a throttle rate, it is set to normal, the default value, and
the base threshold is set to 200, as shown in the preceding figure.
If you specify a throttle rate (aggressive, normal, or relaxed) without
specifying a base threshold, the curve reflects the default values of the base
threshold for that throttle rate. For example, if you set the throttle rate to
relaxed, the resulting curve will have the base threshold value of 500.
If you specify only the base threshold, the entire surge protection curve
shifts up or down, depending on the value you specify, as shown in the
figure that follows.
If you specify both a base threshold and a throttle rate, the resulting surge
protection curve is based on the set throttle rate and adjusted according to
the value set for the base threshold.
In the following figure, the lower curve (Aggressive 1) results when the throttle
rate is set to aggressive but the base threshold is not set. The upper curve
(Aggressive 2) results when the base threshold is set to 500, but the throttle rate is
not set. The second upper curve (Aggressive 2) also results when the base
threshold is set to 500, and the throttle rate is set to aggressive.
Aggressive Rate with the Default or a Set Base Threshold
Configuring Surge Protection for a Commonly
Used Deployment Scenario
How Priority Queuing Works
The priority queuing feature lets you filter incoming HTTP traffic based on
categories you create and define. Priority queuing directs high-priority requests to
the server ahead of low-priority requests. You can create a priority queuing policy
rule that specifies a priority, weight, threshold, and implicit action.
When an incoming request matches the rule of a particular priority queuing
policy, the request is associated with that rule.
You can create a priority queuing policy that triggers a corresponding action
when the threshold you specify is met. When the threshold has a positive value,
the request is placed in the SURGE queue. If a threshold is not specified, the
request is placed in one of the higher-priority queues.
You can bind up to three priority queuing policies to a single load balancing
virtual server. The priority levels are:
Level 1
Level 2
Level 3
A Level 1 policy is higher in priority than a Level 2 policy. A weight can range
from 0 to 101 (101 representing infinite weight).
Note: For more information about defining policy rules and expressions, see
the chapter Cache Redirection.
You must assign unique names to the priority queuing policies.Policy names can
be up to 31 characters. Multiple policies bound to the same load balancing virtual
server cannot have the same priority level. No two vservers that have one or more
common underlying physical services can have priority queuing configured or
enabled on both vservers simultaneously.
Configuring Priority Queuing
To configure priority queuing on Citrix NetScaler System, perform the following
procedures described in the sections that follow:
Enable the load balancing feature
Define a server and service
Define a load balancing virtual server
Bind the service to the load balancing virtual server
Enable the priority queuing feature
Create the priority queuing policies
Bind the priority queuing policies to the load balancing virtual server
Enable priority queuing on load balancing virtual server
For information about enabling load balancing, creating servers, vservers and
services, and binding the services, see the Load Balancing chapter in this guide.
Enabling Priority Queuing
To use the priority queuing feature on Citrix NetScaler System, you must enable
it, as described in the following procedure.
To enable priority queuing
2. Click advanced features. TheConfigure Advanced Features dialog box
appears.
3. Select the Priority Queuing check box, click OK, and click Yes on the
Enable/Disable Feature(s) dialog box.
Creating the Priority Queuing Policies
To add a priority queuing policy, you can use the GUI or the CLI. At the CLI use
the add pq pol i cy command. The following procedure describes the steps to
create a policy at the GUI.
Note: For more information about using the CLI commands, see Command
Reference Guide.
To create a priority queuing policy
1. In the right pane, expand Protection Features, and select Priority
Queuing. The Priority Queuing page appears in the right pane.
2. Click Add. The Create PQ Policy dialog box appears.
3. In the Policy Name text box, type the name, for example, PQ1.
4. In the Rule text box, you can either enter the policy expression or click
New to create a policy expression. If you click New, perform the following
steps:
A. In the Create Expression dialog box, click Add. The Add
Expression dialog box appears.
B. In the Expression Type drop-down list select a value, for example,
General.
C. Select a Flow Type, Protocol, Qualifier, and Operator. For
example, REQ, HTTP, URL, and CONTAINS.
D. In the Value text box, type a value, for example, test and click OK.
The expression is added in the Expression text box.
E. Click Create.The expression appears in the Rule text box.
5. In the Priority and Weight text boxes, type numeric values, for example, 1
and 30.
6. Enter a numeric value for either Queue Depth or Policy Queue Depth, for
example 234, and click Create.
Queue Depth: Defines the total number of waiting clients or requests
on the virtual server to which the policy is bound.
Policy Queue Depth: Defines the total number of waiting clients or
requests belonging to the policy:
The policy is created and appears in the Priority Queuing page.
Note: To create additional priority queuing policies, repeat the procedure in the
preceding section, and click Close after you finish.
Binding and enabling the Priority Queuing
Policies
This section describes how to bind and enable the priority queuing policies to the
load balancing virtual servers.
To bind and enable a policy
1. In the left pane, expand Load Balancing and select Virtual Servers. The
2. In the list of available vservers, select the vserver to which you want to bind
the priority queuing policy and click Add. The Configure Virtual Server
3. Click the Policies tab, and select the Active check box for the priority
queuing policy that you created.
4. Click the Advanced tab, and select the PQ check box.
5. Click OK. A message in the status bar indicates that the virtual server is
configured.
Citrix recommends you to verify that the priority queuing policies you created in
the preceding procedure are correctly bound. To verify, in the Load Balancing
Virtual Servers page, select the virtual server that you configured. The Details
section at the bottom of the right pane displays the configuration.
Setting up Weighted Queuing
With priority queuing set, low-priority requests are typically kept on hold while
higher-priority requests are served. The low priority requests may be delayed if
there is a constant flow of higher-priority requests and the system is configured to
serve the higher-priority requests first.
To prevent delays for low-priority requests across multiple priority levels, you
can configure weighted queuing for serving requests. The default weights for the
priorities are:
Gold - Priority 1 - Weight 3
Silver - Priority 2 - Weight 2
Bronze - Priority 3 - Weight 1
Weight 0 specifies the system to serve this priority level only if no requests are
stored in the other queues. The maximum weight that can be assigned is 101. A
weight of 101 specifies the system to serve this priority level first, regardless of
the requests waiting in other queues. This queue starves all other priority queues.
Weights assigned to higher priorities must be larger than weights assigned to
lower priorities. For example, a weight assigned to priority 1 must be greater than
a weight assigned to a priority of 2.
How Layer 7 Denial of Service Protection Works
Internet hackers can bring down a site by sending a surge of GET requests or
other HTTP-level requests. Layer 7 Denial of Service Protection provides an
effective way to prevent such attacks from being relayed to the server. This
feature also ensures that a Citrix NetScaler System located between the internet
cloud and the servers is not brought down by the attack while protecting the
servers.
Most attackers on the Internet use applications that discard responses to reduce
computation costs, and minimize their size to avoid detection. The attackers focus
on speed, devising ways to send attack packets, establish connections or send
HTTP requests as rapidly as possible.
A typical approach to prevent these attacks is effective in most cases. However,
for more complicated attack methodologies including the use of real HTTP
clients as attacking tool, the simpler prevention approaches can fail to protect the
servers.
Real HTTP clients such as Internet Explorer, Firefox, or NetScape browsers can
understand HTML Refresh meta tags, J ava scripts, and cookies. In standard
HTTP the clients have most of these features enabled. However, the dummy
clients used in DoS attacks cannot parse the response from the server. If the
malicious clients attempt to parse and send requests intelligently, it becomes
difficult for them to launch the attack aggressively.
When the Citrix NetScaler System detects an attack, it responds to 0% to 100% of
incoming requests based on the value of the Client Detect Rate parameter with a
J ava or HTML script containing a simple refresh and cookie. Real clients can
parse the request and return the request with the cookie. Spurious clients drop the
response, and are therefore dropped by the system. When a POST request is
received, it is first checked for a valid cookie. If the request has a valid cookie, the
request goes through, but, if the request does not have a valid cookie, the system
sends a J avascript to the client asking it to resend the information with a new
cookie. If the client sends a new cookie, this cookie becomes invalid after four
minutes, and every response to the client is sent with the new cookie. The cookie
in a POST request can become invalid in the following conditions:
If the POST request is made when the system is under attack, and the
preceding GET request is made when the system is not under attack.
When the think time of the client exceeds four minutes.
Note: Both scenarios are rare but not impossible.
Limitations of the Feature
The DoS protection feature has the following limitations:
Under an attack, all POST requests are dropped, and an error page with a
cookie is sent.
Under an attack, all embedded objects without a cookie are dropped, and an
error page with a cookie is sent.
HowDoS Protection Affects Other Features
This section describes how the DoS protection feature may affect other features.
Content Switching
Using DoS protection for a particular content switching policy creates additional
overhead, because the policy engine must find the policy to be matched.
SSL
There is some overhead for SSL requests due to SSL decryption of the encrypted
data; however, because most attacks are not on a secure network, the attack is less
aggressive.
Priority Queuing/Surge Protection
Under an attack, requests without proper cookies are queued by the system.
Although this creates overhead, it protects the servers from false clients.
Memory/Performance Implications
There is minimal effect on throughput, since the J avaScript is sent to the client at
a very slow rate (default: 1% of the server's HTTP response rate). This rate can be
changed by tuning the -Client Detect Rate parameter of the HTTP DoS
protection policy. The latency of the requests is increased, because the client must
re-issue the request after the J avaScript is returned. This takes time, since the
requests are also queued.
Configuring DoS Protection
This section describes the following procedures to configure HTTP DoS
protection on the system.
Enable HTTP DoS
Add an HTTP DoS policy
Add a service
Bind the monitor
Bind the service to the policy
Note: For information about using the CLI to configure this feature, see the
Command Reference Guide.
To enable HTTP DoS
1. In the left pane, expand System, and click Settings. The System Settings
Overview page appears in the right pane.
appears.
3. Select HTTP DoS Protection check box, click OK, and click Yes on the
Enable/Disable Feature(s) dialog box.
The status bar displays a message indicating that the selected feature is
enabled.
To add an HTTP DoS policy
1. In the left pane, expand Protection Features, and click HTTP DoS. The
HTTP DoS page appears in the right pane.
2. Click Add.The Create HTTP DoS Policy dialog box appears.
3. Type a name for the policy in the Name text box, for example, dospol_1.
4. Type a numeric value in the QDepth text box that denotes the queue size,
for example, 200, .
5. Type a numeric value in the Client Detect Rate text box, for example, 1,
and click OK.
Note: The client detect rate value denotes the percentage of traffic to
which the HTTP DoS policy is applied.
The policy that you created appears in the right pane and the status bar
displays a message indicating that the DoS policy is successfully
configured.
To add a service
1. In the left pane, expand Load Balancing, and click Services. The Services
3. In the Service Name text box type a name, for example,
HTTP_DoS_service1.
4. In the Server text box type the IP address of the server that the service
represents, for example, 10.102.29.1.
5. In the Protocol drop-down list box, select the protocol type, for example,
HTTP.
6. Type the port number in the Port text box, for example, 80. Ensure that
Enable Service check box is selected.
7. Select the Advanced tab, and select the Override Global check box.
8. Type numeric values in the Max Clients text box and Client text box
respectively, for example, 200 and 60.
9. Click Create and click Close. The service you create appears in the list of
services.
To bind a monitor and a policy to the service
1. In the left pane, expand Load Balancing, and click Services. The Services
page displays the list of services in the right pane.
2. Select the service that you want to bind and click Open. The Configure
Service dialog box appears.
3. Select the Monitor tab, click tcp in the Monitors list, and click Add. The
selected monitor tcp is added to the Configured frame.
4. Select the Policies tab, click a policy from the Available Policies list, for
example, dospol_1 that you created in the previous section, and click Add.
The policy appears in the Configured Policies list.
5. Click OK and click Close. A message in the status bar indicates that the
service is configured.
In the previous procedure, if more than 200 clients are waiting in the system surge
queue for the service HTTP_DoS_service1, the HTTP DoS protection function is
triggered. The default rate of challenged J avaScript responses sent to the client is
one percent of the server response rate.
For example, if the server generates 100 responses per second, and there are 200
clients in the surge queue, the HTTP DoS protection feature picks one pending
client request per second from the surge queue (1% of 100) and sends a challenge
J avaScript response to the suspect client at the rate of one J avaScript per second.
If the client executes the received challenge J avaScript, generates the cookie, and
re-sends the original HTTP request with the J avaScript-generated cookie, it
proves that it is a legitimate browser-based client.
The HTTP DoS Protection feature queues the HTTP requests of the client in its
higher-priority legitimate client queue, so that it is served faster.
Tuning the Client Detection/JavaScript Challenge
Response Rate
The default client detection/J avaScript challenge response rate of one percent is
inadequate in many real attack scenarios, therefore, it needs to be tuned.
For example, there are 500 responses/sec from the server, and the server is under
attack with 10000 Gets/sec. If 1% of the server responses are sent as J avaScript
challenges, responses are reduced to almost none: 5 client (500 *0.01) J avascript
responses, for 10000 waiting client requests, approximately 0.05% of the real
clients receive J avaScript challenge responses.
If the client detection/J avascript challenge response rate is very high (for
example, 10%, generating 1000 challenge J avascript responses per second), it
may saturate the upstream links or harm the upstream network devices. Citrix
recommends that an administrator exercise care when choosing Client Detect
Rate values.
If the configured triggering surge queue depth is, for example, 200, and the surge
queue size is toggling between 199 and 200, the system toggles between the
attack and no-attack scenario, which is not desirable.
To prevent the attack and no attack scenario from occurring, a window
mechanism is provided. When the surge queue size reaches 200, and the attack
scenario is detected, the surge queue size must fall for the system to enter no-
attack mode. If the value of WINDOW_SIZE is set to 20, the surge queue size
must fall under 180 before the system enters no-attack mode. During
configuration, you must specify a value more than the WINDOW_SIZE for the
QDepth parameter when adding a DoS pol i cy or setting a DoS pol i cy.
The triggering surge queue depth should be configured based on prior knowledge
of the traffic characteristics. For more information about setting up a correct
configuration, see the following section.
Guidelines for HTTP DoS Protection Deployment
Citrix recommends you to deploy the HTTP DoS protection feature in a tested
and planned manner, and closely monitor after the initial deployment.
Use the following information to fine-tune the deployment of HTTP DoS
Protection.
The maximum number of concurrent connections supported by your
servers.
The average and normal values of the concurrent connections supported by
your servers
The maximum output rate (responses/sec) that your server can generate.
The average traffic that your server handles.
The typical bandwidth of your network.
The maximum bandwidth available upstream.
The limits faced by the bandwidth, for example, external link, router and so
on. The critical devices on the path that may suffer from a traffic surge.
Whether allowing a greater number of clients to connect is more important
than protecting upstream network devices.
Attack Characteristics
What is the rate of incoming fake requests that you have experienced in the
past?
What types of requests have you received (complete posts, incomplete
gets)?
Did previous attacks saturate your downstream links? If not, what was the
bandwidth?
What types of source IP addresses and source ports did the HTTP requests
have (e.g., IP addresses from one subnet, constant IP, ports increasing by
one).
What types of attacks do you expect in future? What type have you seen in
the past?
Any or all information that can help you tune DoS attack protection.
CHAPTER 10
Web Server Logging
Web server logging is the process of maintaining a history of page requests in the
web server log that originate from Citrix NetScaler System. This chapter
discusses how to configure the web server logging feature on the Citrix NetScaler
System and includes the following topics:
How Web Server Logging Works
Configuring Web Server Logging Parameters
Installing the NSWL files
Configuring Web Server Logging
Checklist for Configuring Web Server Logging
How Web Server Logging Works
The Citrix NetScaler System collects log transaction data from the servers and
stores it in the system buffer when you enable the web server logging feature. The
default size of the buffer is 16 MB. You can increase the size of the buffer
depending on the log data.
Note: For more information about modifying the buffer size, see Modifying
the Default Buffer Size at the GUI on page 539 in this chapter.
You must configure filters to allow logging based on a domain name or a server
IP address. If the server uses the load balancing, content switching, or cache
redirection feature of the system, you can also configure web server logging to
log transactions based on the virtual IP address.
The system can store log file data in the following three formats:
W3C Extended log file format
NCSA Common log file standard format
Custom log format
The log format that you can use depends on the requirements to troubleshoot a
problem. Custom log formats let you define only those parameters to log that you
specify.
Configuring Web Server Logging Parameters
This section describes the steps to configure web server logging parameters on
the Citrix NetScaler system.
Enabling Web Server Logging
You can enable web server logging from the GUI or at the CLI. The following
procedure describes how to enable the feature from the GUI.
To enable web server logging
appears.
3. Select the Web Logging check box and click OK.
4. On the Enable/Disable Feature(s) dialog box, click Yes. A message in the
status bar indicates that the web server logging feature is enabled.
Note: To disable web server logging, clear the selection in the Web Logging
check box.
Using CLI Commands to ViewWeb Server
Logging Status
Use the command line interface to configure and set the logging features.
To enable web server logging, type the following command:
enabl e ns f eat ur e WL
To disable web server logging, type the following command:
di sabl e ns f eat ur e WL
To verify whether web server logging is enabled or disabled, type the
following command:
show ns i nf o
Chapter 10 Web Server Logging 539
To check the present buffer size to store log transactions, type the following
command:
show webl ogpar am
Modifying the Default Buffer Size at the GUI
You can modify the default buffer size of 16MB of the Citrix NetScaler System to
a custom size as per your requirements using the GUI of Citrix NetScaler System.
To configure the buffer size
1. In the left pane, expand System, and click Settings.The Settings page
2. Click global system settings. The Configure Global Settings dialog box
appears.
3. In the Web Logging frame, enter the numeric value in the Buffer Size (in
Mega Bytes) text box, for example, 32. Click OK.
A message in the status bar indicates that the global settings are
successfully configured.
Note: To activate the new buffer size, you must disable and re-enable web
server logging.
Modifying the Default Buffer Size at the CLI
To modify the default buffer size of the system at a command prompt, enter the
following command:
set webl ogpar am<- b buf f er si zeMB>
<buffersizeMB>: Specifies the buffer size (in MB) allocated for log
transaction data in the system.
Type the following command to disable web server logging:
di sabl e ns f eat ur e WL
Type the following command to re-enable web server logging:
enabl e ns f eat ur e WL
The default web server log buffer size is 16 MB, which can handle up to 10,000
transactions per second on the logging system that has the operating system
configuration and hardware configuration as shown in the following table:
If the client cannot process the log transaction due a CPU limitation, the Citrix
NetScaler web log buffer overruns, and the logging process re-initiates.
Caution: Re-initiation of logging can result in loss of log transactions.
To temporarily solve a logger client bottleneck caused by a CPU limitation, you
can tune the web server logging buffer size. Thus, it is necessary to identify a
higher configuration logger client that can handle the throughput of the site.
Installing the NSWL files
This section describes the steps to install the web server logging executable files
(NSWL) on various operating systems.
Operating System Software Requirements
Windows Windows XP Professional - Version 2002
Windows 2003 server
Windows 2000/NT
MAC RELEASE_PPC Power Macintosh powerpc - Darwin Kernel
Version 8.6.0
Linux Red Hat Enterprise Linux AS release 4 (Nahant) - Linux
version 2.6.9-5.EL
Red Hat 3.4.3-9.EL4 - Linux version 2.6.9-5.ELsmp
Red Hat Linux 3.2.2-5 - Linux version 2.4.20-8
Solaris Sun Microsystems 5.9 - sun4u Sun Ultra 5/10 UPA/PCI
FreeBSD FreeBSD 4.9
Hardware Requirements
For Windows / Linux /
FreeBSD
Processor - Intel x86 ~501MHz
RAM - 512 MB
Controller - SCSI
For Solaris 2.6 Processor - UltraSPARC-IIi 400 MHz
RAM - 512 MB
Controller - SCSI
Note: Copy the installation files from the product CD or download them from
ftp.netscaler.com. Run the installations from a root user account. <path_to_cd>:
Defines the system path to the drive where the CD device is mounted.
Installing on the Solaris Operating System
Use the following procedure to install the nswl executable and other files on a
computer running the Solaris operating system.
To install on a Solaris operating system
1. Copy the NSwebl og. t ar file into a temporary directory using the
command:
cp <pat h_t o_cd>/ Ut i l i t i es/ webl og/ Sol ar i s/ NSwebl og. t ar / t mp
2. Change to the temporary directory:
cd / t mp
3. Extract the files from the *.t ar file using the following command:
t ar xvf NSwebl og. t ar
A directory NSweblog is created in the temporary directory, and the files
are extracted to the NSweblog directory.
4. Install the package using the following command:
pkgadd - d .
The list of available packages appears. In the following example, one
NSweblog package is shown:
1 NSwebl og Net Scal er Webl oggi ng
( SunOS, spar c) 7. 0
5. You are prompted to select the packages. Select the package number of the
NSwebl og to be installed.
Note: The dot indicates the current directory.
After you select the package number and press Enter, the files are extracted
and installed in the following directories:
/ usr / l ocal / net scal er / et c
/ usr / l ocal / net scal er / bi n
/ usr / l ocal / net scal er / sampl es
6. To verify that the package is installed, enter the following command:
pkgi nf o | gr ep NSwebl og
Note: To uninstall web server logging, use the command: pkgr mNSwebl og
Installing on the Linux Operating System
Use the following procedure to install the nswl executable and the other files on
a computer running the Red Hat Linuxoperating system.
To install on a Linux operating system
1. Copy the NSweblog.rpm file into a temporary directory:
cp <pat h_t o_cd>/ Ut i l i t i es/ webl og/ Li nux/ NSwebl og. r pm/ t mp
2. To install the nswl executable, use the following command:
r pm- i NSwebl og. r pm
This command extracts the files and installs them in the following
directories:
/ usr / l ocal / net scal er / sampl es.
To uninstall web server logging, use the following command:
r pm- e NSwebl og
To get more information on the NSweblog RPM file, use the command: r pm-
qpi *. r pm.
To view the installed web server logging files, use the command: rpm -qpl *.rpm.
Note: *.rpm is the file name
Installing on the FreeBSD Operating System
a computer running the FreeBSD 4.4 operating system.
To install on a FreeBSD operating system
1. At a command prompt, copy the NSweblog.tgz file into a temporary
directory:
cp <pat h_t o_cd>/ Ut i l i t i es/ webl og/ Fr eebsd/ NSwebl og. t gz / t mp
cd / t mp
3. Install the package using the following command:
pkg_add NSwebl og. t gz
This command extracts the files and installs them in the following
directories:
4. To verify that the package is installed, use the following command:
pkg_i nf o | gr ep NSwebl og
Note: To uninstall the web server logging package, enter the command:
pkg_del et e NSwebl og
Installing on the MAC Operating System
a computer running the FreeBSD 4.4 operating system.
To install on a MAC operating system
1. At a command prompt, copy the NSwebl og. t gz file into a temporary
directory using the following command:
cp <pat h_t o_cd>/ Ut i l i t i es/ webl og/ macos/ NSwebl og. t gz / t mp
cd / t mp
3. To install the package, use the pkg_add command:
pkg_add NSwebl og. t gz
This command extracts the files and installs them in
4. To verify that the package is installed, use the command:
pkg_i nf o | gr ep NSwebl og
Note: To uninstall the web server logging package, enter the command
pkg_del et e NSwebl og
Installing on the Windows Operating System
a computer running the Windows operating system.
To install on a Windows operating system
1. Copy the NSweblog.exe file (winzip executable) into a temporary directory.
2. The extracted files are installed in the following directories:
\ NS\ BI N
\ NS\ ETC
\ NS\ SAMPLES
3. To install web server logging as a service, at a command prompt, run the
following command from the \ NS\ BI N path:
nswl - i nst al l - f <di r ect or ypat h> \ l og. conf
<directorypath>: Specifies the path where the l og. conf file is available.
4. To uninstall the web server logging, run the following command from the
\ NS\ BI N folder:
nswl - r emove
Note: To uninstall the web server logging, run the nswl - r emove command
from the \ NS\ BI N folder:
NSWL Options
The nswl executable uses various parameters. The table that follows explains all
the parameters. Run the following commands from the directory in which the
nswl executable is located:
Windows: \ ns\ bi n
Solaris and Linux: \ usr \ l ocal \ net scal er \ bi n
The web server logging configuration files are located in the following directory
path:
Windows: \ ns\ et c
Solaris and Linux: \ usr \ l ocal \ net scal er \ et c
The nswl executable is started as . \ nswl in Linux and Solaris. The following
table describes the options that you can use with the web server executable, nswl:
nswl Commands Description
nswl -help Lists all available nswl options
nswl -addns -f <path to
configuration file>
Specifies the system that gathers the log transaction data.
On execution of the command, you are prompted to enter the
IP address of the system.
Enter a valid username and password.
nswl -verify -f <path to
configuration file>
Checks for syntax or semantic errors in the configuration file,
for example, log.conf.
nswl -start -f <path to
configuration file>
Starts web server logging based on the settings in the
configuration file, for example, log.conf.
For Solaris and Linux: To start web server logging as a
background process, use and at the end of the command..
nswl -stop Solaris and Linux only
Stops web server logging when nswl is started as a
background process; otherwise, use CTRL+C to stop web
server logging.
nswl -install -f <path to
configuration file>
Windows only
Installs the web server logging client as a service in
Windows.
nswl -startservice Windows only
To start web server logging, enter this command at the
command prompt.
Web server logging can be started from Start>Control
Panel>Services.
Web server logging starts using the settings in the
configuration file, for example, log.confspecified in the nswl
install option.
nswl -stopservice Windows only
nswl -remove Removes the web server logging service from the registry.
Configuring Web Server Logging
Following are the steps to configure web server logging:
1. Install web server logging
2. Modify the web server log configuration file, log.conf
3. Define log properties
4. Add the IP addresses of the Citrix NetScaler System in the log.conf file
5. Verify the configuration
6. Start web server logging
Note: You can configure the Citrix NetScaler System to log integrated cache
transactions, using the web server logging feature.
Modifying the Web Server Log Configuration
File
To modify the web server logging settings, use a text editor to make the changes
in the log.conf configuration file.
Defining Filters
Log filters let you filter the host IP address, domain name, and hostname of the
web servers. You must do the following to define filters:
Define filters in the configuration file for each server, for example, log.conf
for each server whose web transactions are logged.
Define log properties for each filter. The filter applies these log properties
to transactions that match the filter.
Note: If a filter does not exist for a log transaction,the transaction is not
recorded unless the default filter is defined.
Defining Default Filters
You can use the default filter definition present in the sample configuration file,
log.conf, or you can modify it.
Note: For consolidated logging: Log transactions for which no filter is defined,
the default filter is used if it is enabled. Consolidated logging of all servers can be
done by defining only the default filter.
Creating Filters
To create a filter, enter the following command in the log.conf file:
Fi l t er <f i l t er Name> [ HOST name] | [ I P i p] | [ I P i p 2. . . i p n] | [ I P
i p NETMASK mask] [ ON | OFF]
The following table lists the parameters that can be set using the filter command:
In the following example, you specify an IP address of 192.168.100.0 and
netmask of 255.255.255.0. The filter applies to IP addresses 192.168.100.1
through 192.168.100.254.
Example:
1. Filter F1 HOST www.netscaler.com ON
2. Filter F2 HOST www.netscaler.com IP 192.168.100.151 ON
3. Filter F3 HOST www.netscaler.com IP 192.168.100.151 192.165.100.152
ON
4. Filter F4 IP 192.168.100.151
5. Filter F5 IP 192.168.100.151 HOST www.netscaler.com OFF
6. Filter F6 HOST www.netscaler.com HOST www.xyz.com HOST
www.abcxyz.com IP 192.168.100.200 ON
filterName Specifies the name of the filter (maximum 64 alphanumeric
characters.)
HOST name Specifies the host name of the server for which the transactions
are being logged.
IP ip Specifies the IP address of the server for which transactions are
to be logged (for example, if the server has multiple domains
that have one IP address.)
IP ip 2...ip n: Specifies multiple IP addresses (for example, if the server
domain has multiple IP addresses.)
IP ip NETMASK mask Specifies the IP addresses and netmask combination to be used
on a subnet.
ON | OFF Specify ON to enable the filter to log transactions, or specify
OFF to disable the filter. If no argument is selected, the filter is
on.
7. Filter F7 IP 192.250.100.0 NETMASK 255.255.255.0
8. Filter F8 HOST www.xyz.com IP 192.250.100.0 NETMASK
255.255.255.0 OFF
Defining Filters for Virtual Servers
If the server hosts multiple Web sites, where each Web site has its own domain
name, and each domain is associated with a virtual server, you can configure web
server logging to create a separate log directory for each Web site.
To define a filter for a virtual server, use the following command:
Fi l t er <f i l t er Name> 
<filterName>: Specifies the name of the filter
<IP>: Specifies the IP address of the virtual server
Defining Log Properties
Log properties associated with the filter are applied to all log entries associated
with the filter.
Log property definition begins with the keyword BEGI N and ends with END.
Example
BEGI N <f i l t er name>
l ogFor mat . . .
l ogFi l enameFor mat . . .
l ogI nt er val . . .
l ogFi l eSi ze . . . .
l ogExcl ude . . . .
END
LogFormat: Specifies the web server logging feature that supports NCSA,
W3C Extended, and custom log file formats. For more information, see Log File
Formats on page 555 in this chapter.
By default, the l ogf or mat property is w3c. To override, enter cust omor
NCSA in the configuration file, for example:
LogFor mat NCSA
Note: For the NCSA and Custom log formats, local time is used to timestamp
transactions and for file rotation.
LogInterval: Specifies the intervals at which log files are created. The default
property is Dai l y. If the LogI nt er val value is specified as:
Hour l y: A file is created every hour
Dai l y: A file is created every day at midnight
Weekl y: A file is created every Sunday at midnight
Mont hl y: A file is created on the first day of the month at midnight
None: A file is created only once, when web server logging starts
Example
LogI nt er val Hour l y
LogFileSizeLimit: Specifies the maximum size of the log file in MB. It can
be used with any log interval (weekly, monthly, and so on.) A file is created when
the maximum file size limit reaches or when the defined log interval time elapses.
To override this behavior, specify the size as the loginterval property so that a file
is created only when the log file size limit is reached.
The default LogFi l eSi zeLi mi t is 10 MB.
Example
LogFi l eSi zeLi mi t 35
LogFilenameFormat: Specifies the file name format of the log file. The
name of the file can be of the following types:
Static: Specifies a constant string that contains the absolute path and file
name.
Dynamic: Specifies an expression containing the following format:
Server IP address (%A)
Date ( %{f or mat }t )
URL suffix (%x)
Host name (%v)
Note: For more information, see Log File Formats on page 555 in this
chapter.
Example
LogFi l eNameFor mat Ex%{%m%d%y}t . l og
This creates the first file name as Exmmddyy. l og, then every hour creates a
file with file name: Exmmddyy. l og. 0, Exmmddyy. l og. 1,...,
Exmmddyy. l og. n.
Example
LogI nt er val si ze
LogFi l eSi ze 100
LogFi l eNameFor mat Ex%{%m%d%y}t
Caution: The date format %t specified in the LogFi l enameFor mat
overrides the log interval property for that filter. To prevent a new file being
created every day instead of when the specified log file size is reached, do not use
%t in the LogFi l enameFor mat .
LogExcl ude: Specify this property to prevent logging of transactions with the
specified file extensions.
Example
LogExcl ude . ht ml
This creates a log file that excludes log transactions for *. ht ml files.
LogTi me: Specify this property to define the log time as either GMT or
LOCAL.
The defaults are:
NCSA log file format: LOCAL
W3C log file format: GMT.
Default Settings for the Log Properties
The following default settings apply to the filter:
LogFormat: W3C Extended
LogInterval: Daily
LogFileSize: 10
LogFileNameFormat: Ex%{%m%d%y}t
LogTime (logTime): GMT
Example 1
Fi l t er f 1 I P 192. 168. 10. 1
This creates a log file for server 192.168.10.1
Example 2
Fi l t er f 1 I P 192. 168. 10. 1
begi n f 1
l ogFi l enameFor mat c: \ l ogf i l es. l og
end f 1
This creates a log file for server 192.168.10.1. Only the log file name format is
specified, and the rest of the default values for the log properties remain same.
Adding the IP Addresses of the System
In the configuration file, add the IP addresses of the system that performs web
server logging.
To add the IP addresses
1. At a command prompt, enter the following command:
nswl - addns - f <directorypath>\ l og. conf
<directorypath>: Specifies the path where the l og. conf configuration
file resides.
2. The following information appears:
NSI P:
User name:
Passwor d:
Enter the following:
NSIP: Specify the IP address of the system
Username: Specify the username to log on
Password: Specify the password
If you add multiple NetScaler IP addresses (NSIP), and later you do not want to
log all of Citrix NetScaler System log details, you can delete the NSIPs manually
by removing the NSIP statement at the end of the log.conf file. During a failover
setup, you must add both primary and secondary Netscaler IPs to log.conf using
the command. Before adding the IP address, make sure the username and
password exist on the system.
Check the configuration file (log.conf) for syntax errors so that logging works
correctly.
To verify the configuration, enter the following command:
nswl - ver i f y - f <di r ect or ypat h>\ l og. conf
<directorypath>: Specifies the path where the configuration file (l og. conf )
resides.
Starting Web Server Logging
To start web server logging, type the following command:
nswl - st ar t - f <di r ect or ypat h>\ l og. conf
<directorypath>: Specifies the path where the configuration file (l og. conf )
resides.
Stopping Web Server Logging
To stop web server logging started as a background process in Solaris or Linux,
use the following command:
nswl - st op
To stop web server logging started as a service in Windows, use the following
command:
nswl - st opser vi ce
Sample Configuration File
Following is a sample configuration file:
##########
# Thi s i s t he NSWL conf i gur at i on f i l e
# Onl y t he def aul t f i l t er i s act i ve
# Remove l eadi ng # t o act i vat e ot her f i l t er s
##########
##########
# Def aul t f i l t er ( def aul t on)
# W3C For mat l oggi ng, new f i l e i s cr eat ed ever y hour or on r eachi ng
10MB f i l e si ze,
# and t he f i l e name i s Exyymmdd. l og
##########
Fi l t er def aul t
begi n def aul t
l ogFor mat W3C
l ogI nt er val Hour l y
l ogFi l eSi zeLi mi t 10
l ogFi l enameFor mat Ex%{%y%m%d}t . l og
end def aul t
##########
#netscaler caches example
# CACHE_F f i l t er cover s al l t he t r ansact i on wi t h HOST name
www. net scal er . comand t he l i st ed ser ver i p' s
##########
#Fi l t er CACHE_F HOST www. net scal er . comI P 192. 168. 100. 89
192. 168. 100. 95 192. 168. 100. 52 192. 168. 100. 53 ON
##########
#netscaler origin server example
# Not i nt er est ed i n Or i gi n ser ver t o Cache t r af f i c t r ansact i on
l oggi ng
##########
#Fi l t er ORI GI N_SERVERS I P 192. 168. 100. 64 192. 168. 100. 65
192. 168. 100. 66 192. 168. 100. 67 192. 168. 100. 225 192. 168. 100. 226
192. 168.
100. 227 192. 168. 100. 228 OFF
##########
#netscaler image server example
# al l t he i mage ser ver l oggi ng.
##########
#Fi l t er I MAGE_SERVER HOST www. net scal er . i mages. comI P
192. 168. 100. 71 192. 168. 100. 72 192. 168. 100. 169 192. 168. 100. 170
192. 168. 10
0. 171 ON
##########
# NCSA For mat l oggi ng, new f i l e i s cr eat ed ever y day mi dni ght or on
r eachi ng 20MB f i l e si ze,
# and t he f i l e name i s / dat adi sk5/ net scal er / l og/ NS<host name>/
Nsmmddyy. l og.
# Excl ude obj ect s t hat ends wi t h . gi f . j pg . j ar .
##########
#begi n ORI GI N_SERVERS
# l ogFor mat NCSA
# l ogI nt er val Dai l y
# l ogFi l eSi zeLi mi t 40
# l ogFi l enameFor mat / dat adi sk5/ ORGI N/ l og/ %v/
NS%{%m%d%y}t . l og
# l ogExcl ude . gi f . j pg . j ar
#end ORI GI N_SERVERS
##########
# NCSA For mat l oggi ng, new f i l e i s cr eat ed ever y day mi dni ght or on
r eachi ng 20MB f i l e si ze,
Nsmmddyy. l og wi t h l og r ecor d t i mest amp as GMT.
##########
#begi n CACHE_F
# l ogFor mat NCSA
# l ogFi l enameFor mat / dat adi sk5/ net scal er / l og/ %v/
NS%{%m%d%y}t . l og
# l ogt i me GMT
#end CACHE_F
##########
# W3C For mat l oggi ng, new f i l e on r eachi ng 20MB and t he l og f i l e
pat h name i s
# at adi sk6/ net scal er / l og/ ser ver ' s i p/ Exmmyydd. l og wi t h l og r ecor d
t i mest amp as LOCAL.
##########
#begi n I MAGE_SERVER
# l ogFor mat W3C
# l ogI nt er val Si ze
# l ogFi l enameFor mat / dat adi sk6/ net scal er / l og/ %AEx%{%m%d%y}t
# l ogt i me LOCAL
#end I MAGE_SERVER
##########
# Vi r t ual Host by Name f i r m, can f i l t er out t he l oggi ng based on t he
host name by,
##########
#Fi l t er VHOST_F I P 10. 101. 2. 151 NETMASK 255. 255. 255. 0
#begi n VHOST_F
# l ogFor mat W3C
l ogFi l enameFor mat / ns/ pr od/ vhost / %v/ Ex%{%m%d%y}t
#end VHOST_F
########## END FI LTER CONFI GURATI ON ##########
Log File Formats
Citrix NetScaler system supports the following log file formats:
NCSA Common Log Format
W3C Extended Log Format
Custom Log Format
Apache Log Format
NCSA Common Log Format
If the log file format is NCSA, the log file displays log information in the
following format:
Cl i ent _I P_addr ess User _Name [ Dat e: Ti me Ti meZone] Met hod Obj ect
HTTP_ver si on HTTP_St at usCode Byt esSent
To use the NCSA Common log format, enter NCSA in the LogFormat argument
in the log.conf file.
The following table describes the NCSA Common log format.
Client _IP_address Specifies the IP address of the client computer
User Name Specifies the user name
Date Specifies the date of the transaction
Time Specifies the time when the transaction was completed
Time Zone Specifies the time zone (Greenwich Mean Time or local
time)
W3C Extended Log Format
An extended log file contains a sequence of lines containing ASCII characters
terminated by either the sequence Line Feed (LF) or Carriage Return Line Feed
(CRLF.) Log file generators must follow the line termination convention for the
platform on which they are run.
Log analyzers must accept either LF or CRLF form. Each line may contain either
a directive or an entry.
If you want to use the W3C Extended log format, enter W3C as the Log-Format
argument in the l og. conf file.
Customizing W3C Format
By default, the standard W3C log format is defined internally as the custom log
format, shown as follows:
%{%Y-%m-%d%H:%M:%S}t %a %u %S %A %p %m %U %q %s %j %J %T
%H %+{user-agent}i %+{cookie} i%+{referer}i
For a description of the meaning of this each custom format, see Custom Log
Format on page 560 in this chapter. You can also change the order or remove
some fields in this W3C log format. For example:
logFormat W3C %{%Y-%m-%d%H:%M:%S}t %m %U
W3C log entries are created with the following format:
#Version: 1.0
#Fields: date time cs-method cs-uri
#Date: 12-J un-2001 12:34
2001-06-12 12:34:23 GET /sports/football.html
2001-06-12 12:34:30 GET /sports/football.html
Entries
Entries consist of a sequence of fields relating to a single HTTP transaction.
Fields are separated by white space; Citrix recommends the use of tab characters.
If a field in a particular entry is not used, a dash - marks the omitted field.
Method Specifies the request method (for example; GET, POST)
Object Specifies the URL
HTTP_version Specifies the version of HTTP used by the client
HTTP_StatusCode Specifies the status code in the response
Bytes Sent Specifies the number of bytes sent from the server
Directives
Directives record information about the logging process. Lines beginning with
the #character contain directives.
The following table lists the directives with the descriptions:
Note: The Ver si on and Fi el ds directives are required. They precede all
other entries in the log file.
Example
The following example log file displays the W3C Extended log format:
#Ver si on: 1. 0
#Fi el ds: t i me cs- met hod cs- ur i
#Dat e: 12- J an- 1996 00: 00: 00
00: 34: 23 GET / spor t s/ f oot bal l . ht ml
Fields
The Fields directive lists a sequence of field identifiers that specify the
information recorded in each entry. Field identifiers may have one of the
following forms:
identifier: Relates to the transaction as a whole.
Directive Description
Version: <integer>.<integer> Displays the version of the extended log file format
used. This document defines version 1.0.
Fields: [<specifier>...] Identifies the fields recorded in the log.
Software: <string> Identifies the software that generated the log.
Start-Date: <date><time> Displays the date and time at which the log was
started.
End-Date: <date><time> Displays the date and time at which logging finished.
Date: <date><time> Displays the date and time when the entry was added.
Remark: <text> Displays comments. Analysis tools ignore data
recorded in this field.
prefix-identifier: Relates to information transfer between parties defined
by the value prefix.
prefix(header): Specifies the value of the HTTP header field header for
transfer between parties defined by the value prefix. Fields specified in this
manner always have the type <string>.
The following table describes defined prefixes.
Examples
The following examples are defined identifiers that use prefixes:
cs-method : Specifies the method in the request sent by the client to the server
sc(Referer): Specifies the Referer field in the reply
c-ip: Specifies the IP address of the client
Identifiers
The following table describes the W3C Extended log format identifiers that do
not require a prefix.
Prefix Description
c Client
s Server
r Remote
cs Client to server
sc Server to client
sr Server to remote server (prefix used by proxies)
rs Remote server to server (prefix used by proxies)
x Application-specific identifier
Identifier Description
date Specifies the date on which the transaction was done.
time Specifies the time when the transaction is done.
time-taken Specifies the time taken(in seconds) for the transaction to complete.
bytes Specifies the number of bytes transferred.
cached Records whether a cache hit has occurred. A zero indicates a cache miss.
The following table describes the W3C Extended log format identifiers that
require a prefix.
The W3C Extended Log file format allows you to choose log fields. These fields
are shown in the following table:
Identifier Description
IP Specifies the IP address and the port number
dns Specifies the DNS name
status Specifies the status code
comment Specifies the comment returned with status code
method Specifies the method
url Specifies the URL
url-stem Specifies the stem portion of the URL
url-query Specifies the query portion of the URL
Field Description
Date Specifies the date on which the transaction is done
Time Specifies the time when the transaction is done
Client IP Specifies the IP address of the client
User Name Specifies the user name
Service Name Specifies the service name, which is always HTTP
Server IP Specifies the server IP address
Server Port Specifies the server port number
Method Specifies the request method (for example; GET, POST)
Url Stem Specifies the URL stem
Url Query Specifies the query portion of the URL
Http Status Specifies the status code in the response
Bytes Sent Specifies the number of bytes sent to the server (request size,
including HTTP headers)
Bytes Received Specifies the number of bytes received from the server (response size,
including HTTP headers)
Time Taken Specifies the time taken for transaction to complete, in seconds
Protocol Version Specifies the version number of HTTP being used by the client
User Agent Specifies the User-Agent field in the HTTP protocol
CustomLog Format
You can customize the display format of the log file data as described in the
following sections:
Using the NSWL Library to Define a Custom Log Format
Manually Defining a Custom Log Format
Using the NSWL Library to Define a CustomLog Format
Use one of the following NSWL libraries depending on whether the nswl
executable has been installed on a Windows or Solaris host computer:
Windows: The nswl.lib library located in \ ns\ bi n directory on the
system manager host computer.
Solaris: The l i bnswl . a library located in / usr / l ocal /
net scal er / bi n
To define the custom log format
1. Add the following two C functions defined by the system in a source file:
ns_user Def Fi el dName( ) : This function returns the string that must
be added as a custom field name in the log file.
ns_user Def Fi el dVal ( ) : This function implements the custom field
value, then returns it as a string that must be added at the end of the log
record.
2. Compile the file into an object file.
3. Link the object file with the NSWL library (and optionally, with third party
libraries) to form a new nswl executable.
4. Add a %d string at the end of the l ogFor mat string in the l og. conf
file.
Example
If you want to add a digital signature at the end of each record, follow the steps in
the preceding section, then define the filter in the log.conf file as described below.
##########
# A new f i l e i s cr eat ed ever y mi dni ght or on r eachi ng 20MB f i l e
si ze,
Cookie Specifies the Cookie field of the HTTP protocol
Referer Specifies the Referer field of the HTTP protocol
Nsmmddyy. l og and cr eat e di gi t al
#si gnat ur e f i el d f or each r ecor d.
BEGI N CACHE_F
l ogFor mat cust om" %a - " %{user - agent }i " [ %d/ %B/ %Y %T - %g] " %x"
%s %b%{r ef er r er }i " %{user - agent }i " " %{cooki e}i " %d "
l ogI nt er val Dai l y
l ogFi l enameFor mat / dat adi sk5/ net scal er / l og/ %v/ NS%{%m%d%y}t . l og
END CACHE_F
Manually Define a CustomLog Format
To customize the format in which log file data should appear, specify a character
string (described in the following table) as the argument of the LogFormat log
property definition. For example:
LogFor mat Cust om" " %a - " %{user - agent }i "
%[ %d/ %m/ %Y] t %U %s %b %T"
The string can contain the c type control characters \n and \t to
represent new lines and tabs.
Use the <Esc>key with literal quotes and backslashes.
The characteristics of the request are logged by placing % directives in the
format string, which are replaced in the log file by the values.
If the %v (Host name) or %x (URL suffix) format specifiers is present in a log
filename format string, the following characters in the filename are replaced by
an underscore symbol in the log configuration filename:
" , *, . , / , : , <, >, ? \ , |
Characters whose ASCII values lie in the range of 0-31, are replaced by the
following:
%<ASCII value of character in hexadecimal>.
For example, the character with ASCII value 22 is replaced by %16.
Caution: If the %v format specifier is present in a log filename format string, a
separate file is opened for each virtual host. To ensure continuous logging, the
value of the maximum number of files that a process can have open should be
sufficiently large. See your operating system documentation for a procedure to
change the value of the number of files that can be opened.
The following table describes the data that you can use as the LogFormat
argument string:
%a Specifies the remote IP address
%A Specifies the local IP address
%B Specifies the bytes sent, excluding the HTTP headers (response size)
%b Specifies the bytes received, excluding the HTTP headers (request size)
%d Specifies a user-defined field
%g Specifies the Greenwich Mean Time offset
(for example, -0800 for Pacific Standard Time)
%h Specifies the remote host
%H Specifies the request protocol
%{Foobar}i Specifies the contents of the Foobar: header line(s) in the request sent to
the server. The system supports the User-Agent, Referer and cookie
headers. The + after the % in this format informs the logging client to
use the + as a word separator.*
%j Specifies the bytes received, including headers (request size)
%J Specifies the bytes sent, including headers (response size)
%l Specifies the remote log name (from identd, if supplied)
%m Specifies the request method
%M Specifies the time taken to serve the request (in microseconds)
%{Foobar}o Specifies the contents of Foobar: header line(s) in the reply. We support
the USER-AGENT, Referer, and cookie headers.
%p Specifies the canonical port of the server serving the request
%q Specifies the query string [prefixed with a question mark (?) if a query
string exists]
%r Specifies the first line of the request
%s For requests that were redirected internally, this is the status of the original
request
%t Specifies the time, in common log format (standard English time format)
%{format}t Specifies the time, in the form given by format, must be in strftime(3)
format. The next table describes what you can enter as the format.
%T Specifies the time taken to serve the request, in seconds
%u Specifies the remote user (from auth; may be bogus if return status (%s) is
401)
%U Specifies the URL path requested
%v Specifies the canonical name of the server serving the request
For example, if you define the log format as %+{user-agent}i, and if the user
agent value is Citrix Netscaler system Web Client, then the information is logged
as Citrix Netscaler system +Web+Client. An alternative is to use the double quote
(for example, %{user-agent}i, then it logs it as Citrix Netscaler system Web
Client. Do not use the <Esc>key on strings from %.. .r, %. . .i and %. . .o. This
complies with the requirements of the Common Log Format. It implies that
clients can insert control characters into the log, therefore, you should take care
when working with raw log files.
Time Format Definition
The following table lists the characters that you can enter as the format part of the
%{format}t string (described in the previous table). Values within brackets ([ ])
show the range of values that appear. For example, [1,31] in the %d description in
the following table shows %d ranges from 1 to 31.
%V This is the virtual server address in the system, if load balancing, content
switching, and/or cache redirection is used or is being used.
%% Specifies the same as %
%a Specifies the abbreviated name of the week day for the locale
%A Specifies the full name of the week day for the locale
%b Specifies the abbreviated name of the month for the locale
%B Specifies the full name of the month for the locale
%C Specifies the century number (the year divided by 100 and truncated to an integer as
a decimal number [1,99]); single digits are preceded by a 0
%d Specifies the day of month [1,31]; single digits are preceded by 0
%e Specifies the day of month [1,31]; single digits are preceded by a blank
%h Specifies the abbreviated name of the month for the locale
%H Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a 0
%I Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a 0
%j Specifies the number of the day in the year [1,366]; single digits are preceded by 0
%k Specifies the hour (24-hour clock) [0,23]; single digits are preceded by a blank
%l Specifies the hour (12-hour clock) [1,12]; single digits are preceded by a blank
%m Specifies the number of the month in the year [1,12]; single digits are preceded by a
0
%M Specifies the minute [00,59]; leading 0 is permitted but not required
%n Inserts a new line
%p Specifies the equivalent of either a.m. or p.m. for the locale
Note: If you specify a conversion that does not correspond to any of the ones
described in the preceding table, or to any of the modified conversion
specifications listed in the next paragraph, the behavior is undefined and returns
0.
The difference between %U and %W (and also between modified conversions
%OU and %OW) is the day that would be the first day of the week. Week number
1 is the first week in J anuary (starting with a Sunday for %U, or a Monday for
%W). Week number 0 contains the days before the first Sunday or Monday in
J anuary for %U and %W.
Apache Log Formats
You can derive from the custom logs most of the log formats that Apache
currently supports. The custom log formats that match Apache log formats are:
NCSA/combined: LogFor mat cust om%h %l %u [ %t ] " %r " %s %B
" %{r ef er er }i " " %{user - agent }i "
NCSA/Common: LogFor mat cust om%h %l %u [ %t ] " %r " %s %B
Referer Log: LogFor mat cust om" %{r ef er er }i " - > %U
Useragent: LogFor mat cust om%{user - agent }i
Similarly, you can derive the other server log formats also using the custom
formats.
%r Specifies the appropriate time representation in 12-hour clock format with %p
%S Specifies the seconds [00,61]; the range of values is [00,61] rather than [00,59] to
allow for the occasional leap second and for the double leap second.
%t Inserts a tab
%u Specifies the day of the week as a decimal number [1,7].
1 represents Sunday, 2 represents Tuesday and so on.
%U Specifies the number of the week in the year as a decimal number [00,53], with
Sunday as the first day of week 1.
%w Specifies the day of the week as a decimal number [0,6]
0 represents Sunday.
%W Specifies the number of the week in the year as a decimal number [00,53]. Monday
is the first day of week 1.
%y Specifies the number of the year within the century [00,99].
For example, 5 would be the fifth year of that century.
%Y Specifies the year, including the century (for example, 1993)
Checklist for Configuring Web Server Logging
Use the following checklist when you configure web server logging, and to
troubleshoot problems:
1. Check that the Citrix NetScaler system username and password are valid.
2. Make sure that the Netscaler is accessible from the log machine by doing
the following:
Ping the Netscaler IP address
Use FTP and Telnet to access the system
3. Verify that the IP address of the system is present in the configuration file
(l og. conf )
CHAPTER 11
Configuring Audit Server Logging
Auditing is defined as a methodical examination or review of a condition or
situation. The Audit Server feature of Citrix NetScaler System enables you to log
the Citrix NetScaler System states and status information collected by various
modules in the kernel and in the user-level daemons. The audit server collects and
stores the events history in a chronological order, so that you can review to
troubleshoot problems or errors and fix them. This chapter covers the following
topics:
How Audit Server Logging Works
Configuring the Citrix NetScaler Audit Server Log
Installing the Audit Server Files
Configuring Audit Server Logging on a Server Computer
Commonly Used Deployment Scenario
How Audit Server Logging Works
This section contains a brief overview of what audit server logging is and how it
works on the Citrix NetScaler System. By configuring audit server logging, you
set up a log file to capture the Citrix NetScaler System status information in the
form of messages. All these messages typically contain the following
information:
The source module that generates the message
A time stamp
The message type
The predefined log levels (Critical, Error, Notice, Warning, Informational,
Debug, Alert, and Emergency)
The message information
To enable audit server logging, you must configure the auditing parameters on the
system, set up and install the executable files on a computer from where you want
to run the audit tool, and configure the parameters in the configuration file by
defining the filters and filter parameters. For example, filters let you define the
type of information to store and the location to store the audit log files. after you
enable the feature, logging of Citrix NetScaler System events starts.The
information collected in the log files helps administrators troubleshoot errors and
problems in the system.
Configuring the Citrix NetScaler Audit Server Log
You can configure the log settings in the Citrix NetScaler System using the
Graphical User Interface (GUI). For information about using the Command Line
Interface (CLI), see the Command Reference Guide.
The Citrix NetScaler System can also log the following information related to
TCP connections:
Source port
Destination port
Source IP
Destination IP
Number of bytes transmitted and received
Time period for which the connection is open
Note: You can enable TCP logging on individual load balancing vservers. You
must bind the audit log policy to a specific load balancing vserver that you want
to log.
To configure audit server logging, you must set the following parameters:
Auditing Type Specifies the type of audit to perform; options are
SYSLOG and NSLOG.
IP Address Specifies the IP address of the auditing server. The
default is 0.0.0.0.
Port Specifies the port to use to communicate, the default is
3023.
Chapter 11 Configuring Audit Server Logging 569
Audit Server Logging Parameters
The audit server feature provides detailed control of the information to be logged
and specifies the location where these messages are stored. Each log message can
have one of the severity levels as shown in the following table:
Log Levels Specifies the level of log to audit; you can select ALL,
or NONE or customize your selection from the
following options:
EMERGENCY
ALERT
CRITICAL
ERROR
WARNING
NOTICE
INFORMATION
DEBUG
Note: The table that follows explains the log levels
in detail.
Date Format Specifies the format of the date to choose. The available
formats are MMDDYYYY and DDMMYYYY.
Log Facility Specifies to set a log facility level as per the standards
mentioned in RFC3164. Log Facility indicates the type
of message originating from Citrix Netscaler, for
example, NS and VPN. The numerical codes assigned
to these messages range from 0 to 7. You can select one
from the available options of LOCAL0 to LOCAL7.
The default is LOCAL0.
Time Zone Specifies to set the time zone to GMT or Local for an
accurate timestamp.
TCP Logging Specifies to enable or disable logging of TCP events.
Level Description
EMERGENCY Logs only major errors. Entries captured in the log indicate that
the Citrix NetScaler product line is experiencing a critical
problem that may make the system unusable.
ALERT Logs problems that may cause the Citrix NetScaler product
line to function incorrectly, but are not critical to its operation.
You must take immediate corrective action to prevent the
Citrix NetScaler product line from experiencing a critical
problem.
CRITICAL Logs critical conditions that do not restrict the Citrix NetScaler
product line operation, but that may escalate to a larger
problem.
Configuring Global Audit Server Parameters
This section describes how to configure global audit server parameters on Citrix
NetScaler System.
To configure global auditing parameters
1. In the left pane, expand System, and click the Auditing node. The
Auditing page appears in the right pane.
2. Click global auditing parameters. The Configure Auditing Parameters
dialog box appears.
3. In the Auditing Type drop-down list, select NSLOG.
4. In the IP Address and Port text boxes, type the IP of the server for which
you want to configure logging, and the port number to use; for example,
10.102.29.1, and 3023. The default port number is 3023.
5. Select either the ALL check box or select specific log-level check boxes to
determine the log levels.
Note: Selecting NONE disables all log levels. Use this option when you
want to reset log levels.
6. Select a Date format option, and in the Log Facility drop-down list, select
a log facility option.
Note: For more information about the log facility options, see the chapter
Managing the Citrix NetScaler System.
ERROR Displays messages related to failed operations of the Citrix
NetScaler product line.
WARNING Displays issues that may result in critical errors.
NOTICE Displays issues in greater detail than the information-level log,
but serves the same notification purpose.
INFORMATION Includes all actions that the Citrix NetScaler product line takes.
This level of logging can help troubleshoot problems on the
Citrix NetScaler product line.
DEBUG Displays extensive detailed information. Developers use this
level of logging to troubleshoot various problems.
Level Description
7. In the Time Zone options, select either GMT or Local, and in the TCP
Logging options, select NONE or ALL.
8. Click OK. The global settings are in effect.
Note: The default time zone is GMT. ALL enables TCP Logging and
NONE disables TCP Logging for audit server.
Configuring Audit Server Action and Policy
You can configure audit server actions for different servers and for different log
levels.
To configure an auditing action
1. In the left pane, expand System, Auditing node, and click Policies. The
Policies page appears in the right pane.
2. Select the Servers tab and click Add. The Create Auditing Server dialog
box appears.
3. In the Name text box, type a name for the auditing server, and in the
Auditing Type drop-down list, select NSLOG.
4. In the IP Address and Port text boxes, type the IP address and the port
number of the auditing server. The default port is 3023.
5. In Log Levels, select the ALL check box or select specific log-level check
boxes to determine the log levels, and select a Date format option.
6. In the Log Facility drop-down list, select a log facility, in TCP Logging,
click the NONE or ALL option, and in Time Zone, click the GMT or
Local option. The default is GMT time zone.
7. Click Create and click Close. The auditing server is created and added to
the Servers list.
To configure audit server policy
1. In the left pane, expand System, Auditing, and select Policies. The
2. On the Policies tab, click Add. The Create Auditing Policy dialog box
appears.
3. In the Name text box type a name for the policy, for example, nspol1.
4. In the Auditing Type drop-down list, select NSLOG, in the Server drop-
down list, select a server, click Create, and click Close. The policy is
created and appears in the Policies page.
Globally Binding the Audit Policy
You must globally bind the audit log policy to enable logging of all Citrix
NetScaler System events. By defining the priority level, you can set the
evaluation order of the audit server logging. Priority 0 is the highest and is
evaluated first. The higher the priority number, the lower is the priority of
evaluation.
To globally bind the audit policy
1. In the left pane, expand System, Auditing, and click Policies. The Policies
2. On the Policies tab, click Global Bindings. The Bind/Unbind Auditing
Global Policies dialog box appears.
3. In the Active column, select the check box next to the policy that you want
to bind, in the Priority list box, click the priority, for example, 0, and click
OK.
In the Policy pane, the Globally Bound column displays Yes for the policy
you have bound.
Note: To unbind an audit policy, in the Active column clear the selection of the
check box next to the policy that you want to unbind.
Installing the Audit Server Files
This section describes the steps to install the audit server logging executable files
on various operating systems.
Note: Copy the installation files from the product CD or download them from
the site ftp.netscaler.com. Run the installations from the root user account.
The following table lists the minimum system requirements for configuring
external audit server logging for Windows, Linux, and FreeBSD:
Windows Windows XP Professional - Version 2002
Windows 2003 server
Windows 2000/NT
Linux Red Hat Enterprise Linux AS release 4 (Nahant) - Linux
version 2.6.9-5.EL
Red Hat 3.4.3-9.EL4 - Linux version 2.6.9-5.ELsmp
Red Hat Linux 3.2.2-5 - Linux version 2.4.20-8
FreeBSD FreeBSD 4.9
Hardware Requirements
For Windows / Linux /
FreeBSD
Processor - Intel x86 ~501MHz
RAM - 512 MB
Controller - SCSI
Installing on the Linux Operating System
The following section describes the procedure to install the audit server
executable and other files on a system that runs Red Hat Linux.
To install on a Linux operating system
1. At a command prompt, type the following command to copy the
NSauditserver.rpm file to a temporary directory:
cp <pat h_t o_cd>/ Ut i l i t i es/ audi t ser ver / Li nux/ NSaudi t ser ver . r pm
/ t mp
2. Type the following command to install the NSauditserver.rpm file:
r pm- i NSaudi t ser ver . r pm
This command extracts the files and installs them in:
Uninstalling on the Linux Operating System
This section describes the procedure to uninstall audit server logging on a server
that runs on the Linux operating system.
To uninstall audit server logging
At a command prompt, type the following command to uninstall the audit server
logging feature:
r pm- e NSaudi t ser ver
For more information about the NSauditserver RPM file, use the following
command:
r pm- qpi *. r pm
To view the installed audit server files use the following command:
r pm- qpl *. r pm
*. r pm: Specifies the file name.
Installing on the FreeBSD Operating System
This section describes the procedure to install the audit server executable and
other files on the FreeBSD 4.4 operating system.
To install on a FreeBSD operating system
1. Copy the NSauditserver.tgz file to a <target directory>using the
command:
cp <pat h_t o_cd>/ Ut i l i t i es/ audi t ser ver / Fr eebsd/
NSaudi t ser ver . t gz / <t ar get di r ect or y>
<path_to_cd>: Specifies the system path to the CD drive where the CD
device is mounted.
<target directory>: Specifies the path to the directory to which the file
should be copied.
2. Change to the <target directory>:
cd / <t ar get di r ect or y>
3. Use the following command to install the package:
pkg_add NSaudi t ser ver . t gz
This command extracts the files and installs them in:
4. At a command prompt, type the following command to check whether the
package is installed:
pkg_i nf o | gr ep NSaudi t ser ver
Uninstalling on the FreeBSD Operating System
that runs on the FreeBSD operating system.
At a command prompt, type the following command to uninstall the audit server
logging package:
pkg_del et e NSaudi t ser ver
Installing on the Windows Operating System
This section describes the procedure to install the audit server executable and
other files on the Windows operating system.
To install on a Windows operating system
1. Extract the audser ver . exe file from the NSaudi t ser ver . zi p
compressed file into a temporary directory. When the files are extracted the
following directories are created:
\ NS\ BI N
\ NS\ ETC
\ NS\ SAMPLES
2. To install audit server logging as a service, run the following command
from \ NS\ BI N directory:
audser ver - i nst al l - f <di r ect or ypat h> \ audi t l og. conf
<directorypath>: Specifies the path where the audi t l og. conf
file is available.
Uninstalling on the Windows Operating System
that runs on the Windows operating system.
1. At a command prompt, change to the following directory:
cd \ NS\ BI N
2. Type the following command to uninstall the audit server logging feature:
audser ver - r emove
Note: To uninstall the audit server logging application, uninstall the
audi t ser ver service and remove the directory.
Audit Server Options
Run the audser ver command with the executable options described in the
following table from the directory in which the audit server executable is present:
On Windows: \ ns\ bi n
On Solaris and Linux: \ usr \ l ocal \ net scal er \ bi n
The audit server configuration files are present in the following directories:
On Windows: \ ns\ et c
On Linux: \ usr \ l ocal \ net scal er \ et c
The audit server executable is started as . / audi t ser ver in Linux and
FreeBSD.
The following table describes the audit server executable options:
Audit Server Commands Description
audser ver - hel p Lists all the available Audit Server options
audser ver - addns - f
<pat h t o conf i gur at i on
f i l e>
Specifies the system that gathers the log transaction
data.
On execution of the command, you are prompted to
enter the IP address of the system.
Enter the Userid and Password of the system.
Note: Userid and password must be valid.
audser ver - ver i f y - f
f i l e>
Checks for syntax or semantic errors in the
configuration file, for example, auditlog.conf file.
audser ver - st ar t - f
f i l e>
Starts audit server logging based on the configuration
settings in the configuration file, for example,
auditlog.conf file.
Linux only:
To start the audit server as a background process, type &
at the end of the command.
audser ver - st op Linux only:
Stops audit server logging when audit server is started
as a background process. Alternatively, use the Ctrl+C
key to stop audit server logging.
audser ver - i nst al l - f
f i l e>
Windows Only:
Installs the audit server logging client as a service on
Windows.
Configuring Audit Server Logging on a Server Computer
Use the following process to configure audit server logging on the server
computer, Windows, or Linux, or FreeBSD.
1. Install audit server logging as described in the section Installing the Audit
Server Files
2. Using a text editor, make the following changes in the auditlog.conf file:
A. Add the IP address of the audit server in the MYIP field.
B. Define the log filters and log properties.
C. Add the IP address of the Citrix NetScaler System.
D. Verify the configuration.
3. Start audit server logging.
Note: You can configure the system to log integrated cache transactions using
the audit server logging feature.
audser ver - st ar t ser vi ce Windows Only
Starts the audit server logging service, when you enter
this command at a command prompt.
You can also start audit server logging from Start >
Control Panel >Services option.
Note: Audit server logging starts by using the
configuration settings in the configuration file, for
example, auditlog.conf file specified in the audit server
install option.
audser ver - st opser vi ce Windows Only
audser ver - r emove Removes the audit server logging service from the
registry.
Audit Server Commands Description
Defining Filters
Define filters in the configuration file, for example, audi t l og. conf to
configure each Citrix NetScaler to log web transactions handled by the logging
server.
Define log properties for each filter. The filter applies these log properties to the
transactions that match the filter definition.
Note: A transaction is not recorded if a filter definition does not exist for a log
transaction.
Defining Default Filters
To define the default filter, you can either use the filter in the sample
configuration audi t l og. conf file or modify it.
Note: For consolidated logging: if a log transaction occurs for which there is no
filter definition, the default filter is used (if it is enabled.) You can only configure
consolidated logging of all the Citrix NetScaler Systems by defining the default
filter.
Creating Filters
To create a filter define the following command in the audi t l og. conf file:
f i l t er <f i l t er Name> [ I P ] [ NETMASK <mask>] [ ON | OFF]
<filterName>: Specify the name of the filter. (maximum of 64 alphanumeric
characters)
<ip>: Specify the IP addresses
<mask>: Specify the netmask combination to be used on a subnet.
ON | OFF: Specify ON to enable the filter to log transactions, or specify OFF to
disable the filter. If no argument is specified the filter is ON.
Examples:
f i l t er F1 I P 192. 168. 100. 151 ON
To apply the filter F2 to IP addresses 192.250.100.1 to 192.250.100.254:
f i l t er F2 I P 192. 250. 100. 0 NETMASK 255. 255. 255. 0 ON
Note: FilterName is a required parameter if you are defining a filter with other
optional parameters such as IP address, or the combination of IP address -
Netmask.
Defining Log Properties
Log properties associated with the filter are applied to all the log entries present
in the filter. The log property definition starts with the key word BEGI N and ends
with END as illustrated in the following example:
Example:
BEGI N <f i l t er name>
l ogFi l enameFor mat . . .
l ogDi r ect or y . . .
l ogI nt er val . . .
l ogFi l eSi ze . . . .
END
LogInterval: Specifies the intervals at which new log files are created.
A new file is created as follows, depending on the LogI nt er val value
specified:
Hour l y - every hour
Dai l y - every day at midnight
Weekl y - every Sunday at midnight
Mont hl y- the first day of the month at midnight
None - only once, when audit server logging starts.
By default the LogI nt er val property is set to Hour l y.
Example:
LogI nt er val Hour l y
LogFileSizeLimit: Specifies the maximum size (in MB) of the log
file. You can use this parameter with any log interval such as weekly,
monthly and so on. Creates a file when the maximum file size limit is
reached or when the defined log interval time elapses.
To override this behavior, specify the size as the l ogi nt er val property
so that a file is created only when the log file size limit is reached.
The default LogFi l eSi zeLi mi t is 10 MB.
Example:
LogFi l eSi zeLi mi t 35
LogFilenameFormat: Specifies the file name format of the log file.
The name of the file can be of the following types:
Static: A constant string that specifies the absolute path and the file
name.
Dynamic: Is an expression that includes the following format
specifiers:
Date ( %{f or mat }t )
% creates filename with NSIP
Note: For more information, see Checklist for Configuring Audit Server
Logging on page 585.
Example:
LogFi l eNameFor mat Ex%{%m%d%y}t . l og
This creates the first file name as Exmmddyy. l og, then on every hour it
creates a file with name as: Exmmddyy. l og. 0, Exmmddyy. l og. 1,
and so on.
Example:
LogI nt er val si ze
LogFi l eSi ze 100
LogFi l eNameFor mat Ex%{%m%d%y}t
Caution: The date format %t specified in the LogFi l enameFor mat
parameter overrides the log interval property for that filter. To prevent a
new file being created every day instead of when the specified log file size
is reached, do not use %t in the LogFi l enameFor mat parameter.
logDirectory: Specifies the directory name format of the log file. The
name of the file can be either of the following:
Static: Is a constant string that specifies the absolute path and
filename.
Dynamic: Is an expression containing the following format
specifiers:
Date (%{format}t)
% creates directory with NSIP
The directory separator depends on the operating system. In Windows, use
the directory separator \.
Example:
LogDi r ect or y di r 1\ di r 2\ di r 3
In the other operating systems (Linux, FreeBsd, Mac, etc.), use the
directory separator /.
Example:
LogDi r ect or y di r 1/ di r 2/ di r 3
Note: For more information, see Checklist for Configuring Audit Server
Logging on page 585.
Default Settings for the Log Properties
The following is an example of the default filter with default settings for the log
properties:
begi n def aul t
l ogFi l enameFor mat audi t l og%{%y%m%d}t . l og
end def aul t
The following are two examples of defining the default filters:
Example 1:
Fi l t er f 1 I P 192. 168. 10. 1
This creates a log file for NSIP 192. 168. 10. 1 with the default values of the
log in effect.
Example 2:
Fi l t er f 1 I P 192. 168. 10. 1
begi n f 1
l ogFi l enameFor mat l ogf i l es. l og
end f 1
This creates a log file for NSIP 192. 168. 10. 1. Since the log file name format
is specified, the default values of the other log properties are in effect.
Adding the IP Addresses of the System
In the configuration file, add the IP addresses of the system that performs the
audit server logging, as well as the Citrix NetScaler Systems whose events must
be logged.
To add the IP addresses
1. At a command prompt, type the following command:
audser ver - addns - f <di r ect or ypat h>\ audi t l og. conf
<directorypath>: Specifies the path to the configuration file (for
example audi t l og. conf .)
You are prompted to enter the information for the following parameters:
NSI P: Specifies the IP address of the Citrix NetScaler System, for
example, 10.102.29.1.
User i d: Specifies the username, for example, nsroot
Passwor d: Specifies the password, for example, nsroot.
If you add multiple NetScaler IP addresses (NSIP), and later you do not want to
log all of Citrix NetScaler System event details, you can delete the NSIPs
manually by removing the NSIP statement at the end of the auditlog.conf file.
During a failover setup, you must add both primary and secondary Citrix
Netscaler IPs to auditlog.conf using the command. Before adding the IP address,
make sure the username and password exist on the system.
Verifying Configuration
Check the configuration file (auditl og. conf ) for syntax correctness to enable
logging to start and function correctly.
To verify configuration, at a command prompt, type the following command:
audser ver - ver i f y - f <di r ect or ypat h>\ audi t l og. conf
<directorypath>: Specifies the path where the configuration file
(auditl og. conf ) resides.
Starting Audit Server Logging
To start audit server logging, enter the following command at a command prompt:
audser ver - st ar t - f di r ect or ypat h\ audi t l og. conf
<directorypath>: Specifies the path to the configuration file
(auditl og. conf .)
Stopping Audit Server Logging
To stop audit server logging that starts as a background process in FreeBSD or
Linux, use the following command:
audser ver - st op
To stop audit server logging that starts as a service in Windows, use the following
command:
audser ver - st opser vi ce
Sample Configuration File
The contents of a sample configuration file are as follows:
##############################
# Thi s i s t he Audi t ser ver conf i gur at i on f i l e
# Onl y t he def aul t f i l t er i s act i ve
# Remove l eadi ng # t o act i vat e ot her f i l t er s
##############################
MYI P <NSAudi t ser ver I P>
MYPORT 3023
# Fi l t er f i l t er _nsi p I P <Speci f y t he Net Scal er I P addr ess t o
f i l t er on > ON
# begi n f i l t er _nsi p
# l ogI nt er val Hour l y
# l ogDi r ect or y l ogdi r \ %A\
# l ogFi l enameFor mat nsi p%{%d%m%Y}t . l og
# end f i l t er _nsi p
Fi l t er def aul t
begi n def aul t
end def aul t
Checklist for Configuring Audit Server Logging
Use the following checklist when you configure audit server logging, and to
troubleshoot problems:
1. Check that the Citrix NetScaler System username and password are valid.
2. If there is a firewall between the system and logging machine, make sure
the RPC 3010/3011 port is open.
3. Make sure that the Citrix NetScaler is accessible from the log machine by
doing the following:
Ping the Citrix NetScaler IP address
Use FTP and Telnet to access the system
4. Verify that the IP address of the system is present in the configuration file
(auditl og. conf )
5. Ensure that the Audit Server IP address is entered in the MYIP field in the
auditlog.conf file
Commonly Used Deployment Scenario
This section describes how to configure the audit server logging feature for a
commonly used deployment scenario, which lets you log all NOTICE events of
Citrix NetScaler System. The following diagram illustrates a typical deployment
topology of audit server logging:
Audit Server Logging Topology
The procedures describe how to create an action, a policy, and bind the policy
globally. The following table lists the parameters that need to be set on Citrix
NetScaler System to configure audit server:
Parameter Value
Name audit1
Auditing Type NSLOG
IP Address 10.102.1.1
Port 3024
Log Level NOTICE
TCP Logging ALL
To create an audit server action
1. In the left pane, expand System, and click Auditing. The Auditing page
2. Select the Servers tab and click Add. The Create Auditing Server dialog
box appears.
3. In the Name text box, type audit1, and in the Auditing Type drop-down
list, select NSLOG.
4. In the IP Address text box, type 10.102.1.1, and in the Port text box, type
3024.
5. In Log Levels, select the NOTICE check box , and select the
DDMMYYYY Date format option.
6. In the Log Facility drop-down list, select LOCAL0, in TCP Logging,
select the ALL option, and in Time Zone, select the Local option.
7. Click Create and click Close. The auditing server Audit1 is created and
added to the Servers list.
The following procedure explains how to create a policy for the audit server
action audit1.
To configure audit server policy
2. On the Policies tab, click Add. The Create Auditing Policy dialog box
appears.
3. In the Name text box type a name for the policy, for example, auditpol1.
4. In the Auditing Type drop-down list, select NSLOG, in the Server drop-
down list, select audit1, click Create, and click Close. The policy is
created and appears in the Policies page.
In the following procedure, you globally bind the audit log policy auditpol1 and
set the priority to 0.
Date Format DDMMYYYY
Log Facility LOCAL0
Time Zone Local
Parameter Value
To globally bind the audit log policy
2. On the Policies tab, click Global Bindings. The Bind/Unbind Auditing
Global Policies dialog box appears.
3. In the Active column, select the check box next to auditpol1, and in the
Priority list box, click the priority as 1, and click OK.
In the Policy pane, the Globally Bound? column displays Yes for the
policy you have bound.
To install and configure the audit server tool on a Windows Server
1. Extract the files from NSauditserver.zip. The following directories are
created:
\ NS\ BI N
\ NS\ ETC
\ NS\ SAMPLES
Note: The BIN directory contains the executable audserver.exe and the
ETC directory contains the auditlog.conf file.
2. Check the version of the auditserver executable using the following
command at a command prompt:
audser ver - ver si on
The output appears in the following format:
Ver si on: Net scal er Audi t i ng Ser ver ( audser ver )
NS<Rel ease_ver si on>: <Bui l d_Ver si on>, Dat e: <Dat e>,
<Ti me>( r el ease) [ Wi ndows NT/ 2000]
3. Type the following command at a command prompt:
audser ver - addns - f . . / et c/ audi t l og. conf
The system prompts for inputs for the following parameters:
NSI P
User i d
Passwor d
4. Enter the following values:
NSI P: 10. 102. 10. 1
User i d: nsr oot
Passwor d: nsr oot
5. Edit the auditlog.conf file located at \NS\ETC. Change the values for the
following parameters in the file:
MYI P 10. 102. 1. 1
MYPORT 3024
Fi l t er def aul t
begi n def aul t
end def aul t
6. Verify the configuration using the following command at a command
prompt:
audser ver - ver i f y - f . . / et c/ audi t l og. conf
A debug file is created and the following output appears:
Debug l og f i l e i s . / nsaudi t . l og- <ddmmyyhhmm> & Log l evel i s 1
Conf i gur at i on f i l e i s cor r ect
7. Start audit server by typing the following command at a command prompt:
audser ver - st ar t - f / et c/ audi t l og. conf
The following output appears:
Debug l og f i l e i s . / nsaudi t . l og- <ddmmyyhhmm> & Log l evel i s 1
Conf i gur at i on f i l e i s cor r ect
Logging starts and the information is logged in the
audi t l og%{%y%m%d}t . l og file under the \NS\BIN directory.
8. To stop audit server, at the command prompt, press Ctrl+C. The following
output appears:
NSAUDI T: qui t t i ng on 2 si gnal !
CHAPTER 12
Advanced Network Configuration
This chapter describes the advanced networking features of the NetScaler and
provides configuration instructions.
Reverse Network Address Translation
Dynamic Routing
Link Load Balancing
Path MTU Behavior
IP Tunneling
IPv6 Support
Reverse Network Address Translation
In Reverse Network Address Translation (RNAT), the NetScaler replaces the
source IP addresses in the packets generated by the servers with public, NAT IP
addresses. The following diagram shows how RNAT works.
RNAT on the Citrix NetScaler
This section provides information about the following aspects of RNAT:
RNAT Modes
RNAT in USIP, USNIP, and LLB Modes
Viewing RNAT Statistics
RNAT Modes
By default, the NetScaler uses the Mapped IP address (MIP) as the NAT IP
address. You can also configure the NetScaler to use a unique NAT IP address for
each subnet. This section describes how to enable RNAT when the NAT IP
address is set to a MIP or a different unique IP address. It also explains how to
configure RNAT using Access Control Lists (ACLs). Following are the
subsections:
Configuring RNAT by Using MIP as the NAT IP Address
Configuring RNAT by Using a unique IP Address as the NAT IP Address
Configuring RNAT by Using ACLs
Configuring RNAT by Using MIP as the NAT IP Address
When using a MIP as the NAT IP address, the NetScaler replaces the source IP
addresses of server-generated packets with the MIP. Thus, the MIP address must
be a public IP address. If Use Subnet IP (USNIP) mode is enabled, the NetScaler
uses the subnet IP address (SNIP) as the NAT IP address.
Chapter 12 Advanced Network Configuration 593
The following table lists and describes the parameters used to specify the MIP as
the NAT IP address.
The following example describes the steps to enable RNAT when the NAT IP is
set to the MIP. In the example, RNAT is enabled for the network and subnet mask,
192.168.1.0 and 255.255.255.0, respectively. The NetScaler changes the source
IP addresses of packets originating from the 192.168.1.0 network to the MIP.
To enable RNAT when the NAT IP is set to MIP using the configuration utility
1. In the navigation pane, expand Network, expand Routing, and click
2. On the RNAT tab, click Configure RNAT. The Configure RNAT dialog
box appears.
3. In the Network and Netmask text boxes, type the network and subnet mask
for which you want to enable RNAT, for example, 192.168.1.0 and
255.255.255.0.
4. Click Create, and then click Close.
To enable RNAT when the NAT IP is set to MIP using the NetScaler command
line
At a NetScaler command prompt, type:
set rnat 192.168.1.0 255.255.255.0
Configuring RNAT by Using a Unique IP Address as the
NAT IP Address
When using a unique IP address as the NAT IP address, the NetScaler replaces the
source IP addresses of server-generated packets with the unique IP address
specified. The unique IP address must be a public NetScaler-owned IP address.
This is illustrated in the following figure.
Network Network or subnet from which the traffic is flowing.
Netmask Subnet mask of the network.
Using a Unique NAT IP Address for a Subnet
The following table lists and describes the parameter used to set a unique NAT IP
address.
In the following procedure, the NetScaler is configured to use two unique IP
addresses, MIP1 and MIP2, for two subnets. The NetScaler replaces the source IP
addresses of packets originating from the 192.168.1.0 and 192.168.2.0 subnets to
10.102.29.50 (MIP1) and 10.102.29.60 (MIP2), respectively.
To enable RNAT when the NAT IP is set to a unique IP address using the
2. On the RNAT tab, select the RNAT network for which you want to
configure the NAT IP address, for example, 192.168.1.0.
3. Click Configure RNAT. The Configure RNAT dialog box appears.
Available NAT IP (s) NAT IP(s) assigned to a source IP or NetScaler IP.
4. In the Available NAT IP (s) list box, select the NAT IP address that you
want to configure, for example, select 10.102.29.50.
5. Click Add. The NAT IP you selected in Step 4 appears in the Configured
NAT IP (s) list box.
6. Click OK.
7. Repeat Steps 3 -7 to configure the NAT IP address for 192.168.2.0 to
10.102.29.60.
To enable RNAT when the NAT IP is set to a unique IP address using the
At a NetScaler command prompt, type:
set rnat 192.168.1.0 255.255.255.0 -natip 10.102.29.50
set rnat 192.168.2.0 255.255.255.0 -natip 10.102.29.60
Note: If multiple NAT IP addresses are configured for a subnet, the NAT IP
address is selected using the round robin algorithm.
Configuring RNAT by Using ACLs
You can configure the NetScaler to use a unique IP address for traffic that
matches an ACL. The following section describes how to configure an ACL, if no
ACL is currently configured, and how to configure RNAT and then apply the
ACL. This section provides the procedure to change the source IP and destination
port information based on an ACL.
Note: ACL-based RNAT is not applied to traffic originating from the
NetScaler.
Changing the Source IP Address Based on an ACL
The steps to change the source IP address based on an ACL are divided into the
following tasks:
1. Configure the ACL
2. Configure RNAT to change the source IP address
3. Apply the ACL
The configuration steps are illustrated in the following figure.
Changing Source IP Address
The following table lists and describes the parameters used to configure an ACL.
In the following procedure, an ACL, named acl1, that allows traffic originating
from a server with IP address 10.102.29.40 to an external client with IP address
209.165.202.11 is configured.
To configure an ACL using the configuration utility
1. In the navigation pane, expand Network and click ACLs. The ACLs page
appears.
Name Name of the ACL.
Action ACL action. If a packet matches the condition represented
by an ACL, the NetScaler processes the packet, bridges
the packet, or drops the packet. These actions are
summarized as follows:
ALLOW. The NetScaler processes the packet.
BRIDGE. The NetScaler bridges the packet to the
destination without processing it.
DENY. The NetScaler drops the packets.
Operator Logical operator to be used while comparing the source IP
address of the packet.
Low Initial IP address in a range of IP addresses.
High Last IP address in a range of IP addresses.
3. In the Name text box, type the name of the ACL. For example, type acl1.
4. In the Action and Operator drop-down lists, select the action and the
operator that you want to configure, for example, select ALLOW and =.
5. Under Source, in the Low and High text boxes, type the IP addresses. For
example, type 10.102.29.40 and 10.102.29.40, respectively.
6. Under Destination, in the Low and High text boxes, type the IP addresses.
For example, type 209.165.201.11 and 209.165.201.11, respectively.
To configure an ACL using the NetScaler command line
add acl acl1 allow -srcip 10.102.29.40 -destip 209.165.201.11
The following example describes the steps to configure RNAT to change the
source IP address of all packets that match the ACL created. In the example, the
NetScaler modifies the source IP address of packets that match acl1, to
209.165.202.129.
To configure RNAT to change the Source IP address based on an ACL using
2. Click the RNAT tab and click Configure RNAT. The Configure RNAT
dialog box appears.
3. Click the ACL radio button.
4. In the ACL Name drop-down list box, select the ACL that you want to
configure, for example, acl1.
want to configure, for example, 209.165.202.129.
6. Click Add. The NAT IP you selected appears in the Configured NAT IP
(s) list box.
To configure RNAT to change the Source IP Address based on an ACL using
set rnat acl1 -natip 209.165.202.129
To apply an ACL
You must apply the ACL for the ACL to function. For instructions on how to
apply an extended ACL using the configuration utility, see Applying Extended
ACL in the Basic Network Configuration chapter.
apply ns acls
Changing the Source IP and Destination Port Based on an ACL
The steps to change the source IP and destination port based on an ACL are
divided into the following tasks:
1. Configure the ACL
2. Configure RNAT to change the source IP address and Destination Port
3. Apply the ACL
This is illustrated in the following figure.
Changing Source IP Address and Port
In the following procedure, an acl, acl1, that allows traffic originating from a
server with IP address 10.102.29.40 to an external client 209.165.202.11 is
configured. The protocol is specified as TCP.
To configure an ACL using the configuration utility
1. In the navigation pane, expand Network and click ACLs. The ACLs page
appears.
3. In the Name text box, type the name of the ACL. For example, type acl1.
4. In the Action, Operator, and Protocol drop-down lists, select the action,
operator, and the protocol that you want to configure. For example,
ALLOW, =, and TCP.
5. Under Source, in the Low and High text boxes, type the IP addresses. For
example, type 10.102.29.40 and 10.102.29.40.
6. Under Destination, in the Low and High text boxes, type the IP addresses.
For example, type 209.165.201.11 and 209.165.201.11.
To configure an ACL using the NetScaler command line
add acl acl1 allow -srcip 10.102.29.40 -destip 209.165.201.11
-protocol TCP
In the following procedure, an RNAT is configured to replace the source IP
address of packets related to the example ACL, acl1, with the NAT IP address,
209.165.202.129. The destination port is configured to 8080.
To set RNAT to change the Source IP address and Destination Port using
2. Click the RNAT tab and click Configure RNAT. The Configure RNAT
dialog box appears.
3. Click the ACL radio button.
4. In the ACL Name drop-down list box, select the ACL that you want to
configure, for example, select acl1.
5. In the Redirect Port text box, type the port, for example, 8080.
6. In the Available NAT IP (s) list box, select the NAT IP address which you
want to configure, for example, 209. 165.202. 129.
7. Click Add. The NAT IP you selected appears in the Configured NAT IP
(s) list box.
To set RNAT to change the Source IP address and Destination Port using
set rnat acl1 -natip 209.165.202.129 -redirectPort 8080
To apply an ACL
You must apply the ACL for the ACL to function. For instructions on how to
apply an extended ACL using the configuration utility, see Applying Extended
ACL in the Basic Network Configuration chapter.
apply ns acls
Note: The NetScaler uses ports 1024 to 64000 for mapped IP addresses and
subnet IP addresses.
RNAT in USIP, USNIP, and LLB Modes
When RNAT and Use Source IP (USIP) are both configured, RNAT takes
precedence. When RNAT and USNIP are configured, selection of the source IP
address is based on the state of USNIP as follows:
If USNIP is off, the NetScaler uses the mapped IP addresses.
If USNIP is on, the NetScaler uses SNIP as the NAT IP address.
This behavior does not apply when a unique NAT IP address is used.
In a topology where the NetScaler performs both Link Load Balancing (LLB) and
RNAT for traffic originating from the server, the NetScaler selects the source IP
address based on the router. The LLB configuration determines selection of the
router.
Note: For more information about LLB, see Link Load Balancing on page
619.
Viewing NAT Statistics
You can now retrieve statistics of Reverse Network Address Translation (RNAT).
Following are two commands that provide RNAT statistics:
st at r nat - provides the statistics of Reverse Network Address
translation (RNAT)
The command st at r nat provides information on the parameters listed in the
following table.
st at r nat i p <nat i p>- provides the statistics of Reverse Network
Address Translation (RNAT) for a Network Address Translation (NAT) IP
address.
The command st at r nat i p provides information on the parameters listed in
The following SNMP commands are also available:
nsRnat Gl obal St at Tabl e - provides RNAT statistics for all RNAT
sessions
nsRnat Per I PSt at Tabl e - provides RNAT statistics for each IP
address
Bytes received Total number of bytes received for all RNAT sessions
Bytes sent Total number of bytes sent for all RNAT sessions
Packets received Total number of packets received for all RNAT sessions
Packets sent Total number of bytes sent for all RNAT sessions
Syn sent Total number of syn sent for all RNAT sessions
Current sessions Total number of sessions opened for all RNAT
Bytes received Total number of bytes received for the NATIP in RNAT sessions
Bytes sent Total number of bytes sent for the NATIP in RNAT sessions
Packets received Total number of packets received for the NATIP in RNAT
sessions
Packets sent Total number of packets sent for the NATIP in RNAT sessions
Syn sent Total number of syn sent for the NATIP in RNAT sessions
Current sessions Total number of sessions opened for the NATIP in RNAT
Dynamic Routing
Dynamic routing enables routers to automatically obtain topology information,
routes, and IP addresses from neighboring routers. To use dynamic routing on the
NetScaler, you must first enable the routing protocol.
To use dynamic routing on a system, you must:
1. Enable dynamic routing
2. Enable the routing protocol
The NetScaler supports the following protocols:
Routing Information Protocol (RIP) version 1 and version 2 as defined in
RFC 1058 and RFC 2453
Open Shortest Path First (OSPF) version 2 as defined in RFC 2328
Border Gateway Protocol (BGP) as defined in RFC 1771
When a dynamic routing protocol is enabled, the corresponding routing process
monitors route updates and advertises routes. The routing processes can also be
placed in passive mode. Routing protocols enable an upstream router to load
balance traffic to identical vservers hosted on two standalone NetScalers using
the Equal Cost Multipath technique.
High Availability Setup - Active Standby Mode
In Active Standby mode, the primary node runs the routing process and
propagates routing table updates to the secondary node. The routing table of the
secondary node mirrors the routing table on the primary node.
After failover, the secondary node takes time to start the protocol and learn the
routes, and update its routing table. But this does not affect routing, because the
routing table on the secondary node is identical to the routing table on the primary
node. This mode of operation is known as Active Standby mode.
This section describes how to configure RIP, OSPF, and BGP on the system. The
topics are covered in the following sequence:
Enabling and Disabling Dynamic Routing
Using RIP
Using OSPF
Using BGP
Enabling and Disabling Dynamic Routing
The following procedure describes the steps to enable and disable dynamic
routing feature on the NetScaler.
To enable or disable dynamic routing using the configuration utility
2. Under the Modes & Features group, click advanced features. The
Configure Advanced Features dialog box appears.
3. Do one of the following:
To enable dynamic routing, select the Dynamic Routing check box.
To disable dynamic routing, clear the Dynamic Routing check box.
5. Click Yes.
To enable or disable dynamic routing using the NetScaler command line
At the NetScaler command prompt, type one of the following:
enable ns feature dynamic routing
disable ns feature dynamic routing
Using RIP
Routing Information Protocol (RIP) is based on the Distance Vector protocol. The
NetScaler supports RIP as defined in RFC 1058 and RFC 2453. RIP can run on
any subnet.
This section provides instructions to perform the following tasks:
Enabling and Disabling RIP
Configuring RIP
Enabling and Disabling RIP
The following example describes the steps to enable and disable RIP routing
protocol. After you enable RIP, the system starts the RIP process.After you
disable RIP, the NetScaler stops the RIP process.
To enable and disable RIP routing using the configuration utility
To enable RIP routing, select the RIP Routing check box.
To disable RIP routing, clear the RIP Routing check box.
5. Click Yes.
To enable or disable RIP routing using the NetScaler command line
enable ns feature rip
disable ns feature rip
Configuring RIP
On the NetScaler, RIP can function in one of the following modes:
Advertising and learning routes
Listen only
No Route learning
The following table lists and describes the parameters used to configure RIP.
Advertising Routes
RIP enables an upstream router to load balance traffic between two identical
vservers hosted on two standalone NetScaler devices.By using advertising routes,
an upstream router can track network entities located behind the NetScaler. The
following table lists and describes the parameters required to advertise routes.
Passive Interface Name of the passive interface.
Network Broadcast network on which RIP is to be run.
Netmask Subnet mask for the broadcast network.
The following example describes the steps to configure RIP to advertise routes on
the NetScaler.
To configure RIP to advertise routes using the configuration utility
1. In the navigation pane, expand Network, expand Routing, and click RIP.
The RIP page appears in the details pane.
2. Select the network for which you want to configure RIP, for example,
0.0.0.0.
3. Click Open. The Configure RIP dialog box appears.
4. Under Redistribute Routes, select the kernel check box. Click OK.
To configure RIP to advertise routes using the NetScaler command line
set router rip -kernelRedistribute
Limiting RIP Propagations
You can configure the NetScaler to listen to RIP advertisements on a particular
interface. The following table lists and describes the parameters required for
configuring the interface for listen-only mode.
The following example describes the steps to limit RIP propagations. The
interface 1/8 is set to listen-only mode.
Static Redistribute State of the router in redistributing static routes. Use this
option to enable the redistribution of static routes.
The default value is
NS_RIP_REDISTRIBUTE_STATIC.
Kernel Redistribute State of the router in redistributing kernel routes. Use this
option to enable the redistribution of kernel routes. The
default value is NS_RIP_REDISTRIBUTE_KERNEL
Connection Redistribute State of the router in redistributing connected routes. Use
this option to enable the redistribution of connected routes.
The default value is NS_RIP_REDISTRIBUTE_CON.
Passive Interface Sets the mode of the interface to listen only.
To limit RIP propagations using the configuration utility
0.0.0.0.
4. In the Passive Interface text box, type the name of the interface you want
to use, for example, 1/8. Click OK.
To limit RIP propagations using the NetScaler command line
set router rip -passiveInterface 1/8
Controlling Route Learning
Route learning is disabled by default.The following table lists and describes the
parameters required to control route learning.
The following example describes the steps to set RIP to learn routes.
To configure RIP to learn routes using the configuration utility
0.0.0.0.
4. Select the Learn Routes check box. Click OK.
To configure RIP to learn routes using the NetScaler command line
set router rip -learnRoute
Learn Route State of Route learning. Use this option to enable route
learning and installation in the kernel. The default value is
NS_RIP_SET_LEARNING.
Viewing RIP Information
The following example describes the steps to view RIP settings.
To view the RIP settings using the configuration utility
In the navigation pane, expand Network, expand Routing, and click RIP. The
RIP page appears in the details pane. The following information appears on the
RIP page: Default Metric, Passive Interface, Networks, Netmask, and Learn
Routes.
To view the RIP settings using the NetScaler command line
show router rip
Using OSPF
The NetScaler supports Open Shortest Path First (OSPF) Version 2 (RFC 2328).
The features of OSPF are:
The NetScaler supports OSPF within a single area only.
If a vserver is active, the host routes to the vserver can be injected into the
FreeBSD kernel.
OSPF can run on any subnet.
The NetScaler can advertise static routes, routes to downstream networks
and routes to upstream routers.
Route learning advertised by neighboring OSPF routers can be disabled on
the system.
The NetScaler can advertise Type-1 or Type-2 external metrics for all
routes.
The NetScaler can advertise user-specified metric settings for stub
networks.
The OSPF area ID for the NetScaler can be specified.
OSPF on a NetScaler is supported on a broadcast network, for example, an
Ethernet LAN.
This section includes the following sections:
Enabling and Disabling OSPF
Configuring OSPF
OSPF in a High Availability Setup - Active Standby Mode
NSSA Support
Enabling and Disabling OSPF
The following example describes the steps to enable and disable the OSPF
routing protocol. When OSPF is enabled, the NetScaler starts the OSPF process.
When OSPF is disabled, the NetScaler stops the OSPF routing process.
To enable and disable OSPF routing using the configuration utility
To enable OSPF routing, select the OSPF Routing check box.
To disable OSPF routing, clear the OSPF Routing check box.
5. Click Yes.
To enable or disable OSPF routing using the NetScaler command line
enable ns feature OSPF
disable ns feature OSPF
Configuring OSPF
You can use OSPF on the NetScaler to advertise routes, listen on interfaces, and
control route learning.
On the system, OSPF can function in one of the following modes:
Configuring Advertising Routes
Limiting OSPF Propagations
Viewing OSPF Settings
The following table lists and describes the parameters required to configure
OSPF.
In the following example, OSPF is configured for router ID 10.102.29.50, and the
interface 1/8 is configured as the passive interface.
To configure OSPF using the configuration utility
1. In the navigation pane, expand Networks, expand Routing, and click
OSPF. The OSPF page appears in the details pane.
2. Select the Router ID for which you want to configure OSPF, for example,
10.102.29.50.
3. Click Open. The Configure OSPF dialog box appears.
4. In the Passive Interface text box, type the name of the interface that you
want to use, for example, 1/8.
5. Under Subnet Configuration, in the Network, Netmask and Router Area
text boxes, type the network, subnet mask and the router area that you want
to configure. For example, type 10.102.29.0, 255.255.255.0, and 0.
6. Click OK.
To configure OSPF using the NetScaler command line
set router ospf -routerID 10.102.29.50 -passiveInterface 1/8
-network 10.102.29.0 255.255.255.0 -area 0
Configuring Advertising Routes
OSPF enables an upstream router to load balance traffic between two identical
vservers hosted on two standalone NetScaler devices. By using advertising
routes, an upstream router can track network entities located behind the
NetScaler. The following table lists and describes the parameters required to
advertise routes.
Passive Interface Name of the passive interface.
Network Broadcast network on which OSPF is to be run.
Netmask Subnet mask for the broadcast network.
Router Area Area ID of the area in which OSPF is running.
The following example describes the steps to configure OSPF to advertise routes
on the NetScaler.
To configure OSPF to advertise routes using the configuration utility
1. In the navigation pane, expand Network, expand Routing, and click OSPF.
The OSPF page appears in the details pane.
2. Select the network for which you want to configure OSPF, for example,
0.0.0.0.
4. Under Redistribute Routes, select the kernel check box. By default, the
Type-2 radio button is selected. Click OK.
To configure OSPF to advertise routes using the NetScaler command line
set router ospf -kernelRedistribute
Limiting OSPF Propagations
You can configure the NetScaler to listen to OSPF advertisements on a particular
interface. The following table lists and describes the parameters required for
configuring the interface for listen-only mode.
The following example describes the steps to configure the NetScaler to listen to
OSPF advertisements on the interface 1/8.
Static Redistribute State of the router in redistributing static routes. Use this
option to enable the redistribution of static routes. The
default value is
NS_OSPF_REDISTRIBUTE_STATIC.
Kernel Redistribute State of the router in redistributing kernel routes. Use this
option to enable the redistribution of kernel routes. The
default value is NS_OSPF_REDISTRIBUTE_KERNEL
Connection Redistribute State of the router in redistributing connected routes. Use
this option to enable the redistribution of connected routes.
The default value is NS_OSPF_REDISTRIBUTE_CON.
Passive Interface Sets the mode of the interface to listen only.
To limit OSPF propagations to a single interface using the configuration
utility
2. Select the router ID for which you want to configure OSPF, for example,
10.102.29.50.
4. In the Passive Interface text box, type the name of the interface that you
want to use, for example, 1/8.
5. Click OK.
To limit OSPF propagations to a single interface using the NetScaler
command line
set router ospf -passiveInterface 1/8
The following table lists and describes the parameters required to control route
learning.
To configure OSPF to learn routes using the configuration utility
0.0.0.0.
4. Select the Learn Routes check box. Click OK.
To configure OSPF to advertise routes using the NetScaler command line
set route ospf -learnRoute
Learn Route State of the router in learning routes from OSPF. Use this
option to enable route learning from OSPF. The default
value is NS_OSPF_SET_LEARNING.
Viewing OSPF Settings
To view the OSPF settings using the configuration utility
In the navigation pane, expand Network, expand Routing, and click OSPF. The
OSPF page appears in the details pane and displays information about the Router
ID, Passive Interface, Networks, Netmask, Area, and Learn Routes.
To view the OSPF settings using the NetScaler command line
show router ospf
NSSA Support
The Not-So-Stubby-Area (NSSA) is an enhancement of OSPF area. NSSAs are
similar to the existing OSPF stub area configuration option; however, NSSAs can
inject external routes in a limited fashion into the stub area. The NetScaler is
enhanced to provide NSSA support. To support NSSAs, a new option bit (the "N"
bit) and a new type 7 Link State Advertisement (LSA) area are defined. Type 7
LSAs support external route information within an NSSA. An NSSA area border
router (ABR) translates type 7 LSA into a type 5 LSA that is propagated into the
OSPF domain. The OSPF specification defines only the following general classes
of area configuration:
Type 5 LSA: Originated by routers internal to the area or flooded into the
area by area border routers.
Stub: Allows no type 5 LSAs to be propagated into/throughout the area and
instead depends on default routing to external destinations.
Using BGP
The NetScaler supports BGP-4 (RFC 1771). The features of BGP are:
BGP can run on any subnet.
The NetScaler advertises routes from the FreeBSD kernel to BGP peers.
The NetScaler injects host routes to Virtual IP addresses (VIPs) into the
FreeBSD kernel based on the health of the underlying vservers.
The NetScaler advertises downstream networks.
The NetScaler generates configuration files for running BGP on the
secondary node after failover.
This section provides instructions to perform the following tasks:
Enabling and Disabling BGP
Enabling BGP on a Non-NSIP Network
Configuring BGP
Viewing BGP Settings
Enabling and Disabling BGP
The following example describes the steps to enable and disable the BGP routing
protocol. When BGP is enabled, the NetScaler starts the BGP process on the
NetScaler IP (NSIP) subnet. When BGP is disabled, the NetScaler stops the BGP
process on the NSIP subnet.
To enable or disable BGP routing using the configuration utility
To enable BGP routing, select the BGP Routing check box.
To disable BGP routing, clear the BGP Routing check box.
5. Click Yes.
To enable or disable BGP routing using the NetScaler command line
enable ns feature BGP
disable ns feature BGP
Enabling BGP on a Non-NSIP Network
To enable BGP on a non-NSIP network, perform the following tasks:
1. Enable management access on the Subnet IP (SNIP).
2. Enable BGP on the IP.
3. Enable mode Use Subnet IP (USNIP).
4. Add a service that points to each peer.
Configuring BGP
You can use BGP on a NetScaler to advertise routes and to learn routes. The
following table lists and describes the parameters required to configure BGP.
The following example describes the steps to configure a BGP instance.
To configure BGP using the configuration utility
1. In the navigation pane, expand Network, expand Routing, and click BGP.
The BGP page appears in the details pane.
2. Click Add. The Configure BGP dialog box appears.
3. In the Autonomous System text box, type the name of the autonomous
system that you want to use, for example, 11.
4. Click Create.
To configure BGP using the NetScaler command line
add router bgp 11
Advertising Routes
You can configure the NetScaler to advertise host routes to VIPs and to advertise
routes to downstream networks. The following table lists and describes the
parameters required to configure the NetScaler device to advertise BGP routes.
The following example describes the steps to configure BGP to advertise routes
on the NetScaler.
Autonomous System BGP autonomous system.
Static Redistribute State of the router in redistributing static routes. The
default value is NS_BGP_REDISTRIBUTE_STATIC.
Kernel Redistribute State of the router in redistributing kernel routes. The
default value is NS_BGP_REDISTRIBUTE_KERNEL.
Connection Redistribute State of the router in redistributing connected routes. The
default value is NS_BGP_REDISTRIBUTE_CON.
To configure BGP to advertise routes using the configuration utility
2. Select the network for which you want to configure BGP, for example,
0.0.0.0.
3. Click Open. The Configure BGP dialog box appears.
4. Under Redistribute Routes, in the Kernel text box, type the route map that
you want to apply while redistributing routes. The kernel check box is
enabled.
5. Click OK.
To configure BGP to advertise routes using the NetScaler command line
set router bgp 11 -kernelRedistribute -kernelRouteMap route2
Modifying a BGP Instance
The following procedure describes the steps to modify a BGP instance. In the
example, the BGP instance 11 is modified. The example configures the network
to 10.102.29.0 and the netmask to 255.255.255.0.
To modify an existing BGP instance using the configuration utility
2. Select the Autonomous System that you want to modify, for example, 11.
3. Click Open. The Configure BGP dialog box appears.
4. Under Subnet Configuration, in the Network and Netmask text boxes,
type the network and the subnet mask that you want to configure. For
example, type 10.102.29.0 and 255.255.255.0.
5. Click OK.
To modify an existing BGP instance using the NetScaler command line
set router bgp 11 -network 10.102.29.0 255.255.255.0
Viewing BGP Settings
The following example describes the steps to view the BGP settings.
To view the BGP settings using the configuration utility
In the navigation pane, expand Network, expand Routing, and click BGP. The
BGP page appears in the details pane and displays information about the
Autonomous System, Router ID, Networks, Netmask, and Learn Routes.
To view the BGP settings using the NetScaler command line
show router bgp 11 -routeMap route2
Configuring Route Maps
The NetScaler supports the use of route maps to configure policies for route
redistribution. Route maps can be associated with BGP neighbors or with the
redistribute directive. You can use route maps on the NetScaler to:
Set the next hops for the routes being advertised to a neighbor (setting the
next-hop in a route map, then associating it with that neighbor).
Control the prefixes that are advertised (using the matchIP argument and
associating it with the redistribute directive).
To configure route maps, use the following vtysh commands:
#conf i gur e t er mi nal
#r out e- map abcd deny 1
You can associate both prefix lists and access lists with route maps by using the
following command:
#mat ch i p addr ess <pr ef i x- l i st > | <access- l i st >
<1- 199> I P access- l i st name
<1300- 2699> I P access- l i st name
WORD I P access- l i st name
pr ef i x- l i st Mat ch ent r i es of pr ef i x- l i st s
The NetScaler supports dynamic routing and the following associated protocols:
RIP, OSPF, and BGP. The NetScaler uses these routing protocols to advertise
routes to networks and/or VIPs owned by the NetScaler and to the neighboring
router.
For VIPs owned by the NetScaler, the advertisement of host routes depends on
the state of the entity associated with the host route. These entities are vservers,
services, or other downstream devices. If an entity is not active, its host route is
not advertised. This controlled advertisement of host routes through the routing
protocol is known as Route Health Injection (RHI).
This section provides information about the following aspects of RHI:
Enabling RHI
Limiting Host Route Advertising for VIPs
Advertising Networks
Viewing Routes Learned Through Dynamic Routing Protocols
Enabling RHI
The following procedure describes the steps to enable RHI. In the example, RHI
is enabled for an IPV4 VIP, 10.102.29.54. This advertises the host route
associated with the IP address.
To enable RHI using the configuration Utility
1. In the navigation pane, expand Network and click IPs. The IPs page
2. Click the IPV4s tab and select the vserver IP address for which you want to
enable RHI, for example, select 10.102.29.54.
4. Under Host Route, select the Enable check box.
5. Click OK.
To enable RHI using the NetScaler command line
set ip 10.102.29.54 -hostroute enabled
Limiting Host Route Advertising for VIPs
A VIP can represent one or more vservers. Hence, the state of the VIP depends on
the state of the vservers it represents. By default, a host route associated with a
VIP is not advertised when a vserver is down or disabled. The following table
lists and describes the parameters required to configure the host route advertising
for VIPs.
Advertising Networks
You can configure the NetScaler to advertise networks for RHI. The following
table lists and describes the parameters required to advertise networks.
The following procedure defines the steps to advertise networks. The first IP
address in the network is set to 10.102.29.0. The netmask of the network is set to
255.255.255.0. The gateway of the network is set to 10.102.29.50. The dynamic
routing protocol is set to OSPF. The valid protocol values are: OSPF, RIP, and
BGP.
To advertise networks using the configuration utility
2. Click Add. The Create Route dialog box appears.
3. In the Network, Netmask and Gateway IP text boxes, type the network,
subnet mask and the gateway IP address which you want to advertise. For
example, type 10.102.29.0, 255.255.255.0, and 10.102.29.50.
4. Under Route Advertisement, select the Over-ride Global check box.
ONE_VSERVER Host route is advertised when at least a single vserver is
running.
ALL_VSERVERS Host route is advertised only when all the vservers are
running.
None Host route is advertised when none of the vservers are
running.
Network Destination network.
Netmask Subnet mask of the destination network.
Gateway IP Gateway for this route.
Over-ride Global State of advertisement of this route. The valid options for
this parameter are DISABLED and ENABLED.
5. Select Enable.
6. Under Protocol, select OSPF check box. Click Create and click Close.
To advertise networks using the NetScaler command line
add route 10.102.29.0 255.255.255.0 10.102.29.50 -advertise ENABLED
-protocol OSPF
Note: If you have configured static routes on the NetScaler and enabled L3
mode, static routes configuration takes precedence over the L3 mode
configuration. For instance, if you have configured a firewall load balancing
vserver and static routes on the NetScaler, the NetScaler uses the routing table to
route the traffic instead of sending the traffic to the firewall load balancing
vserver.
Viewing Routes Learned Through Dynamic
Routing Protocols
The following procedure provides the steps to view the routes added by routing
protocols. You can view all routes in the routing table. Dynamically installed
routes are marked as DYNAMIC.
To view the routes using the configuration utility
In the navigation pane, expand Network, expand Routing, and click Routes. The
Routes page appears in the details pane. The information on the Networks,
Netmask, Gateway IP, Costs, Flags and Advertise / via appears in the Routes
page.
To view the routes using the NetScaler command line
show route
Link Load Balancing
Link load balancing (Link LB) balances inbound and outbound traffic
transparently across multiple Internet connections. It enables an enterprise with
more than one Internet connection, or with a private network, to monitor and
control traffic so that users are routed over the best available Internet link. For
example, an organization can connect to the Internet through two different service
providers, such as Sprint and AT&T.
This section provides information about the following aspects of Link LB:
Monitoring Routers
Destination IP-Based Persistence
Load Balancing Policy
Implementing RNAT with Link Load Balancing
Configuring Link Load Balancing
Configuring the Backup Router
Configuring RNAT with Link Load Balancing
Monitoring Routers
The NetScaler monitors configured routers and services bound to the LB route
VIP, assigning a default monitor if none is configured. The default monitor type is
PING, which is also the recommended monitor type. The NetScaler supports
transparent monitoring, which means that monitored devices can be upstream of
the routers.
Note: There is no limit to the number of routers that can be configured.
Destination IP-Based Persistence
In link LB, round robin selection of routers distributes packets equally among the
routers, even if they operate at different speeds. This can result in retransmissions
or out-of-order packets. Destination IP-based persistence resolves this by routing
all traffic from a single client, in a single session, through a single router.
The destination IP session entry contains the router information that is used as the
gateway to reach the destination. When the first IP packet is sent to the
destination IP, an entry is created and populated with the router information for
the destination IP. This information elapses after a specified period of inactivity.
The timeout period can be configured by using the GUI or the CLI. After sending
the first packet to the destination IP, the NetScaler sends all subsequent traffic
through the router used for that packet.
The destination IP persistence feature selects a server based on the persistence
setting. If the load balancing policies determine that the server selection is not
appropriate, they override the selection. The NetScaler then updates the session
entry with the router selection determined by the load balancing policies.
Optionally, you can design a persistence mask to create one session for a given
destination IP. To configure load balancing, you can also use parameters listed in
Load Balancing Policy
The NetScaler applies a load balancing policy to packets routed through the LB
route through the associated VIP. The preferred IP and preferred port parameters
are valid if the persistence feature is enabled.
If the preferred router is up, LB updates the server statistics and returns the server
structure for the selected router. If the preferred server is not available, LB selects
the ideal router based on the LB policy from the VIP server list. Link LB does not
support the least connections LB method.
Link LB supports the following LB methods:
ROUNDROBIN
DESTINATIONIPHASH
LEASTBANDWIDTH
LEASTPACKETS
Link LB supports the following persistence type:
DESTINATION IP
Implementing RNAT with Link Load Balancing
Reverse NAT (RNAT) can be applied on outbound traffic from an enterprise
network in a manner that guarantees that the return traffic is routed along the
same path as inbound traffic. This functionality is achieved using both link load
balancing and RNAT extensions.
Session Entry Time-out Session entry timeout is specified in minutes. The range is
2-1440 minutes. The default value is 2 minutes. The
persistence aging timeout is stored in the VIP. If the idle
time of a session is equal to the idle timeout, the session is
deleted.
Maximum Session Entries If a router goes down, and an existing session points to the
router for the next packet of the session (with destination
IP-based persistence), load balancing selects another
service or router based on the load balancing policy, and
updates the session table to point to the newly selected
service or router.
To implement RNAT with link LB, perform the following steps:
1. Configure link LB
2. Configure Reverse NAT
3. Enable the USNIP feature in the NetScaler
Note: The hosts on an enterprise network must have the NetScaler designated
as their gateway.
Configuring Link LB
This section describes the procedure to configure link LB on the NetScaler. The
following table lists and describes the parameters required to configure link LB.
The following table summarizes the names and values of the entities that must be
Follow these steps to configure link LB:
1. Create a transparent monitor
2. Create a service and bind the service to the monitor
3. Create a directly addressable LB vserver and bind the service to the vserver
Network IP address of the network to which the route belongs.
Netmask Subnet mask to which the route belongs.
Gateway Name Name of the route.
Directly Addressable Specifies that the virtual server can be directly addressable
externally. If selected, the IP address and Port fields are
required; otherwise, they are optional.
Transparent Monitor uses other network device to access the
destination.
Monitor monitor-HTTP-1 10.10.10.11
Service service-ANY-1 10.102.29.50
LB Vserver vserver-LB-1 NA
4. Set persistence and LB method
5. Configure link LB
The following procedure describes the steps to add a transparent monitor named
monitor-HTTP-1. In the example, a transparent HTTP monitor with an IP address
of 10.10.10.11 is created.
To create a transparent monitor using the configuration utility
3. In the Name and Destination IP text boxes, type the name and destination
IP address of the monitor, for example, monitor-HTTP-1 and 10.10.10.11.
4. In the Type drop-down list box, select the type of the monitor, for example,
HTTP.
5. Under Standard Parameters, select the Transparent check box.
To create a transparent monitor using the NetScaler command line
add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent
YES
The following procedure describes the steps to add a service named service-ANY-
1 of type ANY. The monitor created in the earlier procedure, monitor-HTTP-1, is
bound to this service.
To create a service and bind the monitor to it using the configuration utility
3. In the Service Name, Server, and Port text boxes type the name, IP
address, and port of the service, for example, service-ANY-1, 10.102.29.50,
and *.
4. In the Protocol drop-down list box, select the type of the service, for
example, ANY.
5. Under Available, in the Monitors list box, select the monitor that you want
to bind to the service, for example, monitor-HTTP-1.
To create a service and bind the monitor to it using the NetScaler command
line
add service service-ANY-1 10.102.29.50 ANY *
The following procedure describes the steps to add a directly addressable LB
vserver named vserver-LB-1 of type ANY. The service named service-ANY-1 is
bound to this vserver.
To create an LB vserver and bind the service to it using the configuration
utility
appears.
3. In the Name text box, type the name of the vserver, for example, vserver-
LB-1.
4. Select the Directly Addressable check box.
5. In the Protocol drop-down list box, select the type of the vserver, for
example, ANY.
6. Select the Active check box corresponding to the service that you want to
bind to the vserver, for example, service-ANY-1.
To create an LB vserver and bind the service to it using the NetScaler
command line
bind lb vserver vserver-LB-1 service-ANY-1
The following procedure describes the steps to set the LB method of vserver-LB-
1 to round robin. The persistence method is set to the destination IP method.
To set the LB method and persistence using the configuration utility
2. Select the vserver for which you want to configure LB method and
persistence, for example, vserver-LB-1.
appears.
4. Click the Method and Persistence tab. In the drop-down list box, under
LB Method, select round robin.
5. Under Persistence, in the Persistence drop-down list box, select DESTIP.
6. In the PersistMask and Timeout text boxes, type the subnet mask and
timeout values, for example, 225.225.225.225 and 2.
7. Click OK.
To set the LB method and persistence using the NetScaler command line
set lb vserver vserver-LB-1 -persistenceType DESTIP -lbmethod
roundrobin
The following procedure describes the steps to configure link LB. In the example
the vserver called vserver-LB-1 is set as the gateway.
To configure link LB using the configuration utility
2. Click the LLB tab and click Add. The Configure LB Route dialog box
appears.
3. In the Network and Netmask text boxes, type the network and the subnet
mask that you want to configure, for example, 1.1.10.0 and 255.255.255.0.
4. In the Gateway Name drop-down list box, select the vserver, for example,
vserver-LB-1.
To configure link LB using the NetScaler command line
add lb route 1.1.10.0 255.255.255.0 vserver-LB-1
Configuring the Backup Router
The backup router is used when the primary router fails. The following table
summarizes the names and values of the entities that must be configured to set up
a backup router.
Follow these steps to configure a backup router:
1. Create services
2. Create a primary and secondary router
3. Set the secondary router as the backup router
The following procedure describes the steps to add an active router named R1. A
router named R2 is configured as backup router for R1. If R1 fails, traffic is
routed to R2.
The following procedure describes the steps to add two services named R1 and
R2. The protocol of type R1 and R2 is set to ANY.
To create services using the configuration utility
address, and port of the service, for example, R1, 10.102.29.4, and *.
example, ANY.
6. Repeat Steps 1-5 to create another service with name, IP address, port, and
protocol as R2, 10.102.29.5, *, and ANY.
To create services using the NetScaler command line
add service R1 10.102.29.4 ANY *
add service R2 10.102.29.5 ANY *
LB Service R1 10.102.29.4
R2 10.102.29.5
LB Vserver vserver-LB-Pri-1 NA
vserver-LB-Sec-1 NA
The following procedure describes the steps to add an LB vserver named vserver-
LB-Pri-1 of type ANY. The vserver is set as a directly addressable vserver. The
LB method is set to round robin and the service R1 is bound to this vserver.
To create a primary router using the configuration utility
appears.
LB-Pri-1, and select the Directly Addressable check box.
4. In the IP Address and Port text boxes, type the IP address and port of the
vserver, for example, 10.102.23.77 and *.
example, ANY.
bind to the vserver, for example, R1.
To create a primary router using the NetScaler command line
add lb vserver vserver-LB-Pri-1 any 10.102.1.10 *
-lbmethod roundrobin
bind lb vserver vserver-LB-Pri-1 R1
The following procedure describes the steps to add an LB vserver named vserver-
LB-Sec-1 of type ANY. This is set as a directly addressable vserver. The LB
method is set to round robin. The service R2 is bound to this vserver.
To create a secondary router using the configuration utility
appears.
LB-sec-1, and select the Directly Addressable check box.
4. In the IP Address and Port text boxes, type the IP address and port of the
vserver, for example, 10.102.07.78 and *.
example, ANY.
bind to the vserver, for example, R2.
7. Click the Method and Persistence tab. In the drop-down list box under LB
Method, select round robin.
To create a secondary router using the NetScaler command line
add lbserver vserver-LB-Sec-1 any 10.102.07.78 *
-lbmethod roundrobin
bind lb vserver vserver-LB-Sec-1 R2
The following procedure describes the steps to set the vserver called vserver-LB-
Sec-1 as the backup vserver.
To set the secondary router as the backup router using the configuration
utility
2. Select the vserver for which you want to configure the backup vserver, for
example, vserver-LB-Pri-1.
appears.
5. In the Backup Virtual Server drop-down list box, select the backup
vserver, for example, vserver-LB-Sec-1. Click OK.
To set the secondary router as the backup router using the NetScaler
command line
set lb vserver vserver-LB-Pri-1 -backupVserver vserver-LB-Sec-1
The following procedure describes the steps to configure link LB. The vserver
called vserver-LB-Pri-1 is set as the gateway.
appears.
mask that you want to configure, for example, 10.102.29.0 and
255.255.255.0.
4. In the Gateway Name drop-down list box, select the vserver that you want,
for example, vserver-LB-Pri-1.
add lb route 10.102.29.0 255.255.255.0 vserver-LB-Pri-1
Configuring RNAT with Link Load Balancing
This section provides instructions to configure Reverse NAT (RNAT) with link
LB. The following table summarizes the names and values of the entities that
must be configured on the NetScaler.
To configure RNAT with link load balancing, perform the following:
1. Create a transparent monitor
2. Create a service and bind the service to the monitor
3. Create a directly addressable LB vserver and bind the service to the vserver
4. Set persistence and LB method
5. Configure link load balancing
6. Configure RNAT
The following procedure describes the steps to create a monitor named monitor-
HTTP-1 of type HTTP.
Monitor monitor-HTTP-1 NA
LB Service route1 10.102.29.5
LB Vserver vserver-LB-3 NA
To create a transparent monitor using the configuration utility
3. In the Name and Destination IP text boxes, type the name and destination
IP address of the monitor, for example, monitor-HTTP-1 and 10.10.10.11.
4. In the Type drop-down list box, select the type of the monitor, for example,
HTTP.
5. Under Standard Parameters, select the Transparent check box.
To create a transparent monitor using the NetScaler command line
add monitor monitor-HTTP-1 HTTP -destip 10.10.10.11 -transparent
YES
The following procedure describes the steps to create a service named route1 of
type ANY. The monitor called monitor-HTTP-1 is bound to this service.
To create a service and bind the monitor to it using the configuration utility
address, and port of the service, for example, route1, 10.102.29.5, and *.
example, ANY.
5. Under Available, in the Monitors list box, select the monitor that you want
to bind to the service, for example, monitor-HTTP-1.
To create a service and bind the monitor to it using the NetScaler command
line
add service route1 10.102.29.5 ANY *
The following procedure describes the steps to create an LB vserver named
routervip of type ANY. The vserver is set as a directly addressable vserver and
service route1 is bound to it.
To create an LB vserver and bind the service to it using the configuration
utility
appears.
LB-3.
4. Select the Directly Addressable check box.
example, ANY.
bind to the vserver, for example, route1.
To create an LB server and bind the service to it using the NetScaler
command line
bind lb vserver vserver-LB-3 any route1
The following procedure describes the steps to set the LB method of the vserver
called vserver-LB-3 to round robin. Persistence method is set to Destination IP
persistence method.
To set the LB method and persistence using the configuration utility
2. Select the vserver for which you want to configure the LB method and
persistence, for example, vserver-LB-3.
appears.
5. Under Persistence, in the Persistence drop-down list box, select DESTIP.
6. In the PersistMask and Timeout text boxes, type the subnet mask and
timeout values, for example, 225.225.225.225 and 2. Click OK.
To set the LB method and persistence using the NetScaler command line
set lb vserver vserver-LB-3 -persistenceType DESTIP -lbmethod round
robin
The following procedure describes the steps to configure link LB. The LB vserver
called vserver-LB-3 is made the gateway.
appears.
mask that you want to configure, for example, 1.10.10.0 and 255.255.255.0.
4. In the Gateway Name drop-down list box, select the vserver, for example,
vserver-LB-3.
add lbroute 1.10.10.0 255.255.255.0 vserver-LB-3
The following procedure describes the steps to configure RNAT. The NAT IP is
set to a unique NAT IP address.
To configure RNAT using the configuration utility
2. Click the RNAT tab.
3. Select the RNAT network for which you want to configure the NAT IP
address, for example, 10.102.29.0.
4. Click Configure RNAT. The Configure RNAT dialog box appears.
want to configure, for example, 10.102.29.61.
6. Click Add. The NAT IP you selected in Step 5 appears in the Configured
NAT IP (s) list box.
7. Click OK.
To configure RNAT using the NetScaler command line
set rnat 10.102.29.0 -natip 10.102.29.61
The following procedure describes the steps to enable USNIP (Use Subnet IP
Address) mode.
To enable subnet IP mode using the configuration utility
dialog box appears.
3. Select the Use Subnet IP check box.
5. Click Yes.
To enable subnet IP mode using the NetScaler command line
enable ns mode USNIP
Path MTU Behavior
Depending on the installation type and configuration, the NetScaler can have
some limitations in how it handles Path Maximum Transmission Unit Discovery.
Therefore, you may need to make changes to your configuration.
The following procedure describes the steps to enable or disable Path MTU
discovery.
To enable or disable Path MTU discovery using the configuration utility
dialog box appears.
To enable Path MTU Discovery, select the Path MTU Discovery check
box.
To disable Path MTU Discovery, clear the Path MTU Discovery check
box.
5. Click Yes.
To enable or disable Path MTU discovery using the NetScaler command line
enable ns mode pmtud
disable ns mode pmtud
IP Tunneling
An IP Tunnel is a communication channel, that can be created by using
encapsulation technologies, between two networks that do not have a routing
path. Every IP packet that is shared between the two networks is encapsulated
within another packet and then sent via the tunnel.
The NetScaler implements IP Tunneling in the following ways:
NetScaler as an Encapsulator (Load Balancing with DSR mode)
NetScaler as a Decapsulator
NetScaler as an Encapsulator (Load Balancing
with DSR mode)
Consider an organization that has multiple data centers across different countries,
where the NetScaler maybe at one location and the back-end servers are located
in a different country. In essence, the NetScaler and the back-end servers are on
different networks and are connected via a router.
When you configure Direct Server Return (DSR) on this NetScaler, the packet
sent from the source subnet is encapsulated by the NetScaler and sent via a router
and tunnel to the appropriate back-end server. The back-end server decapsulates
the packet and responds directly to the client, without allowing the packet to pass
via the NetScaler. For information on how to configure DSR, refer to the Load
Balancing Chapter.
NetScaler as a Decapsulator
Consider an organization having multiple data centers each having NetScalers
and back-end servers. When a packet is sent from data center A to data center B it
is usually sent via an intermediary, say a router or another NetScaler. The
NetScaler processes the packet and then forwards the packet to the back-end
server.
However, if an encapsulated packet is sent, the NetScaler must be able to
decapsulate the packet before sending it to the back-end servers. To enable the
NetScaler to function as a decapsulator, a tunnel is added between the router and
the NetScaler.
When the encapsulated packet, with additional header information, reaches the
NetScaler, the data packet is decapsulated i.e. the additional header information is
removed, and the packet is then forwarded to the appropriate back-end servers.
The NetScaler can also be used as a decapsulator for the Load Balancing feature,
specifically in scenarios when the number of connections on a vserver exceeds a
threshold value and all the new connections are then diverted to a back-up
vserver. For more information on the spillover option, see Diverting Excess
Traffic to a Backup LB Vserver on page 188.
NetScaler as a decapsulator is illustrated in the diagram specified below.
NS as a Decapsulator
In this section:
Adding an IP Tunnel
Verifying the IP Tunnel Configuration
Removing an IP Tunnel
Customizing the IP Tunnel Globally
Adding an IP Tunnel
This section discusses how to enable IP/IP (IP Tunneling) for a specific virtual IP
(VIP) address. Enabling IP/IP involves adding an IP Tunnel manually, known as
Configured tunnels. A tunnel can also be created automatically by the LB
module, when they configure DSR mode using IP over IP mode of forwarding.
These tunnels are known as internal tunnels.
The following table lists and describes the parameters used for adding a tunnel
manually.
To add an IP Tunnel using the configuration utility
1. In the navigation pane, expand Network, and click IP Tunnels.
2. On the IP Tunnels page, click Add.
3. In the Add IP Tunnel dialog box, in the Name textbox, type the name of
the tunnel (for example, nstnl).
4. In the Remote IP textbox, type a public VIP address owned by the
NetScaler (for example, 192.168.0.0).
5. In the Remote Mask textbox, type the subnet mask of the remote IP
address of the tunnel (for example, 255.255.255.0).
To add an IP Tunnel using the NetScaler command line
add iptunnel Name RemoteIPAddress RemoteSubnetMask LocalIP Address
Example
add iptunnel nstl 192.168.0.0 255.255.255.0 *
Parameter Specifies
Name Name of the IP Tunnel. Mandatory parameter.
Remote IP Address of the entry point of the tunnel. Mandatory parameter.
Remote Mask Subnet mask of the remote IP address of the tunnel. Mandatory
parameter.
Local IP Type Local IP Address of the tunnel. Possible values: Auto, MIP, SNIP,
and VIP. Default: Auto.
Protocol IP Tunneling protocol. Possible values: IPIP. Default: IPIP.
Verifying the IP Tunnel Configuration
You can view all the IP tunnels (user configured and internal) that have been
created. You can also view the following properties of a specific IP Tunnel:
Name, Remote, Protocol, and others. Viewing these details of the configured IP
Tunnel can be helpful when you are troubleshooting any issues in the
configuration.
To view all the IP Tunnels created using the configuration utility
In the navigation pane, expand Network, and click IP Tunnels. On the IP Tunnels
page, all the created IP tunnels are displayed.
To view all the IP Tunnels created using the NetScaler command line
sh iptunnel
To view the IP Tunnel configuration using the configuration utility
2. On the IP Tunnels page, verify that the configured IP tunnel appears, for
example, check if the nstl tunnel appears.
3. Select the configured IP Tunnel, for example, nstl, and in the Details
section, verify that the parameters displayed are as configured.
To view the IP Tunnel using the NetScaler command line
sh iptunnel Name
Example
sh iptunnel nstl
Removing an IP Tunnel
A tunnel is a communication channel created between two appliances. The tunnel
can be removed when either one of the appliances goes down or when you no
longer use that tunnel, irrespective of the type of tunnel.
To remove an IP Tunnel using the configuration utility
2. On the IP Tunnels page, select the name of the IP Tunnel that you want to
remove (for example, nstl), and click Remove.
3. In the Remove pop-up window, click Yes.
To remove an IP Tunnel using the NetScaler command line
rm iptunnel Name
Example
rm iptunnel nstl
Customizing the IP Tunnel Globally
By globally specifying the Source IP address parameter, you can assign a
common source IP address across all tunnels. Fragmentation is CPU-intensive
and so if a packet requires fragmentation, you can globally specify that the
NetScaler must drop the packet. However, if you would like to fragment all
packets as long as a CPU threshold value is not met, you can globally specify the
CPU threshold value.
The following table lists and describes the parameters required for customizing
the IP tunnels globally.
To customize the IP Tunnel using the configuration utility
1. In the navigation pane, click Network.
2. In the Network page, in the IP Tunnels group, click IP Tunnel Global
Settings.
Parameter Specifies
Source IP The common global source IP address for all tunnels.
The global source IP can either be a MIP or a SNIP. You
can also create a new MIP or SNIP address to be used as
the global source IP address.
Drop Packet if Fragmentation is
required
Packet must be dropped if it requires fragmentation.
Possible values: Yes or No. If the value is set to Yes,
packets that require fragmentation are dropped by the
NetScaler. If the value is set to No, packets are not
dropped if they require fragmentation. Default: No.
Dont fragment and drop packet
if CPU usage is >=
Packet must be dropped if the CPU usage is greater or
equal to the user configured value. This parameter is
applicable only if the Drop Packet if Fragmentation is
required parameter is set to No. Possible values: 1 to
100. Default: 0 (Not set). For example, let us assume that
the CPU usage value is 50%. If the CPU usage is not
greater than 50%, all packets are fragmented and not
dropped. If the CPU usage is greater than 50%, all
packets are dropped and not fragmented. If the CPU
usage has not been specified, then all packets are
fragmented and not dropped.
3. In the Configure IP Tunnel Global Parameters dialog box, in the Source
IP textbox, select the global source IP address of the tunnel (for example,
10.102.29.21).
Note: You can also add a new IP address of type SNIP or MIP which can be
used as the default source IP address for all tunnels by clicking New. An updated
Add IP dialog box is displayed to enable you to add a new source IP address.
To enable NetScaler to drop packets if fragmentation is required, select the
Drop packet if fragmentation is required checkbox.
To enable NetScaler to fragment the packets, clear the Drop packet if
fragmentation is required checkbox.
5. To fragment packets until the threshold value for the CPU usage is met,
type a value in the Dont fragment and drop packet if CPU usage is =>
textbox, for instance, 50.
Note: To fragment packets irrespective of the CPU usage, do not specify any
value in the Dont fragment and drop packet if CPU usage is => textbox.
6. Click Ok.
To customize the IP Tunnel using the NetScaler command line
set iptunnelparam srcIP SourceIPAddress dropFrag Value
dropFragCpuThreshold Value
Example
set iptunnelparam -srcIP 12.12.12.22 -dropFrag No
dropFragCpuThreshold 50
IPv6 Support
Internet Protocol version 6 (IPv6) is a suite of protocols and standards. The suite
of protocols include IPv6, ICMPv6, ND6, and related protocols. However, IPv6 is
better known for its enhancements to the Internet Protocol. IPv6 is defined in
RFC 2460. It incorporates several enhancements proposed for updating the IPv4
protocol.
Some of the significant enhancements are:
New Header Format
Large Address Space
Better Routing
Better Address Configuration
Built-in security
Better support for quality of service (QoS)
New protocol for neighboring node interaction
NewHeader Format
The new header format is significantly simpler than the IPv4 header, thus
reducing header overhead. Nonessential fields and option fields are moved to
extension headers that are placed after the IPv6 header. Most importantly, the
IPv4 and IPv6 header formats are not compatible. To allow IPv6- and IPv4-based
NetScaler units to communicate with each other, network applications need to
support Network Address Translation - Protocol Translation (NAT-PT) defined in
RFC 2766.
Large Address Space
IPv6 supports 128-bit source and destination addresses. This implies that 2
128

IPv6 addresses can be configured.
Better Routing
With IPv6, global addresses are designed to improve aggregation efficiency,
resulting in smaller routing tables.
Better Address Configuration
IPv6 supports both stateful and stateless address configuration. Stateful address
configuration allows hosts to use a Dynamic Host Configuration Protocol
(DHCP) server to obtain an IP address. Stateless address configuration allows
hosts to auto-configure link local addresses based on their MAC addresses. Hosts
can also auto-configure global addresses.
Security
The IPv6 protocol suite provides native support for IP Security (IPSec).
Quality of Service (QoS)
The IPv6 includes a new field named Flow Label.To ensure QoS, you can
configure routers to handle traffic with specific Flow Label fields in an
appropriate manner.
Neighbor Discovery
This protocol allows neighboring nodes to interact with each other. The neighbor
discovery protocol replaces the Address Resolution Protocol (ARP), ICMPv4
Router Discovery, and ICMPv4 Redirect messages.
As mentioned earlier, IPv6 is a suite of protocols. The core protocols of IPv6 are:
Internet Protocol version 6 (IPv6)
Internet Control Message Protocol for IPv6 (ICMPv6)
Multicast Listener Discovery (MLD)
Neighbor Discovery (ND6)
Internet Protocol version 6 (IPv6)
Internet Control Message Protocol for IPv6 (ICMPv6)
ICMPv6 is an improvement over ICMPv4 and is described in RFC 2463. IPv6
nodes use ICMPv6 messages to communicate errors and other diagnostic
messages. Messages are identified by their message types, which are integers.
Message types for error messages range from 0 to 127 and 128 to 255 for
informational messages. Some ICMPv6 messages are defined as follows:
ICMPv6 error messages:
1 - Destination Unreachable
2 - Packet Too Big
3 - Time Exceeded
4 - Parameter Problem
ICMPv6 informational messages:
128 - Echo Request
129 - Echo Reply
Multicast Listener Discovery (MLD)
IPv6 routers use MLD to exchange membership status information between
members of multicast groups. MLD is defined in RFC 2710.
Neighbor Discovery (ND6)
Neighbor Discovery (ND6) is a message-based protocol that allows nodes to
advertise their link layer addresses and obtain the addresses of neighboring nodes.
As mentioned earlier, the IPv6 header is simpler than the IPv4 header. The
following figure illustrates the differences.
Comparison of the IPv4 and IPv6 Headers
Understanding IPv6 Addresses
Before configuring IPv6, it is important to understand the addressing scheme.
This section describes the following aspects of IPv6 addresses:
Size
Allocation
Representation
Compressing Zeros
Prefix
Size
IPv6 supports 128-bit source and destination addresses. This implies that 2
128

IPv6 addresses can be configured.
Allocation
Division of the IPv6 address space is based on the value of the high-order bits in
the address. The high-order bits are known as a format prefix (FP). The following
table lists the different types of IPv6 addresses:
Representation
As mentioned earlier, an IPv6 address is 128 bits long. It is represented by 8
hexadecimal numbers separated by colons. Each hexadecimal number is 16 bits
long. This form of representing an IPv6 address is called colon-hexadecimal.
The following example illustrates the derivation of an IPv6 address.
An IPv6 address in binary form:
0010000111011010000000001101001100000000000000000010111100111011
0000001010101010000000001111111111111110001010001001110001011010
The eight 16-bit numbers:
0010000111011010 0000000011010011 0000000000000000
0010111100111011
0000001010101010 0000000011111111 1111111000101000
1001110001011010
The eight 16-bit numbers converted to hexadecimal and delimited with colons:
21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A
Compressing Zeros
Leading zeros within each 16-bit number can be replaced with a single '0' to
simplify an IPv6 address. For example:
21DA:00D3:0000:2F3B:02AA:00FF:FE28:9C5A
becomes
Type Format prefix (FP)
Reserved 0000 0000
Reserved for NSAP
allocation
0000 001
Aggregatable global unicast
addresses
001
Link-local unicast addresses 1111 1110 10
Site-local unicast addresses 1111 1110 11
Multicast addresses 1111 1111
21DA:D3:0:2F3B:2AA:FF:FE28:9C5A.
An IPv6 address can be further simplified by replacing the longest contiguous
sequence of 16-bit blocks, set to 0 with ::. For example:
21DA:00D3:0000:2F3B:02AA:0000:0000:5
becomes
21DA:00D3:0000:2F3B:02AA::5
Prefix
The prefix is used to indicate the network ID in an IPv6 address. It removes the
need for subnet masks. Prefixes are expressed using the forward slash (/) notation
(address/prefix-length.) This is similar to the CIDR notation for IPv4. For
example, 21DA:C1:0:2A35::1235/64 indicates that the first 64 bits of the IPv6
address represent the network ID. Hence, the network ID is 21DA:C1:0:2A35.
Types of IPv6 Addresses
Based on the scope, IPv6 addresses can be classified as:
Unicast
Multicast
Anycast
Unicast
A unicast address, as the name implies, identifies a single interface. Its role is
similar to the IPv4 unicast address. Unicast IPv6 addresses can be classified as:
Node local - This is used within the node. For example, it is used for IPC
inter process communication across multiple line cards.
Link local - These addresses are required for neighbor discovery and are
used by nodes that share a common link. Link local addresses are identified
by the 1111 1110 10 format prefix.
Global - These are publicly routable and reachable addresses and are
equivalent to public IPv4 addresses. They are identified by the format
prefix 001.
Multicast
A multicast address, as the name implies, is used to identify multiple interfaces.
Multicast packets are sent to all members in a multicast group. These addresses
are identified by the 1111 1111 format prefix.
Multicast addresses cannot be used as source addresses.
Anycast
An anycast address is a unique IPv6 address assigned to multiple interfaces.
Packets destined to an anycast address are delivered to the interface nearest in
terms of routing distance.
Neighbor Discovery
Neighbor discovery (ND) is one of the most important features of IPv6. It allows
nodes to advertise their link layer addresses and obtain the addresses of the
neighboring nodes. This process is performed by the Neighbor Discovery
protocol (ND6). It is a message-based protocol. It combines the functionality of
the Address Resolution Protocol (ARP), Internet Control Message Protocol
(ICMP), and Router Discovery.
Neighbor discovery can perform the following functions:
Router Discovery - This function allows a host to discover the local routers
on an attached link and automatically configures a default router.
Prefix Discovery - This function enables the host to discover the network
prefixes for local destinations. Currently, the NetScaler does not support
Prefix Discovery.
Parameter Discovery - This function enables a host to discover additional
operating parameters such as MTU and the default hop limit for outbound
traffic.
Address Autoconfiguration - This function enables hosts to automatically
configure IP addresses for interfaces both with and without stateful address
configuration services such as DHCPv6. The NetScaler does not support
Address Autoconfiguration for Global IPv6 addresses.
Address Resolution - This function is equivalent to ARP in IPv4. It allows a
node to resolve a neighboring node's IPv6 address to its link-layer address.
Neighbor Unreachability Detection - This function allows a node to
determine the reachability state of a neighbor or the state of the route to a
destination.
Duplicate Address Detection - This function allows a node to determine, if
an address is already in use by a neighboring node.
Redirect - This function is equivalent to the IPv4 ICMP Redirect message.
This feature allows a router to redirect the host to a better first-hop IPv6
address to reach a destination. The NetScaler does not support Redirect.
IPv6 on the NetScaler
The NetScaler only supports client-side IPv6. This means that the NetScaler
functions as an IPv6 node with limited functionality. It accepts connections from
IPv6 nodes (both hosts and routers) and performs Protocol Translation (RFC
2765) before sending traffic to the IPv4-based back-end services. The reverse
occurs when IPv4-based services respond to client requests. IPv4 packets are
converted to IPv6 packets before they are sent to the IPv6-based clients. If the
NetScaler is configured with an IPv6 management IP address (NSIP), it responds
to ping, telnet, and ssh.
The NetScaler also performs Protocol Translation. During protocol translation,
the NetScaler converts IPv4 packet headers into IPv6 packet headers and vice
versa. Hence, the back-end details need not be modified. However, due to
Protocol Translation, the performance of the NetScaler can be impacted.
The IPv6 features supported by the NetScaler are:
Neighbor Discovery protocol for NS, NA, and DAD (RFC 2461)
Configuration of IPv6 address for NSIP and select VIPs
Support for management protocols like ping, telnet, and ssh
Basic routing support limited to default static routes
Basic High Availability (HA) support for IPv6-related configuration
changes
RA and RS message handling
Client-IP insertion for IPv6
IPv6 statistics
Port-based VLAN support
ICMPv6 support for ping, PMTU, and error messages
Supported for Gigabit Ethernet, Fast Ethernet, and LACP-based interfaces
The following features are not supported by the NetScaler:
IPv6-based ACL expressions
Routing protocols for IPv6
Non-default static routing
Policies with IPv6 addresses
USIP (Use source IP) and DSR (Direct Server Return) for IPv6
IPv6, IPv4 Fragmentation
Network Address Translation (NAT) and Reverse Network Address
Translation (RNAT) for IPv6
HA with native IPv6 node addresses
Path-MTU discovery for IPv6
IPv6 addresses for MIPs and SNIPs
IPv6 addresses for servers and services
SNMP for IPv6
SSL VPN and GSLB for IPv6
Enabling and Disabling IPv6
IPv6 is a licensed feature. When IPv6 is enabled, the NetScaler processes IPv6
packets.
When IPv6 is disabled, the NetScaler does not process IPv6 packets and displays
the following warning when you run an unsupported command:
"Warning: Feature(s) not enabled [IPv6PT]"
Similarly, the following error appears when you run the IPv6 commands without
the appropriate license:
"ERROR: Feature(s) not licensed"
The following procedure describes the steps to enable and disable IPv6.
To enable and disable IPv6 using the configuration utility
To enable IPv6, select the IPv6 Protocol Translation check box.
To disable IPv6, clear the IPv6 Protocol Translation check box.
5. Click Yes.
To enable or disable IPv6 using the NetScaler command line
enable ns feature ipv6pt
disable ns feature ipv6pt
Adding IPv6 Addresses
You can configure one global IPv6 address at run time. If you create a new global
IPv6 NSIP, the old one is overwritten. The NetScaler is configured with one link
local address that can be modified. Both of these addresses respond to ping,
telnet, and ssh.
You can only configure NSIPs for management access. The NetScaler does not
support MIPs and SNIPs with IPv6 addresses. If default routes are not
configured, packets that do not belong to the NSIP subnet are dropped.
The following table lists and describes the parameters required to add an IPv6
address.
The following procedure describes the steps to add fe80::2c0:95ff:fec5:d9b8 as a
link-local IPv6 address.
To add an IPv6 address using the configuration utility
2. Click the IPV6s tab and click Add. The Create IP6 dialog box appears.
3. In the IPv6 Address text box, type the IPv6 address that you want to
configure, for example, fe80::2c0:95ff:fec5:d9b8.
4. In the Scope drop-down list box, select the scope of the IPv6 address, for
example, link-local.
IPv6Address IPv6 address.
Scope Scope of the IPV6 address. The valid options for this
parameter are global and link-local. The default value is
NS_GLOBAL.
Type Type of IPV6 address. The valid options for this
parameter are NSIP and VIP. The default value is
NS_IPV6_NSIP.
map Mapped IPV4 address for IPV6.
To add an IPv6 address using the NetScaler command line
add nsip6 fe80::2c0:95ff:fec5:d9b8 -scope link-local
The following procedure describes the steps to add an IPv6 address with a
specified prefix length. In this example, the global IPv6 address 2002::50 is
added. The prefix length is set to /64.
To add an IPv6 address with prefix length using the configuration utility
2. Click the IPV6s tab and click Add. The Create IP6 dialog box appears.
3. In the IPv6 Address text box, type the IPv6 address that you want to
configure, for example, 2002::50/64.
4. In the Scope drop-down list box, select the scope of the IPv6 address, for
example, global.
5. In the Type drop-down list box, select the type of the IPv6 address, for
example, NSIP.
To add an IPv6 address with prefix length using the NetScaler command line
add nsip6 2002::50/64 -scope global -type NSIP
The following procedure describes the steps to view the IPv6 addresses
To view a configured IPv6 address using the configuration utility
In the navigation pane, expand Networks and click IPs. The IPs page appears in
the details pane. Click the IPV6s tab. The information for the IPv6 addresses,
State, Scope, Type, and Mapped IP address appears on the IPs page.
To view a configured IPv6 address using the NetScaler command line
show ns ip6
Adding an IPv6 Vserver
You can also configure LB, CS, and CR vservers with IPv6 addresses. The
choices are limited to global addresses. The NetScaler supports only client-side
IPv6; therefore, it performs Protocol Translation (RFC 2765) to manage the IPv6-
based vserver and the IPv4-based services. Vservers with IPv6 addresses respond
to ping requests.
The following procedure describes the steps to add a vserver named VS1 of type
HTTP with global IPv6 address 2002::45.
A vserver named VS2 of type HTTP is created with a link-local IPv6 address
fe80::1. The procedure fails if the IPv6 address of a vserver is not a global
address.
To add an IPv6 vserver using the configuration utility
appears.
3. Select the IPv6 check box.
4. In the Name, Port, and IP Addresses text boxes, type the name, port, and
IP address of the vserver, for example, vserver-LB-6, 80, and 2002::45/64.
example, HTTP.
To add an IPv6 vserver using the NetScaler command line
add lb vserver vserver-LB-6 HTTP 2002::45/64 80
Managing Static Routes
Currently, the NetScaler supports the creation of default static routes. You can
configure a maximum of six default static routes. IPv6 routes are selected based
on whether the MAC address of the destination device is reachable. This can be
determined by using the IPv6 Neighbor Discovery feature. Routes are load
balanced and only source/destination-based hash mechanisms are used.
Therefore, route selection mechanisms, such as round robin, are not supported.
The next hop address in the default route need not belong to the NSIP subnet.
Adding an IPv6 Route
The following procedure describes the steps to add an IPv6 routes and to add an
IPv6 route with VLAN.
To add an IPv6 route with VLAN using the configuration utility
2. Click the IPv6 tab.
3. Click Add. The Create IPv6 Route dialog box appears.
4. In the Network, Gateway IP and VLAN text boxes, type the network,
Gateway IP address, and VLAN for which you want to add a route, for
example,::/0, fe80::1, and 5.
To add a IPv6 route with VLAN using the NetScaler command line
add route6 ::/0 2001::1
Removing an IPv6 Route
The following procedure describes the steps to remove an IPv6 route from the
NetScaler.
To remove an IPv6 route using the configuration utility
2. Click the IPV6 tab.
3. Select the network from which you want to remove the route, for
example,::/0.
5. Click Yes.
To remove an IPv6 route using the NetScaler command line
rm route6 ::/0 2001::1
The following procedure describes the steps to verify the configured IPv6 routes
by viewing them.
To view the IPv6 routes using the configuration utility
2. Click the IPV6 tab. The information for the Network, Gateway IP address,
VLAN, and Flags appears on the Routes page.
To view the IPv6 routes using the NetScaler command line
show route6
Neighbor Discovery
The NetScaler supports Neighbor Discovery (ND) for IPv6. When the state of a
vserver changes from DOWN to UP, the NetScaler sends gratuitous NA or
unsolicited NA messages.
Viewing Discovered Neighbors
The following procedure describes the steps to view discovered neighbors.
To view discovered neighbors using the configuration utility
In the navigation pane, expand Network and click IPv6 Neighbor. The IPv6
Neighbors page appears in the details pane. The information about the
Neighbors, MAC Address, VLAN, Interface, State, and Time parameters are
displayed on the IPv6 Neighbors page.
To view discovered neighbors using the NetScaler command line
show nd6
Removing Neighbor Discovery Entries
The following procedure describes the steps to remove Neighbor Discovery
(ND6) entries from the NetScaler.
To remove neighbor discovery entries using the configuration utility
1. In the navigation pane, expand Network and click IPv6 Neighbor. The
IPv6 Neighbors page appears in the details pane.
2. Click Clear.
To remove neighbor discovery entries using the NetScaler command line
clear nd6
Router Learning
The NetScaler can learn default routers from RA and RS messages. However, the
NetScaler ignores other properties in RA messages, such as prefix list and MTU.
The following procedure describes the steps to enable router advertisement
learning.
To enable router discovery learning using the configuration utility
1. In the navigation pane, click Network. The Network page appears in the
details pane.
2. Click the Router Advertisement Learning link. The Configure RA
Learning dialog box appears.
3. Select the Enable Router Advertisement Learning check box. Click OK.
To enable router discovery learning using the NetScaler command line
set ipv6 -ralearning enabled
Viewing Statistics
The following procedure describes the steps to view IPv6 statistics, such as the
number of IPv6 packets transmitted and received.
To view the IPv6 statistics using the configuration utility
appears in the details pane. Click the IPV6s tab.
2. Select the IPv6 address for which you want to view statistics and click
Statistics. Statistics on the IPv6 packets received, IPv6 packets transmitted,
IPv6 bytes transmitted, IPv6 bytes received, and so on appear on the IPs
page.
To view the IPv6 statistics using the NetScaler command line
stat protocol ipv6 -detail
VLAN Support
If you need to send broadcast or multicast packets without identifying the VLAN
(for example, during DAD for NSIP, or ND6 for the next hop of the route), you
can configure the NetScaler to send the packet on all the interfaces with
appropriate tagging. The VLAN is identified by ND6, and a data packet is sent
only on the VLAN. Port-based VLANs are common for IPv4 and IPv6. Currently,
prefix-based VLANs are not supported for IPv6.
Simple Deployment Scenario
In this section, a simple load balancing set-up consisting of an IPv6 vserver and
IPv4 services is configured, as illustrated in the following topology diagram.
IPv6 sample topology
The following table summarizes the names and values of the entities that must be
configured on the system.
LB Vserver VS1_IPv6 2002::9
Services SVC1 10.102.29.1
SVC2 10.102.29.2
The following figure shows the entities and values of the parameters to be
IPv6 Entity Diagram
To configure the deployment scenario, perform the following:
1. Create an IPv6 service
2. Create an IPv6 LB vserver
3. Bind the services to the vserver
The following procedure describes the steps to add two services SVC1 and SVC2
of type HTTP.
To create IPv6 services using the configuration utility
3. In the Service Name, Server, and Port text boxes type the name, IP
address, and port of the service, for example, SVC1, 10.102.29.1, and 80.
example, HTTP.
6. Repeat Steps 1-5 to create a service SVC2 with IP address 10.102.29.2 and
port 80.
To create IPv6 services using the NetScaler command line
add service SVC1 10.102.29.1 HTTP 80
The following procedure describes the steps to add an IPv6 vserver named
VS1_IPv6 of type HTTP. The IP address is specified as 2002::9.
To create an IPv6 vserver using the configuration utility
appears.
3. Select the IPv6 check box.
4. In the Name, Port, and IP Addresses text boxes, type the name, port, and
IP address of the vserver, for example, VS1_IPv6, 80, and 2002::9.
To create an IPv6 vserver using the NetScaler command line
add lb vserver VS1_IPv6 HTTP 2002::9 80
The following procedure describes the steps to bind the services SVC1 and SVC2
to the vserver VS1_IPv6.
To bind a service to an LB vserver using the configuration utility
SVC1.
bind to the vserver, for example, SVC1. Click OK.
5. Repeat Steps 1-4 to bind the service SVC2 to the vserver, VS1_IPv6.
To bind a service to an LB vserver using the NetScaler command line
bind lb vserver VS1_IPv6 SVC1
The vservers receive IPv6 packets and the NetScaler performs Protocol
Translation (RFC 2765) before sending traffic to the IPv4-based back-end
services.
Host Header Modification
When the HTTP request has an IPv6 address in the host header, and the back-end
server does not understand the IPv6 address, you must change the IPv6 address to
an IPv4 address.
To change the IPv6 address in the host header to an IPv4 address, you need to
map an IPv4 address to it. When the IPv4 address is mapped successfully, it is
used in the host header of the HTTP request and sent to the vserver.
The following procedure describes the steps to map the IPv4 address
200.200.200.200 to the VIP 2002::9. When the IP addresses are mapped
successfully, the IPv4 address is used in the host header.
To change the IPv6 address in the host header to an IPv4 address using the
1. In the navigation pane, expand Networks and click IPs. The IPs page
2. Click the IPV6s tab.
3. Select the IP address for which you want to configure Mapped IP address,
for example, 2002:0:0:0:0:0:0:9.
4. Click Open. The Configure IP6 dialog box appears.
5. In the Mapped IP text box, type the mapped IP address which you want to
configure, for example, 200.200.200.200.
6. Click OK.
To change the IPv6 address in the host header to an IPv4 address using the
set ns ip6 2002::9 -map 200.200.200.200
VIP Insertion
You can configure the NetScaler to insert the Virtual IP Address (VIP) and port
number of a vserver in the HTTP requests that are sent to the back-end servers.
This allows applications running on the server to identify the vserver that sent the
request.
If an IPv6 address is sent to an IPv4-based server, the server may not understand
the IP address in the HTTP header, and may generate an error. To avoid this, you
can map an IPv4 address to the IPv6 VIP. When mapped successfully, the IPv4
address is sent to the server when the VIP insertion is enabled on the vserver.
To insert the VIP and port number of a vserver, perform the following tasks:
1. Configure a mapped IPv6 address
2. Enable VIP insertion
The following procedure describes the steps to map the IPv4 address,
200.200.200.200 to VIP 2002::9 and enable VIP insertion on the vserver. When
the IP addresses are mapped successfully, the IPv4 address is sent as the VIP to
the servers.
To configure mapped IPv6 address using the configuration utility
1. In the navigation pane, expand Networks and click IPs. The IPs page
2. Click the IPV6s tab.
3. Select the IP address for which you want to configure Mapped IP address,
for example, 2002:0:0:0:0:0:0:9.
4. Click Open. The Configure IP6 dialog box appears.
5. In the Mapped IP text box, type the mapped IP address which you want to
configure, for example, 200.200.200.200.
6. Click OK.
To configure mapped IPv6 address using the NetScaler command line
set ns ip6 2002::9 -map 200.200.200.200
In the following procedure, you enable the insertion of the VIP address and port
number in the HTTP requests sent to the servers. The IPv4 VIP 200.200.200.200
and port 80 are inserted in the request with the default header tag of vip-header.
To enable VIP insertion using the configuration utility
2. In the Load Balancing Virtual Servers page, select the vserver that you
want to enable port insertion, for example, select VS1_IPv6.
appears.
5. In the Vserver IP Port Insertion drop-down list box, select VIPADDR.
6. In the Vserver IP Port Insertion text box, type the vip header.
To enable VIP insertion using the NetScaler command line
set lb vserver VS1_IPv6 -insertVserverIPPort ON
CHAPTER 13
URL Rewrite
How URL Rewriting Works
The rewrite feature is a general-purpose utility for modifying HTTP headers and
body text. You can use it to to add HTTP headers to an HTTP request or response,
make modifications to individual HTTP headers, or delete HTTP headers. It also
lets you modify the HTTP body in requests and responses.
When the NetScaler receives a request or sends a response, it checks for rewrite
rules, and if applicable rules exist, it applies them to the request or response
before passing it on to the Web server or client computer.
An Illustration of the rewrite Process
You can use the rewrite feature to perform the following tasks:
Modify the URL of a request.
Insert HTTP headers into requests or responses, and delete HTTP headers
from requests and responses.
Replace any string with any other string.
Locate any HTML or text string and insert any other string before or after
it. (This allows you to add data to specific HTTP headers.).
Delete any string within an HTTP header.
After you set up rewrite rules and policies and bind them to the proper policy
bank, the NetScaler begins to apply the policies. When a users browser sends a
HTTP request to your web server, the NetScaler checks the list of policies
configured on it, and if it finds rewrite policies, it evaluates each policy in order
of priority, starting with the lowest number and proceeding to the highest.
Configuring URL Rewriting
The following sections describe the procedures to configure the rewrite feature
with basic settings.
The following sample procedure describes the steps to insert a new HTTP header
named CLIENT-IP into incoming requests that contain the actual client IP
address from which the request originates.
Enabling URL Rewriting
You can find the rewrite feature under Basic Features on the Citrix NetScaler.
To enable the rewrite feature
1. In the left pane, click System and click Settings. The Settings page appears
in the right pane.
2. Under Modes & Features, click Basic Features. The Configure Basic
3. Click Rewrite and click OK. When the Enable/Disable Feature(s)
message appears, click Yes.
The Rewrite feature is enabled on the NetScaler.
To enable the rewrite feature using the NetScaler command line
enable ns feature REWRITE
Setting the NetScaler Behaviour for Undefined
Events
An undefined event is triggered when the NetScaler cannot identify a matching
policy. When the rewrite policy evaluation results in an undefined event, the
configured undefined action is carried out.
Undefined actions configured at the rewrite policy level are carried out before the
globally configured undefined actions.
Chapter 13 URL Rewrite 663
The NetScaler supports two types of undefined actions: NOREWRITE and
RESET.
NOREWRITE. The NOREWRITE action aborts the rewrite feature
processing and the packet flow is not altered in any way
RESET. If the undefined action is set to RESET, the NetScaler resets the
current client connection.
Note: Undefined events can be triggered for both request and response flow
specific policies.
To set the NetScaler behavior for undefined events
1. In the left pane, click Rewrite. The Rewrite page appears in the right pane.
2. Under Rewrite Overview, click Rewrite Parameters. The Set Rewrite
Params dialog box appears.
3. Under Undefined Action, select NOREWRITE and click OK.
The global undefined action is set to NOREWRITE.
Note: To set the global undefined action to RESET, in Step 3 above, click
RESET.
To set the NetScaler behavior for undefined events using the NetScaler
command line
set rewrite param -undefAction NOREWRITE
Configuring a Rewrite Action
All rewrite tasks are configured on the NetScaler using rewrite actions. These
actions are then associated with rewrite policies that are activated based on
incoming traffic and the configured policy rules. When a rewrite policy is
activated, the correponding rewrite action is carried out.
The following sample procedure describes steps to configure a rewrite action to
insert a new HTTP header CLIENT-IP that contains the IP address of the client
from where the incoming request originates.
To configure a rewrite action
1. In the left pane, expand Rewrite, then click Actions. The Rewrite Actions
2. Click Add. The Create Rewrite Action dialog box appears.
3. In the Name text box, type the name of the rewrite action, for example,
Action-Rewrite-1.
4. Under Type, select the type of rewrite action to be performed, for example,
INSERT_HTTP_HEADER.
5. In the Header Name text box, type the name of the header to be inserted,
for example, CLIENT-IP
6. In the String expression for header value text box, type the value of the
inserted header, for example, CLIENT.IP.SRC
7. Click Create, then click Close. The rewrite action you created now appears
in the Rewrite Actions Page.
To configure a rewrite action using the NetScaler command line
add rewrite action Action-Rewrite-1 INSERT_HTTP_HEADER CLIENT-IP
CLIENT.IP.SRC
Creating a Rewrite Policy
A rewrite policy consists of a rule expression and a rewrite action. The policy
rules can be based on various parameters of the incoming data. For some
incoming data, if a configured rule matches, the corresponding policy triggered
The following sample procedure describes the steps to create a rewrite policy
Policy-Rewrite-1 that inserts the client IP address into every valid HTTP request
using the rewrite action, Action-Rewrite-1 created in the previous section.
To create a rewrite policy
1. In the left pane, expand Rewrite, then click Policies. The Rewrite Policies
2. Click Add. The Create Rewrite Policy dialog box appears as shown in the
figure.
3. In the Name text box, type the name of the rewrite policy, for example,
Policy-Rewrite-1.
4. Under Action, select the action to be associated with the policy, for
example, Action-Rewrite-1.
5. Under Undefined Action, select Global Undefined Action.
Note: If you want to associate a specific undefined action with the policy
being created, then select the undefined action. Otherwise, the global
undefined action will be applied for all UNDEF events.
6. In the list under the Expression text area, select Advanced Free Form and
in the Expression text area, type the rule for which you want the policy to
be applied, for example, HTTP.REQ.IS_VALID
Note: To use the NetScaler policy infrastructure to configure policy
expressions, refer the Policies and Expressions chapter.
7. Click Create, then click Close. The rewrite policy that you configured now
appears in the Rewrite Policies page.
To create a rewrite policy using the NetScaler command line
add rewrite policy Policy-Rewrite-1 HTTP.REQ.IS_VALID Action-
Rewrite-1
Binding Rewrite Policies to a Virtual Server
Rewrite policies that have been configured on the NetScaler are bound to a virtual
server or to any other bind point on the NetScaler.
You can bind rewrite 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.
Note: Rewrite policies cannot be bound to a TCP based virtual server on the
NetScaler.
The following sample procedure describes steps to bind the rewrite policy,
Policy-Rewrite-1, which you created in the previous section, to the load
balancing virtual server Vserver-LB-1.
To bind a rewrite policy to a load balancing vserver
1. In the left pane, expand Load Balancing, then click Virtual Servers. The
rewrite policy to. For example, select Vserver-LB-1, then click Open. The
Configure Virtual Server (Load Balancing) appears as shown in the
figure.
3. Select the Policies tab to display the policies configured on the NetScaler.
4. Select the check box next to Policy-Rewrite-1, then click OK. The rewrite
policy Policy-Rewrite-1 is bound to the virtual server Vserver-LB-1.
To bind a rewrite policy to a load balancing vserver using the NetScaler
command line
bind lb vserver Vserver-LB-1 -policyname Policy-Rewrite-1
You can find configured rewrite actions and policies in the Configuration Utility.
You can open any action or policy to verify settings.
To verify the configuration using the NetScaler command line
At the NetScaler command prompt, type
show rewrite action
or
show rewrite policy
Managing Rewrite Actions
The rewrite actions you created in the earlier section are configured with the basic
settings. There are a few additional parameters you can configure for these
actions.
The following procedures describe the steps to manage the rewrite actions you
have configured on the NetScaler.
Bypassing the Safety Check
Expressions created by the NetScaler from run-time data, for example, URLs
contained in the HTTP requests or responses can cause unexpected errors and are
reported by the NetScaler as unsafe expressions.
When you create a rewrite action, the NetScaler verifies that the expression you
used to create the action is safe. You can manually bypass this option to allow
configuration of unsafe expressions.
To bypass the safety check
2. Select the rewrite action that is allowed to bypass the safety check. For
example, Action-Rewrite-1, then click Open. The Configure Rewrite
Action dialog box appears.
3. Click Bypass Safety Check and click OK. The NetScaler is now
configured to bypass the safety check for the rewrite action Action-
Rewrite-1.
To bypass safety check for a rewrite action using the the NetScaler
command line
set rewrite action Action-Rewrite-1 -bypassSafetyCheck YES
Creating Rewrite Actions
You can use the rewrite feature to perform a variety of HTTP insertions.
However, chunked HTTP responses cannot be modified by the rewrite module. If
you need to use the Rewrite feature to rewrite the message body, you must disable
chunked responses on the web server.
Note: APE HTTP body expressions that only read the HTTP payload will
continue to work even for chunked responses.
The various rewrite actions that can be configured are described in the following
table.
Type of Rewrite Action
INSERT_HTTP_HEADE
R: Inserts the designated
HTTP header into the
designated HTTP request
or response. This is the
default choice.
In the Header Name text
area, type the the name of
the HTTP header you
want to insert.
For example, if you want
to insert the client IP
from which a request is
sent, type Cl i ent - I P
in the text area.
In the String expression for
header value text area, type a
string expression that describes
the contents of the header you
want to insert.
For example, if you want to
insert the Client IP from which
a request is sent, type
CLI ENT. I P. SRC in the text
area.
INSERT_BEFORE:
Inserts a new string before
the designated string in the
HTTP header or body.
In the Expression to
choose target location
text area, type a string
expression that describes
the string before which
you want to insert a new
string.
to find the hostname
www.example.com and
insert a string before the
"example.com" portion,
type the following in the
text area:
HTTP.REQ.HOSTNAM
E.BEFORE_STR
("example.com")
insertion text text area, type a
the new string you want to
insert.
insert the new string "en."
before the string "example" in
the hostname, type "en." in the
text area.
INSERT_AFTER: Inserts
a new string after the
designated string in the
HTTP header or body
choose target location
the string after which you
want to insert a new
string.
to find the hostname
www.example.com, and
insert a string after the
"www." portion, type the
following in the text area:
HTTP.REQ.HOSTNAM
E.AFTER_STR
("www.")
insertion text text area, type a
the new string you want to
insert.
insert the new string "en." after
the string "www." in the
hostname, type "en." in the text
area.
REPLACE: Replaces the
designated string in the
HTTP header or body with
a different string
choose target text
reference text area, type
a string expression that
describes the string you
want to replace with a
new string.
to replace the entire
hostname in the Host
header, type
HTTP.REQ.HOSTNAM
E.SERVER in the text
area.
replacement text text area,
type a string expression that
describes the new string you
want to insert.
replace the current host header
with the string
"web01.example.net type
"web01.example.net" in the
text area.
DELETE: Deletes the
designated string from the
HTTP header or body.
choose target text
reference to be deleted
the string you want to
delete.
to find and delete the
string ".en" in the
hostname of HTTP
response headers, type
the following in the text
area:
HTTP.RES.HEADER("
Host") .SUBSTR("en.")
DELETE_HTTP_HEAD
ER: Deletes the designated
HTTP header, including all
header contents.
In theHeader Name text
area, type the name of the
HTTP header you want
to delete.
to delete the cache-
control header from
HTTP responses, type
HTTP.RES.HEADER
("Cache-Control") in the
text area.
REPLACE_HTTP_RES:
Replace the http response
with the value specified in
the target field.
In the String expression
for replacement text
area, type a string
the string you want to
replace the HTTP
response with.
For example, you can
replace the entire HTTP
response with the
warning HTTP 200
OK You are not
authorized to
view this page by
typing it in the "String
expression for
replacement text" box.
REPLACE_ALL: Will
replace all occurrences of a
pattern in the target text
reference with the value
specified in the string
builder expression
choose target text
references text area, type
the part of either the
HTTP request or
response where you want
to carry out the
replacement.
want to insert
In the Pattern text area, type a
string pattern that you want to
replace.
DELETE_ALL: Delete
every occurrence of the
pattern specified in the
target text reference.
choose target text
HTTP request or
the deletion to occur.
string pattern after which the
insertion should occur.
INSERT_AFTER_ALL:
Will insert the value
specified by string builder
expression after each
occurrence of a specified
reference.
choose target text
HTTP request or
want to insert
string pattern after which the
insertion should occur
INSERT_BEFORE_ALL
: Will insert the value
specified by string builder
expression before each
occurrence of a specified
reference.
choose target text
HTTP request or
want to insert
string pattern before which the
insertion should occur
Modifying an Existing Rewrite Action
After you configure a rewrite action, you can modify its Target expression and
the Bypass Safety Check option.
You can modify a rewrite action only if the concerned rewrite policy is not bound
to any bind point on the NetScaler. If the concerned rewrite policy is bound to any
bind point then you need to unbind the policy before you modify the action.
To modify an existing rewrite action
2. Select the rewrite action you want to modify, for example, Action-
Rewrite-1, then click Open. The Configure Rewrite Action dialog box
appears.
3. Modify the Target Expression or the state of the Bypass Safety Check
option and click OK. The modified rewrite action Action-Rewrite-1 now
appears in the Rewrite Actions page.
To modify an existing rewrite action using the NetScaler command line
set rewrite action Action-Rewrite-1 -target CLIENT-IP -
stringBuilderExpr CLIENT.IP.DST -bypassSafetyCheck YES
Removing an Existing Rewrite Action
You can remove rewrite actions that are not associated with any policies on the
NetScaler. If a configured rewrite action is bound to a rewrite policy, then you
have to unbind the action first before removing it.
To remove a configured rewrite action
2. Select the rewrite action you want to remove, for example, select Action-
Rewrite-1, then click Remove. The Remove dialog box appears.
3. Click Yes to confirm. The rewrite action, Action-Rewrite-1 is removed
from the NetScaler.
To remove a configured rewrite action using the NetScaler command line
rm rewrite action Action-Rewrite-1
Note: Removal fails if the rewrite action is used by any policy configured on
the NetScaler.
Managing Rewrite Policies
The procedures in this section describe the steps to manage any rewrite policies
you have configured on the NetScaler.
Setting the Undefined Action
The undefined action is the action to be carried out in case of an undefined event.
For more detailed control, you can set the undefined action on a per-policy basis.
Any undefined actions that you set at the policy level take precedence over the
global undefined action.
To set the undefined action for a configured policy,
1. In the left pane, expand Rewrite and click Policies. The Rewrite Policies
2. Select the rewrite policy you want to modify, for example, Policy-Rewrite-
1, and click Open. The Configure Rewrite Policy dialog box appears.
3. Under Undefined Action, select the undefined action to be configured, for
example, NOREWRITE.
4. Click OK. The undefined action, NOREWRITE is associated with the
rewrite policy, Policy-Rewrite-1.
Note: To set the undefined action to RESET, in Step 3 above, click RESET.
To set the undefined action for a configured policy using the NetScaler
command line
set rewrite policy Policy-Rewrite-1 -undefAction NOREWRITE
Removing an Existing Rewrite Policy
You can remove rewrite policies that are not bound globally, or to a virtual server
or a custom bind point.
To remove a configured rewrite policy
1. In the left pane, expand Rewrite and click Policies. The Rewrite Policies
2. Select the rewrite policy you want to remove, for example, Policy-
Rewrite-1, and click Remove. The Remove dialog box appears.
3. Click Yes to confirm. The rewrite policy Policy-Rewrite-1 is removed
from the NetScaler.
Note: If the policy is bound to any bind point on the NetScaler, the removal
fails. To remove these polcies, first unbind them from the bind point.
To remove a configured rewrite policy using the NetScaler command line
rm rewrite policy Policy-Rewrite-1
Configuring the Rewrite Feature for Commonly Used
The examples in this section demonstrate how to configure rewrite to perform
varioius useful tasks. The examples occur in the server room of Example
Manufacturing, Inc., a mid-sized manufacturing company that uses its Web site to
manage a considerable portion of its sales, deliveries, and customer support.
Example Manufacturing has two domains: example.com for its Web site and
email to customers, and example.net for its intranet. Customers use the Example
Web site to place orders, request quotes, research products, and contact customer
service and technical support.
As an important part of Example's revenue stream, the Web site must respond
quickly and keep customer data confidential. Example, Inc. therefore has several
web servers and uses a Citrix NetScaler Application Switch to balance the site
load and manage traffic to and from its servers.
The Example system administrators use the rewrite features described in the
previous sections to perform the following tasks:
Insert the client IP address as an HTTP header. Example, Inc. uses Web
log analysis software to track hits on its Web site. By placing the actual
client IP address in an HTTP header, it saves that IP address in the Web
server logs and makes it available to the Web log analysis program.
Delete old X-Forwarded-For headers. Example, Inc. removes old X-
Forwarded-For HTTP headers from incoming requests.
Tag SSL and non-SSL connections. Example, Inc. tags incoming requests
with a header that indicates if the connection is a secure connection.
Mask the HTTP server type. Example, Inc. modifies the HTTP Server:
header so that unauthorized users and malicious code cannot use that
header to determine the HTTP server software it uses.
Redirect external URL to internal URL. Example, Inc. hides information
about the actual names of its web servers and the configuration of its server
room from users, to make URLs on its Web site shorter and easier to
remember, and to improve security on its site.
Migrate Apache rewrite module rules. Example, Inc. moved its Apache
rewrite rules to the Application Switch, translating the Apache PERL-based
script syntax to the NetScalers rewrite rule syntax.
Redirect marketing keyword requests. The marketing department at
Example, Inc. sets up simplified URLs for certain predefined keyword
searches on the companys Web site.
Redirect an old home page. Example, Inc. recently acquired a smaller
competitor, and it now redirects requests for the acquired companys home
page to a page on its own Web site.
Redirect queries to the queried server. Example, Inc. redirects certain
query requests to the appropriate server.
Each of the example scenarios described below requires that the system
administrators create rewrite actions and policies and bind them to a valid bind
point on the NetScaler. These procedures use the values described in the previous
table to create the desired rewrite actions and policies.
Example 1: Inserting the Client IP Address as an
HTTP Header
Example, Inc., uses a Web statistics package to track usage of its Web site. This
package requires that the original client IP address be present in the Web server
logs so that it can accurately track the sources of incoming requests. The
NetScaler load balances between several mirrored Web servers, the NetScaler IP
address rather than the actual client IP address is shown as the request source in
the Web server logs.
Example wants to include the actual client IP address in the logs so that the Web
statistics package can continue to generate information about the sources of
requests to its Web site.
You can create a rewrite action and policy with the values used in the table below.
After creating the policy, bind it, assign it a priority of one to make sure that this
policy is executed on all incoming requests and cannot be skipped over by other
policies. Configure the Goto Priority Expression to NEXT to tell the Application
Switch to proceed to the next policy on the priority list after evaluating and
applying the present policy.
Note: For information on using the NetScaler policy infrastructure to bind
policy expressions on the NetScaler, refer to the Policies and Expressions
chapter.
A new HTTP header, Client-IP, containing the actual client IP address is added to
all incoming requests.
Example 2: Delete Old X-Forwarded-For Headers
Example, Inc. wants to remove old X-Forwarded-For HTTP headers from
incoming requests, so that the only X-Forwarded-For headers that appear are the
ones added by the local server..
In order to remove these old headers, create a rewrite action and a rewrite policy
using the values used in the following table.
Then bind the rewrite policy globally, assigning it a priority of 100 and a setting
the Goto Priority Expression to NEXT.
Action Name Type of Rewrite
Action
Header Name Value
Action-Rewrite-
ClientIP_Insert
INSERT_HTTP_HE
ADER
CLIENT-IP CLIENT.IP.SRC
Policy Name Action Name Undefined Action Expression
Policy-Rewrite-
ClientIP_Insert
Action-Rewrite-
ClientIP_Insert
NOREWRITE HTTP.REQ.IS_VALID
Action Name Type of Rewrite Action Header Name
Action-Rewrite-
Header_Delete
DELETE_HTTP_HEADER X-FORWARDED-FOR
Policy-Rewrite-
Header_Delete
Action-Rewrite-
Header_Delete
chapter.
All old X-Forwarded-For HTTP headers are now deleted from incoming
requests.
Example 3: Tagging Secure and Unsecure
Connections
Example, Inc. wants to tag incoming requests with a header that indicates
whether or not the connection is a secure connection. This helps the server keep
track of secure connections after the Application Switch has decrypted the
connections.
To do this, create rewrite actions using the values used in the following table.
These actions label connections to port 80 as unsecure connections, and
connections to port 443 as secure connections.
Next, create a rewrite policy using the values used in the following table. These
policies check incoming requests to determine which are directed to port 80 and
which are directed to port 443. The policies then add the correct SSL header.
Action
Header Name Value
Action-Rewrite-
SSL_YES
INSERT_HTTP_HE
ADER
SSL YES
Action
Header Name Value
Action-Rewrite-
SSL_NO
INSERT_HTTP_HE
ADER
SSL NO
Policy-Rewrite-
SSL_YES
Action-Rewrite-
SSL_YES
NOREWRITE CLIENT.TCP.DSTPOR
T.EQ(443)
Policy-Rewrite-
SSL_NO
Action-Rewrite-
SSL_NO
NOREWRITE CLIENT.TCP.DSTPOR
T.EQ(80)
Finally, bind the rewrite policies to the NetScaler, assigning the first policy a
priority of 200, and the second a priority of 300, and setting the Goto Priority
Expression of both policies to END.
chapter.
Each incoming connection to port 80 now has an SSL:NO HTTP header added to
it and each incoming connection to port 443 has an SSL:YES HTTP header added
to it.
Example 4: Mask the HTTP Server Type
Example, Inc. wants to modify the HTTP Server: header so that unauthorized
users and malicious code cannot use the header to determine the software that the
HTTP server uses.
To modify the HTTP Server: header, create a rewrite action and a rewrite policy
using the values in the following table.
Finally, bind the rewrite policy to the NetScaler, assigning a priority of 100 and
setting the Goto Priority Expression of the policy to END.
chapter.
The HTTP Server: header is now modified to read Web Server 1.0, masking the
actual HTTP server software used by the Example, Inc. Web site.
Action
Expression to
choose target
reference
String expression for
replacement text
Action-Rewrite-
Server_Mask
REPLACE HTTP.RES.HEA
DER("Server")
"Web Server 1.0"
Policy-Rewrite-
Server_Mask
Action-Rewrite-
Server_Mask
NOREWRITE HTTP.RES.IS_VALID
Example 5: Redirect an External URL to an
Internal URL
Example, Inc. wants to hide its actual server room configuration from users to
improve security on its Web servers.
To do this, create a rewrite action using the values as shown in the following
table. For the request headers, the action in the table modifies www.example.com
to web.hq.example.net. For the response headers, the action does the opposite
it modifies web.hq.example.net to www.example.com.
Next, create rewrite policies using the values shown in the following table.
The first policy checks incoming requests to see if they are valid, and if they are,
it performs the Action-Rewrite-Request_Server_Replace action. The second
policy checks responses to see if they originate at the server
web.hq.example.net, and if they do, it performs the Action-Rewrite-
Response_Server_Replace action.
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Request_Server_Repl
ace
REPLACE HTTP.REQ.HOS
TNAME.SERVE
R
"web.hq.example.net"
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Response_Server_R
eplace
REPLACE HTTP.RES.HEA
DER("Server")
"www.example.com"
Policy-Rewrite-
Request_Server_R
eplace
Action-Rewrite-
Request_Server_R
eplace
NOREWRITE HTTP.REQ.HOSTNA
ME.SERVER.EQ("ww
w.example.com")
Policy-Rewrite-
Response_Server_
Replace
Action-Rewrite-
Response_Server_
Replace
NOREWRITE HTTP.RES.HEADER("
Server").EQ("web.hq.ex
ample.net")
Finally, bind the rewrite policies, assigning each a priority of 500 because they
are in different policy banks so the priorities do not conflict. The system
administrator sets the Goto Priority Expression to NEXT for both bindings.
All instances of www.example.com in the request headers are now changed to
web.hq.example.net, and all instances of web.hq.example.net in response
headers are now changed to www.example.com.
chapter.
Example 6: Migrating Apache Rewrite Module
Rules
Example, Inc., is currently using the Apache rewrite module to process search
requests sent to its web servers and redirect those requests to the appropriate
server, based on information in the request URL. Example, Inc. wants to simplify
its setup by migrating these rules onto the NetScaler.
Two of the Apache rewrite rules that Example currently uses are shown below.
The first rule redirects search requests to a special results page if do not have a
SiteID string, or if they have a SiteID string equal to zero (0). The second
rule redirects all other search requests to the standard results page.
The following are the Apache rewrite rules used:
RewriteCond %{REQUEST_FILENAME} ^/search$ [NC]
RewriteCond %{QUERY_STRING} !SiteId=[OR]
RewriteCond %{QUERY_STRING} SiteId=0
RewriteCond %{QUERY_STRING} CallName=DisplayResults [NC]
RewriteRule ^.*$ /results2.html [P,L]
RewriteCond %{REQUEST_FILENAME} ^/search$ [NC]
RewriteCond %{QUERY_STRING} CallName=DisplayResults [NC]
RewriteRule ^.*$ /results.html [P,L]
To implement this rule on the NetScaler, create rewrite actions using the values in
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Display_Results_Nul
SiteID
REPLACE HTTP.REQ.URL "/results2.html"
Next, create rewrite policies with the values as shown in the table below.
Finally, bind the rewrite policies, assigning the first a priority of 600 and the
second a priority of 700. Then, set the Goto Priority Expression to NEXT for both
bindings.
The NetScaler now handles these search requests exactly as the Web server did
before the Apache rewrite module rules were migrated.
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Display_Results
REPLACE HTTP.REQ.URL "/results.html"
Policy-Rewrite-
Display_Results_N
ulSiteID
Action-Rewrite-
Display_Results_N
ulSiteID
NOREWRITE HTTP.REQ.URL.PATH
.SET_TEXT_MODE(I
GNORECASE).EQ("/
search") &&
(HTTP.REQ.URL.QUE
RY.CONTAINS("!SiteI
d=") ||
HTTP.REQ.URL.QUE
RY.CONTAINS("SiteId
=0") ||
HTTP.REQ.URL.QUE
RY.SET_TEXT_MOD
E(IGNORECASE).CO
NTAINS("CallName=D
isplayResults"))
Policy-Rewrite-
Display_Results
Action-Rewrite-
Display_Results
NOREWRITE HTTP.REQ.URL.PATH
.SET_TEXT_MODE(I
GNORECASE).EQ("/
search") ||
HTTP.REQ.URL.QUE
RY.SET_TEXT_MOD
E(IGNORECASE).CO
NTAINS("CallName=D
isplayResults"))
Example 7: Marketing Keyword Redirection
The marketing department at Example, Inc. wants to set up simplified URLs for
certain predefined keyword searches on the companys Web site. For these
keywords, it wants to redefihne the URL as shown below.
External URL: http://www.example.com/<marketingkeyword>
Internal URL: http://www.example.com/go/
kwsearch.asp?keyword=<marketingkeyword>
To set up redirection for marketing keywords, create a rewrite action usin the
values in the following table.
Next, create a rewrite policy with the values in the table below:
Finally, bind the rewrite policy, assigning it a priority of 800. Unlike the previous
rewrite policies, this policy should be the last to be applied to a request that
matches its criteria. For this reason, the NetScaler administrator sets its Goto
Priority Expression to END.
Any request using a marketing keyword is redirected to the keyword search CGI
page whereupon a search is performed and all remaining policies are skipped.
Example 8: Redirect Queries to the Queried
Server
Example, Inc. wants to redirect query requests to the appropriate server, as shown
here.
Request: GET /query.cgi?server=5
HOST: www.example.com
Redirect URL: http://web-5.example.com/
Action
Expression to
choose target
location
replacement text
Action-Rewrite-
Modify_URL
INSERT_BEFORE HTTP.REQ.URL.
PATH.GET(1)
""go/
kwsearch.aspkeyword
="l"
Policy-Rewrite-
Modify_URL
Action-Rewrite-
Modify_URL
ME.SERVER.EQ("ww
w.example.com")
Create a rewrite action using values from the following table:
Then, create a rewrite policy using the values in the following table:.
Finally, bind the rewrite policy, assigning it a priority of 900. Because this policy
should be the last policy applied to a request that matches its criteria, the
NetScaler administrator sets its Goto Prority Expression to END.
Incoming requests to any URL that begins with http://www.example.com/
query.cgi?server=are redirected to the server number in the query.
Example 9: Home Page Redirection
New Company, Inc. recently acquired a smaller competitor, Purchased Company,
and wants to redirect the home page for Purchased Company to a new page on its
own Web site, as shown here.
Old URL: http://www.purchasedcompany.com/*
New URL: http://www.newcompany.com/products/page.htm
To redirect requests to the Purchased Company home page, create rewrite actions
using the values in the following table.
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Replace_Hostheader
REPLACE HTTP.REQ.HEA
DER("Host").BE
FORE_STR(".ex
ample.com")
"server-" +
HTTP.REQ.URL.QU
ERY.VALUE("web")
Policy-Rewrite-
Replace_Hosthead
er
Action-Rewrite-
Replace_Hosthead
er
NOREWRITE HTTP.REQ.HEADER("
Host").EQ("www.exam
ple.com")
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Replace_URLr
REPLACE HTTP.REQ.URL.
PATH_AND_QU
ERY
"/products/page.htm"
Next, create rewrite policies using the values in the following tables..
Finally, bind the rewrite policies globally, assigning the first a priority of 100, the
second a priority of 200, and the third a priority of 300. As with the previous
rewrite policy, these policies should be the last policies applied to a request that
matches the criteria. For this reason, set the Goto Priority Expression to END for
the first and third policies, and a Goto Priority Expression of 300 to the second
policy. This ensures that all remaining requests are processed correctly.
Requests to the acquired company's old Web site are now redirected to the
configured location of the New Company, Inc. home page.
Action
Expression to
choose target
reference
replacement text
Action-Rewrite-
Replace_Host
REPLACE HTTP.REQ.HOS
TNAME
"www.newcompany.c
om"
Policy-Rewrite-
Replace-None
NOREWRITE !HTTP.REQ.HOSTNA
ME.SERVER.EQ("ww
w.purchasedcompany.co
m")
Policy-Rewrite-
Replace-Host
Action-Rewrite-
Replace_Host
ME.SERVER.EQ("ww
w.purchasedcompany.co
m")
Policy-Rewrite-
Replace-URL
Action-Rewrite-
Replace_URL
CHAPTER 14
HTML Injection
Overview
This chapter describes the HTML Injection functionality of the Citrix NetScaler
Application Switch. It explains what HTML Injection is and how to configure it.
It addresses both basic and advanced configuration procedures.
How HTML Injection Works
Configuring HTML Injection for Inserting Data Into the HTTP Header
Configuring HTML Injection for Inserting Data Into the HTTP Body
Configuring HTML Injection for Commonly Used Applications
How HTML Injection Works
HTML Injection is a form of content rewriting which allows the NetScaler to
insert text or scripts into an HTTP response served from the NetScaler to a client.
You can configure the NetScaler to choose responses to modify based on policies
you create. The policies can be based on request parameters, response parameters
or both.
A request/response pair constitutes a transaction. When a transaction matches the
criteria in a policy, the injection content is injected into the outgoing response.
Certain applications (such as Citrix EdgeSight for NetScaler) use injected data to
measure application performance.
The following figure illustrates how HTML Injection is used to insert data
Functional Overviewof HTML Injection
Configuring HTML Injection to Insert Data in the HTTP
Header
To configure HTML Injection to insert data in the HTTP header, set the
parameters as described in the sections that follow.
The following sample procedure describes the steps to insert a unique transaction
ID into every HTTP response. Injection is configured so that the transaction ID
persists across reboots and system upgrades.
Enabling the HTML Injection Feature
HTML injection is a licensed feature, thus you will only be able to configure the
feature if the requisite license is present on your NetScaler. The following
discussion assumes that you have the requisite licenses installed.
Note: Contact your Citrix customer service center to obtain licenses for the
HTML Injection feature.
The HTML Injection feature is located under Advanced Features on the Citrix
NetScaler.
To enable the HTML Injection feature,
Chapter 14 HTML Injection 687
2. Under Modes & Features, click Advanced Features. The Configure
Advanced Features dialog box appears.
3. Choose HTML Injection and click OK. Click Yes on the Enable/Disable
Feature(s)? confirmation message that appears.
The HTML Injection feature is enabled on the NetScaler.
To enable the HTML Injection feature using the NetScaler command line
enable ns feature htmlinjection
Injecting Data into the HTTP Header
In this example, we will create a filter action to insert the NetScaler variable
%%HTTP. XI D%%into a custom HTTP header X- HTTP- REQ- I D. The variable
assigns a unique ID to each transaction. We will then use the filter action to create
a filter policy that inserts the ID into the response header for every transaction.
Next, we will bind the policy to a load balancing virtual server, Vserver-LB-1, on
the NetScaler.
After creating the filter action, you can use an external server to extract the value
of the custom HTTP header and track the unique transaction ID of each HTTP
response.
Creating Filter Actions
To create filter actions, use the parameters listed in the following table.
Action Name The name of the filter action. This is a mandatory
Qualifier Select the type of filter action being performed. The
following filter actions can be configured
Reset
Add
Corrupt
Forward
ErrorCode
Drop
The following sample procedure describes the steps to create a filter action,
Action-Filter-1 to insert the system variable %%HTTP. XI D%%into the custom
HTTP header X- HTTP- REQ- I D.
To add a filter action
1. In the left pane, expand Protection Features, then click Filter. The Filter
2. Click the Actions tab.
3. Click Add. The Create Filter Action dialog box appears.
4. In the Action Name text box, type the name of the Filter Action, for
example, Action-Filter-1
5. Under Qualifier, choose the type of qualifier, for example, Add
6. In the HTTP Header text box, name of the custom header, followed by a
colon, then the system variable that will insert text in the HTTP header. For
example X- HTTP- REQ- I D: %%HTTP. XI D%%
7. Click Create, then click Close. The filter action Action-Filter-1 that you
created now appears in the Filter Actions page.
To add the filter action using the NetScaler command line
add filter action Action-Filter-1 add X-HTTP-REQ-ID:%%HTTP.XID%%
Value Specify the value to be inserted. This parameter is
active only when you select the Add qualifier. If the
value parameter is not set, then the contents of the
HTTP Header text box are inserted. The following
values can be configured
Prebody - Inserts the contents of the
configured prebody file into the HTTP
response
Postbody - Inserts the contents of the
configured postbody file into the HTTP
response
HTTP Header The data to be inserted into the HTTP header. This field
is active only if neither prebody nor postbody injection
is configured.
Creating Filter Policies
To create filter policies, use the parameters listed in the following table.
The following sample procedure describes the steps to use the filter action,
Action-Filter-1, created in the previous section, to create the filter policy Policy-
Filter-1, which inserts the system variable into every successful HTTP response
To add a Filter Policy
2. Click Add. The Create Filter Policy dialog box appears.
3. In the Filter Name text box, type the name of the Filter Policy, for
example, Policy-Filter-1
4. Click Response Action and in the Response Action list, choose the filter
action, Action-Filter-1, to be associated with this policy.
Note: To insert data into the HTTP request header, in step 4, choose Request
Action.
5. Under General Named Expressions, choose the built-in general
expression ns_true, then click Add Expression. The expression ns_true
now appears in the Expression text box.
Note: The ns_true general expression applies the policy to all successful
responses (200 OK) 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.
Filter Namer The name of the filter policy. This is a mandatory
Request Action The name of the action to be performed on an HTTP
request. The string value can be a configured filter
action or one of the built-in actions
Response Action The action to be performed on an HTTP response. The
string value can be a configured filter action or one of
the built-in actions
6. Click OK, then click Close. The filter policy that you created, Policy-
Filter-1, now appears in the Filter Policies page.
To add a filter policy using the NetScaler command line
add filter policy Policy-Filter-1 -rule ns_true -resAction Action-
Filter-1
Binding Filter Policies
The following sample procedure describes the steps to bind the filter policy,
Policy-Filter-1 configured in the previous section, to the load balancing virtual
server, Vserver-LB-1.
To bind a filter policy to a load balancing vserver
2. From the list of virtual servers, select the virtual server to which you want
to bind the filter policy. For example, choose Vserver-LB-1, then click
appears.
3. Select the Policies tab to view the policies configured on the NetScaler.
4. Select the check box next to Policy-Filter-1
5. Click OK and then click Close.The filter policy Policy-Filter-1 is bound to
the virtual server Vserver-LB-1.
To bind a filter policy to a load balancing vserver usingthe NetScaler
command line
bind lb vserver Vserver-LB-1 -policyname Policy-Filter-1
Note: You can bind filter policies to virtual servers, or to bind points on the
NetScaler, and also globally. For more information on binding filter policies, refer
to the "Policies and Expressions" chapter.
Verify that the HTML Injection feature is accurately configured to insert the
required data into the HTTP response header.
Viewing the Configured Filter Actions
In this section, you will verify that the filter action Action-Filter-1 is accurately
To view configured filter actions
2. Click the Actions tab.The Filter Actions page appears.
3. Verify that the filter action Action-Filter-1 is displayed.
4. Select the filter policy Action-Filter-1 and in the Details section, verify the
qualifier and the value.
To view configured filter actions using the NetScaler command line
show filter action
To view details about the filter action Action-Filter-1, type
show filter action Action-Filter-1
Viewing the Configured Filter Policies
We will verify that the filter policy Policy-Filter-1 is configured accurately on the
NetScaler.
To view configured filter policies
2. Verify that the filter policy Policy-Filter-1 is displayed.
3. Select the filter policy Policy-Filter-1, and in the Details section, verify
that the rule ns_true is configured.
To view configured policies actions using the NetScaler command line
show filter policy
To view details about the filter policy Policy-Filter-1, type
show filter policy Policy-Filter-1
Viewing the Properties of the Virtual Server
We will verify that the filter policy binding is accurate.
To verify that the filter polices are bound to the load balancing vserver
to bind the filter policy for example, Vserver-LB-1. Click Open. The
Configure Virtual Server (Load Balancing) appears.
4. Verify that the check box corresponding to the filter policy to be bound to
the virtual server is selected.
To verify that the filter polices are bound to the load balancing vserver using
Configuring HTML Injection to Insert Data into the HTTP
Body
In this section, you will create a prebody file, pr ebody. j s, and a postbody file,
post body. j s, and use them to insert data into the body of all HTTP responses
through the NetScaler.
Internal Variables used for HTML Injection
The HTML Injection feature provides a pre-defined set of internal variables that
are dynamically replaced with actual NetScaler values during run time. This is
useful for measuring performance, since you can use these variables to track
NetScaler values at different points in time.
The table below lists all of the internal variables that can be referenced during
HTML injection.
Name Type JavaScript
Type
Comment
SYS.IID 128 bit GUID
structure
Windows
format GUID
This is a GUID that uniquely
identifies each Netscaler. The
value of this variable remains
constant across reboots. It is valid
in both prebody and postbody.
HTTP.XID 128 bit GUID
structure
Windows
format GUID
This is a GUID that uniquely
identifies each HTTP transaction
(request/response). This variable
is guaranteed to be unique even if
the Netscaler is rebooted. It is
valid in both the prebody and
postbody.
SYS.UPTIME 32 bit integer 10 digit
number
Gives the time in seconds, offset
to UTC, that the Netscaler has
been up. It is valid in both
prebody and postbody.
HTTP.REQ.RECEIV
E_TIME_BEG
64 bit integer 20 digit
number
Gives the time, in microseconds,
when Netscaler received the first
byte of a client request. It is valid
in both prebody and postbody.
HTTP.REQ.RECEIV
E_TIME_END
number
when Netscaler received the last
byte of a client request. It is valid
in both the prebody and postbody.
HTTP.REQ.SEND_T
IME_BEG
number
when Netscaler forwarded the
first byte of a request to the
backend server. It is valid in both
HTTP.REQ.SEND_T
IME_END
number
when Netscaler forwarded the last
byte of a request to the backend
server. It is valid in both prebody
and postbody.
HTTP.RES.RECEIV
E_TIME_BEG
number
when Netscaler received the first
byte of a response from the
backend server. It is valid in both
HTTP.RES.RECEIV
E_TIME_END
number
when Netscaler received the last
byte of a response from the
backend server. It is valid only in
postbody.
Configuring Prebody Files
Content injected before the response body is called the prebody content. To
insert content into the response prebody, you need to create a separate prebody
file on the NetScaler with the content you want injected.
By default, prebody files are stored in the / nsconf i g/ ht ml i nj ect i on
directory on the NetScaler. However, you can store them in any other location
you prefer.
Note: The prebody file name can have a maximum of 64 characters and can
have any extension.
The following is a sample prebody file to be used for prebody insertion.
Sample prebody file: /nsconfig/htmlinjection/
prebody.js
<! - - Thi s i s a sampl e pr ebody f i l e - - >
<scr i pt l anguage=" J avaScr i pt " >
/ / I nt er nal var i abl es ar e del i mi t ed by t he per cent char act er s
/ * The f ol l owi ng t wo var i abl es must be quot ed.
* Ot her wi se br owser may gi ve a J avaScr i pt er r or .
*/
/ / Syst emI I D
var sys_i i d=" %%SYS. I I D%%" ;
/ / HTTP t r ansact i on I D
var ht t p_xi d=" %%HTTP. XI D%%" ;
/ * Fol l owi ng t i mest amp var i abl es wi l l al ways be val i d
HTTP.RES.SEND_TI
ME_BEG
number
when Netscaler forwarded the
first byte of response to the client.
It is valid in both prebody and
postbody.
HTTP.RES.SEND_TI
ME_END
number
when Netscaler forwarded the last
byte of a response to the client. It
is valid only in postbody.
Name Type JavaScript
Type
Comment
* when pr ebody i s i nj ect ed ( When we get t he i ni t i al
* byt es of ser ver r esponse) .
*/
/ / Cl i ent r equest t i mest amps
var cl t _r eq_beg=%%HTTP. REQ. RECEI VE_TI ME_BEG%%;
var cl t _r eq_end=%%HTTP. REQ. RECEI VE_TI ME_END%%;
/ / Net scl aer t o ser ver r equest t i mest amps
var ns_r eq_beg=%%HTTP. REQ. SEND_TI ME_BEG%%;
var ns_r eq_end=%%HTTP. REQ. SEND_TI ME_END%%;
</ scr i pt >
Configuring Postbody Files
Content injected after the response body of a response is called the postbody
content. To insert content into the response postbody, you must need to create a
separate postbody file on the NetScaler, containing with the content you want
injected.
Postbody files are stored by default in the / nsconf i g/ ht ml i nj ect i on
directory on the NetScaler by default. However, they can be stored in any other
location of your choice.
Note: The postbody file name can have a maximum of 64 characters and can
have any extension.
The following is a sample postbody file created on the NetScaler that will be used
for postbody injection.
Sample postbody file: /nsconfig/htmlinjection/
postbody.js
<! - - Thi s i s a sampl e post body f i l e - - >
<scr i pt l anguage=" J avaScr i pt " >
/ / I nt er nal var i abl es ar e del i mi t ed by t he per cent char act er s
/ * The f ol l owi ng t wo var i abl es must be quot ed.
* Ot her wi se br owser may gi ve a J avaScr i pt er r or .
*/
/ / Syst emI I D
var sys_i i d=" %%SYS. I I D%%" ;
/ / HTTP t r ansact i on I D
var ht t p_xi d=" %%HTTP. XI D%%" ;
/ * Fol l owi ng t i mest amp var i abl es ar e guar ant eed t o be
* val i d onl y when we get t he l ast byt e of r esponse
* ( That i s, when we ar e i nj ect i ng post body) .
*/
/ / Ser ver r esponse t i mest amp var i abl es
var ser ver _r es_beg=%%HTTP. RES. RECEI VE_TI ME_BEG%%;
var ser ver _r es_end=%%HTTP. RES. RECEI VE_TI ME_END%%;
/ / Syst emt o cl i ent r esponse t i mest amp var i abl es
var ns_r es_beg=%%HTTP. RES. SEND_TI ME_BEG%%;
var ns_r es_end=%%HTTP. RES. SEND_TI ME_END%%;
</ scr i pt >
Specifying Files to be used for Injection
In this section, you will specify the files that the NetScaler will use for prebody
and postbody injection.
To specify files to be used for prebody injection
1. In the left pane, click Protection Features. The Protection Features page
2. In the Protection Features Overview group, click the HTML Injection
link. The Configure HTML Injection dialog box appears.
3. Click the Browse button next to the Prebody text box. The contents of the
/ nsconf i g/ ht ml i nj ect i on directory are displayed by default.
4. Select pr ebody. j s and click OK.
To specify files to be used for prebody injection using the NetScaler
command line
set filter prebodyinjection prebody.js
To specify files to be used for postbody injection
2. In the Protection Features Overview group, click the HTML Injection
link. The Configure HTML Injection dialog box appears.
3. Click the Browse button next to the Postbody text box. The contents of the
/ nsconf i g/ ht ml i nj ect i on directory appear by default.
4. Select post body. j s and click OK.
To specify files to be used for postbody injection using the NetScaler
command line
set filter postbodyinjection postbody.js
Injecting Data into the HTTP Body
This section describes the procedures to inject data into the HTTP body using the
prebody and postbody files configured in the section above.
The following sample procedure describes the steps to create two filter actions,
Action-Filter-Prebody and Action-Filter-Postbody, that insert the contents of the
prebody and postbody files into the HTTP body.
To add a prebody filter action
4. In the Action Name text box, type the name of the filter action, for
example, Action-Filter-Prebody.
5. Under Qualifier, choose Add.
6. In the Value list, select Prebody.
7. Click Create. The filter action Action-Filter-Prebody is created.
To add a prebody filter action using the NetScaler command line
add filter action Action-Filter-Prebody add prebody
To add a Postbody Filter Action,
3. Click Add. The Create Filter Action dialog box appears. See figure above.
4. In the Action Name text box, type Action-Filter-Postbody.
6. In the Value list, select Postbody.
7. Click Create. The filter action Action-Filter-Postbody is created.
To add a postbody filter action using the NetScaler command line
add filter action Action-Filter-Postbody add postbody
The following example creates two filter policies, Policy-Filter-Prebody and
Policy-Filter-Postbody, and binds them to a virtual server to be used for prebody
and postbody injection.
To add a prebody filter policy
2. Click Add. The Create Filter Policy dialog box appears.
3. In the Filter Name text box, type Policy-Filter-Prebody.
4. Under Response Action, choose the filter action, Action-Filter-Prebody,
to be associated with this policy.
5. Under General Named Expressions, select the built-in general expression
ns_true, then click Add Expression. The expression ns_true now appears
in the Expression text box
6. Click OK, then click Close. The new filter policy Policy-Filter-Prebody,
appears in the Filter Policies page.
To add a prebody filter policy using the NetScaler command line
add filter policy Policy-Filter-Prebody -rule ns_true -resAction
Action-Filter-Prebody
To add a postbody filter policy
2. Click Add. The Create Filter Policy dialog box appears as shown in the
figure.
3. In the Filter Name text box, type Policy-Filter-Postbody.
4. Under Response Action, choose the filter action, Action-Filter-Postbody,
6. Click OK, then click Close. The new filter policy Policy-Filter-Postbody,
To add a postbody filter policy using the NetScaler command line
add filter policy Policy-Filter-Postbody -rule ns_true -resAction
Action-Filter-Postbody
In this section you will bind the filter policies that you configured in the previous
section (Policy-Filter-Prebody and Policy-Filter-Postbody) to the load balancing
virtual server Vserver-LB-2 on the NetScaler.
To bind a prebody filter policy to a load balancing vserver
filter policy to. For example, select Vserver-LB-2, then click Open. The
Configure Virtual Server (Load Balancing) dialog box appears.
3. Select the Policies tab to view the policies presently configured on the
NetScaler.
4. Select the check box next to Policy-Filter-Prebody
5. Click OK. The filter policy Filter-Policy-Prebody is bound to the virtual
server Vserver-LB-2.
To bind a prebody filter policy to a load balancing vserver using the
bind lb vserver Vserver-LB-2 -policyname Policy-Filter-Prebody
To bind a postbody filter policy to a load balancing vserver,
filter policy to. For example, select Vserver-LB-2, then click Open. The
Configure Virtual Server (Load Balancing) dialog box appears.
3. Select the Policies tab to view the policies presently configured on the
NetScaler.
4. Select the check box next to Policy-Filter-Postbody
5. Click OK. The filter policy Filter-Policy-Postbody is bound to the virtual
server Vserver-LB-2.
To bind a postbody filter policy to a load balancing vserver using the
bind lb vserver Vserver-LB-2 -policyname Policy-Filter-Postbody
Configuring the HTML Injection Feature for Commonly
Used Applications
The HTML Injection feature measures application performance in combination
with applications such as the Citrix EdgeSight for NetScaler server or the
Symphoniq TrueView server.
This section describes the steps to configure HTML Injection for performance
measurement using the Citrix EdgeSight for NetScaler server.
Measuring Application Performance Using a Citrix
EdgeSight for NetScaler Server
You can use the HTML Injection feature to measure performance in combination
with the Citrix EdgeSight for NetScaler server. You will need to inject appropriate
J avascript to send the required data to the EdgeSight server.
The injected J avaScript will record various values such as system ID, HTTP
transaction ID and other transaction performance measurement timestamps. The
J avaScript then executes on the client browser and sends performance data to the
EdgeSight for NetScaler database and report generation server.
You can then use the EdgeSight for NetScaler server console to view performance
results based on the data collected. You can also use the EdgeSight for NetScaler
console to set a number of other operational parameters and user preferences.
Note: For details on setting up a Citrix EdgeSight for NetScaler server, refer to
the Citrix EdgeSight for NetScaler Installation Guide.
In order to configure the NetScaler for performance mgeasurement using the
Citrix EdgeSight server, you must create specific prebody and postbody scripts,
then bind them on the NetScaler. Once the policies are bound, data is sent to the
Citrix EdgeSight for NetScaler server to enable performance analysis and
measurement.
In the following example, the client connects to a Citrix NetScaler that hosts the
site http://www.a.com. A Citrix Edgesight for NetScaler server, http://
ens.citrix.com, is used to measure application performance for all traffic flowing
through the Citrix NetScaler. The following table lists the names and values of the
entities that must be configured on the NetScaler before you can set up
performance monitoring as described in the example..
.
Application Performance Measurement with Citrix EdgeSight for NetScaler
Entity Type Name URL
Load Balancing Virtual Server Vserver-LB-ENS ht t p: / / www. a. com
Citrix EdgeSight for NetScaler
Server
ht t p: / / ens. ci t r i x. com
Enabling the HTML Injection Feature
To enable the HTML Injection feature
2. In the Modes & Features group, click Advanced Features. The
3. Choose HTML Injection and click OK. Click Yes on the Enable/Disable
Feature(s)? confirmation message that appears.
The HTML Injection feature is enabled on the NetScaler.
Configuring Prebody and Postbody files for the Citrix
EdgeSight for NetScaler Server
The NetScaler provides Citrix EdgeSight-specific prebody and postbody
J avascript files that you can modify and use for performance measurement.
These files are available in the /nsconfig/htmlinjection/ens folder.
Open the prebody.js file in any editor of your choice and modify the EdgeSight
server variable to reflect the location of the Citrix EdgeSight server in your
network.
For example, if the Citrix EdgeSight server is located at http://ens.citrix.com,
you should change the EdgeSight server variable to http://ens.citrix.com.
Note: Use https in case of an SSL server.
You can also customize the Citrix EdgeSight-specific prebody and postbody
J avascript files by including other NetScaler internal variables as required.
Once the prebody and postbody files are configured, you can create HTML
Injection policies, as described earlier, and use them to measure performance in
conjunction with the Citrix EdgeSight server.
Specifying Files to be used for Injection
This section describes how to specify that the NetScaler should use the Citrix
EdgeSight for NetScaler files provided for prebody and postbody insertion.
To specify files to be used for prebody injection,
2. Under Protection Features Overview click HTML Injection. The
Configure HTML Injection dialog box appears.
3. Click the Browse button next to the Prebody text box. The contents of the
/ nsconf i g/ ht ml i nj ect i on folder appear by default.
4. Double-click the ens folder. The contents of the ens folder appear.
5. Select pr ebody. j s and click OK.
To specify files to be used for postbody injection,
2. Under Protection Features Overview click HTML Injection. The
Configure HTML Injection dialog box appears.
3. Click the Browse button next to the Postbody text box. The contents of the
/ nsconf i g/ ht ml i nj ect i on folder appear by default.
4. Double-click the ens folder. The contents of the ens folder appear.
5. Select post body. j s and click OK.
Injecting Data into the HTTP Body
This section describes how to create two filter actions, Action-Filter-Prebody
and Action-Filter-Postbody, that insert the contents of the prebody and postbody
files into the HTTP body.
To add a prebody filter action
4. In the Action Name text box, type the name of the filter action, for
example, Action-Filter-Prebody.
6. In the Value list, select Prebody.
7. Click Create. The filter action Action-Filter-Prebody is created.
To add a Postbody Filter Action,
3. Click Add. The Create Filter Action dialog box appears. See figure above.
4. In the Action Name text box, type Action-Filter-Postbody.
6. In the Value list, select Postbody.
7. Click Create. The filter action Action-Filter-Postbody is created.
In this section, you will create two filter policies, Policy-Filter-Prebody and
Policy-Filter-Postbody, and bind them to a virtual server for use in prebody and
postbody injection.
To add a prebody filter policy
figure.
3. In the Filter Name text box, type Policy-Filter-Prebody.
4. Under Response Action, choose the filter action, Action-Filter-Prebody,
6. Click OK, then click Close. The new filter policy Policy-Filter-Prebody,
To add a postbody filter policy,
figure.
3. In the Filter Name text box, type Policy-Filter-Postbody.
4. Under Response Action, choose the filter action, Action-Filter-Postbody,
6. Click OK, then click Close. The new filter policy Policy-Filter-Postbody,
This section describes the steps to bind the filter policies you created in the
previous section, Policy-Filter-Prebody and Policy-Filter-Postbody, to the load
balancing virtual server Vserver-LB-ENS.
To bind the prebody filter policy to the load balancing vserver,
2. Select Vserver-LB-ENS and click Open. The Configure Virtual Server
4. Select the check box next to Policy-Filter-Prebody
5. Click OK. The filter policy Filter-Policy-Prebody is bound to the virtual
server Vserver-LB-ENS.
To bind the postbody filter policy to the load balancing vserver,
2. Select Vserver-LB-ENS and click Open. The Configure Virtual Server
4. Select the check box next to Policy-Filter-Postbody
5. Click OK. The filter policy Filter-Policy-Postbody is bound to the virtual
server Vserver-LB-ENS.
To measure application performance with a Citrix Edgesight for NetScaler
server using the NetScaler command line
enable ns feature htmlinjection
set filter prebodyinjection /nsconfig/htmlinjection/ens/prebody.js
set filter prebodyinjection /nsconfig/htmlinjection/ens/postbody.js
add filter action Action-Filter-Prebody add prebody
add filter action Action-Filter-Postbody add postbody
add filter policy Policy-Filter-Prebody -rule ns_true -resAction
Action-Filter-Prebody
add filter policy Policy-Filter-Postbody -rule ns_true -resAction
Action-Filter-Postbody
bind lb vserver Vserver-LB-ENS -policyname Policy-Filter-Prebody
bind lb vserver Vserver-LB-ENS -policyname Policy-Filter-Postbody
CHAPTER 15
Responder
Overview
This chapter describes the responder feature of the NetScaler, with basic and
advanced configuration procedures.
How Responder works
Configuring the Responder feature with the Respondwith action
Configuring the Responder feature with the Redirect action
Managing Responder actions
Managing Responder policies
How Responder Works
The responder feature functions as an advanced content filter that can generate
responses from the NetScaler to the client. Common uses of the responder are to
generate redirect responses, user-defined responses, and resets. The responder
deals only with the request side of the NetScaler (unlike content filtering, which
deals with requests just before they are returned to the back-end servers).
The responder is one of the first modules on the NetScaler to process requests
from the client side. You can set up custom responses for various types of
requests using the responder.
You can configure responder policies to look for certain types of data in a client
request and perform actions according to the rules you set. If a request matches a
configured responder policy, the action corresponding to the policy generates the
response and sends it to the client. The response will typically contain some
pieces of the request. For example, when generating a redirect response, the
incoming URL is fed back into the response.
The following figure shows the responder feature in the NetScaler
An Overviewof the Responder Feature in the NetScaler
Configuring the Responder Feature with a Respondwith
Action
The Respondwith action generates an HTTP response to the client before the
request reaches the back-end server.
The following sample procedure describes the steps to block access to the back-
end server for clients originating from the IP address subnet 222.222.X.X. The
responder sends an error message stating that the client is not authorized to access
the URL requested.
Enabling the Responder Feature
The responder feature is located under Advanced Features. The following
procedure describes the steps to enable the responder feature
To enable the responder feature
2. In the Modes & Features group, click Advanced Features. The
3. Select the Responder check box, then click OK. When the Enable/Disable
Feature(s)? message appears, click Yes.
Chapter 15 Responder 709
The Responder feature is enabled on the NetScaler.
To enable the responder feature usingthe NetScaler command line
enable ns feature responder
Setting the NetScaler Behavior for Undefined
Events
The NetScaler triggers an UNDEF event when it is unable to determine a
matching policy. When the NetScaler evaluates a responder policy and produces
an UNDEF event, it carries out the action configured as a response to the UNDEF
event.
UNDEF actions configured at the responder policy level are carried out before
globally configured UNDEF actions.
Two types of UNDEF actions are available, NOOP and RESET. The default
UNDEF action is NOOP.
NOOP. The NOOP action aborts responder processing but does not alter
the packet flow.
RESET. If the UNDEF action is set to RESET, the NetScaler resets the
particluar client connection.
Note: UNDEF events are triggered only for client requests. No UNDEF events
are triggered while preparing the response.
The following procedure describes the steps to set the NetScaler behavior for
undefined actions.
To set the NetScaler behavior for undefined actions
1. In the left pane, expand Protection Features, then click Responder. The
Responder page appears in the right pane.
2. In the Responder Overview group, click the Responder Parameters link.
The Set Responder Params dialog box appears.
3. Under Undefined Action, select NOOP, then click OK.
The global undefined action is set to NOOP.
Note: To set the global undefined action to RESET, in Step 3 above, click
RESET under Undefined Action.
To set the NetScaler behaviour for undefined actions using the NetScaler
command line
set responder param -undefAction NOOP
Configuring Respondwith Actions
All responder tasks are configured on the NetScaler using responder actions.
These actions are then associated with responder policies that are activated based
on incoming traffic and the configured policy rules. When a responder policy is
activated, the corresponding responder action is carried out.
A respondwith action is used to send an HTTP string as a response to a client.
The following table describes the parameters you must configure to create a
respondwith action
The following sample procedure describes steps to create a Respondwith action
that sends an HTTP/1.1 200OK response to the client, along with an error
message indicating that the client IP is not authorized to access the requested
URL.
To create a respondwith action
1. In the left pane, expand Protection Features, then expand Responder and
click Actions. The Responder Actions page appears in the right pane.
2. Click Add. The Create Responder Action dialog box appears.
Name The name of the action. This is a mandatory parameter and
cannot be changed. The action name must not exceed 31
characters.
Type The type of responder action being configured. This
parameter determines the behaviour of the responder action.
You can choose to respond to the client or redirect the client
elsewhere.
Select the Respondwith responder action type to send the
configured target string to the client.
Target This parameter contains the HTTP string to be sent as a
response to the client.
3. In the Name text box, type the name of the responder action, for example
Action-Responder-1.
4. Under Type, select Respond with.
5. In the Target text area, type " HTTP/ 1. 1 200 OK\ r \ n\ r \ n" + " Cl i ent : "
+ CLI ENT. I P. SRC + " i s not aut hor i zed t o access URL: " +
HTTP. REQ. URL. HTTP_URL_SAFE
6. Click Create, then click Close. The responder action you created now
appears in the Responder Actions page.
To create a respondwith action using the NetScaler command line
add responder action Action-Responder-1 respondwith "HTTP/1.1 200
OK\r\n\r\n" + "Client: " + CLIENT.IP.SRC + " is not authorized to
access URL:" + HTTP.REQ.URL.HTTP_URL_SAFE
Configuring Responder Policies
A responder policy consists of a rule expression and a responder action. The
policy rules can be based on various parameters of the incoming data. For some
incoming data, if a configured rule matches, the corresponding policy is triggered
This section describes the procedures to configure responder policies.
Creating Responder Policies
responder policy
Name The name of the policy. This is a mandatory parameter and
cannot be changed. The policy name must not exceed 31
characters.
Action The responder action associated with the policy. You can
choose either the built-in NOOP or RESET actions or
any other configured responder action.
Undefined Action The action to use if the policy causes an undefined event.
You can select either the NOOP or RESET action or set
the NetScaler use the configured global undefined action.
The undefined action configured using this dialog box will
override the global undefined action.
The following sample procedure describes steps to create a responder policy to
invoke the responder action Action-Responder-1, created in the previous section
for all client requests that originate from the IP address subnet 222.222.X.X.
To create a responder policy
click Policies. The Responder Policies page appears in the right pane.
2. Click Add. The Create Responder Policy dialog box appears.
3. In the Name text box, type the name of the responder policy, for example,
Policy-Responder-1.
4. Under Action, select the action to be associated with the policy, for
example, Action-Responder-1.
5. Under Undefined Action, select Global Undefined Action.
Note: To associate a specific undefined action with the policy being
created, select the undefined action. Otherwise, the NetScaler will apply the
global undefined action for all UNDEF events.
6. Under Expression, select Advanced Free Form and in the Expression
text box, type the rule for which you want the policy to be applied, for
example, CLI ENT. I P. SRC. I N_SUBNET( 222. 222. 0. 0/ 16) .
Note: For information on using the NetScaler policy infrastructure to
configure policy expressions, see the chapter Policies and Expressions.
7. Click Create, then click Close. The responder policy you configured now
appears in the Responder Policies page.
To create a responder policy using the NetScaler command line
add responder policy Policy-Responder-1
CLIENT.IP.SRC.IN_SUBNET(222.222.0.0/16) Action-Responder-1
Binding Responder Policies to a Virtual Server
The responder policies that are configured on the NetScaler should be bound to a
virtual server which will intercept traffic directed to it. If the incoming data
matches any of the rules configured in the responder policy, the policy is
triggered and the action associated with it is carried out.
The following sample procedure describes the steps to bind the responder policy
Policy-Responder-1, configured in the previous section, to the load balancing
virtual server Vserver-LB-1 on the NetScaler.
Note: Responder policies cannot be bound to TCP based virtual servers on the
NetScaler.
To bind a responder policy to a Load Balancing vserver
to bind the responder policy. For example, select Vserver-LB-1, then click
appears.
3. Select the Policies tab. The policies configured on the NetScaler appear.
4. Select the check box next to Policy-Responder-1.
5. Click OK. The responder policy Policy-Responder-1 is bound to the
virtual server Vserver-LB-1.
To bind a responder policy to a load balancing vserver using the NetScaler
command line
bind lb vserver Vserver-LB-1 -policyname Policy-Responder-1
Note: You can bind responder policies globally, and to custom bind points on
the NetScaler. For more information on binding policies on the NetScaler, refer to
the Policies and Expressions chapter.
This section describes the procedure to verify that the responder feature is
accurately configured to respond to client requests.
Viewing the Configured Responder Actions
The following example describes the steps to verify that the responder action
Action-Responder-1 is configured accurately on the NetScaler.
To view configured responder actions
1. In the left pane, expand Protection Features, then expand Filter and click
Actions.The Responder Actions page appears in the right pane, and the
Responder actions configured on the NetScaler appear.
2. Verify that the configured responder action, Action-Responder-1 is
displayed.
3. Select the responder action Action-Responder-1, and in the Details
section, verify that the correct target string is configured for it..
To view configured responder actions using the NetScaler command line
show responder action
To view details about the responder action Action-Responder-1, type
show filter action Action-Responder-1
Viewing the Configured Responder Policies
Verify that the responder policy Policy-Responder-1 is configured accurately on
the NetScaler.
To view configured responder policies
1. In the left pane, expand Protection Features, then expand Filter and click
Policies.The Responder Policies page appears in the right pane, and the
responder policies configured on the NetScaler are displayed.
2. Verify that the configured responder policy, Policy-Responder-1 is
displayed.
3. Select the responder policy Policy-Responder-1, and in the Details
section, verify that the parameters configured are correct.
To view configured responder policies using the NetScaler command line
show responder policy
To view details about the responder policy Policy-Responder-1, type
show filter policy Policy-Responder-1
Viewing the Properties of the Virtual Server
The following example verifies that the responder policy binding is accurate.
To verify that the responder polices are bound to the load balancing vserver
2. From the list of virtual servers, select the virtual server that the responder
policy is bound to. For example, choose Vserver-LB-1, then click Open.
The Configure Virtual Server (Load Balancing) dialog box appears.
3. Select the Policies tab. The policies configured on the NetScaler are
displayed
4. Verify that the check box corresponding to the responder policy to be bound
to the virtual server is selected.
To verify that the responder polices are bound to the load balancing vserver
usingthe NetScaler command line
Configuring the Responder Feature with a Redirect
Action
The Redirect action of the responder is used to redirects the client if a request
meets certain conditions, before the request reaches the back-end server.
The example in this section uses the responder to block access to the back-end
server for clients originating from IP address subnet 222.222.X.X. It then
redirects the client to the URL http://redirectURL.
Notice that, except for choosing a Redirect action, the steps in the folloowing
procedure are the same as for configuring a Respondwith action, as described in
Configuring Respondwith Actions
Configuring Redirect Actions
redirect action
Name The name of the action. This is a mandatory parameter and
cannot be changed. The action name must not exceed 31
characters.
The sample procedure below describes the steps to create a Redirect action that
redirects the client to the URL ht t p: / / r edi r ect URL.
To create a responder action
2. Click Add. The Create Responder Action dialog box appears.
3. In the Name text box, type the name of the responder action, for example
Action-Responder-2.
4. Under Type, select Redirect.
5. In the Target text area, type ht t p: / / r edi r ect URL.
6. Click Create, then click Close. The responder action you created now
appears in the Responder Actions page.
To create a redirect action using the NetScaler command line
add responder action Action-Responder-2 redirect http://
redirectURL
Managing Responder Actions
This section describes the procedures to manage any responder actions you have
Bypassing the Safety Check
Expressions created by the NetScaler from run-time data, for example, URLs
contained in the HTTP requests or responses can cause unexpected errors and are
reported by the NetScaler as unsafe expressions.
Type The type of responder action being configured. This
parameter determines the behaviour of the responder action.
You can choose to respond to the client or redirect the client
elsewhere.
Select the Redirect action type
Redirect - Generate an HTTP redirect to the URL
configured in the target string.
Target This parameter contains the URL to the location the client
should redirected to.
When you create a responder action, the NetScaler verifies that the expression
you used to create the action is safe. You can manually bypass this option to allow
configuration of unsafe expressions.
To bypass safety check
2. Select the responder action that will be allowed to bypass the safety check.
For example, select Action-Responder-1, then click Open. The Configure
Responder Action dialog box appears.
3. Select the Bypass Safety Check check box, then click OK. The NetScaler
is now configured to bypass the safety check for the responder action
Action-Responder-1.
To bypass safety check for a responder action using the NetScaler
command line
set responder action Action-Responder-1 -bypassSafetyCheck YES
Modifying an Existing Responder Action
You can modify the Target expression and the Bypass Safety Check option for
any configured responder action. The following procedure describes the steps to
modify the Bypass Safety Check option for the respodner action Action-
Responder-1.
To modify an existing responder action
2. Select the responder action you want to modify, for example Action-
Responder-1, then click Open. The Configure Responder Action dialog
box appears.
3. Modify the Target expression or the state of the Bypass Safety Check
option as required and click OK. The modified responder action Action-
Responder-1 now appears in the Responder Actions page.
To modify an existing responder action using the NetScaler command line
set responder action Action-Responder-1 -target new_string
Removing an Existing Responder Action
You can remove responder actions that are not associated with any policies on the
NetScaler. The following procedure describes the steps to remove the responder
action Action-Responder-1 from the NetScaler.
To remove a configured responder action
2. Select the responder action you want to remove, for example Action-
Responder-1, then click Remove. The Remove dialog box appears.
3. Click Yes to confirm. The responder action, Action-Responder-1 is
removed from the NetScaler.
To remove a configured responder action using the NetScaler command line
At the NetScaler prompt, type:
remove responder action Action-Responder-1
Note: Removal will fail if the responder action is used by any configured policy
on the NetScaler.
Managing Responder Policies
This section describes the procedures to manage responder policies configured on
the NetScaler.
Setting the Undefined Action
For more granular control, you can set the action to be carried out in case of an
undefined event on a per-policy basis. Any undefined actions you set at the policy
level take precedence over the global undefined action.
The following procedure describes the steps to set the NOOP undefined action for
the responder policy Policy-Responder-1.
To set the undefined action for a configured policy
2. Select the responder policy you want to modify, for example Policy-
Responder-1, then click Open. The Configure Responder Policy dialog
box appears.
3. Under Undefined Action, select the undefined action to be configured, for
example NOOP.
4. Click OK. The undefined action NOOP is associated with the responder
policy Policy-Responder-1.
To set the undefined action for a configured policy using the NetScaler
command line
set responder policy Policy-Responder-1 -undefAction NOOP
Removing an Existing Responder Policy
You can remove responder policies that are not bound globally to a virtual server,
or to a custom bind point. The following procedure describes the steps to remove
the responder policy Policy-Responder-1.
To remove a configured responder policy
2. Select the responder policy you want to remove, for example, Policy-
Responder-1, and click Remove. The Remove dialog box appears.
3. Click Yes to confirm. The responder policy Policy-Responder-1 is
removed from the NetScaler.
To remove a configured responder policy using the NetScaler command line
rm responder policy Policy-Responder-1
Note: Responder policy removal fails if the policy is bound to any point on the
NetScaler
APPENDIX A
API Reference
This chapter provides information on the Application Switch Application
Programming Interface (API) and detailed instructions on how to use the API to
implement customized client applications.
This chapter is intended for developers and administrators who will use the API
to implement customized client applications.
Introduction to the API
The Application Switch can be configured using an external Application
Programming Interface (API). The API allows programmatic communications
between client applications and the system. This interface provides the means for
a custom client application to configure and monitor the state of the system.
The API is based on the Simple Object Access Protocol (SOAP) over HTTP and
is used to develop custom client application that will configure and monitor the
system. SOAP is a transport protocol for exchanging information in a
decentralized, distributed environment and enables you to write the business logic
and schema for facilitating business-to-business transactions over the Internet.
The NetScaler x.xx software contains a number of changes and enhancements to
the API, including the following:
Add command. In 4.0.1, the add command contains only the required
argument and optional argument. Neither can be modified by the set
command.
Set command. In 4.0.1, all set commands take single arguments; these
commands take multiple arguments only in case of dependent arguments.
In dependent arguments, the name of the first argument is assumed to be
part of the signature.
Bind and unbind commands. In 4.0.1, the bi nd and unbi nd commands
treat dependent arguments exactly as set commands do.
Note: The Application Switch continues to accept and correctly process
requests from clients developed using previous versions of the API.
Benefits of API
The following are the benefits of the API:
The API provides developers the advantage of controlling the system from
a custom application. The API enables the client application to configure
and monitor the system.
The interface allows the developers to easily and quickly develop client
applications using a language and platform with which the developer is
comfortable.
The API provides a secure, end-to-end, standards-based framework that
integrates into the existing infrastructure.
Hardware and Software Requirements
To work with the API, your system needs to meet the following hardware and
software setup and requirements:
A client workstation.
Access to a Application Switch (version 5.0 or higher).
A SOAP client tool kit (supporting SOAP version 1.1 and above), and the
development environment for the tool kit. (For example, if you use a Visual
Basic tool kit, you must have Visual Basic installed on your system).
Interface Description
The API consists of the NSConfig interface. The NSConfig interface includes
methods for setting and querying the configuration. These methods allow the
client application using the NSConfig interface to perform almost all operations
that an administrator would normally perform with the CLI or GUI.
The Application Switch provides an interface description using the Web Services
Definition Language (WSDL) that facilitates the development of client
applications using a language and platform of the developers choice.
Appendix A 723
API Architecture
The API architecture is designed to allow NSConfig client requests to be routed
through the HTTP daemon running on the target Application Switch to a SOAP
handler that translates the SOAP request into a call to the (internal) kernel
configuration API. An illustration of the flow of these requests is provided in
Figure.
The API Architecture
The order in which the Application Switch processes requests through the API is
as follows:
1. The client formats a request containing XML conforming to the SOAP
protocol and sends it to the Application Switch.
2. The HTTPD server instance on the Application Switch routes this request
to a SOAP handler.
3. The SOAP handler interprets the SOAP headers, and maps the enclosed
request to an internal configuration function.
4. The kernel acts on the request and returns one or more responses.
5. The SOAP handler then translates the response(s) to a SOAP response
message.
6. The XML response is then sent back to the client in a HTTP response.
The NSConfig Interface
The NSConfig interface closely mirrors the structure of the Application Switch
Command Line Interface (CLI). The administrators and programmers who are
familiar with the CLI can easily create and implement custom applications to
query or set the configuration on their Application Switch. This semantic and
syntactic similarity between the API and the CLI helps users to leverage their
familiarity and expertise with the CLI to create applications using the API.
The NSConfig interface contains a method corresponding to each CLI command.
See the <portType>section of the WSDL for a complete list of methods and their
names.
Note: There are several CLI commands that are not included in the API, and a
few instances where the method name and the CLI command differ.
For example, you use the add l b vser ver CLI command to create a load
balancing virtual server, as shown below:
add l b vser ver <vSer ver Name> <ser vi ceType> [ <por t >]
where:
<vServerName> =A name for the virtual server.
<serviceType> =( HTTP | FTP | TCP | UDP).
<IPAddress> =The IP address used by the virtual server.
<port> =The port that the virtual server listens on.
The corresponding API call, in the C language, is shown below:
i nt ns__addl bvser ver ( voi d *handl e,
st r i ng vSer ver Name,
st r i ng ser vi ceType,
st r i ng I PAddr ess,
unsi gnedShor t por t ,
ns__addl bvser ver Response *out ) ;
Note: The exact syntax of the API call will depend on the language being used
to write the client program. The above ns__addl bvser ver function prototype is
similar to the one that would be generated by the gSOAP package at ht t p: / /
www. cs. f su. edu/ ~engel en/ soap. ht ml .
The result returned for all NSConfig requests consists of:
Rc. An integer return code. The value is zero if the request succeeded; a
non-zero value is returned if the request failed.
Appendix A 725
Message. A string message. This contains meaningful information only if
the request fails (rc is non-zero), for example, Required argument
missing.
List. A type-specific list of result entities. This element is present only for
requests that retrieve information from the system. For example, the API
method names starting with get , which corresponds to the CLI show
commands, return a list.
For a CLI command listed in the Command Reference (CRG) as <op><grp>
<ot>, the corresponding API method is named "<op><grp><ot>", with the
following exceptions:
1. The CLI show command is changed to get in the API, as shown below.
show l b vser ver => get l bvser ver
show ser vi ce => get ser vi ce
2. The group of commands in the base CLI group have no <grp>, and are
listed in the Command Reference Guide as such. For example, show
ser vi ce becomes get ser vi ce, and add moni t or becomes addmoni t or.
3. The following commands are, for various reasons, omitted from the API:
All commands in the cli" group.
The bat ch, pi ng, gr ep, mor e, shel l , and scp commands.
The show r out er bgp and show r out er map commands.
All st at commands.
4. Message "part" names in the API are the same as the corresponding CLI
argument names. As in the CLI, case does not matter; these names can be
abbreviated. See the first chapter of the Command Reference Guide for
more information.
5. The result of "get" methods (which correspond to the show commands in
the CLI) is always an array of a type defined in the WSDL. The elements of
these complex types generally correspond to arguments to the
corresponding add/set command/method.
6. Authorization must be performed once, by sending a login" request; the
response to this contains a Set-Cookie HTTP header. The cookie must be
passed with each subsequent request. This is addressed in the Perl examples
using HTTP::Cookies.
7. In some programming languages, such as Perl, it is possible to invoke the
programming language API without using the WSDL.
Examples of API Usage
This section consists of examples that show how you can develop an API call
from a standard CLI command, how to generate the SOAP request, and how the
Application Switch responds to that request.
Example: Setting the Configuration
This example shows a CLI command, the corresponding API method, the
resulting XML request, and the XML response that is sent back to the client.
Note: The actual API method and the XML SOAP message contents may differ
from the example shown below. The XML shown will be encased in a SOAP
envelope, which will in turn be carried in an HTTP message. For more
information on this, see ht t p: / / www. w3. or g/ TR/ SOAP.
The following is the CLI command to create a Load Balancing virtual server:
> add l b vser ver vi pLB1 HTTP 10. 100. 101. 1 80
The following is the corresponding API method:
> ns__addl bvser ver ( handl e, vi pLB1, HTTP, 10. 100. 101. 1, 80,
&out ) ;
The XML generated for this request is as follows.
<ns: addl bvser ver >
<vSer ver Name xsi : t ype=" xsd: st r i ng" >vi pLB1</ vSer ver Name>
<ser vi ceType xsi : t ype=" ns: vser vi cet ypeEnum>HTTP</ ser vi ceType>
10. 100. 101. 1
<por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t >
< / ns: addl bvser ver >
The XML response to the above request is as follows.
<ns: addl bvser ver Response>
<r c xsi : t ype=" xsd: unsi gnedI nt " >0</ r c>
<message xsi : t ype=" xsd: st r i ng" >Done</ message>
</ ns: addl bvser ver Response>
Example: Querying the Configuration
This example shows an API request that queries the configuration and receives a
list of entities.
Note: The actual API method and the XML SOAP message contents may differ
from the example shown below.
Appendix A 727
The following is the CLI command to show the configured Load Balancing
virtual servers:
> show l b vser ver s
Sample output of the show l b vser ver s command is as follows.
> show l b vser ver s
2 conf i gur ed vi r t ual ser ver s:
1) vi pLB1 ( 10. 100. 101. 1: 80) - HTTP Type: ADDRESS St at e:
DOWN
Met hod: LEASTCONNECTI ON Mode: I P
Per si st ence: NONE
2) vi pLB2 ( 10. 100. 101. 2: 80) - HTTP Type: ADDRESS St at e:
DOWN
Met hod: LEASTCONNECTI ON Mode: I P
Per si st ence: NONE
Done
The corresponding API method to show the list of Load Balancing virtual servers
is as follows.
ns__get l bvser ver ( handl e, NULL, &out )
The XML generated for this request is as follows.
<ns: get l bvser ver ></ ns: get l bvser ver >
The XML response to the about request is as follows.
<ns: get l bvser ver Response>
<r c xsi : t ype=" xsd: unsi gnedI nt " >0</ r c>
<message xsi : t ype=" xsd: st r i ng" >Done</ message>
<Li st xsi : t ype=" SOAP- ENC: Ar r ay"
SOAP- ENC: ar r ayType=" ns: l bvser ver [ 2] " >

<vSer ver Name xsi : t ype=" xsd: st r i ng>vi pLB1
</ vSer ver Name>
<ser vi ceType xsi : t ype=" xsd: st r i ng>HTTP</ ser vi ceType>
10. 100. 101. 1



<vSer ver Name xsi : t ype=" xsd: st r i ng>vi pLB2
</ vSer ver Name>
<ser vi ceType xsi : t ype=" xsd: st r i ng>HTTP</ ser vi ceType>
10. 100. 101. 2


</ Li st >
</ ns: get l bvser ver Response>
The Web Service Definition Language (WSDL)
The interface schema provided by enables the development of client applications
that use the API in a language and platform with which the developer is
comfortable. This interface schema is based on the WSDL specification.
The Application Switch provides a WSDL file (NSConf i g. wsdl ) containing the
interface definition. Developers, with the help of a third-party tool (such as
gSOAP) can use this WSDL file to generate client stubs. These stubs are then
called in a custom application to send a request to the Application Switch. The
application can be in any of the languages supported by the third-party tool, such
as Perl, J ava, C, C#, etc.
The NSConf i g. wsdl file is available on the Application Switch at:
ht t p: / / <NSI P>/ API / NSConf i g. wsdl
where <NSIP> is the IP address of your Application Switch.
Use this WSDL file and the interfaces mentioned in this document to develop
customized applications.
Creating Client Applications Using the
NSConfig.wsdl File
A client application can be created by importing the NSConf i g. wsdl with the
gSOAP WSDL Importer to create a header file with the C/C++declarations of
the SOAP methods. The gSOAP compiler is then used to translate this header file
into stubs for the client application.
To create client stubs using the NSConfig.wsdl file:
1. Get the NSConf i g. h header file from the WSDL file.
A. Run the wsdl 2h program that comes with gSOAP on the WSDL file.
The wsdl 2h program is in the following location.
> . / wsdl 2h NSConf i g. wsdl
The output of wsdl 2h is as follows:
** The gSOAP WSDL par ser f or C and C++ 1. 0. 2
** Copyr i ght ( C) 2001- 2004 Rober t van Engel en, Geni vi a, I nc.
** Al l Ri ght s Reser ved. Thi s pr oduct i s pr ovi ded " as i s" ,
wi t hout any war r ant y.
Savi ng NSConf i g. h
Readi ng f i l e ' NSConf i g. wsdl '
Cannot open f i l e ' t ypemap. dat '
Pr obl emr eadi ng t ype map f i l e t ypemap. dat .
Usi ng i nt er nal t ype def i ni t i ons f or C i nst ead.
Appendix A 729
B. Run the soapcpp2 program to compile the header file and complete
the process, as shown below.
> soapcpp2 NSConf i g. h
2. Generate the XML files and stubs, as shown below.
> . / soapcpp2 - c - i NSConf i g. h
Sample output for this command is shown below.
** The gSOAP St ub and Skel et on Compi l er f or C and C++ 2. 4. 1
** Copyr i ght ( C) 2001- 2004 Rober t van Engel en, Geni vi a, I nc.
** Al l Ri ght s Reser ved. Thi s pr oduct i s pr ovi ded " as i s" , wi t hout
any war r ant y.
Savi ng soapSt ub. h
Savi ng soapH. h
Savi ng soapC. c
Savi ng soapCl i ent . c
Savi ng soapSer ver . c
Savi ng soapCl i ent Li b. c
Savi ng soapSer ver Li b. c
Usi ng ns1 ser vi ce name: NSConf i gBi ndi ng
Usi ng ns1 ser vi ce l ocat i on: ht t p: / / Net Scal er . com/ api Usi ng ns1
schema namespace: ur n: NSConf i g
Savi ng soapNSConf i gBi ndi ngPr oxy. h cl i ent pr oxy
Savi ng soapNSConf i gBi ndi ngObj ect . h ser ver obj ect
Savi ng NSConf i gBi ndi ng. addser ver . r eq. xml sampl e SOAP/ XML r equest
Savi ng NSConf i gBi ndi ng. addser ver . r es. xml sampl e SOAP/ XML r esponse
Savi ng NSConf i gBi ndi ng. di sabl eser ver . r eq. xml sampl e SOAP/ XML
r equest
Savi ng NSConf i gBi ndi ng. di sabl eser ver . r es. xml sampl e SOAP/ XML
r esponse
Savi ng NSConf i gBi ndi ng. enabl eser ver . r eq. xml sampl e SOAP/ XML r equest
Savi ng NSConf i gBi ndi ng. enabl eser ver . r es. xml sampl e SOAP/ XML
r esponse
[ ... Similar lines clipped ... ]
Savi ng NSConf i gBi ndi ng. nsmap namespace mappi ng t abl e
Compi l at i on successf ul
This creates the stub files soapC. c, soapCl i ent . c and st dsoap2. c.
3. Link the stub files you created with your source code to create a stand-alone
binary that invokes the API.
Filter WSDL
The NetScaler WSDL describes services for the entire gamut of NetScaler
services. When you use the NetScaler API in your scripts, link to the WSDL and
attempt to compile them, the entire WSDL gets included and the time taken to
compile and also the eventual size of the program is unnecessarily increased.
Filter WSDL is a method to select only those service definitions from the
NetScaler WSDL that are relevant to the API calls made in the script. This
drastically reduces the size of the compiled program and also increases the speed
of compilation.
The NetScaler provides two WSDL files, one for the configurational APIs and the
other for statistical APIs. The WSDL file for the configurational API is much
larger in size and hence filter WSDL plays an important role when you try to
compile programs written using the configurational API.
FilterWSDL is a program which works on the Windows, FreeBSD and Linux
platforms which can be run from the CLI.
The syntax for the FilterWSDL command is as follows
f i l t er wsdl <f r omwsdl > <pat t er n>
where:
fromwsdl: The wsdl file from which you want to filter
pattern: API method names or patterns that should be filtered
For example, if you want to filter all the service definitions for the API method
'addlbvserver' from the system WSDL file, "NSConfig.wsdl", you can use the
command
> f i l t er wsdl NSConf i g. wsdl " addl bvser ver "
The output of this command is sent to the screen by default but it can be
redirected to a file on the system using the UNIX redirect '>' operator. The output
of the previous command can be saved into a file called 'NSConfig-Custom.wsdl'
using the command as follows,
> f i l t er wsdl NSConf i g. wsdl " addl bvser ver " > NSConf i g- Cust om. wsdl
Consider the files NSConfig.wsdl and NSConfig-Custom.wsdl attached to this
article. The original WSDL file is 1.58 MB in size while the filtered WSDL file is
6 KB in size.
The pattern used in the filterwsdl command can be used with the '+' and '-'
operators and the wildcard '*' operator to create more generic filters.
For example, if you wish to filter the service definitions for all the available load
balancing methods, you can use the command
> f i l t er wsdl NSConf i g. wsdl " *l b" *
This command will filter all the Load Balancing methods but will also include
'GSLB' methods because the pattern 'lb' will be matched by all 'GSLB' methods
also. To include only LB methods and exclude all GSLB methods, use the
command as follows
> f i l t er wsdl NSConf i g. wsdl +" *l b" - " gl sb" *
Appendix A 731
Securing API Access
Secure access to CLI objects can be provided based on the Application Switch IP
address or on the subnet IP address on which the Application Switch is deployed.
To provide secured API access based on the Application Switch IP address, you
must configure the Application Switch to use transparent SSL mode with clear
text port, as described below.
To configure secure API access based on the Application Switch IP:
1. Create a loopback SSL service, and configure it use transparent SSL mode
with clear text port.
> add ser vi ce secur e_xml access 127. 0. 0. 1 SSL 443 - cl ear Text Por t 80
2. Add certificate and key.
> add cer t key cer t 1 cer t / nsconf i g/ ssl / ssl / cer t 1024. pemkey /
nsconf i g/ ssl / ssl / r sakey. pem
Note: You can use an existing certificate and key or use the NetScaler
Certificate Authority Tool to create key and test certificate for secure
access.
3. Bind the certificate and key to the service.
> bi nd cer t key secur e_xml access cer t 1 - Ser vi ce
4. Add a custom TCP monitor to monitor the SSL service you have added.
> add moni t or ssl _mon TCP - dest por t 80
5. Bind the custom TCP monitor to the SSL service.
> bi nd moni t or ssl _mon secur e_xml access
To configure secure API access based on the subnet IP:
1. Create an SSL VIP in the appropriate subnet.
> add vser ver <vServerName> SSL <Subnet-IP> 443
2. Create a loopback HTTP service.
> add ser vi ce <serviceName> 127. 0. 0. 1 HTTP 80
3. Bind the service to the SSL VIP.
> bi nd l b vser ver <vServerName> <serviceName>
4. Add the certificate and the key.
> add cer t key cer t 1 cer t / nsconf i g/ ssl / ssl / cer t 1024. pemkey /
nsconf i g/ ssl / ssl / r sakey. pem
Note: You can use an existing certificate and key or use the NetScaler
Certificate Authority Tool to create key and test certificate for secure
access.
5. Bind the Certificate and the Key to the SSL VIP.
> bi nd cer t key <vServerName> cer t 1
APPENDIX B
Converting Certificate and Keys
This Appendix describes how to convert your SSL certificates and keys from one
format to another.
OpenSSL
The examples in this section will help you understand how to use the OpenSSL
tool to convert certificate and key file formats. (You can use the openssl tool
binary that comes bundled with the system.)
The below examples are based on the OpenSSL release version openssl_0.9.7c
that comes with the system. For newer versions of OpenSSL, the command
syntax may differ. For more help on tool usage, refer to: www.openssl.org.
Converting fromPKCS#12 to .PEM
Key and certificate files exported from IIS 5 are in PKCS#12 format and must be
converted to .PEM-encoded format before loading into the system.
Note: You can use the systems PKCS#12 conversion tool to convert
PKCS#12-encoded certificate and key files to PEM-encoded format. For more
information on the conversion tool, refer to Exporting SSL Certificates in SSL
chapter.
Enter the following command at the Unix prompt:
openssl pkcs12 - i n <pkcs12Fi l e> - out <pemFi l e> [ - nodes] [ - des] [ -
des3]
Where
<pkcs12File>: is the path and file name of the PKCS#12-format file
<pemFile>: is the path and file name of the PEM-encoded file.
[-nodes]: use this option if you do not wish to encrypt the private-key.
By default this option is disabled, and the key will be encrypted with Triple-DES
algorithm. The user will be prompted to enter the PEM pass phrase. Refer to the
example below.
[-des]: use this option to encrypt the private-key with DES algorithm
[-des3]: use this option to encrypt the private-key with Triple-DES
algorithm
Note: The User will be prompted to enter the password to import the
certificate-key pair.
Example:
openssl pkcs12 - i n ser ver _cer t . p12 - out ser ver _cer t . pem
Ent er I mpor t Passwor d: *****
MAC ver i f i ed OK
Ent er PEM pass phr ase: *******
Ver i f yi ng passwor d - Ent er PEM pass phr ase: *******
The content of the output certificate/Key pair file (server_cert.pem) after
conversion to PEM format is similar to the content as shown:
Bag At t r i but es
l ocal KeyI D: C6 49 0B C4 1C 3C 0F 9D D5 98 29 F1 2A 5D 7D D0 DA
48 83 1C
subj ect =/ C=US/ ST=CA/ L=SC/ O=I TM/ OU=SSL/ CN=www. mysi t e. com/
Emai l =admi n@mysi t e. com
i ssuer = / C=US/ ST=CA/ L=SC/ O=CA/ OU=CA- cer t / CN=www. myca. com
- - - - - BEGI N CERTI FI CATE- - - - -
MI I DCj CCAnOgAwI BAgI BAj ANBgkqhki G9w0BAQQFADBkMQswCQYDVQQGEwJ J bj ELMAk
GA1UECBMCS2ExDTALBgNVBAcTBEJ ubGcxEj AQBgNVBAoTCU5l dHNj YWxl cj ENMAsGA1
UECxMERW5nZzEWMBQGA1UEAxMNbmV0c2NhbGVyLmNvbTAeFw0wMj A4MTMwNj U2MTJ aF
w0wMj A5MTI wNj U2MTJ aMGExCzAJ BgNVBAYTAkl OMQswCQYDVQQI EwJ LYTELMAkGA1UE
BxMCYWExCzAJ BgNVBAoTAmFhMQswCQYDVQQLEwJ hYTELMAkGA1UEAxMCYWExETAPBgk
qhki G9w0BCQEWAmFhMI Gf MA0GCSqGSI b3DQEBAQUAA4GNADCBi QKBgQDMbi uRnTSOUM
t 7CbQNE9i zs1HTxXOQG/
LbYHaZ3Vi 8ds099vs18i qRGYSeFEUwCb9yJ vt 34Rcgr SUVF5KTwhp2UB3GRj qqWmduR
XT61Sp8wuNn7KvDuJ vUN+vPj PSkJ 61G9+Kj J eY4ZnbM08t l zI P1bQXbL7ow7N1SEPf M
O4LugQI DAQABo4HOMI HLMB0GA1UdDgQWBBTXFbWcqZz2K5V10sf Hj zI omI 2AcTCBj gY
DVR0j BI GGMI GDgBRyXxvUy02r t amOMt z7knOUFGi ow6FopGYwZDELMAkGA1UEBhMCSW
4xCzAJ BgNVBAgTAkt hMQ0wCwYDVQQHEwRCbmxnMRI wEAYDVQQKEwl OZXRzY2FsZXI xD
TALBgNVBAsTBEVuZ2cxFj AUBgNVBAMTDW5l dHNj YWxl ci 5j b22CAQAwDAYDVR0TBAUw
AwEBzALBgNVHQ8EBAMCBsAwDQYJ KoZI hvcNAQEEBQADgYEALQmB5ns3Gno0anzKCi H1
6r 6BZ2SU9N75sw59j vI FxzydmSM4mAS4i CgNx3/
7moheu8ALRacf hXZue49QcY7ZLnkSni Mn5R2dAzDon8cncyue4kf bl I gcNVJ f j wPF89
yvsgNpnTd9i ZKu+i a2hhuF/ sEnoi sM+7hM7Y9RAeUeGo=
Appendix B 735
- - - - - END CERTI FI CATE- - - - -
Bag At t r i but es
l ocal KeyI D: C6 49 0B C4 1C 3C 0F 9D D5 98 29 F1 2A 5D 7D D0 DA
48 83 1C
Key At t r i but es: <No At t r i but es>
- - - - - BEGI N RSA PRI VATE KEY- - - - -
Pr oc- Type: 4, ENCRYPTED
DEK- I nf o: DES- EDE3- CBC, A24CAD1C93DE946F
M8uXNZPI +J 675NFqEVWANl Anvwpaf WHgT0dCMVt 21zi Xl +7J 7bl aaf Lt zr OUbO0BGnb
pes+Gkr oUEt i Pt Cl 9GKqVVot I U5aeTowUi 0Bf 9SEF/
EgogD9gOdA3M7t I I L708kC4uI 7Yr OphJ J YK2j f Rl CMyMLgj geNoOt bJ CPZN8Uyq9GxV
l L8OX+VgoLYJ VvTf J oqvI 2n9I oswv4qYGsyc2wBt aTM3J NCZ3at l bPagcnf 5U29YGKo
+RXyFkt EhWhPr aFnEr U17Lt Kt aA1+3LsdFaOD6pL5sOkCj To9Szl sQxvl gFf OOI 18l g
u4I EI M6TqELph4MSYeVf U9UPbKqXE+ZUSWv2f 6i eaHl HONJ l vJ TnmXke35bBf 3NDpdO
AeKMLTuLwWr 30HA6nKwynXa0di l 0dEht t FOhF0A+s90UGHmRj G5Er hdGG9J Ci Z4w0R8
xt dRXPw2dy8et vb+dX00y586WUyt MNf eaw23HzSXsazQYpnUDsI XN1gYQmWeMnvp4x8
B2vboKF3Ht g1V0hUOp+BzBqpPzJ Vw8br 8t scuD0YRuoeht TOP5OJ +X73MJ Cf 7NopAaX
m7hokM6GQssd0nX7LAPJ aAM+CbFZ6LFi cl Y5Ds/
h5FCHPu6i VY3MXLP2yoEPoKSkTQssL3t l Weq6i YMX3sBDf l CGOONbOf t MKJ dGHdt oTO
PANVf 8wDyQpFmEFJ 2Oo10T2CpN3MY3qVdLRJ zSt vkU0+TgBoi H8ezM0WSNb/
ui Fl j Xq1qCbDeD2PuFj PKpAdl ht 2r Nag/
FWQovEBFCVRVKSQFbcr 5gt 8O9ePoO32LzCxQ0Hj 9Zow==
- - - - - END RSA PRI VATE KEY- - - - -
Note: The certificate and private-key is stored in the same file. If necessary, you
can copy the certificate and keys to different files.
Open the output file with a text editor and copy the certificate and key into
individual files.
The certificate starts with "-----BEGIN CERTIFICATE-----" and ends with "-----
END CERTIFICATE-----".
The key starts with "-----BEGIN RSA PRIVATE KEY-----" and ends with "-----
END RSA PRIVATE KEY-----".
Transforming a IIS 4.0 Exported Key
Follow these steps to convert the key to DER format:
1. In a HEX editor, open the key file (backup.key) containing the backed-
up .NET key.
2. Find first occurrence of the string private-key and search for 30 82
3. Cut and paste to a new file all of the saved selection from 30 82 onward.
(saved.key)
4. FTP the Certificate and Key file in binary mode in the system.
5. Run the following OpenSSL command to convert the key to DER format:
Openssl r sa - i n saved. key - i nf or mNET - out newkey. der - out f or m
DER
APPENDIX C
Warning and Safety Messages
This chapter lists the warning and safety messages that appear on the Application
Switch hardware and in instructions shipped with the Application Switch.
WarningThis equipment is to be installed and maintained by authorized and
trained service personnel only.
Attention Cet quipement doit tre install et maintenu
seulement par du personnel d'entretien.
WarningOnly trained and qualified personnel should be allowed to install or
replace this equipment.
Attention Tout installation ou remplacement de
l'quipement doit tre fait par du personnel
qualifi et comptent.
WarningRead the installation instructions carefully before you connect the
system to its power source.
Attention Avant de brancher le systme sur la source
d'alimentation, consulter les directives
d'installation.
SAFETY PERSONNEL WARNING
QUALIFIED PERSONNEL WARNING
INSTALLATION WARNING
WarningBefore getting down to work on equipment that is connected to live
power lines, remove jewelry items (including rings, necklaces, and watches).
Metal objects can heat up when connected to power and ground and can cause
serious burns or weld the metal object to the terminals.
Attention Avant d'accder cet qu ipement connect aux
lignes lectriques, arracher tout bijou (anneaux,
colliers et montres compris). Lorsqu'ils sont
branchs l'alimentation et relis la terre, les
objets mtalliques chauffent, ce qui peut
provoquer des blessures graves ou souder l'objet
mtallique aux bornes.
WarningDo not stack the chassis on any other equipment. If the chassis falls, it
can cause severe bodily injury and equipment damage.
Attention Ne placez pas ce chssis sur un autre appareil. En
cas de chute, il pourrait provoquer de graves
blessures corporelles et quipement dommage.
WarningThe plug-socket combination must be accessible at all times because it
serves as the main power disconnecting device.
Attention La combinaison de prise de courant doit tre
accessible tout moment parce qu'elle fait office
de systme principal de dconnexion.
WarningThe device is designed to work with TN power systems.
Attention Ce dispositif a t conu pour fonctionner avec
des systmes d'alimentation TN.
JEWELRY REMOVAL WARNING
STACKING THE CHASSIS WARNING
MAIN DISCONNECTING DEVICE
TN POWER WARNING
Appendix C 739
WarningWhen installing the unit, the ground connection must always be made
first and disconnected last.
Attention Lors de l'installation de l'appareil, la mise la
terre doit toujours tre connecte en premier et
dconnecte en dernier.
WarningThe equipment is intended to be grounded. Ensure that the host is
connected to earth ground during normal use.
Attention Cet quipement doit tre reli la terre. S'assurer
que l'appareil hte est reli la terre lors de
l'utilisation normale.
WarningThis product relies on the buildings installation for short-circuit
(overcurrent) protection. Ensure that a fuse or circuit breaker no larger than 120
VAC, 15 A U.S. (240 VAC, 16 A international) is used on the phase conductors
(all current-carrying conductors).
Attention Pour ce qui est de la protection contre les courts-
circuits (surtension), ce produit dpend de
l'installation lectrique du local. Vrifier qu'un
fusible ou qu'un disjoncteur de 120 V alt., 15 A
U.S. maximum (240 V alt., 16 A international) est
utilis sur les conducteurs de phase (conducteurs
de charge).
WarningUnplug the power cord before you work on a system that does not have
a power on/off switch.
Attention Avant de travailler sur un systme non quip
d'un commutateur marche-arrt, dbrancher le
cordon d'alimentation.
GROUND CONNECTION WARNING
GROUNDED EQUIPMENT WARNING
CIRCUIT BREAKER (15 A) WARNING
NO ON/OFF SWITCH WARNING
WarningCare must be given while/before connecting units to the supply circuit
so that the wiring is not overloaded.
Attention Veillez bien connecter les units au circuit
d'alimentation afin de ne pas surcharger les
connections.
WarningDo not work on the system or connect or disconnect cables during
periods of lightning activity. This product relies on the buildings installation for
short-circuit (overcurrent).
Attention Ne pas travailler sur le systme ni brancher ou
dbrancher les cbles pendant un orage. Pour ce
qui est de la protection contre les courts-circuits
(surtension), ce produit dpend de l'installation
lectrique du local.
WarningDo not touch the power supply when the power cord is connected. For
systems with a power switch, line voltages are present within the power supply
even when the power switch is off and the power cord is connected. For systems
without a power switch, line voltages are present within the power supply when
the power cord is connected.
Attention Ne pas toucher le bloc d'alimentation quand le
cordon d'alimentation est branch. Avec les
systmes munis d'un commutateur marche-arrt,
des tensions de ligne sont prsentes dans
l'alimentation quand le cordon est branch, mme
si le commutateur est l'arrt. Avec les systmes
sans commutateur marche-arrt, l'alimentation
est sous tension quand le cordon d'alimentation
est branch.
SUPPLY CIRCUIT WARNING
LIGHTNING ACTIVITY WARNING
POWER SUPPLY WARNING
CHASSIS WARNING RACK MOUNTING AND SERVICING
Appendix C 741
WarningTo prevent bodily injury when mounting or servicing this unit in a rack,
you must take special precautions to ensure that the system remains stable. The
following guidelines are provided to ensure your safety:
This unit should be mounted at the bottom of the rack if it
is the only unit in the rack.
When mounting this unit in a partially filled rack, load the
rack from the bottom to the top with the heaviest
component at the bottom of the rack.
If the rack is provided with stabilizing devices, install the
stabilizers before mounting or servicing the unit in the
rack.
AttentionPour viter toute blessure corporelle pendant les oprations de montage
ou de rparation de cette unit en casier, il convient de prendre des prcautions
spciales afin de maintenir la stabilit du systme. Les directives ci-dessous sont
destines assurer la protection du personnel:
Si cette unit constitue la seule unit monte en casier, elle
doit tre place dans le bas.
Si cette unit est monte dans un casier partiellement
rempli, charger le casier de bas en haut en plaant
l'lment le plus lourd dans le bas.
Si le casier est quip de dispositifs stabilisateurs, installer
les stabilisateurs avant de monter ou de rparer l'unit en
casier.
WarningUltimate disposal of this product should be handled according to all
national laws and regulations.
Attention La mise su rebut ou te recyclage de ce produit
sont gnralement soumis des lois et/ou
directives de respect de lenvironment.
Renseignez-vous auprs de lorganisme
comptent.
WarningThere is the danger of explosion if the battery (CR 2032) is replaced
incorrectly. Replace the battery only with the same or equivalent type
recommended by the manufacturer. Dispose of used batteries according to the
manufacturer's instructions.
PRODUCT DISPOSAL WARNING
BATTERY HANDLING/REPLACEMENT WARNING
Attention Danger d'explosion si la pile (batterie) (CR 2032)
n'est pas remplace correctement. Ne la
remplacer que par une pile (batterie) de type
quivalent, recommande par le fabricant. Jeter
les piles (batteries) usages conformment aux
instructions du fabricant.
CautionNever remove the cover on a power supply or any part that has the
following label attached:
Hazardous voltage, current, and energy levels are present inside any component
that has this label attached. There are no serviceable parts inside these
components. If you suspect a problem with one of these parts, contact system
Technical Support.
SAFETY LABEL CAUTION
!
APPENDIX D
SystemHealth Counters
This Appendix describes various system health parameters such as voltage, fan,
temperature, and disk space that are required to monitor the system status. Table
lists the system health counters along with their descriptions and reference values.
For more information on counters and the platforms supported, refer to the MAN
pages.
Health
Parameter
Type
Health Parameter
Name
Description Reference
Values
SNMP
Alarm
Support
Voltage CPU 0 Core
Voltage (Volts)
Measures the
processor core 0
voltage in volts
1.080 through
1.650 Volts
No
CPU 1 Core
Voltage (Volts)
Measures the
processor core 1
voltage in volts
1.080 through
1.650 Volts
No
Main 3.3 V Supply
Voltage
Measures the +3.3V
main power supply in
volts
2.970 through
3.630 Volts
Yes
Standby 3.3 V
Supply Voltage
Measures the 3.3V
standby power supply
in volts
2.970 through
3.630 Volts
Yes
+5.0 V Supply
Voltage
Measures the +5V
power supply in volts
4.500 through
5.500 Volts
No
-5.0 V Supply
Voltage
Measures the -5V
-5.500 through -
4.500 Volts
No
+12.0 V Supply
Voltage
Measures the +12V
10.800 through
13.200 Volts
No
-12.0 V Supply
Voltage
Measures the -12V
-13.200 through
-10.800 Volts
No
Battery Voltage
(Volts)
Measures the battery
voltage
Platform-
dependent
No
Fan CPU Fan 0 Speed
(RPM)
Measures the
processor fan 0 speed
in RPM
4000 through
6000 RPM. The
lower threshold
is 75% of the
minimum fan
speed (3000) for
SNMP alarms.
Yes
CPU Fan 1 Speed
(RPM)
Measures the
processor fan 1 speed
in RPM
4000 through
6000 RPM. The
lower threshold
is 75% of the
minimum fan
speed (3000) for
SNMP alarms.
Yes
System Fan Speed
(RPM)
Measures the system
fan speed in RPM
4000 through
6000 RPM. The
lower threshold
is 75% of the
minimum fan
speed (3000) for
SNMP alarms.
Yes
Temperature CPU 0
Temperature
(Celsius)
Measures the
processor 0
temperature in degree
celcius (
0
C)
User input Yes
CPU 1
Temperature
(Celsius
Measures the
processor 1
temperature in degree
celcius (
0
C)
User input Yes
Internal
Temperature
(Celsius
Measures the
hardware monitor
internal temperature
in degree celcius (
0
C)
User input Yes
Health
Parameter
Type
Health Parameter
Name
Values
SNMP
Alarm
Support
Appendix D 745
Disk Space /flash Size (MB) Measures /flash total
size in MB
-- No
/flash Used (MB) Measures /flash used
size in MB
-- No
/flash Available
(MB)
Measures /flash
available space in MB
-- No
/flash Used (%) Measures /flash used
space in percentage
User input Yes
/var Size (MB) Measures /var total
size in MB
-- No
/var Used (MB) Measures /var used
space in MB
-- No
/var Available
(MB)
Measures /var
available space in MB
-- No
/var Used (%) Measures /var used
space in percentage
User input Yes
Health
Parameter
Type
Health Parameter
Name
Values
SNMP
Alarm
Support
APPENDIX E
Introducing the Citrix NetScaler Hardware
Platforms
The Citrix NetScaler product line includes hardware platforms, with varying
capabilities and functionality, that range from the single-core processor 7000
platform to the high-capacity dual quad-core processor 17000 platform.
The physical hardware components for each platform are described in the
following sections as well as a summary of platform features.
Hardware Platforms
The hardware consists of the following platforms.
Citrix NetScaler 7000
Citrix NetScaler 9010 and 9010 FIPS
Citrix NetScaler 12000 and 12000-10G
Citrix NetScaler MPX 5500
Citrix NetScaler MPX 7500 and MPX 9500
Citrix NetScaler MPX 9700, MPX 10500, and MPX 12500
The Citrix NetScaler 7000 is a 1U appliance that ships with 1 single-core
processor and 1 gigabyte (GB) of memory. The following figure shows the front
panel of the 7000.
Citrix NetScaler 7000 Front Panel
The LCD display provides real-time information about the appliances state and
activity in sequential screens with real-time statistics, diagnostic information, and
active alerts. The display consists of two lines of 16 characters each, a neon
backlight, and a screen refresh rate of 3 seconds. For more information about the
LCD display, see Understanding the LCD Panel on page 771.
The 7000 has the following ports:
Six 10/100BASE-T copper Ethernet ports, named 1/1, 1/2, 1/3, 1/4, 1/5,
and 1/6. Port 1/1 is the upper-left port, port 1/2 is the port beneath it, and the
other 10/100BASE-T ports are named sequentially as you move from left to
right, top to bottom.
Two 10/100/1000BASE-T copper Ethernet ports, named 1/7 and 1/8. Port
1/7 is the upper-right port, and port 1/8 is the port beneath it.
Note: The network port numbers on all appliances consist of two
numbers separated by a forward slash. The first number is the port adapter
slot number. The second number is the interface port number. Ports on
appliances are numbered sequentially starting with 1.
One RS232 serial console port.
The following figure shows the back panel of the 7000.
LCD 10/100BASE-T
Ethernet Ports
10/100/1000BASE-T
Ethernet Ports
Console Port
Appendix E 749
Citrix NetScaler 7000 Back Panel
The following components are visible on the back panel of the 7000:
A removable hard disk drive that is used to store user data.
An appliance reset switch, which signals the 7000 to perform an orderly
shutdown after saving all data.
A removable compact flash that is used to store the operating system.
A power switch, which turns off power to the 7000 just as if you were to
unplug it.
A 250 watt, 110-240 volt power supply with fan.
Citrix NetScaler 9010 and 9010 FIPS
processor and 2 gigabytes (GB) of memory. The 9010 platform is available in
three models: the copper Ethernet version, the fiber SFP (Small Form Factor
Pluggable) version, and the FIPS (Federal Information Processing Standards)
version. The following figure shows the front panel of the 9010 model with
copper Ethernet ports.
Citrix NetScaler 9010 Front Panel with Copper Ethernet Ports
The following figure shows the front panel of the 9010 with SFP ports.
Hard Disk Drive
Reset Switch
Power Supply
Power Switch Compact Flash
CItrIx Systems

Console Port
Ethernet Ports
LCD
Citrix NetScaler 9010 Front Panel with SFP Ports
For all 9010 models, the LCD display provides real-time information about the
appliances state and activity in sequential screens with real-time statistics,
diagnostic information, and active alerts. The display consists of two lines of 16
characters each, a neon backlight, and a screen refresh rate of 3 seconds. For more
information about the LCD display, see Understanding the LCD Panel on page
771.
The 9010 models have the following ports:
Network ports
9010, copper Ethernet model. Four copper Ethernet 10/100/
1000BASE-T ports, numbered 1/1, 1/2, 1/3, and 1/4 from left to right.
9010, SFP model. Four SFP ports, numbered 1/1, 1/2, 1/3, and 1/4
from left to right.
When facing the bezel, the upper LEDs to the left of each optical SFP
port inset represent connectivity. They are lit and amber in color
when active. The lower LEDs represent throughput. They are lit and
green when active.
9010 FIPS model. Same as the 9010, non-FIPS model.
numbers separated by a forward slash. The first number is the port
adapter slot number. The second number is the interface port number.
Ports on appliances are numbered sequentially starting with 1.
The following figure shows the back panel of the 9010 models.
Note: The back panels of the three 9010 models are the same.
CItrIx Systems
Console Port
SFP Ports
LCD
Appendix E 751
The following components are visible on the back panel of the 9010 models:
A power switch, which turns off power to the 9010, just as if you were to
unplug both power supplies.
One 10/100BASE-T copper Ethernet port, numbered 0/1.
A non-maskable interrupt (NMI) button, which signals the 9010 to perform
an orderly shutdown after saving all files. You must use a pen, pencil, or
other pointed object to press this button, which is located inside a small
hole to prevent it being pressed accidentally.
A disable alarm button, which silences the alarm that the 9010 sounds when
it is receiving power from only one of its power supplies.
Press this button to stop the power alarm from sounding when you have
plugged the 9010 into only one power outlet or when one power supply is
malfunctioning and you want to continue operating the 9010 until it is
repaired.
Two 500 watt, 110-240 volt power supplies, each with two fans.
You plug separate power cords into the power supplies and connect them to
separate wall sockets. The 9010 functions properly with a single power
supply; the extra power supply serves as a backup.
Disable Alarm Button
Fans
Power Supply
Power Switch
Hard Disk Drive
10/100BASE-T Ethernet Port
NM Button
Compact Flash Drive
processor and 4 gigabytes (GB) of memory. The following figure shows the front
panel of the 10010.
Citrix NetScaler 10010 Front Panel
Four copper Ethernet 10/100/1000BASE-T ports, numbered 1/5, 1/6, 1/7,
and 1/8 from left to right.
Four SFP (Small Form Factor Pluggable) ports, numbered 1/1, 1/2, 1/3, and
1/4 from left to right.
When facing the bezel, the upper LEDs to the left of each optical SFP port
inset represent connectivity. They are lit and amber in color when active.
The lower LEDs represent throughput. They are lit and green when active.
The following figure shows the back panel of the 10010.
LCD
Console Port
SFP Ports 10/100/1000BASE-T
Ethernet Ports
Appendix E 753
One 10/100BASE-T copper Ethernet port, numbered 0/1.
A non-maskable interrupt (NMI) button, which signals the 10010 to
perform an orderly shutdown after saving all files. You must use a pen,
pencil, or other pointed object to press this button, which is located inside a
small hole to prevent it being pressed accidentally.
A disable alarm button, which silences the alarm that the 10010 sounds
when it is receiving power from only one of its power supplies.
repaired.
Fans
Power Supply
Power Switch
Hard Disk Drive
NM Button
Compact Flash Drive
Citrix NetScaler 12000 and 12000-10G
processors and 4 gigabytes (GB) of memory. The 12000 is a high-capacity, fault-
tolerant hardware platform intended for heavy use in data center environments.
The 12000 platform is available in four models: the fiber model, the copper
model, the mixed model, and the 10-G model. The following figure shows the
front panel of the 12000 fiber model.
Citrix NetScaler 12000 Fiber Front Panel
The fiber model has eight fiber SFP (Small Form Factor Pluggable) ports. The
copper model has eight copper SFP ports instead of eight fiber SFP ports, located
in the same places. The mixed model has four copper SFP ports located in the left
four positions and four fiber SFP ports located in the right four positions.
The following figure shows the front panel of the 12000-10G model.
Citrix 12000-10G Front Panel
Console Port
SFP Ports
LCD
Console Port
SFP Ports
LCD
10-Gigabit XFP Ports
Appendix E 755
Network ports
12000 Fiber. Eight fiber SFP ports, numbered 1/1, 1/2, 1/3, 1/4, 1/5,
1/6, 1/7, and 1/8 from left to right.
12000 Copper. Eight copper SFP ports, numbered 1/1, 1/2, 1/3, 1/4,
1/5, 1/6, 1/7, and 1/8 from left to right.
12000 Mixed. Four copper SFP ports, numbered 1/1, 1/2, 1/3, and 1/
4, and four fiber SFP ports, numbered 1/5, 1/6, 1/7, and 1/8 from left
to right.
12000-10G. Eight SFP ports, numbered 1/1, 1/2, 1/3, 1/4, 1/5, 1/6, 1/
7, and 1/8 from left to right, and two XFP (10-Gigabit Small Form
Factor Pluggable) ports, numbered 1/9 and 1/10.
When facing the bezel, the upper LEDs to the left of each optical SFP
port represent connectivity. They are lit and amber in color when
active. The lower LEDs represent throughput. They are lit and green
when active.
The following figure shows the back panel of all 12000 models.
One 10/100/1000BASE-T copper Ethernet port, numbered 0/1.
A non-maskable interrupt (NMI) button, which signals the 12000 to
A disable alarm button, which silences the alarm that the 12000 sounds
when it is receiving power from only one of its power supplies.
repaired.
The Citrix NetScaler MPX 5500 is a 1U appliance that ships with 1 dual-core
processor and 4 gigabytes (GB) of memory.
Fans
Power Supply
Power Switch
Hard Disk Drive
NM Button
Compact Flash Drive
Appendix E 757
The following figure shows the front panel of the MPX 5500.
Citrix NetScaler MPX 5500 Front Panel
Note: The LCD keypad is not available in this release.
The MPX 5500 has the following ports:
Two 10/100/1000Base-T copper Ethernet ports numbered 0/1 and 0/2 from
left to right. You can use these ports to connect directly to the appliance for
system administration functions.
Four 10/100/1000Base-T copper Ethernet ports numbered 1/1, 1/2, 1/3, and
1/4 from left to right.
The following figure shows the back panel of the MPX 5500.
Console Port
Management
Ports
Ethernet
Ports
LCD
LCD Keypad
Citrix NetScaler MPX 5500 Back Panel
The following components are visible on the back panel of the MPX 5500:
A 4 GB removable compact flash that is used to store the operating system.
A power switch, which turns off power to the MPX 5500, just as if you
were to unplug the power supply. Press the switch for five seconds to turn
off the power.
One USB port.
Note: The USB port is not available in this release.
A non-maskable interrupt (NMI) button, which signals the MPX 5500 to
pencil, or other pointed object to press this red button, which is located
inside a small hole to prevent it being pressed accidentally.
A single 300 watt, 110-240 volt power supply.
Citrix NetScaler MPX 7500 and MPX 9500
The Citrix NetScaler MPX 7500 and MPX 9500 are 1U appliances that ship with
1 quad-core processor and 8 gigabytes (GB) of memory.
The following figure shows the front panel of the MPX 7500 and MPX 9500.
Compact Flash Drive
USB Port
Power Switch
Power Supply
Hard Disk Drive
NM Button
Serial Number Label
Appendix E 759
Citrix NetScaler MPX 7500/9500 Front Panel
The MPX 7500 and MPX 9500 appliance has the following ports:
left to right. These ports are used to connect directly to the appliance for
Eight 10/100/1000Base-T copper Ethernet ports numbered 1/1, 1/2, 1/3,
and 1/4 on the first row from left to right, and 1/5, 1/6, 1/7, and 1/8 on the
second row from left to right.
The following figure shows the back panel of the MPX 7500 and MPX 9500.
Console Port
Management
Ports
Ethernet
Ports
LCD
LCD Keypad
Citrix NetScaler MPX 7500/9500 Back Panel
The following components are visible on the back panel of the MPX 7500 and
MPX 9500:
A power switch, which turns off power to the appliance, just as if you were
to unplug the power supply. Press the switch for five seconds to turn off the
power.
One USB port.
A non-maskable interrupt (NMI) button, which signals the appliance to
A disable alarm button. This button is functional only when the appliance
has two power supplies.
plugged the appliance into only one power outlet or when one power supply
is malfunctioning and you want to continue operating the appliance until it
is repaired.
A single 450 watt, 110-240 volt power supply. A second power supply is
optional.
Note: You can order the second power supply through a Cirix Sales
Representative.
Compact Flash Drive
USB Port
Disable Alarm
Button
Power Switch
Power Supply
(second optional)
Hard Disk Drive
NM Button
Serial Number Label
Appendix E 761
Citrix NetScaler MPX 9700, MPX 10500, and MPX
12500
The Citrix NetScaler MPX 9700, MPX 10500, and MPX 12500 are 2U
appliances that ship with 2 quad-core processors and 16 gigabytes (GB) of
memory.
The following figure shows the front panel of the MPX 9700, MPX 10500, and
MPX 12500.
Citrix NetScaler MPX 9700/10500/12500 Front Panel
The MPX 9700, MPX 10500, and MPX 12500 appliances have the following
ports:
left to right. These ports are used to connect directly to the appliance for
Eight Gigabit copper or fiber SFP ports numbered 1/1, 1/2, 1/3, and 1/4 on
the first row from left to right, and 1/5, 1/6, 1/7, and 1/8 on the second row
from left to right.
LCD Keypad
LCD
Management
Ports
Console Port
SFP Ports
Ethernet
Ports
Eight 10/100/1000Base-T copper Ethernet ports numbered 1/9, 1/10, 1/11,
and 1/12 on the third row from left to right, and 1/13, 1/14, 1/15, and 1/16
on the fourth row from left to right.
The following figure shows the back panel of the MPX 9700, MPX 10500, and
MPX 12500.
Citrix NetScaler MPX 9700/10500/12500 Back Panel
The following components are visible on the back panel of the MPX 9700, MPX
10500, and MPX 12500.
A power switch, which turns off power to the appliance, just as if you were
to unplug the power supply. Press the switch for five seconds to turn off the
power.
One USB port.
A non-maskable interrupt (NMI) button, which signals the appliance to
Power Switch
Serial Number Label
Disable Alarm
Button
USB Port
Hard Disk Drive
NM Button
(recessed)
Dual Power Supply
Compact Flash
Appendix E 763
A disable alarm button. This button is functional only when the appliance
has two power supplies.
plugged the appliance into only one power outlet or when one power supply
is malfunctioning and you want to continue operating the appliance until it
is repaired.
Two 450 watt, 110-240 volts power supplies.
The Citrix NetScaler MPX 15000 is a 2U appliance that ships with 2 dual-core
processors and 16 gigabytes (GB) of memory. The MPX 15000 is a high-capacity,
fault-tolerant hardware platform intended for heavy use in enterprise and service
provider environments. The following figure shows the front panel of the MPX
15000.
Citrix NetScaler MPX 15000 Front Panel
The appliance has the following ports:
One 10/100/1000BASE-T copper Ethernet port, numbered 0/1. This port is
used to connect directly to the appliance for system administration
functions.
LCD Console Port
XFP Ports
Ethernet Ports
Management Port
Two XFP (10-Gigabit Small Form Factor Pluggable) fiber optical ports,
numbered from left to right 1/1 and 1/2.
Eight 10/100/1000BASE-T copper Ethernet ports, numbered from upper
left to bottom right 1/3, 1/4, 1/5, 1/6, 1/7, 1/8, 1/9, and 1/10.
When facing the bezel, the upper LEDs to the left of each port represent
connectivity. They are lit and amber in color when active. The lower LEDs
represent throughput. They are lit and green when active.
The following components are visible on the back panel of the MPX 15000:
separate wall sockets. The MPX 15000 functions properly with a single
power supply; the extra power supply serves as a backup.
Fans
Power Supply
Hard Disk Drives
Compact Flash
NM Button
Appendix E 765
The Citrix NetScaler MPX 17000 is a 2U appliance that ships with 2 quad-core
processors and 32 gigabytes (GB) of memory. The MPX 17000 is a high-capacity,
fault-tolerant hardware platform intended for any high traffic, intensive
processing data center environment. The MPX 17000 is available in two models:
the Four Network Port model and the Ten Network Port model. The following
figure shows the front panel of the MPX 17000, Four Network Port model.
Citrix NetScaler MPX 17000 Four Network Port Model, Front Panel
Depending on the model, the appliance has the following ports:
One 10/100/1000BASE-T copper Ethernet port, numbered 0/1. This port is
used to connect directly to the appliance for system administration
functions.
Network Ports
MPX 17000 four network port model. Four XFP (10-Gigabit Small
Form Factor Pluggable) ports, numbered from upper left to bottom
right 1/1, 1/2, 1/3, and 1/4.
MPX 17000 ten network port model. Two XFP ports, numbered from
left to right 1/1 and 1/2 and eight 10/100/1000BASE-T Ethernet
ports, numbered from upper left to bottom right 1/3, 1/4, 1/5, 1/6, 1/7,
1/8, 1/9 and 1/10.
LCD Console Port
XFP Ports Management Port
When facing the bezel, the upper LEDs to the left of each port represent
connectivity. They are lit and amber in color when active. The lower LEDs
represent throughput. They are lit and green when active.
The following components are visible on the back of the MPX 17000:
One removable hard disk drive that is used to store user data.
separate wall sockets. The MPX 17000 functions properly with a single
power supply; the extra power supply serves as a backup.
Fans
Power Supply
Hard Disk Drives
Compact Flash
NM Button
Appendix E 767
Citrix PlatformSummary
The following table summarizes the specifications of each of the hardware
platforms.
Citrix PlatformSummary
7000 9010 10010 12000 MPX 5500 MPX 7500/
MPX 9500
MPX
15000
MPX
17000
Processor 1 single-
core
1 single-
core
1 single-
core
2 single-
cores
1 dual-
core
1 quad-
core
2 dual-
cores
2 quad-
cores
Memory 1 GB 2 GB 4 GB 4 GB 4 GB 8 GB 16 GB 32 GB
Number of
Power
Supplies
1 2 2 2 1 1 with
second
optional
2 2
Power Supply
input voltage
& frequency
100-240/
47-63Hz
100-240/
47-63Hz
100-240/
47-63Hz
100-
240/
47-63Hz
90-
264VAC
47-63 Hz
90-
264VAC
47-63 Hz
100-240/
47-63Hz
100-240/
47-63Hz
Maximum
Power
Consumption
250 W 500 W 500 W 500W 300 W 450 W 700W 700W
Weight (lbs.) 28 52 52 52 22 23 with
one power
supply
52 52
Height 1U 2U 2U 2U 1U 1U 2U 2U
Width EIA 310-
D
EIA 310-
D
EIA 310-
D
EIA
310-D
EIA 310-
D
EIA 310-
D
EIA 310-
D
EIA 310-
D
Depth 24 in/
61 cm
24 in/
61 cm
24 in/
61 cm
24 in/
61 cm
21.75 in/
55 cm
21.75 in/
55 cm
18.5 in/
47 cm
18.5 in/
47 cm
Operating
Temperature
(degree
celsius)
0-40 0-40 0-40 0-40 0-40 0-40 0-35 0-35
Humidity
range (non-
condensing)
5%-95% 5%-95% 5%-95% 5%-95% 5%-95% 5%-95% 5%-95% 5%-95%
Safety
Certifications
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
UL &
TUV-C
EMC &
Susceptibility
FCC
Class A
FCC
Class A
FCC
Class A
FCC
Class A
FCC
(Part 15
Class A),
DoC, CE,
VCCI,
CNS,
AN/NES
FCC (Part
15 Class
A), DoC,
CE,
VCCI,
CNS, AN/
NES
FCC
(Part 15
Class A),
DoC, CE,
VCCI,
CNS,
AN/NES
FCC
(Part 15
Class A),
DoC, CE,
VCCI,
CNS,
AN/NES
Compliance RoHS RoHS RoHS RoHS RoHS RoHS RoHS RoHS
APPENDIX F
Clearing the Configuration
This section provides instruction for clearing the configuration on your system.
You can clear your system configuration in different levels as described below:
Basic Configuration: When the clearing of configuration is done at this level, all
configurations except the following are cleared:
NSIP, MIP(s), and SNIP(s)
Network settings (Default Gateway, VLAN, RHI, NTP, and DNS settings.)
HA node definitions
Feature and mode settings
Default administrator password (nsroot)
Extended Configuration: When the clearing of configuration is done at this
level, all configurations except the following are cleared:
NSIP, MIP(s), and SNIP(s)
Network settings (Default Gateway, VLAN, RHI, NTP, and DNS settings.)
HA node definitions
Feature and mode settings are reverted to their default values.
Full Configuration: When the clearing of configuration is done at this level, all
settings are reset to their factory default values. However, the NSIP and default
gateway are not changed. This is done to ensure that the system does not lose
network connectivity.
In the following example, you clear the basic configuration in your system:
To clear configuration
1. In the left pane, expand System, then click Diagnostics. The Diagnostics
2. Under Configuration click Clear Configuration. The Clear
Configuration dialog box appears.
3. Under Configuration Level, select a clear configuration option. For
example, basic.
4. Click Run.
The Clear Configuration dialog box is shown in the following figure:
Clearing the configuration
APPENDIX G
Understanding the LCD Panel
The LCD display on the front of every appliance displays messages about the
current operating status of the appliance. These messages communicate whether
your appliance has started properly and is operating normally. If the appliance is
not operating normally, the LCD will display troubleshooting messages.
The LCD is located on the front panel of the appliance, as shown in the following
figure.
LCD on the Front Panel
The LCD displays real-time statistics, diagnostic information, and active alerts.
The dimensions of the LCD limit the display to two lines of 16 characters each
causing the displayed information to flow through a sequence of screens. Each
screen shows information about a specific function.
The LCD has a neon backlight. Normally, the backlight glows steadily. When
there is an active alert, it blinks rapidly. If the alert information exceeds the LCD
screen size, the backlight blinks at the beginning of each display screen. When
the appliance shuts down, the backlight remains on for one minute, and then
automatically turns off.
The display information on the LCD can be divided into two categories:
Special Display Screens. Information displayed when your appliance is
not in active mode but is turning on, starting up, or out of service.
Regular Display Screens. Information displayed when the appliance is in
active mode.
Special Display Screens
The special display screens display general information about your appliance.
There are three types of special display screens on the LCD display.
Booting Screen
The booting screen is displayed immediately after the appliance is turned on. The
first line displays the hardware platform, as shown in the following figure.
LCD Booting Screen
The newer MPX platforms will display NSMPX-<platform number>in the first
line. For example, the 5500 model will display NSMPX-5500.
Startup Screen
The startup screen is displayed for a few seconds after the appliance successfully
starts. The first line displays the hardware platform and the second line displays
the operating system version and build number, as shown in the following figure.
LCD Startup Screen
Appendix G 773
Out-of-Service Screen
The out-of-service screen is displayed when the appliance has undergone a
controlled shutdown, as shown in the following figure.
LCD Out-of-Service Screen
Regular Display Screens
The regular display screens show configuration information, real-time alerts,
HTTP information, network traffic information, CPU load information, and port
information for your appliance. There are six types of special display screens on
the LCD display.
Configuration Screen
The first line displays the status and time. STA indicates that the appliance is in
standalone mode, PRI indicates that the appliance is a primary node in a high
availability (HA) pair, and SEC indicates that the appliance is a secondary node in
an HA pair. Appliance uptime is displayed in HH: MMformat. The second line
displays the IP address of the appliance, as shown in the following figure.
LCD Configuration Screen
Alert Screen
The display changes depending on whether the alert is known or unknown. The
first line displays the status of the appliance as STA, PRI , or SEC.
STA indicates that the appliance is in standalone mode, PRI indicates that the
appliance is a primary node in a high availability (HA) pair, and SEC indicates
that the appliance is a secondary node in an HA pair.
The second line displays the IP address of the appliance, as shown in the
following figures.
LCD Known Alert Screen
LCD Unknown Alert Screen
HTTP Statistics Screen
The first line displays the rate of HTTP GETS per second. The second line
displays the rate of HTTP POSTS per second, as shown in the following figure.
LCD HTTP Statistics Screen
Appendix G 775
Network Traffic Statistics Screen
The first line displays the rate of data being received in megabits per second. The
second line displays the rate of data being transmitted in megabits per second, as
LCD Network Traffic Statistics Screen
CPU Load, Memory, and Connections Screen
The first line displays CPU utilization and memory utilization as a percentage.
The second line displays the ratio of the number of server connections to the
number of client connections.
Note: If the number of server or client connections exceeds 99,999, then the
number is displayed in thousands with a suffix of K.
LCD CPU Load, Memory, and Connections Screen
Port Information Screen
The S row ports display speed, flow control, and duplex information. The R row
ports display the megabits per second received on the interface. The first port in
both rows is the management port.
Port Information for an 8-port Appliance
Port Information for a 10-port Appliance
The following table defines the various abbreviations and symbols that display in
the S row of the port information screen.
Port Abbreviations and Symbols for S Row
S Row
Abbreviation/
Symbol
Description
Indicates a speed rate of 10 megabits per second, full duplex mode,
and flow control OFF.
Indicates a speed rate of 100 megabits per second, full duplex mode,
Indicates a speed rate of 1 gigabit per second, full duplex mode, and
flow control OFF.
Indicates a speed rate of 10 gigabits per second, full duplex mode,
Indicates a disconnected port.
Note: The R row does not display an abbreviation or symbol for a
disconnected port.
F G f E g T S
R
T G
E
F
G
T
Appendix G 777
The following table defines the various abbreviations and symbols that display in
the R row of the port information screen.
Indicates receive flow control regardless of speed rate or duplex
mode.
Indicates transmit flow control regardless of speed rate or duplex
mode.
Indicates receive and transmit flow control regardless of speed or
duplex mode
Indicates a speed rate of 10 megabits per second, half duplex mode,
Indicates a speed rate of 100 megabits per second, half duplex mode,
Indicates a speed rate of 1 gigabit per second, half duplex mode, and
flow control OFF
Port Abbreviations and Symbols for R row
R Row
Abbreviation/
Symbol
Description
Indicates the port is disabled.
Indicates receive speed is approximately 10% of line speed.
Indicates receive speed is 50% of line speed.
S Row
Abbreviation/
Symbol
Description
f
g
#
Port Abbreviations and Symbols for R row
R Row
Abbreviation/
Symbol
Description
APPENDIX H
Configuring Secure Access
By default, management access and communication between two systems are not
secure.This implies that the following are not secure: propagation and
synchronization between two nodes in an HA pair, MEP propagation between
sites in a GSLB setup, and access to the Configuration Utility using a Web
browser, etc. To secure these communication modes , you can encrypt the traffic
using the system's SSL capabilities.
To enable secure communications between two nodes, execute the set rpcNode
command and configure the "secure" option to YES. Secure communications
between two nodes are supported by a set of internally created services.
The secure internal services are:
nsrpcs
This service provides transparent SSL offload on port 3008 with the clear text
port being 3010 and secures management access and command synchronization,
to the system. It is created for the NSIP address and every management IP address
(MIP and SNIP). Therefore, when a management IP address such as MIP or SNIP
is added, a corresponding nsrpcs service is also added.
nshttps
This service provides transparent SSL offload on port 443 with the clear text port
being 80 and secures access to the Configuration Utility and Statistical Utility. It
is created for the NSIP and all SNIPs or an MIPs. Therefore, when an SNIP / MIP
is added, a corresponding nshttps service is also added. Once this service is
enabled, the user can access the Configuration Utility and Statistical Utility at
URL: https://<NSIP/MIP/SNIP>.
nskrpcs
This service secures command propagation in a HA setup and communication
between GSLB sites using MEP. Therefore, when a GSLB local site is added, a
corresponding nskrpcs service is created. The nskrpcs corresponding to the NSIP,
nskrpcs-127.0.0.1-3009, is preconfigured on the system.
The following table lists the system entities and their corresponding internal
services:
You cannot delete internal services and their corresponding servers. They are
automatically deleted when the corresponding system entity is deleted. For
example, when you delete an MIP or a SNIP, the internal service corresponding to
it is deleted. In addition, you cannot change the parameters of an internal service,
but you can change the SSL-related parameters. Finally, you cannot bind
monitors or vservers to the internal services. If you attempt any of these tasks, the
system responds with an "Operation not permitted" error.
To view the internal services, run the show service command.
> sh ser vi ce - i nt er nal
1) nsr pcs- 127. 0. 0. 1- 3008 ( 10. 102. 29. 50: 3008) - SSL_TCP
St at e: DOWN[ Cer t key not bound] Ser ver Name: ns- i nt er nal -
127. 0. 0. 1
Cl ear Text Por t : 3010
Max Conn: 0 Max Req: 0 Max Bandwi dt h: 0 kbi t s
Use Sour ce I P: YES
Cl i ent Keepal i ve( CKA) : NO
Access Down Ser vi ce: NO
TCP Buf f er i ng( TCPB) : NO
HTTP Compr essi on( CMP) : NO
I dl e t i meout : Cl i ent : 9000 sec Ser ver : 9000 sec
Cl i ent I P: DI SABLED
Ser ver I D : 0 Moni t or Thr eshol d : 0
2) nsht t ps- 127. 0. 0. 1- 443 ( 10. 102. 29. 50: 443) - SSL
Entity Internal Service
NSIP nsrpcs
nskrpcs
nshttps
MIP nsrpcs
nshttps
SNIP nsrpcs
nshttps
GSLB local Site nskrpcs
Appendix H 781
St at e: DOWN[ Cer t key not bound] Ser ver Name: ns- i nt er nal -
127. 0. 0. 1
Cl ear Text Por t : 80
Use Sour ce I P: YES
3) nskr pcs- 127. 0. 0. 1- 3009 ( 10. 102. 29. 50: 3009) - RPCSVRS
St at e: UP Ser ver Name: ns- i nt er nal - 127. 0. 0. 1
Use Sour ce I P: NO
Done
As mentioned in the previous section, to enable security, you need to execute the
set rpcNode command. When this command is executed, the communications are
handled by the secure services.
This is illustrated by the following sample configuration. In this example, secure
communication is enabled for a system with NSIP 10.102.29.50 and the
password, is set to PASSWORD.
> set r pcNode 10. 102. 29. 50 - secur e YES
Done
> sh r pcNode
1) I PAddr ess: 10. 102. 29. 50 Passwor d: . . ee0e237340e81007
Ret r y: 1 Sr cI P: 10. 102. 29. 50
Secur e: YES
Done
Note: In an HA setup, the secure mode can be enabled for both nodes from a
single node.
Configuring SSL Parameters for Internal Services
The internal services support basic SSL configurations such as binding
certificates and changing ciphers. As with any SSL service, the internal services
have a default certificate key, ns-server-certificate, bound to them. Once a
certificate key with this name is added to the system, it is automatically bound to
all the internal services. When new internal services are added, the default
certificate key pair is bound to them. The ns-server-certificate certificate key
reserved and cannot be deleted.
You can bind a certkey of your choice (or the default certkey) with different
certificate and key files. However, you cannot delete the default certkey; you can
only update it using the "update certkey" command.
On a fresh system, the default certificate key is added when the system starts up.
However, for a system that is upgraded, you need to execute the add ssl certkey
command to create it. Once created, the certificate key is automatically bound to
the internal services.
This is illustrated in the following sample configuration:
1. Run the sh ssl service command to verify the ciphers bound to the internal
service, nsrpcs.
> sh ssl ser vi ce nsr pcs - 127. 0. 0. 1 - 3008
Advanced SSL conf i gur at i on f or Fr ont - end SSL Ser vi ce nsr pcs-
127. 0. 0. 1- 3008:
DH: DI SABLED
Ephemer al RSA: ENABLED Ref r esh Count : 0
Sessi on Reuse: ENABLED Ti meout : 120 seconds
Ci pher Redi r ect : DI SABLED
SSLv2 Redi r ect : DI SABLED
Cl i ent Aut h: DI SABLED
SSL Redi r ect : DI SABLED
Non FI PS Ci pher s: DI SABLED
SSLv2: DI SABLED SSLv3: ENABLED TLSv1: ENABLED
Appendix H 783
1) Ci pher Name: DEFAULT
Descr i pt i on: Pr edef i ned Ci pher Al i as
Done
2. Run the add ssl certkey command to add the default certificate.
> add ssl cer t key ns- ser ver - cer t i f i cat e - cer t ns- ser ver . cer t - key
ns- ser ver . key
Done
Note: You need to bind the certificate to the services if the certificate is not ns-
server-certificate.
3. Run the sh ssl service command to verify if the default certificate is bound
to the internal service, nsrpcs.
> sh ssl ser vi ce nsr pcs- 127. 0. 0. 1- 3008
Advanced SSL conf i gur at i on f or Fr ont - end SSL Ser vi ce nsr pcs-
127. 0. 0. 1- 3008:
DH: DI SABLED
Ephemer al RSA: ENABLED Ref r esh Count : 0
Sessi on Reuse: ENABLED Ti meout : 120 seconds
Ci pher Redi r ect : DI SABLED
SSLv2 Redi r ect : DI SABLED
Cl i ent Aut h: DI SABLED
SSL Redi r ect : DI SABLED
Non FI PS Ci pher s: DI SABLED
SSLv2: DI SABLED SSLv3: ENABLED TLSv1: ENABLED
1) Cer t Key Name: ns- ser ver - cer t i f i cat e Ser ver Cer t i f i cat e
1) Ci pher Name: DEFAULT
Descr i pt i on: Pr edef i ned Ci pher Al i as
Done
As mentioned earlier, the internal services are SSL services. They support all the
configuration tasks that other SSL services support. For details, refer to the
"Secure Sockets Layer (SSL) Acceleration" chapter in Volume 1 of the ICG.
Note: While connecting to either the Configuration Utility or the Statistical
Utility using the NSIP or MIP in the secure mode, a server certificate-related
warning appears twice.
APPENDIX I
FIPS Approved Algorithms and Ciphers
The FIPS approved algorithms are:
Key-Exchange algorithms
RSA
Cipher algorithms
AES
DES
3ES
Note: RC4 (ARC4) is not a FIPS approved algorithm, and will be disabled on
an SSL virtual server, if a FIPS certificate-key pair is bound to it.
SSL virtual server is marked UP only when default ciphers (FIPS) are configured.
To enable other ciphers on an SSL virtual server, use the following command:
set ssl Vser ver [ - nonf i psci pher ( ENABLE| DI SABLE) ]
The following are the FIPS approved ciphers supported by the system
SSL3-DES-CBC3-SHA
SSL3-DES-CBC-SHA
TLS1-AES-256-CBC-SHA
TLS1-AES-128-CBC-SHA
SSL3-RC4-SHA is the only Non-FIPS approved cipher supported by the system.
You can create cipher groups of FIPS approved ciphers and SSL3-RC4-SHA only
APPENDIX J
Resetting a Locked HSM
As mentioned in the previous section, the HSM is locked after three unsuccessful
login attempts. This is a security measure that is aimed at preventing
unauthorized access attempts and changes to the HSM settings. This implies that
once the card gets locked, you will not be allowed to log on to the HSM and alter
its configuration. Moreover, the HSM will cease to be operational.
To avoid this situation, you are strongly advised to follow these directions:
1. Use the save configuration command to save the configuration
after initializing the HSM.
2. Store the passwords in a secure location.
3. Store the super user password in a secure location. You will need it to
initialize the HSM. Moreover, you need to specify this password as the old
SO password when reinitializing the HSM.
Despite these precautions, if your HSM gets locked, you need to reset it to use it
again. Use the reset fips command to reset the HSM. This command clears
the HSM and resets the SO password and the User passwords to their default
values, i.e., sopin123 and userpin123 respectively.
The usage of the command is as follows:
r eset f i ps
WarningDo not use the command as an alternative to the set fips -
initHSM command, or when you have forgotten the passwords.
This commend must be used only on a locked HSM.
After executing the reset fips command, use the set fips -initHSM
command to change the default passwords. Use the save configuration
command to save the running configuration.
In the following example, the HSM gets locked after three unsuccessful login
attempts. The reset fips command is then used to reset the card. Finally, the
set fips -initHSM command is used to change the default SO and User
passwords. This change is saved using the save configuration command.
> set f i ps - i ni t HSM Level - 2 newsopi n123 newsopi n123 newuser pi n123 -
hsmLabel NSFI PS
Thi s command wi l l er ase al l dat a on t he FI PS car d. You must save t he
conf i gur at i on ( saveconf i g) af t er execut i ng t hi s command. Do you
want t o cont i nue?( Y/ N) y
ERROR: I nt er nal Er r or
> set f i ps - i ni t HSM Level - 2 newsopi n1234 newsopi n1234 newuser pi n123
- hsmLabel NSFI PS
ERROR: I nt er nal Er r or
> set f i ps - i ni t HSM Level - 2 newsopi n12345 newsopi n12345
newuser pi n12345 - hsmLabel NSFI PS
ERROR: FI PS car d l ocked due t o t hr ee unsuccessf ul l ogi n at t empt s
> r eset f i ps
Done
> set f i ps - i ni t HSM Level - 2 f i pssopi n123 sopi n123 f i psuser pi n123 -
hsmLabel NSFI PS
Done
> saveconf i g
Net Scal er saved t he conf i gur at i on
Done
>
INDEX
Index
A
Access Gateway
alerts 5
accessdown on services
enabling, 209
ACLs
applying, 102
configuring, 95
managing, 102
modifying, 104
action
respondwith 708
actions
modifying 671
URL Rewriting 671
removing 671
URL Rewriting 671
SSL 401
actions, content filtering 508
active standby mode
concepts, 602
add, HTTP DoS 531
add, IP address 551, 583
add, service 532
adding
name server, 290
static ARP entries, 54
adding IPv6
addresses, 648
vserver, 650
address resolution protocol (ARP)
controlling, 49
advantages, SYN cookies 519
advertising
networks, 618
advertising routes
BGP, 614
OSPF, 609
RIP, 604
alerts
Knowledge Center 5
anycast
IPv6 address types, 645
Apache format, log files 555, 564
applying
ACLs, 102
applying rules
classify frames, 82
architecture
load balancing, 112
argument string, log format 562
ARP entries
viewing properties, 56
assigning
service weights, 184
audit log, parameters 568
audit policy, global binding 572
audit server action, configuring 571
audit server executable, options 577
audit server files, installing 572
audit server logging
deployment scenario 586
installing on Linux 574
audit server logging, configuring 568
audit server logging, how it works 567
audit server logging, starting 584
audit server logging, stopping 584
audit server logging, systemrequirements 572
audit server policy, configuring 571
auditing 567
audserver
command 577
B
backup persistence
configuring, 178
backup router
configuring, 625
backup vserver
configuring, 339
bandwidth-based spillover
configuring, 190
base threshold 522
basic configuration
load balancing, 113, 114
basic content switching
configuring, 319
basic load balancing setup
configuring, 114
basic network configuration
concepts, 41
basic SSL offloading
configuring virtual server 354
BGP
advertising routes, 614
disabling, 614
enabling, 613
using, 612
viewing settings, 615
BGP instance
creating, 614
modifying, 615
bind policy, priority queuing 528
bind, HTTP DoS policy 532
bind, monitor 532
binding
HTTP services 356
metrics to metric tables, 255
monitors to services, 225
URL Rewrite policies 665
vserver to work load manager, 260
binding policies
vservers, 325
binding to channel
network interface, 74
binding to service
monitors, 225
binding to service group
IP addresses, 268
monitor, 269
binding to VLANs
IP address, 90
network interfaces, 90
binding to vserver
service group, 267
services, 121
bridge table
configuring, 107
modifying, 107
verifying, 108
viewing statistics, 109
buffer size
configure 539
TCP buffering 460
built-in policies
compression 478
C
cache redirection
configuring on services, 222
configuring, 197
content switching vserver, 344
calculating
response time for monitors, 146
call ID hash method
configuring, 156
case sensitivity
setting, 335, 338
certificate authority
obtaining certificate 361
changing ACL
source IP and destination port, 598
source IP, 595
changing source IP
ACL, 595
changing source IP and destination port
ACL, 598
channel
configuring manually, 73
modifying, 75
unbinding a network interface, 76
checklist, audit server logging 585
checklist, web server logging 565
Citrix NetScaler
9010 749, 758
Citrix NetScaler against failure
protecting, 339
Citrix Netscaler system
IPv6, 646
neighbor discovery, 652
Citrix Presentation Server component
monitoring, 246
Index 791
classify frames
applying rules, 82
egress rules, 83
ingress rules, 82
classifying
clearing
network interface statistics, 71
clearing ACLs
extended, 103
simple, 98
CLI
web server logging 538
client IP address
insertion, 213
client keep-alive
basic topology 451
configuration 451
configure service 453, 454
configured parameters 452
configuring, 212
definition 449
disable mode 453
enable mode 453
entities configured 452
entity model 450
how it works 450
client traffic
managing, 195
command, audit server 577
comparing
IPv4 and IPv6 headers, 642
compressible content 462
compression
basic topology 465
configuration steps 465
configure service parameters 466
configured entities 465
definition 461
enable feature 466
enabling on service, 210
entity model 463
how it works 462
supported MIME types 462
compression actions
built-in 475
COMPRESS 474
create 475
definition 474
DEFLATE 474
DELTA 474
GZIP 474
NOCOMPRESS 474
compression policies
built-in 478
configured parameters 479, 480
user-defined 479
compression policy
create 479
definition 478
concepts
active standby mode, 602
BGP, 612
connection failover, 191
dynamic routing, 602
ICMP for IPv6, 641
IPv6 addresses scheme, 642
IPv6, 639
link aggregation, 73
link load balancing, 619
load balancing, 111
neighbor discovery of IPv6, 645
NSSA support, 612
OSPF, 607
RNAT, 591
route health injection, 616
VLAN support, 654
configuration file, sample 585
configuration file, verifying 584
configuration, verifying 551
configure
buffer size 539
content filtering 509
logging parameters 538
configure audit server
server computer 578
configure, audit server action 571
configure, audit server logging 568
configure, audit server policy 571
configure, DoS protection 531
configure, global audit server parameters 570
configure, priority queuing 526
configure, surge protection 521
configure, web server logging 546
Configuring 386, 387
basic High Availability 9
configuring
ACL based RNAT, 595
ACLs, 95
backup vserver, 339
basic content switching, 319
basic load balancing setup, 114
BGP, 614
body insertion 692
bridge tables, 107
content switching, 317
HA command propagation 18
HA dead Intervals 16
HA hello Intervals 16
HA synchronization 17
load balancing setup, 323
metrics, 253
OSPF, 608
packet forwarding modes, 56
persistence, 171
postbody files 695
prebody files 694
rewrite actions 663
RIP, 604
RNAT, 293
route maps, 616
services for load balancing, 206
spillover, 341
SSL 387, 394, 395, 396, 398, 399
static ARP, 53
systemto advertise host routes, 614
URL for redirection, 342
URL Rewriting 662
VLANs, 81
VMAC, 95
configuring ACLs
extended, 100
simple, 96
configuring BGP
HA setup active-standby mode, 616
configuring channel
link aggregate channel protocol (LACP), 78
manually, 73
configuring connection failover
high availability, 193
configuring content switching
how content switching works, 317
configuring IP address
system-owned, 41
types, 42
configuring load balancing
deployment scenario, 654
SASP, 257
configuring load balancing methods
call ID hash method, 156
custom load method, 167
destination IP hash method, 154
domain hash method, 154
hash methods, 151
least bandwidth method, 156
least connection method, 134
least packets method, 160
least response time method, 141
LRTM using monitors, 146
round robin method, 139
source IP destination IP hash method, 155
source IP hash method, 155
source IP source port hash method, 155
token method, 164
URL hash method, 153
weighted round robin, 140
configuring metrics
load assessments, 253
configuring monitors
inline, 247
load, 252
user, 248
configuring persistence
backup persistence, 178
vserver groups, 179
configuring persistence types
cookie based persistence, 174
destination IP persistence, 177
rule based persistence, 175
Server-ID based persistence, 177
source and destination IP based persistence, 178
Source IP persistence, 173
SSL session IDs persistence, 175
URL passive, 176
configuring RNAT
configuring router
backup, 625
configuring spillover
bandwidth-based spillover, 190
connection-based spillover, 189
dynamic spillover, 190
Index 793
configuring VLANs
802.1q tagging, 89
HA setup, 85
multiple subnets, 87
single subnet, 85
untagged 88
configuring VMAC 22
connection failover
concepts, 191
configuring, 191, 193
disabling, 194
connection-based spillover
configuring, 189
connections
proxying, 62
content filter policy, creating 510
content filter policy, globally binding 511
content filter policy, removing 511
enabling 509
content filtering, actions 508
content filtering, configuring 509
content filtering, disabling 510
content filtering, how it works 508
content switching
configuring, 317
enabling, 321
topology, 320
content switching configuration
verifying, 327
content switching policies
creating, 323
modifying, 331
removing, 334
viewing, 328
content switching policy
managing, 331
content switching setup
customizing, 334
content switching vserver
enabling and disabling, 330
content switching vservers
creating, 322
removing, 330
unbinding content switching policies, 329
content switching, DoS protection 530
controlling
address resolution protocol (ARP), 49
PING response, 50
route learning, 606
cookie based persistence
configuring, 174
create policies
compression 479
create policy, priority queuing 527
create, compression actions 475
create, content filter policy 510
create, filters 579
create, rules 508
creating
content switching policies, 323
content switching vservers, 322
filter action 510
filter actions 687
filter policies 689
HTTP based services 354
IPv6 routes, 651
link aggregate channels, 73
metric tables, 254
monitors, 224
range of vservers and services, 264
rewrite policies 664
servers, 119
service groups, 266
services, 116
SSL virtual server 355
VLANs, 84
vservers, 120
work load manager, 259
creating ACLs
extended, 100
simple, 96
creating IP address
GSLB site, 47
mapped, 46
NetScaler system, 42
subnet, 44
virtual server, 46
CRL
configuring 386
CS vserver state dependency on the state of target LB
vservers
setting, 338
custom format, log files 555, 560
custom load method
configuring, 167
CustomLog Format
Define 560
Defining Manually 561
Time Format Definition 563
custom log format, defining 560
customizing
content switching setup, 334
load balancing configuration, 131
monitors, 247
customizing, W3C format 556
D
default buffer size
default log filter, defining 546
default settings, log properties 550
default weights, priority queuing 528
define 548
define, customlog format 560
define, filters 579
define, log properties 580
defining
log properties 548
defining log filter
virtual servers 548
delayed cleanup of vserver connections
enabling, 345
Denial of Service 517
deployment scenario
configuring load balancing, 654
load balancing DNS servers, 285
load balancing domain-name based services, 287
load balancing FTP servers, 282
load balancing in direct server return mode, 295
load balancing in inline mode, 309
load balancing in one-arm mode, 299, 307
load balancing SIP servers, 292
load balancing, 295
deployment scenario, audit server logging 586
deployment scenarios
URL Rewriting 673
describing
spillover parameters, 188, 341
destination IP
routing persistence, 620
destination IP address
selecting, 63
destination IP based persistence
configuring, 177
destination IP hash method
configuring, 154
direct server return mode
configuring, 295
directing requests
priority based, 198
Web page, 199, 207
disable feature
compression 467
disable mode
client keep-alive 453
TCP buffering 459
disable surge protection, service 522
disable, content filtering 510
disable, surge protection 521
disabling
BGP, 614
connection failover, 194
discovered neighbors
viewing, 652
DNS servers
load balancing, 285
monitoring, 287
DNS service
monitoring, 242
domain hash method
configuring, 154
domain-name based service
load balancing, 287
DoS protection, configuring 531
DoS protection, content switching 530
DoS protection, memory 530
DoS protection, performance 530
DoS protection, priority queuing 530
DoS protection, SSL 530
DoS protection, surge protection 530
downstateflush
enabling on vserver, 200
dynamic routing
concepts, 602
dynamic routing protocols
viewing routes, 619
dynamic spillover
configuring, 190
E
egress rules
applying, 83
enable
responder 708
Index 795
enable feature
compression 466
enable mode
client keep-alive 453
TCP buffering 459
enable, HTTP DoS 531
enable, priority queuing 526
enable, surge protection 521
enabling
accessdown on services, 209
BGP, 613
delayed cleanup of vserver connections, 345
HTML Injection 686
load balancing, 115
OSPF, 608
RHI, 617
RIP, 603
SNIP mode, 45
URL Rewriting 662
use source IP address, 216
enabling and disabling
content switching vserver, 330
dynamic routing, 603
extended ACLs, 103
IP addresses 52
IPv6, 647
layer 2 mode, 57
layer 3 mode, 58
MBF mode, 59
monitors, 229
path MTU behavior, 633
servers, 126
service group, 274
services, 128
use source IP mode (USIP), 64
vservers, 130
enabling BGP
non-NSIP network, 613
enabling downstateflush
services, 208
vservers, 200
enabling on service
compression, 210
TCP buffering, 210
entity model
entry time-out
session, 621
event
undefined 709
extended ACLs
clearing, 103
configuring, 100
creating, 100
removing, 102
resetting priorities, 104
verifying, 106
F
f 583
filter
content 707
filter action
creating 510
filter policies
binding 690
FilterName 580
Filters
Creating 547, 579
Defining 546, 579
filters, creating 579
filters, defining 579
FIS 30
FIS, unbind interfaces 32
FIS,binding interfaces 31
FIS,remove 33
FIS,unbinding interfaces 33
FIS,verify configuration 32
force HA failover 20
force HA synchronization 18
forwarding
packets, 83
FTP monitors
configuring, 284
FTP servers
load balancing, 282
FTP service
monitoring, 235
G
global audit server parameters, configuring 570
global binding, audit policy 572
global binding, content filter policy 511
GSLB site IP address
creating, 47
H
HA setup
configuring VLANs, 85
HA setup active standby mode
OSPF, 612
HA setup active-standby mode
configuring BGP, 616
hash methods
configuring, 151
High Availability
adding node 10
basic configuration 9
configuring command propagation 18
configuring state of a node 37
configuring synchronization 17
configuring VMAC 22
dead Intervals 16
disabling a node 13, 14
disabling HA monitor 11
enabling a node 15
FIS 30
force failover 20
force synchronization 18
health checks 37
hello Intervals 16
INC 27
modifying configuration 13
removing a node 15
requirements 8
route monitors 34
High availability
binding route monitor 34
high availability
configuring connection failover, 193
High Availabilty
troubleshooting 39
High Availabity
troubleshooting 37
host header
modifying, 657
how content switching works
configuring content switching, 317
how it works
HTML Injection 685
SSL 351
URL Rewriting 661
HTML Injecion
example
mask server type 677
HTML Injection
body insertion 697
configuring for commonly used applications 700
configuring header insertion 686
example 674, 675, 676, 677, 678, 679,
681, 682
delete header 675
home page redirection 682
inserting client IP address 674
keyword redirection 681
migrate rewrite module rules 679
query redirection 681
redirect URLs 678
tagging connections 676
internal variables 692
HTTP DoS policy, binding 532
HTTP DoS, adding 531
HTTP DoS, enabling 531
HTTP redirection
configuring, 201
I
ICMP for IPv6
concepts, 641
idle client connections
setting time-out, 205, 219
setting timeout, 348
idle server connections
setting time-out, 220
implementing
RNAT with link load balancing, 621
INC 27
adding node 29
disabling HA monitor 29
route monitors 34
ingress rules
applying, 82
inline mode
configuring, 309
inline monitors
configuring, 247
Index 797
inserting
client IP address in requests, 213
IP address and port, 203, 346
VIP, 658
install, how to
audit server files 572
installing
NSWL on FreeBSD 542
NSWL on Linux 542
NSWL on MAC operating system 543
NSWL on Solaris 541
NSWL on Windows 544
installing audit server logging
FreeBSD 575
Windows 576
installing, NSWL 540
IP address
binding to VLANs, 90
managing, 51
modifying, 47
removing, 51
IP address and port
inserting, 203, 346
IP address types
configuring, 42
IP address, adding 551, 583
IPv4 and IPv6 headers
comparing, 642
IPv6
Citrix Netscaler system, 646
multicast listener discovery, 641
support, 639
IPv6 address scheme
concepts, 642
IPv6 address types
anycast, 645
classifying, 644
multicast, 644
unicast, 644
IPv6 addresses
adding, 648
viewing, 649
IPv6 route
creating, 651
removing, 651
viewing, 652
IPv6 statistics
viewing, 653
IPv6 vserver
adding, 650
K
Knowledge Center
alerts 5
L
LACP
large scale deployment
managing, 263
layer 2 mode
layer 3 mode
Layer 7 Denial of Service Protection 529
LB configuration
modifying, 125
LB method
load balancing DSR mode, 298, 313
LCD
display
out of service 773
power on 772
start-up 772
LDAP service
monitoring, 243
learning
router, 653
learning routes
OSPF, 611
least bandwidth method
configuring, 156
least connection method
configuring, 134
least packets method
configuring, 160
least response time method
configuring, 141
LED
12000 764, 766
9010 system 750, 752, 755
limiting propagations
RIP, 605
link aggregate channel
binding an interface, 74
creating, 73
removing, 77
verifying, 80
link aggregate channel protocol (LACP)
configuring, 78
link aggregation
concepts, 73
link load balancing
concepts, 619
configuring, 622
RNAT, 629
listen to RIP advertisements
configuring 605
listen-only mode
configuring, 610
load balancing
architecture, 112
basic configuration, 113, 114
common protocols, 281
concepts, 111
deployment scenarios, 295
enabling, 115
redirection mode, 182
sessionless vservers, 195
SIP in inline DSR mode, 240
SIP in one-armDSR mode, 239
spillover, 188
SSL 426
SSL servers, 284
topology, 114
troubleshooting problems, 315
verifying configuration, 123
load balancing configuration
customizing, 131
protecting, 185
viewing, 328
load balancing DSR mode
enabling MAC-based forwarding, 297, 312
LB method and redirection mode, 298, 313
USIP mode, 298, 314
load balancing policy
routing, 621
load balancing setup
configuring, 323
load balancing using SASP
configuring, 257
load monitors
configuring, 252
log file format
types 537
log files, Apache format 564
log filter, creating 547
log filter, defining 546
log format, argument string 562
log messages, severity levels 569
log properties 548, 580
log properties, default settings 550
log properties, defining 580
logging parameters
configure 538
logging, TCP 568
LRTM using monitors
configuring, 146
M
MAC-based forwarding
enabling, 297, 312
maintaining
client connections, 212
managing
ACLs, 102
client traffic, 195
content switching policy, 331
IP addresses, 51
large scale deployment, 263
monitors, 229
rewrite actions 666
servers, 125
service groups, 272
services, 127
static routes, 650
VLANs, 92
vservers, 129
managing and monitoring
servers, 206
mapped IP address
creating, 46
maximumbandwidth usage
setting, 221
maximumentries
session, 621
maximumnumber of client connections
setting, 217
maximumnumber of requests
setting, 218
Index 799
MBF mode
measuring
application performance 700
memory usage limit
TCP buffering 461
metric table
creating, 254
unbinding, 256
metric tables
removing, 255
metrics
binding to metric tables, 255
configuring, 253
MIB xvi
MIP as NAT IP address
using, 592
modes
RNAT, 592
modifying
ACLs, 104
BGP instance, 615
bridge tables, 107
channels, 75
host header, 657
IP addresses, 47
LB configuration, 125
monitors, 226
service groups, 270
VLANs, 91
modifying,HA configuration 13
monitor
managing, 229
modifying, 226
removing, 230
monitor, binding 532
monitoring
Citrix Presentation Server component, 246
DNS servers, 287
routers, 620
services, 223
monitoring services
DNS, 242
FTP, 235, 284
LDAP, 243
MySQL, 244
NNTP, 245
POP3, 245
RADIUS, 241
SIP, 235
SMTP, 246
SNMP, 244
SSL, 233
monitors
binding to a service group, 269
binding to services, 225
configuring, 223
creating, 224
customizing, 247
unbinding fromservice, 230
viewing, 231
multicast
IPv6 address, 644
multicast listener discovery
IPv6, 641
multiple subnets
configuring VLAN, 87
MySQL service
monitoring, 244
N
name server
adding, 290
NAT statistics
viewing, 600
NCSA Common format, log files 555
neighbor discovery
Citrix Netscaler system, 652
concepts, 641
IPv6, 642
neighbor discovery entries
removing, 652
neighbor discovery of IPv6
concepts, 645
NetScaler
safety information 737
NetScaler system IP address
creating, 42
network interface
binding to VLAN, 90
clearing statistics, 71
configuring, 67
managing, 69
resetting, 70
unbinding froma VLAN, 92
verifying, 71
networks
advertising, 618
nfiguration 13
NNTP service
monitoring, 245
non-NSIP network
enabling BGP, 613
NOOP 709
NSSA support
concepts, 612
NSWL
installing 540
NSWL, options 545
O
one-armmode
options
NSWL 545
options, audit server executable 577
OSPF
advertising routes, 609
concepts, 607
configuring, 608
enabling, 608
in a HA setup active standby mode, 612
learning routes, 611
listen-only, 610
viewing settings, 612
P
packet forwarding modes
configuring, 56
packets
forwarding, 83
parameters, audit log 568
parameters, set 547
path MTU behavior
persistence
configuring, 171
persistence groups
configuring, 179
PING response
controlling, 50
policies
compression 478
managing 672
URL Rewriting 672
removing 672
URL Rewriting 672
POP3 service
monitoring, 245
ports
10010 752, 755
15000 763, 765
7000 system 748, 757, 759, 761
9010 750
ports and protocols
rewriting, 346
potential for, DoS attack 517
precedence of evaluation
setting, 336
priority levels, policy queuing 525
priority queuing 525
configuring, 198
priority queuing, binding policy 528
priority queuing, configuring 526
priority queuing, creating policy 527
priority queuing, enabling 526
priority queuing, priority levels 525
priority queuing, verifying configuration 528
product alerts 5
protecting
Citrix NetScaler against failure, 339
traffic surge, 206
protocols
load balancing, 281
proxying
connections, 62
R
RADIUS service
monitoring, 241
range of vservers and services
creating, 264
Index 801
redirecting
client requests, 185
HTTP requests to cache, 197
requests to cache, 222
redirecting requests
cache, 344
redirection mode
configuring, 182
load balancing DSR mode, 298, 313
remove
basic configuration 769
extended configuration 769
full configuration 769
route monitor 36
VMAC 26
remove, content filter policy 511
removing
extended ACLs, 102
IP Addresses, 51
IPv6 routes, 651
metric tables, 255
monitors, 230
neighbor discovery entries, 652
server, 126
service groups, 272
service, 127
simple ACLs, 98
static ARP entries, 55
VLANs, 93
vserver, 130
renumbering
extended ACLs, 104
requesting
NAT statistics, 600
resetting
responder
bypassing safety checks 716
configuring policies 711
configuring redirect actions 715
enable 708
how it works 707
managing actions 716
managing policies 718
modifying actions 717
removing actions 718
removing policies 719
verifying configuration 713
respondwith action 708, 710
configure 708, 710
response time
calculating, 146
rewriting
ports and protocols, 346
rewriting ports and protocols
HTTP redirection, 201
RHI
enabling, 617
VIP, 618
RIP
configuring, 604
enabling, 603
RIP settings
viewing, 602
RIP to advertise routes
configuring, 604
RNAT
concepts, 591
configuring, 293
modes, 592
RNAT modes
USIP,USNIP,LLB, 600
RNAT with link load balancing
implementing, 621
round robin method
configuring, 139
route health injection
concepts, 616
route learning
configuring 606
route maps
configuring, 616
route monitor
remove 36
route monitor,binding to HA node 34
router advertisement learning
enabling, 653
routers
monitoring, 620
routing
load balancing policy, 621
routing persistence
destination IP, 620
rule based persistence
configuring, 175
rules, creating 508
S
safety check
bypassing 667
URL Rewriting 667
safety information 737
sample configuration file 585
NSWL 552
selecting
destination IP address, 63
source IP address, 63
server
creating, 119
managing, 125
removing, 126
server IDs
setting, 215
server parameters
usage, 119
Server-IDs based persistence
configuring, 177
servers
managing and monitoring 206
service
binding to vservers, 121
creating, 116
managing, 127
removing, 127
unbinding froma vserver, 129
viewing bindings, 125
service group
binding an IP address, 268
binding to a vserver, 267
configuring, 266
creating, 266
managing, 272
modifying, 270
removing, 272
unbinding a member, 273
unbinding froma vserver, 273
unbinding monitors, 274
service parameters
usage, 116
service weight
configuring, 184
service, adding 532
service, configure
client keep-alive 453, 454
compression 466, 469
parameters 466
TCP buffering 458, 460
session
entry time-out, 621
maximumentries, 621
sessionless vservers
configuring, 195
set threshold, surge protection 522
setting
case sensitivity, 335, 338
CS vserver state dependency on the state of target
LB vservers, 338
expiry time (TTL), 97
maximumbandwidth usage, 221
maximumnumber of client connections, 217
maximumnumber of requests, 218
precedence of evaluation, 336
server IDs, 215
SIP parameters, 294
threshold value for monitors, 218
undefined actions 672
URL Rewriting 672
setting idle time-out
client connections, 205, 219
server connections, 220
setting timeout
idle client connections, 348
Index 803
setting up
connection failover, 191, 193
monitors, 223
service groups, 266
severity level, log messages 569
simple ACL
removing, 98
verifying, 99
simple ACL rules
creating, 96
simple ACLs
configuring, 96
single subnet
configuring VLANs, 85
SIP
working, 237
SIP in inline DSR mode
concepts, 240
SIP in one-armDSR mode
concepts, 239
SIP parameters
configuring, 294
SIP servers
load balancing, 292
SIP service
monitoring, 235
SMTP service
monitoring, 246
SNIP mode
enabling, 45
SNMP xv
SNMP service
monitoring, 244
source and destination IP persistence
configuring, 178
source and destination IPs based on ACL
changing, 595
source IP address
selecting, 63
source IP destination IP hash method
configuring, 155
source IP hash method
configuring, 155
source IP persistence
configuring, 173
source IP source port hash method
configuring, 155
Specification
7000 model 747, 756
specification
10010 system 752
12000 system 754
15000 MPX appliance 763, 765
9010 system 749, 758
specifying files
HTML Injection 696
spillover
SSL
actions 401
certificate key pair 357
certificate revocation lists 386
client authentication 381, 382, 401
configurations 411, 414, 421, 423, 426,
428
configuring 399
configuring SSL offloading 352
CRL 389, 390
customizing configuration 392
deployment scenarios 426
enabling 353
insertion 403
managing certificates 360
outlook web access 402
overview 351
policies 409
server authentication 385
virtual server 359
SSL Acceleration
Exporting Certificates and Keys
IIS 5 on Windows 2000 366
Sun iPlanet 367
SSL certificate
exporting 364
self signed 371
SSL certificates
chain 373
client certificates 381
converting 381
exporting 364, 365, 366, 367, 369
global site certificates 376
importing 378
managing 375
server 375
SSL servers
load balancing, 284
SSL service
monitoring, 233
SSL session IDs based persistence
configuring, 175
SSL, DoS protection 530
start, audit server logging 584
start, web server logging 552
state, SYN cookie 518
static ARP
configuring, 53
static ARP entry
adding, 54
removing, 55
static routes
managing, 650
stop, audit server logging 584
stop, web server logging 552
subnet IP address
creating, 44
supported MIME types
compression 462
sure connect
surge protection 519
configuring, 206
surge protection, configuring 521
surge protection, disabling 521
surge protection, enabling 521
surge protection, setting threshold 522
SYN cookies 518
system requirements, audit server logging 572
system-owned IP address
configuring, 41
T
tagged network interface
configuring, 91
TCP buffering
basic topology 457
buffer size 460
configuration steps 457
configure parameters 460
configured parameters 458
definition 454
entities configured 458
entity model 456
how it works 455
memory usage limit 461
TCP logging 568
threshold value for monitors
setting, 218
threshold, configuration 524
throttle 523
throttle rate, aggressive 523
throttle rate, normal 523
time format definition 563
token method
configuring, 164
topology
load balancing, 114
troubleshooting
load balancing problems, 315
TTL
configuring, 97
types of, log file formats 537
U
unbind, how to
content filter policy 512
unbinding
metric tables, 256
monitors fromservice groups, 274
monitors, 230
service groups, 267, 273
unbinding content switching policies
unbinding froma vserver
service group, 273
services, 129
unbinding fromservice
monitors, 230
unbinding fromservice group
member, 273
monitors, 274
unbinding IP addresses
VLANs, 93
unbinding network interface
channel, 76
VLAN, 92
undefined actions
setting 672
URL Rewriting 672
undefined event 709
configure 709
NOOP 709
RESET 709
URL Rewriting 662
Index 805
understanding
basic LB topology, 114, 320
LB entity model 115, 321
SIP in inline DSR mode, 240
SIP in one-armDSR mode, 239
unicast
uninstalling audit server
on Linux 574
uninstalling audit server logging
on FreeBSD 575
on Windows 576
unique NAT IP address
configuring, 593
untagged VLANs
configuring, 88
URL for redirection
configuring, 342
URL hash method
configuring, 153
URL passive persistence
configuring, 176
URL redirection
configuring, 185
URL Rewrite
configuring actions 663
URL Rewriting
binding policies 665
configuring 662
creating policies 664
deployment scenarios 673
enabling 662
how it works 661
managing actions 666
managing policies 672
modifying actions 671
removing actions 671
removing policies 672
undefined events 662
use source IP address
enabling, 216
use source IP mode (USIP)
user monitors
configuring, 248
user-defined policies
compression 479
using
MIP as NAT IP address, 592
unique NAT IP address, 593
USIP,USNIP,LLB
RNAT modes, 600
V
verify
route monitor 34
VMAC configuration 25
verify cache redirection configuration
using CLI 472, 473
verify configuration, priority queuing 528
verify, compression configuration
configuration utility 473
statistical utility 471
using SNMP 471
verify, configuration 551
verify, configuration file 584
verifying
bridge tables, 108
configuration 666
URL Rewriting 666
content switching configuration, 327
extended ACLs, 106
simple ACLs, 99
VLANs, 94
verifying configuration
HTML Injection 690
viewing
discovered neighbors, 652
filter actions 691
filter policies 691
IPv6 addresses, 649
monitors, 231
service bindings, 125
virtual server 692
vserver properties, 123
viewing properties
ARP entries, 56
bridge tables, 108
channels, 80
extended ACLs, 106
IP addresses, 53
LACP, 80
metric tables, 256
service group, 275
service, 124
simple ACLs, 99
VLANs, 94
vserver, 123
viewing routes
dynamic routing protocols, 619
IPv6, 652
viewing settings
BGP, 615
OSPF, 612
RIP, 602
viewing statistics
bridge table, 109
extended ACL, 107
IPv6, 653
network interface, 72
service group, 276
service, 124
simple ACL, 99
VLANs, 94
vserver, 123
VIP
inserting, 658
RHI, 618
virtual server IP address
creating, 46
virtual servers
defining log filter 548
VLAN support
concepts, 654
VLANs
configuring, 81
creating, 84
managing, 92
removing, 93
unbinding IP address, 93
verifying, 94
VMAC
adding 23
binding interfaces 24
configuring, 95
remove 26
unbinding interfaces 26
verify configuration 23, 25
vserver
creating, 120
managing, 129
removing, 130
vserver parameters
usage, 120, 322
vservers
binding policies, 325
binding to work load manager, 260
W
W3C Extended log format
Customizing W3C Format 556
Directives 557
Entries 556
Fields 557
Identifiers 558
W3C format, customize 556
W3C format, log files 555, 556
configure 546
enabling 538
hardware configuration 540
how it works 537
software configuration 540
web server logging, checklist 565
web server logging, starting 552
web server logging, stopping 552
weighted queuing 528
weighted round robin
configuring, 140
work load manager
creating, 259
entity model, 259
managing, 262
modifying, 261
removing, 262
unbinding, 262
viewing, 263
working
SIP, 237

Citrix Netscaler Installation and Configuration Guide - Volume 1

Uploaded by

Document Information

Copyright

Available Formats

Share this document

Share or Embed Document

Sharing Options

Did you find this document useful?

Is this content inappropriate?

Copyright:

Available Formats

Citrix Netscaler Installation and Configuration Guide - Volume 1

Uploaded by

Copyright:

Available Formats

CitrixNetScaler

Installation and Configuration Guide - Volume 1

You might also like