Citrix Netscaler Installation and Configuration Guide - Volume 1

Citrix®NetScaler®Installation and Configuration Guide - Volume 1 Release 8.1 Copyright and Trademark Notice ©CITRIX SYSTEMS, INC., 2009. ALL RIGHTS RESERVED. NO PART OF THIS DOCUMENT MAY BE REPRODUCED OR TRANSMITTED IN ANY FORM OR BY ANY MEANS OR USED TO MAKE DERIVATIVE WORK (SUCH AS TRANSLATION, TRANSFORMATION, OR ADAPTATION) WITHOUT THE EXPRESS WRITTEN PERMISSION OF CITRIX SYSTEMS, INC. ALTHOUGH THE MATERIAL PRESENTED IN THIS DOCUMENT IS BELIEVED TO BE ACCURATE, IT IS PRESENTED WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED. USERS MUST TAKE ALL RESPONSIBILITY FOR THE USE OR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS MANUAL. CITRIX SYSTEMS, INC. OR ITS SUPPLIERS DO NOT ASSUME ANY LIABILITY THAT MAY OCCUR DUE TO THE USE OR APPLICATION OF THE PRODUCT(S) DESCRIBED IN THIS DOCUMENT. INFORMATION IN THIS DOCUMENT IS SUBJ ECT TO CHANGE WITHOUT NOTICE. COMPANIES, NAMES, AND DATA USED IN EXAMPLES ARE FICTITIOUS UNLESS OTHERWISE NOTED. The following information is for FCC compliance of Class A devices: This equipment has been tested and found to comply with the limits for a Class A digital device, pursuant to part 15 of the FCC rules. These limits are designed to provide reasonable protection against harmful interference when the equipment is operated in a commercial environment. This equipment generates, uses, and can radiate radio- frequency energy and, if not installed and used in accordance with the instruction manual, may cause harmful interference to radio communications. Operation of this equipment in a residential area is likely to cause harmful interference, in which case users will be required to correct the interference at their own expense. Modifying the equipment without Citrix' written authorization may result in the equipment no longer complying with FCC requirements for Class A digital devices. In that event, your right to use the equipment may be limited by FCC regulations, and you may be required to correct any interference to radio or television communications at your own expense. You can determine whether your equipment is causing interference by turning it off. If the interference stops, it was probably caused by the NetScaler Request Switch™ 9000 Series equipment. If the NetScaler equipment causes interference, try to correct the interference by using one or more of the following measures: Move the NetScaler equipment to one side or the other of your equipment. Move the NetScaler equipment farther away from your equipment. Plug the NetScaler equipment into an outlet on a different circuit from your equipment. (Make sure the NetScaler equipment and your equipment are on circuits controlled by different circuit breakers or fuses.) Modifications to this product not authorized by Citrix Systems, Inc., could void the FCC approval and negate your authority to operate the product. BroadCom is a registered trademark of BroadCom Corporation. Fast Ramp, NetScaler, and NetScaler Request Switch are trademarks of Citrix Systems, Inc. Linux is a registered trademark of Linus Torvalds. Internet Explorer, Microsoft, PowerPoint, Windows and Windows product names such as Windows NT are trademarks or registered trademarks of the Microsoft Corporation. NetScape is a registered trademark of Netscape Communications Corporation. Red Hat is a trademark of Red Hat, Inc. Sun and Sun Microsystems are registered trademarks of Sun Microsystems, Inc. Other brand and product names may be registered trademarks or trademarks of their respective holders. Software covered by the following third party copyrights may be included with this product and will also be subject to the software license agreement: Copyright 1998 ©Carnegie Mellon University. All rights reserved. Copyright ©David L. Mills 1993, 1994. Copyright © 1992, 1993, 1994, 1997 Henry Spencer. Copyright ©J ean-loup Gailly and Mark Adler. Copyright ©1999, 2000 by J ef Poskanzer. All rights reserved. Copyright ©Markus Friedl, Theo de Raadt, Niels Provos, Dug Song, Aaron Campbell, Damien Miller, Kevin Steves. All rights reserved. Copyright ©1982, 1985, 1986, 1988-1991, 1993 Regents of the University of California. All rights reserved. Copyright © 1995 Tatu Ylonen, Espoo, Finland. All rights reserved. Copyright ©UNIX System Laboratories, Inc. Copyright ©2001 Mark R V Murray. Copyright 1995-1998 ©Eric Young. Copyright ©1995,1996,1997,1998. Lars Fenneberg. Copyright ©1992. Livingston Enterprises, Inc. Copyright ©1992, 1993, 1994, 1995. The Regents of the University of Michigan and Merit Network, Inc. Copyright © 1991-2, RSA Data Security, Inc. Created 1991. Copyright ©1998 J uniper Networks, Inc. All rights reserved. Copyright ©2001, 2002 Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 1999- 2001©The Open LDAP Foundation. All Rights Reserved. Copyright ©1999 Andrzej Bialecki. All rights reserved. Copyright ©2000 The Apache Software Foundation. All rights reserved. Copyright (C) 2001-2003 Robert A. van Engelen, Genivia inc. All Rights Reserved. Copyright (c) 1997-2004 University of Cambridge. All rights reserved. Copyright (c) 1995. David Greenman. Copyright (c) 2001 J onathan Lemon. All rights reserved. Copyright (c) 1997, 1998, 1999. Bill Paul. All rights reserved. Copyright (c) 1994-1997 Matt Thomas. All rights reserved. Copyright ©2000 J ason L. Wright. Copyright ©2000 Theo de Raadt. Copyright ©2001 Patrik Lindergren. All rights reserved. Part No. NS-ICG1-81-0609 Last Updated: November 2009 CONTENTS Chapter 1 Managing the Citrix NetScaler SNMP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xv Configuring SNMP V1 and V2. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xvii Configuring SNMP V3 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxx Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxv How it Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .xxxv Configuring Users and Groups . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xxxvi Role-Based Authorization Command Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . xli How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlii Configuring RBAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xlii Configuring Clock Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . l NetScaler Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii Logging NetScaler Events. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lii Customizing Syslog. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liii Configuring Log File Rotation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . liv Path Maximum Transmission Unit Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . lv How It Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lv Enabling PMTU Discovery. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lvi Autodetected Services. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . lvi Chapter 2 Introduction About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1 Audience. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Additional Product Documentation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2 Document Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .3 Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Additional Maintenance Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .4 Subscription Advantage . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Knowledge Center Watches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Education and Training. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Documentation Feedback. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5 Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6 Chapter 3 High Availability How High Availability Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7 Considerations for a High Availability Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8 ii Installation and Configuration Guide - Volume 1 Configuring High Availability. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 9 Configuring a Basic High Availability Setup . . . . . . . . . . . . . . . . . . . . . . . . . . 10 Modifying an Existing HA Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13 Customizing an High Availability Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Configuring the Communication Intervals. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 16 Configuring Synchronization. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 17 Configuring Command Propagation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Forcing a Node to Failover. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20 Improving the Reliability of a High Availability Setup . . . . . . . . . . . . . . . . . . . . . 22 Configuring Virtual MAC Addresses (VMAC) . . . . . . . . . . . . . . . . . . . . . . . . 22 Configuring High Availability Nodes in Different Subnets . . . . . . . . . . . . . . . 27 Configuring Link Redundancy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30 Configuring Route Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34 HA Health Check Computation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Configuring the State of a Node . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37 Forcing the Secondary Node to Stay Secondary . . . . . . . . . . . . . . . . . . . . . . . . 37 Forcing the Primary Node to Stay Primary . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 Troubleshooting HA Issues . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39 Chapter 4 Basic Network Configuration Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Configuring System-Owned IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41 Creating the NetScaler IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Configuring IP Address Types. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42 Modifying IP Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47 Managing IP Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51 Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Configuring Static ARP . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 53 Configuring Modes of Packet Forwarding . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 56 Enabling and Disabling Layer 2 Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57 Enabling and Disabling Layer 3 Mode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 58 Enabling and Disabling MAC-Based Forwarding Mode . . . . . . . . . . . . . . . . . 59 Contents iii Proxying Connections. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .62 Selecting the Destination IP Address . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 Selecting the Source IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .63 Configuring the Use Source IP Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64 Configuring Network Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67 Managing Network Interfaces. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .69 Configuring Link Aggregation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .73 Configuring VLANs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .81 Applying Rules to Classify Frames . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .82 Forwarding Packets on the System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .83 Configuring VMAC . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 Configuring Access Control Lists . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .95 Configuring Simple ACLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96 Configuring Extended ACLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .100 Configuring Bridge Tables. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Modifying Bridge Tables . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .107 Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .108 Chapter 5 Load Balancing How Load Balancing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .111 Configuring Basic Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .113 Configuring a Basic Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114 Modifying an Existing Load Balancing Configuration . . . . . . . . . . . . . . . . . .125 Customizing Load Balancing Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . .131 Changing the Load Balancing Algorithm. . . . . . . . . . . . . . . . . . . . . . . . . . . . .132 Configuring Persistent Connections Between Clients and Servers . . . . . . . . .171 Configuring Persistence Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .179 Configuring the Redirection Mode. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .182 Assigning Weights to Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .184 Protecting the Load Balancing Configuration against Failure. . . . . . . . . . . . . . . .185 Redirecting Client Requests to an Alternate URL . . . . . . . . . . . . . . . . . . . . . .185 Configuring a Backup LB Vserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186 Diverting Excess Traffic to a Backup LB Vserver. . . . . . . . . . . . . . . . . . . . . .188 Configuring Stateful Connection Failover . . . . . . . . . . . . . . . . . . . . . . . . . . . .191 iv Installation and Configuration Guide - Volume 1 Managing Client Traffic. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Configuring Sessionless LB Vservers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Redirecting HTTP Requests to a Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 197 Directing Requests Based on Priority . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 198 Directing Requests to a Custom Web Page. . . . . . . . . . . . . . . . . . . . . . . . . . . 199 Enabling Delayed Cleanup of Vserver Connections. . . . . . . . . . . . . . . . . . . . 200 Rewriting Ports and Protocols for HTTP Redirection. . . . . . . . . . . . . . . . . . . 201 Inserting the IP Address and Port of a Vserver in the Request Header. . . . . . 203 Managing and Monitoring Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Configuring Services for Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . 206 Redirecting Client Requests to a Cache. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 222 Configuring Monitors. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 223 Monitoring Applications and Services Using Prebuilt Monitors . . . . . . . . . . 232 Monitoring Applications and Services Using Customized Monitors . . . . . . . 247 Configuring Load Monitors . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 252 Configuring Support for Third-party Load Balancers Using SASP . . . . . . . . 257 Managing a Large Scale Deployment. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 263 Configuring a Range of Vservers and Services. . . . . . . . . . . . . . . . . . . . . . . . 264 Configuring Service Groups. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 266 Translating the IP Address of a Domain-Based Server. . . . . . . . . . . . . . . . . . 276 Masking a Virtual Server IP Address. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 278 Configuring Load Balancing for Commonly Used Protocols. . . . . . . . . . . . . . . . 281 Load Balancing for a Group of FTP Servers. . . . . . . . . . . . . . . . . . . . . . . . . . 282 Load Balancing a Group of SSL Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 284 Load Balancing DNS Servers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 285 Load Balancing with Domain-Name Based Services . . . . . . . . . . . . . . . . . . . 287 Load Balancing a Group of SIP Servers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 292 Configuring Load Balancing in Commonly Used Deployment Scenarios. . . . . . 295 Configuring Load Balancing in Direct Server Return Mode. . . . . . . . . . . . . . 295 Configuring Load Balancing in Direct Server Return mode using IP Tunneling. 299 Configuring Load Balancing in Direct Server Return mode using TOS . . . . 303 Configuring Load Balancing in One-arm Mode . . . . . . . . . . . . . . . . . . . . . . . 307 Configuring Load Balancing in the Inline Mode. . . . . . . . . . . . . . . . . . . . . . . 309 Load Balancing of Intrusion Detection System Servers . . . . . . . . . . . . . . . . . 310 Troubleshooting Common Problems. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 315 Chapter 6 Content Switching How Content Switching Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 317 Contents v Configuring Basic Content Switching . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .319 Configuring Basic Content Switching Setup . . . . . . . . . . . . . . . . . . . . . . . . . .319 Modifying the Existing Content Switching Configuration . . . . . . . . . . . . . . .328 Customizing a Content Switching Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .334 Setting Case Sensitivity in Policy Evaluation. . . . . . . . . . . . . . . . . . . . . . . . . .335 Setting the Precedence of Evaluation of Policy . . . . . . . . . . . . . . . . . . . . . . . .336 Setting Dependency of CS Vserver State on the State of Target LB Vservers. . . 338 Protecting the NetScaler against Failure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339 Configuring Backup Vserver . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .339 Diverting Excess Traffic to a Backup Vserver. . . . . . . . . . . . . . . . . . . . . . . . .341 Configuring a URL for Redirection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .342 Managing Client Connections . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .343 Redirecting Client Requests to a Cache . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .344 Enabling Delayed Cleanup of Vserver Connections . . . . . . . . . . . . . . . . . . . .345 Rewriting Ports and Protocols for Redirection. . . . . . . . . . . . . . . . . . . . . . . . .346 Inserting the IP Address and Port of a Vserver in the Request Header . . . . . .346 Setting a Time-out Value for Idle Client Connections. . . . . . . . . . . . . . . . . . .348 Chapter 7 Secure Sockets Layer (SSL) Acceleration Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 How SSL Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .351 Configuring SSL Offloading . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .352 Enabling the SSL Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .353 Configuring an SSL Virtual Server for Basic SSL Offloading . . . . . . . . . . . .354 Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .359 Managing Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .360 Obtaining a Certificate from a Certificate Authority . . . . . . . . . . . . . . . . . . . .361 Exporting Existing Certificates and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . .364 Generating a New Certificate and Key. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .369 Creating a Chain of Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .373 Managing Certificates and Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .375 Managing Global Site Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .376 Importing and Exporting SSL Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . .378 Configuring Client Authentication. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381 Generating Client Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .381 Converting Certificates into PKCS#12 Format . . . . . . . . . . . . . . . . . . . . . . . .381 Configuring Client Certificate-Based Authentication on the NetScaler . . . . .382 Managing Server Authentication . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .385 vi Installation and Configuration Guide - Volume 1 Managing Certificate Revocation Lists. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 386 Configuring an Existing CRL on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . 386 Configuring CRL Refresh Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 387 Synchronizing CRLs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 389 Creating a CRL on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 390 Customizing the SSL Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 392 Configuring Diffe-Hellman (DH) Parameters. . . . . . . . . . . . . . . . . . . . . . . . . 394 Configuring Ephemeral RSA . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 395 Configuring Session Reuse. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Configuring Cipher Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 396 Configuring SSLv2 Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 398 Configuring SSL Protocol Settings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Configuring Advanced SSL Settings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 399 Managing SSL Actions and Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Creating SSL Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 401 Configuring Insertion . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 403 Creating SSL Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 409 Binding SSL Policies to a Virtual Server. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 410 Configuring Some Commonly Used SSL Configurations . . . . . . . . . . . . . . . . . . 411 Configuring SSL Offloading with End-to-End Encryption. . . . . . . . . . . . . . . 411 Configuring Transparent SSL Acceleration. . . . . . . . . . . . . . . . . . . . . . . . . . . 414 Configuring the SSL feature with HTTP on the Front End and SSL on the Back- end. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 419 Configuring SSL Offloading with Other-TCP Protocols . . . . . . . . . . . . . . . . 421 Configuring SSL Bridging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 423 Configuring the SSL Feature for Common Used Deployment Scenarios . . . . . . 426 Configuring an SSL Virtual Server for Load Balancing. . . . . . . . . . . . . . . . . 426 Configuring a Secure Content Switching Server. . . . . . . . . . . . . . . . . . . . . . . 428 Chapter 8 FIPS How FIPS Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 437 Configuring a FIPS system . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Configuring the HSM. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 438 Managing FIPS Keys. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 Creating FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 Exporting FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 440 Importing FIPS Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 441 Importing External Keys . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 442 Configuring a Certificate Signing Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 444 Configuring a High Availability (HA) FIPS system. . . . . . . . . . . . . . . . . . . . . . . 445 Contents vii Managing Certificates. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .446 Chapter 9 Optimizing Performance Understanding and Configuring Client Keep-Alive . . . . . . . . . . . . . . . . . . . . . . .449 How Client Keep-Alive Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .450 Configuring Client Keep-Alive. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .451 Modifying the Client Keep-Alive Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . .453 Understanding and Configuring TCP Buffering . . . . . . . . . . . . . . . . . . . . . . . . . .454 How TCP Buffering Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .455 Configuring TCP Buffering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .457 Modifying the TCP Buffering Setup. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .459 Understanding and Configuring Compression. . . . . . . . . . . . . . . . . . . . . . . . . . . .461 How Compression Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .462 Configuring the Compression Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .464 Modifying an Existing Compression Setup . . . . . . . . . . . . . . . . . . . . . . . . . . .467 Verifying the Compression Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . .470 Customizing a Compression Setup with Policies and Actions. . . . . . . . . . . . .473 Configuring Compression for Commonly Used Deployment Scenarios. . . . .489 Configuring TCP Window Scaling . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .503 Configuring Selective Acknowledgement (SACK). . . . . . . . . . . . . . . . . . . . . . . .504 Chapter 10 Protection Features How Citrix NetScaler Enforces Protection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .507 How Content Filtering Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .508 Configuring Content Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509 Enabling Content Filtering . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509 Disabling Content Filtering. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .509 Creating Content Filter Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510 Creating Content Filter Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .510 Binding and Unbinding the Filter Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . .511 Configuring Content Filtering for a Commonly Used Deployment Scenario.512 Configuring Layer 3-4 Denial of Service (SYN) Protection. . . . . . . . . . . . . . . . .517 How the System Protects Against DoS Attack. . . . . . . . . . . . . . . . . . . . . . . . .517 Using SYN Cookies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .518 How Surge Protection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .519 Configuring Surge Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .521 Disabling and Re-enabling Surge Protection . . . . . . . . . . . . . . . . . . . . . . . . . .521 Setting Threshold for Surge Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .522 Configuring Surge Protection for a Commonly Used Deployment Scenario .525 viii Installation and Configuration Guide - Volume 1 How Priority Queuing Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 525 Configuring Priority Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Enabling Priority Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Creating the Priority Queuing Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 526 Binding and enabling the Priority Queuing Policies . . . . . . . . . . . . . . . . . . . . 528 Verify the configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 Setting up Weighted Queuing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 528 How Layer 7 Denial of Service Protection Works . . . . . . . . . . . . . . . . . . . . . . . . 529 Limitations of the Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 530 How DoS Protection Affects Other Features. . . . . . . . . . . . . . . . . . . . . . . . . . 530 Configuring DoS Protection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 531 Tuning the Client Detection/JavaScript Challenge Response Rate. . . . . . . . . 533 Guidelines for HTTP DoS Protection Deployment. . . . . . . . . . . . . . . . . . . . . 534 Chapter 11 Web Server Logging How Web Server Logging Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 537 Configuring Web Server Logging Parameters . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Enabling Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 538 Using CLI Commands to View Web Server Logging Status . . . . . . . . . . . . . 538 Modifying the Default Buffer Size at the GUI. . . . . . . . . . . . . . . . . . . . . . . . . 539 Modifying the Default Buffer Size at the CLI . . . . . . . . . . . . . . . . . . . . . . . . . 539 Installing the NSWL files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 540 Installing on the Solaris Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . 541 Installing on the Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . . . . . 542 Installing on the FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . . . . . 542 Installing on the MAC Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . . 543 Installing on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . . . . 544 NSWL Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 544 Configuring Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 546 Modifying the Web Server Log Configuration File . . . . . . . . . . . . . . . . . . . . 546 Defining Log Properties. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 548 Adding the IP Addresses of the System. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 551 Starting Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 Stopping Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 552 Log File Formats. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 555 Custom Log Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 560 Apache Log Formats . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 564 Checklist for Configuring Web Server Logging. . . . . . . . . . . . . . . . . . . . . . . . . . 565 Contents ix Chapter 12 Configuring Audit Server Logging How Audit Server Logging Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .567 Configuring the Citrix NetScaler Audit Server Log . . . . . . . . . . . . . . . . . . . . . . .568 Audit Server Logging Parameters. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .569 Configuring Global Audit Server Parameters. . . . . . . . . . . . . . . . . . . . . . . . . .570 Configuring Audit Server Action and Policy. . . . . . . . . . . . . . . . . . . . . . . . . .571 Globally Binding the Audit Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572 Installing the Audit Server Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .572 Installing on the Linux Operating System . . . . . . . . . . . . . . . . . . . . . . . . . . . .574 Uninstalling on the Linux Operating System. . . . . . . . . . . . . . . . . . . . . . . . . .574 Installing on the FreeBSD Operating System. . . . . . . . . . . . . . . . . . . . . . . . . .575 Uninstalling on the FreeBSD Operating System . . . . . . . . . . . . . . . . . . . . . . .575 Installing on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . . . .576 Uninstalling on the Windows Operating System . . . . . . . . . . . . . . . . . . . . . . .576 Audit Server Options. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .577 Configuring Audit Server Logging on a Server Computer . . . . . . . . . . . . . . . . . .578 Defining Filters . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .579 Defining Log Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .580 Adding the IP Addresses of the System . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .583 Verifying Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584 Starting Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584 Stopping Audit Server Logging . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .584 Sample Configuration File . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .585 Checklist for Configuring Audit Server Logging. . . . . . . . . . . . . . . . . . . . . . .585 Commonly Used Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .586 Chapter 13 Advanced Network Configuration Reverse Network Address Translation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .591 RNAT Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .592 RNAT in USIP, USNIP, and LLB Modes . . . . . . . . . . . . . . . . . . . . . . . . . . . .600 Viewing NAT Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .600 Dynamic Routing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .602 Enabling and Disabling Dynamic Routing. . . . . . . . . . . . . . . . . . . . . . . . . . . .603 Using RIP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .603 Using OSPF. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .607 Using BGP. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .612 x Installation and Configuration Guide - Volume 1 Route Health Injection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 616 Enabling RHI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 617 Limiting Host Route Advertising for VIPs . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 Advertising Networks. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 618 Viewing Routes Learned Through Dynamic Routing Protocols. . . . . . . . . . . 619 Link Load Balancing . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 619 Monitoring Routers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Destination IP-Based Persistence. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 620 Load Balancing Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 621 Implementing RNAT with Link Load Balancing . . . . . . . . . . . . . . . . . . . . . . 621 Configuring Link LB . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 622 Configuring the Backup Router . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 625 Configuring RNAT with Link Load Balancing. . . . . . . . . . . . . . . . . . . . . . . . 629 Path MTU Behavior. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 633 IP Tunneling. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 NetScaler as an Encapsulator (Load Balancing with DSR mode) . . . . . . . . . 634 NetScaler as a Decapsulator. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 634 IPv6 Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 639 Understanding IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 642 Types of IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 644 Neighbor Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 645 IPv6 on the NetScaler. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 646 Enabling and Disabling IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 647 Adding IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 648 Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 649 Adding an IPv6 Vserver. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 Managing Static Routes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 650 Neighbor Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 652 Router Learning . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653 Viewing Statistics. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 653 VLAN Support . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 Simple Deployment Scenario. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 654 Host Header Modification . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 657 Chapter 14 URL Rewrite How URL Rewriting Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 661 Contents xi Configuring URL Rewriting. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .662 Enabling URL Rewriting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .662 Setting the NetScaler Behaviour for Undefined Events. . . . . . . . . . . . . . . . . .662 Configuring a Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .663 Creating a Rewrite Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .664 Binding Rewrite Policies to a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . .665 Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666 Managing Rewrite Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .666 Bypassing the Safety Check . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667 Creating Rewrite Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .667 Modifying an Existing Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671 Removing an Existing Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .671 Managing Rewrite Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672 Setting the Undefined Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672 Removing an Existing Rewrite Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .672 Configuring the Rewrite Feature for Commonly Used Deployment Scenarios . .673 Example 1: Inserting the Client IP Address as an HTTP Header . . . . . . . . . .674 Example 2: Delete Old X-Forwarded-For Headers . . . . . . . . . . . . . . . . . . . . .675 Example 3: Tagging Secure and Unsecure Connections . . . . . . . . . . . . . . . . .676 Example 4: Mask the HTTP Server Type. . . . . . . . . . . . . . . . . . . . . . . . . . . . .677 Example 5: Redirect an External URL to an Internal URL . . . . . . . . . . . . . . .678 Example 6: Migrating Apache Rewrite Module Rules . . . . . . . . . . . . . . . . . .679 Example 7: Marketing Keyword Redirection. . . . . . . . . . . . . . . . . . . . . . . . . .681 Example 8: Redirect Queries to the Queried Server. . . . . . . . . . . . . . . . . . . . .681 Example 9: Home Page Redirection. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .682 Chapter 15 HTML Injection Overview. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685 How HTML Injection Works. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .685 Configuring HTML Injection to Insert Data in the HTTP Header . . . . . . . . . . . .686 Enabling the HTML Injection Feature . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .686 Injecting Data into the HTTP Header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .687 Verifying the Configuration . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .690 Configuring HTML Injection to Insert Data into the HTTP Body . . . . . . . . . . . .692 Internal Variables used for HTML Injection . . . . . . . . . . . . . . . . . . . . . . . . . .692 Configuring Prebody Files . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .694 Configuring Postbody Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .695 Specifying Files to be used for Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . .696 Injecting Data into the HTTP Body . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .697 xii Installation and Configuration Guide - Volume 1 Configuring the HTML Injection Feature for Commonly Used Applications. . . 700 Measuring Application Performance Using a Citrix EdgeSight for NetScaler Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 700 Enabling the HTML Injection Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702 Specifying Files to be used for Injection . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 702 Injecting Data into the HTTP Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 703 Chapter 16 Responder Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 How Responder Works . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 707 Configuring the Responder Feature with a Respondwith Action. . . . . . . . . . . . . 708 Enabling the Responder Feature. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 708 Setting the NetScaler Behavior for Undefined Events . . . . . . . . . . . . . . . . . . 709 Configuring Respondwith Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 710 Configuring Responder Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 711 Verifying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 713 Configuring the Responder Feature with a Redirect Action. . . . . . . . . . . . . . . . . 715 Configuring Redirect Actions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 715 Managing Responder Actions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 Bypassing the Safety Check. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 716 Modifying an Existing Responder Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . 717 Removing an Existing Responder Action . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 Managing Responder Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 Setting the Undefined Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 718 Removing an Existing Responder Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . 719 Appendix A API Reference Introduction to the API. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 721 Benefits of API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 Hardware and Software Requirements . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 Interface Description . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 722 API Architecture . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 723 The NSConfig Interface. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 724 Examples of API Usage. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 Example: Setting the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 Example: Querying the Configuration. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 726 The Web Service Definition Language (WSDL) . . . . . . . . . . . . . . . . . . . . . . . . . 728 Creating Client Applications Using the NSConfig.wsdl File . . . . . . . . . . . . . 728 Filter WSDL. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 729 xiii Installation and Configuration Guide - Volume 1 Securing API Access . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 731 Appendix B Converting Certificate and Keys OpenSSL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 Converting from PKCS#12 to .PEM . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 733 Transforming a IIS 4.0 Exported Key . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 735 Appendix C Warning and Safety Messages Appendix D SystemHealth Counters Appendix E Introducing the Citrix NetScaler Hardware Platforms Hardware Platforms. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747 Citrix NetScaler 7000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 747 Citrix NetScaler 9010 and 9010 FIPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 749 Citrix NetScaler 10010. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 752 Citrix NetScaler 12000 and 12000-10G. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 754 Citrix NetScaler MPX 5500. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 756 Citrix NetScaler MPX 7500 and MPX 9500. . . . . . . . . . . . . . . . . . . . . . . . . . 758 Citrix NetScaler MPX 9700, MPX 10500, and MPX 12500 . . . . . . . . . . . . . 761 Citrix NetScaler MPX 15000 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 763 Citrix NetScaler MPX 17000. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 765 Citrix Platform Summary. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 767 Appendix F Clearing the Configuration Appendix G Understanding the LCD Panel Special Display Screens. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 Booting Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 Startup Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 772 Out-of-Service Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 Regular Display Screens . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 Configuration Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 Alert Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 773 HTTP Statistics Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 774 Network Traffic Statistics Screen. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 775 CPU Load, Memory, and Connections Screen . . . . . . . . . . . . . . . . . . . . . . . . 775 Port Information Screen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 776 xiv Installation and Configuration Guide - Volume 1 Appendix H Configuring Secure Access Appendix I FIPS Approved Algorithms and Ciphers Appendix J Resetting a Locked HSM Index . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 789 CHAPTER 2 Managing the Citrix NetScaler This chapter describes how to manage the Citrix NetScaler. The chapter provides instructions on performing common tasks, including configuring SNMP, managing system users and groups, and configuring a number of other features. Topics in this chapter include: • SNMP • Users and Groups • Role-Based Authorization Command Policies • Configuring Clock Synchronization • System Logging • Path Maximum Transmission Unit Discovery • Autodetected Services SNMP The system supports SNMP for a wide range of network management functions. The following subsections explain which SNMP features are supported, and how to configure SNMP support on the NetScaler. HowIt Works The following figure is a conceptual diagram that shows a network with a NetScaler that has SNMP enabled and configured. In the diagram, each SNMP network management application uses SNMP to communicate with the SNMP agent on the NetScaler. The SNMP agent then searches the MIB to collect the data requested by the network management application, and provides the information to the application. xvi Installation and Configuration Guide - Volume 1 NetScaler Supporting SNMP To configure SNMP support on the NetScaler, you will use GUI to do the following: • Assign access privileges to network management applications and their users. • Specify NetScaler information that can be displayed from the NetScaler SNMP MIB. • Specify SNMP traps that track various parameters, such as CPU usage and interfaces status. The NetScaler supports enterprise-specific MIBs. They are: • A subset of standard MIB-2 groups. Provides the MIB-2 groups SYSTEM, IF, ICMP, UDP, SNMP. • A system enterprise MIB. Provides NetScaler-specific configuration and statistics. Chapter 2 Managing the Citrix NetScaler xvii The SNMP agent on the NetScaler supports SNMP version 1 (SNMPv1), SNMP version 2 (SNMPv2), and SNMP version 3 (SNMPv3). As a result, the SNMP agent operates in bilingual mode, allowing it to handle SNMPv2 queries, such as Get-Bulk. The SNMP agent also sends out traps compliant with SNMPv2, and supports SNMPv2 data-types, such as counter64. SNMPv1 managers (programs on other servers that request SNMP information from the NetScaler) use the NS-MIB-smiv1.mib file when processing SNMP queries. SNMPv2 managers use the NS-MIB-smiv2.mib file. Configuring SNMP V1 and V2 This section describes configuring SNMP V1 and V2. Before you can use SNMP in the NetScaler, you must configure it to allow the appropriate SNMP managers access, and provide it with the necessary NetScaler-specific information. The configuration process consists of these tasks: • Set the access control list for SNMP managers. • Set the SNMP community, which defines access privileges (Read operation). • Set the NetScaler’s MIB variables: NetScaler name, contact person for that NetScaler and NetScaler location. • Set which traps will be enabled and where trap notifications will be displayed. You can also set the source IP of the SNMP trap to MIP or SNIP. • Set the threshold level, (the level at which an event is recorded and an alarm is generated) for all traps. The threshold level defines which set of events will generate an alarm (notification message) to an SNMP network management application. • If you want the SNMP service to respond to SNMP queries on IPs other than the NSIP, add the additional IPs to the NetScaler configuration. • Import the appropriate SNMP MIB files. • If the HP OpenView SNMP manager is installed on your workstation, copy the NS-MIB-smiv2.mib file from the NetScaler Product CD, / Utilities/SNMP/HP_OpenView directory, or download it from the FTP site ftp.netscaler.com. • If the WhatsUpGold SNMP manager is installed on your workstation, copy the traps.txt and mib.txt files from the NetScaler Product CD, / Utilities/SNMP/WhatsUpGold directory, or download it from the FTP site ftp.netscaler.com. xviii Installation and Configuration Guide - Volume 1 Note: For information regarding the Username and Password used to connect to the FTP site, contact the NetScaler product support group. Adding SNMP Manager This section covers the procedure for adding a SNMP Manager. You also configure the management application, which complies with SNMP version 1 or SNMP version 2, to access to the NetScaler. The netmask parameter can be used to grant access from entire subnets. Up to a maximum of 100 network management hosts or networks can be added. Note: If you do not configure at least one SNMP manager, the NetScaler accepts and responds to SNMP queries from all IPs on the network. If you configure one or more SNMP managers, it accepts and responds to only SNMP queries from those specific IPs. To add a SNMP Manager, use the parameters listed in the following table: In the following example, a SNMP manager having IP address 10.102.29.5 and subnet mask 255.255.255.0 is created. To add an SNMP manager 1. In the left pane, expand System, click SNMP and click Managers. The Managers page appears on the right pane. 2. Click Add. The Create Manager dialog box appears. 3. In the IP Address text box, type the IP address. For example, 10.102.29.5. 4. Click Add. To add an SNMP manager using the NetScaler command line At the NetScaler command prompt, type: add snmp manager 10.102.29.5 Parameter Description IP Address The IP/Network address of the management station. Netmask The subnet of management stations. Chapter 2 Managing the Citrix NetScaler xix Configuring SNMP Traps and Alarms This section describes configuring SNMP Traps and Alarms. In addition to providing information on specific request, the NetScaler can be configured to display an alarm, or notification message, in a window on a designated computer or computers whenever a particular type of event occurs. This type of notification is called an SNMP trap, and it helps administrators monitor the NetScaler and respond promptly to any issues. Note: SNMP manager to listen for traps with this community name. The default community name is “public”. You can configure the NetScaler to send SNMP traps with source IP other than NSIP. You can set the source IP of an SNMP trap to either MIP or SNIP. The NetScaler supports two types of generic SNMP traps and 57 types of enterprise-specific traps. A maximum of 5 IP addresses can be entered for enterprise-specific trap destinations. A maximum of five IP addresses can be entered for generic trap destinations. If more than 10 authentication traps are generated within 20 seconds, no traps will be generated for the next 60 seconds. The following table shows the generic traps that the NetScaler supports, with brief descriptions: The following table shows the specific SNMP traps that the NetScaler supports, with brief descriptions: Generic trap Name Description authenticationFailure An SNMP management application without access privileges attempts to access the NetScaler. coldStart An SNMP entity, acting in an agent role, reinitializes itself and its configuration may have been altered. linkUp This trap indicates that the sending protocol entity recognizes that one of the communication links represented in the agent's configuration has come up. linkDown This trap indicates that the sending protocol entity recognizes a failure in one of the communication links represented in the agent's configuration. Specific Trap Name Description averageCpuUtilization This trap indicates that the average CPU usage in the multi-processor NetScaler has exceeded the high threshold. averageCpuUtilizationNormal This trap indicates that the average CPU usage in the multi-processor NetScaler has come back to normal after exceeding the predefined threshold . xx Installation and Configuration Guide - Volume 1 changeToPrimary This trap indicates that the NetScaler is now operating in the primary mode. changeToSecondary This trap indicates that the NetScaler is now operating as a secondary node. cpuUtilization This trap indicates that CPU utilization exceeds the predefined threshold. cpuUtilizationNormal CPU utilization has returned to normal after exceeding the predefined threshold and generating a cpuUtilization trap. diskUsageHigh This trap indicates that disk usage has gone high. diskUsageNormal This trap indicates that disk usage has returned to normal. entityup The state of the interface, vserver, or physical service changes to UP. entitydown The state of the interface, vserver, or physical service changes to DOWN. fanSpeedLow This trap indicates that a fan speed has gone below an alarm threshold. Note: The fan speed varies from 4000 through 6500 on all platforms. An alarm threshold of 25% of the minimum is recommended. fanSpeedNormal This trap indicates that a fan speed has returned to normal. interfaceThroughputLow This trap indicates that interface throughput is low. interfaceThroughputNormal This trap indicates that interface throughput has returned to normal. maxClients The number of clients for a service reaches the maximum number allowed for that service. maxClientsNormal The number of clients for a service falls below 70% of the maximum number allowed for that service after a maxClients trap has been generated. memoryUtilization Memory utilization exceeds the predefined threshold. memoryUtilizationNormal Memory utilization returns to normal after a memoryUtilization trap has been generated. Specific Trap Name Description Chapter 2 Managing the Citrix NetScaler xxi monRespTimeoutAboveThresh This trap is sent when the response timeout for a monitor probe exceeds the configured threshold. monRespTimeoutBelowThresh This trap is sent when the response timeout for a monitor probe comes back to normal, less than the threshold set. netscalerLoginFailure This trap is sent to the configured SNMP managers every time an user's login to the NetScaler fails. NetScalerConfigChange A change has been made to your NetScaler configuration. Note: This trap is not generated when the configuration is being restored from the ns.conf file. netScalerConfigSave This trap is sent when the configuration on the NetScaler is saved. serviceRequestRate The request rate on a service exceeds the predefined threshold. serviceRequestRateNormal The request rate on a service returns to normal after a serviceRequestRate trap is generated. serviceRxBytesRate This trap is sent when the request bytes/s of a service exceeds a threshold value. serviceRxBytesRateNormal This trap is sent when the request bytes/s of a service returns to normal. serviceTxBytesRate This trap is sent when the response bytes/s of a service exceeds a threshold value. serviceTxBytesRateNormal This trap is sent when the response bytes/s of a service returns to normal. serviceSynfloodRate This trap is sent when the number of unacknowledged syns for a service exceeds a threshold value. serviceSynfloodNormal This trap is sent when the number of unacknowledged syns for a service returns to normal. sslCertificateExpiry This trap is sent as an advance notification when an SSL certificate is due to expire. svcGrpMemberRequestRate This trap is sent when the request rate on a service group member exceeds a threshold value. svcGrpMemberRequestRateNormal This trap is sent when the request rate on a service group member returns to normal. Specific Trap Name Description xxii Installation and Configuration Guide - Volume 1 svcGrpMemberRxBytesRate This trap is sent when the request bytes per second of a service group exceeds a threshold value. svcGrpMemberRxBytesRateNormal This trap is sent when the request bytes per second of a service group returns to normal. svcGrpMemberTxBytesRate This trap is sent when the response bytes per second of a service group exceeds a threshold value. svcGrpMemberTxBytesRateNormal This trap is sent when the response bytes per second of a service group returns to normal. svcGrpMemberSynfloodRate This trap is sent when the number of unacknowledged SYN packets for a service group exceeds a threshold value. svcGrpMemberSynfloodNormal This trap is sent when the number of unacknowledged SYN packets for a service group returns to normal. svcGrpMemberMaxClients This trap is sent when the number of clients hits the maxClients value for a service group member. svcGrpMemberMaxClientsNormal This trap is sent when the number of clients falls below 70% of maxClients value for a service group member. synflood The rate at which unacknowledged SYN packets are received exceeds the predefined threshold. synfloodNormal The rate at which unacknowledged SYN packets are received returns to normal after a synflood trap has been generated. temperatureHigh This trap indicates that a temperature has gone high. The temperature is measured in degree centigrade ( 0 C). temperatureNormal This trap indicates that a temperature has returned to normal. vServerRequestRate The request rate on a vserver exceeds the predefined threshold. By default, this threshold is. vServerRequestRateNormal The request rate on a vserver returns to normal after a vServerRequestRate trap is generated. vserverRxBytesRate This trap is sent when the request bytes/s of a vserver exceeds a threshold value. vserverRxBytesRateNormal This trap is sent when the request bytes/s of a vServer returns to normal. vserverTxBytesRate This trap is sent when the response bytes/s of a vserver exceeds a threshold value. Specific Trap Name Description Chapter 2 Managing the Citrix NetScaler xxiii For more information on NetScaler health alarms, refer to the appendix on NetScaler Health Counters. Adding SNMP Trap The SNMP traps are asynchronous events generated by the agent to indicate the state of the NetScaler. The destination to which these traps should be sent by the NetScaler is configured through the following procedure: To add a SNMP Trap, use the parameters listed in the following table: In the following example, a SNMP trap, with trap destination IP address 10.102.29.3 and trap class, specific, is created. vserverTxBytesRateNormal This trap is sent when the response bytes/s of a vServer returns to normal. vserverSynfloodRate This trap is sent when the number of unacknowledged syns for a vserver exceeds a threshold value. vserverSynfloodNormal This trap is sent when the number of unacknowledged syns for a vserver returns to normal. voltageLow This trap indicates that a voltage has gone low. voltageNormal This trap indicates that a voltage has returned to normal. voltageHigh This trap indicates that a voltage has gone high. Note: The three traps voltageLow, voltageNormal, and voltageHigh are based on v33main and v33stby (mV). The normal value ranges from 2970mV through 3630mV. Parameter Description Trap Class The Trap type. The Generic type causes the standard SNMP traps supported by the NetScaler to be sent to the destination, while the Specific trap type sets the destination for specific traps. Possible values: generic, specific Trap Destination The IP address of the trap destination. Specific Trap Name Description xxiv Installation and Configuration Guide - Volume 1 To add an SNMP Trap 1. In the left pane, expand System, click SNMP and click Traps. The Traps page appears on the right pane. 2. Click Add. The Add Trap dialog box appears. 3. In the IP Address text box, type the IP address. For example, 10.102.29.3. 4. Click Add. To add an SNMP Trap using the NetScaler command line At the NetScaler command prompt, type: add SNMP trap specific 10.102.29.3 Modifying SNMP Traps This section covers procedure for modifying SNMP traps. This section covers the following topics: • Setting the Trap Destination Port • Setting the SNMP Version of the Trap PDU to be Sent • Setting the Source IP of the SNMP Traps • Setting the Community String • Setting the Severity of the Trap Setting the Trap Destination Port This section covers procedure for setting the destination port of the trap. The trap destination port is the one on which the SNMP manager receives traps. If this is not configured correctly the traps will not reach the SNMP manager. To set the destination port, use the parameters listed in the following table: In the following example, the SNMP destination port is set to 163. The following table summarizes the parameters values: Parameter Description Destination Port The destination port of the SNMP trap. Default value: 162 Minimum value: 1 Parameter Description Destination Port The destination port of the SNMP trap. Default value: 162 Minimum value: 1 Chapter 2 Managing the Citrix NetScaler xxv To set the trap destination port 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page, select the trap for which you want to set the trap destination port. 3. In the Destination Port, type a destination port, for example, 163. 4. Click OK. To set the trap destination port using the NetScaler command line At the NetScaler command prompt, type: set snmp trap specific 10.102.29.3 destPort 163 Setting the SNMP Version of the Trap PDU to be Sent This section covers procedure for setting the SNMP Version. The SNMP version is sent with the trap PDU. To set SNMP version, use the parameters listed in the following table: In the following example, the SNMP version, V1, option is selected: To set SNMP version of the trap 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page select the trap for which you want to set the SNMP version to be sent with the trap. 3. In the Version, select a SNMP Version, for example, V1. 4. Click OK. Version The SNMP version of the trap PDU to be sent. Source IP The source IP of the SNMP traps. Community Name SNMP trap community string Default value: public. Parameter Description Version The SNMP version of the trap PDU to be sent. Parameter Description xxvi Installation and Configuration Guide - Volume 1 Setting the Source IP of the SNMP Traps You can configure the NetScaler to send SNMP traps with source IP other than NSIP. You can set the source IP of an SNMP trap to either MIP or SNIP. To set the source IP of the SNMP traps, use the parameters listed in the following table: In the following example, an IP address, 10.102.29.54 is set for the source IP of SNMP trap: To set the source IP of the SNMP trap 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page select the trap for which you want to set the community string. 3. In the source IP text box, type an IP address. For example, 10.102.29.54. 4. Click OK. Setting the Community String This section covers procedure for setting the community string. The community string is sent with the trap PDU. To set community string of the SNMP traps, use the parameters listed in the following table: To set the community string 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page select the trap for which you want to set the community string. 3. In the Community Name text box, type the name of the SNMP string which you want to include in the SNMP traps. For example, com1. 4. Click OK. Parameter Description Source IP The source IP of the SNMP traps. Parameter Description Community Name The SNMP trap community string. The default value is public. Chapter 2 Managing the Citrix NetScaler xxvii Setting the Severity of the SNMP Trap You can configure a NetScaler to send specific traps based on severity, to the SNMP manager. There are 5 severity types: Critical, Major, Minor, Warning, Informational. These severity types are only tags which are for your ease. The trap is sent only when the severity of the alarm matches the severity configured in traps. To set minimum severity of the SNMP traps, use the parameters listed in the following table: To set the severity of the trap 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page select the trap for which you want to set the minimum severity. 3. Click Open. The Modify SNMP Trap dialog box appears. 4. In Severity, select a severity option. For example, Major. 5. Click Ok. Removing a SNMP Trap This section covers procedure for removing SNMP traps. When a trap is removed the trap messages are no longer send to this trap destination. To remove a SNMP trap 1. In the left pane, expand System, click SNMP, and then click Traps. The SNMP Traps page appears on the right pane. 2. In the SNMP Traps page, select the trap which you want to remove. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. Configuring SNMP Alarm This section covers procedure for configuring SNMP Alarms. This section covers the following topic: Parameter Description Severity The minimum severity of the alarms to be sent to this trap destination. By default all traps will be sent to this trap destination. xxviii Installation and Configuration Guide - Volume 1 • Setting the Severity of the SNMP Alarm • Disabling a SNMP Alarm • Enabling a SNMP Alarm Setting the Severity of the SNMP Alarm This section describes procedure for setting the severity of the SNMP alarms. There are 5 severity types: Critical, Major, Minor, Warning, Informational. These severity types are only tags which are for your ease. The trap is sent only when the severity of the alarm matches the severity configured in traps. To set minimum severity of the SNMP traps, use the parameters listed in the following table: In the following example, an IP address, 10.102.29.54 of type subnet IP address and subnet mask 255.255.255.0 is created. To set the severity of the alarm 1. In the left pane, expand System, click SNMP, and click Alarms. The SNMP Alarms page appears on the right pane. 2. Click Open. The Configure SNMP Alarm dialog box appears. 3. In Severity, select a severity option. For example, Major. 4. Click Ok. Disabling an SNMP Alarm This section covers disabling of SNMP alarms. When you disable a SNMP alarm, the NetScaler will not generate corresponding trap messages when some events occur. For example when you disable Login-Failure SNMP alarm, the NetScaler will not generate a trap message when a login failure happens in the NetScaler. To disable an SNMP alarm 1. In the left pane, expand System, click SNMP, and click Alarms. The Alarms page appears on the right pane. 2. In the Alarms page, select a SNMP alarm which you want to disable. For example, Login-Failure. Parameter Description Severity The severity level of this alarm. Possible values: Critical, Major, Minor, Warning, Informational. Chapter 2 Managing the Citrix NetScaler xxix 3. Click Disable. Enabling a SNMP Alarm This section covers procedure for enabling SNMP alarms. When you enable a SNMP alarm, the NetScaler will generate corresponding trap messages when some events occur. Some NetScaler alarms are enabled by default. To enable alarms 1. In the left pane, expand System, click SNMP, and click Alarms. The Alarms page appears on the right pane. 2. In the Alarms page, select a disabled SNMP alarm which you want to enable. For example, Login-Failure. 3. Click Enable. Removing SNMP Managers This section covers procedure for removing of SNMP manager. When you remove a SNMP manager from the NetScaler the manager can no longer query the NetScaler. Note: If there is no SNMP manager configured in the NetScaler, network management applications from any host computer can access the NetScaler. In the following example, a SNMP manager having IP address 10.102.29.5 and subnet mask 255.255.255.0 is removed. To remove a SNMP manager 1. In the left pane, expand System, click SNMP, and then click Managers. The SNMP Managers page appears on the right pane. 2. In the SNMP Managers page, select the manager which you want to remove. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. Adding a SNMP Community This section covers procedure for adding a SNMP community string. You add SNMP community string to grant access to an SNMP network management application to manage the NetScaler. The community also defines the specific management tasks that you can perform. Use the following procedure to set the management privileges for the network management application. xxx Installation and Configuration Guide - Volume 1 To add a SNMP community, use the parameters listed in the following table: In the following example, a community, Com_All, is added with access permission ALL. To add a community string 1. In the left pane, expand System, click SNMP, and then click Community. The SNMP Community page appears in the right pane. 2. Click Add. The Add SNMP Community dialog appears. 3. In the Community String text box, type a name for the community to be added. For example, Com_All. 4. In Permission, select ALL option. 5. Click Create. Removing a SNMP Community This section covers procedure for removing community string. when you remove a community string, the SNMP managers are not able to use the community to manage the NetScaler. In the following example, a community, Com_All, is removed. To remove a community string 1. In the left pane, expand System, click SNMP, and click Community. The SNMP Community page appears on the right pane. 2. In the SNMP Community page, select the community which you want to remove. For example, Com_All. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. Configuring SNMP V3 This section describes configuring SNMP V3. This section covers the following topics: • How It Works Parameter Description Community Name The SNMP community string. Permissions The access privileges. Possible values: GET, GET NEXT, GET BULK, ALL. Chapter 2 Managing the Citrix NetScaler xxxi • Configuring SNMP V3 HowIt Works Simple Network Management Protocol Version 3 (SNMPv3) is based on the basic structure and architecture of SNMPv1 and SNMPv2. However, SNMPv3 enhances the basic architecture to incorporate administration and security capabilities such as authentication, access control, data integrity check, data origin verification, message timeliness check, and data confidentiality. Salient Features SNMPv3 provides security features such as message-level security and access control. To implement these features, SNMPv3 introduces the following: • User-based Security Model (USM) • View-based Access Control Model (VACM) User-based Security Model User-based Security Model (USM) provides message-level security. It enables you to configure users and security parameters at the agent and the manager to ensure: • Data integrity: To protect messages from being modified during transmission through the network. • Data origin verification: To authenticate the user who sent the message requests. • Message timeliness: To protect against message delays or replays. • Data confidentiality: To protect the content of messages from being disclosed to unauthorized entities or individuals. View-based Access Control Model View-based Access Control Model (VACM) allows you to configure access rights to a specific subtree of the MIB based on various parameters such as security level, security model, user name, and view type. It enables you to configure agents to provide different levels of access to the MIB to different managers. SNMPv3 Security Entities The Citrix NetScaler supports the following entities that enable you to implement the security features of SNMPv3: • SNMP Engine • SNMP Views xxxii Installation and Configuration Guide - Volume 1 • SNMP Groups • SNMP Users SNMP Engine SNMP engines are service providers that reside in the SNMP agent. They provide services such as sending or receiving and authenticating messages. SNMP engines are uniquely identified using engine IDs. SNMP Views SNMP views restrict user access to specific portions of the MIB. SNMP views are used to implement access control. SNMP Groups SNMP groups are logical aggregations of SNMP users. They are used to implement access control and to define the security levels. You can configure an SNMP group to set access rights for users assigned to that group, thereby, restricting the users to specific views. SNMP Users SNMP users are the SNMP managers that are configured at the agent to access the MIB. Each SNMP user is assigned to an SNMP group. These entities function together to implement the SNMPv3 security features. Views are created to allow access to subtrees of the MIB. Then, groups are created with the required security level and access to the defined views. Finally, users are created and assigned to the groups. The configuration of these entities is explained in the next section. Configuring SNMP V3 To implement message authentication and access control, you need to: • Set the Engine ID • Configure Views • Configure Groups • Configure Users The following sections describe the tasks in detail: Note: For information on the parameters used in these tasks, refer to the Command Reference Guide or the MAN pages. Chapter 2 Managing the Citrix NetScaler xxxiii Setting the Engine ID As mentioned in the previous section, the SNMP engine ID uniquely identifies an SNMP engine. The NetScaler has an unique engineID based on the MAC address of one of its interfaces. It is not necessary to override this engineID. However, if you want to change this engine ID, then you can reset it. To set the Engine ID, use the parameters listed in the following table: To set the engine ID 1. In the left pane, expand System, click SNMP, and click Users. The SNMP Users page appears on the right pane. 2. Click Configure Engine ID. The Configure Engine ID dialog box appears. 3. In the Engine ID text box, type an engine ID. For example, 8000173f0300c095f80c68. 4. Click OK. Adding SNMP View This section covers removing of SNMP view. SNMP views are used to implement access control. To add a SNMP View, use the parameters listed in the following table: To add a SNMP view 1. In the left pane, expand System, click SNMP, and then click View. The SNMP View page appears on the right pane. 2. Click Add. The Add SNMP View dialog box appears. 3. In the Name text box, type a name for the SNMP view you want to add. For example, View1. 4. In the Subtree text box, type the subtree of the MIB. 5. Click Create. Parameter Description EngineID The engine ID of the SNMP agent. Parameter0 Description Name The name of the SNMP view. Subtree The subtree of the MIB. xxxiv Installation and Configuration Guide - Volume 1 Adding SNMP Group You need to configure an SNMP group to set access rights for users assigned to that group. To add a SNMP Group, use the parameters listed in the following table: To add a SNMP group 1. In the left pane, expand System, click SNMP, and then click Group. The SNMP Groups page appears on the right pane. 2. Click Add. The Add SNMP Group dialog box appears. 3. In the Name text box, type a name for the SNMP group you want to add. For example, View1. 4. In Read View Name, select a configured SNMP view, which you want to associated to the Group. 5. Click Create and click Close. Adding SNMP User You need to configure users at the agent, and assign each user to a group. To add a SNMP user, use the parameters listed in the following table: To add a SNMP user 1. In the left pane, expand System, click SNMP, and then click Users. The SNMP Users page appears on the right pane. 2. Click Add. The Add SNMP User dialog box appears. 3. In the Name text box, type a name for the SNMP user you want to add. For example, user1. 4. In Group Name, select a configured SNMP group, which you want the user to be part of. Parameter Description Name The name of the SNMP view. Read View The SNMP view to be associated with this group. Parameter Description Name The name of the SNMP user. Read View The SNMP view to be associated with this user. Chapter 2 Managing the Citrix NetScaler xxxv 5. Click Create and click Close. Note: The view, group, and user configuration are synchronized and propagated to the secondary node in an HA pair. However, the engineID is neither propagated nor synchronized as it is unique to each NetScaler. Users and Groups The NetScaler allows you to create users and groups, for managing access and allowing individual user’s access to match their duties and needs. This section explains how to create and manage these users and groups. Howit Works The NetScaler allows you to create users and groups, for managing access and allowing individual users access to match their duties and needs. To manage the day-to-day tasks to your NetScaler, you should create NetScaler user accounts and groups, and associate each user with the appropriate groups. An user account is a logon / password combination used by a specific person or process to log on to the NetScaler. A group is a set of user accounts to which a specific set of command policies applies. A command policy is a rule that allows or prohibits an user or group to access or modify a specific part of the NetScaler configuration. Before you configure users and groups, you must understand the role of the system global scope. Within the NetScaler operating system, a scope is a category of user accounts and groups that meet certain criteria. System global is the set of all user accounts and groups on the NetScaler except for the nsroot user account. System global policies and parameters apply to all user accounts and groups except for the nsroot user account. Before you can create and apply command policies, you must create the user accounts and groups to which those policies can then be applied. All NetScalers are configured with a default user account, the nsroot user account. The following are important characteristics of this user account: • The default administrator user account (nsroot) is immutable, and always has full NetScaler privileges. xxxvi Installation and Configuration Guide - Volume 1 • The nsroot user account is not subject to any policy which is configured on the NetScaler. This means that command and authentication polices cannot be used to modify the nsroot user's access to the NetScaler. • The nsroot user account cannot be bound in to group memberships. • The nsroot user account's default password is nsroot. It is strongly advised that you change your NetScaler’s nsroot password immediately on powering it up for the first time. You use the nsroot user account during initial installation and configuration of the NetScaler, and for certain types of troubleshooting. You should not log on as nsroot for other purposes. Instead, you should create individual user accounts and groups for administrators, and create command policies that define access and privileges for each user account. Configuring Users and Groups This section explains how to create and manage users and groups, and covers the following procedure: • Adding an User Account • Adding a NetScaler Group • Binding Users to a Group • Verifying the Configuration Adding an User Account This section covers procedure for adding an user account. An user account is a logon / password combination used by a specific person or process to log on to the NetScaler. To add an user account, use the parameters listed in the following table: In the following example, a NetScaler user, johnd, is created. To add an user account 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. Parameter Description User Name The name you want to assign to user account. Password The user password you want to assign to this user account. Chapter 2 Managing the Citrix NetScaler xxxvii 2. Click Add. The Create User dialog box appears. 3. In the User Name text box, type a name for the user you want to create, for example, johnd. 4. In the Password text box, type a password you want to assign to the user account. 5. In the Confirm Password text box, type the password again that you have typed in the Password text box. 6. Click Create. Adding Groups This section covers procedure for adding groups. A group is a set of user accounts to which a specific set of command policies applies To add a group, use the parameters listed in the following table: In the following example, a NetScaler group, Managers, is created. To add a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. Click Add. The Create Group dialog box appears. 3. In the Group Name text box, type a name for the group you want to create. For example, Managers. 4. Click Create. Binding User to a Group You bind a NetScaler user account to a NetScaler group to which you want to associate that user account by using the following procedure. You can bind each user account to more than one group. Binding your user accounts to multiple groups may allow more flexibility when applying command policies, which are discussed in section custom based policies. To bind users to a group, use the parameters listed in the following table: Parameter Description Group Name The name for the NetScaler group. Parameter Description User Name The name for the NetScaler user to be bound to the group. xxxviii Installation and Configuration Guide - Volume 1 In the following example, the user account, johnd, is bound to the group, Managers. To bind an user to a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. Click Open. The Configure Group dialog box appears. 3. Under the Member of section, select the user you want to bind to the group, from the Available Users table and click Add. 4. The bound users are shown in Configured Users. Once the NetScaler users and groups are created, you can view details about them. Verifying the Configuration This section covers procedure for viewing the details of the created user and groups. This section covers the following topics: • Viewing an User • Viewing a Group Viewing an user This section covers procedure for viewing NetScaler users. In the following example, you will view the user, johnd. To view an user 1. In the left pane, expand System and click Users. 2. The System Users page appears on the right pane with all the configured users. Viewing a Group This section covers procedure for viewing NetScaler groups. In the following example, you will view the user, Managers. To view a group 1. In the left pane, expand System and click Group. 2. The System Groups page appears on the right pane with the configured groups. Chapter 2 Managing the Citrix NetScaler xxxix Managing Users and Groups This section covers procedure for managing users and groups. Changing User Password This section covers the procedure for changing the password for user accounts configured in the NetScaler. To change the NetScaler user password, use the parameters listed in the following table: In the following example, the password of user account, johnd, is changed. To change the user password 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. 2. Select the user account for which you want to change the password. For example, johnd. 3. Click Open. In the Password text box, type a password you want to assign to the user account. 4. In the Confirm Password text box, type the password again which you have provided in the Password text box. 5. Click OK. Note: When you enter the password when adding an user account, it is displayed in clear text. However, NetScaler user passwords are encrypted on the NetScaler. Resetting the Default Administrator (nsroot) Password If you have lost the nsroot password, you can recover it as described in this section. The nsroot account provides complete access to all features of the NetScaler. Therefore, to preserve security, the nsroot account should be used only when necessary, and only individuals whose duties require full access should know the nsroot account password. Also for security, it is advisable to change the nsroot password frequently. If you lose the password, you can reset it as described here. Parameter Description Password The password you assign for the user account. xl Installation and Configuration Guide - Volume 1 To reset the nsroot password, you must boot the NetScaler into single user mode, mount the file systems in read/write mode, and remove the set NetScaler user nsroot entry from the ns.conf file. This process does not actually recover your nsroot password, but it does allow you to reset it to the default setting, nsroot. You can then choose a new password. To reset the nsroot password 1. Connect a computer to the NetScaler serial port, and log on. Note: You cannot log on via ssh to perform this procedure; you must connect directly to the NetScaler. As the operating system starts, it displays the following message: Hit [Enter] to boot immediately, or any other key for command prompt. Booting [kernel] in #seconds. 2. Press the space bar. The following message is displayed: Type ‘?’ for a list of commands, ‘help’ for more detailed help. ok 3. Type boot -s, and press the Enter key to start the system in single user mode. After the system boots, it displays the following message: Enter full pathname of shell or RETURN for /bin/sh: 4. Press the <Enter>key to display the #prompt, and type the following command at the prompt to mount the file systems: mount /dev/ad0s1a /flash 5. Using a text editor of your choice, edit the /flash/nsconfig/ns.conf file and remove the set system user nsroot entry. 6. Save the file and exit the text editor. 7. Type reboot and press the Enter key to reboot the NetScaler. When the NetScaler completes rebooting, it prompts for username and password. 8. Log on as nsroot, with the password nsroot. Once logged in to the NetScaler, you will be required to enter a new nsroot user password. 9. Follow the prompts to change the password. Chapter 2 Managing the Citrix NetScaler xli 10. Exit the config ns menu with option. Removing User Accounts This section covers procedure for removing the user accounts from the NetScaler. If your user account has the rights to remove another user, then you can remove another user account in the NetScaler. The nsroot account cannot be removed by any user and also the nsroot user can remove any other user account. In the following example, the group, Managers, is removed from the NetScaler. To remove an user account 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. 2. In the System Users page, select the user account which you want to remove. For example, johnd. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. Removing Groups This section covers procedure for removing groups from the NetScaler. When you remove a group, all the users and command policies which are currently bound to the group, are unbound. In the following example, the group, Managers, is removed from the NetScaler. To remove a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. In the System Groups page, select the group which you want to remove. For example, Managers. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. Role-Based Authorization Command Policies This section covers the functions of role-based authorization command policies (RBAC) and how to create and manage them. xlii Installation and Configuration Guide - Volume 1 HowIt Works Command policies are rules that control what individual users may access and do on the NetScaler. The NetScaler users and groups functions allow you to define who has access to the NetScaler. Command policies allow you to define what parts of the NetScaler configuration an user or group is permitted to access and modify. In other words, command policies regulate which commands, command groups, vservers, and other elements NetScaler users and groups are permitted to use. Configuring RBAC This section covers configuring role based command policies (RBAC). Here are the key points to keep in mind when defining and applying command policies. • No global command policies may be created on the NetScaler. Command policies must be bound directly to NetScaler users and groups. • Users or groups with no associated command policies are subject to the default DENY -ALL command policy, and will therefore be unable to execute any commands until the proper command policies are bound to them. • All users inherit the policies of the groups to which they belong. • When you bind it to an user account or group, you must assign priorities to a command policy. This allows the NetScaler to determine which policy has priority when two or more conflicting policies apply to the same user accounts or groups. • The following commands are available to any user by default and are unaffected by any command policies you specify: help cli, show cli attribute, clear cli prompt, alias, unalias, batch, source, help, history, man, quit, exit, whoami, config, set cli mode, unset cli mode, show cli mode, set cli prompt, and show cli prompt. Using Built-in Command Policies Four default command policies are available on the NetScaler. The following lists these policies: Policy Name Description read-only Allows read-only access to all show commands except for the NetScaler command group show commands and show runningconfig and show ns.conf commands. Chapter 2 Managing the Citrix NetScaler xliii When creating command policies, you must bind them to the user accounts and groups to which they apply. • If the built-in command policies provide the levels of access control you need, proceed to Section : Binding Command Policies to Users and Groups. • If you need different levels of control than are provided by the built-in command policies, proceed to Section , “Creating Custom Based Command Policies.” Creating CustomBased Command Policies This section covers procedure for custom based policies. Note: Regular expression support is offered for those users with the resources to maintain more customized expressions and those deployments that require the flexibility that regular expressions offer. For most users, the built-in command policies discussed in Section , “Binding Built-in Command Policies to Users and Groups,” should be sufficient. Users who need additional levels of control, but are unfamiliar with regular expressions, may want to use only simple expressions, such as those in the examples provided in this section, to maintain policy readability. When you use a regular expression to create a command policy, keep the following in mind. • When you use regular expressions to define commands that will be affected by a command policy, you must enclose the commands in double quotes. For example, if you want to create a command policy named allowShow that includes all commands that begin with show, you should type the following: “^show .*$” If you want to create a command policy that includes all commands that being with rm, you should type the following: operator Allows read-only access as above, and in addition allows access to enable and disable commands on services and servers. This policy also allows access to set services and servers as ‘accessdown.’ network Permits total NetScaler access, excluding NetScaler commands, the shell command, and the show ns.conf and sh runningconfig commands. superuser Grants full NetScaler privileges, giving exactly the same privileges as the nsroot user. Policy Name Description xliv Installation and Configuration Guide - Volume 1 DENY “^rm .*$” • Regular expressions used in command policies are case insensitive. The following table gives examples of regular expressions: The following shows the command specifications for each of the built-in command policies: The following examples show how you can use the command specification regular expressions .The default_deny_override command policy is especially useful, since it allows you to override the default NetScaler-level DENY rule and grant access only to the specific user accounts and groups that need it. Command Specification Matches these Commands “^r m\ s+. *$” All remove actions, because all remove actions begin with the rm string, followed by a space and additional parameters and flags. “^show\ s+. *$” All show commands, because all show actions begin with the show string, followed by a space and additional parameters and flags. “^shel l $” The shell command alone, but not combined with any other parameters or flags. “^add\ s+vser ver \ s+. *$” All create a vserver actions, which consist of the add vserver command, followed by a space and additional parameters and flags. “^add\ s+( l b\ s+vser ver ) \ s+ . *” All create an lb vserver actions, which consist of the add lb vserver command, followed by a space and additional parameters and flags. “^set \ s+l b\ s+. *$” All commands that configure load balancing settings at the command group level. Policy Name Command Specification Regular Expression read-only ( ^man. *) | ( ^show\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns r unni ngConf i g) . *) | ( ^st at . *) operator ( ^man. *) | ( ^show\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns r unni ngConf i g) . *) | ( ^st at . *) | ( ^set . *- accessdown. *) | ( ^( enabl e| di sabl e) ( ser ver | ser vi ce) . *) network ^( ?! shel l ) \ S+\ s+( ?! syst em) ( ?! ns ns. conf ) ( ?! ns r unni ngConf i g) . * superuser . * Chapter 2 Managing the Citrix NetScaler xlv Binding Command Policies to Users and Groups Once you have defined your command policies, you must bind them to the appropriate user accounts and groups. When you create each binding, you must also set a priority on the policy so that the system can determine which command policy to follow when two or more applicable command policies are in conflict. The order in which command policies are evaluated: • Command policies bound directly to user and the corresponding groups are evaluated based on the priority number. A command policy with a lower priority number is evaluated before one with a higher priority number. Therefore, any privileges the lower-numbered command policy explicitly grants or denies are not overridden by a higher-numbered command policy • When two command policies one bound to an user account and other bound to a group have the same priority number then the command policy bound directly to the user account is evaluated first. Binding Command Policies to an user To bind users to a group, use the parameters listed in the following table: In the following example, a command policy is bound to the user, johnd. To bind command policies to an user 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. 2. Select an user for which you want to bind command policies. For example, johnd. 3. Click Open. The Configure Group dialog box appears. The Member of section shows a list of command policies that can be bind to the group. 4. In the Active column, select the check box against the policy that you want to bind, change the priority in the Priority list box, for example, 1, and click OK. Parameter Description User Name The user account Command Policies The name of the command policy you want to bind to the user account. xlvi Installation and Configuration Guide - Volume 1 Binding Command Policies to a Group To bind users to a group, use the parameters listed in the following table: In the following example, a command policy is bound to the group, Managers. To bind command policies to a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. Select a group for which you want to bind command policies. For example, Managers. 3. Click Open. The Configure Group dialog box appears. The Member of section shows a list of command policies that can be bind to the group. 4. In the Active column, select the check box against the policy that you want to bind, change the priority in the Priority list box, for example, 1, and click OK. User Accounts and Command Policies The following example will show you how you create a complete set of user accounts, groups, and command policies, and then bind each policy with the appropriate groups and users. The company, Example Manufacturing, Inc., has three users who will access the NetScaler: • John Danilov. The IT manager. J ohn needs to see all parts of the NetScaler configuration, but does not need to modify anything. • Maria Ramirez. The lead IT administrator. Maria needs to be able to see and modify all parts of the NetScaler configuration except for NetScaler commands (which local policy dictates must be performed while logged on as nsroot). • Michael Baldrock. The IT administrator in charge of load balancing. Michael needs to be able to see all parts of the NetScaler configuration, but needs to modify only the load balancing functions. The following table shows the breakdown of network information, user account names, group names, and command policies for the example company: Parameter Description User Name The user account Command Policies The name of the command policy you want to bind to the user account. Chapter 2 Managing the Citrix NetScaler xlvii The following description walks you through the process of creating a complete set of user accounts, groups, and command policies on Example Manufacturing, Inc., NetScaler, ns01.example.net. The discussion includes procedures for binding the appropriate user accounts and groups to one another, and binding appropriate command policies to the user accounts and groups. This procedure illustrates how you can use prioritization to grant precise access and privileges to each user in the IT department. The example assumes that initial installation and configuration have already been performed on the NetScaler. To create johnd, mariar, and michaelb user accounts 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. 2. Click Add. The Create User dialog box appears. 3. In the User Name text box, type johnd. 4. In the Password text box, type a password you want to assign to the user account. 5. In the Confirm Password text box, type the password again that you have typed in the Password text box. 6. Click Create. 7. Repeat step2 -6 to create user accounts and passwords for Maria Ramirez and Michael Baldrock. Note: You would, of course, assign different passwords for these users to protect the security of the NetScaler. For optimal security, passwords should include a mix of upper- and lower-case letters, numbers, and symbols. Field Value Note NetScaler hostname ns01.example.net User accounts johnd mariar michaelb John Danilov, IT manager Maria Ramirez, IT administrator Michael Baldrock, IT administrator Groups Managers SysOps All managers All IT administrators Command Policies read_all modify_lb modify_all Allow complete read-only access Allow modify access to load balancing Allow nearly complete modify access xlviii Installation and Configuration Guide - Volume 1 To add groups 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. Click Add. The Create Group dialog box appears. 3. In the Group Name text box, type Managers. 4. Click Create. 5. Repeat step1-4 to create a group named SysOps. To bind users to a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. 2. Select the group Managers. 3. Click Open. The Configure Group dialog box appears. 4. Under the Member of section, select the user johnd from the Available Users table and click Add to bind to the Managers. 5. The bound user johnd is shown in Configured Users. 6. Repeat step1-5 to bind users mariar and michaelb to the group SysOps. To add command policies 1. In the left pane, expand System and click Command Policies. The Command Policies page appears on the right pane. 2. Click Add. The Create Command Policies dialog box appears. 3. In the Policies Name text box, type read_all. 4. In the Action list, select Allow. 5. In the Command Spec, enter “(^show\s+(?!system)(?!ns ns.conf)(?!ns runningConfig).*)|(^stat.*)”, with the help of policy components. 6. Click Create. 7. Repeat step 1-5, to create command policy named modify_lb with action as Allow and having command spec “^set\s+lb\s+.*$” 8. Repeat step 1-5, to create command policy named modify_all with action as Allow and having command spec “^\S+\s+(?!system).*” To bind command policy to a group 1. In the left pane, expand System and click Groups. The System Groups page appears on the right pane. Chapter 2 Managing the Citrix NetScaler xlix 2. Select the group Managers. 3. Click Open. The Configure Group dialog box appears. The Member of section shows a list of command policies that can be bind to the group. 4. In the Active column, select the check box against the read_all policy, change the priority in the Priority list box to1, and click OK. Note: Assigning a priority of 1 to this binding ensures that any other command policy assigned to this group or to an individual account will take priority. This allows you to use this policy to grant default NetScaler-wide read access to any part of the Application Switch configuration. 5. Repeat step 1-4, to bind the read_all command policy to the SysOps group, also assigning it a priority of 1. To bind command policies to an user 1. In the left pane, expand System and click Users. The System Users page appears on the right pane. 2. Select the user account michaelb. 3. Click Open. The Configure User dialog box appears. The Member of section shows a list of command policies that can be bind to the user. 4. In the Active column, select the check box against the modify_lb policy, change the priority in the Priority list box to5, and click OK. Note: Assigning a priority of 5 to this binding ensures that it will take priority over any “background” command policy with a priority of 1, but it will not take priority over a command policy with an assigned priority greater than 5. The configuration you've just created results in the following: • J ohn Danilov, the IT manager, has read-only access to the entire NetScaler, but cannot make modifications. • Maria Ramirez, the IT lead, has near-complete access to all areas of the NetScaler configuration, having to log on only to perform NetScaler-level commands. • Michael Baldrock, the IT administrator responsible for load balancing, has read-only access to the NetScaler configuration, and can modify the configuration options for load balancing. l Installation and Configuration Guide - Volume 1 As mentioned earlier, the set of command policies that applies to a specific user is a combination of command policies applied directly to the user's account, plus command policies applied to the group(s) of which the user is a member. Each time an user enters a command, the operating system searches the command policies for that user until it finds a policy with an explicit ALLOW or DENY action that matches the command. When it finds a match, the operating system stops its command policy search and allows or denies access to the command. If the operating system finds no matching command policy, it denies the user access to the command, in accordance with the NetScaler’s default deny policy. Note: When placing an user into multiple groups, take care not to cause unintended user command restrictions or privileges. To avoid these conflicts, when organizing your users in groups, it's good to bear in mind the NetScaler's command policy search procedure and policy ordering rules. Configuring Clock Synchronization You can configure your NetScaler to synchronize its local clock with a Network Time Protocol (NTP) server. This will ensure that its clock has the same date and time settings as the other servers on your network. To enable clock synchronization on your NetScaler 1. Log on to the NetScaler CLI. 2. Switch to the shell prompt. 3. Copy the ntp.conf file from the /etc directory to the /nsconfig directory. If it already exists in the /nsconfig directory, ensure that you remove the following entries from the ntp.conf file: restrict localhost restrict 127.0.0.2 These entries are required only if you want to run the device as a time server. However, this feature is not supported on the NetScaler. 4. Edit /nsconfig/ntp.conf, and add the IP address for the desired NTP server under the file’s server and restrict entries. 5. Create a file and name it rc.netscaler in the /nsconfig directory, if the file does not already exist in the directory. 6. Edit /nsconfig/rc.netscaler, and add the following entry. Chapter 2 Managing the Citrix NetScaler li /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ ntpd.log & This entry starts the ntpd service, checks the ntp.conf file, and logs messages in the /var/log directory. Note: When the time difference between the NetScaler and the time server is more than 1000 sec, the ntpd exits with a message to the NetScaler log. To avoid this, you need to start ntpd with the -g option, which will forcibly sync the time. Add the following entry in /nsconfig/rc.netscaler: /usr/sbin/ntpd -g -c /nsconfig/ntp.conf -l /var/ log/ntpd.log & If you dont want to forcibly sync the time due to the large difference, you can set the date manually and then start ntpd again. You can check the time difference between the NetScaler and the time server by executing the following command in the shell: ntpdate -q <IP address or domain name of the NTP server> 7. Reboot the NetScaler to enable clock synchronization. Note: If you want to restart the NetScaler at a later time but start the time synchronization process, run the following command from the shell prompt: /usr/sbin/ntpd -c /nsconfig/ntp.conf -l /var/log/ ntpd.log & This command starts the time synchronization process. However, if you want the process to start every time the NetScaler is restarted, ensure that you have added it to the rc.netscaler file, as described in step 6. If you do not have a local NTP server, you can find a list of public, open access, NTP servers at the official NTP site, http://www.ntp.org, under Public Time Servers List. Before configuring your NetScaler to use a public NTP server, be sure to read the Rules of Engagement page, (link included on all Public Time Servers pages). lii Installation and Configuration Guide - Volume 1 NetScaler Logging This section gives instructions for logging on the NetScaler, and for configuring the logging features of the NetScaler. The NetScaler allows you to customize logging of NetScaler and SSL VPN access events to the needs of your site. You can direct these logs either to files on the NetScaler, or to external log servers. The NetScaler uses the Audit Server Logging feature for logging the states and status information collected by different modules in the kernel as well as in the user-level daemons. For more information on the Audit Server Logging feature, refer to the chapter Audit Server Logging. You can customize two logging functions for NetScaler events—messaging and syslog. The NetScaler’s internal event message generator that passes log entries to the syslog server. The syslog server accepts these log entries and logs them. Logging NetScaler Events This subsection describes how to configure NetScaler event logging. Logging of NetScaler and VPN events is enabled by default. To disable logging of NetScaler and VPN events, you must add the entries described below to the end of the /nsconfig/rc.conf file, with each entry on a separate line. If the file does not already exist, you must create it. Caution: For High Availability (HA) installations, NetScaler logging configurations are not automatically propagated across an HA pair. You must either manually copy the configuration files to the HA peer, or repeat your file creations and modifications on the peer. Disabling Events Logging To disable NetScaler events logging, add the following entry to the end of the / nsconfig/rc.conf file, on a separate line: nssyslog_enable="NO" To disable VPN events logging, add the following entry to the end of the / nsconfig/rc.conf file, on a separate line: nsvpnl og_enabl e=" NO" Disabling Syslog The syslog daemon is enabled by default. For disabling syslog, add the following entry to the end of the /nsconfig/rc.conf file, on a separate line: Chapter 2 Managing the Citrix NetScaler liii sysl ogd_enabl e=" NO" Customizing Syslog This section explains how to modify the syslog configuration of your NetScaler. Editing Syslog File To customize the syslog configuration, you begin by copying the base syslog.conf file from /etc to /nsconfig/syslog.conf. When the NetScaler restarts, the dynamically generated /etc directory is recreated, and your customized syslog.conf file is used instead of the base version. Overriding nssyslog Local Facility NetScaler messages are configured to use the syslog local0 facility, logging to / var/log/ns.log. To override this, you must make two edits. First, you add the following line to /nsconfig/rc.conf: nssysl og_f l ags=" - s sysl ogf aci l i t y=0 - s sysl og=1 - d event wai t " You must create a new file if one does not already exist. Now, replace the local facility value, syslogfacility=0, with the desired level. For example, to configure the local2 facility for NetScaler logs, your new entry for the syslogfacility value should read syslogfacility=2. Next, you must edit the syslog configuration to reflect the new value. If you have not previously copied /etc/syslog.conf to /nsconfig, do so now. You then open / nsconfig/syslog.conf in a text editor, and change the following line to use the new local facility value: l ocal 0. * / var / l og/ ns. l og For example, if you want to use the local2 facility, change local0.* to local2.*. Note: When editing syslog.conf, be sure to use tabs as field separators. Overriding nsvpn Local Facility By default, VPN messages are configured to use the syslog local1 facility, logging to /var/log/nsvpn.log. To use another syslog local facility for VPN logging, you must change entries in two files. First, edit the /nsconfig/rc.conf file, creating a new file if it does not already exist. In this file, add the following line, changing the syslogfacility value to your desired syslog local facility number: nsvpnl og_f l ags=" - s sysl ogf aci l i t y=1 - s sysl og=1 - d accessl ogs" liv Installation and Configuration Guide - Volume 1 For example, if you want to use the local4 facility instead of the default local1 facility, you must change the syslogfacility entry to syslogfacility=4. Next, you need to update /nsconfig/syslog.conf to reflect the new local logging facility value. To do this, edit /nsconfig/syslog.conf and change the following line to use the new local facility value: l ocal 1. * / var / l og/ nsvpn. l og For example, if you want to use the local4 syslog facility for VPN event logging, you must change the facility entry to local4.* in this line. Configuring Logging to External log host This section describes configuring the NetScaler and VPN logging to an external host. If you prefer to have syslog send messages to an external log host instead of to local files, you will need to remove the log file specifications in your /nsconfig/ syslog.conf file for both of the local facilities, replacing them with the loghost hostname or IP address of the remote syslog host, as shown below. l ocal 0. * @10. 100. 3. 53 l ocal 1. * @10. 100. 3. 53 You must also configure the syslog server to accept log entries from both of these logging facilities. Consult your syslog server documentation to determine how to do this. For most UNIX-based servers using the standard syslog software, you must add a local facility configuration line for both the ns.log and nsvpn.log log files to the syslog.conf configuration file. The facility values must correspond with those configured on the NetScaler. Configuring Log File Rotation Log files on the NetScaler are automatically rotated at regular intervals. If you change the names of your log files, you must update the rotation configuration to reflect the new names, so that the correct files will be rotated. You can also customize other aspects of the rotation configuration for your log files. You can find the file that controls log rotation at /etc/newsyslog.conf. To make changes to this file, copy the file from /etc/newsyslog.conf to /nsconfig/ newsyslog.conf if newsyslog.conf does not already exist in the /nsconfig directory. Edit the /nsconfig/newsyslog.conf file, and reboot the NetScaler to implement your changes. If you need to update a log file name, you edit the appropriate file name in the left column. The remaining columns control the log rotation parameters. If you need to customize the log rotation parameters, you can refer to the FreeBSD manpage on newsyslog(8), because the NetScaler logging facility uses the same file formats and syntax. Chapter 2 Managing the Citrix NetScaler lv Path MaximumTransmission Unit Discovery This section covers the NetScaler path maximum transmission unit (MTU) discovery feature of the NetScaler. HowIt Works PMTU discovery is a method for dynamically learning the maximum transmission unit of any Internet channel. This discovered PMTU is then used by the TCP or UDP layer to create packets of an optimum size for that channel. This avoids fragmentation overhead on the routers in the path, and reassembly overhead on the receiving server. PMTU discovery is an operation mode in the NetScaler. This mode enables the NetScaler to interoperate with other routers participating in PMTU Discovery. In a typical topology, the NetScaler is deployed in front of the servers it manages, and either manages connections from clients on behalf of these servers (transparent mode), or manages connections with the servers and clients independently (end-point mode). The NetScaler in End-Point Mode In end-point mode, the NetScaler separately manages connections to the servers it manages and clients that contact those servers separately. For client connections, the NetScaler uses an MSS of 1460 bytes, meaning that the MSS of packets sent to the client is a minimum of 1460 bytes, as received from the client. If the network contains a router that fragments the packet into multiple datagrams because of MTU mismatches, the router sends an ICMP error to the NetScaler. The NetScaler does not pass the error to the servers it manages, but parses it and determines an MTU appropriate for that particular client. The NetScaler then updates the MTU database with the lower MTU. Thereafter, it uses the new MTU value for all new connections to that client. The NetScaler in Transparent Mode In transparent mode, if a managed server sets the DF bit and sends a datagram, and Path MTU is smaller than the size of the datagram, the NetScaler receives an ICMP error. When the NetScaler is operating in MIP mode, it adjusts the MTU to the MIP and updates the MTU database so that the lower MTU is used for subsequent connections. All packets subsequently sent via that connection have the DF bit unset. Note: This affects all clients using that MIP, not just the client that generated the ICMP error. lvi Installation and Configuration Guide - Volume 1 In USIP mode, when an ICMP error message is received, the NetScaler translates it and sends it to the managed server. The managed server updates the MTU for that destination, and subsequent datagrams are sent with the lowered MTU. The MTU value for that client is also updated in the NetScaler. All new connections then use the lowered MTU. Enabling PMTU Discovery This section covers procedure to enable the PMTU Discovery feature in the NetScaler. The NetScaler does not participate in PMTU Discovery by default, you have to enable this feature. The default PMTU size is 576 bytes. To enable PMTU discovery 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 2. Under Modes & Features click modes. The Configure Modes dialog box appears. 3. Select the Path MTU Discovery option and click OK Note: To disable PMTU discovery, clear thePath MTU Discovery option and click OK. Autodetected Services When the NetScaler is deployed in transparent mode, it provides an autodetection service, where it automatically detects back-end Web servers. The following are some scenarios: Configuring Global HTTP port When the NetScaler is using transparent mode connection multiplexing, you can configure global HTTP port(s) on the NetScaler with no virtual IP addresses (VIPs) or services. What are the allowable service types? In this case, the client directly accesses the back-end web server using the server’s IP address. If the destination port matches the configured global HTTP port(s), then the NetScaler dynamically detects the information it needs. You can configure several such vservers simultaneously. To create a vserver for autodetecting transparent HTTP services 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. Chapter 2 Managing the Citrix NetScaler lvii 2. Click Add. The Create Virtual Servers (Load Balancing) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type LBhttp and 80 respectively. 4. In the IP Address and Port text box, type ‘*’. 5. In the Protocol drop-down list box select HTTP. 6. Click Create and then click Close. The vserver you created appears in the Load Balancing Virtual Servers page. Configuring Cache-Redirection The NetScaler is deployed in transparent or reverse cache redirection topology, and the cache redirection virtual server mode is set to cache. When the NetScaler detects that the cache is down, it automatically redirects requests to the origin server(s). Configuring Transparent SSL In transparent mode connection multiplexing, you configure wildcard *.443 port(s) on the NetScaler with no virtual IP addresses (VIPs) or services. For the client to access the back-end server, L2 mode needs to be enabled on the NetScaler. The client directly accesses the backend web server using the server’s IP address. If the destination port matches the configured wildcard *.443 port(s), the NetScaler dynamically detects and learns the necessary information. To create a vserver for autodetecting transparent SSL services 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Servers (Load Balancing) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type LBssl and 443 respectively. 4. In the IP Address and Port text box, type ‘*’. 5. In the Protocol drop-down list box select SSL. 6. Click Create and then click Close. The vserver you created appears in the Load Balancing Virtual Servers page. lviii Installation and Configuration Guide - Volume 1 CHAPTER 1 Introduction This chapter describes the objectives of the Citrix NetScaler Installation and Configuration Guide - Volume 1, how it is organized, its intended audience, and its document conventions. In This Chapter • About This Guide • New in This Release • Audience • Additional Product Support • Document Conventions • Getting Service and Support • Documentation Feedback • Related Documentation About This Guide This guide covers the steps involved in installation and configuration of the NetScaler and all the commonly used features. The features covered in this guide are: • High Availability • Load Balancing • Content Switching • Secure Sockets Layer (SSL) Acceleration • FIPS • Client Keep-Alive • TCP Buffering • Compression • Surge Protection 2 Installation and Configuration Guide - Volume 1 • Priority Queuing • Layer 7 Denial of Service Protection • Content Filtering Works • Layer 3-Layer 4 Denial of Service (SYN) Protection • Surge Protection • Web Server Logging • Audit Server Logging • Reverse NAT • MAC-Based Forwarding • Route Health Injection • VLAN • Link Aggregation • Link Load Balancing • Dynamic Routing • IPv6 • URL Rewrite • HTML Injection • Responder Audience This guide is intended for system and network administrators who install and configure complex networking equipment. While sales and marketing professionals might find the conceptual information useful, they are advised to refer to the white papers, product brochures, and other literature on our Web site for more details. Additional Product Documentation The NetScaler documentation set consists of the following: • Citrix NetScaler Quick Start Guide - Provides instructions for installing the hardware. Includes instructions for rack mounting the chassis, fixing SFPs and XFPs, connecting the cables, and connecting to the power supply. • Citrix NetScaler Getting Started Guide - Describes how to initially set up and configure a Citrix® NetScaler®. It begins with an overview of the core architecture, followed by details about the product line, installation and deployment instructions, and hands-on labs that cover commonly used features. • Citrix NetScaler Migration Guide - Applies to users upgrading the system software. Covers upgrade and downgrade procedures, new commands and APIs, command and API changes. Chapter 1 Introduction 3 • Citrix NetScaler Installation and Configuration Guide, Volume 2 - Covers the steps involved in configuring the advanced features. The features covered in this guide are: • Domain Name System (DNS) • Global Server Load Balancing (GSLB) • Cache Redirection • Firewall Load Balancing • Integrated Caching • SureConnect • Citrix NetScaler Command Reference Guide - Provides detailed descriptions of all the CLI commands. The contents of this guide are identical to the man pages. • Citrix NetScaler Release Notes - Covers enhancements, new features, known issues, and limitations. • Citrix NetScaler Advanced Policy Guide - Covers the policy infrastructure which includes both the Policy Expressions (PE) and Policy Infrastructure (PI) languages. Includes examples drawn from real-life configurations. • Citrix Application Firewall Guide - Covers the features, configuration, and maintenance of both the standalone Citrix Application Firewall and the integrated Citrix NetScaler Application Firewall feature. • Access Gateway Enterprise Edition Administrator’s Guide - Administrator manual for configuring Access Gateway Enterprise Edition. • Citrix Secure Access Client User Guide for Java - User manual for using Secure Access for J ava. • Citrix Secure Access Client User Guide for Windows - User manual for using Secure Access for Windows. The NetScaler guides are provided as Adobe Portable Document Format (PDF) files. You can locate this documentation on your product CD or on the Citrix Support Web site at http://support.citrix/com/. Document Conventions This documentation uses the following typographic conventions. Note: Procedures in this guide are examples that you can enter to get your NetScaler up and running. You can literally follow the examples, including the sample values, and later enter your own values to customize your configuration. For complete information about configuration options, refer to the Command Reference Guide. Convention Meaning Boldface Commands that you type exactly as shown. Italics New terms, words that would otherwise be enclosed in quotation marks, and placeholders for information or parameters that you provide. For example, FileName in a command means you type the actual name of a file. Monospace Text displayed in a text file and commands used at the NetScaler Command Line Interface (CLI). 4 Installation and Configuration Guide - Volume 1 Getting Service and Support Citrix provides technical support primarily through the Citrix Solutions Network (CSN). Our CSN partners are trained and authorized to provide a high level of support to our customers. Contact your supplier for first-line support, or check for your nearest CSN partner at http://support.citrix.com/. In addition to the CSN program, Citrix offers a variety of self-service, Web-based technical support tools from its Knowledge Center at http://support.citrix.com/. Knowledge Center features include: • A knowledge base containing thousands of technical solutions to support your Citrix environment • An online product documentation library • Interactive support forums for every Citrix product • Access to the latest hotfixes and service packs • Security bulletins • Online problem reporting and tracking (for organizations with valid support contracts) Another source of support, Citrix Preferred Support Services, provides a range of options with which you can customize the level and type of support for your organization's Citrix products. Additional Maintenance Support In addition to the standard support options, all NetScalers are available with Silver and Gold maintenance options. If you purchase either of these options, you receive documentation with special Citrix Technical Support numbers you can call. Silver Maintenance Option The Silver maintenance option provides unlimited system support for one year. This option provides basic coverage hours, one assigned support account manager for nontechnical relations management, four named contacts, and advanced replacement for materials. Technical support is available at the following times: • North America, Latin America, and the Caribbean: 8 A.M. to 9 P.M. U.S. Eastern Time, Monday through Friday • Asia (excluding J apan): 8 A.M. to 6 P.M. Hong Kong Time, Monday through Friday • Australia and New Zealand: 8 A.M. to 6 P.M. Australian Eastern Standard Time (AEST), Monday through Friday • Europe, Middle East, and Africa: 8 A.M. to 6 P.M. Coordinated Universal Time (Greenwich Mean Time), Monday through Friday Gold Maintenance Option The Gold maintenance option provides unlimited system support for one year. Support is available 24 hours a day, 7 days a week. There is one assigned support account manager for nontechnical relations management, and there are six named contacts. Chapter 1 Introduction 5 Subscription Advantage Your product includes a one-year membership in the Subscription Advantage program. The Citrix Subscription Advantage program gives you an easy way to stay current with the latest software version and information for your Citrix products. Not only do you get automatic access to download the latest feature releases, software upgrades, and enhancements that become available during the term of your membership, you also get priority access to important Citrix technology information. You can find more information on the Citrix Web site at http://www.citrix.com/services/ (on the Support menu, click Subscription Advantage). You can also contact your sales representative, Citrix Customer Care, or a member of the Citrix Solutions Advisors program for more information. Knowledge Center Watches You can set up alerts to have the Citrix Knowledge Center notify you if a topic you are interested in is updated. To set up an alert, log on to the Citrix Support Web site at http://support.citrix.com. After you are logged on, under Products, select a product. Under Alerts, click Add to your Alerts. To remove an alert, go to the Knowledge Center product and click Remove from your Alerts. Education and Training Citrix offers a variety of instructor-led and Web-based training solutions. Instructor-led courses are offered through Citrix Authorized Learning Centers (CALCs). CALCs provide high-quality classroom learning using professional courseware developed by Citrix. Many of these courses lead to certification. Web-based training courses are available through CALCs, resellers, and from the Citrix Web site. Information about programs and courseware for Citrix training and certification is available at http:// www.citrix.com/edu/. Documentation Feedback You are encouraged to provide feedback and suggestions so that we can enhance the documentation. You can provide feedback in one of the following ways: • Send e-mail to [email protected] with the subject line “Installation and Configuration Guide - Feedback.” Be sure to include the following information in your e-mail: document name, page number, and product release version. • Fill out the documentation feedback form at http://support.citrix.com/docfeedback/. • Navigate to the Knowledge Center home page (http://support.citrix.com) and do the following: A. On the Knowledge Center home page, click Citrix Application Delivery and click a release of your choice. B. On the Citrix Application Delivery Software <release number> page, on the Documentation tab, click the guide name and click Article Feedback. C. On the Documentation Feedback page, complete the form and click Submit. 6 Installation and Configuration Guide - Volume 1 Related Documentation The following guides and release notes are available for Access Gateway Enterprise Edition and WANScaler products. All documents are available at http://support.citrix.com/. For information about Citrix Access Gateway Enterprise Edition, the following guides are available: • Citrix Access Gateway Enterprise Edition Administrator’s Guide • Getting Started with Citrix Access Gateway Enterprise Edition • Citrix Access Gateway Enterprise Edition Pre-Installation Checklist • Citrix Secure Access Client User Guide for Java • Citrix Secure Access Client User Guide for Windows • Citrix Secure Gateway to Access Gateway Migration Guide For information about Citrix WANScaler system, the following guides are available: • Citrix WANScaler Appliances Installation and User’s Guide • Citrix WANScaler Quick Installation Guide CHAPTER 2 High Availability This chapter describes basic and advanced configuration procedures for the High Availability (HA) feature of the Citrix NetScaler System. Topics include: • How High Availability Works • Configuring a Basic High Availability Setup • Considerations for a High Availability Setup • Customizing an High Availability Setup • Improving the Reliability of a High Availability Setup • Configuring the State of a Node • Troubleshooting HA Issues How High Availability Works If you have two systems, you can deploy them in a configuration where one system accepts connections and manages servers, while the second system monitors the first. If, for any reason, the first system is unable to accept connections, the second system takes over. A high availability configuration prevents downtime and ensures uninterrupted service when a system ceases to function. The secondary system monitors the primary system by sending periodic messages to the primary system (often called heartbeat messages or health checks) to determine if it is accepting connections. When a health check fails, the secondary system retries the connection for a specified period, after which it determines that the primary system is not functioning normally. The secondary system then takes over for the primary system (a process called failover). After a failover, all clients must reestablish their connections to the managed servers, but the session persistence rules are maintained as they were before the failover. 8 Installation and Configuration Guide - Volume 1 With Web server logging persistence enabled, no log data is lost due to the failover. For logging persistence to be enabled, the log server configuration must carry entries for both systems in the log.conf file. For details of setting up logging persistence, see Chapter 12, "Web Server Logging." The following figure shows a network configuration with an HA pair: Systems in High Availability mode With Web server logging persistence enabled, no log data is lost due to the failover. For logging persistence to be enabled, the log server configuration must carry entries for both systems in the log.conf file. For details of setting up logging persistence, see Chapter 12, "Web Server Logging." Considerations for a High Availability Setup Note the following requirements for configuring systems in an HA setup: • The passwords for the default administrator accounts (nsroot) on both systems in an HA pair must be the same. However, the operating system does not automatically synchronize these passwords. Therefore, when you change the password of the nsroot account on one system, you must also perform the change manually on the other system. • Entries in the configuration file (ns.conf) on both the primary and the secondary system must match, with the following exceptions: • The primary and the secondary systems must each be configured with their own unique NetScaler IPs (NSIPs.) Chapter 2 High Availability 9 • In an HA pair, the node ID and associated IP address of one system must point to the other system. For example, if you have two systems, NS1 and NS2, then you must configure NS1 with a the unique node ID and the IP address of NS2, and you must configure NS2 with a unique node ID and the IP address of NS1. • If you create or copy a configuration file on either system using a method other than the direct GUI or the CLI (for example, SSL certificates, or changes to startup scripts), you must create or copy the configuration file onto both the primary and the secondary systems. • You must configure Remote Procedural Call (RPC) node passwords on both systems in an HA pair. Initially, all systems are configured with the same RPC node password. RPC nodes are internal system entities used for system-to-system communication of configuration and session information. For security, you should change the default RPC node passwords. One RPC node exists on each system. This node stores the password, which is checked against the password provided by the contacting system. In order to communicate with other systems, each system requires knowledge of those systems, including how to authenticate on those systems. RPC nodes maintain this information, which includes the IP addresses of the other systems, and the passwords used to authenticate on each. RPC nodes are implicitly created when adding a node or adding a Global Server Load Balancing (GSLB) site. You cannot create or delete RPC nodes manually. Note: If the systems in a high availability setup are configured in one-arm mode, you must disable all system interfaces except the one connected to the switch or hub. Configuring High Availability This section describes how to configure a basic high availability setup. The following topics are covered: • Configuring a Basic High Availability Setup • Modifying an Existing High Availability Setup 10 Installation and Configuration Guide - Volume 1 Configuring a Basic High Availability Setup This section describes procedures to configure two systems in a high availability setup, as illustrated in the following figure: Two systems connected in an HA setup In the figure, systems NS1 and NS2 are on the same subnet. To config- ure the systems in high availability mode, you must configure one sys- tem as primary and the other as secondary. You will need to perform the following procedures, as described in the sections that follow: • Add a node • Disable HA monitor for unused interfaces • Save the configuration • Verify the configuration Adding a Node This section describes how to add a node in an HA setup. The new node is identified by a unique ID and its NSIP. The maximum number of node IDs for systems in a high availability setup is 64. Chapter 2 High Availability 11 To add a node, use the parameters described in the followint table: To add a node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Add. The Add Node dialog box appears. 4. In the ID text box, type an ID. For example, type 3. 5. In the IP Address textbox, type an IP Address, for example, 10.102.29.170. 6. Click Create. The Add Node dialog box is appears, as shown in the following figure: Adding a node To add a node using the NetScaler command line At the NetScaler command prompt, type: add HA node 3 10.102.29.170 Disabling HA Monitor for Unused Interfaces You must disable the HA monitor for interfaces in the system that are not connected or being used for traffic. Parameter Description Node ID The unique number that identifies the node to be added. The minimum value is 1 and the maximum value is 64. IP Address The IP Address of the node to be added. 12 Installation and Configuration Guide - Volume 1 To disable an HA monitor, use the parameters described in the following table: To disable HA monitor for an unused interface 1. In the left pane, expand Network and click Interfaces. The Interfaces page appears in the right pane. 2. Select the interfacewhich you want to disable the HA monitor. 3. Click Open. The Configure Interface dialog box appears. 4. In the HA Monitoring select the OFF option. 5. Click OK. The Modify Interface box appears, as shown in the following figure: Disabling HA monitor To disable HA monitor using the NetScaler command line At the NetScaler command prompt, type: set interface 1/3 -haMonitor OFF Parameter Description Interface Number The interface number represented in the <slot/port> notation. Chapter 2 High Availability 13 Saving the Configuration This section describes how to save the configuration for a basic HA setup. To save the configuration 1. In the GUI screen, click Save. A pop-up window appears. 2. Click Yes to save the configuration. Note: To ensure that each system in the configuration has the same settings, you should synchronize your SSL certificates, startup scripts, and other configuration files with those on the primary system.. To save the configuration using the NetScaler command line At the NetScaler command prompt, type: save ns config Verifying the Configuration To verify your configuration, you can view the node and check its status in the local system. One node will be primary and other will be secondary. To view the configuration 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears, with the primary and the secondary nodes displayed. To view the configuration using the NetScaler command line At the NetScaler command prompt, type: sh ha node Modifying an Existing HA Setup This section describes the procedures to modify an existing high availability configuration. The following topics are covered: • Disabling a Node • Enabling a Node • Removing a Node 14 Installation and Configuration Guide - Volume 1 Disabling a Node You can only disable a secondary node. When you disable a secondary node, it stops sending heartbeat messages to the primary node. The primary node therefore can longer check the status of the secondary node. To disable a node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the secondary node and click Open. The Configure Node Dialog box appears. 4. Under High Availability Status, select the DISABLED (Do not participate in HA) option. 5. Click OK. The Configure Node dialog box is shown in the following figure: Disabling a secondary node To disable a node using the NetScaler command line At the NetScaler command prompt, type: Chapter 2 High Availability 15 set HA node -hastatus DISABLED Enabling a Node When you enable a node, the node takes part in the high availability configuration. You can only enable a secondary node. To enable a node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the secondary node and click Open. The Configure Dialog box appears. 4. Under High Availability Status, select the ENABLED (Actively participates in HA) option. 5. Click OK and click Close. To enable a node using the NetScaler command line At the NetScaler command prompt, type: set ha node -hastatus ENABLED Removing a Node When you remove a node, the nodes are no longer in high availability configuration. To remove a node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the node that you want to remove. 4. Click Remove. The Remove pop-up window appears. 5. Click Yes. To remove a node using the NetScaler command line At the NetScaler command prompt, type: r mha node 3 16 Installation and Configuration Guide - Volume 1 Customizing an High Availability Setup This section describes the steps to customize a high availability setup. The following topics are covered: • Configuring the Communication Intervals • Configuring Synchronization • Configuring Command Propagation • Forcing a Node to Failover Configuring the Communication Intervals This section describes the procedure to configure the communication intervals in a high availability configuration. The hello interval is the interval at which the heartbeat messages are sent to the peer node. The dead interval is the time interval after which the peer node is marked DOWN if heartbeat packets are not received. The heartbeat messages are UDP packets sent to port 3003 of the other system in an HA pair. To set the hello and the dead intervals, use the parameters listed in the following table: To set the hello and dead intervals 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the node for which you want to change the hello interval. 4. Click Open. The Configure Dialog box appears. 5. Under Interval, in the Hello Interval (msecs) within the Interval frame, type the interval, for example, 400. 6. In the Dead Interval (secs), type the interval, for example, 6. Parameter Description Hello Interval The time interval between successive heartbeat messages in milliseconds. The default value is 200. The minimum value is 200, and maximum value is 1000. Dead Interval The time duration in seconds after which a node is declared dead if there is no response to heartbeat messages. The default value is 3, the minimum value is 3, and the maximum value is 60. Chapter 2 High Availability 17 7. Click OK. To set the hello and dead intervals using the NetScaler command line At the NetScaler command prompt, type: set HA node -helloInterval 400 -deadInterval 6 Configuring Synchronization Synchronization is a process of pulling the configuration of the primary node by the secondary node. The purpose of the synchronization process is to ensure that there is no loss of configuration information between the primary and the secondary nodes, irrespective of the number of failovers that occur. The port number 3010 is used for synchronization. The synchronization process is triggered in the following circumstances: • When a secondary node in an HA setup comes up after a restart • When the primary node becomes secondary after a failover occurred in an HA setup Disabling or Enabling Synchronization HA synchronization is enabled by default in each node in an HA pair. You can enable or disable HA synchronization on either node in an HA pair. 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the local node. 4. Click Open. The Configure Dialog box appears. 5. Under HA Synchronization, clear the Secondary node will fetch the configuration from Primary option. 6. Click OK and then click Close. Note: To enable HA synchronization, in step 5 above, you must select Secondary node will fetch the configuration from Primary. To disable or enable automatic synchronization using the NetScaler command line At the NetScaler command prompt, type: set HA node -haSync ENABLED 18 Installation and Configuration Guide - Volume 1 or set HA node -haSync DISABLED Forcing the Secondary Node to Synchronize with the Primary Node In addition to automatic synchronization, the system supports forced synchronization. You can force the synchronization from either the primary or the secondary node. When you force synchronization from the secondary node, it will start synchronizing its configuration with the primary node. However, if synchronization is already in progress, forced synchronization will fail and the system will display a warning. Forced synchronization will also fail in the following circumstances: • when you force synchronization on a standalone system • when the secondary node is disabled • when HA synchronization is disabled in the secondary node To force the secondary node to synchronize with the primary node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Force Synchronization. To force synchronization using the NetScaler command line At the NetScaler command prompt, type: force HA sync Configuring Command Propagation In an HA setup, any command issued on the primary node will propagate automatically to the secondary node. When a command is issued on the primary, the command is first propagated to and executed on secondary, and then executed on the primary. If the command propagation fails due to some reason or command execution fails on the secondary after command propagation, the primary node will still execute the command and an error will be logged. Port number 3011 is used for command propagation. In an HA pair configuration, command propagation is enabled by default on both the primary and secondary nodes. You can enable or disable command propagation on either node in an HA pair. If you disable command propagation in the secondary node, it command is effective only on the primary node. Chapter 2 High Availability 19 Note: Afte re-enabling propagation, remember to force synchronization When you disable propagation in the primary node, commands executed on the primary node are no longer propagated to the secondary node. When you disable propagation on a primary node after synchronization has been successfully completed, commands executed on the primary node are not propagated to the secondary node. However, if synchronization occurs during this period, the configuration-related changes that you made when propagation was disabled are synchronized with the secondary node. This is also true for cases where propagation is disabled while synchronization is in progress. To disable or enable command propagation 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Select the local node. 4. Click Open. The Configure Dialog box appears. 5. Under HA Propagation, clear the Primary node will propagate configuration to the Secondary option . 6. Click OK. Note: To enable HA synchronization, in Step 5 you must select the Primary node will propagate configuration to the Secondary. To disable or enable command propagation using the NetScaler command line At the NetScaler command prompt, type: set HA node -haProp ENABLED or set HA node -haProp DISABLED 20 Installation and Configuration Guide - Volume 1 Forcing a Node to Failover One scenario where you might want to force a failover is when you need to replace or upgrade your primary system in an HA setup. You can force failover either from the primary or the secondary system. A forced failover is not propagated or synchronized. To view the synchronization status after a forced failover, you can view the status of the node. A forced failover will fail in the following circumstances: • when you force failover on a standalone system • when the secondary node is disabled • when the secondary node is configured to remain as secondary Forcing the Primary Node to Failover If you force failover on the primary system, the primary becomes the secondary system and the secondary becomes the primary. Forced failover is only possible when the primary system can determine that the secondary system is UP. If the Secondary system is DOWN, the force failover command returns the error message "Operation not possible due to invalid peer state. Rectify and retry." If the secondary system is in the claiming state or inactive, it returns the message "Operation not possible now. Please wait for system to stabilize before retrying." To force the primary node to failover 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Force Failover. The Warning pop-up window appears. 4. Click Yes. To force the primary node to failover using the NetScaler command line At the NetScaler command prompt, type: force HA failover Chapter 2 High Availability 21 Forcing the Secondary Node to Failover When you execute the force failover command from the secondary system, then the secondary system becomes the primary system and the primary node becomes the secondary system. Force failover happens only if the secondary system’s health is good or if it is not configured to stay secondary. If the secondary system cannot become the primary system, or if secondary system was configured to stay secondary using the staysecondary option, the system displays the message “Operation not possible as my state is invalid. View the node for more information.” To force the secondary node to failover 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Force Failover. A Warning pop-up window appears. 4. Click Yes. To force the secondary node to failover using the NetScaler command line At the NetScaler command prompt, type: force HA failover Forcing Failover When Nodes are in Listen Mode When the two nodes of an HA pair are running different versions of the system software, the node running the higher version switches to the listen mode. In this mode, neither command propagation or synchronization work. Before upgrading the system software on both nodes, you should test the new version on one of the nodes. To do this, you will need to force a failover on the system that has already been upgraded. The upgraded system then takes over as the primary node, but neither command propagation or synchronization occurs. Also, all connections need to be re-established. To force failover when nodes are in listen mode 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Force Failover. A Warning pop-up window appears. 4. Click Yes. 22 Installation and Configuration Guide - Volume 1 To force failover when nodes are in listen mode using the NetScaler command line At the NetScaler command prompt, type: force HA failover Improving the Reliability of a High Availability Setup This section describes how to configure the Virtual MAC address (VMAC) and high availability when nodes are in different subnets. This section also describes link redundancy and route monitors, system functions that can be helpful in a cross-network HA configuration, and the health check process used by a system to ensure that its partner node is up and running. The section covers the following topics: • Configuring Virtual MAC Addresses • Configuring High Availability for Nodes in Different Subnets • Configuring Link Redundancy • Configuring Route Monitors • HA Health Check Computation Configuring Virtual MAC Addresses (VMAC) The Virtual MAC address (VMAC) is a floating entity shared by the primary and the secondary nodes in an HA setup. In an HA setup, the primary node owns all of the floating IP addresses such as the MIP, SNIP, VIP and so on. The primary node responds to Address Resolution Protocol (ARP) requests for these IP addresses with its own MAC address. As a result, the ARP table of an external device (for example, an upstream router) is updated with the floating IP address and the primary node's MAC address. When a failover occurs, the secondary node takes over as the new primary node. It then uses the Gratuitous ARP (GARP) to advertise the floating IP addresses that it acquired from the primary. The MAC address that the new primary advertises is the MAC address of the new primary's own interface. Some devices (notably a few routers) do not accept GARP messages generated by the Citrix NetScaler system. As a result, some external devices will retain the old IP to MAC mapping advertised by the old primary node. This may result in a site going down. Chapter 2 High Availability 23 You can overcome this problem by configuring a VMAC on both nodes of an HA pair. When you do this, both nodes possess identical MAC addresses. Therefore, when failover occurs, the MAC address of the secondary node remain unchanged, and the ARP tables on the external devices do not need to be updated. As mentioned earlier, the VMAC is a user-defined MAC address that is shared by the primary and secondary nodes. To create a VMAC, you need to first create a Virtual Router ID (VRID) and bind it to an interface. (In an HA setup, you need to bind the VRID to the interfaces on both nodes.) Once the VRID is bound to an interface, the system generates a VMAC with the VRID as the last octet. The generic VMAC is of the form 00:00:5e:00:01:<VRID>. For example, if you create a VRID with a value of 60 and bind it to an interface, the resulting VMAC is 00:00:5e:00:01:3c, where 3c is the hex representation of the VRID. You can create 255 VRIDs with values from 1 to 254. This section covers the following procedures: • Adding a Virtual MAC Addresses • Binding Interfaces to the Virtual MAC Address • Verifying the VMAC Configuration Adding a VMAC The example scenario described in this section illustrates the configuration of a VMAC on a standalone system, with a VRID value of 100. To add a virtual MAC, use the parameters in the following table: To add a VMAC 1. In the left pane, expand Network and click VMAC. The VMAC page appears in the right pane. 2. Click Add. The Add VMAC appears, as shown in the figure below. 3. In the Virtual Router ID text box, type a number, for example, 100. 4. Click Create. Parameter Description Virtual Router ID Each VMAC is identified by a VRID. Minimum value is 1 and maximum is 255. Interface Number. The interface number represented in the <slot/port>notation to be bound to the VMAC. 24 Installation and Configuration Guide - Volume 1 . Adding VMAC To add a VMAC using the NetScaler command line At the NetScaler command prompt, type: add vrID 60 Binding Interfaces to the VMAC The following procedure illustrates the steps to bind the VRID to interface 1/1. You cannot bind multiple VRIDs to an interface. To bind an interface to a VMAC, use the parameters listed in the following table: To bind interfaces to the VMAC 1. In the left pane, expand Network and click VMAC. The VMAC page appears in the right pane. 2. Click Open. The Configure VMAC dialog box appears. Parameter Description Virtual Router ID. Each VMAC is identified by a VRID. Minimum value is 1 and maximum is 255 Interface Name The interface name represented in the <slot/port>notation to be bound to the VMAC. Chapter 2 High Availability 25 3. Select the desired interfaces from the Available Interfaces table and click Add. For example, 1/1, 1/2, and 1/3. 4. The interfaces are bound to the VMAC and appear in theConfigured Interfaces table. 5. Click OK. To bind interfaces to the VMAC using the NetScaler command line At the NetScaler command prompt, type: bind vrid 100 ifnum 1/1 1/2 1/3 Verifying the VMAC Configuration To verify the VMAC configuration, perform the following steps as described in the procedures that follow: • View the VMACs • View the interfaces bound to the VMAC To view VMACs 1. In the left pane, expand Network and click VMAC. 2. The VMAC page appears, with all the available VMACs displayed. To view VMACs using the NetScaler command line At the NetScaler command prompt, type: sh vrID To view the interfaces bound to the VMAC 1. In the left pane, expand Network and click VMAC. 2. The VMAC page appears, with all the available VMACs. 3. Select a VMAC, for example 100, the bound interface are displayed in the bottom of the page. To view the interfaces bound to the VMAC using the NetScaler command line At the NetScaler command prompt, type: sh vrID 100 26 Installation and Configuration Guide - Volume 1 Managing VMACs This section describes procedures for unbinding the interfaces from a VMAC and deleting the created VMAC from the system. To unbind interfaces from a VMAC 1. In the left pane, expand Network and click VMAC. The VMAC page appears in the right pane. 2. Select a VMAC, for example 100, and click Open. The Configure VMAC dialog box appears. 3. In the Configured Interfaces table, select the interfaces you want to unbind from the VMAC, for example 1/2 and 1/3. 4. Click Remove. The interfaces are unbound from the VMAC and appear in the Available Interfaces table. 5. Click OK. To unbind interfaces from a VMAC using the NetScaler command line At the NetScaler command prompt, type: unbind vrID 100 1/2 1/3 To remove a VMAC 1. In the left pane, expand Network and click VMAC. The VMAC page appears in the right pane. 2. Select the VRID that you want to remove from the system, for example 100. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. The selected VRID is removed. To remove a VMAC using the NetScaler command line At the NetScaler command prompt, type: rm vrid 100 Chapter 2 High Availability 27 Configuring High Availability Nodes in Different Subnets The earlier section "Configuring a Basic High Availability Setup" covered a typical HA deployment where both systems in an HA pair reside on the same subnet. This section describes an HA pair configuration where the two systems reside on different subnets. The section provides sample configurations, and a list of the differences between HA configurations within one subnet, and configurations across networks. The following figure shows an HA deployment with the two systems located in different subnets: HA over a routed network In the figure, the systems NS1 and NS2 are connected to two separate routers R3 and R4 on two different subnets. The systems exchange heartbeat packets through the routers. This configuration could be expanded to accommodate deployments involving any number of interfaces. 28 Installation and Configuration Guide - Volume 1 Note: If you use static routing on your network, you must add static routes between all the systems to ensure that heartbeat packets are sent and received successfully. (If you use dynamic routing on your systems, static routes are unnecessary.) If the nodes in an HA pair reside on two separate networks, the secondary node must have an independent network configuration. This means that nodes on different networks cannot share entities such as MIPs, SNIPs, VLANs, and routes. This type of configuration, where the nodes in an HA pair have different configurable parameters, is known as Independent Network Configuration (INC) or Symmetric Network Configuration (SNC). The following table describes the parameters that you must set on each node in an INC: When two nodes of an HA pair reside on different subnets, each node must have a different network configuration. Therefore, to configure two independent systems to function as an HA pair, you must specify an INC mode during the configuration process. To specify an INC mode, perform the following steps, as described in the sections that follow: • Add a node with inc option enabled • Disable HA monitor for unused interfaces • Save the configuration Configurable Parameters Behavior IPs (NSIP/MIP/SNIPs) Node-specific. Active only on that unit. VIP Floating. Vlans Node-specific. Active only on that unit. Routes Node-specific. Active only on that unit. LLB route is floating. ACLs Floating (Common). Active on both units. Dynamic routing Node-specific. Active only on that unit. The secondary node should also run the routing protocols and peer with upstream routers. L2 mode Floating (Common). Active on both units. L3 mode Floating (Common). Active on both units. Reverse NAT (RNAT) Node-specific. RNAT with VIP, because NATIP is floating. Chapter 2 High Availability 29 Adding a Node This section describes the procedure to add a node in a different subnet than the local node, using the parameters listed in the following table: To add a node 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Add. The Add Node dialog box appears. 4. In the ID text box, type an ID, for example, 3. 5. In the IP Address textbox, type an IP Address, for example, 10.102.29.170. 6. Under Independent Network Configuration, select Nodes in an HA pair would have its network configuration. 7. Click Create. To add a node using the NetScaler command line At the NetScaler command prompt, type: add HA node 3 10.102.29.170 - inc ENABLED Disabling HA Monitor in Interfaces You must disable the HA monitor for interfaces in the system that are not connected or being used for traffic. To disable HA MON in the interfaces, use the interface number parameter, as described in the following table: To disable HA monitor for an unused interface 1. In the left pane, expand Network and click Interfaces. The Interfaces page appears in the right pane. Parameter Description Node ID The unique number that identifies the node to be added. Minimum value is 1 and maximum value is 64. IP Address The IP Address of the node to be added. Parameter Description Interface number The interface number (represented in the <slot/port>notation) 30 Installation and Configuration Guide - Volume 1 2. Select the interfacefor which you want to disable the HA monitor. 3. Click Open. The Configure Interface dialog box appears. 4. In the HA Monitoring section select the OFF option. 5. Click OK. To disable HA monitor using the NetScaler command line At the NetScaler command prompt, type: set interface 1/3 -haMonitor OFF Saving the Configuration The following procedure describes the steps to save the configuration in the system. To save the configuration 1. In the GUI screen, click Save. A pop-up window appears. 2. Click Yes to save the configuration. To save the configuration using the NetScaler command line At the NetScaler command prompt, type: save ns config Configuring Link Redundancy Link redundancy is a way to prevent failover by grouping interfaces so that when one interface fails, other functioning interfaces will still be available. The section "Configuring High Availability for Nodes in Different Subnets" describes a scenario in which the first interface on the primary system, NS1, fails, triggering failover, even though it can still serve client requests via its second link. The link redundancy feature allows you to group the two interfaces into a failover interface set (FIS), and prevent the failure of a single link from causing failover to the secondary system unless all of the interfaces on the primary system are nonfunctional. Each interface in an FIS maintains independent bridge entries. HA MON interfaces that are not bound to an FIS are known as critical interfaces (CI) because if any of them fails, failover is triggered. Adding a Failover Interface Set (FIS) This section describes the procedure to add a Failover Interface Set (FIS) in the system. Chapter 2 High Availability 31 To add a FIS 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Failover Interface Set tab. The Failover Interface Set page appears. 3. Click Add. The Create FIS dialog box appears. 4. In the Name text box, type a name for the FIS to be created, for example, FIS1. 5. Click Create. The Create FIS dialog box appears, as shown in the following figure: Creating FIS To add a FIS using the NetScaler command line At the NetScaler command prompt, type: add fis FIS1 Binding the Interfaces to an FIS To bind interfaces to the Failover Interface Set, use the parameters listed in the following table: Parameter Description FIS Name The name of the FIS to which interfaces are to be bound. 32 Installation and Configuration Guide - Volume 1 To bind interfaces to the FIS 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Failover Interface Set tab. The Failover Interface Set page appears. 3. Click Open. The Configure FIS dialog box appears. 4. Select interfaces from the Available Interfaces table and click Add. 5. The interfaces are bound to the Failover Interface Set and appear in the Configured Interfaces table. 6. Click OK. To bind interfaces using the NetScaler command line At the NetScaler command prompt, type: bind fis FIS1 1/1 1/2 1/3 Verifying the Created FIS This section describes how to an FIS that you have created. To view an FIS 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Failover Interface Set tab. The Failover Interface Set page appears, with all the configured FISs displayed. To view an FIS using the NetScaler command line At the NetScaler command prompt, type: sh fis FIS1 Managing Link Redundancy This section describes how to unbind interfaces from an FIS, and how to remove an FIS. Interface Number The interface number (represented in the <slot/port>notation) to be bound to the FIS. Parameter Description Chapter 2 High Availability 33 Unbinding an Interface fromthe FIS This following sample procedure illustrates the steps to unbind interfaces from an FIS. An unbound interface becomes a critical interface (CI) if it is enabled and HA MON is on. To unbind an interfaces from the FIS To unbind interfaces from the Failover Interface Set, use the parameters in the following table: 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Failover Interface Set tab. The Failover Interface Set page appears. 3. Select the FIS from which you want the interfaces to be unbound. 4. Click Open. The Configure FIS dialog box appears. 5. In the Configured Interfaces table, select the interface you want to unbind from the FIS, and click Remove. 6. The interface is unbound from the Failover Interface Set and is shown in theAvailable Interfaces table. 7. Click OK. To unbind an interfaces from the FIS using the NetScaler command line At the NetScaler command prompt, type: unbind fis FIS1 1/1 1/2 Removing the FIS The following sample procedure describes the steps to remove an FIS that you have created. Once the FIS is removed, its interfaces become CIs. To remove a Failover Interface Set, use the parameter in the following table: Parameter Description FIS Name The name of the FIS from which the interfaces are to be unbound. Interface Name The interface name (represented in the <slot/port>notation.) Parameter Description FIS Name The name of the FIS that is to be removed. 34 Installation and Configuration Guide - Volume 1 To remove a FIS 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Failover Interface Set tab. The Failover Interface Set page appears. 3. Select the FIS that you want to remove. For example, select FIS1 4. Click Remove. The Remove pop-up window appears. 5. Click Yes. The selected Failover Interface Set is removed. To remove a FIS using the NetScaler command line At the NetScaler command prompt, type: rm fis FIS1 Configuring Route Monitors You can make the HA state independent of the system internal routing table, whether or not dynamically learned routes are present. The procedure requires using route monitors. If the route is present on which the route monitor is bound, the node can become primary. If the route is absent, the node will always remain as secondary. Note: Route monitors are neither propagated by nodes, or exchanged during synchronization. In an HA configuration, a route monitor on each system watches the internal routing table to make sure that an entry for the other system is always present. This is especially important when using dynamic routing, because a router error can make an HA node believe that the other node is down, when it is not. When the nodes of an HA pair reside on different networks, the HA state of a node depends on its reachability. Before the route monitor runs, you must save the configuration. Note: Clearing the configuration does not delete the route monitors on a system. You must remove the route monitors manually. Binding a Route Monitor to an HA Node This section describes how to add a route monitor in the system. Chapter 2 High Availability 35 To add a route monitor, use the parameters in the following table: To add a route monitor 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Route Monitors tab. The Route Monitors page appears. 3. Click Configure. The Bind / Unbind Route Monitor(s) dialog box appears. 4. In the Network text box, type a network IP, for example, 10.102.29.30 5. In the Netmask text box, type a netmask, for example,255.255.255.0 6. Click Add . The Route Monitor is added and appears in the Configured Route Monitors table. 7. Click OK. The Bind / Unbind Route Monitor(s) dialog box is shown in the following figure: Adding a route monitor Note: When a route monitor is not bound to a node, the HA state (primary or secondary) of the node is determined solely by the state of the interfaces. Parameter Description Network The network prefix of the route to be monitored Netmask The subnet for the network 36 Installation and Configuration Guide - Volume 1 To add a route monitor using the NetScaler command line At the NetScaler command prompt, type: bind ns node -routeMonitor 10.102.29.30 255.255.255.0 Verifying the Route Monitors The following sample procedure describes the steps to verify the configured route monitor in the system. To view a route monitor 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Route Monitors tab. The Route Monitors page appears, with all the configured route monitors displayed. To view a route monitor using the NetScaler command line At the NetScaler command prompt, type: sh HA node Removing Route Monitors The following sample procedure describes the steps to remove a route monitor from the system. To remove a route monitor 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Route Monitors tab. The Route Monitors page appears. 3. Click Configure. The Bind / Unbind Route Monitor(s) dialog box appears. 4. In the Configured Route Monitors table, select a Route Monitor to remove. 5. Click Remove and click OK. To remove a route monitor using the NetScaler command line At the NetScaler command prompt, type: bind ns node -routeMonitor 10.102.29.30 255.255.255.0 Chapter 2 High Availability 37 HA Health Check Computation The following table summarizes the factors examined in a health check computation: • State of the CIs • State of the FISs • State of the route monitors The following table summarizes the health check computation: Configuring the State of a Node This section describes how to configure the state of a secondary node to stay as secondary, and the primary node to stay as primary. Forcing the Secondary Node to Stay Secondary In an HA setup, the secondary node can be forced to stay secondary, independent of the state of the primary node. For example, in an existing HA setup, suppose the primary node needs to be upgraded, and that the process will take a few seconds. During the upgrade, the primary node may go down for a few seconds, but you do not want the secondary system to take over; you want it to remain the secondary node, even if it detects a failure in the primary node. When you force the secondary node to stay secondary, the secondary system will remain as secondary even if the primary node goes down. Also, when you force the status of a system in an HA pair to stay secondary, it does not participate in HA state machine transitions. The status of the node is displayed as "STAYSECONDARY." Forcing the node to stay secondary works on both standalone and secondary nodes. On a standalone node, you must use this option before you can add a node to create an HA pair. When you add the new node, the existing node will continue to function as the primary node, and the new node will become the secondary node. FIS CI Route Monitor Condition N Y N If the system has any CIs, all of those CIs must be UP. Y Y N If the system has any FISs, all of those FISs must be UP. Y Y Y If the system has any route monitors configured, all monitored routes must be present in the FIS. 38 Installation and Configuration Guide - Volume 1 Note: When you force a system to stay as secondary, the forcing process is not propagated or synchronized. It affects only the node on which the command is executed. To force the secondary node to stay secondary 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Open. The Configure Dialog box appears. 4. Under High Availability Status, select STAY SECONDARY. 5. Click OK. To force the secondary node to stay secondary using the NetScaler command line At the NetScaler command prompt, type: set node -hastatus STAYSECONDARY Forcing the Primary Node to Stay Primary In an HA setup, you can force the primary node can be forced to stay primary even after failover. You can enable this option can enabled either on a primary node in an HA pair or on a standalone system. On a standalone system, you must execute the option before you can add a node to create an HA pair. When you add the new node, the new node becomes the primary node. The existing node stops processing traffic and becomes the secondary node in the HA pair. To force the primary node to stay primary 1. In the left pane, expand System and click High Availability. The High Availability page appears in the right pane. 2. Click the Nodes tab. The Nodes page appears. 3. Click Open. The Configure Dialog box appears. 4. Under High Availability Status, select STAY PRIMARY. 5. Click OK. Chapter 2 High Availability 39 To force the secondary node to stay secondary using the NetScaler command line At the NetScaler command prompt, type: set node -hastatus STAYPRI MARY Troubleshooting HA Issues This section gives troubleshooting tips for the following issues in a high availability setup: • Improper synchronization of VLAN configuration in high availability systems. In HA pairs, synchronization does not work properly if only one system has a VLAN configured. To prevent this problem, configure your VLANs after you configure your systems as an HA pair, and be ensure that you configure them both. • Retrieving a lost configuration. If the primary system is unable to send the configuration to the secondary system due to a network error, the secondary system may not have an accurate configuration and may not behave correctly when failover occurs. If this happens, you can retrieve the current configuration from the configuration backup on the hard disk of the primary system. The operating system saves the last four copies of the ns.conf file in the /nsconfig directory as ns.conf.0, ns.conf.1, ns.conf.2, and ns.conf.3. The ns.conf.0 file contains the current configuration. To retrieve the current system configuration: 1. Exit from the CLI to FreeBSD by typing the following command and pressing the Enter key: > shell The FreeBSD shell prompt appears, as shown below. # 2. Copy the latest backup file to /nsconfig/ns.conf, using the following command: # cp ‘ls -t /nsconfig/ns.conf.? | head -1` /nsconfig/ns.conf If you perform a configuration using the NSConfig utility, it is not propagated. If you create a configuration using NSconfig, you must repeat the configuration steps separately for each node in an HA pair. 40 Installation and Configuration Guide - Volume 1 CHAPTER 3 Basic Network Configuration Overview This chapter describes the basic networking features of the Citrix NetScaler System (system) and provides instructions for configuring them. Topics include: • Configuring System-Owned IP Addresses • Configuring Modes of Packet Forwarding • Proxying Connections • Configuring VMAC • Configuring Access Control Lists • Configuring Bridge Tables Configuring System-Owned IP Addresses The system communicates with other devices using a set of IP addresses. These IP addresses enable the system to abstract servers and to multiplex connections. The system owns the following IP addresses: • NetScaler IP address (NSIP). The NetScaler IP address is the IP address of the Citrix NetScaler system. The system is managed by using this IP address. • Subnet IP address (SNIP). Subnet IP address is the IP address that an external host residing on another subnet uses to access a system. The system determines the next hop for a service from the routing table and if the IP address of the hop is within the range of SNIPs, the system uses SNIP to source traffic to the service. • Mapped IP address (MIP). Mapped IP addresses (MIP) are used for external connections from the system. MIP can be considered as a default SNIP when a SNIP cannot be used. 42 Installation and Configuration Guide - Volume 1 • Virtual IP address/Vserver IP address (VIP). The virtual server IP address (VIP) is the IP address associated with a vserver. This IP address is optional and can be used when you create a vserver. • GSLB site IP address (optional). The GSLB site IP address is the IP address associated with a GSLB site. This IP address is optional and can be used when you create a GSLB site. Creating the NetScaler IP Address The NetScaler IP address (also called management IP address) is the IP address of the system. By default, the system is managed using this IP address. The system can only have a single NSIP. You must add this IP address when you configure the system for the first time. If you modify this IP address, you must reboot the system. Note: Configuring the NetScaler IP address is mandatory. The following example describes the procedure to set the NSIP address to 10.102.29.170, subnet mask to 255.255.255.0, and host name to NS170. To configure the NetScaler IP address using the configuration utility 1. In the Navigation Pane, click NetScaler. The System Information page appears in the Details Pane. 2. Click Setup Wizard. The Setup Wizard dialog box appears. 3. Click Next. The IP Addresses page appears. 4. Under System IP Address Configuration, in the IP Address, Netmask, and Host Name text boxes, type the IP address, subnet mask, and the host name, for example, 10.102.29.170, 255.255.255.0, and NS170. 5. Follow the instructions provided in the Setup Wizard to complete the configuration. To configure the NetScaler IP address using the NetScaler command line At the NetScaler command prompt, type: set ns conf i g - i paddr ess 10. 102. 29. 170 - net mask 255. 255. 255. 0 Configuring IP Address Types The section describes the basic instructions that you must follow to configure system-owned IP addresses. This section describes the procedures to configure the following types of IP addresses: Chapter 3 Basic Network Configuration 43 • Subnet IP address • Mapped IP address • Virtual server IP address • GSLB site IP address To create an IP address, use the parameters listed in the following table. The following example describes the procedure to create an IP address 10.102.29.54 of type subnet IP address and subnet mask 255.255.255.0. To configure an IP address using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Click Add. The Create IP dialog box appears. 3. In the IP Address and Netmask text boxes, type the subnet IP address and mask, for example, 10.102.29.54 and 255.255.255.0. 4. Click Create and click Close. The subnet IP address you created appears in the IPs page. This is shown in the following figure. IP Page Parameters Description IP Address The IP address of the entity. This is a mandatory parameter. Netmask The netmask associated with the IP. type The type of the IP address. The valid options for this parameter are SNIP, VIP, MIP, and GSLBsiteIP. The default value is SNIP. The parameter does not provide an NSIP option, as NSIP must be configured using a different procedure. For more information about the procedure to configure NSIP, see the section “Creating the NetScaler IP Address” on page 42. 44 Installation and Configuration Guide - Volume 1 To configure an IP address using the NetScaler command line At the NetScaler command prompt, type: add ns i p 10. 102. 29. 54 255. 255. 255. 0 Creating Subnet IP Addresses You can use the subnet IP address to access a system from an external host that is residing on another subnet. When you add a subnet IP address, a route corresponding to the subnet IP address is added in the route table. The system determines the next hop for a service from the routing table and if the IP address of the hop is within the range of SNIPs, the system uses SNIP to source traffic to the service. When many SNIPs cover the IP addresses of the next hops based on their netmasks, the SNIPs are used in round robin manner. It is not mandatory to specify the subnet IP address (SNIP) when you initially configure the system. To create a subnet IP address, you must follow the procedure described in the section, “Configuring IP Address Types” on page 42. This IP address is used in connection management and server monitoring. In a multiple-subnet scenario, the NSIP, mapped IP, and IP address of a server can exist on different subnets. In such a multiple-subnet scenario, you can configure separate IP addresses (subnet IP addresses) on the system. The source IP address of a packet sent from the system is the SNIP. When the system is configured with multiple subnets, you can enable the Use SNIP (USNIP) mode to use an appropriate SNIP as the source IP for all packets originating from the system. This eliminates the need to configure additional routes on devices such as servers. By default, use SNIP mode is enabled. Use the following procedure to disable use SNIP mode. To disable use SNIP using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Clear the Use Subnet IP check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To disable use SNIP using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns mode usni p Chapter 3 Basic Network Configuration 45 When you enable the use SNIP mode, the system uses the use SNIP as the source IP address for outgoing packets, as shown in the following figure. SNIP mode The following procedure describes the steps to enable use SNIP mode and ensure that the system uses the appropriate subnet IP address to connect to back-end servers. To enable use SNIP using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Select the Use Subnet IP check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable use SNIP using the NetScaler command line At the NetScaler command prompt, type: enabl e ns mode usni p 46 Installation and Configuration Guide - Volume 1 Creating Mapped IP Addresses Mapped IP addresses (MIP) and SNIP are used for external connections from the system. But, MIPs are used for server-side connections when appropriate SNIPs cannot be used or when the use subnet IP address option is globally disabled on the system. When a SNIP has a subnet that doesn’t cover the IP address of the next hop, the MIPs are used in a round robin manner irrespective of the netmask. You must specify at least one MIP address when you configure the system for the first time. If the mapped IP address is the first in the subnet, the system adds a route entry, with this IP address as the gateway to reach the subnet. You can create or delete a mapped IP address (MIP) during runtime without rebooting the system. To create a mapped IP address, follow the procedure described in the section “Configuring IP Address Types” on page 42. An MIP does not necessarily exist on the NSIP subnet. However, it is customary to add MIPs on the NSIP subnet. If the system has only one MIP, and you are required to change it, first create a new MIP before removing the old one. When MIPs and SNIPs are used for many connections, there is limit on the number of connections to the system For more information about the number of connections, see “Appendix”. Creating Virtual Server IP Addresses The virtual server IP address (VIP) is the IP address associated with a vserver. Like SNIP, it is not mandatory to specify the VIP when you initially configure the system. You can host the same vserver on multiple systems residing on the same broadcast domain by using ARP and ICMP attributes. To create a virtual server IP address, follow the procedure described in the section, “Configuring IP Address Types” on page 42. You must create a virtual server when you configure the load balancing setup on the system. A virtual server uses a VIP to communicate with other entities in the load balancing setup. For more information about configuring the load balancing setup, see the chapter on load balancing in the Installation and Configuration Guide. To create virtual server IP addresses, use the virtual IP parameter described in the following table. Parameters Description Virtual IP Use this option to set (enable or disable) the vserver attribute for this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. Chapter 3 Basic Network Configuration 47 Creating GSLB Site IP Addresses When configuring a GSLB local site, you use the GSLB site IP. To create the GSLB Site IP address, follow the procedure described in the “Creating GSLB Site” section of the “Global Server Load Balancing” chapter. For more information on creating a GSLB site IP address, see the “Global Server Load Balancing” chapter. Modifying IP Addresses The system can be accessed and managed using services such as Tel-net, SSH, GUI, and FTP. You can utilize these services using the NetScaler IP address (NSIP), Mapped IP addresses (MIP), and Subnet IP addresses (SNIP). However, you cannot disable these services for SNIP. To modify IP addresses, use the parameters described in the following table. Note: Telnet and FTP are disabled on the system for security reasons. To enable them, contact the customer support. After the services are enabled, you can apply the controls at the IP level. Parameters Descriptions Telnet Use this option to set (enable or disable) the state of telnet access to this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. FTP Use this option to set (enable or disable) the state of FTP access to this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. GUI Use this option to set GUI access to this IP entity. The valid options for this parameter are ENABLED, SECUREONLY, and DISABLED. The default value is ENABLED. SSH Use this option to set (enable or disable) the state of SSH access to this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. SNMP Use this option to set (enable or disable) the state of SNMP access to this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. Management Access Use this option to set (enable or disable) the state of management access to this IP entity. The valid options for this parameter are ENABLED and DISABLED. The default value is DISABLED. 48 Installation and Configuration Guide - Volume 1 The following table provides a summary of the interaction between management access and specific service settings. It provides information on the state of the service configured on the system, and its impact on the state of the service when configured at the IP level. By default, management access is enabled for NSIP. Therefore, you cannot control management access for NSIP. However, you can control management access to NSIP using ACLs. The system does not support management access to VIPs. The following table provides an overview of the IP addresses used as source IP addresses in outbound traffic. The following table provides an overview of the services available on these IP addresses. If management access for an IP address is disabled, existing connections that use this IP address are not terminated. However, if you close the session, you cannot initiate a connection. To configure the system to respond to these services using a specific IP address, you need to enable a specific management service. The following example describes the procedure to modify an IP address 10.102.29.54. Management access control is enabled. This procedure does not affect the existing connections. Management Access Telnet (State configured on the system) Telnet (State configured at the IP level) Enable Enable Enable Enable Disable Disable Disable Enable Disable Disable Disable Disable Application/ IP NSIP MIP SNIP VIP ARP Yes Yes Yes No Server side traffic No Yes Yes No RNAT No Yes Yes Yes ICMP PING Yes Yes Yes No Application/ IP NSIP MIP SNIP VIP SNMP Yes Yes Yes No System Access Yes Yes Yes No Chapter 3 Basic Network Configuration 49 To modify an IP address using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to modify, for example, 10.102.29.54. 3. Click Open. The Configure IP dialog box appears. 4. Under Application Access Control, select theEnable Management Access control to support the below listed applications check box. 5. Click OK. To modify an IP address using the NetScaler command line At the NetScaler command prompt, type: set ns i p 10. 102. 29. 54 - mgmt Access enabl ed Controlling Address Resolution Protocol The purpose of controlling Address Resolution Protocol (ARP) is to disable the system from generating gratuitous ARP for the vserver, or responding to ARP requests for the vserver when the vserver is UP. After you add an IP address, the system sends gratuitous ARP (GARP), then responds to ARP requests. This is true when you add any of the following IP addresses: the NetScaler IP address, mapped IP address, virtual server IP address, and subnet IP address. Controlling GARP is useful when you need to switch between two vservers on two different devices. When you switch between vservers, the system does not perform the following: • Generate GARP • Respond to ARP Controlling ARP is useful when you move vservers from another traffic management device to the system (or vice versa). Controlling ARP is also useful in scenarios where a single vserver is configured on two systems, and a device upstream distributes or directs traffic to these systems by using direct server return configuration. In these scenarios, the vserver must be UP, but it should not generate GARP or respond to ARP requests. To control GARP/ARP behavior on a per-IP basis, use the parameters listed in the following table. Use the following procedure to control GARP/ARP behavior. Parameters Description ARP Use this option to set (enable or disable) ARP and gratuitous ARP for the entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. 50 Installation and Configuration Guide - Volume 1 To disable ARP using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to modify, for example, 10.102.29.5. 3. Click Open. The Configure IP dialog box appears. 4. Under Options, clear theARP check box. 5. Click OK. To disable ARP using the NetScaler command line At the NetScaler command prompt, type: set ns i p 10. 102. 29. 54 - ARP di sabl ed Note: You can disable ARP/GARP and ICMP controls only for an IP address associated with a vserver. Controlling PING Response To control PING response, use the ICMP parameter described in the following table. Use the following procedure to control the response of a system to a PING request on a system-owned IP address. To disable PING responses using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to modify, for example, 10.102.29.54. 3. Click Open. The Configure IP dialog box appears. 4. Under Options, clear theICMP check box. 5. Click OK. Parameters Description ICMP Use this option to set ICMP responses for the entity. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. Chapter 3 Basic Network Configuration 51 To disable PING responses using the NetScaler command line At the NetScaler command prompt, type: set ns i p 10. 102. 29. 54 - I CMP di sabl ed Note: You can control ARP and ICMP attributes for a VIP only. These attributes are enabled for the other system-owned IP addresses. Managing IP Addresses This section describes the procedures to perform the following: • Remove an IP Address • Enable and Disable an IP Address The section also provides information on when you must follow these procedures and their impact on the network. Removing an IP Address You can remove the IP addresses that you created. (But, NSIP cannot be removed.) The following table provides information on the processes you must follow to remove the various types of IP addresses. IP Address Type Implications Subnet IP address (SNIP) If the IP address being removed is the last IP address in the subnet, the associated route from the route table is deleted. If the IP address being removed is the gateway in the corresponding route entry, the gateway for that subnet route is changed to another IP address (system-owned IP address). Mapped IP address (MIP) When SNIP exists for the system, you can remove the MIPs. The system uses NSIP and SNIP to communicate to back-end servers when the MIP is removed. Therefore, you also need to enable use SNIP. For information on enabling and disabling use SNIP, refer to the section “Creating Subnet IP Addresses” on page 44. Virtual Server IP address (VIP) To remove a VIP, you must first remove the vserver associated with it, as the vserver uses this VIP for communication. For more information on removing the vserver, see the “Load Balancing” chapter of the Installation and Configuration Guide. GSLB-Site-IP address To remove a GSLB site IP address, you must first remove the site associated with it, as the site uses this IP address to communicate. For more information about removing the site, see the “Global Server Load Balancing” chapter of the Installation and Configuration Guide, Volume 2. 52 Installation and Configuration Guide - Volume 1 The following example describes the procedure to remove an IP address, 10.102.29.54. Follow this procedure to remove MIP, GSLB site IP address, and SNIP. To remove VIP, first remove the vserver associated with the VIP, and then follow this procedure. To remove an IP address using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to remove, for example, 10.102.29.54. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove an IP address using the NetScaler command line At the NetScaler command prompt, type: r mns i p 10. 102. 29. 54 Enabling and Disabling an IP Address This section describes the procedures to enable and disable the IP address. You can only disable VIP. When the VIP is disabled, the vserver using the VIP goes down. When the vserver is down, it does not respond to ARP, ICMP, and L4 service requests. You can enable or disable the following services of SNIP and MIP: • FTP • Telnet • SNMP The following procedure describes the steps to disable an IP address 10.102.29.5 of type virtual IP (VIP). To create a VIP see the section “Creating Virtual Server IP Addresses” on page 46. To disable an IP address using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to disable, for example, 10.102.29.5. 3. Click Disable. Chapter 3 Basic Network Configuration 53 To disable an IP address using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns i p 10. 102. 29. 5 Use the following procedure to enable the IP address. To enable an IP address using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. 2. Select the IP address that you want to enable, for example, 10.102.29.5. 3. Click Enable. To enable an IP address using the NetScaler command line At the NetScaler command prompt, type: enabl e ns i p 10. 102. 29. 5 Verifying the Configuration You can view the properties of the configured IP addresses such as IP address, state, type, and mode. The details of the configured IP addresses can be used to troubleshoot any fault in the configuration. To view the properties of IP addresses using the configuration utility 1. In the Navigation Pane, expand Network and click IPs. The IPs page appears in the Details Pane. The details of the available network interfaces appear in this page. 2. Verify that the configured IP address 10.102.29.5 appears. 3. Select the IP address 10.102.29.5 and in the Details section, verify that the parameters displayed are as configured. To view the IP addresses using the NetScaler command line At the NetScaler command prompt, type: sh ns i p Configuring Static ARP The attributes of an IP address (such as gratuitous ARP [GARP] and PING) control the Layer 3 behavior of the system. This section covers the control of GARP and PING. This section covers the parameters and procedures to perform the following: 54 Installation and Configuration Guide - Volume 1 • Adding ARP entries to the ARP table • Removing ARP entries from the ARP table • Viewing the ARP tables Adding Static ARP Entries This section describes the procedures to add entries in the ARP table. To add ARP entries to the ARP table, use the parameters listed in the following table. Use the following procedure to add the IP address 10.102.29.54, MAC address 00:aa:10:12:13:ef, and network interface 1/8 to an ARP table. To create an ARP entry using the configuration utility 1. In the Navigation Pane, expand Network and click ARP Table. The ARP Table page appears in the Details Pane. 2. Click Add. The Add ARP entry dialog box appears. 3. In the IP Address, MAC Address, and Interface Number text boxes, type the IP address, MAC address and network interface number that you want to add to the ARP table, for example, 10.102.29.54, 00:aa:10:12:13:ef, and 1/8. Parameters Description IP Address The IP address of the server. MAC Address The MAC address of the server. Type the MAC address with colons (:) as shown in the example below. Interface Number The physical interface for the ARP entry. Use the show interface command to view the valid interface names. Chapter 3 Basic Network Configuration 55 4. Click Create and click Close. The ARP entries you added appear in the ARP Table page. This is shown in the following figure. ARP Table page To create an ARP entry using the NetScaler command line At the NetScaler command prompt, type: add ar p - I PAddr ess 10. 102. 29. 54 - mac 00: aa: 10: 12: 13: ef - i f num1/ 8 Note: When you create a static ARP entry and if the IP address, port or MAC address change, you need to remove or manually adjust the static entry. Therefore, creating static ARP entries are not recommended unless necessary. Removing Static ARP Entries The following example describes the procedure to remove the IP address 10.102.29.54 from an ARP table. To remove an ARP entry using the configuration utility 1. In the Navigation Pane, expand Network and click ARP Table. The ARP Table page appears in the Details Pane. 2. Select the ARP entry that you want to remove, for example, 10.102.29.54. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove an ARP entry using the NetScaler command line At the NetScaler command prompt, type: r mar p 10. 102. 29. 54 56 Installation and Configuration Guide - Volume 1 Verifying the Configuration You can view the properties of the ARP entries such as IP address, MAC address, interface, VLAN, and origin. The details of the configured ARP entries can be used to troubleshoot any fault in the configuration. To view the ARP entries of IP addresses using the configuration utility 1. In the Navigation Pane, expand Network and click ARP Table. The ARP Table page appears in the Details Pane. The details of the available ARP entries appear in this page. 2. Verify that the configured ARP entry 10.102.29.54 appears. 3. Select the IP address 10.102.29.54 and in the Details section, verify that the parameters displayed are as configured. To view the ARP entries using the NetScaler command line At the NetScaler command prompt, type: sh ar p Configuring Modes of Packet Forwarding The system uses the following modes to forward the packets it receives: • Layer 2 Mode • Layer 3 Mode • MAC Based Forwarding Mode Chapter 3 Basic Network Configuration 57 Enabling and Disabling Layer 2 Mode Layer 2 mode controls the Layer 2 forwarding (bridging) function. When this mode is enabled, packets that are not destined for the system MAC address are bridged or processed, as shown in the following figure. Interaction between the Layer 2 and Layer 3 modes By default, Layer 2 mode is disabled. When Layer 2 mode is disabled, the system drops packets that are not destined for its MAC address. If another Layer 2 device is installed in parallel with the system, Layer 2 mode must be disabled to prevent bridging (Layer 2) loops. To enable the layer 2 mode, use the following procedure. To enable the Layer 2 mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Select the Layer 2 Mode check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable the Layer 2 mode using the NetScaler command line At the NetScaler command prompt, type: enabl e ns mode l 2 58 Installation and Configuration Guide - Volume 1 To disable the layer 2 mode, use the following procedure. To disable the Layer 2 mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Clear the Layer 2 Mode check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To disable the Layer 2 mode using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns mode l 2 Note: The system does not support spanning tree protocol, and therefore when L2 mode is enabled, you should not connect two interfaces on the system to the same broadcast domain to avoid loops. Enabling and Disabling Layer 3 Mode Layer 3 mode controls the layer 3 forwarding function. By default, Layer 3 mode is enabled. When you enable Layer 3 mode, the system performs a route table lookup and forwards the packets that are not destined to any system-owned IP addresses. When you disable Layer 3 mode, the system drops received packets if the packets are not destined to the system-owned IP address. This is illustrated in the figure “Interaction between the Layer 2 and Layer 3 modes” on page 57. To enable layer 3mode, use the following procedure. To enable Layer 3 mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Select the Layer 3 Mode (IP Forwarding) check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. Chapter 3 Basic Network Configuration 59 To enable Layer 3 mode using the NetScaler command line At the NetScaler command prompt, type: enabl e ns mode l 3 To disable Layer 3 mode, use the following procedure. To disable the Layer 3 mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Clear the Layer 3 Mode (IP Forwarding) check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To disable Layer 3 mode using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns mode l 3 Enabling and Disabling MAC-Based Forwarding Mode You can use MAC-based forwarding to process traffic more efficiently and avoid multiple-route/ARP lookups when forwarding packets. The system remembers the MAC address of the source. To avoid multiple lookups, the system caches from the ARP lookup table, the source MAC address for every connection, and returns the data to the same MAC address. MAC-based forwarding is useful when you use VPN devices, because the system ensures that the traffic flowing through the VPN passes through the same VPN device. The packets can be routed differently otherwise. 60 Installation and Configuration Guide - Volume 1 The following topology diagram illustrates the process of MAC-based forwarding. Working of MAC-based forwarding mode When MAC-based forwarding is enabled, the system caches the MAC address of: • The source (a transmitting device such as router, firewall, or VPN device) of the inbound connection. • The server that responds to the requests. When a server replies through the system, the system sets the destination MAC address of the response packet to the cached address, ensuring that the traffic flows in a symmetric manner and then forwards the response to the client. The process bypasses the route table lookup and ARP lookup functions. However, when the system initiates a connection, it uses the route and ARP tables for the lookup function. When you need to use the direct server return configurations, you must enable MAC-based forwarding. For more information about direct server return configurations, see the “Load Balancing” chapter.To enable MAC- based forwarding, use one of the following procedures. To enable MAC-based forwarding using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Select the MAC Based Forwarding check box. Chapter 3 Basic Network Configuration 61 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable MAC-based forwarding using the NetScaler command line At the NetScaler command prompt, type: enabl e ns mode mbf Some deployment topologies may require the incoming and outgoing paths to flow through different routers. In these situations, MAC-based forwarding breaks this topology design. For a global server load balancing (GSLB) site that requires the incoming and outgoing paths to flow through different routers, you must disable MAC-based forwarding and make the default router of the system the outgoing router. MBF should be disabled in the following situations: • When you configure link load balancing because asymmetric traffic flows are desired because of link costs. • When a server uses network interface card (NIC) teaming without using LACP (802.1ad Link Aggregation). To enable MAC-based forwarding in this situation, you must use a layer 3 device between the NetScaler system and server. Note: MBF can be enabled when the server uses NIC teaming with LACP because the virtual interface uses one MAC address. • When firewall clustering is used. Firewall clustering assumes that ARP is used to resolve the MAC address for inbound traffic. Sometimes the inbound MAC address can be a non-clustered MAC address and should not be used for inbound packet processing. When MBF is disabled, the system uses L2 or L3 connectivity to forward the responses from servers to the clients. Thus, depending on the route table, the routers used for outgoing connection and incoming connection can be different. In case of reverse traffic (response from the server): • If the source and destination are on different subnets, the system uses the route lookup to locate the source. • If the source is on the same subnet as the destination, the system looks up the ARP table to locate the network interface and forwards the traffic to it. If the ARP table does not exist, the system requests the ARP entries. To disable MAC-based forwarding, use one of the following procedures. 62 Installation and Configuration Guide - Volume 1 To disable MAC-based forwarding using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Clear the MAC Based Forwarding check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To disable MAC-based forwarding using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns mode mbf Proxying Connections When a client initiates a connection, the system terminates the client connection that it receives. The system then initiates a connection to an appropriate server and sends the packet to the server. The system does not perform this action for the service types UDP or ANY. For more information about the service types, see the “Load Balancing” chapter of the Installation and Configuration Guide, Volume 1. The system can process the packet before initiating the connection with a server, depending on the configuration of the system. To facilitate secure access of server resources, the system changes the source and destination IP addresses of a packet before sending the packet to the server. Chapter 3 Basic Network Configuration 63 Selecting the Destination IP Address Traffic arriving at the system can be bound to a vserver or to a service. The system handles traffic to vservers and services differently. The system terminates traffic bound to vservers and changes the vserver IP address (VIP) to the IP address of the server before forwarding the traffic to the server. This is illustrated in the following figure. Proxying Connections to VIPs Packets bound to a service are sent directly to the appropriate server, and the system does not modify the destination IP addresses. Selecting the Source IP Address The mapped IP address (MIP), source IP address (SIP), and subnet IP address (SNIP) are used as source IP addresses to establish a connection with a server. By default, the system terminates traffic bound to vservers and configured services. Then, it changes the source IP address of the packet to the mapped IP address (MIP) and sends the packet to the appropriate server. This default behavior is illustrated in the figure “Proxying Connections to VIPs” on page 63. 64 Installation and Configuration Guide - Volume 1 Configuring the Use Source IP Mode Many e-commerce applications that use web server logging require the original client IP addresses recorded in the web server logs. The system can forward the source IP address of the client to the server without masking it, to ensure that the client IP address appears in the logs. The Use Source IP mode (USIP) is used for such applications. When USIP mode is enabled, the system forwards each packet to the appropriate server without changing the source IP address. This is illustrated in the following figure. USIP Mode When USIP mode is enabled for HTTP protocols, the system provides limited connection reuse, WAN latency, and denial of service (SYN) attack prevention benefits. When USIP mode is disabled, the system uses mapped IP addresses and subnet IP addresses to establish server-side connections. USIP mode has the following restrictions: • One-arm installations. You should not enable USIP mode if you install the system in a one-arm configuration, because in a one-arm configuration the system cannot bypass its own processing and sends responses directly to Chapter 3 Basic Network Configuration 65 the client. If the IP address of the default gateway for a service is one of the system-owned IP addresses, the traffic continues to flow through the system and the response is also processed correctly. • Concurrent connection limit. USIP mode supports up to 64,000 concurrent connections for HTTP protocols (this applies to HTTP protocols only.) If concurrent connections between the system and servers are expected to exceed 64,000, you must disable USIP. To increase the number of concurrent connections that USIP mode supports, you must contact customer support because there is a method to override this behavior. The concurrent connection limit does not impact services of the type TCP. • Delay when disabling USIP. When you disable USIP mode, the existing connections continue to use USIP mode. However, the new connections do not use the source IP address. This delay avoids outages on long-lived connections. • Performance Impact on HTTP traffic. Usually, the HTTP connections on the server side are reused for many clients. However, when USIP mode is enabled, the connections may not be reused. Therefore, there can be a large number of connections to the server (depending on the number of client connections) that can impact performance. Further, if there are idle server connections, the client connections may be blocked because the services are serving the idle connections. Therefore, you need to set the limits on the number of connection with care on services. We suggest you to configure the HTTP server time-out on the service to a lower value than the default so that idle client connections are cleared quickly on the server side. For more information about setting an idle time-out value, see Load Balancing chapter in Citrix NetScaler Installation and Configuration Guide, Volume 1. In addition, you must configure persistence (any persistence type such as source IP persistence) with USIP enabled to ensure that the same server is selected and the client connection is reused. The service of type TCP handles the traffic on one-to-one basis and therefore, the USIP option doesn’t impact TCP services. Note: It is recommended not to use Surge Protection (SP) with USIP. You can either configure USIP mode for all services, or for a specific service. By default, USIP mode is disabled. To enable USIP mode globally, use the following procedure. To enable Use Source IP mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 66 Installation and Configuration Guide - Volume 1 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Select the Use Source IP check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable USIP using the NetScaler command line At the NetScaler command prompt, type: enabl e ns mode USI P To disable USIP mode, use the following procedure. To disable Use Source IP mode using the configuration utility 1. In the Navigation Pane, expand System and click Settings. The Settings page appears in the Details Pane. 2. In the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Clear the Use Source IP check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To disable USIP using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns mode USI P Note: For services created after you enable USIP mode globally, the system forwards the packet from the client to the server without changing the source IP address unless you specifically disable the mode on individual services. When you configure USIP mode for individual services, this setting takes precedence over USIP enabled globally. If you enable USIP mode on individual services, enabling or disabling USIP mode globally does not affect those settings -- the global settings are ignored for those services. For more information about configuring USIP mode, see the “Load Balancing” chapter of the Installation and Configuration Guide, Volume 1. A new service inherits the global USIP settings. When you configure the service setting on an individual service, the service setting overrides the global setting. Chapter 3 Basic Network Configuration 67 Configuring Network Interfaces Network interfaces in the system are numbered in <slot>/<port>notation. You can configure network interfaces in the following ways: • Modify network interface characteristics such as speed, duplex mode, flow control, monitoring, and so on. • Enable or disable a network interface. The network interfaces are enabled by default. • Reset the specified network interface. • Clear the statistics of the specified network interface. This does not reset the network interface. • View the configured settings of the network interfaces. If the network interface number appears in the Interfaces page, then the information shown applies only to that network interface. The information on the loopback network interface appears in the Interfaces page. To modify the network interfaces, use the parameters listed in the following table. Parameters Description ID The number of the network interface. Speed The network interface number specifies the Ethernet speed for the network interface. The default setting is AUTO. This means that the system attempts to auto- negotiate or auto-sense the line speed on this network interface when the network interface is invoked. Setting a speed other than AUTO on a network interface requires the device at the other end of the link to be configured identically. Mismatching speed and/or duplex configurations on two ends leads to link errors, packet losses, and so on. You must avoid mismatching of the speed. Some network interfaces do not support certain speeds. If you try to set a speed on a network interface that does not support it, it is reported as an error. The valid options for this parameter are AUTO, 10, 100, and 1000. Duplex The duplex mode for the network interface. The default setting is AUTO. This implies that the system attempts to auto-negotiate for the duplex mode on this network interface when the network interface is invoked. You can also specify half and full duplex modes. It is recommended to leave the speed as AUTO. If you force duplex mode, you must manually configure duplex mode and identical speed on both sides of the link. The valid options for this parameter are AUTO, HALF, and FULL. 68 Installation and Configuration Guide - Volume 1 Flow Control The required 802.3x flow control for the network interface. You can specify OFF (the default), RX, TX, RXTX, and ON (ON means “forced RXTX”). OFF is available only for Fast Ethernet network interfaces. The 802.3x specifications do not define the flow control for speeds 10MB and 100 MB. Gigabit Ethernet network interfaces support flow control for these three possible speeds. Real flow control status depends on the auto- negotiation results. When flow control is ON, you must use auto-negotiation so that the peer can negotiate the flow control. You must then force the two-way flow control for this network interface. Link parameter mismatches must be avoided and checked, because they can cause the system to drop packets, or the link may not be accessible, and so on. Auto Negotiate The state of auto negotiation for the specified network interface. The valid options for this parameter are DISABLED and ENABLED HA Monitor The state of high availability configuration. This parameter specifies the network interfaces that are monitored for failing events. The valid options for this parameter are ON and OFF. By default, this is set to ON for all network interfaces. When ON in an HA configuration, failover occurs when a network interface fails. If a network interface is not being used, or if failover is not required, select OFF. Also, if the network interface is not used in the configuration, then you must disable it. Trunk The option to select whether this port is or is not a trunk port for the network interface. The valid options for this parameter are ON and OFF. By default, this is set to OFF for all network interfaces. When ON, the traffic is tagged for the VLANs bound to this network interface including the native VLAN. If you require 802.1q behavior with backward compatibility, you must set this parameter to OFF. LACP Mode LACP mode. The valid options for this parameter are DISABLED, ACTIVE, and PASSIVE. The default value is DISABLED LACP Key LACP key. The minimum value is 1 and the maximum value is 4 LACP Priority LACP port priority. The default value is 32768. The minimum value is 1 and the maximum value is 65535. LACP Time-out LACP timeout. The valid options for this parameter are LONG and SHORT, and the default value is NSA_LACP_TIMEOUT_LONG. Alias The alias name for the network interface. Parameters Description Chapter 3 Basic Network Configuration 69 The following example describes the procedure to set the duplex of a network interface 1/8 to full duplex. To modify a network interface using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Select the network interface that you want to modify, for example, 1/8. 3. Click Open. The Modify Interface dialog box appears. 4. In the Duplex drop-down list, select FULL. 5. Click OK. To modify a network interface using the NetScaler command line At the NetScaler command prompt, type: set i nt er f ace 1/ 8 - dupl ex f ul l Note: The network interface configuration is neither synchronized nor propagated, therefore you must perform the configuration on each unit in an HA pair independently. Managing Network Interfaces This section describes the following procedures: removing the statistics of a network interface, and enabling and disabling network interfaces. It also provides information about when you must perform these tasks, and how they impact the network. Throughput Minimum required throughput for the network interface. If you provide a throughput value greater than the actual throughput value, the network interface fails. Parameters Description 70 Installation and Configuration Guide - Volume 1 Enabling and Disabling Network Interfaces This section describes the procedures to enable and disable network interfaces. You must disable a network interface that is not connected to the network. If you disable a network interface that is connected to the network, it cannot send or receive packets. Disabling a network interface that is connected to the network in a high availability setup can cause failover. For more information about high availability, see the “High Availability” chapter of the Installation and Configuration Guide. The following example describes the procedure to disable the network interface 1/8. To disable a network interface using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Select the network interface that you want to disable, for example, 1/8. 3. Click Disable. To disable a network interface using the NetScaler command line At the NetScaler command prompt, type: di sabl e i nt er f ace 1/ 8 The following example describes the procedure to enable the network interface 1/ 8. By default, the network interfaces are enabled. To enable a network interface using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Select the network interface that you want to enable, for example, 1/8. 3. Click Enable. To enable a network interface using the NetScaler command line At the NetScaler command prompt, type: enabl e i nt er f ace 1/ 8 Resetting Network Interfaces This section describes the procedure to reset network interfaces. network interface settings are used to control parameters such as duplex, speed, and so on. To renegotiate the parameters of a network interface, you must reset it. The following example describes the procedure to reset the network interface 1/8. Chapter 3 Basic Network Configuration 71 To reset a network interface 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. In the Interfaces page, select the network interface that must be reset. For example, select 1/8. 3. Click Reset Interface. To reset a network interface using the NetScaler command line At the NetScaler command prompt, type: r eset i nt er f ace 1/ 8 Removing the Statistics of a Network Interface This section describes the procedure to remove the statistics of a network interface. You can use network interface statistics to monitor parameters such as packet sent and packet received. You can clear the statistics of a network interface to monitor its statistics from the time the statistics are cleared. The following example describes the procedure to clear the statistics of the network interface 1/ 8. To clear a network interface statistics using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Select the network interface whose statistics you want to clear, for example, 1/8. 3. Click Clear Statistics. To clear a network interface statistics using the NetScaler command line At the NetScaler command prompt, type: cl ear i nt er f ace 1/ 8 Verifying the Configuration This section describes how to view the configured network interfaces and the statistics of the network interfaces. Viewing the configuration can help you troubleshoot problem in the configuration. 72 Installation and Configuration Guide - Volume 1 Viewing Network Interfaces You can view the properties of the configured network interfaces, such as description, MAC address, uptime, and VMAC. Viewing the details of the network interfaces help you troubleshoot configuration errors. The following procedure describes the steps to view the properties of the network interfaces. To view the network interfaces using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. The details of the available network interfaces appear in this page. 2. Verify that the configured interface 1/8 appears. 3. Select the interface 1/8 and in the Details section, verify that the parameters displayed are as configured. To view the properties of the network interfaces using the NetScaler command line At the NetScaler command prompt, type: show i nt er f ace Viewing the Statistics of a Network Interface You can view the statistics such as Packet Statistics, Throughput Statistics, LACP Statistics and Error Statistics of configured network interfaces. You can use the statistics to check the health of the network interface. The following example describes the steps to view the statistics of network interface 1/8. To view the statistics of an Interface using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Select the network interface whose statistics you want to view, for example, 1/8. 3. Click Statistics. The Interface Statistics dialog box appears. This page displays the following information about the selected network interface: Packet Statistics, Throughput Statistics, LACP Statistics and Error Statistics. To view the statistics of the network interfaces using the NetScaler command line At the NetScaler command prompt, type: st at i nt er f ace 1/ 8 Chapter 3 Basic Network Configuration 73 Configuring Link Aggregation Link aggregation combines data coming from multiple ports into a single high- speed link. Configuring the link aggregate channel increases the capacity and availability of the communication channel between the system and other connected devices. An aggregated link is also referred to as a “channel.” You can configure the channels manually or using LACP. You must follow the procedures described in the section to configure the channels. Configuring Link Aggregation Manually This section describes the procedures to configure a link aggregate channel manually. Link aggregate channels increase the capacity and availability of the communication channel. You must follow the procedures described in this section to configure the link aggregate channels. Topics include: • Creating channels • Binding a channel to a network interface • Modifying channels • Unbinding a channel from a network interface • Removing channels • Enabling and disabling channels Creating Link Aggregate Channels This section describes the procedure and parameters to create a link aggregate channel. The state of the channel that you create is DOWN because the active network interfaces are not bound to a channel. To create the channel, use the channel ID parameter described in the following table. Note: Adding a channel without specifying the network interface number parameter can cause a failover. The following example describes the procedure to create the channel with ID LA/1. Parameter Description Channel ID LA channel name (in form LA/*) 74 Installation and Configuration Guide - Volume 1 To create a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Click Add. The Add Channel dialog box appears. 3. In the Channel ID drop-down list, select the link aggregate ID that you want to add, for example, LA/1. 4. Click Create and click Close. The link aggregate channel you added appears in the Channel page. This is shown in the following figure. Link Aggregate Channels Page To create a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: add channel LA/ 1 - i f num1/ 8 Binding a Network Interface to a Link Aggregate Channel This section describes the procedure to bind a network interface to a link aggregate channel. When a network interface is bound to a channel, the channel parameters have precedence over the network interface parameters. (That is, the network interface parameters are ignored.) a network interface can be bound only to one channel. Chapter 3 Basic Network Configuration 75 When a network interface is bound to a channel, it drops the VLAN configuration. When network interfaces are bound to a channel manually or using LACP, they are removed from the VLANs that they originally belonged to, and are added to the default VLAN. However, you can bind the channel back to the old VLAN, or to a new one. For example, if you bind the network interfaces 1/2 and 1/3 to a VLAN with ID 2, and then bind them to a channel LA/1, the network interfaces are moved to the default VLAN, and you can bind them to VLAN 2. The following example describes the procedure to bind the network interface 1/8 to a VLAN with ID 2. The following example describes the procedure to bind a network interface 1/8 to the channel LA/1. To bind a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel that you want to bind to a network interface, for example, LA/1. 3. Click Open. The Modify Channel dialog box appears. 4. In the Available Interface list box, select the network interface, for example, 1/8. 5. Click Add. The network interface you selected appears in the Configured list. 6. Click OK. To bind a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: bi nd channel LA/ 1 - i f num1/ 8 Modifying Link Aggregate Channels This section describes the procedure and parameters to modify link aggregate channels. To modify a link aggregate channel, use the parameters described in the following table. Parameters Descriptions State The initial state for the channel. The valid options for this parameter are ENABLED and DISABLED. The default value is ENABLED. Mode The initial mode for the channel. The valid options for this parameter are MANUAL, AUTO, and DESIRED. Connection Distribution The “connection” distribution mode for the channel. The valid options for this parameter are DISABLED and ENABLED. 76 Installation and Configuration Guide - Volume 1 The following example describes the procedure to set the speed of the channel LA/1 to 100. To modify a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel that you want to modify, for example, LA/1. 3. Click Open. The Modify Channel dialog box appears. 4. Click the Settings tab and in the Speed drop-down list box, select the speed that you want to configure, for example, 100. 5. Click OK. To modify a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: set channel LA/ 1 - speed 100 Unbinding a Network Interface froma Link Aggregate Channel This section describes the procedure to unbind a Link Aggregate Channel. The following example describes the procedure to unbind the network interface 1/8 from the channel LA/1. MAC Distribution The “MAC” distribution mode for the channel. The valid options for this parameter are SOURCE, DESTINATION, and BOTH. Speed The speed for the channel. The valid options for this parameter are AUTO, 10, 100, and 1000. Flow Control Flow control for the channel. The valid options for this parameter are OFF, RX, TX, and RXTX. HA Monitor The HA-monitoring control for the channel. The valid options for this parameter are ON and OFF. Trunk The option to select whether this port is a trunk port or not. By default, this is set to OFF for all interfaces. When ON, the port membership in all VLANs is tagged. If 802.1q behavior with native VLAN is required, use the OFF setting for this variable. The valid options for this parameter are ON and OFF. The default value is OFF. Alias The alias name for the channel. Throughput Specify the minimum required throughput for the network interface. Parameters Descriptions Chapter 3 Basic Network Configuration 77 To unbind a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel from which you want to unbind a network interface, for example, LA/1. 3. Click Open. The Modify Channel dialog box appears. 4. In the Configured list box, select the network interface. For example, select 1/8. 5. Click Remove. The channel that you have selected appears in the Available Interface list. 6. Click OK. To unbind a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: unbi nd channel LA/ 1 1/ 8 Removing Link Aggregate Channels This section describes the procedure to remove a Link Aggregate Channel. When a channel is removed, the network interfaces bound to it induce network loops that decrease network performance. You must first disable a network interface and then remove a channel. The following example describes the procedure to remove the channel, LA/1. To remove a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel that you want to remove, for example, LA/1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: r mchannel LA/ 1 78 Installation and Configuration Guide - Volume 1 Enabling and Disabling Link Aggregate Channels This section describes the procedures to enable or disable link aggregate channels. To avoid network loops, you must first disable a network interface before disabling a channel. The following example describes the procedure to disable the channel, LA/1. To disable a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel that you want to disable, for example, LA/1. 3. Click Disable. To disable a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: di sabl e i nt er f ace LA/ 1 The following example describes the procedure to enable the channel, LA/1. To enable a link aggregate channel using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. 2. Select the channel that you want to enable, for example, LA/1. 3. Click Enable. To enable a link aggregate channel using the NetScaler command line At the NetScaler command prompt, type: enabl e i nt er f ace LA/ 1 Configuring the Link Aggregate Channel Protocol The Link Aggregation Control Protocol (LACP) allows network devices to exchange link aggregation information. To perform this function, network devices configured to use the LACP protocol exchange LACP Data Units (LACPDU). To configure the link aggregate channel protocol, use the system priority parameter described in the following table. This parameter sets the priority of the system globally. Parameters Description System priority The possible values are 1 to 65535. The default value is 32768. Chapter 3 Basic Network Configuration 79 When you configure the network interface, you can configure the following LACP parameters • LACP mode • LACP time-out • Port key • Port priority Note: LACP configurations are neither propagated nor synchronized. By default, LACP is disabled on all network interfaces. You cannot use LACP to modify channels that you created manually. Thus, you cannot enable LACP on member network interfaces of a channel that you created manually. If LACP creates a channel dynamically, you cannot create, bind, unbind, or remove operations on that channel. However, you can configure parameters such as distribution mode, etc. LACP dynamically creates a channel that is deleted when LACP is disabled on all its member network interfaces. To enable LACP on a network interface, you can use the procedure to modify the network interface as described in the section “Managing Network Interfaces” on page 69. When you enable LACP on a network interface, the system creates channels dynamically. The system currently supports two channels, LA/1 and LA/2, based on the LACP Key values. Therefore, if you enable LACP on a network interface and set the LACP Key to 1, the network interface is automatically bound to the channel LA/1. Note: While enabling LACP on a network interface, you must simultaneously specify the LACP Key. The following example describes the procedure to configure the link aggregate channel protocol with a system priority of 12. To configure a link aggregate channel protocol using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Click Set LACP. The Configure LACP dialog box appears. 3. In the System Priority text box, type the priority you want to configure, for example, 12. 4. Click OK. 80 Installation and Configuration Guide - Volume 1 To configure a link aggregate channel protocol using the NetScaler command line At the NetScaler command prompt, type: set l acp - syspr i or i t y 12 Verifying the Configuration This section describes how you can verify the Link Aggregate Channel that you have configured. This is useful for troubleshooting. Viewing the Link Aggregate Channel You can view the properties such as channel ID, description, uptime, and VRID of the configured channels. The following example describes the steps to view the properties of the configured channels. The LACP settings appear as a part of the output, and one channel is created with four network interfaces bound to it. To view the link aggregate channels using the configuration utility 1. In the Navigation Pane, expand Network and click Channels. The Channels page appears in the Details Pane. The details of the available channels appear in this page. 2. Verify that the configured channel LA/1 appears. 3. Select the channel LA/1 and in the Details section, verify that the parameters displayed are as configured. To view link aggregate channels using the NetScaler command line At the NetScaler command prompt, type: show channel s Viewing the Link Aggregate Channel Protocol You can view the properties such as system priority and system MAC of the configured channels. The details of the channels can be used to troubleshoot any fault in the configuration. The following example describes the steps to view the properties of the configured channels. To view the link aggregate channel protocol using the configuration utility 1. In the Navigation Pane, expand Network and click Interfaces. The Interfaces page appears in the Details Pane. 2. Click View LACP Details. The View LACP Details dialog box appears. 3. Click Close. Chapter 3 Basic Network Configuration 81 To view the link aggregate channel protocol using the NetScaler command line At the NetScaler command prompt, type: show l acp Configuring VLANs The system supports (Layer 2) port and IEEE802.1Q tagged VLANs. VLAN configurations are useful when you need to restrict traffic to certain groups of stations. You can configure a network interface as a part of multiple VLANs using IEEE 802.1q tagging. You can configure VLANs and bind them to IP subnets. The system then performs IP forwarding between these VLANs (if it is configured as the default router for the hosts on these subnets). The system supports the following types of VLANs. • Port-Based VLANs • Default VLAN • Tagged VLAN Port-Based VLANs The membership of a port-based VLAN is defined by a set of network interfaces that share a common exclusive Layer 2 broadcast domain. You can configure multiple port-based VLANs. By default, all network interfaces on the system are members of VLAN 1. If you apply 802.1q tagging to the port, the network interface belongs to a port- based VLAN. Layer 2 traffic is bridged within a port-based VLAN, and Layer 2 broadcasts are sent to all members of the VLAN if Layer 2 mode is enabled. When you add an untagged network interface as a member of a new VLAN, it is removed from its current VLAN. Default VLAN By default, the network interfaces on the system are included in a single, port- based VLAN as untagged network interfaces. This VLAN is the default VLAN, and has a VID of 1. This VLAN exists permanently. This VLAN cannot be deleted, and its VID cannot be changed. When you add a network interface to a VLAN as an untagged member, the network interface is automatically removed from the default VLAN and added to this VLAN. If you unbind a network interface from its current port-based VLAN, it is added to the default VLAN again. Tagged VLAN support for the NetScaler IP Subnet 82 Installation and Configuration Guide - Volume 1 802.1q tagging (defined in the IEEE 802.1q standard) allows a networking device (such as the system) to add information to a frame at Layer 2 to identify the VLAN membership of the frame. Tagging allows network environments to have VLANs that span multiple devices. A device that receives the packet reads the tag and recognizes the VLAN to which the frame belongs. Some network devices do not support receiving both tagged and untagged packets on the same network interface, in particular force-10 switches.In such cases, you need to contact customer support for assistance. The network interface can be a tagged or untagged member of a VLAN. Each network interface is an untagged member of one VLAN only (its native VLAN). This network interface transmits the frames for the native VLAN as untagged frames. a network interface can be a part of more than one VLAN if the VLAN is added as a tagged member. When you configure tagging, be sure to match the configuration of the VLAN on both ends of the link. Thus, the port to which the system connects must be configured with the VLAN as that of the network interface. You can use the configuration utility to define a tagged VLAN (nsvlan) that can have any ports bound as tagged members of the VLAN. Configuring this VLAN requires a reboot of the system, and therefore must be done during initial network configuration. Note: This VLAN configuration is neither synchronized nor propagated, therefore you must perform the configuration on each unit in an HA pair independently. The best practise is to set the VLAN ID for an NSIP to 1. Applying Rules to Classify Frames Two types of rules are used to classify frames • Ingress rules • Egress rules Ingress rules Ingress rules classify each frame as belonging only to a single VLAN. When a frame is received on a network interface, the following rules are applied to classify the frame: • If the frame is untagged, or has a tag value equal to 0, the VID of the frame is set to the port VID (PVID) of the receiving interface, which is classified as belonging to the native VLAN. (PVIDs are defined in the IEEE 802.1q standard.) • If the frame has a tag value equal to FFF, the frame is dropped. Chapter 3 Basic Network Configuration 83 • The VID of the frame specifies a member of the VLAN. If the receiving network interface is not this member, the frame is dropped. For example, if a packet is sent from a subnet associated with VLAN ID 12 to a subnet associated with VLAN ID 10, the packet is dropped. If an untagged packet with VID 9 is sent from the subnet associated with VLAN ID 10 to a network interface PVID 9, the packet is dropped. Egress Rules The following egress rules are applied: • For the VID of the frame, frames are discarded if the transmission network interface is not a member of the VLAN. • During the learning process (per the IEEE 802.1q standard), the Src MAC and VID are used to update the bridge lookup table of the system. • A frame is discarded if the VLAN does not have any members. You can define members that are the network interfaces configured in the VLAN. Forwarding Packets on the System The forwarding process on the system is similar to that on any standard switch. However, the system performs forwarding only when Layer 2 mode is on. The key features of the forwarding process are: • Topology restrictions are enforced. Enforcement involves selecting each network interface in the VLAN as a transmission port, based on the state of the network interface, bridging restrictions (do not forward on the receiving network interface), MTU restrictions, and so on. • Frames are filtered based on the bridge table lookup (the FDB of the system). The bridge table lookup is based on the destination MAC and the VID. Packets addressed to the MAC address of the system are processed at the upper layers. • All broadcast and multicast frames are forwarded to each network interface that is a member of the VLAN, but forwarding occurs only if L2 mode is enabled. If L2 mode is disabled, the broadcast and multicast packets are dropped. This is also true for MAC addresses that are not currently in the bridging table. • A VLAN entry has a list of member network interfaces that are part of its untagged member set. When forwarding frames to these network interfaces, a tag is not inserted in the frame. • If the network interface is a tagged member of this VLAN, the tag is inserted in the frame when forwarding frames. 84 Installation and Configuration Guide - Volume 1 When a user sends any broadcast or multicast packets without the VLAN being identified (that is, during DAD for NSIP, ND6 for the next hop of the route), the packet is sent out on all the network interfaces with appropriate tagging. ND6 usually identifies a VLAN, and a data packet is sent on this VLAN only. Port- based VLANs are common for IPv4 and IPv6. For IPv6, prefix-based VLANs are not currently supported. Creating a VLAN You can implement VLANs in the following environments: • Single subnet • Multiple subnets • Single LAN • VLANs (no tagging) • VLANs (802.1q tagging) When you create VLANs that have only untagged network interfaces as their members, the total number of possible VLANs is limited to the number of network interfaces available in the system. If more IP subnets are required with a VLAN configuration, then 802.1q tagging must be used. To create a VLAN, use the VLAN ID parameter described in the following table. To create a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Click Add. The Create VLAN dialog box appears. 3. In the VLAN Id text box, type the ID of the VLAN, for example, 2. Parameter Description VLAN Identifiers (VIDs) Each VLAN has a VLAN identifier (VID). A VID is an integer from 1 to 4094 that uniquely identifies the VLAN to which a particular frame belongs. A maximum of 4094 VLANs are supported on the system. VID 1 is reserved for the default VLAN. Chapter 3 Basic Network Configuration 85 4. Click Create and click Close. The VLAN you added appears in the VLANs page. This is shown in the following figure. VLANs Page To create a VLAN using the NetScaler command line At the NetScaler command prompt, type: add vl an 2 Configuring VLANs in an HA Setup VLAN configuration requires the systems in a high-availability setup to have the same hardware configuration. They must also be mirror images. This is required when the configuration is synchronized between the systems, and the result is identical actions on all the systems. For example, adding network interface 0/1 to VLAN2 adds this network interface to VLAN 2 on all the participating systems in the high-availability setup. Note: If you use network interface-specific commands in an HA setup, the configurations you perform are not propagated to the other system. You must perform these commands on each system in an HA pair, to ensure that the configuration of the two systems in the HA pair remains synchronized. Configuring VLANs on a Single Subnet You must first ensure that Layer 2 Mode is enabled. In this setup: 1. The default router for the system and the servers is Router 1. 2. The Layer 2 mode of the system must be enabled for the system to have direct access to the servers. For more information about the procedure to disable Layer 2 mode, see “Enabling and Disabling Layer 2 Mode” on page 57. 86 Installation and Configuration Guide - Volume 1 3. For this subnet, a virtual server can be configured for load balancing in the system. The following figure shows the single subnet environment VLAN on a Single Subnet To configure a VLAN on a single subnet, follow the procedure described in “Creating a VLAN” on page 84. VLAN configuration parameters are not required, because the network interfaces are members of this VLAN. Chapter 3 Basic Network Configuration 87 Configuring VLANs on Multiple Subnets To configure a single VLAN across multiple subnets, you must add a VIP for the VLAN and configure the routing appropriately. The following figure shows a single VLAN configured across multiple subnets. Multiple Subnets in a Single VLAN To configure a single VLAN across multiple subnets 1. Log on to the Configuration Utility. 2. Disable Layer 2 mode (OFF). For more information about the procedure to disable Layer 2 mode, see “Enabling and Disabling Layer 2 Mode” on page 57. 3. Add a VIP. For more information about the procedure to add a VIP, see “Creating Virtual Server IP Addresses” on page 46. 4. Configure RNAT ID. For more information about the procedure to configure the RNAT ID, see the “Advanced Network Configuration” chapter of the Installation and Configuration guide, Volume 2. Note: The system only supports using the Creating Route procedure to add multiple IP subnets in single-subnet VLAN configurations. 88 Installation and Configuration Guide - Volume 1 Configuring Multiple Untagged VLANS across Multiple Subnets In environments with multiple untagged VLANs across multiple subnets, a VLAN is configured with an IP subnet. a network interface is bound to one VLAN only. The following figure shows this configuration. Multiple Subnets with VLANs - No Tagging To configure untagged VLANs across multiple subnets 1. Log on to the Configuration Utility. 2. Add VLAN 2. For more information about the procedure to create a VLAN, see “Creating a VLAN” on page 84. 3. Bind the 1/ 2 network interface of the system to VLAN 2 as an untagged network interface. For more information about the procedure to bind a network interface to a VLAN, see “Binding a Network Interface to a VLAN” on page 90. 4. Bind the IP address and netmask to VLAN 2. For more information about the procedure to bind an IP address to a VLAN, see “Binding an IP Address to a VLAN” on page 90. Chapter 3 Basic Network Configuration 89 Configuring Multiple VLANs with 802.1q Tagging In this environment, each VLAN is configured with a different IP subnet. Each network interface is in one VLAN. One of the VLANs is set up as tagged. The following figure shows this configuration. Multiple VLANs with IEEE 802.1q Tagging To configure multiple VLANs with 802.1q tagging 1. Log on to the Configuration Utility. 2. Add VLAN 2. For more information about the procedure to create a VLAN, see “Creating a VLAN” on page 84. 3. Bind the 1/ 2 network interface of the system to VLAN 2 as an untagged network interface. For more information about the procedure to bind a network interface to a VLAN, see “Binding a Network Interface to a VLAN” on page 90. 4. Bind the IP address and netmask to VLAN 2. For more information about the procedure to bind an IP address to a VLAN, see “Binding an IP Address to a VLAN” on page 90. 5. Add VLAN 3. For more information about the procedure to create a VLAN, see “Creating a VLAN” on page 84. 90 Installation and Configuration Guide - Volume 1 6. Bind the 1/ 2 network interface of the system to VLAN 3 as a tagged network interface. For more information about the procedure to bind a network interface to a VLAN, see “Binding a Network Interface to a VLAN” on page 90. For more information about the procedure to bind a tagged network interface, see “Modifying a VLAN” on page 91. 7. Bind the IP address and netmask to VLAN 3. For more information about the procedure to bind an IP address to a VLAN, see “Binding an IP Address to a VLAN” on page 90. Binding a Network Interface to a VLAN When you bind a network interface to a VLAN, the network interface is moved from the default VLAN. You can bind the network interfaces as tagged members to the VLANs, if the network interfaces need to be a part of more than one VLAN. To bind a network interface to a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN to which you want to bind the network interface, for example, 2. 3. Click Open. The Modify VLAN dialog box appears. 4. Under Interfaces, select the Active check box corresponding to the interface that you want to bind to the VLAN, for example, 1/8. 5. Click OK. To bind an interface to a VLAN using the NetScaler command line At the NetScaler command prompt, type: bi nd vl an 2 - i f num1/ 8 Binding an IP Address to a VLAN You can configure the system to forward traffic between VLANs at Layer 3. A VLAN is associated with a single IP subnet. The hosts in a VLAN that belong to a single subnet use the same subnet mask, and one or more default gateways connected to that subnet. Configuring Layer 3 for a VLAN is optional. It is used for IP forwarding (inter- VLAN routing). Each VLAN has a unique IP address and netmask that define an IP subnet for the VLAN. In an HA configuration, this IP address is shared with the other systems. The system forwards packets between configured IP subnets (VLANs). Chapter 3 Basic Network Configuration 91 Note: When you configure the system, you must not create overlapping IP subnets, as doing so impedes Layer 3 functionality. Each VLAN is a unique Layer 2 broadcast domain. Two VLANs, each bound to separate IP subnets, cannot be combined into a single broadcast domain. Forwarding traffic between two VLANs requires a Layer 3 forwarding (routing) device, such as the system. For a VLAN, a route added in the route table defines the IP subnet for the VLAN. A route is added for the gateway is a SNIP for the gateway. When you bind an IP address to a VLAN, the system need not use the bound IP address to proxy the traffic to the VLAN and can select SNIP or MIP. Note: You must assign a netmask to the VIP address and then bind it to a VLAN, or the binding procedure fails. To assign a netmask to a VIP use one of procedures described in the “Configuring IP Address Types” section. The following example describes the procedure to bind the IP address 10.102.29.54 to a VLAN with ID 2. To bind an IP address to a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN for which you want to bind the IP address, for example, 2. 3. Click Open. The Modify VLAN dialog box appears. 4. Under IPs, select the Active check box corresponding to the IP address that you want to bind to the VLAN, for example, 10.102.29.54. 5. Click OK. To bind an IP address to a VLAN using the NetScaler command line At the NetScaler command prompt, type: bi nd vl an 2 - I PAddr ess 10. 102. 29. 54 255. 255. 255. 0 Modifying a VLAN This section describes the procedure to modify a VLAN. The following example describes the procedure to configure a tagged network interface. 92 Installation and Configuration Guide - Volume 1 To modify a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN that you want to modify, for example, 2. 3. Click Open. The Modify VLAN dialog box appears. 4. Under Interfaces, select the Tagged check box corresponding to the network interface that must be tagged, for example, 1/8. 5. Click OK. To make a network interface a tagged member of a VLAN using the NetScaler command line, you must first unbind the network interface from the VLAN, then bind it as a tagged member as shown in the following procedure. For more information about unbinding a network interface from a VLAN, see “Unbinding a Network Interface from a VLAN” on page 92. To modify a VLAN using the NetScaler command line At the NetScaler command prompt, type: unbi nd vl an 2 - i f num1/ 8 bi nd vl an 2 - i f num1/ 8 - t agged Managing a VLAN This section describes the procedures to remove a VLAN, and to unbind a network interface from a VLAN. Unbinding a Network Interface froma VLAN The following example describes the procedure to unbind the network interface 1/8 from a VLAN with ID 2. To unbind a network interface from a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN from which you want to unbind the network interface, for example, 2. 3. Click Open. The Modify VLAN dialog box appears. 4. Under Interfaces, clear the Active check box corresponding to the interface that you want to unbind from the VLAN, for example, 1/8. 5. Click OK. Chapter 3 Basic Network Configuration 93 To unbind an interface to a VLAN using the NetScaler command line At the NetScaler command prompt, type: unbi nd vl an 2 - i f num1/ 8 Unbinding an IP Address froma VLAN The following example describes the procedure to unbind the IP address 10.102.29.54 from a VLAN with ID 2. To unbind an IP address from a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN from which you want to unbind the IP address, for example, 2. 3. Click Open. The Modify VLAN dialog box appears. 4. Under IPs, clear the Active check box corresponding to the IP address that you want to unbind from the VLAN, for example, 10.102.29.54. 5. Click OK. To unbind an IP address to a VLAN using the NetScaler command line At the NetScaler command prompt, type: unbi nd vl an 2 - I PAddr ess 10. 102. 29. 54 255. 255. 255. 0 Removing a VLAN This section describes the procedure to remove a VLAN. When you remove a VLAN, the network interfaces are bound to the default VLAN. To remove a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN that you want to remove, for example, 2. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a VLAN using the NetScaler command line At the NetScaler command prompt, type: r mvl an 2 94 Installation and Configuration Guide - Volume 1 Verifying the Configuration This section describes the procedure to verify the VLAN that you have configured. This is useful for troubleshooting. Viewing VLANs You can view the properties such as VLAN ID, members, and tagging of the configured VLANs. The details of the VLANs can be used to troubleshoot any fault in the configuration. The following example describes the steps to view the properties of the VLANs. To view VLANs using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. The details of the available VLANs appear in this page. 2. Verify that the configured VLAN with ID 2 appears. 3. Select the VLAN with ID 2 and in the Details section, verify that the parameters displayed are as configured. To view the VLAN using the NetScaler command line At the NetScaler command prompt, type: sh vl an Viewing the Statistics of a VLAN You can view the statistics of configured VLANs, such as packets received, bytes received, packets sent, bytes sent, and so on. These statistics can be used to find anonymous values and to help debug a VLAN. The following example describes the steps to view the statistics of a VLAN with ID 2. To view the statistics of a VLAN using the configuration utility 1. In the Navigation Pane, expand Network and click VLANs. The VLANs page appears in the Details Pane. 2. Select the VLAN whose statistics you want to view, for example, 2. 3. Click Statistics. The VLAN Statistics dialog box appears. This page displays the following information about the selected VLAN: Packets received, Bytes Received, Packets sent, Bytes sent and so on. To view the statistics of a VLAN using the NetScaler command line At the NetScaler command prompt, type: st at vl an 2 Chapter 3 Basic Network Configuration 95 Configuring VMAC The primary and secondary nodes in a high availability (HA) setup share the floating entity, Virtual MAC address (VMAC). The primary node owns the floating IP addresses (such as MIP, SNIP, VIP, and so on). The primary node responds to ARP requests for these IP addresses with its own MAC address. Therefore, the ARP table of an external device, such as an upstream router, is updated with the floating IP address and the MAC address of the primary node. When a failover occurs, the secondary node takes over as the new primary node. The secondary node uses GARP to advertise the floating IP addresses that it learns from the primary node. The MAC address that the new primary advertises is the MAC address of its own network interface. Some devices (a few routers) do not accept these GARP messages. Therefore, these external devices retain the IP address-to-MAC address mapping that the old primary node formerly advertised. This may result in a GSLB site going down. You must configure a VMAC on both nodes of an HA pair. This means that both nodes have identical MAC addresses. When a failover occurs, the MAC address of the secondary node remains unchanged, and the ARP tables on the external devices do not need to be updated. For more information on the procedures to configure a VMAC, see the “High Availability” chapter of the Installation and Configuration guide, Volume 1. Configuring Access Control Lists You can configure Access Control Lists (ACLs) and configure the system to compare incoming packets against the ACLs. If a packet matches an ACL rule, the system applies the action specified by the rule. Otherwise, the system applies the default action (ALLOW), and the packet is processed normally. Two types of ACLs are available on the system, • Simple ACLs • Extended ACLs 96 Installation and Configuration Guide - Volume 1 Configuring Simple ACLs Simple ACLs filter a packet based only on the source IP address and destination port. Simple ACLs take precedence over extended ACLs. If a simple ACL returns the DENY value, the system takes a simple ACL action. Otherwise, the extended ACL is applied. This is illustrated by the following figure. Simple and Extended ACLs FlowSequence Creating Simple ACLs The following example describes the procedure to create a simple ACL rule1 that causes the system to drop IP packets that originate from the computer with IP address 10.102.29.10. This rule is an “all port” rule; that is, it is applied to packets from the configured IP address directed to any port. After such a rule is configured, the system does not allow you to configure a specific port rule using the same IP address, because the “all port” rule overrides any specific port rule. However, if an “all port” rule is not configured, you can configure multiple specific port rules on the system. For example, after rule1 is created, if you attempt to configure rule2 as a port 80 rule, the system shows an error. However, you can add multiple specific port rules if an “all port” rule is not configured for the same IP address. To create a simple ACL, use the parameters described in the following table. Parameters Description Name The alphanumeric name of the ACL. Source IP Address (subnet or host) The IP address of the source machine. You can also specify a range or a specific address. You can specify an IP address with a value of 0.0.0.0. Chapter 3 Basic Network Configuration 97 To create a Simple ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click Add. The Add ACL dialog box appears. 3. In the Name and Source IP Address text boxes, type the name of ACL and IP address, for example, rule1 and 10.102.29.10. 4. Click Create and click Close. The ACL you created appears in the ACLs page. This is shown in the following figure. ACLs Page To create a simple ACL using the NetScaler command line At the NetScaler command prompt, type: add si mpl eacl r ul e1 deny - sr ci p 10. 102. 29. 10 Configuring an Expiry Time on Simple ACL You can configure simple ACLs to be valid for a specified time. The specified time for which the simple ACL is valid is known as Time to Live (TTL). ACLs with TTLs are not saved when you save the configuration. To configure the TTL value, use the TTL parameter described in the following table. The following example illustrates the steps to configure a simple ACL with a TTL value of 10 seconds. You can only configure the TTL value when you create a simple ACL. You cannot modify the TTL value for the existing rule. Parameters Description TTL The time to expire this ACL (in seconds). The minimum value is 1 and the maximum value is 0x7FFFFFFF. 98 Installation and Configuration Guide - Volume 1 To configure an expiry time using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click Add. The Add ACL dialog box appears. 3. In the Name, Source IP Address and TTL (secs) text boxes, type the name of the ACL, the IP address, and the TTL, for example, Block_20, 10.102.29.20, and 10. 4. Click Create and click Close. The ACL you created appears in the ACLs page. To configure an expiry time using the NetScaler command line At the NetScaler command prompt, type: add si mpl eacl bl ock_20 deny - sr ci p 10. 102. 29. 11 - TTL 10 Removing Simple ACL This section describes the procedure to remove simple ACLs. To remove a simple ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Select the ACL that you want to remove, for example, rule1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a simple ACL using the NetScaler command line At the NetScaler command prompt, type: r emove si mpl eacl r ul e1 Clearing all Simple ACLs This section describes the procedure to remove all configured ACLs. To remove all simple ACLs using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click Clear. The Clear Simple ACL (s) pop-up window appears. 3. Click Yes. Chapter 3 Basic Network Configuration 99 To remove all simple ACLs using the NetScaler command line At the NetScaler command prompt, type: cl ear si mpl eacl Verifying the Configuration This section describes the procedure to verify the ACLs that you have configured. This is useful for troubleshooting. Viewing an Simple ACL You can view the properties such as name, action, and protocol of the configured ACLs. The details of the ACLs can be used to troubleshoot any fault in the configuration. The following example describes the steps to view the properties of the ACLs. To view the ACLs using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. The details of the available ACLs appear in this page. 2. Verify that the configured ACL rule1 appears. 3. Select the ACL rule1 and in the Details section, verify that the parameters displayed are as configured. To view the simple ACLs using the NetScaler command line At the NetScaler command prompt, type: show si mpl eacl Viewing the Statistics of a Simple ACL This section describes the procedure to view the statistics of an ACL. You can use the statistics of the ACLs to find the anonymous values and debug the working of the ACL. To view the statistics of a simple ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Select the ACL whose statistics you want to view, for example, rule1. 3. Click Statistics. The ACL Statistics dialog box appears. This page displays the following information about the selected simple ACL: Simple ACL Hits, Allow Simple ACL Hits, Deny Simple ACL Hits, Bridge Simple ACL Hits, and Simple ACL Misses. 100 Installation and Configuration Guide - Volume 1 To view the statistics of the simple ACLs using the NetScaler command line At the NetScaler command prompt, type: st at si mpl eacl Configuring Extended ACLs Extended ACLs can filter packets based on the parameters of the packet, such as source IP address, source port, action, and so on. When you configure simple and extended ACLs, the simple ACLs take precedence over the extended ACLs. Creating Extended ACLs This section describes the procedure to create extended ACLs. An ACL defines the condition that a packet must satisfy for the system to process the packet, bridge the packet, or drop the packet. These actions are known as “processing modes.” The processing modes are: • ALLOW - The system processes the packet. • BRIDGE – The system bridges the packet to the destination without processing it. • DENY – The system drops the packet. The system processes an IP packet directly when both of the following conditions exist: • ACLs are configured on the system. • The IP packet does not match any of the ACLs The system does not support outbound ACLs. For example, you create an ACL that denies the packets from destination IP address 10.102.29.234. When the system sends a ping request to 10.102.29.234, it is not evaluated by the blockping ACL, because the traffic originated from the system. To configure an extended ACL, use the parameters described in the following table. Parameters Description Name The alphanumeric name of the ACL. Source IP Address (subnet or host) The IP address of the source machine. You can specify a range or a specific address. You can also specify an IP address with a value of 0.0.0.0. Action The action associated with the ACL. The valid options for this parameter are BRIDGE, DENY, and ALLOW. Operator You can use the following operators while creating ACLs: =and !=. Chapter 3 Basic Network Configuration 101 You cannot create two ACLs with the same parameters. If you attempt to create a duplicate, an error message appears. Note: You must configure the simple ACL first, before configuring an extended ACL. The following example describes the procedure to create an ACL named rule. The system drops the IP packets originating from the device when its source IP address is between 10.102.0.0 and 10.102.255.255. To create an extended ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and click Add. The Add ACL dialog box appears. 3. In the Name text box, type the name of the ACL, for example, rule1. 4. In the Action and Operator list boxes, select the action and operator that you want to configure, for example, DENY and =. 5. Under Source, in the Low and High text boxes, type the IP addresses, for example, 10.102.0.0 and 10.102.255.255. 6. Click Create and click Close. The ACL you created appears in the ACLs page. This is shown in the following figure. Extended ACL Page To create a extended ACL using the NetScaler command line At the NetScaler command prompt, type: add ns acl r ul e1 deny - sr ci p 10. 102. 0. 0- 10. 102. 255. 255 102 Installation and Configuration Guide - Volume 1 Applying an ACL After you create an extended ACL, you must activate it using the following procedure. This procedure re-applies all of the ACLs. For example, if you have created the ACLs rule1 through rule10, and then you create rule11 ACL, all of the ACLs (rule1 through rule11) are freshly applied. If a session has a DENY ACL related to it, the session is destroyed. You must apply this procedure after every action you perform on an ACL. For example, you must follow this procedure after disabling an ACL. Note: Extended ACLs created on the system do not work until they are applied. To apply an ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and select the ACL that you want to apply, for example, rule1. 3. Click Commit. TheApply ACL(s) pop-up window appears. 4. Click Yes. To apply an ACL using the NetScaler command line At the NetScaler command prompt, type: appl y ns acl s Managing ACLs This section describes the parameters and procedures to remove, enable, and disable simple and extended ACLs. Removing Extended ACLs This section describes the procedure to remove extended ACLs. To remove a simple ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and select the ACL that you want to remove. 3. Click Remove. TheRemove pop-up window appears. 4. Click Yes. Chapter 3 Basic Network Configuration 103 To remove an ACL using the NetScaler command line At the NetScaler command prompt, type: r mns acl r ul e1 Clearing all Extended ACLs This procedure provides instruction to remove the configured extended ACLs. To remove all extended ACLs using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab. 3. Click Clear. The Clear ACL (s) pop-up window appears. 4. Click Yes. To remove all extended ACLs using the NetScaler command line At the NetScaler command prompt, type: cl ear ns acl Enabling and Disabling an ACL This section describes the procedures to enable or disable extended ACLs. By default, the ACLs are enabled. This means that when ACLs are applied, the system compares incoming packets against the configured ACLs. If an ACL is not required to be part of the lookup table, but needs to be retained in the configuration, it must be disabled before the ACLs are applied. After the ACLs are applied, the system does not compare incoming packets against disabled ACLs. To disable an ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and select the ACL that you want to disable, for example, rule1. 3. Click Disable. To disable an ACL using the NetScaler command line At the NetScaler command prompt, type: di sabl e ns acl r ul e1 104 Installation and Configuration Guide - Volume 1 The example provides instruction to enable the ACL. To enable an ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab. 3. Select the ACL that you want to enable, for example, rule1. 4. Click Enable. To enable an ACL using the NetScaler command line At the NetScaler command prompt, type: enabl e ns acl r ul e1 Renumbering an ACL This section describes the procedure to renumber ACLs. This procedure resets the priorities of the ACLs to multiples of 10. For more information about priorities, see “Modifying Extended ACLs” on page 104. To renumber ACLs using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab. 3. Click Renumber Priority(s) ACL(s). The Renumber ACL pop-up window appears. 4. Click Yes. To renumber ACL using the NetScaler command line At the NetScaler command prompt, type: r enumber ns acl Modifying Extended ACLs This section describes the procedure to modify simple and extended ACLs. You can configure the priority of an ACL. The priority (an integer value) defines the order in which the system evaluates ACLs. All priorities are multiples of 10, unless you configure a specific priority to an integer value. When you create an ACL without specifying a priority, the system automatically assigns a priority that is a multiple of 10. Chapter 3 Basic Network Configuration 105 If a packet matches the condition defined by the ACL, the system performs an action. If the packet does not match the condition defined by the ACL, the system compares the packet against the ACL with the next-highest priority. To modify the extended ACL, use the parameters listed in the following table. Parameters Description Source PORT The port address of the source machine. You can specify a range or a specific port address. You can also specify a port address with a value of 0. Destination IP Address (subnet or host) The IP address of the destination machine. You can specify a range or a specific address. You can also specify an IP address with a value of 0.0.0.0. Destination PORT The port address of the destination machine. You can specify either a range or a specific port address. You can also specify a port address with a value of 0. Source MAC Address The MAC address of the source machine. Only the last 32 bits are considered during a lookup. Protocol This is the protocol field in the IP header. The valid options for this parameter are ICMP, IGMP, TCP, EGP, IGP, ARGUS, UDP, RDP, RSVP, EIGRP, L2TP, and ISIS. Protocol Number The IP protocol number (decimal). The minimum value is 1 and the maximum value is 255. VLAN ID The VLAN ID present in the VLAN tag of the packet. The minimum value is 1 and the maximum value is 255. Interface This is the network interface on which the packet arrived. ICMP Type The ICMP message type. For example, to block DESTINATION UNREACHABLE messages, you must specify 3 as the ICMP type. For a complete list of ICMP types, see http://www.iana.org/assignments/ icmp-parameters. The minimum value is 0 and the maximum value is 255. ICMP Code The ICMP message code. For example, to block DESTINATION HOST UNREACHABLE messages, specify 3 as the ICMP type and 1 as the ICMP code. For a complete list of ICMP types, see http://www.iana.org/ assignments/icmp-parameters. The minimum value is 0 and the maximum value is 255. State The state of the ACL. The valid options for this parameter are ENABLED and DISABLED. Priority The priority of the ACL. The minimum value is 0 and the maximum value is 10240. 106 Installation and Configuration Guide - Volume 1 Consider the following example. Two ACLs, rule 1 and rule 2, are configured on the system and automatically assigned priorities 20 and 30. You need to add a third ACL, rule 3, to be evaluated immediately after Rule 1. Rule 3 must have a priority between 20 and 30. In this case, you can specify the priority as 25. The following procedure describes the steps to set the priority of rule1 to 20. To modify the priority of an ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and select the ACL that you want to modify, for example, rule1. 3. Click Open. TheConfigure ACL(s) dialog box appears. 4. In the Priority text box, type the priority that you want to configure on the ACL, for example, 20. 5. Click OK. To modify the priority of an ACL using the NetScaler command line At the NetScaler command prompt, type: set acl r ul e1 - pr i or i t y 10 Verifying the Configuration This section describes the procedure to verify the ACLs that you have configured. This can be useful for troubleshooting. Viewing an Extended ACL You can view the properties such as name, action, and protocol of the configured ACLs. Use the following procedure to view the extended ACLs. To view extended ACLs using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACLs tab. The details of the available ACLs appear in this page. 3. Verify that the configured ACL rule1 appears. 4. Select the ACL rule1 and in the Details section, verify that the parameters displayed are as configured. Chapter 3 Basic Network Configuration 107 To view extended ACLs using the NetScaler command line At the NetScaler command prompt, type: show ns acl Viewing the Extended Statistics of an ACL Use the following procedure to view the statistics of the extended ACLs. To view the statistics of an extended ACL using the configuration utility 1. In the Navigation Pane, expand Network and click ACLs. The ACLs page appears in the Details Pane. 2. Click the Extended ACL tab and select the ACL whose statistics you want to view, for example, rule1. 3. Click Statistics. The ACL Statistics dialog box appears. This page displays the following information about the selected extended ACL: ACL Hits, NAT ACL Hits, Allow ACL Hits, Deny ACL Hits, Bridge ACL Hits, and ACL Misses. To view the statistics of an extended ACL using the NetScaler command line At the NetScaler command prompt, type: st at ns acl r ul e1 Configuring Bridge Tables This section describes the steps to configure bridge tables for bridging frames. The system bridges frames based on bridge table lookup of the destination MAC address and the VLAN ID. Packets addressed to the MAC address of the system are processed at the upper layers. The forwarding process on the system is similar to that on any standard switch. However, the system performs forwarding only when Layer 2 mode is enabled. For more information about enabling Layer 2 mode, see “Enabling and Disabling Layer 2 Mode” on page 57. Modifying Bridge Tables This section describes the procedure to modify bridge tables. To modify the bridge table, use the bridge age parameter described in the following table. Parameter Description Bridge Age The bridge ageing time in seconds. The default value is 300. The minimum value is 60 and the maximum value is 300. 108 Installation and Configuration Guide - Volume 1 The following procedure describes the steps to configure the ageing time to 70 seconds. To modify a bridge table using the configuration utility 1. In the Navigation Pane, expand Network and click Bridge Table. The Bridge Table page appears in the Details Pane. 2. Select the MAC address for which you want to configure the ageing time, for example, 00:12:01:0a:5f:46. 3. Click Change Ageing Time. The Change Ageing Time dialog box appears. 4. In the Ageing Time (seconds) text box, type the ageing time, for example, 70. 5. Click OK. The MAC you selected is configured with the ageing time. This is shown in the following figure. Bridge Table Page To modify a bridge table using the NetScaler command line At the NetScaler command prompt, type: set br i dget abl e - br i dgeAge 70 Verifying the Configuration This section describes the procedure to verify a bridge table that you have configured. This can be useful for troubleshooting. Viewing the Properties of a Bridge Table This section describes the procedure to view a bridge table. Chapter 3 Basic Network Configuration 109 To view the bridge table using the configuration utility 1. In the Navigation Pane, expand Network and click Bridge Table. The Bridge Table page appears in the Details Pane. The details of the available bridge tables appear in this page. 2. Verify that the configured bridge table appears. 3. Select the configured bridge table and in the Details section, verify that the parameters displayed are as configured. To view the bridge table using the NetScaler command line At the NetScaler command prompt, type: show br i dget abl e Viewing the Statistics of a Bridge Table This section describes the procedure to view the bridging statistics. To view the statistics of a bridge table using the configuration utility 1. In the Navigation Pane, expand Network and click Bridge Table. The Bridge Table page appears in the Details Pane. 2. Select the MAC address for which you want to view the statistics, for example, 00:12:01:0a:5f:46. 3. Click Statistics. The Bridge Statistics dialog box appears. This dialog box displays the following information about the selected bridge table: Loops, Collisions, and Interface Muted To view the statistics of a bridge table using the NetScaler command line At the NetScaler command prompt, type: st at br i dge 110 Installation and Configuration Guide - Volume 1 CHAPTER 4 Load Balancing This chapter describes the load balancing (LB) feature of a Citrix NetScaler. Load balancing allows a NetScaler to distribute the client requests across multiple servers. Load balancing improves server fault tolerance and end-user response time. This chapter lists the basic and a few advanced settings that you can configure on a NetScaler. In This Chapter • How Load Balancing Works • Configuring Basic Load Balancing • Customizing Load Balancing Configuration • Protecting the Load Balancing Configuration against Failure • Managing Client Traffic • Managing and Monitoring Servers • Managing a Large Scale Deployment • Configuring Load Balancing for Commonly Used Protocols • Configuring Load Balancing in Commonly Used Deployment Scenarios • Troubleshooting Common Problems How Load Balancing Works The load balancing feature distributes client requests across multiple servers to optimize resource utilization. In a real-world scenario with a limited number of servers providing service to a large number of clients, a server can become overloaded and degrade server performance. A NetScaler uses the load balancing criteria to prevent bottlenecks by forwarding the client requests to the servers best suited to handle them. Thus, the NetScaler balances the load on the servers. 112 Installation and Configuration Guide - Volume 1 To configure load balancing, you define virtual server (vserver) to proxy multiple servers in a server farm and balance the load among them. The vserver identifies the server using the load balancing criteria and directs incoming client requests to it. When a client initiates a connection to the server, the vserver terminates the client connection and initiates a new connection with the selected server to perform load balancing. The load balancing feature provides traffic management from layer 4 (TCP and UDP) to layer 7 (FTP, HTTP, and HTTPS). Layer 7 protocol HTTP is aware of Layer 4 protocol TCP. A NetScaler uses a number of algorithms, called LB methods, to determine how to distribute the load among the servers. The default load balancing method is the Least Connections method. A typical load balancing deployment consists of the entities described in the following figure. LB architecture The entities that you must configure in a typical load balancing setup are: • Vserver. An entity that is represented by using an IP address, a port, and a protocol. The vserver IP address (VIP) is usually a public IP address. The client sends connection requests to this IP address. The vserver represents a bank of servers. • Service. An entity that is represented by using an IP address, a port, and a protocol. A service is a logical representation of a server or an application running on a server. The services are bound to the vservers. Chapter 4 Load Balancing 113 • Server object. An entity that is represented by using an IP address. The server object is usually created when you create a service. The IP address of the service is taken as the name of the server object. You can also create a server object and then create services by using the server object. • Monitor. An entity that tracks the health of the services. The NetScaler periodically probes the servers using the monitor bound to each service. If a server does not respond within a specified response timeout, and the specified number of probes fails, the service is marked down. The NetScaler then performs load balancing among the remaining services. To configure load balancing, you must first create services. Then, you must create vservers and bind services to the vservers. By default, the NetScaler binds a monitor to each service. You can also assign weights to a service. The LB method uses the assigned weight to select a service. You can enable a NetScaler option to maintain persistent connections between clients and servers. For instance, in e-commerce such as shopping card usage, the server needs to maintain the state of the connection to track the transaction. To maintain the state of connection, you must configure persistence on a vserver. The NetScaler selects a server to process a client request and forwards all subsequent requests to the selected server. You can also specify persistence for a group of vservers. When you enable persistence on the group, the client requests are directed to the same selected server regardless of which vserver in the group receives the client request. When the configured idle time for persistence elapses, any vserver in the group is selected for the incoming client requests. The following sections describe the steps to configure a complete load balancing setup, for several deployment scenarios. Configuring Basic Load Balancing This section describes how to configure a basic but functional LB setup and modify it. The tasks described here serve as a basis for all future configuration tasks that you might perform. This section also covers the procedures to modify the setup, including deleting, enabling, and disabling entities. Topics include: • Configuring a Basic Setup • Modifying an Existing Load Balancing Configuration 114 Installation and Configuration Guide - Volume 1 Configuring a Basic Setup This section describes the topology of a basic LB setup. It also describes how to create the vservers and services using the basic topology. A basic LB setup uses only the mandatory parameters, and serves as the first step in configuring the load balancing feature on a NetScaler. The basic LB setup provides a simple and functional LB configuration as described in the following section. Understanding the Topology In a load balancing setup, the NetScalers are logically located between the client and the server farm. Load balancing is used to manage traffic flow to the servers in the server farm. The following diagram shows the topology of a basic load balancing configuration. Basic load balancing topology In the diagram, load balancing is used to manage traffic flow to the servers. The vserver selects the service and assigns it to serve client requests. Consider a scenario where the services Service-HTTP-1 and Service-HTTP-2 are created and bound to the vserver named Vserver-LB-1. Vserver-LB-1 forwards the client request to either Service-HTTP-1 or Service-HTTP-2. The NetScaler selects the service for each request using the Least Connections load balancing method. The following table lists the names and values of the basic entities that must be configured on the NetScaler. Entity Type Mandatory Parameters and Sample Values Name IP Address Port Protocol Vserver Vserver-LB-1 10.102.29.60 80 HTTP Chapter 4 Load Balancing 115 The following figure shows the load balancing sample values and mandatory parameters that are described in the preceding table. Load balancing entity model Enabling Load Balancing To use the load balancing feature, you must enable load balancing. You can configure load balancing entities though the load balancing feature is disabled. However, the entities will not work. To enable load balancing using the configuration utility 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under Modes & Features, click basic features. The Configure Basic Features dialog box appears. 3. Select the Load Balancing check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. Services Service-HTTP-1 10.102.29.5 8083 HTTP Service-HTTP-2 10.102.29.6 80 HTTP Monitors Default None None None Entity Type Mandatory Parameters and Sample Values Name IP Address Port Protocol 116 Installation and Configuration Guide - Volume 1 To enable load balancing using the NetScaler command line At the NetScaler command prompt, type: enable feature lb Creating Services You can add, modify, bind, and remove services. Once configured, services are in the disabled state until the NetScaler can reach the server on the network and monitor its status. To create services, use the mandatory parameters as described in the following table. Before you create a service, you need to understand the service types and the usage of each type. NetScaler supports the following service types: • HTTP. For HTTP services and virtual servers. To enable the Layer 7 benefits for HTTP connections such as compression, content filtering, caching, and Client Keep Alive, you can configure services and virtual servers of type HTTP. Because HTTP is a TCP based application protocol, you may alternatively use service type TCP, however, in this case, the NetScaler will only perform Layer 4 load balancing and will not provide the Layer 7 benefits listed above, as well as the following: • Vserver IP Port Insertion • Redirect Port Rewrite • Push • Redirect URL • SSL. For HTTPS services and virtual servers. Select this service type to configure the NetScaler to encrypt and decrypt (offload) SSL traffic. Alternatively, you can use service types SSL_BRIDGE, SSL_TCP, or TCP, Parameter Description Name The name of the service. The service name must not be longer than 31 characters, and must not contain spaces. This setting cannot be changed after the service is created. Server Name or IP address The IP address of the service. When you provide the IP address of the service, a server object is created with this IP address as its name. You can also create a server and use the server name instead of the IP address. Service Type Behavior of the service. Select one of the following service types: HTTP, SSL, FTP, TCP, SSL_TCP, UDP, SSL_BRIDGE, NNTP, DNS, ANY, SIP-UDP, DNS-TCP, and RTSP. Port The port on which the service listens. The port number must be a positive number not greater than 65535. Chapter 4 Load Balancing 117 however in these cases, the NetScaler performs only Layer 4 load balancing, and the server must encrypt and decrypt the SSL traffic. Also, with service type SSL_Bridge, SSL_TCP, and TCP no Layer 4-Layer 7 processing can be done, such as persistence based on HTTP information, content switching, rewrite, etc., and the following options are not supported: • Vserver IP Port Insertion • Push • Redirect URL • FTP. For FTP services and virtual servers. This setting ensures that the NetScaler takes care of the specifics of the FTP protocol. Alternatively, you can use service type TCP with the appropriate additional service type ANY virtual server. • TCP. For any TCP services or virtual servers for which a more specific service type is not available. Alternatively, you can use service type ANY. • SSL_TCP. For non-HTTP-based SSL services and virtual servers. Alternatively, you can use service type TCP, however in this case, NetScaler performs Layer 4 load balancing, but not SSL offloading and the server must encrypt and decrypt the SSL traffic. • UDP. For User Datagram Protocol services and virtual servers. Alternatively, you can use service type ANY. • SSL_BRIDGE. For services and virtual servers using the SSL protocol when you do not want the NetScaler to encrypt or decrypt the SSL traffic. Alternatively, you can use SSL_TCP for the service type. • NNTP. For Network News Transfer Protocol services or virtual servers, typically used for Usenet. • DNS. For Domain Name System services and virtual servers. With service type DNS, the NetScaler will validate the packet format of the DNS requests and responses, it can cache the DNS responses, and it will be possible to apply DNS policies to the service or vserver. Alternatively, you can use service type UDP, but in this case the NetScaler will only perform Layer 4 load balancing and will not provide the other benefits possible with the DNS service type. • ANY. For any TCP, UDP, and Internet control message protocol (ICMP) services or virtual servers. The ANY parameter is used primarily with firewall load balancing and link load balancing. 118 Installation and Configuration Guide - Volume 1 • SIP-UDP. For UDP-based Session Initiation Protocol (SIP) connections. SIP initiates, manages, and terminates multimedia communications sessions and has emerged as the standard for Internet telephony (VoIP). Alternatively, you can use service type UDP, but in this case the NetScaler performs only Layer 4 load balancing for SIP servers. • DNS-TCP. For enabling the NetScaler to act as a proxy for TCP traffic sent to DNS severs. With service type DNS-TCP, the NetScaler will validate the packet format of the DNS requests and responses, and it can cache the DNS responses. Alternatively, you can use service type TCP, but, the NetScaler will not parse DNS queries and it will only perform Layer 4 load balancing of external DNS name servers. • RTSP. For Real Time Streaming Protocol services and virtual servers. RTSP provides delivery of multimedia and other streaming data. Select this type to support media streams, such as audio and video. Alternatively, you can use service type TCP protocol, but in this case, the NetScaler will not parse the RTSP traffic, it will perform Layer 4 load balancing only, and the following options are not supported: • RTSPID persistence • RTSP Natting • DHCPRA. For Dynamic Host Configuration Protocol (DHCP) services and virtual servers. The DHCPRA service type can be used to relay DHCP requests and responses between VLANs. Note: For more information about SSL and SSL TCP service types, see the “Secure Sockets Layer (SSL) Acceleration” chapter. The following procedure describes the steps to create a service. The sample values are listed in the topology summary table on Chapter 4, " 10.102.29.60". To create a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name, Server, and Port text boxes, type the name, IP address, and port of the service, for example, Service-HTTP-1, 10.102.29.5, and 8083. 4. In the Protocol list, select the type of the service, for example, HTTP. Chapter 4 Load Balancing 119 5. Click Create and click Close. The service you created appears in the Services page, as shown in the following figure. Services page To create a service using the NetScaler command line At the NetScaler command prompt, type: add service Service-HTTP-1 10.102.29.5 HTTP 80 Creating Servers A server object is an entity that is created when you create a service. The IP address of the service is taken as the name of the server object. You can also create a server object and then create services using the server object. To create a server, use the parameters as described in the following table. Use the following procedure to create a server. To create servers using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. The Servers page appears in the details pane. 2. Click Add. The Create Servers dialog box appears. Parameter Description Name The name of the server. The server name must not be longer than 31 characters and must not contain spaces. This setting cannot be changed after the server is created. Domain Name or IP address The IP address or the domain name of the server for which a service needs to be added. You need not specify the domain name if an IP address is specified. 120 Installation and Configuration Guide - Volume 1 3. In the Name and IP Address / Domain name text boxes, type Server-1 and 10.102.29.18. 4. Click Create and click Close. The server you created appears in the Servers page, as shown in the following figure. Servers page To create servers using the NetScaler command line At the NetScaler command prompt, type: add server Server-1 10.102.29.18 Creating a Vserver After you create a service, create a vserver. You can add, modify, and remove vservers. The state of the vserver that you create is down because the active services are not bound to it. To create a vserver, use the parameters as described in the following table. Parameter Description Name The name of the vserver. The vserver name must not exceed 31 characters and must not contain spaces. This setting cannot be changed. IP address The IP address of the vserver. This IP address (VIP) is usually a public IP address and the clients send connection requests to this IP address. Service Type Behavior of the service. Select one of the following service types: HTTP, SSL, FTP, TCP, SSL_TCP, UDP, SSL_BRIDGE, NNTP, DNS, ANY, SIP-UDP, DNS-TCP, and RTSP. Port The port on which the vserver listens for client connections. The port number must be between 0-65535. Chapter 4 Load Balancing 121 The following example describes the procedure to create a vserver named Vserver-LB-1. The sample values are listed in the topology summary table on Chapter 4, " 10.102.29.60". To create a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Click Add. The Create Virtual Server (Load Balancing) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type the name, IP address, and port of the vserver, for example, Vserver-LB-1, 10.102.29.60, and 80. 4. In the Protocol list, select the type of the vserver, for example, HTTP. 5. Click Create and click Close. The vserver you created appears in the Load Balancing Virtual Servers page, as shown in the following figure. Load balancing virtual servers page To create a vserver using the NetScaler command line At the NetScaler command prompt, type: add lb vserver Vserver-LB-1 HTTP 10.102.29.60 80 Binding the Services to the Vserver After you have created vserver and services, you can bind the services to the vserver. You can bind multiple services to a vserver. The state of the services bound to the vserver determines the state of the vserver, as follows: • If state of the bound services is down, the vserver is marked down. 122 Installation and Configuration Guide - Volume 1 • If state of one of the bound services is up or out of service, the state of the vserver is up. To load balance the incoming traffic, you must bind the services to vserver. In most cases, services are bound to vservers of the same type, but you can bind different types of services and vservers. The following table shows the supported cases. The following procedure describes the steps to bind the services to the vserver. To bind a service to a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. The services appear in the Services tab. 4. Select the Active check box next to the service that you want to bind to the vserver, for example, Service-HTTP-1. 5. Click OK. To bind a service to a vserver using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-LB-1 Service-HTTP-1 Note: You can bind a single service to multiple virtual servers. Vserver Type Service Type Comment HTTP SSL Back-end encryption SSL HTTP SSL offloading SSL_TCP TCP SSL offloading for other TCP (SSL decryption without content awareness). Chapter 4 Load Balancing 123 Verifying the Configuration To verify the configuration, you need to view the load balancing entities and the statistics of the entities in the configuration. Viewing the Properties of the Server You can view properties such as the name, state, and IP address of the configured servers. The details of the server can be used to troubleshoot any mistake in the configuration. The following procedure describes the steps to view the properties of a server named Server-1. To view the properties of servers using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. The Servers page appears in the details pane. The details of the available servers appear on this page. To view the properties of servers using the NetScaler command line At the NetScaler command prompt, type: show server server-1 Viewing the Properties of the Vserver You can view properties such as the name, state, effective state, IP address, port, protocol, method, and persistence of the configured vservers. The details of the vserver can be used to troubleshoot any mistake in the configuration. The following procedure describes the steps to view the properties of a vserver named vserver-LB-1. To view the properties of vservers using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. The details of the available vservers appear on this page. To view the properties of vservers using the NetScaler command line At the NetScaler command prompt, type: show lb vserver Vserver-LB-1 Viewing the Statistics of a Vserver You can view statistics such as the name, vserver IP address, port, vserver protocol, state, and request rate of configured vservers. You can use the statistics to troubleshoot the working of a vserver. The following procedure displays the statistics of a vserver vserver-LB-1. 124 Installation and Configuration Guide - Volume 1 To view the statistics of a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver whose statistics you want to view, for example, Vserver-LB-1. 3. Click Statistics to view the statistics of the vserver. To view the statistics of a vserver using the NetScaler command line At the NetScaler command prompt, type: stat lb vserver Vserver-LB-1 Viewing the Properties of the Service You can view the name, state, IP address, port, protocol, maximum client connection, maximum requests per connection, and server type of the configured services, and use this information to troubleshoot any mistake in the service configuration. The following example describes the steps to view the properties of a service named service-HTTP-1. To view the properties of services using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears on the right page. The details of the available services appear in this pane. To view the properties of services using the NetScaler command line At the NetScaler command prompt, type: show service Service-HTTP-1 Viewing the Statistics of a Service You can view the rate of requests, responses, request bytes, response bytes, current client connections, requests in surge queue, current server connections, and so on using the service statistics. The following procedure displays the statistics of a service named Service-HTTP-1. To view the statistics of a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service whose statistics you want to view, for example, Service-HTTP-1. 3. Click Statistics. The statistics appear in a new window. Chapter 4 Load Balancing 125 To view the statistics of a service using the NetScaler command line At the NetScaler command prompt, type: stat service Service-HTTP-1 Viewing the Bindings of a Service You can view the list of vservers to which the service is bound. The binding information also provides the name, IP address, port and state of the vservers to which the services are bound. You can use the binding information to troubleshoot any problem in the binding the services to vservers. The following procedure displays the binding information for a service. To view the bindings of a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service whose binding information you want to view, for example, Service-HTTP-1. 3. Click Show Bindings. The bindings of the service you selected appear in the Bindings Info for Service: Service-HTTP-1 dialog box. To view the bindings of a service using the NetScaler command line At the NetScaler command prompt, type: show service bindings Service-HTTP-1 Modifying an Existing Load Balancing Configuration This section describes how to modify the basic LB setup you configured previously. This section also describes the impact of modifying an entity in the basic LB setup. Modifying a basic LB setup allows you manage the entities configured in the setup. You can perform tasks such as enabling, disabling, and removing entities in the basic LB setup to modify the setup, using the procedures described in this section. Managing Servers This section describes how to manage the servers you create in a basic LB setup. After creating servers, you can enable, disable, or remove them. Each task that you perform has an impact on the services that use the server, as described in the following sections. 126 Installation and Configuration Guide - Volume 1 Removing a Server When you create a service, a server with the IP address of the service is created, if the server does not exist. If you remove the server, the service is also deleted. The following example describes the steps to remove a server with IP address 10.102.29.5. To remove a server using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. The Servers page appears in the details pane. 2. Select the server that you want to remove, for example, 10.102.29.5. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a server using the NetScaler command line At the NetScaler command prompt, type: rm server 10.102.29.5 Enabling and Disabling Servers You can disable a server to disable the services that use the server object. When you refresh the NetScaler, after you disable the server, the state of the services appears as Going Out of Service. When a server is disabled with specific wait time the server handles the established connections only and rejects the new connections. To disable a server, use the Wait Time parameter as described in the following table. The following example describes the steps to disable the server, 10.102.29.5 after 30 seconds. To disable a server using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. The Servers page appears in the details pane. 2. Select the server that you want to disable, for example, 10.102.29.5. 3. Click Disable. The Wait Time pop-up window appears. 4. Type the wait time after which the server is to be disabled, for example 30. 5. Click Enter. Parameter Description Wait Time The time in seconds, after which the server is marked down. Chapter 4 Load Balancing 127 To disable a server using the NetScaler command line At the NetScaler command prompt, type: disable server 10.102.29.5 30 When you enable the server and refresh the NetScaler, the services associated with the server are also enabled. The following example describes the steps to enable the server 10.102.29.5. To enable a server using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. The Servers page appears in the details pane. 2. Select the server that you want to enable, for example, 10.102.29.5. 3. Click Enable. The Enable pop-up window appears. 4. Click Yes. To enable a server using the NetScaler command line At the NetScaler command prompt, type: enable server 10.102.29.5 Managing Services This section describes how to manage the services after you create them in a basic LB setup. Managing the services allows you to modify the working of the basic LB setup. You can perform tasks such as enabling, disabling, and removing services after you create the services. Each task that you perform has an impact on the basic LB setup as described in the following sections. Removing a Service You can remove a service when it is no longer used. When you remove a service, it is unbound from the vserver and deleted from the NetScaler. To remove a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service that you want to remove, for example, Service-HTTP-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a service using the NetScaler command line At the NetScaler command prompt, type: 128 Installation and Configuration Guide - Volume 1 rm service Service-HTTP-1 Enabling and Disabling Services By default, the configured services are enabled. You can disable a service when you do not want to use the service. To disable a service, you must specify a wait time. If you do not specify the wait time, the service is disabled immediately after you disable it. During the shutdown period, the state of a service appears as Going Out of service. When a service is disabled with specific wait time the service handles the established connections only and rejects the new connections. To disable a service, use the Wait Time parameter as described in the following table. The following example describes the steps to disable the service Service-HTTP-1 after 30 seconds. To disable a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service that you want to disable, for example, Service-HTTP-1. 3. Click Disable. The Wait Time pop-up window appears. 4. In the Wait Time pop-up window, type the wait time after which the service is to be disabled, for example, 30. 5. Click Enter. To disable a service using the NetScaler command line At the NetScaler command prompt, type: disable service Service-HTTP-1 30 You can also enable the services individually. The following example describes the steps to enable the service Service-HTTP-1. To enable a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service that you want to enable, for example, Service-HTTP-1. 3. Click Enable. The Enable pop-up window appears. Parameter Description Wait Time The time in seconds, after which the services representing the server are marked down. Chapter 4 Load Balancing 129 4. Click Yes. To enable a service using the NetScaler command line At the NetScaler command prompt, type: enable service Service-HTTP-1 Managing an LB Vserver This section describes how to manage the vservers after you create them. Managing the vservers allows you to modify the working of the entities in a basic LB setup. You can perform tasks such as enabling, disabling, and removing vservers after you create them. You can also unbind a service from a vserver. Each task that you perform has an impact on the basic LB setup, as described in the following sections. Unbinding a Service froma Vserver When you unbind a service from a vserver, the NetScaler does not consider the service for load balancing. The following example describes the steps to unbind the service Service-HTTP-1 from the vserver Vserver-LB-1. To unbind a service from a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver from which you want to unbind a service, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. The services appear in the Services tab. 4. Clear the Active check box next to the service that you want to unbind from the vserver, for example, Service-HTTP-1. 5. Click OK. To unbind a service from a vserver using the NetScaler command line At the NetScaler command prompt, type: unbind lb vserver Vserver-LB-1 Service-HTTP-1 130 Installation and Configuration Guide - Volume 1 Removing a Vserver You need to remove a vserver only when you no longer require the vserver. To remove a vserver, you must first unbind the services from the vserver, and then remove the vserver. If you remove all the vservers from the NetScaler, the NetScaler does not accept any new connections. The following example describes the steps to delete the vserver Vserver-LB-1. To remove a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver that you want to remove, for example, Vserver-LB-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a vserver using the NetScaler command line At the NetScaler command prompt, type: rm lb vserver Vserver-LB-1 Enabling and Disabling Vservers You can disable a vserver for maintenance. If you disable the vserver, the state of the vserver changes to Out of Service. In this state, the vserver cannot accept new connections, but it continues to serve requests on existing connections. To disable a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver that you want to disable, for example, Vserver-LB-1. 3. Click Disable. The Disable pop-up window appears. 4. Click Yes. To disable a vserver using the NetScaler command line At the NetScaler command prompt, type: disable lb vserver Vserver-LB-1 Chapter 4 Load Balancing 131 By default, the vservers are enabled. To enable a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver that you want to enable, for example, Vserver-LB-1. 3. Click Enable. The Enable pop-up window appears. 4. Click Yes. To enable a vserver using the NetScaler command line At the NetScaler command prompt, type: enable lb vserver Vserver-LB-1 Note: In the disabled state, a vserver continues to exist on the network. The NetScaler continues to respond to ARP and ICMP requests directed to the IP address of the vserver. Customizing Load Balancing Configuration This section describes how to customize a basic LB setup to meet your requirements. You can perform the optional tasks such as the following: change the load balancing criteria, maintain persistent connection between the client and the server, and assign weights to the services. Customizing a basic LB setup allows you to change the working of the basic LB setup, as described in the following sections. 132 Installation and Configuration Guide - Volume 1 Changing the Load Balancing Algorithm The Load Balancing algorithm (LB method) defines a criterion that the NetScaler uses to select the server to which it sends client requests. When the selected server reaches the configured criteria, the NetScaler selects a different server. Load Balancing Granularity refers to the criteria that the NetScaler uses to decide the load balancing method in a given situation. The NetScaler performs request- based, connection-based, or time-based load balancing, depending on the protocol of the service (s) it is load balancing. The following table describes the types of load balancing, and the criteria that determine when each method is used. You can change the load balancing algorithm using the procedure described in this section. To configure LB method, use the LB Method parameter as described in the following table. Protocol Load balancing Granularity Description HTTP or HTTPS HTTP Request based Server selection is done for every HTTP request independent of TCP connections. TCP Connections based Server selection is done for every new TCP connection. UDP and Other IP protocols Time based Server selection is done on a UDP packet. On selection of a server, a session is created between the server and a client, for a specified period of time. When the time expires, the session is deleted and server selection is done for other packets, even if the packets come from the same client. Parameter Description LB Method The load balancing method for the vserver. The valid options for this parameter are: ROUNDROBIN, LEASTCONNECTION, LEASTRESPONSETIME, URLHASH, DOMAINHASH, DESTINATIONIPHASH, SOURCEIPHASH, SRCIPDESTIPHASH, LEASTBANDWIDTH, LEASTPACKETS, TOKEN, SRCIPDESTIPHASH, CUSTOMLOAD. The default LB method is LEASTCONNECTION. Chapter 4 Load Balancing 133 The following example describes the steps to set the vserver Vserver-LB-1 to use the least connection method to select the services for load balancing. To set LB methods using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure an LB method, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Method and Persistence tab. In the list under LB Method, select Least Connection. 5. Click OK. To set LB methods using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -lbMethod LeastConnection Understanding SlowStart When you configure a NetScaler to use a metric-based LB method such as Least Connections, Least Response Time, Least Bandwidth, Least Packets, or Custom Load, the LB method will initially start out as Round Robin for what is called a slow start. As mentioned earlier, NetScaler appliances use the configured load balancing method to determine the appropriate service for forwarding an incoming request. Load balancing environments are dynamic, and the NetScaler needs to manage the events that may overload the server. For example, when you configure the Least Connections LB method, the NetScaler selects the service that has the least number of connections. If a new server is added to the server farm, the NetScaler selects the new server with the least number of connections, and, therefore, may overload the new server. To avoid overloading servers, the NetScaler performs slow start. During the slow start phase, the NetScaler distributes requests by using Round Robin, regardless of the metric-based LB method configured on the virtual server. However, the weight assigned on the services is used by Round Robin. After the number of incoming requests or connections per second exceeds a given threshold, the NetScaler stops slow start and operates using the configured load balancing method. Slow start occurs when: 134 Installation and Configuration Guide - Volume 1 • You configure a new metric-based load balancing method. • You bind a service to the vserver. • The state of the server changes from DOWN to UP. To compute slow start, the number of services bound to the vserver is multiplied by 100. For a new virtual server with the LB method determined by dynamic traffic parameters, slow start allows time to collect a valid data sample before the correct method is applied. Note: When slow start is in operation, the output for the show l b vser ver <vser ver name>command will specify the current method as Round Robin. In GSLB setup, metric-based load balancing methods do not work correctly if MEP is DOWN except Custom Load LB method, and they will operate only in RoundRobin. For Custom Load if MEP is DOWN and custom load monitors that use SNMP to get statistics are bound to service, Custom Load LB method is used for load balancing. If local load monitors bound to service and MEP is DOWN, then Round Robin is used. For more information about GSLB, see Citrix NetScaler Installation and Configuration Guide. Configuring the Least Connection Method When the NetScaler is configured to use the least connection method, it selects the service with the least number of active connections to ensure that the load of the active requests is balanced on the services. This method is the default load balancing method because it provides the best performance. For TCP, HTTP, HTTPS and SSL_TCP services, the following connections are also considered for the least connections method: • Active connections to a service. Active connections represent the requests sent by the client to a service. But in case of HTTP and HTTPS services, active connections represent only the outstanding HTTP or HTTPS requests to services. • Waiting connections to a service in the Surge Queue. Connections can build up in the surge queue at any time because of any of the following reasons: • A connection limit exists on the service • The Surge Protection feature is configured • The server does not open new connections as in case of Apache’s connection limit. Chapter 4 Load Balancing 135 When a NetScaler uses the least connections method, it considers such waiting connections as belonging to a service. Therefore, it does not open new connections to the selected service in a timely manner. For UDP services, the connections considered for the least connections method include all sessions between the client and a service. These sessions are logical, time-based entities, and are created for the UDP packet that arrives first. When the UDP packet arrives first, the session is created for the combination of the source IP address and port, and the destination IP address and port. The following example shows how a NetScaler selects a service for load balancing by using the least connections method. Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3: • Service-HTTP-1 is handling three active transactions. • Service-HTTP-2 is handling 15 active transactions. • Service-HTTP-3 is not handling any active transactions. The following figure illustrates how the NetScaler uses the least connections method and forwards the requests to the three services. Least connections mechanism The NetScaler selects the service by using the value (N) of the following expression: N =Number of active transactions 136 Installation and Configuration Guide - Volume 1 The requests are delivered as follows: • Service-HTTP-3 receives the first because the service is not handling any active transactions. Note: The service with no active transaction is selected first. • Service-HTTP-3 receives the second and third requests because the service has least number of active transactions. • Service-HTTP-1 receives the fourth request. Because Service-HTTP-1 and Service-HTTP-3 have same number of active transactions, the NetScaler performs load balancing in a round robin manner. Therefore, Service-HTTP-3 receives the fifth request, Service-HTTP-1 receives the sixth request, Service-HTTP-3 receives the seventh request, and Service-HTTP-1 receives the eighth request and so on. Service-HTTP-2 is not considered for load balancing because it is loaded more (handling 15 active transactions) as compared to the other two services. However, if Service-HTTP-2 completes the active transactions, the NetScaler considers the service for load balancing. Also, when the services are handling the same number of active transactions, the NetScaler selects the service in a round robin manner. The manner in which a service receives requests based on the N value is summarized in the following table. Request received Service selected Current N (Number of active transaction) value Remarks Request-1 Service-HTTP-3 (N =0) N =1 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-3 (N =1) N =2 Request-3 Service-HTTP-3 (N =2) N =3 Request-4 Service-HTTP-1 (N =3) N =4 Service-HTTP-1 and Service-HTTP-3 have the same N values. Request-5 Service-HTTP-3 (N =3) N =4 Request-6 Service-HTTP-1 (N =4) N =5 Request-7 Service-HTTP-3 (N =4) N =5 Request-8 Service-HTTP-1 (N =5) N =6 Chapter 4 Load Balancing 137 Selection of services by using the least connections method when weights are assigned to the services The NetScaler also performs load balancing by using the number of connections when weights are assigned to services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (Number of active transactions) * (10000 / weight) The following example shows how the NetScaler selects a service for load balancing by using least connections method when the weights are assigned to services. In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a weight of 4. The requests are delivered as follows: • Service-HTTP-3 receives the first because the service is not handling any active transactions. Note: If services are not handling any active transactions, the NetScaler selects them in a round robin manner irrespective of the weights assigned to them. • Service-HTTP-3 receives the second, third, fourth, fifth, sixth, and seventh requests because the service has least N w value. • Service-HTTP-1 receives the eighth request. Because Service-HTTP-1 and Service-HTTP-3 have same N w value, the NetScaler performs load balancing in a round robin manner. Therefore, Service-HTTP-3 receives the ninth request. Service-HTTP-2 is selected for load balancing when it completes the active transactions or when the N value of other services (Service-HTTP-1 and Service-HTTP-3) is equal to 15. Request received Service selected Current N (Number of active transaction) value Remarks 138 Installation and Configuration Guide - Volume 1 The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-3 (N w =0) N w =2500 Service-HTTP-3 has the least N w value. Request-2 Service-HTTP-3 (N w =2500) N w =5000 Request-3 Service-HTTP-3 (N w =5000) N w =7500 Request-4 Service-HTTP-3 (N w =7500) N w =10000 Request-5 Service-HTTP-3 (N w =10000) N w =12500 Request-6 Service-HTTP-3 (N w =12500) N w =15000 Request-7 Service-HTTP-1 (N w =15000) N w =20000 Service-HTTP-1 and Service-HTTP-3 have the same N w values. Request-8 Service-HTTP-3 (N w =15000) N w =17500 Service-HTTP-2 is selected for load balancing when it completes the active transactions or when the N w value of other services (Service-HTTP-1 and Service-HTTP-3) is equal to 50000. Chapter 4 Load Balancing 139 The following figure illustrates how the NetScaler uses the least connections method when weights are assigned to the services. Least connections mechanismwhen weights are assigned To configure the Least Connection method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Least Connection. Configuring the Round Robin Method When the NetScaler is configured to use the round robin method, it rotates incoming requests to the managed servers, regardless of the load. For example, the first request is sent to Service-HTTP-1, the second to Service-HTTP-2, the third to Service-HTTP-3, and so on. When requests have been sent to all of the servers, the cycle begins again from Service-HTTP-1. 140 Installation and Configuration Guide - Volume 1 The following figure illustrates how the NetScaler uses the round robin method and forwards requests to the three services. Round robin mechanism A NetScaler also performs weighted round robin if different weights are assigned to the services. For example, Service-HTTP-1 is set to a weight of 2, Service-HTTP-2 to a weight of 3, and Service-HTTP-3 to a weight of 4, and the services are bound to Vserver-LB-1. The requests are delivered as follows: • Service-HTTP-1 receives the first request. • Service-HTTP-2 receives the second request. • Service-HTTP-3 receives the third request. • Service-HTTP-1 receives the fourth request. • Service-HTTP-2 receives the fifth and sixth request. • Service-HTTP-3 receives the seventh, eighth, and ninth requests. Note: You can configure weights on services to prevent multiple services from using the same server, overloading the server. Chapter 4 Load Balancing 141 A new cycle then begins, using the same pattern. The following figure illustrates the weighted round robin method. Round robin mechanismwhen weights are configured To configure the round robin method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Round Robin. Configuring the Least Response Time Method When the NetScaler is configured to use the least response time method, it selects the service with the least number of active connections and the least average response time. You can configure this method for HTTP and SSL type of services only. The response time (also called Time to First Byte, or TTFB) is the time interval between sending a request packet to a service and receiving the first response packet from the service. The NetScaler uses response code 200 to calculate TTFB. The following example shows how a NetScaler selects a service for load balancing by using the least response time method. Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3. • Service-HTTP-1 is handling three active transactions and TTFB is two seconds. • Service-HTTP-2 is handling seven active transactions and TTFB is one second. • Service-HTTP-3 is not handling any active transactions and TTFB is two second. 142 Installation and Configuration Guide - Volume 1 The following figure illustrates how the NetScaler uses the least response time method and forward requests to the three services. Least response time mechanism The NetScaler selects the service by using the value (N) of the following expression: N =Number of active transactions * TTFB The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because the service is not handling any active transaction. Note: The service with no active transaction is selected first. • Service-HTTP-3 receives the second and third requests because the service has the least N value. • Service-HTTP-1 receives the fourth request. Because Service-HTTP-1 and Service-HTTP-3 have same N value, the NetScaler performs load balancing in a round robin manner. Therefore, Service-HTTP-3 receives the fifth request. • Service-HTTP-2 receives the sixth request because the service has the least N value. Chapter 4 Load Balancing 143 • Service-HTTP-1 receives the seventh request. Because Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same N value, the NetScaler performs load balancing in a round robin manner. Therefore, Service- HTTP-2 receives the eighth request. The manner in which a service receives requests based on the N value is summarized in the following table. Selection of services by using the least response time method when weights are assigned The NetScaler also performs load balancing by using the number of connections, TTFB, and weights if different weights are assigned to the services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (N) * (10000 / weight) The following example shows how the NetScaler selects a service for load balancing by using the least response time method when weights are assigned on the services. In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned weight of 3, and Service-HTTP-3 is assigned weight of 4. Request received Service selected Current N (Number of active transaction * TTFB) value Remarks Request-1 Service-HTTP-3 (N =0) N =2 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-3 (N =2) N =4 Request-3 Service-HTTP-3 (N =3) N =6 Request-4 Service-HTTP-1 (N =6) N =8 Service-HTTP-1 and Service-HTTP-3 have the same N values. Request-5 Service-HTTP-3 (N =6) N =8 Request-6 Service-HTTP-2 (N =7) N =8 Service-HTTP-2 has the least N value. Request-7 Service-HTTP-1 (N =8) N =15 Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have the same N values. Request-8 Service-HTTP-2 (N =8) N =9 144 Installation and Configuration Guide - Volume 1 The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because it is not handling any active transaction. Note: If services are not handling any active transactions, the NetScaler selects them irrespective of the weights assigned to them. • Service-HTTP-3 receives the second, third, fourth, and fifth requests because the service has the least N w value. • Service-HTTP-2 receives the sixth request because the service has the least N w value. • Service-HTTP-3 receives the seventh request because the service has the least N w value. • Service-HTTP-2 receives the eighth request because the service has the least N w value. Service-HTTP-1 has the least weight and the N w value is the highest. Therefore, the NetScaler does not select it for load balancing. The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-3 (N w =0) N w =2500 Service-HTTP-3 has the least N w value. Request-2 Service-HTTP-3 (N w =2500) N w =5000 Request-3 Service-HTTP-3 (N w =5000) N w =15000 Request-4 Service-HTTP-3 (N w =15000) N w =20000 Request-5 Service-HTTP-3 (N w =20000) N w =25000 Request-6 Service-HTTP-2 (N w =23333.34) N w =26666.67 Service-HTTP-2 has the least N w value. Request-7 Service-HTTP-3 (N w =25000) N w =30000 Service-HTTP-3 has the least N w value. Chapter 4 Load Balancing 145 The following figure illustrates how the NetScaler uses the least response time method when weights are assigned on the services. Least response time mechanismwhen weights are assigned To configure the least response time method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Least Response Time. Request-8 Service-HTTP-2 (N w =26666.67) N w =33333.34 Service-HTTP-2 has the least N w value. Service-HTTP-1 is selected for load balancing when it completes the active transactions or when the N w value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to 105000. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks 146 Installation and Configuration Guide - Volume 1 Configuring the Least Response Time Method Using Monitors When the NetScaler is configured to use the least response time method with monitors, it selects the service with the least number of active transactions and the fastest average response time of monitors. In this load balancing method the NetScaler uses the existing monitoring infrastructure. Therefore, before you use this method, you must bind application-specific monitors to each service, and enable LRTM mode on these monitors. The NetScaler then makes load balancing decisions based on the response times received from the monitoring probes. For more information about configuring monitors, see the section “Configuring Monitors in an LB Setup” on page 223. Least response time method with monitors can be used to select non-HTTP and non-HTTPS services unlike the least response time method without monitors. You can also use this method when several monitors are bound to a service. The vserver reads the response times of all monitors and calculates an average response time for each service. Monitors determine response times according to different protocols. The following table summarizes how response times are calculated for various monitors. Monitor Response Time Calculation PING Time difference between the ICMP ECHO request and the ICMP ECHO response. TCP Time difference between the SYN request and the SYN+ACK response. HTTP Time difference between the HTTP request (after the TCP connection is established) and the HTTP response. TCP-ENV Time difference between the time the data send string is sent and the data receive string is returned. A tcp-ecv monitor without the send and receive strings is considered to have an incorrect configuration. HTTP-ECV Time difference between the HTTP request and the HTTP response. UDP-ECV Time difference between the UDP send string and the UDP receive string. A udp-ecv monitor without the receive string is considered to have an incorrect configuration. DNS Time difference between a DNS query and the DNS response. TCPS Time difference between a SYN request and the SSL handshake completion. FTP Time difference between the sending of the user name and the completion of user authentication. Chapter 4 Load Balancing 147 The following example shows how the NetScaler selects a service for load balancing by using the least response time method with configured monitors. Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3. • Service-HTTP-1 is handling three active transactions and the response time is five seconds. • Service-HTTP-2 is handling seven active transactions and the response time is one second. • Service-HTTP-3 is not handling any active transactions and the response time is two seconds. The following figure illustrates how the NetScaler uses the least response time method and forward requests to the three services when monitors are configured to calculate the response time. Least response time mechanismusing monitors HTTPS (monitors HTTPS requests) Time difference is same as the HTTP monitor. HTTPS-ENV (monitors HTTPS requests) Time difference is same as the HTTP-ECV monitor. USER Time difference between the time when a request is sent to the dispatcher and the time when the dispatcher responds. Monitor Response Time Calculation 148 Installation and Configuration Guide - Volume 1 The NetScaler selects the service by using the value (N) of the following expression: N =Number of active transactions * Response time that is determined by the monitor The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because the service is not handling any active transaction. Note: The service with no active transaction is selected first. • Service-HTTP-3 receives the second, third, and fourth requests because the service has the least N value. • Service-HTTP-2 receives the fifth request because the service has the least N value. • Now both Service-HTTP-2 and Service-HTTP-3 have the same N value, so the NetScaler performs load balancing in a round robin manner. Therefore, Service-HTTP-3 receives the sixth request. • Service-HTTP-2 receives the seventh and eighth requests because the service has the least N value. Service-HTTP-1 is not considered for load balancing because it is loaded more (the highest N value) as compared to the other two services. However, if Service-HTTP-1 completes the active transactions, the NetScaler considers the service for load balancing. The manner in which a service receives requests based on the N value is summarized in the following table. Request received Service selected Current N (Number of active transaction) value Remarks Request-1 Service-HTTP-3 (N =0) N =2 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-3 (N =2) N =4 Request-3 Service-HTTP-3 (N =4) N =6 Request-4 Service-HTTP-3 (N =6) N =8 Chapter 4 Load Balancing 149 Selection of services by using the least response time method when weights are assigned The NetScaler also performs load balancing by using the number of active transactions, response time, and weights, if different weights are assigned to the services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (N) * (10000 / weight) The following example shows how the NetScaler selects a service for load balancing by using the least response time method when weights are assigned to the services. In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a weight of 4. The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because it is not handling any active transaction. Note: If services are not handling any active transactions, the NetScaler selects them irrespective of the weights assigned to them. • Service-HTTP-3 receives the second, third, and fourth, requests because the service has the least N w value. • Service-HTTP-2 receives the fifth request because the service has the least N w value. Request-5 Service-HTTP-2 (N =7) N =8 Service-HTTP-1 and Service-HTTP-3 have the same N values. Request-6 Service-HTTP-3 (N =8) N =10 Request-7 Service-HTTP-2 (N =8) N =9 Service-HTTP-2 has the least N value. Request-8 Service-HTTP-1 (N =9) N =10 Service-HTTP-1 is selected for load balancing when it completes the active transactions or when the N value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to 15. Request received Service selected Current N (Number of active transaction) value Remarks 150 Installation and Configuration Guide - Volume 1 • Service-HTTP-3 receives the sixth request because the service has the least N w value. • Service-HTTP-2 receives the seventh and the eighth requests because the service has the least N w value. Service-HTTP-1 has the least weight and the highest N w value. Therefore, the NetScaler does not select it for load balancing. The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-3 (N w =0) N w =5000 Service-HTTP-3 has the least N w value. Request-2 Service-HTTP-3 (N w =5000) N w =10000 Request-3 Service-HTTP-3 (N w =15000) N w =20000 Request-4 Service-HTTP-3 (N w =20000) N w =25000 Request-5 Service-HTTP-2 (N w =23333.34) N w =26666.67 Service-HTTP-2 has the least N w value. Request-6 Service-HTTP-3 (N w =25000) N w =30000 Service-HTTP-3 has the least N w value. Request-7 Service-HTTP-2 (N w =23333.34) N w =26666.67 Service-HTTP-2 has the least N w value. Request-8 Service-HTTP-2 (N w =25000) N w =30000 Service-HTTP-2 has the least N w value. Service-HTTP-1 is selected for load balancing when it completes the active transactions or when the N w value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to 75000. Chapter 4 Load Balancing 151 The following figure illustrates how the NetScaler uses the least response time method when weights are assigned on the services. Least response time mechanismusing monitors when weights are assigned To configure the Least response time method using monitors, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select LRTM. Configuring the Hash Methods You can use hashing methods in a cache environment where a cache serves a wide range of content from the Internet or origin servers. Caching the requests reduces the request and response latency and ensures better resource utilization (CPU) at the cache. The NetScaler provides the following hashing methods: • URL hash method • Domain hash method • Destination IP hash method • Source IP hash method • Source IP Destination IP hash method • Source IP Source Port hash method • Call ID hash method 152 Installation and Configuration Guide - Volume 1 When the NetScaler is configured to use the hashing methods, it selects a service based on the hashed value of the parameter used in that method. The NetScaler caches the hashed value of the parameter. The subsequent requests that use the same parameter constitute a cache hit. The NetScaler forwards these requests to the same service. If the state of a service that is selected based on the hashed value is DOWN or if the service is deleted, the requests that must be sent to that service are hashed again. The NetScaler then sends these requests to the remaining services. Also, the NetScaler updates the cache and, therefore, its performance is degraded during high traffic. Note: It is recommended that when you adjust server pools by removing services, you should adjust the pools during low traffic periods to enable the caches to repopulate without impacting the performance. Chapter 4 Load Balancing 153 Configuring the URL Hash Method When the NetScaler is configured to use the URL hash method, it selects a service based on the hashed value of an incoming HTTP URL. The NetScaler caches the hashed value of the URL, and subsequent requests that use the same URL make a cache hit and are forwarded to the same service. By default, the NetScaler calculates the hash value based on the first 80 bytes of the URL. You must specify the Hash Length parameter to calculate a different URL value. If the NetScaler cannot accurately parse the incoming request, it uses the round robin method for load balancing. Consider a scenario where three services are bound to a vserver and the URL hash method is configured. The services are Service- HTTP-1, Service-HTTP-2, and Service-HTTP-3, and the hash value is URL1. When the services are UP, URL1 is sent to Service-HTTP-1 using the hashing result. If Service-HTTP-1 is down, the URL1 is sent to Service-HTTP-2 using the secondary hash result, as shown in the following figure. URL hashing If Service-HTTP-1 and Service-HTTP-2 are down, URL1 is sent to Service-HTTP-3. If the services are then UP, URL1 is sent to the services in the following ways: • If the Service-HTTP-2 is up, the URL1 is sent to Service-HTTP-2. • If the Service-HTTP-1 is up, the URL1 is sent to Service-HTTP-1. • If Service-HTTP-1 and Service-HTTP-2 are up at the same time, URL1 is sent to Service-HTTP-1. 154 Installation and Configuration Guide - Volume 1 To configure the URL hash method, use the Hash Length parameter as described in the following table. To configure the URL hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select URL Hash. Configuring the Domain Hash Method When the NetScaler is configured to use the domain hash method, it selects a service based on the hashed value of the domain name in the HTTP request. The domain name is taken either from the incoming URL or from the Host header of the HTTP request. If the domain name appears in both the URL and the Host header, the NetScaler gives preference to the URL. If you configure domain name hashing and an incoming HTTP request does not contain a domain name, the NetScaler defaults to the round robin method for that request. The hash value is calculated using the name length or hash length value, whichever is smaller. By default, the NetScaler calculates the hash value from the first 80 bytes of the domain name. To specify a different number of bytes in the domain name when calculating the hash value, use the Hash Length parameter. To configure the domain hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Domain Hash. Configuring the Destination IP Hash Method When the NetScaler is configured to use the destination IP hash method, it selects a service based on the hashed value of the destination IP address. You can use the subnet mask parameter to mask the destination IP address and then calculate the hash value. When the requests from different networks arrive at the NetScaler, it identifies the requests belonging to a subnet using the subnet mask and forwards the requests to the same server based on the hashed value. Parameter Description Hash Length The number of bytes that are hashed in the URL or domain name. Valid values are from 1 to 4K bytes. The default is 80 bytes. It must not exceed 4096 bytes. Chapter 4 Load Balancing 155 This method is appropriate for use with the cache redirection feature of the NetScaler. For more information about cache redirection, see the “Cache Redirection” chapter in Citrix NetScaler Installation and Configuration Guide. To configure the destination IP hash method, use the Netmask parameter as described in the following table. To configure the destination IP hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Destination IP Hash. Configuring the Source IP Hash Method When the NetScaler is configured to use the source IP hash method, it selects a service based on the hashed value of the client IP address. You must use the optional subnet mask parameter to direct the requests from source IP addresses that belong to a particular network, to one server. To configure the source IP hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Source IP Hash. Configuring the Source IP Destination IP Hash Method When the NetScaler is configured to use the source IP destination IP hash method, it selects a service based on the hashed value of the source and destination IP addresses. Hashing is symmetric, so it yields the same value if the source and destination IP addresses are reversed. This ensures that all packets flowing from a particular client to the same destination are directed to the same server. To configure the source IP destination IP hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Source IP Destination IP Hash. Configuring the Source IP Source Port Hash Method When the NetScaler is configured to use the source IP source port hash method, it selects the server based on the hash value of the source IP and source port of the incoming request. This ensures that all packets on a particular connection are directed to the same server. This method is used in the connection Mirroring and firewall load balancing. For more information about connection Mirroring, see the section “Configuring Stateful Connection Failover” on page 191. To configure the source IP source port hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Source IP Source Port Hash. Parameter Description Netmask Masks the destination IP address before calculating the hash value so that all IP addresses belonging to a particular network are directed to the same server. 156 Installation and Configuration Guide - Volume 1 Configuring the Call ID Hash Method When the NetScaler is configured to use the call ID hash method, it selects the service based on the hash value of the call ID in the SIP header, so that a particular SIP session is directed to the same proxy server. This method is applicable for SIP load balancing. For more information about SIP load balancing, see the section “Monitoring SIP Services” on page 235. To configure the call ID hash method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Call ID Hash. Configuring the Least Bandwidth Method When the NetScaler is configured to use the least bandwidth method, it selects the service that is currently serving the least amount of traffic, measured in megabits per seconds (Mbps). The following example shows how the NetScaler selects a service for load balancing by using the least bandwidth method. Example: Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3. • Service-HTTP-1 has 3 Mbps bandwidth. • Service-HTTP-2 has 5 Mbps bandwidth. • Service-HTTP-3 has 2 Mbps bandwidth. Chapter 4 Load Balancing 157 The following figure illustrates how the NetScaler uses the least bandwidth method to forward requests to the three services. Least bandwidth mechanism The NetScaler selects the service by using the bandwidth value (N) which is the sum of the number of bytes transmitted and received per 14 second. If each request requires 1 Mbps bandwidth, the NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because the service has the least N value. • Now Service-HTTP-1 and Service-HTTP-3 have same N value and the NetScaler performs load balancing in a round robin manner. Service-HTTP-1 receives the second request, Service-HTTP-3 receives the third request, Service-HTTP-1 receives the fourth request, Service-HTTP-3 receives the fifth request, Service-HTTP-1 receives the sixth request. • Now Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same N value and the NetScaler performs load balancing in a round robin manner. So, Service-HTTP-2 receives the seventh request, and Service-HTTP-3 receives the eighth request. 158 Installation and Configuration Guide - Volume 1 The manner in which a service receives requests based on the N value is summarized in the following table. Selection of services by using the least bandwidth method when weights are assigned The NetScaler also performs load balancing by using the bandwidth and weights if different weights are assigned to the services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (N) * (10000 / weight) The following example shows how the NetScaler selects a service for load balancing by using the least bandwidth method when weights are assigned on the services. Example: In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a weight of 4. The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first second, third, fourth, and fifth requests because the service has the least N w value. Request received Service selected Current N (Number of active transaction) value Remarks Request-1 Service-HTTP-3 (N =2) N =3 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-1 (N =3) N =4 Service-HTTP-1 and Service-HTTP-3 have the same N values. Request-3 Service-HTTP-3 (N =3) N =4 Request-4 Service-HTTP-1 (N =4) N =5 Request-5 Service-HTTP-3 (N =4) N =5 Request-6 Service-HTTP-1 (N =5) N =6 Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have the same N values. Request-7 Service-HTTP-2 (N =5) N =6 Request-8 Service-HTTP-3 (N =5) N =6 Chapter 4 Load Balancing 159 • Service-HTTP-1 receives the sixth request because the service has the least N w value. • Service-HTTP-3 receives the seventh request because the service has the least N w value. • Service-HTTP-2 receives the eighth request because the service has the least N w value. The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-3 (N w =5000) N w =5000 Service-HTTP-3 has the least N w value. Request-2 Service-HTTP-3 (N w =5000) N w =7500 Request-3 Service-HTTP-3 (N w =7500) N w =10000 Request-4 Service-HTTP-3 (N w =10000) N w =12500 Request-5 Service-HTTP-3 (N w =12500) N w =15000 Request-6 Service-HTTP-1 (N w =15000) N w =20000 Service-HTTP-1 and Service-HTTP-3 have the same N w value. Request-7 Service-HTTP-3 (N w =15000) N w =17500 Request-8 Service-HTTP-2 (N w =16666.67) N w =20000 Service-HTTP-2 has the least N w value. 160 Installation and Configuration Guide - Volume 1 The following figure illustrates how the NetScaler uses the least bandwidth method when weights are assigned on the services. Least bandwidth mechanismwhen weights are assigned To configure the least bandwidth method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Least Bandwidth. Configuring the Least Packets Method When the NetScaler is configured to use the least packets method, it selects the service that is currently serving the least packets in last 14 seconds second. The following example shows how the NetScaler selects a service for load balancing by using the least packets method. Example: Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3. • Service-HTTP-1 is handling three packets in last 14 seconds. • Service-HTTP-2 is handling five packets in last 14 seconds. • Service-HTTP-3 is handling two packets in last 14 seconds. Chapter 4 Load Balancing 161 The following figure illustrates how the NetScaler uses the least packets method and forward requests to the three services. Least packets mechanism The NetScaler selects the service by using the number of packets (N) which is the sum of number of packets transmitted and received in last 14 seconds. The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first request because the service has the least N value. • Now Service-HTTP-1 and Service-HTTP-3 have same N value and the NetScaler performs load balancing in a round robin manner. Service-HTTP-1 receives the second request, Service-HTTP-3 receives the third request, Service-HTTP-1 receives the fourth request, Service-HTTP-3 receives the fifth request, Service-HTTP-1 receives the sixth request. • Now Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same N value and the NetScaler performs load balancing in a round robin manner. So, Service-HTTP-2 receives the seventh request, and Service-HTTP-3 receives the eighth request. 162 Installation and Configuration Guide - Volume 1 The manner in which a service receives requests based on the N value is summarized in the following table. Selection of services by using the least packets method when weights are assigned The NetScaler also performs load balancing by using the number of packets, and weights if different weights are assigned to the services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (N) * (10000 / weight) The following example shows how a NetScaler selects a service for load balancing by using the least packets method when weights are assigned on the services. Example: In the preceding example, suppose Service-HTTP-1 is assigned a weight of 2, Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a weight of 4. The NetScaler delivers the requests as follows: • Service-HTTP-3 receives the first second, third, fourth, and fifth requests because the service has the least N w value. Request received Service selected Current N (Number of active transaction) value Remarks Request-1 Service-HTTP-3 (N =2) N =3 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-1 (N =3) N =4 Service-HTTP-1 and Service-HTTP-3 have the same N values. Request-3 Service-HTTP-3 (N =3) N =4 Request-4 Service-HTTP-1 (N =4) N =5 Request-5 Service-HTTP-3 (N =4) N =5 Request-6 Service-HTTP-1 (N =5) N =6 Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have the same N values. Request-7 Service-HTTP-2 (N =5) N =6 Request-8 Service-HTTP-3 (N =5) N =6 Chapter 4 Load Balancing 163 • Service-HTTP-1 receives the sixth request because the service has the least N w value. • Service-HTTP-3 receives the seventh request because the service has the least N w value. • Service-HTTP-2 receives the eighth request because the service has the least N w value. The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-3 (N w =5000) N w =5000 Service-HTTP-3 has the least N w value. Request-2 Service-HTTP-3 (N w =5000) N w =7500 Request-3 Service-HTTP-3 (N w =7500) N w =10000 Request-4 Service-HTTP-3 (N w =10000) N w =12500 Request-5 Service-HTTP-3 (N w =12500) N w =15000 Request-6 Service-HTTP-1 (N w =15000) N w =20000 Service-HTTP-1 and Service-HTTP-3 have the same N w value. Request-7 Service-HTTP-3 (N w =15000) N w =17500 Request-8 Service-HTTP-2 (N w =16666.67) N w =20000 Service-HTTP-2 has the least N w value. 164 Installation and Configuration Guide - Volume 1 The following figure illustrates how the NetScaler uses the least packets method when weights are assigned on the services. Least packets mechanismwhen weights are assigned To configure the least packets method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Least Packets. Configuring the Token Method When the NetScaler is configured to use the token method, it selects a service based on the value of a token extracted from the client request. You can configure the location and size of the token. For subsequent requests with the same token, the NetScaler chooses the same server that handled the initial request. This method is content aware. This means that it operates differently for the TCP, HTTP, and HTTPS service types. For HTTP or HTTPS services, the token is found in the HTTP headers or the URL or the BODY using the configured expressions. Parameter Description Rule The string value. The string can be an existing rule name, or it can be an inline expression with a maximum of 256 characters. The default string value is none. The maximum length of the string value is 14999. Chapter 4 Load Balancing 165 Expressions can be Classic or Advanced. Advanced expressions do not need to have rules. For more information about expressions, see the chapter “Policies and Expressions” in the Citrix NetScaler Installation and Configuration Guide. For example, if you are load balancing a set of servers that contain Web content, and you want to configure the NetScaler to search for the token inside a URL query in each request. The NetScaler searches the token inside the URL query after matching the string token. For HTTP services, the NetScaler searches for the configured token in the first 24 KB of the TCP payload. For non-HTTP (TCP, SSL, and SSL_TCP) services, the NetScaler searches for the configured token in the first 16 packets if the total size of the 16 packets is less than 24 KB. But, if the total size of the 16 packets is greater than 24 KB, the NetScaler searches for the token in the first 24 KB of payload. To configure the location and size of the token, use the parameters as described in the following table. You can use this load balancing method across vservers of different types to ensure that requests presenting the same token are directed to the services on the same servers, regardless of the protocol used. For example, the server server-1 has two services Service-HTTP-1 and Service- TCP-1, and the server server-2 has two services Service-HTTP-2 and Service- TCP-2. The TCP services are bound to Vserver-LB-2, and the HTTP services are bound to Vserver-LB-1. Parameters Descriptions Data Length The length of the token in bytes. This parameter is applicable to TCP virtual servers when the Token method is selected. The minimum value is 0 and the maximum value is 100. Data Offset Offset of the data to be taken as a token. This parameter is applicable to the TCP type virtual servers when the Token load balancing method is used and must be within the first 24k of the client TCP data. The minimum value is 0, and the maximum value is 25400. 166 Installation and Configuration Guide - Volume 1 A request sent to Vserver-LB-1 with the token “AA” selects the service Service- HTTP-1 (bound to server-1) to process the request. A different request sent to Vserver-LB-2 with the same token “AA” directs this request to the service Service-TCP-1, as shown in the following figure. Working of token method To configure the token method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Token. You must configure a rule to configure a token. To configure a rule using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver, Vserver-LB-1 and click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 3. Click the Method and Persistence tab and under LB Method, select Token. The Rule text box appears. 4. Click Configure and the Create Expression dialog box appears. 5. Under Expression, click Add. The Add Expression dialog box appears. 6. In the Qualifier and Operator lists, select URLQUERY and CONTAINS and in the Value text box, type AA. 7. Click OK and click Close. The expression you created appears in the Expression list box. Chapter 4 Load Balancing 167 8. Click Create. The expression you created appears in the Rule text box. Click OK. Configuring the CustomLoad Method Generally, the NetScaler selects a service that is not handling any active transaction. If the services are handling active transactions, the NetScaler selects a service based on its load. A special type of monitor, known as a load monitor, calculates the load on each service in the network. The load monitors do not mark the state of a service; however, they take the service out of the load balancing decision. Custom load balancing is performed on server parameters such as CPU usage, memory, and response time. For more information about load monitors, see “Configuring Load Monitors” on page 252. The following diagram illustrates how a load monitor operates. Working of load monitors The load monitor uses an SNMP probe to calculate the load on the service. To accomplish this, the monitor sends an SNMP GET request to the server. This request contains one or more object IDs (OID). The server then sends back an SNMP GET response with metrics corresponding to the SNMP OIDs. The monitor calculates the load on each service based on the metrics in the response message and parameters such as pre-configured threshold and weight as described later in the chapter. The load monitor calculates the load on a service using the following parameters: • Metrics values retrieved through SNMP probes that exist as tables in the NetScaler • Threshold value set for each metric • Weight assigned to each metric 168 Installation and Configuration Guide - Volume 1 The following example shows how the NetScaler selects a service for load balancing by using the custom load method. Example: Consider three services, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3. • Service-HTTP-1 is using 20 MB of memory. • Service-HTTP-2 is using 70 MB of memory. • Service-HTTP-3 is using 80 MB of memory. The servers can export metrics such as CPU and memory usage. The load monitor sends an SNMP GET request containing the OIDs 1.3.6.1.4.1.5951.4.1.1.41.1.5, 1.3.6.1.4.1.5951.4.1.1.41.1.4, and 1.3.6.1.4.1.5951.4.1.1.41.1.3 to the servers. The three services respond to the request. The NetScaler compares the exported metrics to select Service-HTTP-1 because it has more memory for processing requests. The following figure illustrates how the NetScaler uses the custom load method and forward requests to the three services. Customload mechanism The NetScaler selects the service by using the load (N). If each request uses 10 MB memory, the NetScaler delivers the requests as follows: • Service-HTTP-1 receives the first, second, third, fourth, and fifth requests because the service has the least N value. • Now, Service-HTTP-1 and Service-HTTP-2 have same load and the NetScaler selects the service in round robin manner. Therefore, Chapter 4 Load Balancing 169 Service-HTTP-2 receives the sixth request and Service-HTTP-1 receives the seventh request. • Now, Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have same load and the NetScaler selects the service in round robin manner. Therefore, Service-HTTP-1 receives the eighth request. The manner in which a service receives requests based on the N value is summarized in the following table. Selection of services by using the custom load method when weights are assigned The NetScaler also performs load balancing by using the load on services, and weights if different weights are assigned to the services. The NetScaler selects the service by using the value (N w ) of the following expression: N w = (N) * (10000 / weight) The following example shows how the NetScaler selects a service for load balancing by using the custom load method when weights are assigned on the services. Request received Service selected Current N (Number of active transaction) value Remarks Request-1 Service-HTTP-1 (N =20) N =30 Service-HTTP-3 has the least N value. Request-2 Service-HTTP-1 (N =30) N =40 Request-3 Service-HTTP-1 (N =40) N =50 Request-4 Service-HTTP-1 (N =50) N =60 Request-5 Service-HTTP-1 (N =60) N =70 Request-6 Service-HTTP-1 (N =70) N =80 Service-HTTP-2 and Service-HTTP-3 have the same N values. Request-7 Service-HTTP-2 (N =70) N =80 Request-8 Service-HTTP-1 (N =80) N =90 Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 have the same N values. 170 Installation and Configuration Guide - Volume 1 Example: In the preceding example, suppose Service-HTTP-1 is assigned a weight of 4, Service-HTTP-2 is assigned a weight of 3, and Service-HTTP-3 is assigned a weight of 2. If each request uses 10 MB memory, the NetScaler delivers the requests as follows: • Service-HTTP-1 receives the first, second, third, fourth, fifth, sixth, seventh, and eighth requests because the service has the least N w value. • Service-HTTP-2 receives the ninth request because the service has the least N w value. Service-HTTP-3 has the highest N w value and is not considered for load balancing. The manner in which a service receives requests based on the N w value is summarized in the following table. Request received Service selected Current N w (Number of active transactions) * (10000 / weight) value Remarks Request-1 Service-HTTP-1 (N w =50000) N w =75000 Service-HTTP-1 has the least N w value. Request-2 Service-HTTP-1 (N w =5000) N w =100000 Request-3 Service-HTTP-1 (N w =15000) N w =125000 Request-4 Service-HTTP-1 (N w =20000) N w =150000 Request-5 Service-HTTP-1 (N w =23333.34) N w =175000 Request-6 Service-HTTP-1 (N w =25000) N w =200000 Request-7 Service-HTTP-1 (N w =23333.34) N w =225000 Request-8 Service-HTTP-1 (N w =25000) N w =250000 Request-9 Service-HTTP-2 (N w =233333.34) N w =266666.67 Service-HTTP-2 has the least N w value. Service-HTTP-1 is selected for load balancing when it completes the active transactions or when the N w value of other services (Service-HTTP-2 and Service-HTTP-3) is equal to 400000. Chapter 4 Load Balancing 171 The following figure illustrates how the NetScaler uses the custom load method when weights are assigned on the services. CustomLoad mechanismwhen weights are assigned To configure the custom load method, perform the steps described in the section “Changing the Load Balancing Algorithm” on page 132. Under LB Method, select Custom Load. Configuring Persistent Connections Between Clients and Servers The NetScaler initially selects a server by using the LB methods. With persistence configured, enabling the NetScaler to send any subsequent client requests to the selected server, the server can access state information for that client. If persistence is configured, it overrides the load balancing methods once the server has been selected. If the configured persistence applies to a service that is down, the NetScaler uses the load balancing methods to select a new service, and the new service becomes persistent for subsequent requests from the client. If the state selected service is out of service, it continues to serve the outstanding requests, but doesn’t allow new requests or connections directed to it. After the shutdown period elapses, no new requests or connections are directed to the service and the existing connections are closed. 172 Installation and Configuration Guide - Volume 1 You can configure different types of persistence on the NetScaler. The following table lists the persistence types and indicates if the persistence type consumes resources. Configuring Persistence Types If the configured persistence cannot be maintained because of lack of resources on the NetScaler, the load balancing methods are used for server selection. Persistence is maintained for a configured period of time, depending on the persistence type. Some persistence types are specific to certain vservers. The following table shows the relationship. To configure persistence, you must use the parameters as described in the following table. Persistence Type Persistent Connections Source IP, SSL Session ID, Rule, DESTIP, SRCIPDESTIP 250 K CookieInsert, Custom Server ID, URL passive Memory limit. In case of CookieInsert, if time out is not 0, any number of connections are allowed until limited by memory. Persistence Type HTTP HTTPS TCP User Datagram Protocol (UDP)/IP SSL_Bridge Source IP YES YES YES YES YES CookieInsert YES YES NO NO NO SSL Session ID NO YES NO NO YES URL passive YES YES NO NO NO Custom Server ID YES YES NO NO NO Rule YES YES NO NO NO SRCIPDESTIP NA NA YES YES NA DESTIP NA NA YES YES NA Parameter Description Persistence Type Persistence type for the vserver. The valid options for this parameter are: SOURCEIP, COOKIEINSERT, SSLSESSION, RULE, URLPASSIVE, CUSTOMSERVERID, DESTIP, SRCIPDESTIP, CALLID, NONE (default) Chapter 4 Load Balancing 173 The following example describes the steps to set SOURCEIP persistence on the vserver Vserver-LB-1, with a persistence mask of 255.255.255.255 and a timeout of 2 minutes. To configure persistence on vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure persistence, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Method and Persistence tab. 5. In the Persistence list, select SOURCEIP. 6. In the PersistMask and Timeout text boxes type the subnet mask and timeout values, for example, 255.255.255.255 and 2. 7. Click OK. To configure persistence on vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -persistenceType SOURCEIP Configuring Persistence Based on Source IP Addresses the NetScaler selects a service based on the load balancing method, and uses the source IP address of the selected service to send the subsequent requests. The NetScaler creates a session between the client and the servers using the IP address. Using persistence based on source IP address overloads the servers because the connections are routed through the single gateway. In the multiple proxy environments, the client requests arrive at a Web site with different IP addresses. This restriction is known as Mega Proxy problem. You can use CookieInsert persistence to solve this problem. Persistence Mask Persistence Mask is used to specify if the persistence is IP- based. The default value is 255.255.255.255. If you set 0 using this parameter the complete IP address is used for persistence. Timeout The time period for which persistence is in effect for a specific client. The default value is 2 minutes, and the maximum value that can be configured is 1440 minutes. Parameter Description 174 Installation and Configuration Guide - Volume 1 You can set a timeout value for this type of persistence that specifies the inactivity period for the session. When the timeout value expires, the session is discarded, and a new server is selected based on the configured load balancing method. To configure persistence based on Source IP Addresses, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select SOURCEIP. Configuring Persistence Based on HTTP Cookies The NetScaler adds an HTTP cookie into the Set-Cookie header field of the HTTP response. The cookie contains information about the service where the HTTP requests must be sent. The client stores the cookie and includes it in all subsequent requests. The NetScaler uses this cookie to select the service for subsequent requests. You can use this persistence on vservers of type HTTP or HTTPS. The NetScaler inserts the cookie NSC_XXXX=<ServiceIP ><ServicePort> where • NSC_XXXX is the vserver ID that is derived from the vserver name • ServiceIP is a representation of the IP address of the service • ServicePort is a representation of the port of the service ServiceIP and ServicePort are encrypted and inserted. When the NetScaler receives a cookie, it decrypts the cookie. Note: If the client is not allowed to store the HTTP cookie, the subsequent requests do not have the HTTP cookie, and persistence is not honored. By default, the NetScaler sends an HTTP cookie with version 0, in compliance with the Netscape specification. The NetScaler can also send HTTP cookies with version 1, in compliance with RFC 2109. You can configure a timeout value for persistence that is based on HTTP cookies. Note the following: • If HTTP cookie version 0 is used, the NetScaler inserts the absolute Coordinated Universal Time (GMT) of the cookie expiration time (the “expires” attribute of the HTTP cookie) that is calculated as the sum of the current GMT time on the NetScaler, and the timeout value. • If an HTTP cookie version 1 is used, the NetScaler inserts a relative expiration time (“Max-Age” attribute of the HTTP cookie). In this case, the client software calculates the actual expiration time. Chapter 4 Load Balancing 175 Note: Most client software currently installed (Microsoft Internet Explorer and Netscape browsers) understand HTTP cookie version 0; however, some HTTP proxies understand HTTP cookie version 1. When you set the timeout value to 0, the NetScaler does not specify the expiration time, regardless of the HTTP cookie version used. The expiration time depends on the client software, and such cookies are not valid when the software is shut down. This persistence type does not consume any NetScaler resources. Hence, it can accommodate an unlimited number of persistent clients. To configure persistence based on HTTP Cookie, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select COOKIEINSERT. Configuring Persistence Based on SSL Session IDs the NetScaler creates a session-based persistence on the arriving SSL Session ID that is part of the SSL handshake process. The requests with the same SSL session ID are directed to the initially selected service. This persistence is used for SSL bridge type of services and the NetScaler does not encrypt or decrypt data when it forwards the requests to the services. The NetScaler must maintain the data structures to keep track of the sessions. Thus, the persistence type consumes NetScaler resources. Also, if the SSL sessions re-negotiate the session IDs during the transactions, the persistence based on SSL session-id does not function correctly. The timeout value for this type of persistence is as described in the section “Configuring Persistence Based on Source IP Addresses” on page 173. To configure persistence based on SSL session IDs, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select SSLSESSION. Configuring Persistence Based on User-Defined Rules the NetScaler maintains persistence based on the contents of the matched rule. This persistence type requires configuration of a payload expression or a policy infrastructure expression. The expression is evaluated and if the request matches the criteria, a persistence session is created. The subsequent client requests are directed to the previously selected server. To configure rule-based persistence, use the Rule parameter as described in the following table. Parameter Description Rule The string value used to set the RULE persistence type. The string can be an existing rule name, or it can be an inline expression with a maximum of 256 characters. The default value is none. The maximum length is 14999. 176 Installation and Configuration Guide - Volume 1 Example: Payload Expression The expression, “httpheader User-Agent contains MyBrowser” directs any client requests containing, “User-Agent: MyBrowserV1.1” to the initially selected server. Example: Advanced Expression The expression, “HTTP.REQ.HEADER (“User-Agent”).CONTAINS (“MyBrowser”) directs client requests containing, “User-Agent: MyBrowserV1.1” to the initially selected server. The timeout value for this type of persistence is as described in the section “Configuring Persistence Based on Source IP Addresses” on page 173. To configure persistence based on user-defined rules, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select RULE. Configuring Persistence based on Server-IDs in URLs the NetScaler can maintain persistence based on the server ID in the URLs. In a technique called URL passive persistence type, the NetScaler extracts the server ID from the server response and embeds it in the URL query of the client request. The server ID is its IP address and port specified as a hexadecimal number. The NetScaler extracts the server ID from subsequent client requests, and uses it to select the server. URL passive persistence requires configuring either a payload expression or a policy infrastructure expression specifying the location of the server ID in the client requests. For more information about expressions, see the “Policies and Expressions” chapter in the Citrix NetScaler Installation and Configuration Guide, Volume 1. Note: If the server ID cannot be extracted from the client requests, server selection is based on the load balancing method. Example: Payload Expression The expression, URLQUERY cont ai ns si d=configures the NetScaler to extract the server ID from the URL query of a client request, after matching token si d=. Thus, a request with the URL http://www.citrix.com/ index.asp?&sid=c0a864100050 is directed to the server with the IP address 10.102.29.10 and port 80. The timeout value does not affect this persistence type. This persistence type is maintained as long as the server ID can be extracted from the client requests. This persistence type does not consume any NetScaler resources, so it can accommodate an unlimited number of persistent clients. Chapter 4 Load Balancing 177 To configure persistence based on server IDs in a URL, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select URLPASSIVE. Configuring Persistence based on Server-IDs in Client Requests the NetScaler maintains persistence based on the Server ID that you provide. The persistence type requires you to provide the server ID and embeds the server ID in the response. The NetScaler extracts the server ID from subsequent requests and uses it to choose a server. The Server ID value must be in the range 0 through 65535. You must configure the same number in the NetScaler for the corresponding service. This persistence type is called Custom Server ID persistence. The Custom Server ID persistence type requires a payload expression, or an advanced expression to be configured that specifies the location of the Server ID in the client requests. For more information about expressions, see the “Policies and Expressions” chapter. Note the following: • If a Server ID cannot be extracted from the client requests, server selection is performed based on the load balancing method. • Avoid using the same Server ID for multiple services. Example: Payload Expression Two servers, server-1 and server-2 are configured, where server-1 has the Server- ID=5 and server-2 has the Server-ID=6. The services in these servers are bound to the vserver Vserver-LB-1. The expression “URLQUERY contains sid=” configures the NetScaler to extract the Server-ID from the URL query of the client requests, after matching token “sid=”. Thus a request with the URL http://www.citrix.com/ index.asp?&sid=6 that arrives on Vserver-LB-1 is directed to the server server-2. The timeout value does not affect this persistence type. Persistence is maintained for as long as a Server ID can be extracted from the client requests. This persistence type does not consume any NetScaler resources, so it can accommodate an unlimited number of persistent clients. To configure persistence based on server IDs in client requests, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select CUSTOMSERVERID. Configuring Persistence Based on Destination IP Addresses This persistence type is used with link load balancing. With DESTIP configured, the NetScaler chooses a service based on the configured load balancing method. It then directs all subsequent packets to the selected service. 178 Installation and Configuration Guide - Volume 1 The timeout value for this type of persistence is as described in the section “Configuring Persistence Based on Source IP Addresses” on page 173. To configure persistence based on destination IP addresses, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select DESTIP. Configuring Persistence Based on Source and Destination IP Addresses With SRCIPDESTIP configured, the NetScaler chooses a service based on the configured load balancing method and directs subsequent packets with the same source and destination IP addresses to the same service. The timeout value for this type of persistence is as described in the section “Configuring Persistence Based on Source IP Addresses” on page 173. To configure persistence based on source and destination IP addresses, perform the steps described in the section “Configuring Persistence Types” on page 172. In the Persistence list, select SRCIPDESTIP. Configuring Backup Persistence The NetScaler uses the backup persistence option when the primary persistence fails. For example, the primary persistence type is set to Cookie Insert, and backup persistence is set to Source IP. When the client browsers do not support cookies, Source IP persistence is used. To set the Backup persistence option to Source IP, you must set the primary persistence to Cookie Insert. Note: If the traffic comes from behind a NAT device or proxy, the traffic appears to come from a single source IP address and cannot distributed evenly. Backup persistence has a timeout value that you can set only when the primary persistence type is set to COOKIEINSERT, and the backup persistence type is set to SOURCEIP. To configure backup persistence, use the backup persistence parameter as described in the following table. Parameter Description Backup Persistence The backup persistence type for the group. The valid options for this parameter are SOURCEIP and NONE. Chapter 4 Load Balancing 179 The following example describes the steps to set the primary persistence for vserver Vserver-LB-1 to CookieInsert and the backup persistence to SOURCEIP. The timeout and the backup persistence timeout are set to 20 minutes. The subnet mask is set to 255.255.255.255. To set backup persistence for a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure backup persistence, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Method and Persistence tab. 5. In the Persistence list, select COOKIEINSERT and in the Timeout text box type the timeout value, for example, 20. 6. In the Backup Persistence list, select the backup persistence that you want to configure, for example, SOURCEIP. 7. In the Backup Timeout and Netmask text boxes type the backup timeout value and netmask, for example, 20 and 255.255.255.255 Click OK. To set backup persistence for a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -persistenceType CookieInsert -persistenceBackup SourceIP Configuring Persistence Groups You can aggregate vservers into groups and specify a persistence method. You bind vservers using different protocols in one group and configure persistence across the different protocols. When persistence is set on the group of vservers, client requests are directed to the same selected server, regardless of the vserver in the group that receives the client request. When persistence is set on the group of vserver, it overrides the persistence set on individual vservers. Note: When all vservers are removed from the group, the group is also removed. 180 Installation and Configuration Guide - Volume 1 The persistence types allowed on the groups of vservers are: • Source IP • Cookie Insert If you set Cookie Insert persistence, the domain attribute of the HTTP cookie is configured. This setting causes the client software to add the HTTP cookie into client requests if different vservers have different public host names. For more information about Cookie Insert persistence type, see the section “Configuring Persistence Based on HTTP Cookies” on page 174. After you set persistence for the entire group, you cannot change it for individual vservers in the group. If you set persistence on the group of vservers, and a new vserver is added to the group, the persistence of the new vserver is changed to persistence of the group. Note: If you set group persistence to NONE, the persistence on the individual virtual servers is applied. To create groups of virtual servers, use the parameters as described in the following table. The following example describes the steps to create the vserver group Vserver- Group-1 and bind the vserver Vserver-LB-1 to Vserver-Group-1. The persistence type is Source IP, and the persistence mask is 255.255.255.255. The timeout is 2 minutes. To create a vserver group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Persistency Groups. The Persistency Groups page appears in the details pane. 2. Click Add. The Create Virtual Server Group dialog box appears. Parameters Descriptions Name The unique name of the group. This name must not exceed 31 characters. Persistence Type The Persistence type for the group. The valid options for this parameter are: SOURCEIP, COOKIEINSERT, and NONE. Persistence Mask The netmask to be applied when the persistency type is SOURCEIP. Timeout The time period for which the persistence is in effect for a specific client. The value ranges from 2 to 1440 minutes. The default value is 2minutes. The maximum value is 1440 minutes (1 day). Chapter 4 Load Balancing 181 3. In the Group Name text box type the name, for example, Vserver-Group-1. 4. In the Persistence list, select a persistence type, for example, SOURCEIP. 5. In the Persistence Mask and Timeout text boxes type the persistence mask and timeout values, for example, 255.255.255.255 and 2. 6. Under Virtual Server List, in the Available Virtual Server list box, select the vserver that you want to bind to the group, for example, Vserver-LB-1. 7. Click Add. Vserver-LB-1 appears in the Configured Virtual Server list box. 8. Click Create and click Close. The vserver group you created appears in the Persistence Groups page, as shown in the following figure. Persistence groups page To create a vserver group using the NetScaler command line At the NetScaler command prompt, type: bind lb group Vserver-Group-1 Vserver-LB-1 -persistenceType CookieInsert You can change the backup persistence, backup persistence timeout, and cookie domain value. To modify the persistence groups use the parameters as described in the following table. Parameters Descriptions Persistence Backup The backup persistence type for the group. The valid options for this parameter are: SOURCEIP and NONE Backup Persistence Timeout The maximum time for which the backup persistence is in effect for a specific client. The default value is 2minutes. The maximum value is 1440 minutes. 182 Installation and Configuration Guide - Volume 1 The following example describes the steps to set the vserver group Vserver- Group-1 with persistence type COOKIEINSET, backup persistence type SOURCEIP, and backup persistence mask 255.255.255.255. To modify a vserver group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Persistence Groups. The Persistence Groups page appears in the details pane. 2. Select the vserver group that you want to modify for example, Vserver-Group-1. 3. Click Open. The Configure Virtual Server Group dialog box appears. 4. In the Backup Persistence list, select the type of backup persistence, for example, SOURCEIP. 5. In the Persistence Mask text box, type the subnet mask, for example, 255.255.255.255. 6. Click OK. To modify a vserver group using the NetScaler command line At the NetScaler command prompt, type: set lb group vserver-Group-1 -PersistenceBackUP SourceIP -persistMask 255.255.255.255 Configuring the Redirection Mode The redirection mode determines the destination address to forward the incoming traffic. The NetScaler provides the following redirection modes: • IP based (default) • MAC based By default, the NetScaler uses IP based mode. You can set MAC based forwarding in case of direct server return topology, link load balancing, and firewall load balancing. Cookie Domain The domain attribute of the HTTP cookie. Parameters Descriptions Chapter 4 Load Balancing 183 For more information on MAC based forwarding, see the Basic Network Configuration chapter of Installation and Configuration guide. To configure the redirection mode for the load balancing setup, you must use the parameter listed in the following table. The following example describes the steps to configure the MAC Based redirection mode for the vserver Vserver-LB-1. To set a vserver for redirection using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure the redirection mode, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Under Redirection Mode, select the MAC Based radio button. 6. Click OK. To set a vserver for redirection using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -m MAC Parameter Description Redirection Mode The LB mode. If the value is specified as IP-based, then destination IP address is changed to the IP address of the server and the traffic is sent to the servers. If the value is MAC-based, the destination MAC address is changed to the MAC address of the server and the traffic is sent to the server. The destination IP address is not changed. 184 Installation and Configuration Guide - Volume 1 Assigning Weights to Services You can assign weights to services to prioritize the services. If you use a load balancing method (for example, round robin) that supports weighting of servers, you must assign a weight to the service. Assigning weights to services allows the NetScaler to balance the load on the service using the weights. The services with less weight serve least requests. The following table describes the load balancing methods and the manner in which the NetScaler selects the services when you configure weights. To configure weight, use the Weights parameter as described in the following table. The following example describes the steps to assign relative weight of 10 to the service Service-HTTP-1. To set a vserver to assign weights to services using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. The services appear in the Services tab. Load Balancing Methods Selection of services when weights are configured Round Robin The NetScaler selects services sequentially with the highest weight. Least Connections The NetScaler selects services with the least number of active transactions and the highest weight. Least Response Time and Least Response Time Method using Monitors The NetScaler selects services with the least number of active transactions, the fastest average response time, and the highest weight. Least Bandwidth The NetScaler selects services with the least traffic and the highest weight. Least Packets The NetScaler selects services with the least number of packets and the highest weight. Least Load The NetScaler selects services with the least load and the highest weight. Hashing and Token The NetScaler does not use weights to select services. Parameter Description Weights The weight for the specified service. The minimum value is 1 and the maximum value is 100. Chapter 4 Load Balancing 185 4. In the Weights spin box, type or select the weight of a service, for example, 10 next to Service-HTTP-1. 5. Click OK. To set a vserver to assign weights to services using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -weight 10 Service-HTTP-1 Protecting the Load Balancing Configuration against Failure This section describes procedures to protect the LB setup against failure. The LB setup can fail when a vserver fails, or when the vserver is unable to handle excessive traffic. Protecting the LB setup against failure helps ensure the availability of the setup. Topics include: • Redirecting Client Requests to an Alternate URL • Configuring a Backup LB Vserver • Diverting Excess Traffic to a Backup LB Vserver • Configuring Stateful Connection Failover Redirecting Client Requests to an Alternate URL You can configure a redirect URL to communicate the status of the NetScaler in the event that a vserver (only of type HTTP or HTTPS) is down or disabled. This URL can be a local or remote link. The NetScaler uses HTTP 302 redirect. Redirects can be absolute URLs or relative URLs. If the configured redirect URL contains an absolute URL, the HTTP redirect is sent to the configured location, regardless of the URL specified in the incoming HTTP request. If the configured redirect URL contains only the domain name (relative URL), the HTTP redirect is sent to a location after appending the incoming URL to the domain configured in the redirect URL. Note: If a load balancing vserver is configured with both a backup vserver and a redirect URL, the backup vserver takes precedence over the redirect URL. A redirect is used when the primary and backup vservers are down. 186 Installation and Configuration Guide - Volume 1 To configure a vserver to redirect client requests to a URL, use the Redirect URL parameter as described in the following table. The following example describes the steps to set the vserver Vserver-LB-1 to redirect client requests to the URL http://www.newdomain.com/mysite/maintenance. To configure a vserver to redirect the client request to a URL using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure redirect URL, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Redirect URL text box, type the URL, for example, http://www.newdomain.com/mysite/maintenance. 6. Click OK. To configure a vserver to redirect the client request to a URL using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -redirectURL http://www.newdomain.com/mysite/maintenance Configuring a Backup LB Vserver If the primary vserver is marked down or disabled, the NetScalers directs the connections or client requests to a backup vserver that forwards the client traffic to the services. It can also send a notification message to the client regarding the site outage or maintenance. The backup vserver is a proxy and is transparent to the client. Parameter Description Redirect URL The URL where traffic is redirected if the vserver in the NetScaler becomes unavailable. This value must not exceed 127 characters. The domain specified in the URL must not match the domain specified in the domain name argument of a content switching policy. If the same domain is specified in both arguments, the request is redirected continuously to the same unavailable vserver in the NetScaler, and the user cannot get the requested content. Chapter 4 Load Balancing 187 Note: If a load balancing vserver is configured with both a backup vserver and a redirect URL, the backup vserver takes precedence over the redirect URL. A redirect is used when the primary and backup vservers are down. You can configure a backup vserver when you create a vserver, or when you change the optional parameters of an existing vserver. You can also configure a backup vserver for an existing backup vserver, thus creating cascaded backup vservers. The maximum depth of cascading backup vservers is 10. The NetScaler searches for a backup vserver that is up and accesses that vserver to deliver the content. Note: If the backup vserver does not exist, an error message appears. You can use redirect URL on the primary when the primary and the backup vservers are down or have reached their threshold for handling requests. When a service bound to the vserver is in an out of service state, use the redirect URL on the vserver. To configure a backup vserver, use the Name parameter as described in the following table. The following example describes the steps to set the existing Vserver-LB-2 as a backup to Vserver-LB-1. The vserver Vserver-LB-2 is created, with IP address 10.102.29.5 and protocol HTTP. To set a backup vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure the backup vserver, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. Parameter Description Name The name of the backup vserver. You can create a vserver and specify the name, IP address, port, and type as described in “Creating a Vserver” on page 120. You can use the name of the vserver as a backup vserver. 188 Installation and Configuration Guide - Volume 1 5. In the Backup Virtual Server list, select the backup vserver, for example, Vserver-LB-2. 6. Click OK. To set a backup vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -backupVserver Vserver-LB-2 Diverting Excess Traffic to a Backup LB Vserver The spillover option diverts new connections arriving at a vserver to a backup vserver when the number of connections to the vserver exceeds the configured threshold value. The threshold value is dynamically calculated, or you can set the value. The number of established connections (in case of TCP) at the vserver is compared with the threshold value. When the number of connections reaches the threshold, new connections are diverted to the backup vserver. You can also use tunnels to divert connections to the backup vserver. For more information, see “NetScaler as a Decapsulator” on page 634. You can configure persistence with spillover. In this configuration, connections are diverted to the backup vserver based on the persistence settings configured on the backup vserver. These connections are not moved back to the vserver. The vserver accepts new client connections. If the backup vservers reach the configured threshold and are unable to take the load, the primary vserver diverts all requests to the redirect URL. If a redirect URL is not configured on the primary vserver, subsequent requests are dropped. To configure spillover, use the parameters described in the following table. Parameter Description Method Type of spillover used to divert traffic to the backup vserver when the vserver reaches the spillover threshold. The valid options for this parameter are: CONNECTION, DYNAMICCONNECTION, BANDWIDTH, and NONE. Threshold For the CONNECTION (or) DYNAMICCONNECTION spillover type, the Threshold value is the maximum number of connections a vserver can handle prior to spillover. For the BANDWIDTH spillover type, the Threshold value is the amount of incoming and outgoing traffic (in kilobits per second) that a vserver can handle before spillover occurs. The minimum value is 1, and the maximum value is 4294967294. Persistence The spillover persistence state. If you enable spillover persistence, the NetScaler maintains sourceIP-based persistence over primary vserver and backup vservers. The valid options for this parameter are: enabled and disabled. The default value is disabled. Chapter 4 Load Balancing 189 The following example describes the steps to configure the vserver Vserver-LB-1 to divert new connections to the backup vserver Vserver-LB-2 when the number of connections exceeds the threshold value 1000. To set a vserver to divert new connections to a backup vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure the spillover, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Method list, select the type of spillover, and in Threshold text box type the threshold value, for example, Connection and 1000. 6. Under Spillover, select the Persistence check box, and in Persistence Timeout (min) text box type the timeout, for example, 2. 7. Click OK. To set a vserver to divert new connections to a backup vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -soMethod Connection -soThreshold 1000 -soPersistence enabled -soPersistenceTimeout 2 Configuring Connection-Based Spillover Connection-based spillover allows you to configure a maximum threshold for the number of active client connections on a vserver. When the client connections exceed the configured threshold limit, new client connections are diverted to the backup vserver. Persistence Timeout (minutes) This value sets the timeout for spillover persistence. The default value is 2 minutes. The minimum value is 2 minutes, and the maximum value is 1440 minutes. Parameter Description 190 Installation and Configuration Guide - Volume 1 To configure connection-based spillover, follow the steps described in the section “Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the Method list, select Connection. Note: GSLB vservers do not support connection-based spillover. Configuring Dynamic Spillover Dynamic spillover depends on the maximum client setting configured on the services. If the number of client connections at the vserver exceeds the sum of the maximum client values, the new connections are diverted to the services of the backup vserver. To configure dynamic spillover, you must enable it on a vserver. You must configure the services with appropriate maximum client values. If the value for maximum client is set to 0, the spillover limit is treated as infinity, and spillover never occurs. To configure dynamic spillover, follow the steps described in the section “Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the Method list, select Dynamic connection. For example, you create a vserver, a backup vserver, and two services, and bind the services to the vserver. Then you can configure dynamic spillover on the primary vserver. Note: Content-based vservers do not support dynamic spillover. Configuring Bandwidth-based Spillover Bandwidth-based spillover allows you to configure a bandwidth threshold value. When the bandwidth of the vserver exceeds the bandwidth threshold value, the NetScaler diverts new connections to a backup vserver. For example, if you create a vserver, a backup vserver, and two services, and bind the services to the vserver, you can configure bandwidth spillover on the primary vserver. You can also configure the backup vserver with a threshold value. When the threshold for the backup vserver is reached, the NetScaler diverts new client connections to the next backup vserver. To configure bandwidth-based spillover, follow the steps described in the section “Diverting Excess Traffic to a Backup LB Vserver” on page 188. In the Method list, select Bandwidth. Chapter 4 Load Balancing 191 Configuring Stateful Connection Failover The NetScaler enables TCP or UDP connections to survive a failover event in High Availability (HA) mode. This functionality is called connection failover. This section provides an overview of connection failover, and instructions for configuring it. The following topics are discussed: • Understanding connection failover • Configuring high availability • Configuring connection failover • Disabling connection failover Understanding Connection Failover The Citrix NetScaler provides two modes of connection failover. They are: • Stateless connection failover • Stateful connection failover Stateless connection failover Stateless connection failover supports only the service type ANY. Stateless connection failover functions if USIP is enabled, and if Source IP persistence or Source IP Source Port Hash LB method is configured. In this mode, the nodes in the HA configuration do not exchange any information about connections. Stateful connection failover When stateful connection failover is configured, TCP connections established through the primary NetScaler remain active after a failover. The new primary NetScaler obtains information about connections established before the failover and continues to provide service to those connections. The new primary NetScaler synchronizes its data with the new secondary NetScaler using an internal framework called the session stateful failover. Stateful connection failover supports a number of service types, such as TCP, UDP, ANY, FTP, and SSL_BRIDGE. All load balancing (LB) methods and LB persistence types applicable to these service types are also supported. However, the following are not supported: • LB methods such as URLHASH, DOMAINHASH, CALLIDHASH, and LRTM • LB persistence types such as COOKIEINSERT, RULE, URLPASSIVE, CUSTOMSERVERID, and CALLID 192 Installation and Configuration Guide - Volume 1 Both stateless and stateful connection failover are configured on LB vservers, but cannot be configured on content-switching vservers. Mapped (SNIP), Use Source IP, and domain-based service configurations are supported under both modes of connection failover. A basic HA configuration with connection failover contains the entities described in the following figure. Connection failover entity diagram To create an HA configuration, you must add a secondary NetScaler to the primary NetScaler. In the event of a failover, the secondary NetScaler takes over as the primary NetScaler and begins accepting client connections. You can add an LB vserver and TCP services on the primary NetScaler, as shown in the entity diagram, and the same configuration is propagated to the secondary NetScaler. You can then configure connection failover on the required LB vservers. The following table describes how connection failover affects three features of the NetScaler. Functionality Impact of Connection Failover SYN Protection If failover occurs after the NetScaler issues SYN-ACK, but before it receives the final ACK, the connection is not supported by connection failover. The client must reissue the request to establish the connection. Surge Protection If failover occurs before a connection with the server is established, the new primary NetScaler establishes a connection with the server. It also retransmits all packets held in the course of surge protection. Access server in DOWN state Access DOWN functionality takes precedence over stateless connection failover, if it is enabled. Chapter 4 Load Balancing 193 The following configurations are not supported under connection failover: • Reverse NAT. • Transparent services. • Compression. • SSLVPN. • SSL offload. • Application firewall. • Independent Network Configuration (INC) HA mode. • TCP buffering. • The connection failover feature does not synchronize IP fragments, if the failover occurs when IP fragments are being reassembled. Configuring High Availability To configure connection failover, you must first configure HA and set up a primary and secondary NetScaler. To configure HA, see the section “Configuring High Availability” in the “High Availability” chapter. Configuring Connection Failover After adding a secondary node and configuring HA, you can choose to configure either stateless or stateful connection failover. You can configure connection failover on any of the LB vservers. To configure connection failover, use the parameters described in the following table. The following procedure describes the steps to configure a connection failover on an LB vserver. The connection failover state is set to Stateful. Parameter Description Stateless Sets the state of connection failover on the virtual server to Stateless. Stateless supports only the service type ANY. Stateful Sets the state of connection failover on the virtual server to Stateful. Stateful supports the service types TCP, UDP, ANY, FTP, and SSL_BRIDGE. Stateful connection failover synchronizes connections between nodes in an HA configuration. Disable Disables connection failover. 194 Installation and Configuration Guide - Volume 1 To configure a connection failover using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure connection failover, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Connection Failover drop-down list, select Stateful. 6. Click OK. To configure a connection failover using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -connFailover stateful Disabling Connection Failover The following procedure describes the steps to disable connection failover. When connection failover is disabled on a vserver, the resources allocated to the vserver are freed. To disable a connection failover using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure a connection failover, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Connection Failover drop-down list box, select Disable. 6. Click OK. To disable a connection failover using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -connFailover disable Chapter 4 Load Balancing 195 Managing Client Traffic This section describes how to manage client traffic. Maintaining client connections helps to ensure the availability of the services. This section includes procedures for configuring the NetScaler to use cache and other tasks to improve response and direct client requests based on priority. Topics include: • Configuring Sessionless LB Vservers • Redirecting HTTP Requests to a Cache • Directing Requests Based on Priority • Directing Requests to a Custom Web Page • Enabling Delayed Cleanup of Vserver Connections • Rewriting Ports and Protocols for HTTP Redirection • Inserting the IP Address and Port of a Vserver in the Request Header The following section uses the example of an LB setup with: • A vserver named Vserver-LB-1, of type ANY, and IP address 10.102.29.7 • A service named Service-ANY-1, of type ANY, and IP address 10.102.29.1, bound to the vserver Vserver-LB-1 Configuring Sessionless LB Vservers When the NetScaler performs load balancing, it creates and maintains a number of sessions between the client and servers. In scenarios such as DSR setup or IDS load balancing, the NetScaler can perform load balancing without creating sessions. To prevent creation of sessions, you must configure a sessionless vserver in the NetScaler. The sessionless vserver does not allocate any resources on the NetScaler, thereby saving the memory that the specific deployment consumes. When you enable the sessionless option, the NetScaler performs load balancing on a per-packet basis. When a sessionless vserver is configured, the sessionless vserver forwards the packets to a server selected using load balancing methods. While forwarding the packet, the NetScaler changes the destination MAC address to the server MAC address. For sessionless load balancing to operate correctly, you must perform the following tasks: • Enable MBF mode 196 Installation and Configuration Guide - Volume 1 • Enable MAC mode on the sessionless LB vserver • Enable USIP mode on services (because the IP address of the source is not changed) Sessionless load balancing has the following limitations: • Sessionless LB can only be used for load balancing in a direct server return deployment, and in IDS load balancing. • The least connections method cannot be used in sessionless mode. • A vserver of type ANY or UDP can be configured as a sessionless vserver. To configure a sessionless vserver, use the Sessionless parameter as described in the following table. The following example describes the steps to configure the vserver Vserver-LB-1 for sessionless load balancing. The service Service-ANY-1 is configured with Use Source IP enabled. To set a sessionless vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure sessionless load balancing, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Under Redirection Mode, select the MAC mode radio button. 6. Select the Sessionless check box. 7. Click OK. To set a sessionless vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -m MAC -sessionless enabled Parameter Description Sessionless Enable sessionless load balancing. The valid options for the Sessionless parameter are: enabled and disabled. The default value is disabled. Chapter 4 Load Balancing 197 Redirecting HTTP Requests to a Cache The NetScaler provides the cache redirection option for transparently redirecting HTTP requests to a cache. A cache stores frequently requested HTTP content. When you configure cache redirection on a vserver, the NetScaler sends cacheable HTTP requests to the transparent caches and non-cacheable HTTP requests to the origin Web servers. For more information on cache redirection, see the “Cache Redirection” chapter of the Installation and Configuration Guide. To configure cache redirection, use the Cache Redirection parameter as described in the following table. To set cache redirection on a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure cache redirection, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Select the Cache Redirection check box. 6. Click OK. To set cache redirection on a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -cacheable yes Parameter Description Cache Redirection Enables the vserver to route requests to the cache redirection vserver before sending them to the configured servers. The valid options for this parameter are: yes and no. The default value is no. 198 Installation and Configuration Guide - Volume 1 Directing Requests Based on Priority the NetScaler provides the priority queuing option for prioritizing client requests to serve important requests first. The NetScaler places the requests in a queue based on the configured priority, thereby providing an uninterrupted flow of transactions through surges or attacks. For more information on priority queuing, see the “Priority Queuing” chapter in the Installation and Configuration Guide. To configure priority queuing, use the Priority Queuing parameter as described in the following table. To set priority queuing on a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure priority queuing, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Select the PQ check box. 6. Click OK. To set priority queuing on a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -pq yes Note: You must set priority queuing globally for it to function correctly. For more information on configuring priority queuing globally, see the “Protection” chapter of the Installation and Configuration Guide. Parameter Description Priority Queuing Enable priority queuing on the specified vserver. The valid options for this parameter are: on and off. The default value is off. Chapter 4 Load Balancing 199 Directing Requests to a CustomWeb Page To ensure the response from an application through the delays because of server capacity or processing speed, the NetScaler provides sure connect option. Sure connect eliminates the gap between the client expectations and their browsing experience, and improves the real and perceived availability of a Web site. For more information about sure connect, see the sure connect chapter of Installation and Configuration Guide. To configure sure connect, use the sure connect parameter as described in the following table. To set Sure Connect on a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure sure connect, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Select the SC check box. 6. Click OK. To set Sure Connect on a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -sc yes Note: For sure connect to function correctly, you must set it globally. For more information about configuring sure connect globally, see “Sure Connect” chapter of the Installation and Configuration Guide. Parameter Description Sure Connect Enable Sure Connect on the specified vserver. The valid options for this parameter are: ON and OFF. The default value is OFF. 200 Installation and Configuration Guide - Volume 1 Enabling Delayed Cleanup of Vserver Connections You must not enable the down flush state setting on the vservers and services that must complete their transactions and their connections must not be flushed. You can enable the setting on the vservers and services whose connections can be flushed when they marked down. The state of a vserver depends on the states of the services bound to it. The state of each service depends on the monitors bound to it. Sometimes services do not respond to monitors and are marked down. If the server is slow or busy, the monitoring probes time out and the service is marked as down. A vserver is marked as down only when all services bound to it are marked as down. You can configure vservers to either immediately terminate all connections or allow the connections to go through when they go down. You can use this setting when a service is marked as down due to a slow server. The following table summarizes the impact of this setting on a configuration consisting of a vserver and two services. The vserver Vserver-LB-1 has two services, Service-TCP-1 and Service-TCP-2 bound to it. The vserver intercepts two connections, C1 and C2, and redirects them to Service-TCP-1 and Service- TCP-2 respectively. In the table, E and D denote the state of the downStateFlush setting, where E represents Enabled and D represents Disabled. Note: In case of HTTP services, the down state flush setting is effective only when the client is connected to the server. Vserver-LB-1 Service-TCP-1 State of Connections E E Both client and server connections are terminated. E D Both client and server connections are terminated. In case of HTTP services, both client and server connections are terminated only if the transaction is active. If the transaction is not active, only client connections are terminated. D E Both client and server connections are terminated. In case of HTTP services, both client and server connections are terminated only if the transaction is active. If the transaction is not active, only server connections are terminated. D D Both client and server connections are not terminated. Chapter 4 Load Balancing 201 You can extend this logic to larger configurations. To configure down state flush, use the down state flush parameter as described in the following table. To set down state flush on a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure down state flush, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Select the Down state flush check box. 6. Click OK. To set down state flush on a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -downStateFlush enabled Rewriting Ports and Protocols for HTTP Redirection The vservers and servers may use different ports and when the server responds with a redirect, you must configure the NetScaler to rewrite the port and the protocol. By default, this setting is enabled. This setting affects HTTP traffic only. When this setting is enabled on a vserver, the NetScaler rewrites the port using the port settings of the vserver. This setting can be used in the following scenarios: • The vserver is of type HTTP and the services are of type SSL • The vserver is of type SSL and the services are of type HTTP • The vserver port is different than the service port Parameter Description down state flush Perform delayed cleanup of connections on this vserver. The valid options for this parameter are: enabled and disabled. The default value is enabled. 202 Installation and Configuration Guide - Volume 1 When the requests are of type HTTP and the services are of type SSL, the NetScaler rewrites the port of the HTTP requests to that of SSL and forwards the requests to the SSL services. Then, the NetScaler rewrites the port of the HTTPS responses to that of HTTP and forwards them to the client. This is summarized in the following table. When the requests are of type SSL and the services are of type HTTP, the NetScaler rewrites the port of the SSL requests to that of HTTP and forwards the requests to the HTTP services. Then, the NetScaler rewrites the port of the HTTP responses to that of HTTPS and forwards them to the client. When both requests and responses are of same type the NetScaler rewrites the port using the same port value. For more information about SSL redirects, see the “Secure Sockets Layer (SSL) Acceleration” chapter in Installation and Configuration Guide. To configure a vserver for HTTP redirection, you must use the redirect port rewrite parameter listed in the following table. To set HTTP redirection on a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure HTTP redirection, for example, Vserver-LB-1. Redirect URL URL after port rewrite Case 1 - Redirect port rewrite enabled and vserver on port 80 http://domain.com/ http://domain.com/ http://domain.com:8080/ http://domain.com/ https://domain.com/ https://domain.com/ https://domain.com:444/ https://domain.com:444/ Case 1 - Redirect port rewrite enabled and vserver on port 8080. http://domain.com/ http://domain.com:8080/ http://domain.com:8080/ http://domain.com:8080/ https://domain.com/ https://domain.com/ https://domain.com:445/ https://domain.com:445/ Parameter Description Redirect Port Redirect The state of port rewrite while performing HTTP redirect. The valid options for this parameter are: enabled and disabled. The default value is disabled. Chapter 4 Load Balancing 203 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. Select the Redirect Port Rewrite check box. 6. Click OK. To set HTTP redirection on a vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -redirectPortRewrite enabled Inserting the IP Address and Port of a Vserver in the Request Header You can configure the NetScaler to add the IP address and port number of a vserver to the HTTP requests that are sent to the server. This setting allows applications running on the server to identify the vserver that sent the request. This option is not supported for wildcard vservers or dummy vservers. If the primary vserver is down and the backup vserver is up, the configuration settings of the backup vserver are added to the client requests. If you want the same header tag to be added, irrespective of whether the requests are from the primary vserver or backup vserver, then you must configure the required header tag on both vservers. 204 Installation and Configuration Guide - Volume 1 To configure a vserver to add the IP address and port to the client requests, use the Vserver IP Port Insertion parameter as described in the following table. The following example describes the steps to configure the NetScaler to add the IP address and port number of the vserver Vserver-LB-1 to HTTP requests that are forwarded to the servers. To insert the IP address and port of the vserver in the client requests using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure vserver port insertion, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Vserver IP Port Insertion list, select the VIPADDR or V6TOV4MAPPING. Parameter Description Vserver IP Port Insertion The virtual IP and port header insertion option for the vserver. VIPADDR-Header contains the vserver IP address and port number without any translation. If VIPADDR is not specified, the header is inserted with the name specified in the default header tag vip-header and the vserver IP and port are inserted in the request with the default header tag vip-header. If VIPADDR is specified, the header is inserted with the user-specified name in vipHeader. The vserver IP and port are inserted in the request with the user-specified header tag vipHeader. OFF- The virtual IP and port header insertion option is disabled. The vserver and port number are not inserted. V6TOV4MAPPING - Header contains the mapped IPv4 address corresponding to the IPv6 address of the vserver and the port number. An IPv6 address can be mapped to a user-specified IPv4 address. The valid options for this parameter are: OFF, VIPADDR, and V6TOV4MAPPING The default value is OFF. Chapter 4 Load Balancing 205 6. Type the port header in a text box next to Vserver IP Port Insertion box. 7. Click OK. To insert the IP address and port of the vserver in the client requests using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -insertVserverIPPort VipAddr Setting a Time-out Value for Idle Client Connections You can configure the vserver with a timeout value to terminate any idle client connections when the configured time elapses. When you configure this setting, the NetScaler waits for the time you specify, and if the client is idle after the configured time, the NetScaler closes the client connection. To set a timeout value for idle client connections, use the client parameter as described in the following table. The following example describes the steps to set the timeout value for idle client connections to 100 seconds. To set a timeout value for idle client connections using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure vserver port insertion, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 5. In the Client Timeout (secs) text box, type the timeout value, for example, 100. 6. Click OK. To set a timeout value for idle client connections using the NetScaler command line At the NetScaler command prompt, type: Parameters Descriptions Client Timeout (Secs) The idle time (in seconds) after which the client connection is terminated. The default value is 180sec for HTTP/SSL-based services and 9000sec for TCP-based services. 206 Installation and Configuration Guide - Volume 1 set lb vserver Vserver-LB-1 -cltTimeout 100 Managing and Monitoring Servers This section describes how to manage and monitor servers. Managing and monitoring servers allows the NetScaler to determine the state of the service. You can perform management tasks such as protect the services against traffic surges, ensure the server response, and enable access to the services that are down. You can also configure monitors and modify them. Topics include: • Configuring Services for Load Balancing • Configuring Monitors • Monitoring Applications and Services Using Prebuilt Monitors • Monitoring Applications and Services Using Customized Monitors • Configuring Support for Third-party Load Balancers Using SASP Configuring Services for Load Balancing This section describes how to manage the servers by configuring the services with advanced settings. Advanced configuration settings allow you to protect the servers against traffic surges, ensure the server response, improve client responses, and so on. Protecting Applications on the Servers Against a Traffic Surge the NetScaler provides the surge protection option to maintain the capacity of a server or cache. The NetScaler regulates the flow of client requests to servers and controls the number of clients that can simultaneously access the servers. The NetScaler blocks any surges passed to the server, thereby preventing overloading of the server. For more information about surge protection, see the “Surge Protection” chapter of the Installation and Configuration Guide. To configure surge protection, use the surge protection parameter as described in the following table. Parameters Descriptions Surge protection The state of surge protection for the service. The valid options for this parameter are: ON and OFF. The default value is off. Chapter 4 Load Balancing 207 To set surge protection on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure surge protection, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Others, select the Surge Protection check box. 6. Click OK. To set surge protection on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -sp on Note: For surge protection to function correctly, you must enable it globally. For more information about configuring surge protection globally, see the “Protection” chapter of the Installation and Configuration Guide. Directing Requests to a CustomWeb Page the NetScaler provides the sure connect option to ensure the response from an application. Sure connect is described in the section “Directing Requests to a Custom Web Page” on page 199. To configure sure connect, use the sure connect parameter as described in the following table. To set sure connect on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure sure connect, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. Parameters Descriptions Sure Connect The state of sure connect for the service. This parameter is supported for legacy purposes only. It has no effect on the NetScaler, and its only valid value is OFF. The valid options for this parameter are: ON and OFF. The default value is OFF. For more information about the sure connect parameter, see the “Sure Connect” chapter. 208 Installation and Configuration Guide - Volume 1 4. Click the Advanced tab. 5. Under Others, select the Sure Connect check box. 6. Click OK. To set sure connect on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -sc on Note: For sure connect to function correctly, you must set it globally. For more information about configuring sure connect globally, see the “Sure Connect” chapter of the Installation and Configuration Guide. Enabling Delayed Cleanup of Service Connections When delayed cleanup of service connections is enabled, the NetScaler performs a delayed cleanup of the connections on a service that is down. This setting is described in the section “Enabling Delayed Cleanup of Vserver Connections” on page 200. To configure down state flush, use the down state flush parameter as described in the following table. To set down state flush on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure down state flush, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Others, select the Down state flush check box. 6. Click OK. To set down state flush on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -downStateFlush enabled Parameters Descriptions Down State Flush Perform delayed clean up of connections on this service. The valid options for this parameter are: enabled and disabled. The default value is enabled. Chapter 4 Load Balancing 209 Enabling Access to Services When Down You can enable access to a service when it is disabled or down. When you enable Layer 2 or Layer 3 modes, the NetScaler bridges the packets sent to the services. However, when the requests are forwarded to the services that are down, the request packets are dropped. When you enable this setting and the request packets are sent to the services that are down, the packets are bridged. Note: For the NetScaler to bridge the packets sent to the down services, enable Layer 2 or Layer 3 modes with the access down parameter. For more information about Layer 2 and Layer 3 modes, see the “Basic Network Configuration” chapter of the Installation and Configuration Guide. To configure access down, use the access down parameter as described in the following table. To set access down on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure access down, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Others, select the Access Down check box. 6. Click OK. To set access down on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -accessDown yes Parameters Descriptions Access Down Allows access to disabled or down services. If this option is enabled, all packets to this service are bridged. If this option is disabled, the packets are dropped. The valid options for this parameter are: yes and no. The default value is no. 210 Installation and Configuration Guide - Volume 1 Enabling TCP Buffering of Response the NetScaler provides a TCP buffering option that buffers only the responses from the server. This enables the NetScaler to deliver server responses to the client at the speed of the client NetScaler. The NetScaler allocates 0-4095 MB of memory for TCP buffering, and 4-20480 KB of memory per connection. To enable TCP buffering of server data, use the TCP Buffering parameter as described in the following table. To set TCP Buffering on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure TCP buffering, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the TCP Buffering check box. 6. Click OK. To set TCP Buffering on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -TCPB yes Note: TCP buffering set at the service level takes precedence over the global setting. For more information about configuring TCP buffering globally, see “Performance” chapter of the Installation and Configuration Guide. Enabling Compression The NetScaler provides the compression option to transparently compress the HTML and text files. The NetScaler has a set of built-in compression policies and uses them to compress the files. The compression policies act on the service bound to the vserver and determine whether the response is compressible. The compressible content is compressed and sent to the client. Parameters Descriptions TCP Buffering The state of the TCP buffering feature for the service. The valid options for this parameter are: yes and no. The default value is no. Chapter 4 Load Balancing 211 Compression reduces the amount of data delivered to the browser and improves client response time. To enable compression on a service, use the compression parameter as described in the following table. To set compression on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure compression, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Compression check box. 6. Click OK. To set compression on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -CMP yes Note: For compression to function correctly, you must enable it globally. For more information about configuring compression globally, see the “Performance” chapter of the Installation and Configuration Guide. Parameters Descriptions Compression The state of the HTTP compression feature for the service. The valid options for this parameter are: yes and no. The default value is no. 212 Installation and Configuration Guide - Volume 1 Maintaining Client Connection for Multiple Client Requests You can configure services to maintain client connection for multiple client requests by using the client keep-alive parameter. If the server closes the connection, the setting keeps the connection between the client and the NetScaler open. This setting allows services to serve multiple client requests on a single client connection. If you do not enable this setting, the client may open a new connection for every request to the server. The client keep-alive setting saves packet round trip time to establish connections and close the connections. This setting also reduces the time to complete each transaction. Client keep-alive can be set only on HTTP or SSL service types. For more information about client keep-alive, see the “Performance” chapter of the Installation and Configuration Guide. To enable client keep-alive, use the Client Keep-Alive parameter as described in the following table. To set client keep-alive on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure client keep-alive, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Client Keep-Alive check box. 6. Click OK. To set client keep-alive on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -CKA yes Note: Client-keep alive set at the service level takes precedence over the global setting. For more information about configuring Client-keep alive globally, see the “Performance” chapter of the Installation and Configuration Guide. Parameters Descriptions Client Keep-Alive The state of the Client Keep-Alive feature for the service. The valid options for this parameter are: yes and no. The default value is no. Chapter 4 Load Balancing 213 Inserting the IP Address of the Client in the Request Header A NetScaler uses the mapped IP address to connect to the server. The server uses the NetScaler IP address to send the responses. The server is not aware of the client. The header of the packets sent to the server has the NetScaler IP address as the destination address, as shown in the following figure. IP header When you enable client IP setting, the NetScaler inserts the client IP address while forwarding the requests to the server. The server inserts this client IP in the header of the responses. The server is thus aware of the client, as shown in the following figure. IP header when CIP insertion enabled 214 Installation and Configuration Guide - Volume 1 To insert the IP address of the client in the client request, use the parameters as described in the following table. The following example describes the steps to insert the client IP address while forwarding the client request to the server. To insert client IP address in the client request using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to add the client IP address in the request, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Client IP check box. 6. In the Header text box, type the header tag, for example, X-Forwarded-for. 7. Click OK. To insert client IP address in the client request using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -CIP enabled X-forwarded-for Parameters Descriptions Client IP The Client IP header addition option for the service. The valid options for this parameter are: enabled and disabled. The default value is disabled. Client IP Header The name of the HTTP header used. You must specify the IP address of the client. If client IP insertion is enabled and the client IP header is not specified, then the NetScaler sets the client IP header. The default is blank (NetScaler uses a blank HTTP header). Chapter 4 Load Balancing 215 Setting Server ID to Maintain Persistent Connections Configuring the custom server ID persistence type requires that you set a server ID. The persistence type embeds the server ID that servers provide in the response. The NetScaler extracts the server ID from subsequent requests and uses it to choose a server. To set the server ID, use the server ID parameter as described in the following table. The following example describes the steps to set the server ID to 11. To insert the server ID in the response from the server using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to set the server ID, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. In the ServerID text box, type the ID of the server, for example, 11. 6. Click OK. To insert the server ID in the response from the server using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -serverID 11 Parameters Descriptions Server ID The identifier for the service. This is used when the persistence type is set to Custom Server ID. The minimum value is 0 and the maximum value is 65535. 216 Installation and Configuration Guide - Volume 1 Using the Source IP Address of the Client When Connecting to the Server When you enable this setting, the NetScaler forwards the packet from the client to the server without changing the source IP address. To configure use source IP address (USIP), use the use source IP address parameter as described in the following table. You can use this option when you cannot insert the client IP address, for example, non-HTTP services. To use IP address of the client using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to use the source IP address, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Use Source IP check box. 6. Click OK. To use IP address of the client using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -usip yes Note: For USIP to function correctly, you must set it globally. For more information about configuring USIP globally, see the “Basic Network Configuration” chapter of the Installation and Configuration Guide. Parameters Descriptions Use Source IP Address Use the client IP address option as the source IP address when the NetScaler connects to the server. With this option set, the NetScaler uses the client IP address for server connection. The valid options for this parameter are: yes and no. The default value is no. Chapter 4 Load Balancing 217 Setting a Limit on the Number of Client Connections You can specify a maximum limit for the number of client connections that the server can handle. The NetScaler opens the client connections to the servers until this limit is reached. When the maximum limit of client connections is reached, the monitor probes are skipped and the server is not used for load balancing. To limit the number of client connections, use the Maximum Clients parameter as described in the following table. Note: Connections that are closing are not considered for this limit. For more information on Maximum Client, see the section “Load Balancing with Domain-Name Based Services” on page 287. To set a limit the number of client connections using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure the maximum number of client connections, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Thresholds, in the Max Client text box, type the maximum number of client connections, for example, 100. 6. Click OK. To set a limit the number of client connections using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -maxClient 1000 Parameters Descriptions Maximum Clients The maximum number of open connections to the service. The default value is 0. The maximum value is 4294967294. 218 Installation and Configuration Guide - Volume 1 Setting a Limit on Number of Requests Per Connection to the Server In some scenarios, servers have issues when the connections are reused for many requests. You can use the max request option to limit the number of requests sent on a single connection to the server. You can use the max request option for HTTP or SSL. To limit the number of requests, use the maximum requests parameter as described in the following table. To limit the number of client requests using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure the maximum number of client requests, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Thresholds, in the Max Requests text box, type the maximum number of client requests, for example, 100. 6. Click OK. To limit the number of client requests using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -maxReq 100 Setting a Threshold Value for Monitors The threshold value for the monitor specifies a value that determines the state of the service as UP. The NetScaler determines the state of the service as UP only when the sum of the monitors that are UP is equal to or greater than the threshold value you configured on the service. To set the monitor threshold, use the monitor threshold parameter as described in the following table. Parameters Descriptions Maximum Requests The maximum number of requests that can be sent on a persistent connection to the service. The default value is 0. The minimum value is 0 and maximum value is 65535. ‘0’ specifies that there is no limit on the maximum requests that are sent on a persistent connection. Parameters Descriptions Monitor Threshold The monitoring threshold. The default value is 0. The minimum value is 0 and maximum value is 65535. Chapter 4 Load Balancing 219 To set monitor threshold on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure monitor threshold, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. In the Monitor Threshold text box, type the monitor threshold, for example, 100. 6. Click OK. To set monitor threshold on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -monThreshold 100 Setting a Time-out Value for Idle Client Connections You can configure the service with a timeout value to terminate any idle client connections when the configured time elapses. If the client is idle during the configured time, the NetScaler closes the client connection. To set a timeout value for idle client connections, use the client parameter as described in the following table. The following example describes the steps to set the timeout value for idle client connections to 100 seconds. To set a timeout value for idle client connections using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure the timeout value for client connections, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. Parameters Descriptions Client The idle time (in seconds) after which the client connection is terminated. The default value is 180sec for HTTP/SSL-based services and 9000sec for TCP-based services. 220 Installation and Configuration Guide - Volume 1 5. Under Idle Timeout (secs), in the Client text box, type the timeout value, for example, 100. 6. Click OK. To set a timeout value for idle client connections using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -cltTimeout 100 Setting a Time-out Value for Idle Server Connections You can configure the service with a timeout value to terminate any idle server connections when the configured time elapses. If the server is idle during the configured time, the NetScaler closes the server connection. To set a timeout value for idle server connections, use the server parameter as described in the following table. The following example describes the steps to set the timeout value for idle server connections to 100 seconds. To set a timeout value for idle server connections using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure the timeout value for server connections, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Idle Timeout (secs), in the Server text box, type timeout value, for example, 100. 6. Click OK. To set a timeout value for idle server connections using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -svrTimeout 100 Parameters Descriptions Server The idle time (in seconds) after which the server connection is terminated. The default value is 360. The maximum value is 31536000. Chapter 4 Load Balancing 221 Setting a Limit on the Bandwidth Usage by Clients In some scenarios, the servers may have limited bandwidth to handle client requests, and may become overloaded. You can specify a maximum limit on the bandwidth that the server can handle. The NetScaler forwards requests to the servers until this limit is reached. To set a limit on bandwidth, use the maximum bandwidth parameter as described in the following table. The following example describes the steps to set the maximum bandwidth that the client can use for the service Service-HTTP-1 to 100 kilobits. To set a limit bandwidth usage on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure maximum bandwidth usage, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Thresholds, in the Max Bandwidth text box, type the maximum bandwidth, for example, 100. 6. Click OK. To set a limit bandwidth usage on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -maxBandwidth 100 Parameters Descriptions Maximum Bandwidth The maximum bandwidth allowed for the service. The maximum bandwidth parameter is an inbound setting, and is used on incoming requests. The unit of measurement is kilobits. 222 Installation and Configuration Guide - Volume 1 Redirecting Client Requests to a Cache You can configure a service to redirect client requests to a cache, and then forward the request to the servers. To set cache redirection, use the parameters described in the following table. The following example describes the steps to set cache redirection for the service Service-HTTP-1. To set cache redirection on the service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to configure cache redirection, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Cache Redirection Options, in Cache Type list, select the type of cache, for example, Regular Server. 6. Select the Enable Cache Redirection check box. 7. Click OK. To set cache redirection on the service using the NetScaler command line At the NetScaler command prompt, type: set service Service-HTTP-1 -cacheable yes Parameters Descriptions Cache Redirection The vserver routes a request to another vserver on the same NetScaler, then forwards the request to the configured servers. The vserver used for transparent cache redirection determines if the request is directed to the cache servers or the configured servers. By default, this argument is disabled. The valid options for this parameter are: yes, and no. The default value is no. Cache Type The cache type option supported by the cache server. The valid options for this parameter are: transparent, reverse, and forward. Chapter 4 Load Balancing 223 Configuring Monitors Monitors periodically check the state of a service. The NetScaler does not consider services that are marked down for load balancing. A monitor allows the NetScaler to accurately evaluate services. You can bind multiple monitors of any type to a service to determine its state. Monitors specify the types of requests sent to the server, and the expected response from the server. Monitors periodically probe the servers and check if they receive a response within the configured time. If the monitor does not receive a response in the configured time, and if the configured number of probes fail, it determines the server as DOWN. Topics include: • Configuring Monitors in an LB Setup • Modifying Monitors • Managing Monitors Configuring Monitors in an LB Setup This section describes the procedures to configure monitors in an LB setup, and the tasks to create and bind the monitors to the services. After the monitors are bound to the services, they periodically probe the services to determine the state of the services. The following table lists the names and values of the basic entities that are configured on the NetScaler, as described in the “Configuring a Basic Setup” on page 114. Entity Type Name IP Addresses Port Protocol Vserver Vserver-LB-1 10.102.29.60 80 HTTP Services Service-HTTP-1 10.102.29.5 80 HTTP Service-HTTP-2 10.102.29.6 80 HTTP Monitors Monitor-HTTP-1 None None HTTP 224 Installation and Configuration Guide - Volume 1 The following figure shows the monitors and how they operate. Working of monitors Creating Monitors The NetScaler provides a set of built-in monitors. The NetScaler also allows you to create custom monitors based on the default monitors. To create monitors, use the parameters as described in the following table. Parameters Description Monitor Name The unique name of the monitor. This name must not exceed 31 characters. Monitor Type The type of monitor. The valid options for this parameter are: PING, TCP, HTTP, TCP-ECV, HTTP-ECV, UDP-ECV, DNS, FTP, RADIUS, USER, HTTP-INLINE, SIP-UDP, LOAD, FTP-EXTENDED, SMTP, SNMP, NNTP, MYSQL, LDAP, POP3, CITRIX-XML-SERVICE, and CITRIX-WEB- INTERFACE Interval The frequency at which the probe is sent to a service. The interval must be greater than the response timeout. The minimum value is 1 millisecond and the maximum value is 160 seconds. The default value is 5 seconds. Chapter 4 Load Balancing 225 The following example describes the steps to create a monitor monitor-HTTP-1, of type HTTP, with a time interval of 340 seconds. To create a monitor using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Click Add. The Create Monitor dialog box appears. 3. In the Name and Interval text boxes type the name and interval value of the monitor, for example, monitor-HTTP-1 and 340. 4. In the Type list, select the type of the monitor, for example, HTTP. 5. In the list next to the Interval text box, select Seconds. 6. Click Create and click Close. The monitor you created appears in the Monitors page, as shown in the following figure. Monitors page To create a monitor using the NetScaler command line At the NetScaler command prompt, type: add lb mon monitor-HTTP-1 HTTP Binding Monitors to Services After creating a monitor, you can bind it to a service. For the NetScaler to monitor the servers, the monitors must be bound to the service. The NetScaler sends periodic requests to the server. The servers must send a response prior to the configured response timeout. If the configured number of probes fail, the server is marked down, and the next probe is sent when the configured downtime elapses. The destination of the probe may be different than the server IP address and port. 226 Installation and Configuration Guide - Volume 1 You can bind multiple monitors to a service and the status of the service is determined using the results of the bound monitors. The following example describes the steps to bind the monitor monitor-HTTP-1 to the service Service-HTTP-1. To bind a monitor to a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service for which you want to bind the monitor, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Under Available, in the Monitors list box, select the monitor you want to bind the service, for example, monitor-HTTP-1. 5. Click Add. The monitor appears in the Configured box. 6. Click OK. To bind a monitor to a service using the NetScaler command line At the NetScaler command prompt, type: bind mon monitor-HTTP-1 Service-HTTP-1 Modifying Monitors You can modify the configured monitors. If you change a monitor that is bound to multiple services, monitoring of the bound services changes. You can modify a monitor that you created using the parameters listed in this section. Two sets of parameters apply to monitors: • Parameters that apply to all monitors, regardless of type • Parameters that are specific to a monitor type This section describes the parameters that apply to all monitors. To modify monitors, you can use the parameters listed in the following table. Parameter Description LRTM The state of the response time calculation of probes. The valid options for this parameter are: enabled and disabled. The default value is disabled. Deviation Deviation from the learned response time for dynamic response time monitoring. The maximum value is 348 minutes. Chapter 4 Load Balancing 227 Response Timeout The duration of the interval for which the NetScaler waits before it marks the probe as failed. The response timeout must be less than the value specified in the interval parameter. The UDP-ECV monitor type does not decide the probe failure using the response timeout. The NetScaler considers the probe as successful for the UDP-ECV monitor type when the server response matches the criteria that the send and receive options set, or if the response is not received from the server. The send option specifies the data that must be sent to the server in the probe, and the receive option specifies the server response criteria for the probe to succeed. The unreachable error from the service causes probe failure. The minimum value is 10 milliseconds. The maximum value is 159 seconds. The default value is 2 seconds. Response Timeout Threshold The monitor response timeout threshold. If the response time for the monitoring probes exceeds the threshold, a trap is sent. The response timeout is given as a percentage. The minimum value is 1 and the maximum value is 100. Retries The number of consecutive probes failures after which the NetScaler determines the service as down. The default value is 3. Down Time The wait duration until the next probe after the service is marked down. The minimum value is 10 milliseconds and the maximum value is 160 seconds. The default value is 30 seconds. Destination IP Address The IP address to which the probe is sent. If the destination IP address is set to 0, the destination IP address is set to the bound service. The default is 0.0.0.0. Destination Port The TCP/UDP port to which the probe is sent. If the destination port is set to 0, the destination port is the port of the service to which the monitor is bound. For a USER monitor, this port is the port sent in the HTTP request to the dispatcher. This option is ignored if the monitor is of the PING type. For information about user monitors, see “Configuring User Monitors” on page 248. State The state of the monitor. If the monitor is disabled, this monitor type probe is not sent for the services. If the monitor is bound, the state of this monitor is not considered when the state of the service is determined. The valid options for this parameter are: enable and disable. The default value is enabled. Reverse The state of reverse probe criterion check. The valid options for this parameter are: yes and no. The default value is no. Parameter Description 228 Installation and Configuration Guide - Volume 1 The following example describes the steps to configure the monitor monitor- HTTP-1 with an interval of 50 milliseconds and a response time of 20 milliseconds. To modify an existing monitor using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Select the monitor that you want to modify, for example, monitor-HTTP-1. 3. Click Open. The Configure Monitor dialog box appears. 4. In the Interval and Response Timeout text boxes, type the interval and response timeout values, for example, 50 and 20. 5. In the list next to Interval text box, select Milli Seconds. 6. In the list next to Response Timeout text box, select Milli Seconds. 7. Click OK. To modify an existing monitor using the NetScaler command line At the NetScaler command prompt, type: set mon monitor-HTTP-1 HTTP -interval 50 milli -resptimeout 20 milli Transparent The state of the monitor bound for transparent devices, such as firewalls, based on the responsiveness of the services behind them. If monitoring of transparent devices is enabled, the destination IP address must be specified. The probe is sent to the specified destination IP address using the MAC address of the transparent device. The valid options for this parameter are: yes and no. The default value is no. Secure The state of the secure monitoring of services. SSL handshake is performed on the established TCP connection. Applicable for TCP based monitors only. The valid options for this parameter are: yes and no. The default value is no. Application Name of the application that must be executed to check the state of the service. Site Path URL of the logon page. Parameter Description Chapter 4 Load Balancing 229 Managing Monitors This section describes how to manage the monitors you create. You can change the bindings of the monitors, or enable, disable, and remove monitors. You can also unbind monitors from services and service groups. Enabling and Disabling Monitors By default, monitors bound to services and service groups are enabled. If you disable a monitor bound to a service, the state the service is determined using the other monitors bound to the service. If the service is bound to only one monitor, and if you disable the monitor, the state of the service is determined using the default monitor. The following example describes the steps to disable the monitor monitor-HTTP-1. To disable a monitor using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Select the monitor that you want to disable, for example, monitor-HTTP-1. 3. Click Disable. The Disable pop-up window appears. 4. Click Yes. To disable a monitor using the NetScaler command line At the NetScaler command prompt, type: disable lb mon Service-HTTP-1 When you enable a monitor, the monitor begins probing the services to which it is bound. The following example describes the steps to enable the monitor monitor-HTTP-1. To enable a monitor using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Select the monitor that you want to enable, for example, monitor-HTTP-1. 3. Click Enable. The Enable pop-up window appears. 4. Click Yes. To enable a monitor using the NetScaler command line At the NetScaler command prompt, type: enable lb mon Service-HTTP-1 230 Installation and Configuration Guide - Volume 1 Unbinding Monitors You can unbind monitors from a service and service group. When you unbind a monitor from the service group, the monitors are unbound from the individual services that constitute the service group. When you unbind a monitor from a service or a service group, the monitor does not probe the service or the service group. When you unbind the configured monitors from a service or a service group, the default monitor is bound to the service and the service group. The default monitors then probes the service or the service groups. The following example describes the steps to unbind the monitor monitor-HTTP-1 from the service Service-HTTP-1. To unbind a monitor from a service using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service from that you want to unbind the monitor, for example, Service-HTTP-1. 3. Click Open. The Configure Service dialog box appears. 4. Under Configured, select the monitor that you want to unbind from the service, for example, monitor-HTTP-1. 5. Click Remove. Under Available, the available monitors appear in the Monitors list box. 6. Click OK. To unbind a monitor from a service using the NetScaler command line At the NetScaler command prompt, type: unbind mon monitor-HTTP-1 Service-HTTP-1 Removing Monitors You can remove a monitor that you have configured. If a monitor is bound to a service, it cannot be removed. Therefore, you must first unbind the monitor from the service and then remove it. When you remove monitors bound to a service, the default monitor is bound to the service. You cannot remove default monitors. The following example describes the steps to remove the monitor monitor-HTTP-1. To remove a monitor using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. Chapter 4 Load Balancing 231 2. Select the monitor that you want to remove, for example, monitor-HTTP-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a monitor using the NetScaler command line At the NetScaler command prompt, type: rm lb monitor monitor-HTTP-1 HTTP Viewing Monitors You can view the services and service groups bound to the monitor. You can verify the settings of the monitors to troubleshoot the configuration.The following procedure describes the steps to view the bindings of a monitor to the services and service groups. To view monitor bindings using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. In the Monitors page, select the monitor for which you want to view the binding information, for example, monitor-HTTP-1. 3. Click Show Bindings. The binding information for the monitor that you selected appears in the Binding Info for Monitor: monitor-HTTP-1 dialog box. To view monitor bindings using the NetScaler command line At the NetScaler command prompt, type: show lb monbindings monitor-HTTP-1 To view monitors using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. The details of the available monitors appear on this page. To view monitors using the NetScaler command line At the NetScaler command prompt, type: show lb mon monitor-HTTP-1 232 Installation and Configuration Guide - Volume 1 Monitoring Applications and Services Using Prebuilt Monitors This section describes the built-in monitors. You cannot modify the built-in monitors. You can only bind the built-in monitors to the services. However, you can create a custom monitor based on the built-in monitors. To create and bind monitors to the services, see the section “Configuring Monitors in an LB Setup” on page 223, to create and bind the monitors to the services. Monitoring TCP-based Applications The NetScaler has a set of default monitors (tcp-default and ping-default). After a service is created on the NetScaler, the appropriate default monitor is bound to it, so that the service can be used immediately (if it is up): • The TCP-default monitor is bound to all TCP services • The ping-default monitor is bound to all non-TCP services You cannot delete, or modify default monitors. When you bind any monitor to the service, the default monitor is unbound from the service. The following table gives information about monitor types, parameters, and monitoring procedures. The NetScaler provides a built-in monitor for each monitor type. Type Specific Parameters Procedure TCP (tcp) Not applicable The NetScaler establishes a 3-way handshake with the monitor destination, and then closes the connection. If the NetScaler observes TCP traffic to the destination, it does not send TCP monitoring requests. This occurs if LRTM is disabled. By default, LRTM is disabled on this monitor. HTTP (http) httprequest [“HEAD /”] - HTTP request that is sent to the service. respcode [200] - A set of HTTP response codes are expected from the service. The NetScaler establishes a 3-way handshake with the monitor destination. After the connection is established, the NetScaler sends HTTP requests, and then compares the response code in the response from the service, with the configured set of response codes. TCP-ECV (tcp-ecv) send [""] - is the data that is sent to the service. The maximum permissible length of the string is 512 K bytes. recv [""] - expected response from the service. The maximum permissible length of the string is 128 K bytes. The NetScaler establishes a 3-way handshake with the monitor destination. When the connection is established, the NetScaler uses the send parameter to send specific data to the service and expects a specific response through the receive parameter. Chapter 4 Load Balancing 233 To configure prebuilt monitors for TCP-based applications, see “Configuring Monitors in an LB Setup” on page 223. To create a monitor, you must provide values for the required parameters. Monitoring SSL Services The monitors periodically check the SSL servers. The NetScaler has four built-in secure monitors: TCPS, HTTPS, TCPS-ENV, and HTTPS-ENV. You can use the secure monitors to check the HTTP and non-HTTP traffic. The secure monitors work as follows: HTTP- ECV (http-ecv) send [""] - HTTP data is sent to the service recv [""] - the expected HTTP response data from the service The NetScaler establishes a 3-way handshake with the monitor destination. When the connection is established, the NetScaler uses the send parameter to send the HTTP data to the service and expects the HTTP response that the receive parameter specifies. (HTTP body part without including HTTP headers). Empty response data matches any response. Expected data may be anywhere in the first 24K bytes of the HTTP body of the response. UDP- ECV (udp-ecv) send [""] - data that is sent to the service. recv [""] - expected response from the service. When the receive string is specified: If the response matches the receive string, the service is marked as up. Consequently, if the response matches the receive string for a reverse monitor, the service is marked as down. Also, the service is marked as down if an “icmp port unreachable” message is received. When the receive string is not specified: A service is marked as up whether or not a response is received. However, the service is marked as down if an “icmp port unreachable” message is received. For LRTM monitors, when no response is received, the response time is the response timeout for the monitor. When the UDP monitors detect an ICMP port unreachable error, the service is marked as down immediately. PING (ping) Not Applicable The NetScaler sends an ICMP echo request to the destination of the monitor and expects an ICMP echo response. Type Specific Parameters Procedure 234 Installation and Configuration Guide - Volume 1 TCPS - the NetScaler establishes a TCP connection. After the connection is established, the NetScaler performs an SSL handshake with the server. After the handshake is over, the NetScaler closes the connection. HTTPS - the NetScaler establishes a TCP connection. After the connection is established, the NetScaler performs an SSL handshake with the server. When the SSL connection is established, the NetScaler sends HTTP requests over the encrypted channel and checks the response codes. TCPS-ECV - the NetScaler establishes a TCP connection. After the connection is established, the NetScaler performs SSL handshake with the server. When the SSL connection is established, the NetScaler sends specific data using the send parameter to the service on the encrypted channel and expects a specific encrypted response. The response is decrypted, and the data is verified through the receive parameter. HTTPS-ECV - the NetScaler establishes a TCP connection. After the connection is established, the NetScaler performs an SSL handshake. When the SSL connection is established, the NetScaler sends the encrypted HTTP request specified using the send parameter to the service, and expects the encrypted HTTP response (HTTP body part, not including HTTP headers). This response is decrypted and compared with the expected response specified using the receive parameter. The following table describes the monitor types for monitoring SSL services. To configure prebuilt monitors to check the state of SSL services, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create monitors. Monitor type Probe Success criteria (Direct condition) TCP TCP connection SSL handshake Successful TCP connection established and successful SSL handshake. HTTP TCP connection SSL handshake Encrypted HTTP request Successful TCP connection is established, successful SSL handshake is performed, and expected HTTP response code in server HTTP response is encrypted. TCP-ECV TCP connection SSL handshake Data sent to a server is encrypted Successful TCP connection is established, successful SSL handshake is performed, and expected TCP data is received from the server. HTTP-ECV TCP connection SSL handshake Encrypted HTTP request Successful TCP connection is established, successful SSL handshake is performed, and expected HTTP data is received from the server. Chapter 4 Load Balancing 235 Monitoring FTP Services The FTP monitor opens a connection to an FTP server to determine the state of the service. During an FTP session, two connections are opened between the FTP monitor and FTP server: The FTP monitor opens the control connection to transfer commands between the monitor and the FTP server. Then the FTP server opens the data connection to transfer files between the FTP monitor and the server. The FTP monitor connects to the FTP server, checks the response code, and sends a command to the FTP server. If the FTP monitor receives a response in the specified time, the FTP services are marked up. The NetScaler establishes a TCP connection to the service. After a connection is established, the NetScaler logs in to the FTP server using the specified username and password. To monitor FTP services, use the parameters as described in the following table. The NetScaler has a monitor of type FTP-EXTENDED that provides a script to the FTP server. The FTP server executes the script and the responds to the query. Using the response, the FTP-EXTENDED monitor determines the state of the service. The following table describes the parameter you must use to configure FTP - EXTENDED monitors. To configure prebuilt monitors to check the state of FTP services, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create monitors of type FTP or FTP - EXTENDED. Monitoring SIP Services The Session Initiation Protocol (SIP) is an application layer control protocol established by the IETF. It is designed to initiate, manage, and terminate multimedia communications sessions, and has emerged as the standard for Internet telephony (VoIP). Parameters Descriptions User Name User name used in the probe. Password Password used in monitoring. Parameters Descriptions File Name File name to be used for FTP-EXTENDED monitor. 236 Installation and Configuration Guide - Volume 1 SIP messages can be transmitted over TCP or UDP. SIP messages are of two types: request messages and response messages. The following table summarizes the formats of these messages: The traffic in an SIP-based communication system is routed through dedicated devices and applications (entities). In a multimedia communication session, these entities exchange messages. Message Type Components Details Request Method Invite, Ack, Options, Bye, Cancel, Register Request URI Represents the subject, media type, or urgency of sessions initiated. The common format is: sip:user:password@host:port;uri- parameters?headers SIP version The SIP version being used Response SIP version The SIP version being used Status code A 3-digit integer result code. The possible values are: 1xx: Information Responses. For example: 180, Ringing 2xx: Successful Responses. For example: 200, OK 3xx: Redirection Responses. For example: 302, Moved Temporarily 4xx: Request Failures Responses. For example: 403, Forbidden 5xx: Server Failure Responses. For example: 504, Gateway Time-out 6xx: Global Failure Responses. For example: 600, Busy Everywhere Reason-phrase Textual description of the status code Chapter 4 Load Balancing 237 One of the most common scenarios for SIP is VoIP, where SIP is used to set up the session. The usage scenario described in the following section illustrates the role of the messages and entities in an SIP-based communication system. SIP mechanism User Agent (UA) is the entity that initiates the call. The UA can be an SIP softphone (a PC-based application), or an SIP phone. To initiate a call, the UA sends an INVITE request to the previously configured SIP Proxy server. The INVITE request contains the details of the destination, such as the destination URI and Call ID. In the figure, the UA (Caller A) sends an INVITE request to Proxy A. When the proxy server receives the INVITE request, it sends a 100 (Trying) response to the UA that initiated the call. It also performs a DNS lookup to locate the SIP proxy server of the destination domain. After the SIP proxy server of the destination domain is located, the SIP proxy at the source domain sends the INVITE request to it. Here, Proxy A sends a 100 (Trying) response to Caller A and an INVITE request to Proxy B. When the SIP proxy server of the destination domain receives the INVITE request from the SIP proxy server of the source domain, it responds with a 100 (Trying) response. It then sends the INVITE request to the destination UA. In this case, Proxy B sends a 100 (Trying) response to Proxy A and an INVITE request to Caller B. 238 Installation and Configuration Guide - Volume 1 When the destination UA receives the INVITE request, it alerts Caller B and responds with a 180 (ringing) response. This response is routed back to the source UA through the proxies. When caller B accepts the call, the destination UA responds with a 200 (OK) response. This implies that caller B has answered the call. This response is routed back to the source UA via the proxies. After the call is set up, the UAs communicate directly without the proxies. The following table describes the entities of an SIP-based communication system and their roles. You can configure the NetScaler to load balance SIP requests to a group of SIP proxy servers. To do this, you need to create an LB vserver with the LB method set to Call-ID hash, then bind to it the services representing the SIP proxies. You must configure the SIP proxies so that they do not add private IP addresses or private domains to the SIP header/payload. SIP proxies must add a domain name to the SIP header that resolves to the IP address of the SIP vserver. Also, the SIP proxies must communicate with a common database to share registration information. This section describes the role of the NetScaler when configured to perform SIP load balancing in the two most commonly used topologies: • One-arm direct server return (DSR) mode • Inline DSR mode For more information about DSR mode, see the section “Configuring Load Balancing in Direct Server Return Mode” on page 295. Entity Role User Agent (UA) SIP User Agents generate requests and respond to incoming requests. A UA that generates requests is known as a User Agent Client (UAC). The UA that responds to requests is known as the User Agent Server (UAS). In the preceding example, Caller A was the UAC and Caller B was the UAS. Proxy Server Proxies receive and route SIP requests based on the URI. They can selectively rewrite parts of the request message before forwarding it. They also handle registrations, invitations to UAs, and apply call policies. Redirect Server Redirect servers send routing information to the SIP proxy servers. Registrar Server Registrar servers provide location information to UAs and proxy servers. Back-to-Back User Agent (B2BUA) Back-to-Back User Agents (B2BUA) are combination of UAS and UAC. Chapter 4 Load Balancing 239 Understanding SIP in One-armDSR Mode In DSR mode, the NetScaler receives SIP requests from the UAs, and routes the requests to the appropriate SIP proxy using the LB method. The SIP proxies send the responses to the destination SIP proxies, bypassing the NetScaler as illustrated in the following figure. SIP in one-armmode The flow of requests and responses in this scenario is as follows: 1. The UA, Caller A, sends an INVITE request to the NetScaler. The NetScaler, using the LB method, routes the request to Proxy 2. 2. Proxy 2 receives the INVITE request from the NetScaler and responds with a 100 (Trying) message. 3. Proxy 2 performs a DNS lookup to obtain the IP address of the destination SIP proxy at domainB.com. It then sends the INVITE request to the destination proxy. 4. The destination proxy responds with a 100 (Trying) message and sends the INVITE request to the destination UA, Caller B. The destination UA, Caller B, begins to ring and responds with a 180 (Ringing) message. This message is sent to Caller A through the NetScaler and the Proxy 2. After the user accepts the call, Caller B responds with a 200 (OK) message that is propagated to Caller A via the NetScaler and the Proxy 2. 5. After Caller B accepts the call, the UAs (Caller A and Caller B) communicate independently. 240 Installation and Configuration Guide - Volume 1 Understanding SIP in Inline DSR Mode In inline DSR mode, the NetScaler is placed between the router and the SIP proxy, as illustrated in the following figure. SIP in inline mode The flow of requests and responses is as follows: 1. The UA, Caller A, sends an INVITE request to the NetScaler. The NetScaler, based on the LB method, routes the request to Proxy 2. 2. Proxy 2 receives the INVITE request from the NetScaler and responds with a 100 (Trying) message. 3. Proxy 2 performs a DNS lookup to obtain the IP address of the destination SIP proxy at domainb.com. It then propagates the INVITE request to the destination proxy through the NetScaler. 4. the NetScaler performs RNAT, replaces the source IP address in the INVITE request with the NAT IP address, and forwards the INVITE request to the destination SIP proxy. 5. The destination proxy responds with a 100 (Trying) message and sends the INVITE request to the destination UA, Caller B. The destination UA, Caller B, begins to ring and responds with a 180 (Ringing) message. This message is sent to Caller A through the NetScaler and the Proxy 2. After the user accepts the call, Caller B responds with a 200 (OK) message that is propagated to Caller A via the NetScaler and the Proxy 2. Chapter 4 Load Balancing 241 6. After the user accepts the call, the UAs (Caller A and Caller B) communicate independently. To monitor SIP services, use the parameters as described in the following table. To configure prebuilt monitors to check the state of SIP server, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type SIP. Monitoring RADIUS Services The RADIUS monitor periodically checks the state of the RADIUS server using the RADIUS protocol. The NetScaler sends the RADIUS packets to the RADIUS server. The RADIUS server authenticates the RADIUS clients using the authentication information in the RADIUS database. Based on the authentication, the RADIUS server sends the response to the NetScaler. The following are the expected responses from the RADIUS server: • If the client and the server have a similar configuration, the server must send an Access-Accept response. The response code for Access-Accept is 2. This is the default code that the NetScaler uses. • If there is a mismatch in the username, password, or secret key, the server sends an Access-Reject response. The response code for Access-Reject is 3. To monitor RADIUS services, use the parameters as described in the following table. Parameters Descriptions Maximum Forwards SIP packet max-forwards. Default value: 1 Minimum value: 0 Maximum value: 255. SIP Method SIP method to be used for the query. Possible values: OPTIONS, INVITE, REGISTER Default value: OPTIONS. SIP URI SIP method string, sent to the server. For example “OPTIONS sip:sip.test.” SIP Register URI SIP user to be registered. Parameters Descriptions User Name Username on the RADIUS/NNTP/FTP/FTP-EXTENDED/MYSQL/POP3 server. This user name is used in the probe. Password Password used in monitoring RADIUS/NNTP/FTP/FTP- EXTENDED/MYSQL/POP3/LDAP servers. RADIUS Key The shared secret key value that the RADIUS server uses during client authentication. 242 Installation and Configuration Guide - Volume 1 You must perform the following configurations in the RADIUS server: 1. Add the username and password of the client to the database where the RADIUS daemon searches for authentication. 2. Add the IP address and secret key of the client to the respective RADIUS database. 3. Add the IP addresses that originate from the RADIUS packets to the RADIUS database. If the NetScaler has more than one Mapped IP, or if SNIP is used, you must add the same secret key for all of the IP addresses. If the client IP address is not added into the database, the server discards the packets. The RADIUS server can send an access-reject response for any mismatch in username, password, or secret key. To configure prebuilt monitors to check the state of RADIUS server, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type RADIUS. Monitoring DNS Services The DNS monitors use the DNS protocol to determine the state of the DNS server. The DNS monitor sends a DNS query to the server that resolves the query to an IP address. The resolved IP address is then checked against the list of previously configured IP addresses. The IP address list can contain a maximum of five IP addresses. RADIUS NAS ID The NAS-ID that is encapsulated in the payload when an access request is made. RADIUS NA SIP The IP address that is encapsulated in the payload when an access-request is made. When radNASip is not configured, the NetScaler sends the Mapped IP Address (MIP) to the RADIUS server as the NAS-IP-Address. Parameters Descriptions Chapter 4 Load Balancing 243 If the resolved IP address matches at least one of the IP addresses in the IP address list, the DNS service is marked as up. If the resolved IP does not match any of the IP addresses in the list, the DNS service is marked as down. To monitor DNS services, use the parameters as described in the following table. To configure prebuilt monitors to check the state of the DNS server, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type DNS. Monitoring LDAP Services LDAP monitors use the LDAP protocol to determine the state of the services. The LDAP monitors authenticate and send a query to the LDAP server to locate an entity in the LDAP server. The LDAP monitors determine the state of the LDAP services using the response of the LDAP server. The LDAP monitors can specify a location (using the Base DN parameter) in the directory hierarchy where the LDAP server starts the query. You can also specify an attribute of the target entity. The LDAP server uses the fields that the monitor provides to search for the target entity. If the search is successful, the health check is considered good and the service is marked up. If the LDAP server does not locate the entry, a failure message is sent to the LDAP monitors and the service is marked down. To monitor LDAP services, use the parameters as described in the following table. Parameters Descriptions Query The DNS query (domain name) sent to the DNS service that is being monitored. Default value: “\007” If the DNS query succeeds, the service is marked as up otherwise it is marked as down. For a reverse monitor, if the DNS query succeeds, the service is marked as down otherwise it is marked as up. If no response is received, the service is marked as down. Query Type The type of DNS query that is sent. Possible values: Address, Zone. IP Address List of IP addresses that are checked against the response to the DNS monitoring probe. Applicable only to the DNS monitors. Parameters Descriptions Base DN Base name for the LDAP monitor from where the LDAP search must start. If the LDAP server is running locally, the default value of base is dc=netscaler, dc=com. Bind DN BDN name for the LDAP monitor. Filter Filter for the LDAP monitor. 244 Installation and Configuration Guide - Volume 1 To configure prebuilt monitors to check the state of the LDAP server, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type LDAP. Monitoring MySQL Services The MySQL monitor sends a query to the MySQL server to locate an entity in the database and determines the state of the MySQL services using the response from the database. If the entity exists in the database, the health check is considered good and the service is marked up. If the entity is not found in the database, a failure message is sent to the MySQL monitors and the service is marked down. To monitor MySQL services, use the parameters as described in the following table. To configure prebuilt monitors to check the state of the MySQL server, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type MySQL. Monitoring SNMP Services The SNMP monitor periodically probes the SNMP devices for performance and fault data. SNMP monitors check the SNMP agent running on an SNMP device. You must specify an OID (enterprise identification ID) when you configure the monitor. SNMP monitor sends a query to the SNMP devices for an OID and compares the response to the OID that you provide. The SNMP monitors determine the state of the SNMP services using the response. If the SNMP device does not have the OID that you specified, the SNMP monitor determines the state of the service as DOWN. To monitor SNMP services, use the parameters as described in the following table. Password Password used in monitoring LDAP servers. Attribute Attribute for the LDAP monitor. Parameters Descriptions Database Database that is used for the MYSQL monitor. SQL Query SQL query that is used for the MYSQL monitor. Parameters Descriptions SNMP OID OID that is used for the SNMP monitor. SNMP Community Community that is used for the SNMP monitor. SNMP Threshold Threshold that is used for the SNMP monitor. Parameters Descriptions Chapter 4 Load Balancing 245 To configure prebuilt monitors to check the state of SNMP device, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create a monitor of type SNMP. Monitoring NNTP Services The NNTP monitor periodically probes NNTP servers to determine the state of the NNTP servers. The NNTP monitor specifies the name and password to access the NNTP servers. The NNTP monitor connects to the NNTP server to check for the existence of a particular Internet newsgroup. If the newsgroup exists, the NNTP services are marked up. The NNTP monitor records the number of news items in the newsgroup. The monitor also can write a test message to the newsgroup. To monitor NNTP services, use the parameters as described in the following table. To configure prebuilt monitors to check the state of NNTP services, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create monitors of type NNTP. Monitoring POP3 Services The POP3 monitor uses the POP3 protocol to check the following: • A POP3 client opens a connection with a POP3 server. • The POP3 server responds with the correct codes. • The POP3 server responds within a required number of seconds. To monitor POP3 services, use the parameters as described in the following table. SNMP Version SNMP version that is used for load monitoring. The valid options for this parameter are V1 and V2. Parameters Descriptions User Name Username on the RADIUS/NNTP/FTP/FTP-EXTENDED/MYSQL/POP3 server. This user name is used in the probe. Password Password used in monitoring RADIUS/NNTP/FTP/FTP- EXTENDED/MYSQL/POP3/LDAP servers. Group Group name to be queried for NNTP monitor. Parameters Descriptions User Name Username POP3 server. This user name is used in the probe. Parameters Descriptions 246 Installation and Configuration Guide - Volume 1 To configure prebuilt monitors to check the state of POP3 services, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create monitors of type POP3. Monitoring SMTP Services The SMTP monitor uses the SMTP protocol to check the outgoing mail services. The servers use the SMTP protocol to deliver e-mail messages. The SMTP monitor connects to the SMTP server and conducts a sequence of handshakes to ensure that the server is operating correctly. To monitor SMTP services, use the parameters described in the following table. To configure prebuilt monitors to check the state of SMTP services, see “Configuring Monitors in an LB Setup” on page 223. You must provide values for the required parameters to create monitors of type SMTP. Monitoring Citrix Presentation Server Component You can use Citrix Presentation Server (CPS) component monitors to check various services of the CPS (XML-SERVICE, WEB Interface). These monitors are used in data centers where CPS systems are installed. To create monitors for XML-SERVICE and WEB Interface services, see “Creating Monitors” on page 224. Password Password used in monitoring POP3 servers. Script Name The path and name of the script to execute. Dispatcher IP Address The IP address of the dispatcher to which the probe is sent. Dispatcher Port The port of the dispatcher to which the probe is sent. Parameters Descriptions User Name Username SMTP server. This user name is used in the probe. Password Password used in monitoring SMTP servers. Script Name The path and name of the script to execute. Dispatcher IP Address The IP Address of the dispatcher to which the probe is sent. Dispatcher Port The port of the dispatcher to which the probe is sent. Parameters Descriptions Chapter 4 Load Balancing 247 Monitoring Applications and Services Using Customized Monitors This section describes the customized monitors, and how you can use them to check the state of applications and services. The NetScaler provides customized monitors that determine the state of services based on the load on the service, network traffic of the service, or user-defined scripts. The customized monitors are the load monitors, inline monitors, and user monitors. Customized monitors also allow you to define scripts and use the scripts to determine the state of the service. Configuring Inline Monitors Inline monitors analyze and probe the responses from the servers only when the client requests are sent to the server. They do not probe if the responses from the servers are deduced from traffic of the servers that are up. When there are no client requests to the server, inline monitors use the configured URL to probe the server as a regular HTTP monitor. The inline monitor is of type HTTP-INLINE and can only be configured to work with HTTP and HTTPS services. Inline monitors cannot be bound to HTTP or HTTPS GSLB remote or local services. These services represent vservers. Inline monitors also have a timeout value and a retry count on failure of probes. You can select one of the following action types that the NetScaler takes when a failure occurs: • NONE: No explicit action is taken. You can view the service and monitor, and the monitor indicates the number of current contiguous error responses and cumulative responses checked. • LOG: Logs the event in ns/syslog and displays the counters. • DOWN: Marks the service down and does not direct any traffic to the service. This setting breaks any persistent connections to the service. This action also logs the event and displays the counters. After the service is down, the service remains in the down state for the configured down time. After the down time, the configured URL is used to probe to check if the service is up. If the probe succeeds, the state of the service is changed to up. Traffic is directed to the service, and URL probes and traffic are sent to monitor to check the state of the service, as needed. To configure inline monitors, see “Configuring Monitors in an LB Setup” on page 223. 248 Installation and Configuration Guide - Volume 1 Configuring User Monitors User monitors extend the scope of custom monitors. You can create user monitors to track the health of customized applications and protocols that the NetScaler does not support originally. The following diagram illustrates how the user monitor works. User monitors As illustrated in the figure, a user monitor requires the following components. Dispatcher A dispatcher is a process on the NetScaler that listens to monitoring requests. It can be on the loopback IP address (127.0.0.1) and port 3013. These dispatchers are also known as internal dispatchers. A dispatcher may also be a Web server that supports CGI. Such dispatchers are also known as external dispatchers. They are used for custom scripts that do not run on the FreeBSD environment, such as .NET scripts. Note: Communication between the monitor and the dispatcher can use HTTPS if you enable the “secure” option on the monitor. However, the internal dispatcher understands only HTTP, and cannot use HTTPS. In a high availability setup, the dispatcher runs on both the primary and secondary NetScalers. The dispatcher remains inactive on the secondary NetScaler. Chapter 4 Load Balancing 249 Script The script is a program that sends out custom probes to the back-end entity and returns the response code to the dispatcher. The NetScaler is bundled with sample scripts for commonly used protocols. The scripts exist in the /nsconfig/monitors directory. If you want to add a new script, add the script in the location /nsconfig/ monitors. If you want to customize an existing script, copy the script with a new name and modify the script. For the scripts to function correctly, the name of the script file must not exceed 63 characters, and the maximum number of script arguments is 512. To debug the script, you must run it using the nsumon-debug.pl on the Command Line Interface (CLI). You must use the script name (with its arguments), IP address, and the port as the arguments of the nsumon-debug.pl script. Working of User Monitors To track the status of the server, the monitor sends an HTTP POST request to the configured dispatcher. This POST request contains the IP address and port of the server, and the script that must be executed. The dispatcher executes the script as a child process, with user-defined parameters (if any). Then, the script sends a probe to the server. The script sends the status of the probe (response code) to the dispatcher. The dispatcher converts the response code to an HTTP response and sends it to the monitor. Based on the HTTP response, the monitor marks the service as up or down. You can use user monitors with non-user monitors. During high CPU utilization, a non-user monitor enables faster detection of a server failure. If the user monitor probe times out during high CPU usage, the state of the service remains unchanged. The HTTP response codes are summarized in the following table. HTTP Response code Meaning 200 - success Probe success. 503 - service unavailable Probe failure. 404 - not found Script not found or cannot execute. 500 - Internal server error Internal error/resource constraints in dispatcher (out of memory, too many connections, unexpected system error, or too many processes). The service does not go down. 400 - bad request Error parsing HTTP request. 502 - bad gateway Error decoding script's response. 250 Installation and Configuration Guide - Volume 1 To monitor user service, use the parameters as described in the following table. You can use a custom user monitor with the internal dispatcher. Consider a scenario where you need to track the health of a server based on the presence of a file on the server. The following figure illustrates this scenario. Using a user monitor with the internal dispatcher A possible solution can be to use a Perl script that initiates an FTP session with the server and checks for the presence of the file. You can then create a user monitor that uses the Perl script. The NetScaler includes such a Perl script (nsftp.pl), located in the /nsconfig/monitors/ directory. Parameters Descriptions Script Name The path and name of the script to execute. Script Arguments The strings that are added in the POST data. They are copied to the request verbatim. Dispatcher IP Address The IP Address of the dispatcher to which the probe is sent. Dispatcher Port The port of the dispatcher to which the probe is sent. Chapter 4 Load Balancing 251 You can use a user monitor with an external dispatcher. Consider a scenario where you must track the health of a server based on the state of an SMTP service on another server. This scenario is illustrated in the following figure. Using a user monitor with an external dispatcher A possible solution would be to create a Perl script that checks the state of the SMTP service on the server. You can then create a user monitor that uses the Perl script. To configure user monitors, see “Configuring Monitors in an LB Setup” on page 223. 252 Installation and Configuration Guide - Volume 1 Configuring Load Monitors Load monitors use the SNMP polled OIDs to calculate the load on the services. The load monitor uses the IP address of the service or the destination IP address for polling. The load monitor sends an SNMP query to the server, specifying the OID for a metric. The metrics can be CPU, memory, or number of server connections. The server responds to the query with a metric value. The metric value in the response is compared with the threshold value. The NetScaler considers the service for load balancing only if the metric is less than the threshold value. The service with the lowest load value is considered for handling client requests. The following figure illustrates a load monitor configured for the services described in the basic LB setup, as discussed in the section “Configuring a Basic Setup” on page 114. Working of load monitors Note: The load monitor does not determine the state of the service. It only enables the NetScaler to consider the service for load balancing. To configure the load monitor, use the metric table parameter as described in the following table. Parameters Descriptions Metric Table Metric table to use for the metrics that must be bound. The maximum value is 99. Chapter 4 Load Balancing 253 To configure load monitors, see “Configuring Monitors in an LB Setup” on page 223. You must select the metric table to configure load monitors. The following sections describe the steps to configure metrics. Configuring Metrics for Load Assessments For load assessment, the load monitor considers server parameters known as metrics. These metrics are defined within the metric tables in the NetScaler. Metric tables can be of two types: • Local: By default, this table exists in the NetScaler. It consists of four metrics: connections, packets, response time, and bandwidth. The NetScaler specifies these metrics for a service, and SNMP queries are not originated for these services. These metrics cannot be changed. • Custom: A user-defined table. Each metric is associated with an object identifier (OID). By default, the NetScaler generates the following tables: • Netscaler • RADWARE • CISCO-CSS • LOCAL • FOUNDRY • ALTEON You can either add the NetScaler-generated metric tables, or you can add tables of your own choosing, as shown in the following table. The values in the metric table are provided only as examples. In an actual scenario, consider the real values for the metrics. Threshold Value for a Metric You can set the threshold value for each metric. The threshold value enables the NetScaler to select a service for load balancing, if the metric value for the service is less than the threshold value. The threshold value also determines the load on each service. Metric Name OIDs Weight Threshold CPU 1.2.3.4 2 70 Memory 4.5.6.7 3 80 Connections 5.6.7.8 4 90 254 Installation and Configuration Guide - Volume 1 Weight for a Metric To calculate the load for one or more metrics, you can assign a weight to each metric. The default weight is 1. The weight represents the priority given to each metric. If the weight is high, the priority is high. The NetScaler chooses a service based on the SOURCEIPDESTIP hash algorithm. Creating Metric Tables You can create metric tables to configure the metrics for load balancing. The metric table defines a set of metrics that determine the state of the server. To create metric table, use the Metric Table Name parameter as described in the following table. The following example describes the steps to create a metric table Table-Custom-1. To create a metric table using the configuration utility 1. In the navigation pane, expand Load Balancing and click Metric Tables. The Metric Tables page appears in the details pane. 2. Click Add. The Create Metric Table dialog box appears. 3. In the Metric Table Name text box, type the name of the metric table, for example, Table-Custom-1. 4. Click Create and click Close. The metric table you created appears in the Metric Tables page, as shown in the following figure. Metric table page Parameters Descriptions Metric Table Name The name of the metric table. This name must not exceed 31 characters. Chapter 4 Load Balancing 255 To create a metric table using the NetScaler command line At the NetScaler command prompt, type: add metricTable Table-Custom-1 Binding Metrics to Metric Tables You can bind each metric to a metric table. The metrics can be any SNMP OID. The load monitor uses the metrics bound to the metric table to calculate the load on the services. The following example describes the steps to bind the metric 1.3.6.1.4.1.5951.4.1.1.41.1.5 with SNMP OID 11 to the metric table Table-Custom-1. To bind metrics to a metric table using the configuration utility 1. In the navigation pane, expand Load Balancing and click Metric Tables. The Metric Tables page appears in the details pane. 2. Select the metric table to which you want to bind the metrics, for example, Table-Custom-1. 3. Click Open. The Configure Metric Table dialog box appears. 4. In the Metrics and SNMP OID text boxes, type metric and SNMP OID for the metric table, for example, 1.3.6.1.4.1.5951.4.1.1.41.1.5 and 11. 5. Click Add. The metric appears in the Bound Metrics list box. 6. Click OK. To bind metrics to a metric table using the NetScaler command line At the NetScaler command prompt, type: bind metricTable Table-Custom-1 1.3.6.1.4.1.5951.4.1.1.41.1.5 11 Removing a Metric Table The following example describes the steps to delete the metric table Table-Custom-1. To remove a metric table using the configuration utility 1. In the navigation pane, expand Load Balancing and click Metric Tables. The Metric Tables page appears in the details pane. 2. Select the metric table that you want to remove, for example, Table-Custom-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. 256 Installation and Configuration Guide - Volume 1 To remove a metric table using the NetScaler command line At the NetScaler command prompt, type: rm metricTable Table-Custom-1 Unbinding a Metric Table The following example describes the steps to unbind the metrics 1.3.6.1.4.1.5951.4.1.1.41.1.5 with SNMP OID 11 from the metric table. To unbind metrics from a metric table using the configuration utility 1. In the navigation pane, expand Load Balancing and click Metric Tables. The Metric Tables page appears in the details pane. 2. Select the metric table from which you want to unbind the metrics, for example, Table-Custom-1. 3. Click Open. The Configure Metric Table dialog box appears. 4. In the Bound Metrics list box, select the metrics that you want to unbind from the table, for example, 1.3.6.1.4.1.5951.4.1.1.41.1.5. 5. Click Remove and click OK. To unbind metrics from a metric table using the NetScaler command line At the NetScaler command prompt, type: unbind metricTable Table-Custom-1 1.3.6.1.4.1.5951.4.1.1.41.1.5 Viewing the Properties of a Metric Table You can view all the metric tables that are configured. You can view the details such as name and type of the metric tables to determine if the metric table is internal or configured. To view the metric tables using the configuration utility 1. In the navigation pane, expand Load Balancing and click Metric Tables. The Metric Tables page appears in the details pane. The details of the available metric table appear on this page. To view the metric tables using the NetScaler command line At the NetScaler command prompt, type: show metricTable Table-Custom-1 Chapter 4 Load Balancing 257 Configuring Support for Third-party Load Balancers Using SASP The Server Application State Protocol (SASP) allows the NetScaler to perform load balancing based on the weights of the services. A WLM (work load manager) agent runs on each of the servers and relays performance data to the EWLM. The EWLM (enterprise work load manager) uses this data to dynamically calculate the weight for each server. The EWLM uses the PUSH model to send the dynamically calculated weights to the NetScaler (because the NetScaler supports the PUSH model). The prerequisites for dynamic weight calculation are: • The EWLM is configured as an entity within the NetScaler. • A connection is established between the EWLM and the vserver. • The services bound to the vserver are registered in the EWLM. The following diagram shows how SASP facilitates load balancing decisions using the Group Workload Manager: SASP load balancing 258 Installation and Configuration Guide - Volume 1 Communication between the NetScaler and EWLM is achieved through a set of SASP messages. When the NetScaler is connected to the EWLM, a set l bst at e message is sent to the EWLM to indicate that the connection is established. After the connection is established, the NetScaler sends a registration message to the EWLM. This message conveys that all the services are registered with the EWLM. The EWLM responds with a registration success or failure message. A connection is established only when a vserver is bound to the WLM in the NetScaler. After all the services are registered, the EWLM starts sending weight data to the NetScaler using the sendweight message. The WLM that is connected to each of the services sends the weight messages to the EWLM, as shown in the figure above. The weight is calculated for the registered services only. the NetScaler waits for two minutes (default wait time) to receive the weight message from the EWLM. If the NetScaler receives the weight message within two minutes, the weight is dynamically calculated from the incoming weight message. If not, the NetScaler considers the user configured weights for making load balancing decisions. If a service is disabled in the NetScaler, a set member st at e message is sent to the EWLM conveying that the disabled service is not considered for load balancing. The NetScaler sends a deregistration message to the EWLM to deregister or remove the disabled service. The EWLM responds with a deregistration success or failure message. Chapter 4 Load Balancing 259 The following example describes the steps to bind the services Service-HTTP-1 and Service-HTTP-2 to the vserver Vserver-LB-1. Vserver-LB-1 forwards the client request to either of the two services Service-HTTP-1 or Service-HTTP-2. The NetScaler selects the service for each request using the Least Connections load balancing method. A workload manager Wlm-1 is created and bound to Vserver-LB-1. The following figure shows the LB entities and the values of the parameters. WLM entity model Creating Work Load Manager You can create a work load manager to dynamically calculate the load on each service. The NetScaler uses the load data to select services for load balancing. To create a work load manager, use the parameters described in the following table. Parameters Descriptions Name The unique name of the work load manager. This name must not exceed 31 characters. IP Address The IP address of the work load manager. LB unique identifier The unique identifier for the NetScaler to communicate to the work load manager. Port The port of the work load manager. The port number must be a positive number and must not exceed 65535. 260 Installation and Configuration Guide - Volume 1 The following example describes the steps to create the work load manager Wlm- 1 with IP address 10.102.29.30, and LB unique identifier 11. To create a work load manager using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. 2. Click Add. The Create Work Load Manager dialog box appears. 3. In the Name, IP Address, LB Unique Identifier, Port, and Keep Alive Timeout (minutes) text boxes, type the corresponding values, for example, Wlm-1, 10.102.29.30, 11, 80, and 2. 4. Click Create and click Close. The work load manager you created appears in the Work Load Managers page, as shown in the following figure. Work load manager page To create a work load manager using the NetScaler command line At the NetScaler command prompt, type: add lb wlm wlm-1 10.102.29.30 -LBUID 11 Binding Vserver to Work Load Manager The work load manager assigns weight to the service on which it runs. The NetScaler requires a connection to balance the load on the services. When you bind a vserver to a WLM, the connection is established and the NetScaler uses the vserver to balance the services. The following example describes the steps to bind the vserver Vserver-LB-1 to the work load manager Wlm-1. Chapter 4 Load Balancing 261 To bind a vserver to a work load manager using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. 2. Select the work load manager for which you want to bind the vserver, for example, Wlm-1. 3. Click Open. The Configure Work Load Manager dialog box appears. 4. Under Virtual Servers, in the Available list box, select the vserver that you want to bind to the work load manager, for example, Vserver-LB-1. 5. Click Add. Under Virtual Servers, Vserver-LB-1 appears in the Configured list box. 6. Click OK. To bind a vserver to a work load manager using the NetScaler command line At the NetScaler command prompt, type: bind lb wlm wlm-1 Vserver-LB-1 Modifying the Work Load Manager The NetScaler periodically probes the work load manger. You can modify the time interval that the NetScaler uses to probe the WLM. To modify the time period, use the keep alive timeout parameter as described in the following table. The following example describes the steps to set the keep alive timeout value of Wlm-1 to 20 minutes. To modify a work load manager using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. 2. Select the workload manager that you want to modify, for example, Wlm-1. 3. Click Open. The Configure Work Load Manager dialog box appears. 4. In the Keep Alive Timeout (minutes) text box, type the timeout value, for example, 20. 5. Click OK. Parameters Descriptions Keep Alive Timeout The idle time period after which the NetScaler probes the work load manager. The value ranges from 2 to 1440 minutes. The default value is 2 minutes and the maximum value is 1440 minutes. 262 Installation and Configuration Guide - Volume 1 To modify a work load manager using the NetScaler command line At the NetScaler command prompt, type: set lb wlm wlm-1 -KATimeout 20 Managing the Work Load Manager This section describes how to manage the work load manager after you create it in the LB setup. Managing the work load manager allows the NetScaler to use the manually configured weights on the services. You can perform tasks such as removing or unbinding the work load manager from the vserver. Removing a Work Load Manager You must remove a work load manager when you no longer require the NetScaler to dynamically calculate the load on the service. When the work load manager is removed the NetScaler uses the manually configured weights of the service to balance the load. The following example describes the steps to remove the work load manager Wlm-1. To remove a work load manager using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. 2. Select the workload manager that you want to remove, for example, Wlm-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a work load manager using the NetScaler command line At the NetScaler command prompt, type: rm lb wlm wlm-1 Unbinding a Work Load Manager When you unbind a work load manager from a vserver, the NetScaler uses the manually configured weights of the service to select the service. The following example describes the steps to unbind the vserver Vserver-LB-1 from the work load manager Wlm-1. To unbind a vserver from a work load manager using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. Chapter 4 Load Balancing 263 2. Select the workload manager for which you want to unbind a vserver, for example, Wlm-1. 3. Click Open. The Configure Work Load Manager dialog box appears. 4. Under Virtual Servers, in the Configured box, select the vserver that you want to unbind from the work load manager, for example, Vserver-LB-1. 5. Click Remove. Under Virtual Servers, Vserver-LB-1 appears in the Available box. 6. Click OK. To unbind a vserver from a work load manager using the NetScaler command line At the NetScaler command prompt, type: unbind lb wlm wlm-1 vservre-LB-1 Viewing a Work Load Manager You can view the name, IP address, state, port, LB unique identifier, and keep alive timeout of the configured work load mangers. Viewing the details of the configuration is useful to check your setup. To view work load managers using the configuration utility 1. In the navigation pane, expand Load Balancing and click Work Load Managers. The Work Load Managers page appears in the details pane. The details of the available work load managers appear in the Work Load Managers page. To view work load managers using the NetScaler command line At the NetScaler command prompt, type: show lb wlm wlm-1 Managing a Large Scale Deployment This section describes procedures to create groups of vservers and services, to create a range of vservers and services, and to translate or mask vserver and back- end server IP addresses. Creating groups of vservers and services enables you to easily manage the LB setup. You can perform several tasks on such groups, including setting persistence for the group of vservers, binding the monitors for the service groups, and so forth. 264 Installation and Configuration Guide - Volume 1 Creating a range of vservers and services of identical type in a single procedure improves the speed of the LB configuration. You can also use this option to avoid repeating steps when you create services or vservers of the same type. Translating or masking an IP address enables you to take down servers and make changes to your infrastructure without extensive reconfiguration of your server and virtual server definitions. Topics include: • Configuring a Range of Vservers and Services • Configuring Service Groups Configuring a Range of Vservers and Services When you configure load balancing, you can also create ranges of vservers and services. This procedure allows you to configure load balancing more quickly than if you configure vservers and services individually. For example, you can use a single procedure to create three virtual servers using port 80: vserverx, vservery, and vserverz, at IPs 10.102.29.31, 10.102.29.32, and 10.102.29.33. When more than one argument uses a range, all of the ranges must be of the same size. For example, when adding vserverx and vservery, you must use two ranges, each containing two elements: [x-y] and [1-2]. If your configuration has a large number of virtual servers, you can add them all to the configuration at once and save considerable time. The following are the types of ranges you can specify when adding services and vservers to your configuration: • Numeric ranges. Instead of typing a single number, you can type a range that includes the numbers in the range; in this case, 20, 21, 22, 23, 24, and 25. In the following example, a range of servers is created, with IP addresses 10.102.29.[30-35]. The IP addresses within the range are included; in this case, 10.102.29.30, 10.102.29.31, 10.102.29.32, 10.102.29.33, 10.102.29.34, and 10.102.29.35. • Alphabetic ranges. Instead of typing a literal letter, you can substitute a range for any single letter, for example, [C-G]. This results in all letters in the range being included, in this case C, E, F, and G. For example, if you have three vservers named vserverx, vservery, and vserverz, instead of configuring them separately, you can type vserver [x-z] to configure them all. Chapter 4 Load Balancing 265 Note: For this procedure to work, the IP addresses of the services must be consecutive. To create a range of vservers and services, use the parameters as described in the following table. The following example describes the steps to create a range of vservers from 10.102.29.30 to 10.102.29.35. To create range of vservers using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Click Add Range. The Create Virtual Server (Load Balancing) - Range dialog box appears. 3. In the Name Prefix, IP Address Range, and Port text boxes, type the vserver name, IP address range, and port, for example, vserver, 10.102.29.30, and 80. 4. In the text box next to the IP Address Range text box, type the last value of the last vserver, for example, 35. 5. In the Protocol drop-down list box, select the protocol type, for example, HTTP. 6. Click Create and click Close. The range of vservers you created appears in the Load Balancing Virtual Servers page. To create range of vservers using the NetScaler command line At the NetScaler command prompt, type: add lb vserver Vserver-LB-2 http -range 5 10.102.29.30 80 The following example describes the steps to create a range of services from 10.102.29.102 to 10.102.29.104 Parameters Description Name Allow for the creation and manipulation of a range of vservers. Ranges specify a consecutive array of entities. The command will return an error if the ranges differ. IP Address range Specifies an address range. When adding a range of entities, dependent arguments must specify a matching range. 266 Installation and Configuration Guide - Volume 1 To create range of services using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Click Add Range. The Create Services (Range) dialog box appears. 3. In the IP Address Range and Port text boxes, type the start value of the IP address range and the port, for example, 10.102.29.102, and 80. 4. In the text box next to the IP Address Range text box, type the last value of the last service, for example, 104. 5. In the Protocol drop- down list box, select the protocol type, for example, HTTP. 6. Click Create and click Close. The range of services you created appears in the Services page. To create range of vservers using the NetScaler command line At the NetScaler command prompt, type: add lb vserver Vserver-LB-2 http -range 5 10.102.29.30 80 Configuring Service Groups Configuring service groups allows you to manage multiple servers with ease. A service group is a representation of one or more services. You can add servers and services to the service groups. You can create, modify, and manage service groups. Note: Domain-based and transparent service groups are not supported. Creating Service Groups You can create a service group and add services to it. You can also modify, monitor, and remove service groups. The NetScaler allows you to configure 4096 service groups. To create a service group, use the parameters in the following table. Parameter Description Name The name of the service group. The service name must not exceed 31 characters. This parameter cannot be changed Service Type This parameter determines the behavior of the service group. The valid options are: HTTP, TCP, FTP, UDP, SSL, SSL_TCP, SSL_BRIDGE, NNTP, DNS, and ANY Chapter 4 Load Balancing 267 The following example describes the steps to create a service group Service-Group-1 of type HTTP. To create a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Click Add. The Create Service Group dialog box appears. 3. In the Service Group Name text box, type name of the service group, for example, Service-Group-1. 4. In the Protocol list, select the protocol type, for example, HTTP. 5. Click Create and click Close. The service group you created appears in the Service Groups page, as shown in the following figure. Service group page To create a service group using the NetScaler command line At the NetScaler command prompt, type: add servicegroup Service-Group-1 HTTP Binding a Service Group to a Vserver When you bind a service group to a vserver, the member services are bound to the vserver. The following example describes the steps to bind the service group Service-Group-1 to a vserver Vserver-LB-1. To bind a service group to a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 268 Installation and Configuration Guide - Volume 1 2. Select the vserver to which you want to bind the service group, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Services Groups tab. The service groups appear in the Services Groups tab. 5. Select the Active check box next to the service group that you want to bind to the vserver, for example, Service-Group-1. 6. Click OK. To bind a service group to a vserver using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-LB-1 Service-Group-1 Binding a Member to a Service Group Adding servers to a service group enables the service group to manage the servers. You can add the servers to a service group using the IP addresses or names of the servers. When you add a server to the service group using the IP address, the server is created with the IP address as its name. The following example describes the steps to add a server with IP address 10.102.29.30, and port 80 to the service group Service-Group-1. To add members to a service group using IP address (using the configuration utility) 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group for which you want to bind members, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. Under Specify Member (s), select the IP Based radio button. 5. In the IP Address text box, type the IP address, for example, 10.102.29.30. 6. In the Port text box type the port, for example, 80 7. Click Add. The service appears under Configured Members. 8. Click OK. To add members to a service group using IP address (using the NetScaler command line) At the NetScaler command prompt, type: Chapter 4 Load Balancing 269 bind servicegroup Service-Group-1 10.102.29.30 80 You can also bind a server to the service group using the name of the server. The following example describes the steps to bind a member Server-50 to the service group Service-Group-1. To bind members to a service group using names of servers (using the configuration utility) 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group for which you want to bind members, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. Under Specify Member (s), select the Server Based radio button. 5. In the Server Name list, select a server, for example, Server-50. 6. In the Port text box type the port, for example, 80. 7. Click Add. The service appears under Configured Members. 8. Click OK. To bind members to a service group using names of servers (using the NetScaler command line) At the NetScaler command prompt, type: bind servicegroup Service-Group-1 Server-50 80 Binding a Monitor to a Service Group You can bind and unbind monitors from the service groups. Monitors periodically probe the servers in the service group and update the state of the service groups. The following example describes the steps to bind the ping monitor to the service group Service-Group-1. To bind monitor to a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group for which you want to bind monitors, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. Click the Monitors tab. 270 Installation and Configuration Guide - Volume 1 5. Under Available, in the Monitors list box, select a monitor type, for example, ping. 6. Click Add. The service appears under Configured. 7. Click OK. To bind monitor to a service group using the NetScaler command line At the NetScaler command prompt, type: bind mon monitor-HTTP-1 Service-Group-1 Modifying a Service Group You can modify attributes of service group members. You can set several attributes of the service group, such as: maximum client, sure connect, and compression. The attributes are set on the individual servers in the service group. You cannot set parameters on the service group such as: transport information (IP address and port), weight, and server ID. To modify a service group, use the parameters described in the following table. Parameters Descriptions Cache Type The cache server supports the cache type option. The valid options are: TRANSPARENT, REVERSE, and FORWARD. Maximum Client The maximum number of open connections to each service in the service group. The default value is 0. The maximum value is 4294967294. Maximum Requests The maximum number of requests that can be sent over a persistent connection to a service in the service group. The default value is 0. The minimum value is 0. The maximum value is 65535. Cacheable Specifies whether a vserver used in the NetScaler 9000 load balancing or content switching feature routes a request to the vserver (used in transparent cache redirection) on the same NetScaler 9000 before sending it to the configured servers. The vserver used for transparent cache redirection determines if the request is directed to the cache servers or the configured servers. Do not specify this argument if a cache type is specified. By default, this argument is disabled. The valid options are: yes and no. The default value is no. Client IP Enables or disables insertion of the Client IP header for services in the service group. The valid options for this parameter are: enabled and disabled. The default value is disabled. Client IP Header The client IP header. If client IP insertion is enabled and the client IP header is not specified, then the NetScaler sets the value of the Client IP header. Chapter 4 Load Balancing 271 The following example describes the steps to set the maximum client parameter to 5000 for the service group Service-Group-1. Note: Any parameter you set on the service group is applied to the member servers in the group, and not to individual services. Use Source IP Enables or disables use of the client IP address as the source IP address while connecting to the server. By default, the NetScaler uses a mapped IP address for its server connection. However, with this option, you can tell the Netscaler 9000 to use the client's IP address when it communicates with the server. Possible values: yes and no. Default value: no. SC The state of SureConnect on this service group. This parameter is supported for legacy purposes only; it has no effect, and the only valid value is OFF. Possible values: ON and OFF. Default value: OFF. SP Whether surge protection needs to be enabled on this service group. Possible values: ON and OFF. Default value: OFF. Client Timeout The idle time in seconds after which the client connection is terminated. Default value: 180. Maximum value: 31536000. Server Timeout The idle time in seconds after which the server connection is terminated. The default value is 360. The maximum value is 31536000. CKA The state of the Client Keep-Alive feature for the services in the service group. The valid options for this parameter are: yes and no. The default value is no. TCPB The state of the TCP Buffering feature for the services in the service group. The valid options for this parameter are: yes and no. The default value is no. CMP The state of the HTTP Compression feature for the services in the service group. The valid options for this parameter are: yes and no. The default value is no. Maximum Bandwidth A positive integer that identifies the maximum bandwidth in kilobits allowed for the services in the service group. Monitor Threshold The monitoring threshold. The default value is 0. The minimum value is 0 and maximum value is 65535. State The state of the service group after it is added. The valid options for this parameter are: enabled and disabled. The default value is enabled. DownStateFlush Perform delayed cleanup of connections on this service group. The valid options for this parameter are: enabled and disabled. The default value is enabled. Parameters Descriptions 272 Installation and Configuration Guide - Volume 1 To modify a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group that you want to modify, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. Click the Advanced tab. 5. In the Max Clients text box, type the maximum number of clients, for example, 5000. 6. Click OK. To modify a service group using the NetScaler command line At the NetScaler command prompt, type: set servicegroup Service-Group-1 -maxClient 5000 Managing Service Groups This section describes how to manage the service groups after you create them in the LB setup. Managing the service group enables you to change the settings of the services in the service group. You can perform tasks such as enabling, disabling, and removing service groups. You can also unbind members from the service group. Removing a Service Group When you remove a service group, the servers bound to the group retain their individual settings and continue to exist on the NetScaler. The following example describes the steps to delete the service group Service-Group-1. To remove a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group that you want to remove, for example, Service-Group-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a service group using the NetScaler command line At the NetScaler command prompt, type: rm servicegroup Service-Group-1 Chapter 4 Load Balancing 273 Unbinding a Member froma Service Group When you unbind a member from the service group, the attributes set on the service group do not apply to the members. The member services retain their individual settings and continue to exist on the NetScaler. The following example describes the steps to unbind a server with IP address 10.102.29.30, and port 80 from the service group Service-Group-1. To unbind members from a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group from which you want to unbind members, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. In the Configured Members list box, select a service, for example, 10.102.29.30. 5. Click Remove and click OK. To unbind members from a service group using the NetScaler command line At the NetScaler command prompt, type: unbind servicegroup Service-Group-1 10.102.29.30 80 Unbinding a Service Group froma Vserver When you unbind a service group from a vserver, the member services are unbound from the vserver and continue to exist on the NetScaler. The following example describes the steps to unbind the service group Service-Group-1 from a vserver Vserver-LB-1. To unbind a service group from a vserver using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver from which you want to unbind the service group, for example, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Services Groups tab. The service groups appear in the Services Groups tab. 274 Installation and Configuration Guide - Volume 1 5. Clear the Active check box next to the service group that you want to unbind from the vserver, for example, Service-Group-1. 6. Click OK. To unbind a service group from a vserver using the NetScaler command line At the NetScaler command prompt, type: unbind lb vserver Vserver-LB-1 Service-Group-1 Unbinding Monitors fromService Groups When you unbind a monitor from a service group, the monitor no longer probes the individual services that constitute the group. The following example describes the steps to unbind the monitor monitor-HTTP-1 from the service group Service-Group-1. To unbind a monitor from a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group from which you want to unbind the monitor, for example, Service-Group-1. 3. Click Open. The Configure Service Group dialog box appears. 4. In the Configure Service Group dialog box, click the Monitors tab. 5. Under Configured, select the monitor that you want to unbind from the service group, for example, monitor-HTTP-1. 6. Click Remove. The monitor appears under Available in the Monitors list box. 7. Click OK. To unbind a monitor from a service group using the NetScaler command line At the NetScaler command prompt, type: unbind mon monitor-HTTP-1 Service-Group-1 Enabling and Disabling a Service Group When you enable a service group and the servers, the services belonging to the service group are enabled. Similarly, when a service belonging to a service group is enabled, the service group and the service are enabled. By default, the service groups are enabled. The following example describes the steps to disable the service group Service-Group-1 after a wait time of 30 seconds. Chapter 4 Load Balancing 275 To disable a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group that you want to disable, for example, Service-Group-1. 3. Click Disable. The Wait Time pop-up window appears. 4. In the Wait Time pop-up window type the wait time value, for example, 30. 5. Click Enter. To disable a service group using the NetScaler command line At the NetScaler command prompt, type: disable servicegroup Service-Group-1 The following example describes the steps to enable the service group Service-Group-1. To enable a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group that you want to enable, for example, Service-Group-1. 3. Click Enable. The Enable pop-up window appears. 4. Click Yes. To enable a service group using the NetScaler command line At the NetScaler command prompt, type: enable servicegroup Service-Group-1 Viewing the Properties of a Service Group You can view the following settings of the configured service groups: name, IP address, state, protocol, maximum client connections, maximum requests per connection, maximum bandwidth, and monitor threshold. Viewing the details of the configuration can be helpful for troubleshooting your configuration. The following example describes the steps to view the service group Service-Group-1. 276 Installation and Configuration Guide - Volume 1 To view the properties of a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. This pane displays the details of all the available service groups. To view the properties of a service group using the NetScaler command line At the NetScaler command prompt, type: show servicegroup Service-Group-1 Viewing Service Group Statistics You can view the following data using the service group statistics link: rate of requests, responses, request bytes, response bytes, and so on. The NetScaler uses the statistics of a service group (rate of requests, responses, and so on) to balance the load on the services. The following example describes the steps to view the statistics of a service group Service-Group-1. To view the statistics of a service group using the configuration utility 1. In the navigation pane, expand Load Balancing and click Service Groups. The Service Groups page appears in the details pane. 2. Select the service group for which statistics you want to view, for example, Service-Group-1. 3. Click Statistics. The statistics of the service group you selected appears in a new window. To view the statistics of a service group using the NetScaler command line At the NetScaler command prompt, type: stat servicegroup Service-Group-1 Translating the IP Address of a Domain-Based Server To simplify maintenance on a NetScaler and on the domain-based servers that are connected to it, you can configure IP address masks and translation IP addresses. These functions work together to parse incoming DNS packets and substitute a new IP address for a DNS-resolved IP address. When configured for a domain-based server, IP address translation enables the NetScaler to locate an alternate server IP address in the event that you take the server down for maintenance or if you make any other infrastructure changes that affect the server. Chapter 4 Load Balancing 277 When configuring the mask, you must use standard IP mask values (a power of two, minus one) and zeros, for example, 255.255.0.0. Note that non-zero values are only permitted in the starting octets. When you configure a translation IP for a server, you create a 1:1 correspondence between a server IP address and an alternate server that shares leading or trailing octets in its IP address. The mask blocks particular octets in the original server's IP address. The DNS-resolved IP address is transformed to a new IP address by applying the translation IP and the translation mask. For example, you can configure a translation IP address of 10.20.0.0 and a translation mask of 255.255.0.0. If a DNS-resolved IP address for a server is 40.50.27.3, this address is transformed to 10.20.27.3. In this case, the translation IP address supplies the first two octets of the new address, and the mask passes through the last two octets from the original IP address. Note that the reference to the original IP address, as resolved by DNS, is lost. Monitors for all services to which the server is bound also report on the transformed IP address. When configuring a translation IP address for a domain-based server, you specify a mask and an IP address to which the DNS-resolved IP address is to be translated. The following table summarizes the parameters for configuring a server IP address mask:. Translation IP Parameters Parameters Descriptions Server Name (serverName) The name of the domain-based server. IP Address / Domain Name (serverDomainName) The server's domain name (for example, www.example.com). Note that for IP address translation, the domain name is required. Translation IP Address (translationIP) The IP address (relevant octets only) to which the resolved ip for the server needs to be translated. (for example, 11.12.0.0). Translation Mask (translationMask) The mask determines the number of bits in the translation IP address that are to be considered when applying the transformation. For example, if you want an original server IP of 10.20.30.40 to be translated to 11.12.30.40, you could specify the mask 255.255.0.0. 278 Installation and Configuration Guide - Volume 1 Note: Translation of the IP address is only possible for domain-based servers. You cannot use this feature for IP-based servers. Note also that the address pattern can be based on IPv4 addresses only. To configure a translation IP address for a server using the configuration utility 1. In the navigation pane, expand Load Balancing and click Servers. 2. Click Add. 3. In theServer Name field, enter a name. 4. In theIP Address / Domain Name field, enter the server's domain name. Do not enter an IP address if you are entering a mask. 5. In theTranslation IP Address field, enter the IP address of a server on the same subnet. 6. In theTranslation Mask field, enter a valid mask (for example, 255.255.0.0). 7. Click Create. To configure a translation IP address for a server using the NetScaler command line At the NetScaler command prompt, type: add server serverName serverDomainName -translationIp translationIPAddress -translationMask netMask -state ENABLED|DISABLED Example add server myMaskedServer www.example.com -translationIp 10.10.10.10 -translationMask 255.255.0.0 -state ENABLED Masking a Virtual Server IP Address You can configure a mask and a pattern instead of a fixed IP address for a virtual server. This enables traffic that is directed to any of several IP addresses to be rerouted to a particular virtual server. For example, you can configure a mask that allows the first three octets of an IP address to be variable, so that traffic to 111.11.11.198, 22.22.22.198, and 33.33.33.198 are all sent to the same virtual server. Chapter 4 Load Balancing 279 By configuring a mask for a virtual server IP address, you can avoid reconfiguration of your virtual servers due to a change in routing or another infrastructure change. The mask allows the traffic to continue to flow without extensive reconfiguration of your virtual servers. The mask for a virtual server IP address works somewhat differently from the IP pattern definition for a server as described in “Translating the IP Address of a Domain-Based Server” on page 276. For a virtual server IP address mask, a non- zero mask is interpreted as an octet that is considered (in the case of a server, the non-zero value is blocked). Additionally, for a virtual server IP address mask, either leading or trailing values can be considered. If the virtual server IP address mask considers values from the left of the IP address, this is known as a forward mask. If the mask considers the values to the right side of the address, this is known as a reverse mask. Note that the NetScaler evaluates all forward mask virtual servers before evaluating reverse mask virtual servers. When masking a virtual server IP address, you also need to create an IP address pattern for matching incoming traffic with the correct virtual server. When the NetScaler receives an incoming IP packet, it matches the destination IP address in the packet with the bits that are considered in the IP address pattern, and after it finds a match, it applies the IP address mask to construct the final destination IP address. The following is an example: • Destination IP address in the incoming packet: 10.102.27.189 • IP address pattern: 10.102.0.0 • IP mask: 255.255.0.0 • Constructed (final) destination IP address: 10.102.27.189. The first 16 bits in the original destination IP address match the IP address pattern for this virtual server, so this incoming packet can be considered by this virtual server. If a destination IP address matches the IP patterns in more than one virtual server, the longest match takes precedence. The following is an example: • Virtual Server 1: IP pattern 10.10.0.0, IP mask 255.255.0.0 • Virtual Server 2: IP pattern 10.10.10.0, IP mask 255.255.255.0 • Destination IP address in the packet: 10.10.10.45. • Selected virtual server: Virtual Server 2. This virtual server has more bits that are considered when compared to Virtual Server 1. Note that ports are also considered if a tie-breaker is required. 280 Installation and Configuration Guide - Volume 1 The following table summarizes the parameters for a virtual server IP address mask: Note: You cannot convert a virtual server with a fixed IP address to a pattern- based virtual server, and you cannot convert a pattern-based virtual server to one with a fixed IP address. To configure a virtual server IP address mask using the configuration utility 1. In the navigation pane, expand Load Balancing and click Virtual Servers. 2. Click Add. 3. In the Create Virtual Server dialog box, enter a name in the Name field. 4. In the Protocol field, select HTTP. 5. In the Port field, enter the listen port. 6. In the IP Pattern field, enter a pattern for an IP address (for example, 11.11.0.0). The fixed part of the pattern must be entered in contiguous octets. Enter zeros for the pattern values that can vary in the IP address. 7. In the IP Mask field, enter a standard network mask (for example, 255.255.0.0). Use non-zero mask values for the portion of the IP address that constitutes the fixed part of the pattern. Virtual Server IP Address Mask Parameters Parameters Descriptions Name (name) The name of the load balancing virtual server. Protocol (ht t p) A value of HTTP. Port (port) The listen port for the virtual server. Pattern Based (Configuration utility only.) Option to select if the virtual server is to be pattern-based. IP Pattern (- i pPat t er n) The IP address pattern for the virtual server. You must supply either the initial or the trailing octets (for example, 11.11.00.00). IP Mask (- i pMask) A network mask for the IP address. Non-zero values indicate the IP address octets that are to be passed through. For example, for an IP address pattern of 11.11.00.00, you might specify a mask of 255.255.0.0. Chapter 4 Load Balancing 281 To configure a virtual server IP address mask using the NetScaler command line At the NetScaler command prompt, type: add lb vserver lbVserverName http -ipPattern ipAddressPattern - ipMask ipMask listenPort Examples Pattern matching based on prefix octets: add lb vserver myLBVserver http -ippattern 10.102.0.0 -ipmask 255.255.0.0 80 Pattern matching based on trailing octets: add lb vserver myLBVserver1 http -ippattern 0.0.22.74 -ipmask 0.0.255.255 80 Modify a pattern-based virtual server: set lb vserver myLBVserver1 -ippattern 0.0.22.74 -ipmask 0.0.255.255 Configuring Load Balancing for Commonly Used Protocols This section describes the procedures to configure a functional LB setup for common applications, including: load balancing for FTP servers, DNS servers, SSL servers. The procedures discussed include creating the entities of the LB setup and configuring appropriate monitors. Topics include: • Load Balancing for a Group of FTP Servers • Load Balancing a Group of SSL Servers • Load Balancing DNS Servers • Load Balancing with Domain-Name Based Services • Load Balancing a Group of SIP Servers 282 Installation and Configuration Guide - Volume 1 Load Balancing for a Group of FTP Servers the NetScaler distributes client requests across the FTP servers to balance the load on the FTP servers. When you initiate a control connection to the FTP server, the NetScaler selects the FTP server and forwards incoming requests to it. The FTP server opens a data connection to the client for information exchange. In this way the NetScaler balances the load on the FTP servers. The following figure describes the topology of an LB configuration to load balance a group of FTP servers. Basic LB topology for FTP servers In the figure, the services Service-FTP-1, Service-FTP-2, and Service-FTP-3 are bound to the vserver Vserver-LB-1. Vserver-LB-1 forwards the connection request to one of the services using the Least Connections load balancing method. Subsequent requests are forwarded to the service that the NetScaler initially selected for load balancing. The following table lists the names and values of the basic entities configured on the NetScaler. Entity Type Name IP Address Port Protocol Vserver Vserver-LB-1 10.102.29.25 21 FTP Services Service-FTP-1 10.102.29.21 21 FTP Service-FTP-2 10.102.29.22 21 FTP Service-FTP-3 10.102.29.23 21 FTP Monitors FTP None None None Chapter 4 Load Balancing 283 The following figure shows the LB entities, and the values of the parameters that need to be configured on the NetScaler. Load balancing FTP servers entity model To transfer a file, you must open a control connection to the FTP server. The NetScaler selects an FTP server using the load balancing principle, and opens a control connection to the selected FTP server. The FTP server also opens a data connection that you can use to access the required file. The NetScaler can also provide a passive FTP option to access the FTP servers from outside a firewall. When you use this option and initiate a control connection to the FTP server, the FTP server also initiates a control connection. You can then initiate a data connection to transfer a file through the firewall. The following sections describe the tasks required to implement this scenario: 1. Configuring a basic LB setup to load balance FTP server 2. Configuring FTP monitors Configuring a Basic LB Setup to Load Balance FTP Servers To create services and vservers of type FTP, follow the procedure described in the section “Configuring a Basic Setup” on page 114. Name the entities and set the parameters to the values described in the Name and Value columns of the table in the previous section. 284 Installation and Configuration Guide - Volume 1 Configuring FTP Monitors When you configure a basic LB setup, a default monitor is bound to the services. Next, bind the FTP monitor to the services by following the procedure described in the section “Binding Monitors to Services” on page 225. To configure FTP monitors using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Click Add. The Create Monitor dialog box appears. 3. In the Name and Interval text boxes, type monitor-FTP-1 and 340. 4. In the Type list, select FTP. In the Username and Password text boxes, type User. 5. Click Create and click Close. The monitor monitor-FTP-1 that you created appears in the Monitors Page. To configure FTP monitors using the NetScaler command line At the NetScaler command prompt, type: add lb monitor monitor-FTP-1 FTP -interval 360 -userName User -password User Load Balancing a Group of SSL Servers To load balance a group of SSL servers, see the SSL chapter of Installation and Configuration guide. Chapter 4 Load Balancing 285 Load Balancing DNS Servers the NetScaler load balances DNS requests across the DNS servers. When you request DNS resolution of a domain name, the NetScaler uses the load balancing principle to select the DNS server. The DNS server then resolves the domain name and returns the IP address as the response. The NetScaler can also cache the responses, and can use the cached information to forward subsequent requests. Load balancing the DNS servers improves the response of the DNS to client requests. For more information about DNS and caching DNS records, see the “DNS” chapter of the Installation and Configuration Guide. The following figure describes the topology of an LB configuration that load balances a group of DNS servers. Basic LB topology for DNS servers In the figure, the services Service-DNS-1, Service-DNS-2, and Service-DNS-3 are bound to the vserver Vserver-LB-1. The vserver Vserver-LB-1 forwards the client request to one of the services using the least connections load balancing method. The following table lists the names and values of the basic entities configured on the NetScaler. Entity Type Name IP Address Port Protocol Vserver Vserver-LB-1 10.102.29.13 53 DNS 286 Installation and Configuration Guide - Volume 1 The following figure shows the LB entities and the values of the parameters that need to be configured on the NetScaler. Load balancing DNS servers entity model The following sections describe the tasks to implement this scenario. The tasks include the following: 1. Configuring a basic LB setup to load balance DNS servers 2. Monitoring DNS Servers Configuring a Basic LB Setup Load Balance DNS Servers Using the procedure described in the section “Configuring a Basic Setup” on page 114, create services and vservers of type, DNS. Name the entities, and set the parameters to the values described in the Name and Value columns of the table in the previous section. Services Service-DNS-1 10.102.29.14 53 DNS Service-DNS-2 10.102.29.15 53 DNS Service-DNS-3 10.102.29.16 53 DNS Monitors monitor-DNS-1 None None None Entity Type Name IP Address Port Protocol Chapter 4 Load Balancing 287 Monitoring DNS Servers When you configure a basic LB setup, the default ping monitor is bound to the services. To bind the DNS monitor to the services, you can also use the procedure described in the section “Binding Monitors to Services” on page 225. The following procedure describes the steps to create a monitor monitor-DNS-1 that maps a domain name to the IP address based on a query. To configure DNS monitors using the configuration utility 1. In the navigation pane, expand Load Balancing and click Monitors. The Monitors page appears in the details pane. 2. Click Add. The Create Monitor dialog box appears. 3. In the Name and Interval text boxes, type monitor-DNS-1 and 340. 4. In the Type list, select DNS. 5. In the Query text box, type www.citrix.com and in the Query Type list box, select ADDRESS. 6. In the text box below the Query Type list box, type 10.102.29.66, and click Add. The new IP appears in the IP Address box. 7. Click Create and click Close. The monitor-DNS-1 you created appears in the Monitors page. To configure DNS monitors using the NetScaler command line At the NetScaler command prompt, type: add lb monitor monitor-DNS-1 DNS -query www.citrix.com -queryType Address -IPAddress 10.102.29.66 Load Balancing with Domain-Name Based Services To create a service in a basic LB setup, you must provide an IP address. Alternatively, you can create a server with a domain name. The server name (domain name) can be resolved using a name server, or by adding an authoritative DNS record (A record) on the NetScaler. When you change the IP address of the server, the name server resolves the domain name to the new IP address. The monitor runs a health check on the new IP address, and updates the service IP address only when the IP address is found to be healthy. 288 Installation and Configuration Guide - Volume 1 Note: When you change the IP address of the server, the corresponding service is marked down for the first client request. The name server resolves the service IP address to the changed IP address for the subsequent requests. The domain-name based services have the following restrictions: • The maximum domain name length is 255 characters. • The Maximum Client parameter is used to configure a service that represents the domain name-based server. For example, a maxClient of 1000 is set for the services bound to a vserver. When the connection count at the vserver reaches 2000, the DNS resolver changes the IP address of the services. But because the connection counter on the service is not reset, the vserver cannot take any new connections until all the old connections are closed. • When the IP address of the service changes, persistence is difficult to maintain. • If the domain name resolution fails due to a timeout, the NetScaler uses the old information (IP address). • When monitoring detects that a service is down, the NetScaler performs a DNS resolution on the service (representing the domain name-based server) to obtain a new IP address. • Statistics are collected on a service, and are not reset when the IP address changes. • If a DNS resolution returns a code of “name error” (3), the NetScaler marks the service down and changes the IP address to zero. Chapter 4 Load Balancing 289 the NetScaler distributes client requests across the domain name-based services to balance the load on the servers. When the NetScaler receives a request for a service, it selects the target service. In this way, the NetScaler balances the load on the services. The following figure describes the topology of an LB configuration that load balances a group of domain-name based servers (DBS). Basic LB topology for DBS servers The services Service-HTTP-1, Service-HTTP-2, and Service-HTTP-3 are bound to the vserver Vserver-LB-1. The vserver Vserver-LB-1 uses the least connections method to choose the service. The IP address of the service is resolved using the name server Vserver-LB-2. The following table lists the names and values of the basic entities configured on the NetScaler. Entity Type Name IP Address Port Protocol Vserver Vserver-LB-1 10.102.29.17 80 HTTP Vserver-LB-2 10.102.29.20 53 DNS Servers server-1 10.102.29.18 80 HTTP server-2 www.citrix.com 80 HTTP Services Service-HTTP-1 server-1 80 HTTP Service-HTTP-2 server-2 80 HTTP Service-HTTP-2 10.102.29.19 80 HTTP Monitors Default None None None 290 Installation and Configuration Guide - Volume 1 The following figure shows the LB entities and the values of the parameters that need to be configured on the NetScaler. Load balancing DBS servers entity model The following sections explain the following procedures required to implement the scenario described above: 1. Configuring a basic LB setup to load balance a domain name-based server 2. Configuring a name server Configuring a Basic LB Setup Using the procedure described in the section “Configuring a Basic Setup” on page 114, create the services and the vservers of type HTTP. Name the entities and set the parameters under the Name and Value columns in the table in the previous section. Adding a Name Server You can add, remove, enable, and disable external name servers. You can create a name server by specifying its IP address, or you can configure an existing virtual server as the name server. Name Server None 10.102.29.19 None None Entity Type Name IP Address Port Protocol Chapter 4 Load Balancing 291 To add a name server using the configuration utility 1. In the navigation pane, expand DNS and click Name Servers. The Name Servers page appears in the details pane. 2. Click Add. The Create Name Server dialog box appears. 3. Select the DNS Virtual Server radio button. 4. In the DNS Virtual Server drop-down list, select the name server, for example, Vserver-LB-2. Note: Click New if you want to create a new load balancing vserver. The Create Virtual Server (Load Balancing) dialog box appears. 5. Click Create and click Close. To add a name server using the NetScaler command line At the NetScaler command prompt, type: add dns nameServer Vserver-LB-2 You can also add an authoritative name server that resolves the domain name to an IP address. For more information about configuring name servers, see the DNS chapter of the Installation and Configuration Guide. 292 Installation and Configuration Guide - Volume 1 Load Balancing a Group of SIP Servers This section describes how the NetScaler load balances SIP servers. The NetScaler balances the load on the SIP servers by distributing client requests across the SIP servers. Load balancing the SIP servers improves the performance of Internet telephony. You can also enable RPORT on the NetScaler. For more information about RPORT, see the “Advanced Network Configuration” chapter of the Installation and Configuration Guide. The following figure describes the topology of an LB setup configured to load balance a group of SIP servers. SIP load balancing In the sample scenario in this section, the services Service-SIP-1 and Service-SIP-2 are bound to the vserver Vserver-LB-1. The following table lists the names and values of the entities that you need to configure on the NetScaler in inline mode. Entity Type Name IP Address Port Protocol Vserver Vserver-LB-1 10.102.29.65 80 SIP Services Service-SIP-1 10.102.29.10 80 SIP Service-SIP-2 10.102.29.20 80 SIP Monitors Default None 80 SIP Chapter 4 Load Balancing 293 The following figure shows the LB entities and the values of the parameters to be configured on the NetScaler. Load balancing SIP servers entity model The following sections describe the procedures to implement this scenario: 1. Configuring a basic LB setup to load balance SIP servers 2. Configuring RNAT 3. Configuring SIP parameters Configuring a Basic LB Setup to Load Balance SIP Servers Using the procedure described in the section “Configuring a Basic Setup” on page 114, create services and vservers of type SIP. Name the entities and set the parameters using the values described in the Name and Value columns of the table in the previous section. Configuring RNAT The following procedure describes the steps to configure RNAT. To configure RNAT using the configuration utility 1. In the navigation pane expand Network, and expand Routing. Click Routes. The Routes page appears in the details pane. 2. Click Add. The Create Route dialog box appears. 294 Installation and Configuration Guide - Volume 1 3. In the Network, Netmask, and Gateway IP text boxes type 10.102.29.0, 255.255.255.0, and 10.102.29.50. 4. Click Create and click Close. To configure RNAT using the NetScaler command line At the NetScaler command prompt, type: add route 10.102.29.0 255.255.255.0 10.102.29.50 Configuring SIP Parameters When you enable RNAT, the NetScaler sends SIP responses to the IP address and port that the client uses to send the request. The NetScaler also adds the RPORT tag in the VIA header of the message. The NetScaler compares the values of the source and destination ports of the request packets with the RNAT source port and RNAT destination port. If one of the values matches, the NetScaler updates the VIA header with the RPORT setting. You must enable this setting when RPORT is not configured on either of the clients. The following procedure describes the steps to configure SIP parameters. To configure SIP parameters using the configuration utility 1. In the navigation pane, click Load Balancing. The Load Balancing page appears in the details pane. 2. Click SIP Parameters. The Set SIP Parameters dialog box appears. 3. In RNAT Source Port text box, type 5060. 4. Select the Enable Add RPort VIP check box. 5. Click OK. To configure SIP parameters using the NetScaler command line At the NetScaler command prompt, type: set sipParameters -rnatSrcPort 5060 Chapter 4 Load Balancing 295 Configuring Load Balancing in Commonly Used Deployment Scenarios This section describes the procedures to configure a functional LB setup for some common deployment scenarios. You can follow the instructions in this section to implement load balancing in a direct return server setup, one-arm setup, or inline setup (two-arm). The procedures described in this section include creating the entities of the LB setup, and configuring the appropriate path for requests and response flow. Topics include: • Configuring Load Balancing in Direct Server Return Mode • Configuring Load Balancing in Direct Server Return mode using IP Tunneling • Configuring Load Balancing in Direct Server Return mode using TOS • Configuring Load Balancing in One-arm Mode • Configuring Load Balancing in the Inline Mode • Load Balancing of Intrusion Detection System Servers Configuring Load Balancing in Direct Server Return Mode Load balancing in DSR mode allows the server to respond to clients directly using a return path that does not flow through the NetScaler. However, the NetScaler can continue to perform health checks on the application ports. In a high-data volume environment, sending the server traffic directly to the client in DSR mode increases the overall packet handling capacity of the NetScaler, because the packets do not flow through the NetScaler. DSR mode supports the following topologies: • The NetScaler in one-arm mode • The NetScaler in two-arm mode (also called inline mode) The following sections describe the topology and configuration of one-arm and two-arm modes. Note the following: • The NetScaler ages out sessions based on idle timeout • Because the NetScaler does not proxy TCP connection (that is it does not send SYN-ACK to the client), it does not completely shut out syn-attack. By using the SYN packet rate filter, you can control the rate of SYNs to the 296 Installation and Configuration Guide - Volume 1 server. To control the rate of SYNs, set a threshold for the rate of SYNs. To get protection from SYN attack, configure the NetScaler to proxy TCP connection but that would require the reverse traffic to flow through the NetScaler. In the example scenario, the services Service-ANY-1, Service-ANY-2, and Service-ANY-3 are created and bound to the vserver Vserver-LB-1. The vserver load balances the client request to a service, and the service responds to clients directly, bypassing the NetScaler. The following table lists the names and values of the entities configured on the NetScaler in DSR mode. The following figure shows the LB entities and values of the parameters to be configured on the NetScaler. Entity model for load balancing in DSR mode The following sections describe the tasks required to implement this scenario: 1. Enabling MAC based forwarding mode Entity Type Name IP Address Protocol Vserver Vserver-LB-1 10.102.29.94 ANY Services Service-ANY-1 10.102.29.91 ANY Service-ANY-2 10.102.29.92 ANY Service-ANY-3 10.102.29.93 ANY Monitors TCP None None Chapter 4 Load Balancing 297 2. Configuring a basic LB setup 3. Customizing the LB setup for DSR mode Enabling MAC-Based Forwarding For the NetScaler to function in DSR mode, the destination IP in the client request is unchanged. The destination MAC is changed to the selected server MAC address. This setting enables the server to determine the client MAC address for forwarding requests to the client while bypassing the server. The following procedure describes the steps to enable MAC-based forwarding. To enable MAC-based forwarding using the configuration utility 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Select the MAC Based Forwarding check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable MAC-based forwarding using the NetScaler command line At the NetScaler command prompt, type: enable ns mode MAC Configuring a Basic LB Setup in DSR Mode Using the procedure described in the section “Configuring a Basic Setup” on page 114, create the services and the vservers. Name the entities and set the parameters using the values described in the Name and Value columns of the table in the previous section. Customizing the LB setup in DSR Mode After you configure the LB setup, you must customize the LB setup for DSR mode. You need to set the redirection mode to allow the server to determine the client MAC address for forwarding responses and bypass the NetScaler. The following sections describe the procedures to configure the LB setup for DSR mode. 298 Installation and Configuration Guide - Volume 1 Configuring the LB Method and Redirection Mode After you create an LB setup, you must configure the correct LB method, for example, the SOURCEIP Hash method with a sessionless vserver. The NetScaler does not maintain the state of the connection. You must also configure MAC- based redirection as described in the following procedure. To configure LB method and redirection mode for a sessionless vserver using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Method and Persistence tab. Under LB Method, select SOURCEIP Hash. 5. Click the Advanced tab. Under Redirection Mode, select the MAC Based radio button. 6. Select the Sessionless check box and click OK. To configure LB method and redirection mode for a sessionless vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -lbMethod SourceIPHash -m MAC -sessionless enabled Enabling USIP Mode To determine the client IP address, you need to enable the USIP mode on the service. The service uses this address to forward the responses. The following procedure describes the steps to enable use source IP mode for each service bound to the vserver. To set a service to use source IP address using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service, Service-ANY-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Use Source IP check box. Chapter 4 Load Balancing 299 6. Click OK. 7. Repeat steps 1-5 for the services Service-ANY-2 and Service-ANY-3. To set a service to use source IP address using the NetScaler command line At the NetScaler command prompt, type: set service Service-ANY-1 -usip yes Note: For USIP to function correctly, you must set it globally. For more information about configuring USIP globally, see the “Basic Network Configuration” chapter of the Installation and Configuration Guide. Configuring LINUX Servers in DSR Mode This section provides steps to configure the NetScaler in DSR mode. To configure LINUX server in DSR mode 1. Create a loop back interface with the NetScalers VIP (10.101.4.94) on all the servers participating in the DSR cluster. 2. At the Linux OS prompt, type the following commands: i f conf i g dummy0 up i f conf i g dummy0: 0 i net 10. 101. 4. 94 net mask 255. 255. 255. 255 up echo 1 > / pr oc/ sys/ net / i pv4/ conf / dummy0/ ar p_i gnor e echo 2 > / pr oc/ sys/ net / i pv4/ conf / dummy0/ ar p_announce Configuring Load Balancing in Direct Server Return mode using IP Tunneling Load Balancing in DSR mode enables a server to directly respond to the client using a return path that does not flow through the NetScaler. When an IP packet is sent from a client to the NetScaler, the destination IP address of the packet is the NetScaler VIP (Virtual IP address). If the back-end server is on the same network as the NetScaler, the NetScaler forwards the packets after processing it. However, if the NetScaler and the back-end servers are not on the same network and are connected via a router, the NetScaler forwards the packet to the router after encapsulating it with additional header information for the router. The encapsulated information enables the router to route the packet to the appropriate back-end server. If that information was not added, the packet is re- routed to the NetScaler as the destination IP is the NetScaler VIP, resulting in a loop. 300 Installation and Configuration Guide - Volume 1 In this scenario, the NetScaler is the encapsulator i.e., it adds the additional outer header information to the packet and sends it to the router via the tunnels. The back-end servers’ decapsulate the data packet as illustrated in the diagram. NS as an Encapsulator In the example, the services, Service-ANY-1, Service-ANY-2, and Service-ANY- 3 are created and bound to the vserver, Vserver-LB-1. The vserver load balances the client request to a service, and the service responds to clients directly, bypassing the NetScaler. The following table lists the names and values of the entities configured on the NetScaler in DSR mode. The following sections describe the tasks required to implement this scenario: Entity Type Name IP Address Protocol Vserver Vserver-LB-1 206.86.120.50 ANY Services Service-ANY-1 10.10.10.70 ANY Service-ANY-2 10.10.10.80 ANY Service-ANY-3 10.10.10.90 ANY Monitors PING None None Chapter 4 Load Balancing 301 1. Configuring a basic LB setup 2. Customizing the LB setup for DSR mode on Layer 3 • Configuring the Re-direction Mode • Configuring the Monitor for Tunneling • Customize the IP Tunnel Parameter Globally Configuring a basic LB Setup for Layer3 Using the procedure described in the section “Configuring a Basic Setup” on page 158, create the services and the vservers. Name the entities and set the parameters using the values described in the Name and Value columns of the table specified. Customizing the LB Setup for DSR mode on Layer3 After you configure the LB setup, you must customize the LB setup for DSR mode by configuring the redirection mode, and the monitor. The following sections describe the procedures to configure the LB setup for DSR mode. Configuring the Re-direction mode for DSR Layer 3 To customize the LB setup for DSR mode, you must first set the redirection mode to allow the server to decapsulate the data packet and then respond directly to the client and bypass the NetScaler. To configure the redirection mode for the vserver using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Virtual Servers. 2. In the Load Balancing Virtual Servers page, select the vserver, Vserver- LB-1 and click Open. 3. In the Configure Virtual Server (Load Balancing) dialog box, click the Advanced tab. Under Redirection Mode, select the IP Tunnel Based radio button. 4. Click OK. To configure the redirection mode for the vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver VserverName -m Value 302 Installation and Configuration Guide - Volume 1 Example set lb vserver Vserver-LB-1 -m IPTunnel Configuring the Transparent Monitor for Tunneling After specifying the re-direction mode, you must enable the NetScaler to transparently monitor the server. This enables the NetScaler to probe packets having the destination IP set to VIP and tunnel them to the server. To configure the transparent monitor for tunneling using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Monitors. 2. In the Monitors page, select the monitor (tcp, for instance), and click Add. 3. In the Create Monitor dialog box, in the Name and Destination IP textboxes, enter the monitor name and the destination IP address (for example, PING1 and 206.86.120.50). 4. In the Type list, select the type of monitor (for example, PING). 5. To configure the monitor to be transparent, select the Transparent check box. 6. To configure the monitor for tunneling, select the IP Tunnel check box. 7. Click OK. To configure the transparent monitor for tunneling using the NetScaler command line At the NetScaler command prompt, type: add monitor MonitorName Type -destip DestinationIP Address – IPTunnel Value Example add monitor mon1 PING –destip 206.86.120.50 –IPTunnel Yes Customizing the IP Tunnel globally After specifying the re-direction mode, and the monitor, you can make some global changes that impact the behavior of the NetScaler. For more information on how to customize the IP tunnel globally, see Customizing the IP Tunnel globally. Chapter 4 Load Balancing 303 Configuring Load Balancing in Direct Server Return mode using TOS Load Balancing in DSR mode enables a server to directly respond to the client using a return path that does not flow through the NetScaler. For example, when an IP packet is sent from a client to the NetScaler, the destination IP address of the packet is the NetScaler VIP (Virtual IP address). When the back-end server is not on the same network and is connected via a router, the NetScaler forwards the packet to the router after modifying the header. The destination IP address of the packet, the NetScaler VIP, is modified to specify the back-end server IP address. The differentiated services (DS) field of the packet is set to an encoded value of the VIP. Differentiated services (DS), previously known as TOS (Type of Service), is a field that is part of the packet header and is used by upper layer protocols for optimizing the path for a packet. The DS information is used by the back-end servers to derive the VIP from the encoded VIP. In this scenario, the NetScaler adds the additional DS information to the packet and sends it to the back-end server. The back-end servers' then respond directly to the client bypassing the NetScaler as illustrated in the diagram. 304 Installation and Configuration Guide - Volume 1 Before you configure TOS The TOS feature is specifically customized for a controlled environment. Following are the features of the controlled environment. • The environment must not have any stateful devices such as stateful Firewall, TCP gateways in the path between the NetScaler and the back-end servers. • Routers at all the entry points of the network must remove the DS field from all incoming packets to make sure that the server does not confuse other traffic with a value in the DS field. • Each server can have only 63 VIPs. • Care must be taken to make sure that the intermediate router does not send out an ICMP error message regarding fragmentation. The client will not understand the message as the source ip address will be the IP address of the back-end server and not the VIP of the NetScaler. • TOS is valid only for IP based servers. In the example, the services, Service-ANY-1 is created and bound to the vserver, Vserver-LB-1. The vserver load balances the client request to a service, and the service responds to clients directly, bypassing the NetScaler. The following table lists the names and values of the entities configured on the NetScaler in DSR mode. The following sections describe the tasks required to implement this scenario: 1. Configuring a basic LB setup 2. Customizing the LB setup for DSR mode on Layer 3 • Configuring the Re-direction Mode • Configuring the Monitor for TOS (Optional) • Configuring the Back-end Servers for DSR Mode Entity Type Name IP Address Protocol Vserver Vserver-LB-1 10.102.33.91 ANY Services Service-ANY-1 10.102.100.44 ANY Monitors PING None None Chapter 4 Load Balancing 305 Configuring a basic LB Setup for Layer3 Using the procedure described in the section “Configuring Basic Load Balancing” on page 113, create the services and the vservers. Name the entities and set the parameters using the values described in the Name and Value columns of the table specified. Customizing the LB Setup for DSR mode on Layer3 After you configure the LB setup, you must customize the LB setup for DSR mode by configuring the redirection mode. You can also optionally configure a monitor to transparently check the health of the application. The following sections describe the procedures to configure the LB setup for DSR mode. Configuring the Re-direction mode for DSR Layer 3 To customize the LB setup for DSR mode, you must first set the redirection mode to allow the server to decapsulate the data packet and then respond directly to the client and bypass the NetScaler. To configure the redirection mode for the vserver using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Virtual Servers. 2. In the Load Balancing Virtual Servers page, select the vserver, Vserver- LB-1 and click Open. 3. In the Configure Virtual Server (Load Balancing) dialog box, click the Advanced tab. Under Redirection Mode, select the TOS radio button. 4. In the TOS Id textbox, enter a value for the TOS ID, (for example, 3). 5. Click OK. To configure the redirection mode for the vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver VserverName -m Value -tosId Value Example set lb vserver Vserver-LB-1 -m TOS -tosId 3 Configuring the Transparent Monitor for TOS After specifying the re-direction mode, you can optionally enable the NetScaler to transparently monitor the server. This enables the NetScaler to transparently monitor the application running on VIP (alias IP) on the back-end servers. 306 Installation and Configuration Guide - Volume 1 To configure the transparent monitor for TOS using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Monitors. 2. In the Monitors page, select the monitor (tcp, for instance), and click Add. 3. In the Create Monitor dialog box, in the Name and Destination IP textboxes, enter the monitor name and the destination IP address (for example, PING and 10.102.33.91). 4. In the Type list, select the type of monitor (for example, PING). 5. To configure the monitor for TOS, select the TOS check box. 6. In the TOS Id textbox, enter the same TOS Id that you had entered for the vserver (for example, 3.) 7. Click OK. To configure the transparent monitor for TOS using the NetScaler command line At the NetScaler command prompt, type: add monitor Moni t or Name Type - destip Dest i nat i onI P Addr ess - tos Val ue - tosId Val ue Example add monitor mon1 PING -destip 10.102.33.91 -tos Yes -tosId 3 Configuring the Back-end Servers for DSR Mode This section provides steps to configure the back-end servers (Linux, for example) in DSR mode. To configure LINUX server in DSR mode 1. Create a loop back interface with the NetScaler VIP (10.102.33.91) on all the servers participating in the DSR cluster. At t he Li nux OS pr ompt , t ype t he f ol l owi ng commands: echo 1 > / pr oc/ sys/ net / i pv4/ conf / et h0/ ar p_i gnor e echo 2 > / pr oc/ sys/ net / i pv4/ conf / et h0/ ar p_announce r out e add - host 10. 102. 33. 91 gw 10. 102. 100. 44 2. Run the software that re-maps the TOS id to VIP. Chapter 4 Load Balancing 307 Note: Add the correct mappings to the software before running it. In the preceding commands, the LINUX server uses eth0 to connect to the network. When you use this command, type the name of the interface that your LINUX server uses to connect to the network. Configuring Load Balancing in One-armMode In a one-arm setup, you connect the NetScaler to the network through a single interface. This is one of the simplest deployment scenarios, where the router, the servers and the NetScaler are connected to the same switch. The client can access the server directly, bypassing the NetScaler, if the client knows the IP address of the server. Client requests at the switch are forwarded to the NetScaler, and the NetScaler selects the server. This is shown in the following topology diagram. Load balancing in one-armmode In the example scenario, the services Service-ANY-1, Service-ANY-2, and Service-ANY-3 are created and bound to the vserver Vserver-LB-1. The vserver load balances the client request to a service. The following table lists the names and values of the entities configured on the NetScaler in one-arm mode. Entity Type Name IP Address Protocol Vserver Vserver-LB-1 10.102.29.94 ANY 308 Installation and Configuration Guide - Volume 1 The following figure shows the LB entities and values of the parameters that need to be configured on the NetScaler. Entity model for load balancing in one-armmode To configure an LB setup in one-arm mode, use the procedure described in the section “Configuring a Basic Setup” on page 114 and create services and vservers. Name the entities and set the parameters to the values as described in the Name and Value columns of the table in the previous section. Services Service-ANY-1 10.102.29.91 ANY Service-ANY-2 10.102.29.92 ANY Service-ANY-3 10.102.29.93 ANY Monitors TCP None None Entity Type Name IP Address Protocol Chapter 4 Load Balancing 309 Configuring Load Balancing in the Inline Mode In a two-arm setup, you deploy the NetScaler to the network through more than one interface. In the two-arm setup, the NetScaler is connected between the servers and the client. Traffic from the clients passes through the NetScaler to access the server. Client requests at the switch are forwarded to the NetScaler, and the NetScaler selects the server. This is shown in the following topology diagram. Load Balancing in Inline Mode The configuration and the entity diagram for inline mode are the same as described in the section “Configuring Load Balancing in One-arm Mode” on page 307. 310 Installation and Configuration Guide - Volume 1 Load Balancing of Intrusion Detection System Servers The NetScaler supports load balancing of the Intrusion Detection System (IDS) servers. The servers and clients are connected through a switch that has port mirroring enabled. The client sends requests to the server. Because port mirroring is enabled on the switch, these packets are copied or sent to the vserver port. The NetScaler then selects an IDS server based on the LB method and balances the load on it as shown in the following topology diagram. Load balancing IDS servers Currently, the NetScaler supports load balancing of passive IDS devices only. The following section describes load balancing of IDS servers (illustrated in the preceding diagram): 1. The client request is routed to the server. A switch with a mirroring port enabled forwards these packets to the server. The source IP address is the IP address of the client, and the destination IP address is the IP address of the server. The source MAC address is the MAC address of the router and the destination MAC address is the MAC address of the server. 2. The traffic that flows through the switch is mirrored to the NetScaler. The NetScaler uses the layer 3 information (source IP address and destination IP address) to forward the packet for balancing the load on IDS servers. An IDS server is selected and the packet is sent to the server without changing the source IP address or destination IP address, but the source MAC address Chapter 4 Load Balancing 311 and the destination MAC address are changed to the MAC address of the selected IDS server. Note: You can configure the SRCIPHASH, DESTIPHASH, or SRCIPDESTIPHASH load balancing methods. It is recommended to use the SRCIPDESTIPHASH method because the packets flowing from the client to a service on the NetScaler must go to a single IDS server. Suppose, Service-ANY-1, Service-ANY-2, and Service-ANY-3 are created and bound to Vserver-LB-1. The vserver balances the load on the services. The following table lists the names and values of the entities configured on the NetScaler. Note: You can configure the NetScaler to balance the load on IDS servers in the inline mode or in the one-arm mode. Entity Type Name IP Address Port Protocol Vserver Vserver-LB-1 * * ANY Services Service-ANY-1 10.102.29.101 * ANY Service-ANY-2 10.102.29.102 * ANY Service-ANY-3 10.102.29.103 * ANY Monitors Ping None None None 312 Installation and Configuration Guide - Volume 1 The following figure shows the LB entities and values of the parameters to be configured on the NetScaler. Entity model for load balancing IDS servers The following sections describe the tasks required to implement this scenario: 1. Enabling MAC based forwarding mode 2. Configuring a basic LB setup 3. Customizing the LB setup for IDS mode Enabling MAC-Based Forwarding The following procedure describes the steps to enable MAC-based forwarding. Note: You must disable the layer 2 and layer 3 modes on the NetScaler for the IDS load balancing. To enable MAC-based forwarding using the configuration utility 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under Modes & Features, click modes. The Configure Modes dialog box appears. 3. Select the MAC Based Forwarding check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. Chapter 4 Load Balancing 313 5. Click Yes. To enable MAC-based forwarding using the NetScaler command line At the NetScaler command prompt, type: enable ns mode MAC Configuring a Basic LB Setup for IDS Configuration Using the procedure described in the section “Configuring a Basic Setup” on page 114, create the services and the vservers and bind them. Name the entities and set the parameters using the values described in the Name and Value columns of the table in the previous section. To create a vserver with * as its IP address using the configuration utility, in the Create Virtual Server (Load Balancing) dialog box, clear the Directly Addressable check box. Note: To configure the vserver with * as its IP address and port use the procedure described in the section “Configuring a Basic Setup” on page 114 with the step described above. Customizing the LB Setup for IDS Configuration After you configure the LB setup, you must customize the LB setup for IDS configuration. The following sections describe the procedures to configure the LB setup for IDS configuration. Configuring the LB Method and Redirection Mode After you create an LB setup, you must configure the correct LB method (for example, the SRCIPDESTIP Hash method on a sessionless vserver) and enable MAC mode. The NetScaler does not maintain the state of the connection and only forwards the packets to the IDS servers without processing them. The destination IP address and port remains unchanged because the vserver is in the MAC mode. To configure LB method and redirection mode for a sessionless vserver using the configuration utility 1. In the left navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver, Vserver-LB-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 314 Installation and Configuration Guide - Volume 1 4. Click the Method and Persistence tab. Under LB Method, select SRCIPDESTIP Hash. 5. Click the Advanced tab. Under Redirection Mode, select the MAC Based radio button. 6. Select the Sessionless check box and click OK. To configure LB method and redirection mode for a sessionless vserver using the NetScaler command line At the NetScaler command prompt, type: set lb vserver Vserver-LB-1 -lbMethod SourceIPDestIPHash -m MAC -sessionless enabled Enabling USIP Mode The client IP address is needed to process the requests on the IDS servers and, therefore, you must enable the USIP mode on the service. The server uses the client IP address and not MIP or SNIP to forward these requests to the selected service. The following procedure describes the steps to enable use source IP mode for each service bound to the vserver. To set a service to use source IP address using the configuration utility 1. In the navigation pane, expand Load Balancing and click Services. The Services page appears in the details pane. 2. Select the service, Service-ANY-1. 3. Click Open. The Configure Service dialog box appears. 4. Click the Advanced tab. 5. Under Settings, select the Use Source IP check box. 6. Click OK. 7. Repeat steps 1-5 for the services Service-ANY-2 and Service-ANY-3. To set a service to use source IP address using the NetScaler command line At the NetScaler command prompt, type: set service Service-ANY-1 -usip yes Note: For USIP to function correctly, you must set it globally. For more information about configuring USIP globally, see the “Basic Network Configuration” chapter of the Installation and Configuration Guide. Chapter 4 Load Balancing 315 Troubleshooting Common Problems • When a metric bound to the monitor is present in the local and custom metric tables, add the local prefix to the metric name if the metric is chosen from the local metric table. If the metric is chosen from the custom table, no prefix needs to be added. • If the metric table is modified (for example, if the OID for the metric is changed), the change is reflected in the monitoring table. SNMP queries originating from the monitor then use the new OID. • Load monitors cannot decide the state of the service. Therefore, setting a weight on the load monitors is inappropriate. • If multiple load monitors are bound to a service, then the load on the service is the sum of all the values on the load monitors bound to it. For load balancing to work properly, you must bind the same set of monitors to all the services. • When you bind a service to a vserver where the LB method is CUSTOMLOAD, and if the service is up, then the vserver is put to initial round robin (RR). It continues to be in RR if the service has no custom load monitors, or if at least one of the custom load monitors is not up. • If you disable a load monitor bound to the service, and if the service is bound to a vserver, then the vserver goes to RR. • If you disable a metric-based binding, and if this is the last active metric, then the specific vserver goes to RR. A metric is disabled by setting the metric threshold to zero. • When a metric bound to a monitor crosses the threshold value, then that particular service is not considered for load balancing.If all the services have reached the threshold, then the vserver goes into RR and an error message “5xx - server busy error” is received. • All the services that are bound to a vserver where the LB method is CUSTOMLOAD must have load monitors bound to them. • The OIDs must be scalar variables. • For successful load balancing, the interval must be as low as possible. If the interval is high, the time period for retrieving the load value increases. As a result, load balancing takes place using improper values. • The CUSTOMLOAD load balancing method also follows startup RR. 316 Installation and Configuration Guide - Volume 1 • A user cannot modify the local table. • A maximum of 10 metrics from a custom table can be bound to the monitor. CHAPTER 5 Content Switching This chapter describes the content switching (CS) feature of a Citrix NetScaler. Content switching allows a NetScaler to distribute the client requests across multiple servers based on the content that the client is accessing. This chapter describes the basic and advanced settings that you can configure on a NetScaler. In This Chapter • How Content Switching Works • Configuring Basic Content Switching • Customizing a Content Switching Setup • Protecting the NetScaler against Failure • Managing Client Connections How Content Switching Works When you configure content switching, you specify which types of requests are to be directed to which virtual servers. For example, you can configure a NetScaler to direct requests for dynamic content, such as URLs with a suffix of .asp, .dll, or .exe, to one server and direct requests for static content to another server. You can also configure the NetScaler to perform content switching based on TCP/IP headers and payload. In addition, the NetScaler directs requests based on various client attributes. Some of the client attributes that the NetScaler uses to determine the destination Web server include: • Device Type. The NetScaler examines the User-Agent or custom HTTP header in the client request for the type of device from which the request is originated. Based on the device type, it directs the request to a specific Web server. For example, if the request came from a cell phone, the request is directed to a server that is capable of serving content that the user can view on his or her cell phone. A request from a PC is directed to a different server that is capable of serving content that a PC user can view. 318 Installation and Configuration guide • Language. The NetScaler examines the Accept-Language HTTP header in the client request and determines the language used by the client’s browser. The NetScaler then sends the request to a server that serves content in that language. For example, using content switching based on language; the NetScaler can send someone who wants to read a French version of a newspaper to a server with the French version of the newspaper. It can send someone else who wants to read the English version of the same newspaper to a server with the English version of the newspaper. • Cookie. The NetScaler examines a cookie and directs the request to a server with customized content. For example, if the cookie indicates that the client is a gold club member, the request is directed to a faster server or one with special content for gold club members. If the cookie indicates that the user is not a gold club member, the request is directed to a slower server or one with different content for the general public. • HTTP Method. The NetScaler examines the HTTP header for the method used and sends the client request to the appropriate server. For example, GET requests for images can be directed to an image server, while POST requests can be directed to a faster server that handles dynamic content. A typical content switching deployment consists of the entities described in the following figure. Content Switching Architecture A typical content switching configuration consists of a content switching virtual server (vserver), a load balancing (LB) setup with load balancing vservers and services and content switching policies. To configure content switching, you must configure a content switching virtual server, and associate it with policies and load balancing vservers. This process creates a content group, which is a group of all vservers and policies involved in a particular content switching configuration. Content switching is only applicable to HTTP, HTTPS, and TCP transactions. For HTTPS transactions, you must enable SSL Offload. Chapter 5 Content Switching 319 When a request reaches the content switching vserver, it applies the associated content switching policies to that request. The content switching vserver routes the request to the load balancing vserver. The load balancing vserver sends it to the service. When binding a policy to the content switching vserver, you assign a priority to it. The priority of the policy defines the order in which the policy is evaluated. Content switching vservers can only send requests to other vservers. If you are using an external load balancer, you must create a load balancing vserver for it and bind its vserver as a service to the content switching vserver. Configuring Basic Content Switching This section describes how to configure a basic but functional content switching setup and how to modify it. The tasks described here serve as a basis for all future configuration tasks that you might perform. This section also covers the procedures to modify the setup, including deleting, enabling, and disabling entities. Topics include: • Configuring Basic Content Switching Setup • Modifying the Existing Content Switching Configuration Configuring Basic Content Switching Setup This section describes the topology of a basic content switching setup. It also describes how to create the content switching vservers and bind policies to them using the basic topology. A basic content switching setup uses only the mandatory parameters and serves as the first step in configuring the content switching feature on a NetScaler. The basic content switching setup provides a simple and functional content switching configuration as described in the following sections. 320 Installation and Configuration guide Understanding the Topology In a content switching setup, the NetScalers are logically located between the client and the server farm. Policies are used to manage traffic flow to the servers in the server farm. The following diagram shows the topology of a basic content switching configuration. Basic content switching topology The content switching requires load balancing and knowledge of how to configure a load balancing setup. For information about load balancing, see the “Load Balancing” chapter. In this example scenario, a content switching vserver Vserver-CS-1 is created and it uses the load balancing vserver Vserver-LB-1 to balance the load on the services bound to Vserver-LB-1. The following table lists the names and values of the basic entities that must be configured on the NetScaler. Entity Type Mandatory Parameters and Sample Values Name IP Address Port Protocol Vserver Vserver-CS-1 10.102.29.161 80 HTTP Vserver-LB-1 10.102.29.60 80 HTTP Services Service-HTTP-1 10.102.29.5 8083 HTTP Service-HTTP-2 10.102.29.6 80 HTTP Monitors Default None None None Chapter 5 Content Switching 321 The following figure shows the content switching sample values and mandatory parameters that are described in the preceding table. Content switching entity model Enabling Content Switching You can configure content switching entities when the content switching feature is disabled. However, you must enable content switching for the entities to work. To enable content switching using the configuration utility 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click basic features. The Configure Basic Features dialog box appears. 3. Select the Content Switching check box. 4. Click OK, and the Enable/Disable Features(?) dialog box appears. 5. Click Yes. To enable content switching using the NetScaler command line At the NetScaler command prompt, type: enable feature cs 322 Installation and Configuration guide Creating Content Switching Vservers You can add, modify, and remove vservers. When you create a content switching vserver, it is UP by default. To create a content switching vserver, use the parameters as described in the following table. To add a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Click Add. The Create Virtual Server (Content Switching) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type the name, IP address, and port of the vserver, for example, Vserver-CS-1, 10.102.29.161, and 80. Parameter Description Name The name of the content switching vserver. The vserver name must not exceed 31 characters and must not contain spaces. This setting cannot be changed. IP address The IP address of the vserver. This IP address (VIP) is usually a public IP address and the clients send connection requests to this IP address. Service type This parameter determines the behavior of the service. Choose one of the following service types: • HTTP - for HTTP services • TCP - for non-RFC implementation or HTTP services • FTP - for FTP services. This setting ensures that the NetScaler takes care of the specifics of the FTP protocol. • SSL - for HTTPS services. Select this type to encrypt the traffic between the NetScaler and the server. Port The port on which the vserver listens for client connections. The port number must be between 0-65535. Chapter 5 Content Switching 323 4. In the Protocol list, select the type of the vserver, for example, HTTP. 5. Click Create and click Close. The vserver you created appears in the Content Switching Virtual Servers page, as shown in the following figure. Content switching virtual servers page To create a vserver using the NetScaler command line At the NetScaler command prompt, type: add cs vserver Vserver-CS-1 HTTP 10.102.29.161 80 Configuring a Load Balancing Setup The content switching vserver diverts the traffic to the load balancing vserver. The load balancing vserver then balances the load across the servers. To configure a basic load balancing setup, you need to perform the following tasks: • Create load balancing vservers • Create services • Bind services to the load balancing vserver To learn how to configure a load balancing setup, see the “Load Balancing” chapter. You need to have a basic load balancing setup for your content switching setup to work. Creating Content Switching Policies A content switching policy defines a criterion that specifies which content switching vserver receives a client request and is directed to a load balancing vserver. These policies are applied in the sequence of the priorities assigned to them. Policies are created using expressions and rules. 324 Installation and Configuration guide The policies can be: • URL-based policies. The NetScaler selects the content group based on matching the incoming URL with the configured URLs. The NetScaler returns the most appropriate URL-based (usually the longest matching configured URL) content group among the configured URLs. • Rule-based policies. The NetScaler selects the content group with the first matching rule in the configured order. For multiple matching rules, no specific precedence is set and is based on the order in which the rules are configured. You can create rule-based policies by using policy expressions. For more information about policy expressions, see the Advanced Policy Guide. To create a policy, use the parameters as described in the following table. The following procedure describes steps to create a policy named Policy-CS-1 that is evaluated when the NetScaler receives an HTTP request that contains “sports” in the URL and the domain name matches www. xyz.com. To create a content switching policy using the configuration utility 1. In the navigation pane, expand Content Switching and click Policies. The Content Switching Policies page appears in the details pane. 2. Click Add. The Create Content Switching Policy dialog box appears. 3. In the Name text box, type the name of the policy, for example, Policy-CS-1. Parameter Description Policy Name The name of the new content switching policy. The name of the policy must not be longer than 31 characters. URL The URL, with wildcards. Specify the string value in this format: // [[prefix ] [*]] [.suffix] Domain The domain name. Specifies that the NetScaler selects a content group based on domain name matches. The string value can range to 63 characters. Chapter 5 Content Switching 325 4. Select URL. In the Value text box, type the string value, for example, /sports. 5. In the Domain text box, type the string value, for example, www.xyz.com. 6. Click Create and click Close. The policy you created appears in the Content Switching Policies page as shown in the following figure. Content switching policies page To create a content switching policy using the NetScaler command line At the NetScaler command prompt, type: add cs policy Policy-CS-1 -url /sports/* -domain www.xyz.com Binding Policies to the Content Switching Vserver The NetScaler evaluates the policies to direct the traffic to the servers. After you have created the content switching vserver and policy, you can bind the policy to the content switching vserver so that the vserver evaluates the policy and routes the traffic to the load balancing vserver. You can create rule-based policies by using advanced policy expressions. For more information about advanced policy expressions, see the Advanced Policy Guide. After a policy that uses an advanced expression is bound to a CS vserver, you cannot bind policies using classic policy expressions to that vserver. Priorities are compulsory for advanced policies. Duplicate priorities are not supported. 326 Installation and Configuration guide You can also configure policies using GoTo expressions. These expressions always resolve to a number. This number corresponds to the priority of another policy. As a result, when a GoTo expression is evaluated a different policy is invoked. Policies with GoTo expressions do not have LB vservers bound to them. The GoTo expression will fail if the resulting priority is not assigned to a policy, the GoTo expression does not evaluate to a number, or the GoTo expression evaluates to a number lower than its own priority. GoTo expressions can only be configured for advanced expressions. They cannot be used with classic expressions. When a GoTo expression fails, the default target vserver is selected. To bind a policy, use the parameters as described in the following table. The following procedure describes the steps to bind a content switching policy to the content switching vserver. To bind a policy to a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver to which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. The policies appear in the Policies tab. 4. Select the Active check box next to the policy that you want to bind to the vserver, for example, Policy-CS-1. 5. Click the Target box next to the policy and select the load balancing vserver that you want configure for the content switching vserver, for example, Vserver-LB-1. 6. Click OK. Parameter Description Priority Priority with which the policy is to be bound. The minimum value is 1 and the maximum value is 2147483647. gotoPriorityExpression Expression specifying the priority of the next policy which is evaluated after the current policy rule evaluates to TRUE. If you don’t specify the gotoPriorityExpression or if it is the last expression then the policy bank evaluation ends. If the gotoPriorityExpression is next expression, the next policy in the priority order is evaluated. If the gotoPriorityExpression evaluates to the priority of the current policy then the next policy in the priority order is evaluated. If the gotoPriorityExpression evaluates to the priority of a policy in the list then that policy will be evaluated next. The maximum length is 1500. Chapter 5 Content Switching 327 To bind a policy to a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: bind cs vserver Vserver-CS-1 Vserver-LB-1 -policyname Policy-CS-1 Verifying the Configuration To verify the configuration, you need to view the properties of the content switching vservers and content switching policies and the statistics of the entities in the configuration. Viewing the Properties of Content Switching Vservers You can view properties such as the name, state, IP address, and port of the configured content switching vservers. The details of the vserver can be used to troubleshoot any error in the configuration. The following procedure describes the steps to view the properties of a content switching vserver named vserver-CS-1. To view the properties of content switching vservers using the configuration utility In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. The details of the available vservers appear on this page. To view the properties of content switching vservers using the NetScaler command line At the NetScaler command prompt, type: show cs vserver Note: To view the properties of a content switching vserver use the command show cs vserver Vserver-CS-1 328 Installation and Configuration guide Viewing Load Balancing Configuration You can view the properties and the statistics of the entities in the load balancing configuration. To learn how to view the entities and the statistics of a load balancing setup, see the “Load Balancing” chapter. Viewing Content Switching Policies You can view properties such as the name, URL, expression, and domain of the configured content switching policies. The details of the policies can be used to troubleshoot any error in the configuration. The following procedure describes the steps to view the properties of a content switching policy named Policy-CS-1. To view the properties of content switching policies using the configuration utility In the navigation pane, expand Content Switching and click Policies. The Content Switching Policies page appears in the details pane. The details of the available policies appear on this page. To view the properties of content switching policies using the NetScaler command line At the NetScaler command prompt, type: show cs policy Note: To view the properties of a content switching policy use the command show cs policy Policy-CS-1 Modifying the Existing Content Switching Configuration Most environments that use content switching are more complex than the basic setup and require more specialized configuration and sophisticated policies that use more complex expressions. This section describes how to modify the basic content switching setup you configured previously. This section also describes the impact of modifying an entity in the basic content switching setup. You can perform tasks such as enabling, disabling, and removing entities in the basic content switching setup, using the procedures described in this section. Chapter 5 Content Switching 329 Managing Content Switching Vserver This section describes how to manage the content switching vservers after you create them. Managing the content switching vservers involves modifying the entities in a basic content switching setup. You can perform tasks such as enabling, disabling, and removing content switching vservers after you create them. You can also unbind a content switching policy from a content switching vserver. Each task that you perform has an impact on the basic content switching setup, as described in the following sections. Unbinding a Content Switching Policy fromthe Content Switching Vserver When you unbind a policy from a content switching vserver, the NetScaler does not evaluate the policy to direct the traffic to the servers. The following procedure describes the steps to unbind a policy Policy-CS-1 from the content switching vserver Vserver-CS-1. To unbind a policy from a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver from which you want to unbind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. The policies appear in the Policies tab. 4. Clear the Active check box next to the policy that you want to unbind from the vserver, for example, Policy-CS-1. 5. Click OK. To unbind a policy from a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: unbind cs vserver Vserver-CS-1 -policyname Pocily-CS-1 330 Installation and Configuration guide Removing Content Switching Vservers You need to remove a content switching vserver only when you no longer require the vserver. When you remove a content switching vserver, the NetScaler unbinds all policies from the content switching vserver, and then removes the content switching vserver. If you remove all the content switching vservers from the NetScaler, the NetScaler does not perform content switching. The following example describes the steps to delete the content switching vserver Vserver-CS-1. To remove a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver that you want to remove, for example, Vserver-CS-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: rm cs vserver Vserver-CS-1 Enabling and Disabling Content Switching Vservers You can disable a content switching vserver for maintenance. If you disable the content switching vserver, the state of the content switching vserver changes to Out of Service. In this state, the content switching vserver does not respond to the clients with 200 OK. To disable a vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver that you want to disable, for example, Vserver-CS-1. 3. Click Disable. The Disable pop-up window appears. 4. Click Yes. To disable a vserver using the NetScaler command line At the NetScaler command prompt, type: disable cs vserver Vserver-CS-1 Chapter 5 Content Switching 331 By default, the vservers are enabled. To enable a vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver that you want to enable, for example, Vserver-CS-1. 3. Click Enable. The Enable pop-up window appears. 4. Click Yes. To enable a vserver using the NetScaler command line At the NetScaler command prompt, type: enable cs vserver Vserver-CS-1 Managing Load Balancing Configuration After you set up a basic load balancing configuration, you can manage the entities you created in the basic load balancing setup. You can enable, disable, or remove the entities. Each task that you perform has an impact on the services that use the server, as described in the following sections. To learn how to manage the entities of a load balancing setup, see the “Load Balancing” chapter. Managing Content Switching Policy This section describes how to manage the content switching policies after you create them. You can perform tasks such as modifying and removing content switching policies after you create them. You can also unbind a content switching policy from a content switching vserver. Each task that you perform has an impact on the basic content switching setup, as described in the following sections. Modifying Content Switching Policies You can modify an existing policy or create new policies and bind them to the vserver. You can configure rules or change the URL of the policy. To modify a policy, use the parameters as described in the following table. Parameter Description URL The URL, with wildcards. Specify the string value in the following format: // [[prefix ] [*]] [.suffix] 332 Installation and Configuration guide You can create different policies based on the URL. URL-based policies can be of different types as described in the following table. Rule The condition for applying this policy. Expression names separated by the logical operators || and &&. Expression names may be grouped using parentheses. If the expression contains blanks (e.g., between an expression name and a logical operator), then the entire argument must be enclosed in double quotes. Domain The domain name. The string value can range to 63 characters. Type of URL-based policy Description Domain and Exact URL Specifies that the NetScaler selects a content group if the domain name and URL match. The incoming requests must match the configured domain name and configured URL (an exact prefix matches if only the prefix is configured or an exact match of the prefix and suffix if both the prefix and suffix are configured). Example: add cs policy Policy-CS-1 -url /sports/ tennis/index.html -domain "www.domainxyz.com" Domain and Wild Card URL Specifies that the NetScaler selects a content group based on a match of the exact domain name and a partial prefix of the URL. Example: add cs policy Policy-CS-1 -url /*.jsp -domain "www.domainxyz.com" Domain Only Specifies that the NetScaler selects a content group based on domain name matches. The incoming requests must match the configured domain name. Example: add cs policy Policy-CS-1 -domain "www.domainxyz.com" Exact URL Specifies that the NetScaler selects a content group based on whether the incoming URL matches the configured URL policy rule. If only a URL prefix rule is configured, then an exact prefix match should occur with the incoming URL. If a URL prefix and suffix-based rule is configured, an exact prefix and suffix match should occur with the incoming URL. Below are two examples of exact URL-based policies. Example: add cs policy Policy-CS-1 -url /sports/tennis/index.html Parameter Description Chapter 5 Content Switching 333 To modify a content switching policy using the configuration utility 1. In the navigation pane, expand Content Switching and click Policies. The Content Switching Policies page appears in the details pane. 2. Select the policy that you want to modify, for example, Policy-CS-1. 3. Click Open. The Configure Content Switching Policies dialog box appears. 4. In the Domain text box, type the domain name for example, www.domainxyz.com. 5. Click OK. To modify a content switching policy using the configuration utility At the NetScaler command prompt, type: set cs policy Policy-CS-1 -domain “www.domainxyz.com” Prefix Only (Wild Card URL) Specifies that the NetScaler selects the content group based on a match of the partial prefix of the URL. All the incoming URLs must start with the configured prefix. Example: add cs policy Policy-CS-1 -url /sports* sports/*” matches all URLs under /sports “/sports*” matches all URLs whose prefix match “/sports” starting from the beginning of a URL Suffix Only (Wild Card URL) Specifies that the NetScaler selects a content group if all incoming URLs match the configured URL suffix. Example: add cs policy Policy-CS-1 -url /*.jsp “/*.jsp” matches all URLs whose file extension is “jsp” Prefix and Suffix (Wild Card URL) Specifies that the NetScaler selects a content group based on a partial URL match. All incoming URLs start with the configured prefix, which must match the configured suffix. Example: add cs policy Policy-CS-1 -url /sports/*.jsp “/sports/*.jsp” matches all URLs under “/sports/” that also have the file extension of “jsp” Type of URL-based policy Description 334 Installation and Configuration guide Note: You can configure content switching using classic policy expressions or using advanced policy expressions. The rule-based policies use the policy expressions. For more information about configuring policy expressions, see the Advanced Policy Guide. Removing Content Switching Policies You need to remove a content switching policy when you no longer require the policy. When you remove a bound content switching policy, the NetScaler unbinds the policy from the content switching vserver, and then removes the content switching policy. The following example describes the steps to delete the content switching policy Policy-CS-1. To remove a content switching policy using the configuration utility 1. In the navigation pane, expand Content Switching and click Policies. The Content Switching Policies page appears in the details pane. 2. Select the policy that you want to remove, for example, Policy-CS-1. 3. Click Remove. The Remove pop-up window appears. 4. Click Yes. To remove a content switching policy using the NetScaler command line At the NetScaler command prompt, type: rm cs policy Policy-CS-1 Customizing a Content Switching Setup This section describes how to customize a basic content switching setup to meet your requirements. You can perform the optional tasks such as setting case sensitivity in policy evaluation and setting the precedence of policy evaluation. Customizing a basic content switching setup is described in the following sections. Topics include: • Setting Case Sensitivity in Policy Evaluation • Setting the Precedence of Evaluation of Policy • Setting Dependency of CS Vserver State on the State of Target LB Vservers Chapter 5 Content Switching 335 Setting Case Sensitivity in Policy Evaluation You can configure the content switching vserver to send traffic to different target severs based on the case of the URL. When character case sensitivity setting is configured, the NetScaler evaluates the policy to match the incoming requests including the character capitalization. If this setting is not configured, the NetScaler ignores the case of the URL and evaluates the policy to match the incoming requests. To set case sensitivity, use the parameter described in the following table. To configure case sensitivity using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. Select Case Sensitivity check box. 6. Click OK. To configure a content switching vserver to redirect the client request to a URL using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -caseSensitive ON Parameter Description Case Sensitive The URL lookup case option on the content switching vserver. If the case sensitivity of a content switching virtual server is set to 'ON', the URLs /a/1.html and /A/1.HTML are treated differently, and can be switched to different targets with appropriate content switching policies. If the case sensitivity is set to 'OFF', the URLs /a/1.html and /A/ 1.HTML are treated the same, and are switched to the same target. The possible values are ON and OFF. The default value: ON 336 Installation and Configuration guide Setting the Precedence of Evaluation of Policy This section describes how precedence works with URL-based and rule-based policies and explains how to configure precedence. Precedence with URL-based policies Set URL-based precedence if the content type is same for all clients. However, if different types of content must be provided based on client attributes you must use rule-based precedence. If there are multiple matching URLs for the incoming request, the precedence (priority) for URL-based policies is as follows: 1. Domain and exact URL 2. Domain, prefix, and suffix 3. Domain and suffix 4. Domain and prefix 5. Domain only 6. Exact URL 7. Prefix and suffix 8. Suffix only 9. Prefix only 10. Default If you configure precedence based on URL, the request URL is compared to the configured URLs. If none of the configured URLs match the request URL, then rule-based policies are checked. If the request URL does not match any rule- based policies, or if the content group selected for the request is down then the request is processed as follows: • If you configure a default group for the content switching vserver, then the request is forwarded to the default group. • If the configured default group is down, or if no default group is configured, then an “HTTP 404 Not Found” error message is sent to the client. Chapter 5 Content Switching 337 Precedence with rule-based policies If you configure precedence based on rules, which is the default setting, the request is tested based on the rule-based policies you have configured. If the request does not match any rule-based policies, or if the content group selected for the incoming request is down, then the request is processed in the following manner: • If a default group is configured for the content switching vserver, the request is forwarded to the default group. • If the configured default group is down, or if no default group is configured, then an “HTTP 404 Not Found” error message is sent to the client. Note: You can set rule-based precedence on any of the several client attributes. For example, if you set rule-based precedence on the browser type attribute different content is provided to the client. You can configure both URL-based policies and rule-based policies for the same content switching vserver. To set precedence, use the parameter described in the following table. To set precedence using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. Parameter Description Precedence This sets the precedence between RULE-based and URL-based policies on the content switching virtual server. The default precedence is RULE. With the precedence set to RULE, incoming requests are evaluated against the content switching policies created with the -rule argument (using the add cs policy CLI command). If none of the rules match, the URL in the request is evaluated against the content switching policies created with the -url argument (using the add cs policy CLI command). The possible values are RULE and URL. The default value is RULE 338 Installation and Configuration guide 5. Under Precedence, select URL. 6. Click OK. To set precedence using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -Precedence URL Setting Dependency of CS Vserver State on the State of Target LB Vservers You can set the state of a CS vserver to be dependent on the state of target LB vservers that are bound to the CS vserver. If this dependency is enabled, and a default LB vserver is bound to the CS vserver, the CS vserver’s state is dependent only on the state of the default LB vserver. If the dependency is enabled and no default LB vserver is bound to the CS vserver, the CS vserver’s state is dependent on the state of the target LB vservers bound to the CS vserver: In this case, the CS vserver is up only when all target LB vservers are up, and the CS vserver is down if any target LB vserver is down. If this setting is not specified, the NetScaler ignores the state of target LB vservers when displaying the state of the CS vserver. To configure state dependency, use the parameter described in the following table. To set the state dependency of a CS vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to create a state dependency, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. Select the State Update check box. Parameter Description State Update The option to set CS vserver state dependency on the state of target LB vservers.If the state dependency of a CS vserver is set to ‘ENABLED,’ then the NetScaler indicates that the CS vserver is up only when a target LB vserver is also up. If the state dependency of a CSvserver is set to ‘DISABLED,’ then the NetScaler ignores the state of target LB vservers when displaying the state of the CS vserver. The possible values are ENABLED and DISABLED. The default value: DISABLED. Chapter 5 Content Switching 339 6. Click OK. To configure the state dependency of a CS vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -stateupdate ENABLED Protecting the NetScaler against Failure The content switching setup can fail when a content switching vserver fails, or when the content switching vserver is unable to handle excessive traffic. Protecting the content switching setup against failure helps ensure the availability of the setup. Topics include: • Configuring Backup Vserver • Diverting Excess Traffic to a Backup Vserver • Configuring a URL for Redirection Configuring Backup Vserver If the primary content switching vserver is marked down or disabled, the NetScaler directs the connections or client requests to a backup vserver that forwards the client traffic to the load balancing vserver. It can also send a notification message to the client regarding the site outage or maintenance. You can also configure a backup load balancing vserver that handles the client traffic when the content switching vserver is down. The backup vserver is a proxy and is transparent to the client. Note: If a content switching vserver is configured with both a backup vserver and a redirect URL, the backup vserver takes precedence over the redirect URL. A redirect is used when the primary and backup vservers are down. You can configure a backup vserver when you create a content switching vserver, or when you change the optional parameters of an existing content switching vserver. You can also configure a backup vserver for an existing backup vserver, thus creating a cascade of backup vservers. The maximum depth of cascading backup vservers is 10. The NetScaler searches for a backup vserver that is in the UP state and accesses that content switching vserver to deliver the content. 340 Installation and Configuration guide Note: If the backup vserver does not exist, an error message appears. You can use a redirect URL on the primary vserver when the primary and the backup vservers are down or have reached their threshold for handling requests. The following table describes the parameter required to configure a backup vserver. The following example describes the steps to set the existing Vserver-CS-2 as a backup to Vserver-CS-1. The vserver Vserver-CS-2 is created with IP address 10.102.29.163 and protocol HTTP. To set a backup vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. In the Backup Virtual Server list, select the backup vserver, for example, Vserver-CS-2. 6. Click OK. To set a backup vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -backupVserver Vserver-CS-2 Parameter Description Name The name of the backup vserver. You can create a vserver and specify the name, IP address, port, and type as described in “Creating Content Switching Vservers” on page 322. You can use the name of the content switching vserver as a backup vserver. Chapter 5 Content Switching 341 Diverting Excess Traffic to a Backup Vserver The spillover option diverts new connections arriving at a content switching vserver to a backup content switching vserver when the number of connections to the content switching vserver exceeds the configured threshold value. The threshold value is dynamically calculated, or you can set the value. The number of established connections (in case of TCP) at the vserver is compared with the threshold value. When the number of connections reaches the threshold, new connections are diverted to the backup content switching vserver. If the backup content switching vservers reach the configured threshold and are unable to take the load, the primary content switching vserver diverts all requests to the redirect URL. If a redirect URL is not configured on the primary content switching vserver, subsequent requests are dropped. For more information about redirect URL, see the section “Configuring a URL for Redirection” on page 342. To configure spillover, use the parameters described in the following table. The following example describes the steps to configure the content switching vserver Vserver-CS-1 to divert new connections to the backup content switching vserver vserver-CS-2 when the number of connections exceeds the threshold value 1000. Parameter Description Method Type of spillover used to divert traffic to the backup content switching vserver when the vserver reaches the spillover threshold. The valid options for this parameter are: CONNECTION, BANDWIDTH, and NONE. For more information about how each of these methods work, see the “Load Balancing” chapter. Threshold For the CONNECTION spillover type, the Threshold value is the maximum number of connections a vserver can handle prior to spillover. For the BANDWIDTH spillover type, the Threshold value is the amount of incoming and outgoing traffic (in kilobits per second) that a vserver can handle before spillover occurs. The minimum value is 1, and the maximum value is 4294967294. Persistence The spillover persistence state. If you enable spillover persistence, the NetScaler maintains source IP-based persistence over primary vserver and backup content switching vservers. The valid options for this parameter are: enabled and disabled. The default value is disabled. Persistence Timeout (minutes) This value sets the timeout for spillover persistence. The default value is 2 minutes. The minimum value is 2 minutes, and the maximum value is 1440 minutes. 342 Installation and Configuration guide To set a content switching vserver to divert new connections to a backup vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. In the Method list, select the type of spillover, and in Threshold text box type the threshold value, for example, Connection and 1000. 6. Under Spillover, select the Persistence check box, and in Persistence Timeout (min) text box, type the timeout, for example, 2. 7. Click OK. To set a content switching vserver to divert new connections to a backup vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -soMethod Connection -soThreshold 1000 -soPersistence enabled -soPersistenceTimeout 2 Configuring a URL for Redirection You can configure a redirect URL to communicate the status of the NetScaler in the event that a content switching vserver (only of type HTTP or HTTPS) is down or disabled. This URL can be a local or remote link. The NetScaler uses HTTP 302 redirect. Redirects can be absolute URLs or relative URLs. If the configured redirect URL contains an absolute URL, the HTTP redirect is sent to the configured location, regardless of the URL specified in the incoming HTTP request. If the configured redirect URL contains only the domain name (relative URL), the HTTP redirect is sent to a location after appending the incoming URL to the domain configured in the redirect URL. Note: If a content switching vserver is configured with both a backup vserver and a redirect URL, the backup vserver takes precedence over the redirect URL. A redirect is used when the primary and backup vservers are down. Chapter 5 Content Switching 343 The following table describes the parameter required for configuring a vserver to redirect client requests to a URL. The following example describes the steps to set the content switching vserver Vserver-CS-1 to redirect client requests to the URL http://www.newdomain.com/mysite/maintenance. To configure a content switching vserver to redirect the client request to a URL using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. In the Redirect URL text box, type the URL, for example, http://www.newdomain.com/mysite/maintenance. 6. Click OK. To configure a content switching vserver to redirect the client request to a URL using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -redirectURL http://www.newdomain.com/mysite/maintenance Managing Client Connections Maintaining client connections helps to ensure the availability of the services. This section includes procedures for configuring the NetScaler to use cache and other tasks to improve response and direct client requests based on priority. Parameter Description Redirect URL The URL where traffic is redirected if the vserver in the NetScaler becomes unavailable. This value must not exceed 127 characters. The domain specified in the URL must not match the domain specified in the domain name argument of a content switching policy. If the same domain is specified in both arguments, the request is redirected continuously to the same unavailable vserver in the NetScaler, and the user cannot get the requested content. 344 Installation and Configuration guide Topics include: • Redirecting Client Requests to a Cache • Enabling Delayed Cleanup of Vserver Connections • Rewriting Ports and Protocols for Redirection • Inserting the IP Address and Port of a Vserver in the Request Header • Setting a Time-out Value for Idle Client Connections Redirecting Client Requests to a Cache The NetScaler provides the cache redirection option for transparently redirecting HTTP requests to a cache. A cache stores frequently requested HTTP content. When you configure cache redirection on a content switching vserver, the NetScaler sends cacheable HTTP requests to the transparent caches and non-cacheable HTTP requests to the origin Web servers. For more information about cache redirection, see the “Cache Redirection” chapter of the Installation and Configuration Guide. To configure cache redirection, use the Cache Redirection parameter as described in the following table. To set cache redirection on a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. Select the Cacheable check box. 6. Click OK. Parameter Description Cacheable Enables the content switching vserver to route requests to the cache redirection vserver before sending them to the configured servers. The valid options for this parameter are: yes and no. The default value is no. Chapter 5 Content Switching 345 To set cache redirection on a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -cacheable yes Enabling Delayed Cleanup of Vserver Connections You can enable the setting on the Web servers whose connections can be flushed when they are marked down. You must not enable the down flush state setting on the application servers that must complete their transactions and their connections must not be flushed. For more information about the down flush state setting, see the “Load Balancing” chapter. To configure down state flush, use the down state flush parameter as described in the following table. To set down state flush on a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. Select the Down state flush check box. 6. Click OK. To set down state flush on a vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -downStateFlush enabled Parameter Description down state flush Perform delayed cleanup of connections on this vserver. The valid options for this parameter are: enabled and disabled. The default value is enabled. 346 Installation and Configuration guide Rewriting Ports and Protocols for Redirection When the server responds with HTTP redirection, the NetScaler rewrites the port and the protocol. By default, this setting is disabled. This setting affects SSL traffic only. When this setting is enabled on a content switching vserver, the NetScaler rewrites the port using the port settings of the content switching vserver. For more information about SSL redirects, see the “Secure Sockets Layer (SSL) Acceleration” chapter. To configure a vserver for HTTP redirection, you must use the redirect port rewrite parameter listed in the following table. To set redirection on a content switching vserver using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. Select the Redirect Port Rewrite check box. 6. Click OK. To set redirection on a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -redirectPortRewrite enabled Inserting the IP Address and Port of a Vserver in the Request Header You can configure the NetScaler to add the IP address and port number of a content switching vserver to the HTTP requests that are sent to the server. This setting allows applications running on the server to identify the content switching vserver that sent the request. Parameter Description Redirect Port Redirect SSL redirect port rewrite. The valid options for this parameter are: enabled and disabled. The default value is disabled. Chapter 5 Content Switching 347 This option is not supported for wildcard vservers or dummy vservers. If the primary content switching vserver is down and the backup content switching vserver is marked up, the configuration settings of the backup content switching vserver are added to the client requests. If you want to add the same header tag, regardless of whether the requests are from the primary content switching vserver or backup content switching vserver, then you must configure the required header tag on both vservers. To configure a vserver to add the IP address and port to the client requests, use the Vserver IP Port Insertion parameter as described in the following table. The following example describes the steps to configure the NetScaler to add the IP address and port number of the vserver Vserver-CS-1 to HTTP requests that are forwarded to the servers. To insert the IP address and port of the vserver in the client requests using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. Parameter Description Vserver IP Port Insertion The virtual IP and port header insertion option for the vserver. VIPADDR-Header contains the vserver IP address and port number without any translation. If VIPADDR is not specified, the header is inserted with the name specified in the default header tag vip-header and the vserver IP and port are inserted in the request with the default header tag vip-header. If VIPADDR is specified, the header is inserted with the user-specified name in vipHeader. The vserver IP and port are inserted in the request with the user-specified header tag vipHeader. OFF- The virtual IP and port header insertion options are disabled. The vserver and port number are not inserted. V6TOV4MAPPING - Header contains the mapped IPv4 address corresponding to the IPv6 address of the vserver and the port number. An IPv6 address can be mapped to a user-specified IPv4 address. The valid options for this parameter are: OFF, VIPADDR, and V6TOV4MAPPING. The default value is OFF. 348 Installation and Configuration guide 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. 5. In the Vserver IP Port Insertion list, select the VIPADDR or V6TOV4MAPPING. 6. Type the port header in a text box next to Vserver IP Port Insertion box. 7. Click OK. To insert the IP address and port of the vserver in the client requests using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -insertVserverIPPort VipAddr Setting a Time-out Value for Idle Client Connections You can configure the content switching vserver with a timeout value to terminate any idle client connections when the configured time elapses. If the client is idle after the configured time, the NetScaler closes the client connection. To set a timeout value for idle client connections, use the client parameter as described in the following table. The following example describes the steps to set the timeout value for idle client connections to 100 seconds. To set a timeout value for idle client connections using the configuration utility 1. In the navigation pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, Vserver-CS-1. 3. Click Open. The Configure Virtual Server (Content Switching) dialog box appears. 4. Click the Advanced tab. Parameters Descriptions Client Timeout (Secs) The idle time (in seconds) after which the client connection is terminated. The default value is 180sec for HTTP/SSL-based services and 9000sec for TCP-based services. Chapter 5 Content Switching 349 5. In the Client Timeout (secs) text box, type the timeout value, for example, 100. 6. Click OK. To set a timeout value for idle client connections using the NetScaler command line At the NetScaler command prompt, type: set cs vserver Vserver-CS-1 -cltTimeout 100 350 Installation and Configuration guide CHAPTER 6 Secure Sockets Layer (SSL) Acceleration Overview This chapter describes SSL acceleration on the NetScaler. The topics covered include: • How SSL Works • Configuring SSL Offloading • Managing Certificates • Configuring Client Authentication • Managing Certificate Revocation lists • Customizing the SSL Configuration • Managing SSL Actions and Policies • Configuring Some Commonly Used SSL Configurations • Configuring the SSL Feature for Commonly Used Deployment Scenarios How SSL Works Processing secure SSL transactions can consume a large portion of a Web server’s CPU capacity, degrading performance and increasing end-user response times. SSL acceleration transparently improves the performance of Web sites that conduct SSL transactions. The SSL protocol works seamlessly with a variety of HTTP and TCP data types, and provides a secure channel for these data transactions. A NetScaler configured with SSL acceleration is placed in front of a Web server, where it intercepts SSL transactions on behalf of the server, processes the SSL transactions, applies the NetScaler’s load balancing and content switching policies, then relays the transactions to the servers. 352 Installation and Configuration Guide - Volume 1 The following figure shows an implementation of the SSL feature. SSL entity diagram To configure SSL, you must first create an SSL virtual server and services on the NetScaler. Then, you must bind a valid SSL certificate and the configured services to the SSL virtual server. An SSL virtual server intercepts incoming encrypted traffic and decrypts it using the certificate bound to the virtual server. The SSL virtual server then forwards the decrpyted data to the other entities on the NetScaler for appropriate processing. SSL services are a virtual representation of the physical servers on the internal network that offload SSL processing to the NetScaler. Note: FIPS-related options for some of the procedures described in this document are specific to a FIPS-enabled Application Switch. See the FIPS Guide for more information about configuring a FIPS-enabled Application Switch Configuring SSL Offloading SSL offloading diverts the CPU-intensive SSL encryption/decryption tasks from the local Web server to the NetScaler, thereby freeing Web server resources to handle requests for content. SSL offloading ensures the secure delivery of Web applications without degrading performance. Once the SSL traffic is decrypted, it can be processed using any standard services on the NetScaler. Chapter 6 Secure Sockets Layer (SSL) Acceleration 353 This section explains the procedures to configure basic SSL offloading on the NetScaler. The following tasks are covered: • Enabling the SSL Feature • Configuring an SSL Virtual Server for Basic SSL Offloading • Verifying the Configuration Enabling the SSL Feature You should enable the SSL feature on the NetScaler before any SSL processing is carried out. (You can configure SSL-based entities on the NetScaler without enabling the SSL feature, but they will not work until you enable SSL.) The SSL feature is located under Basic Features in the Citrix NetScaler Configuration Utility. To enable the SSL feature 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 2. In the Modes & Features group, click the Basic Features link. The Configure Basic Features dialog box appears. 3. Select the SSL Offloading check box, then click OK. When the Enable/ Disable Feature(s)? message box appears, click Yes.The SSL feature is enabled on the NetScaler. To enable the SSL feature using the NetScaler command line At the NetScaler command prompt, type: enable ns feature ssl 354 Installation and Configuration Guide - Volume 1 Configuring an SSL Virtual Server for Basic SSL Offloading In a basic SSL offloading setup, the SSL virtual server intercepts encrypted traffic, decrypts it, and sends the clear text messages to the services that are bound to the virtual server. Offloading CPU-intensive SSL processing to the NetScaler allows the back-end servers to process a greater number of requests. This is illustrated in the following figure.. Basic SSL offloading Note: For TCP traffic, follow the procedures given below, but create TCP services instead of HTTP services. To configure SSL for basic SSL offloading, you need to set the parameters as described in the sections that follow. The procedures describe the steps to configure the SSL feature in a basic SSL offload setup where an SSL virtual server Vserver-SSL-1 offloads SSL traffic directed to two HTTP services, Service-HTTP-1 and Service-HTTP-2. Adding HTTP-based Services A service on the NetScaler represents a physical web server in the network. Once configured, services are in the disabled state until the NetScaler can reach the server on the network and monitor its status. The following procedure describes the steps to configure two HTTP based services, Service-HTTP-1 and Service-HTTP-2 with IP addresses 10.102.20.30 and 10.102.20.31. To add an HTTP-based service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name text box, type the name of the service being added, for example, Service-HTTP-1. Chapter 6 Secure Sockets Layer (SSL) Acceleration 355 4. Under Server, type the IP address of the server to be associated with this service, for example, 10.102.20.30. Note: If the server has been configured already, in step 4, select the configured server to be associated with the service. 5. Under Protocol, select HTTP. Note: For TCP services, under Protocol, select TCP. 6. In the Port text box, type the port number for the HTTP service to use, for example, 80. 7. Click Create, then click Close. The HTTP service you configured appears in the Services page. To create the second service, repeat the procedure for the service name Service- HTTP-2 with IP address 10.102.20.31. To add an HTTP-based service using the NetScaler command line At the NetScaler command prompt, type: add service Service-HTTP-1 10.102.20.30 HTTP 80 Adding an SSL-based Virtual Server Secure sessions require establishing a connection between the client computer and an SSL-based virtual server on the NetScaler. SSL processing is then carried out on the incoming traffic at the virtual server. Therefore, before enabling the SSL virtual server on the NetScaler, you need to bind a valid SSL certificate to the SSL virtual server. The procedure that follows describes the steps to configure an SSL-based virtual server with IP address 10.102.29.50 and protocol SSL, listening on port 443. To add an SSL-based virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Server (SSL Offload) dialog box appears. 3. In the Name text box, type the name of the virtual server to be created, for example Vserver-SSL-1. 4. In the IP Address text box, type the IP address of the virtual server, for example, 10.102.29.50. 356 Installation and Configuration Guide - Volume 1 5. Under Protocol, select SSL. 6. In the Port text box, type the port number for the virtual server to use, for example, 443. 7. Click Create, then click Close. The virtual server you created appears in the SSL Offload Virtual Servers page. Note: The SSL virtual server you create is shown as down because a certificate- key pair has not been bound to it, and there are no services bound to it. To add an SSL-based virtual server using the NetScaler command line At the NetScaler command prompt, type: add vserver Vserver-SSL-1 SSL 10.102.29.50 443 Binding the HTTP Services to the Virtual Server After decrypting the incoming data, the SSL virtual server forwards the data to the services that are bound to the virtual server. Data transfer between the NetScaler and the servers can be encrypted or in clear text. Note: If the data transfer between the NetScaler and the server is encrypted, the entire transaction is secure from end to end. For details about configuring the NetScaler for end to end security, refer to the section Configuring SSL Offloading with End-to-End Encryption. The following procedure describes the steps to bind the services Service-HTTP-1 and Service-HTTP-2 to the virtual server Vserver-SSL-1. To bind a service to a virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Select the virtual server Vserver-SSL-1, then click Open. The Configure Virtual Server (SSL Offload) dialog box appears. 3. Click the Services tab, then select the checkboxes next to the services Service-HTTP-1 and Service-HTTP-2. 4. Click OK. The services Service-HTTP-1 and Service-HTTP-2 are bound to the virtual server Vserver-SSL-1. Chapter 6 Secure Sockets Layer (SSL) Acceleration 357 Note: The load balancing feature on the NetScaler should be enabled before binding multiple services to a virtual server. For details on enabling features on the NetScaler, refer the Enabling the SSL Feature section. To bind a service to a virtual server using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-SSL-1 Service-HTTP-1 bind lb vserver Vserver-SSL-1 Service-HTTP-2 Binding an SSL Certificate Key Pair to the Virtual Server An SSL certificate is an integral element of the SSL encryption and decryption process. The certificate is used during SSL handshaking to determine the cipher that will be used for SSL processing, and also to establish the identity of the SSL server. You can either use a valid, existing SSL certificate that you have on the NetScaler, or you can create your own SSL certiifcate on the NetScaler. Intermediate certificates created using a FIPS key on the NetScaler cannot be bound to an SSL virtual server. Note: We recommend that you use a valid SSL certificate that has been issued by a trusted certificate authority. Invalid certificates and self-created certificates will not be compatible with all client NetScalers. The following procedure describes the steps to bind an existing SSL certificate, SSL-Certkey-1 to the virtual server Vserver-SSL-1. To bind an SSL certificate key pair to a virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server you want to bind the certificate key pair to. For example, select Vserver-SSL-1, then click Open. The Configure Virtual Server (SSL Offload ) dialog box appears. 3. Click the SSL Settings tab. In the Available area, select the certificate key pair that you want to bind to the virtual server. For example, select SSL- Certkey-1 and click Add. The certificate key pair appears in the Configured area. 4. Click OK. The certificate pair is bound to the virtual server. 358 Installation and Configuration Guide - Volume 1 To bind an SSL certificate key pair to a virtual server using the NetScaler command line At the NetScaler command prompt, type: bind ssl certkey SSL-Certkey-1 Vserver-SSL-1 Adding a Certificate Key Pair Before a certificate can be used for SSL processing, it must be paired with its corresponding key. The certificate key pair that you create is then bound to the virtual server and used for SSL processing. To add a certificate key pair 1. In the left pane, expand SSL and click Certificates. The SSL Certificates page appears in the right pane. 2. Click Add. The Install Certificate dialog box appears. 3. In the Name text box, type the name of the certificate key pair you want to add, for example, Certkey-SSL-1. 4. Under Details, select Remote System. Note: Both the certificate and the key must be present in the same location. To use a certificate present on the local system, in Step 4 above, select Local System. 5. Select the Browse button next to Certificate Filename. The NetScaler file browser appears. Note: You will not be able to load the FIPS key from a local storage device such as a hard disk or flash memory. FIPS keys should always be loaded from the HSM. 6. Select the certificate you want to use and click the Select button. 7. Select the Browse button next to Key Filename. The NetScaler file browser appears. 8. Select the key you want to use and click the Select button. Note: To encrypt the key used in the certificate key pair, in the Password text box, type the password to be used for encryption. Chapter 6 Secure Sockets Layer (SSL) Acceleration 359 9. Click Install. The certificate key pair you created appears in the SSL Certificates window. To add a certificate key pair using the NetScaler command line At the NetScaler command prompt, type: add ssl certkey Certkey-SSL-1 -cert Cert-SSL-1 -key Key-SSL-1 FIPS based systems do not support external keys (non-FIPS keys). On a FIPS system, you will not be able to load keys from a local storage device such as a hard disc or flash memory. The following example describes steps to load a certificate and associate it with its corresponding FIPS key that resides within the HSM. add ssl cer t key Cer t key- SSL- FI PS - cer t Cer t - SSL- Fi ps. pem- f i pskey Key- SSL- FI PS. pem Verifying the Configuration This section explains how to verify the SSL settings you have configured. Viewing the SSL settings can be useful for troubleshooting. Viewing the Properties of the Configured Service You can view the properties of the services created on the NetScaler to ensure that the settings configured have been saved accurately. To view the properties of the configured service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Verify that the configured service Service-HTTP-1 is displayed. 3. Select the service Service-HTTP-1 and in the Details section, verify that the parameters are accurately configured. To view the properties of the configured service using the NetScaler command line At the NetScaler command prompt, type: show service Service-HTTP-1 Viewing the Properties of the Vserver You can view the properties of the virtual servers you have created on the NetScaler to confirm that the settings have been saved accurately. 360 Installation and Configuration Guide - Volume 1 To view the properties of the configured vserver 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offlload Virtual Servers page appears in the right pane. 2. Verify that the configured virtual server Vserver-SSL-1 is displayed and is Enabled. 3. Select the virtual server Vserver-SSL-1 and in the Details section, verify that the parameters are accurately configured. To view the properties of the configured vserver using the NetScaler command line At the NetScaler command prompt, type: show vserver Vserver-SSL-1 Viewing the Properties of the Certificate Key Pairs You can view the properties of the certificate-key pairs created on the NetScaler, to confirm that the settings are accurately configured. To view the properties of the configured certificate key pairs 1. In the left pane, expand SSL, then click Certificates. The SSL Certificates page appears in the right pane. 2. Verify that the configured certificate key pair, Certkey-SSL-1 is displayed. 3. Select the certificate key pair Certkey-SSL-1 and in the Details section, verify that the parameters are accurately configured. To view the properties of the configured certificate key pairs using the NetScaler command line At the NetScaler command prompt, type: show ssl certkey Certkey-SSL-1 Managing Certificates To configure the SSL feature, you need a certificate and a private key for the Web server. An SSL certificate is a digital data form (X509) that identifies a company (domain) or an individual. An SSL key is the private component of the public- private key pair used in asymmetric key encryption (public key encryption). Note: The Application Switch supports a certificate size of up to 2,048 bits (RSA/DSA). Chapter 6 Secure Sockets Layer (SSL) Acceleration 361 You can obtain the SSL certificate and key in one of three ways • From an authorized Certificate Authority (CA), such as VeriSign. • Use an existing SSL certificate and key. • Generate a new SSL certificate and key on the Application Switch. Obtaining a Certificate froma Certificate Authority To obtain an SSL certificate from an authorized certificate authority (CA), you must create a Certificate Signing Request (CSR) and submit it to the CA. The following procedures describe how to create a CSR that you can submit to a CA to obtain a valid certificate. Creating a Private Key Every SSL certificate has a private key associated with it. This key is an integral part of the encryption process and is required by the SSL certificate. The NetScaler allows you to create either an RSA or DSA key which you can then use to create a CSR and obtain a certificate. To create an RSA key 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create RSA Key. The Create RSA Key dialog box appears. 3. In the Key Filename text box, type the name of the RSA key, for example, Key-RSA-1. Note: By default, SSL certificates and keys are stored in the /nsconfig/ssl directory on the NetScaler. If you want to store them elsewhere, use the browse button to navigate to the desired location. 4. In the Key Size (Bits) text box, type the size in bits of the key, for example, 1024. 5. Click Create, then click Close. The RSA key you created is saved on the NetScaler. To create an RSA key using the NetScaler command line At the NetScaler command prompt, type: create ssl rsakey Key-RSA-1 1024 362 Installation and Configuration Guide - Volume 1 To create a DSA key 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create DSA Key. The Create DSA Key dialog box appears. 3. In the Key Filename text box, type the name of the DSA key, for example, Key-DSA-1. Note: SSL certificates and keys are stored by default in the /nsconfig/ssl directory on the NetScaler. If you want to store them elsewhere, use the browse button to navigate to the required location. 4. In the Key Size (Bits) text box, type the size in bits of the key, for example, 1024. 5. Click Create, then click Close. The DSA key you created is saved on the NetScaler. To create an DSA key using the NetScaler command line At the NetScaler command prompt, type: create ssl dsakey Key-DSA-1 1024 For added security, you can encrypt your SSL key using the DES or triple DES (3DES) algorithm. The DES and triple DES options are valid only for keys stored in PEM format, not for keys stored in DER format. Caution: Make sure you limit access to your private key. Anyone who has access to your private key can generate a new CSR and obtain a new certificate using your identity. The certificate that you receive from the CA is valid only with the private key used to create the CSR. The private key is required to add the certificate on the NetScaler. Creating a Certificate Signing Request The certificate signing request (CSR) is a collection of details, including the domain name, other important company details, and the private key to be used to create the certificate. To avoid generating an invalid certificate, you need to ensure that the details provided are accurate. Chapter 6 Secure Sockets Layer (SSL) Acceleration 363 To create a certificate signing request 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create Certificate Request. The Create Certificate Request dialog box appears. 3. In the Request File Name text box, type the name of the CSR, for example Certificate-Request-1. 4. In the Key File Name text box, type the name of the key to be used to create the CSR, for example, Key-RSA-1. Note: You can use the browse button to navigate to the saved key on the NetScaler. 5. Select the format the key was saved in. For example, PEM. 6. In the PEM Passphrase (For Encrypted Key), type the password used to encrypt the key. 7. Under Distinguished Name Fields, enter relevant information for each parameter. The information you enter will form the Distinguished Name (DN) of the company (Web site). 8. Click Create, then click Close. The certificate signing request you created is saved on the NetScaler in the specified location. To create a certificate signing request using the NetScaler command line At the NetScaler command prompt, type: create ssl certreq Certificate-Request-1 -keyFile Key-RSA-1 Next, you need to send the CSR to a CA for authentication and signing. Most CAs accept certificate submissions by email. The CA will return a valid certificate to the email address you used to submit the CSR. Once you have obtained the signed certificate from a CA, install the certificate and its corresponding private key on the NetScaler. Note: For information on configuring a chain of certificates that to be sent on behalf of an SSL virtual server, refer to the section Creating a Chain of Certificates. 364 Installation and Configuration Guide - Volume 1 Exporting Existing Certificates and Keys Instead of purchasing new certificates and keys, you can use versions from an existing secure server. The following sections describe the procedures to transfer a certificate and key from a secure server. Note: For further instructions on exporting keys and certificates, refer to the documentation of the server you are exporting from. Key and certificate names cannot contain spaces or special characters other than those supported by the Unix file system. Be sure to follow the appropriate naming convention when you save the exported key and certificate. The NetScaler supports two encoding formats for keys and certificates: PEM and DER. You must convert the certificate or key file to one of these formats before you install them. Exporting Certificates froman Apache mod_SSL Server The location of the key and certificate files is listed in the $APACHEROOT/conf/ httpd.conf file. The default key is available in $APACHEROOT/conf/ssl.key/ *.key, and the default certificate is available in $APACHEROOT/conf/ssl.crt/ *.crt. Transfer the certificate and key to the NetScaler and follow the installation procedure as described above. Note: Use an FTP client to transfer the certificate and the key to the NetScaler in binary mode. Exporting certificates and keys fromApacheSSL The locations of the key and certificate files are listed in $APACHESSLROOT/ conf/httpd.conf. The default key is available in $APACHEROOT/certs/*.key, and the default certificate is available in $APACHEROOT/certs/*.crt. Transfer the certificate and key to the NetScaler and follow the installation procedure as described above. Note: Use an FTP client to transfer the certificate and the key to the server in binary mode. Chapter 6 Secure Sockets Layer (SSL) Acceleration 365 Exporting Certificates and Keys froma Stronghold Server The locations of the key and certificate files are listed in the $STRONGHOLDROOT/conf/httpd.conf file. The default key is available in $STRONGHOLDROOT/conf/ssl.key/*.key and the default certificate is available in $STRONGHOLDROOT/conf/ssl.crt/*.crt. Transfer the certificate and key to the NetScaler and follow the installation procedure as mentioned above. Note: Use an FTP client to transfer the certificate and the key to the NetScaler in binary mode. Exporting Certificates and Keys froman IIS 4 Server on Windows NT The certificate file is stored in the directory that was specified when the certificate was downloaded from the CA. To export the certificate from an IIS 4 server on Windows NT 1. Double-click the certificate file to open the viewer, then click the Details tab. 2. Click Copy to file. The Certificate Manager Export wizard appears. 3. Click Next. Select the DER-encoded binary X.509 button. 4. Click Next. Type the File Name and Location to store the certificate in the DER format. 5. Click Next, then click Finish. 6. When the notice of succesful completion appears, click OK. 7. Exit the Certificate Manager Export wizard. 8. Close theCertificate Viewer. Note: The certificate is exported in DER format. The keys are located within the Key Ring in the key manager program. 366 Installation and Configuration Guide - Volume 1 To export a key from an IIS 4 server on Windows NT 1. Click the Start button, navigate to Programs>Windows NT 4.0 Option Pack>Microsoft Internet Information Server, then click Internet Service Manager. The Microsoft Management Console appears. 2. Navigate to the Web site using the object list. 3. Right-click the Web site object and click Properties in the shortcut menu. 4. Click theDirectory Security tab. 5. In the Secure Communication panel, click Edit. 6. Click the Key Manager, then select the key to export. 7. On the Key menu, point to Export Key, then click Backup File. 8. Read the security warning, then click OK. 9. Select a file name and location to store the key, then click Save. 10. Exit the Internet Service Manager. The key and certificate file are exported from an IIS server in PKCS#12 (.PFX) format. Convert these to either the PEM or DER format, and install them on the NetScaler as described in the section Binding an SSL Certificate Key Pair to the Virtual Server. Note: For more information on converting the certificate from the PKCS#12 format to the DER or PEM format, refer to the section Importing SSL Certificates. Exporting Certificates froman IIS 5 Server on Windows 2000 To install certificates and keys from an IIS 5 server on Windows 2000, first export the certificate and key, then transform the key and certificate, and install the key and certificate on the NetScaler, as described in the following procedure. To export certificates and keys from an IIS 5 server on Windows 2000 1. Run the Internet Service manager by doing one of the following: • Click Start, select Programs/Administrative Tools, and click Internet Service Manager. or • Open Control Panel > Administrative Tools > Internet Service Manager. Chapter 6 Secure Sockets Layer (SSL) Acceleration 367 2. Right-click the Web site object, then click Properties in the shortcut menu. 3. Click theDirectory Security tab. 4. In the Secure Communications panel, click View Certificate. The Certificate Viewer appears. 5. Click the Details tab, then click Copy to File. 6. In the Certificate Export wizard, click Next. The Export Private Key screen appears. 7. Select Yes to export the private key, then click Next. The Export File Format screen appears. 8. Select Personal Information Exchange—PKCS#12 (pfx) and any optional choices, then click Next. The Password screen appears. 9. In the Password and Confirm Password text boxes, type the password, then click Next. The File to Export screen appears. 10. Type the complete path and file name to the location where you want to save the certificate and key files, then click Next. The Completing the Certificate Export Wizard screen appears. Note: Alternatively, click the browse button and use the Windows Explorer controls to navigate to the folder and file. 11. Click Finish.The files are saved in the specified location. The key and certificate file exported from IIS 5 are in PKCS#12 (.PFX) format and must be converted to PEM or DER format before being loaded on the NetScaler. For more information on converting the certificate format, refer to the section Importing SSL Certificates. Exporting Certificates and Keys fromSun iPlanet To export certificates from Sun iPlanet, you must use the pk12util utility provided by Sun Microsystems. Before you export the certificate using the pk12util utility, you need to do the following • Determine the name of the certificate and/or key pairs you wish to extract (export). The default name is Server-Cert. • Write down the password that was used to protect the database. You will need to provide this password to access the contents of the databases. 368 Installation and Configuration Guide - Volume 1 • Locate the folder where following certificate and key databases are stored: server_root/alias/<serverid-hostname>-key3.db for the key file, and server_root/alias/<serverid-hostname>-cert7.db for the certificate Use the following command to export certificates from Sun iPlanet pk12ut i l - o {out put f i l ename} - n {cer t i f i cat e name} - d {cer t db di r ect or y} [ - P {cer t db name pr ef i x}] The following procedure describes the steps to export the certificate, mySite- cert.db and the key, mySite-key.db, from an iPlanet Web server To export a certificate and key from the Sun iPlanet server 1. Enter the following command: pk12ut i l - o out put . p12 - n Ser ver - Cer t - d c: \ i Pl anet \ ser ver _r oot \ al i as\ - P mySi t e- 2. At the prompt “NSS Certificate DB”: (enter db password) , type the password or pin. 3. At the prompt (enter output password), type the password for the PKCS12 file. 4. At the prompt (re-enter output password), re-type the password. The pk12util utility displays the message “PKCS12 EXPORT SUCCESSFUL” You must provide the complete path to the pk12util binary in the command line interface’s search path. Also put the lib directory ($WEBSERVER_ROOT/bin/ https/lib by default} in front of the LD_LIBRARY_PATH environment variable. For a Solaris server using the Bourne shell, the command to be used is expor t LD_LI BRARY_PATH=${WEBSERVER_ROOT}/ bi n/ ht t ps/ l i b: $LD_LI BRARY_PATH If the error message “Bad database error without -d option” appears, use the -d switch to point to the directory where the certificate and key databases are located. The default names for the certificate and key databases on an iPlanet server are cert7.db and key3.db. iPlanet may prefix the server name with the full machine name for the administrator server and any additional virtual servers that you have defined. In this case, you must include the -P switch with the argument: https- hostname.domain.com-hostname. The exported certificate will be saved in PKCS#12 format and must be converted to PEM or DER format before you install it on the NetScaler. Chapter 6 Secure Sockets Layer (SSL) Acceleration 369 Exporting Certificates and Keys fromBEA WebLogic Server On a BEA WebLogic server, the configured certificate and key are stored in the weblogic.properties file, under weblogic.security.certificate.server, which is a per server directory. To export the certificate file and private key file from the WebLogic server 1. Identify the file where the certificate and key are stored. The path to this file should be displayed in the weblogic.properties file, in the following fields: • The weblogic.security.key.server property field contains the name of the private key file. • The weblogic.security.certificate.server property field contains the name of the certificate file received from the CA. 2. Use an FTP client to transfer the certificate and key in binary mode to the NetScaler. The certificate and key file must be transferred to the NetScaler in the same format. In some versions of BEA WebLogic Server (for example, version 5.0.1), the server allows the key to be exported in DER format and the certificate in PEM format. In such cases, you can convert the DER-encoded key to PEM format using the following OpenSSL tool command: openssl pkcs8 - i n keyf i l e. der - i nf or mDER - out keyf i l e. pem- out f or m PEM Once the certificate and key files are transferred to the NetScaler, install the certificate key pair using the procedures described in the section Binding an SSL Certificate Key Pair to the Virtual Server. Generating a NewCertificate and Key This section provides procedures for creating new certificates and keys on the NetScaler. You configure SSL certificates to identify a domain or an individual in a secure connection. The NetScaler supports SSL certificates that self-signed or signed by a trusted certifying authority. The NetScaler can act as a certifying authority and provide options for creating a certificate request, an encryption key, and signing certificates. Generating a Key This section describes how to generate a key on the NetScaler that can be used for creating certificates 370 Installation and Configuration Guide - Volume 1 Generating an RSA Key For details, see the “To create an RSA key” in the section section Creating a Private Key. Generating a DSA Key For details, see the “To create an DSA key” in the section Creating a Private Key. Generating a DH Key The DH key exchange feature enables support for Diffie-Hellman (DH) key exchange for an SSL virtual server or SSL service on the NetScaler. By default, this feature is disabled. You need to enable this feature to support ciphers that use DH as the key exchange algorithm. The following procedure describes the steps to create a 512 bit DH key, Key-DH- 1 with its DH generator set to 2. To generate a DH key 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Under Tools, click Create Diffe-Hellman (DH) Key. The Create DH Param dialog box appears. 3. In the DH Filename (with path) text box, type the name of the DH key file being created. For example, type Key-DH-1. 4. In the DH Parameter Size (Bits) text box, type the size, in bits of the DH parameter being configured. For example, type 512. Note: The DH key size ranges from 512 to 2048 bits. 5. Under DH Generator, select the value of the DH generator. For example, select 2. To generate a DH key using the NetScaler command line At the NetScaler command prompt, type: create ssl dhparam Key-DH-1 512 -gen 2 Generating a Certificate Signing Request This section describes how to create a certificate signing request (CSR) that you can send to a CA to obtain a certificate. Chapter 6 Secure Sockets Layer (SSL) Acceleration 371 Generating Self- Signed Certificates You can create self-signed certificates using the Citrix NetScaler's built-in CA tools suite. Because these certificates are signed by the NetScaler itself, and not by an actual CA, you should not use them in a production environment, but only for testing purposes. If you attempt to use a self-signed certificate in a production environment, users will receive a "certificate invalid" warning each time the virtual server is accessed. The Citrix NetScaler allows you to create the following types of certificates • Root-CA Certificates • Intermediate CA Certificates • Server Certificates • Client Certificates To create a Root-CA certificate 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create Certificate. The Create Certificate dialog box appears. 3. In the Certificate File Name text box, type the name of the certificate being created, for example, Cert-RootCA-1. Note: Instead of typing the certificate name, you can use the browse button to launch the NetScaler file browser and select the file visually. 4. Select the check box next to the file format of the certificate, for example, PEM. 5. Select the check box next to the type of certificate being created, for example Root-CA. 6. In the Certificate Request File Name text box, type the name of CSR created for the certificate, for example, type Certificate-Request-1. 7. In the Key File Name text box, type the name of the key next to the CSR, for example, Key-RSA-1. 8. Select the radio button next to the format in which the key has been created, for example, select PEM. 9. In the PEM Passphrase (For Encrypted Key) text box, type the password used ot encrypt the key. 372 Installation and Configuration Guide - Volume 1 10. In the Validity Period (Number of Days) text box, type the duration in days the certificate is valid for, for example, 365. 11. Click Create, then click Close. The Root-CA certificate you created is saved on the NetScaler. To create a Root-CA certificate using the NetScaler command line At the NetScaler command prompt, type: create ssl cert Root-CA Certificate-Request-1 PEM ROOT_CERT - keyFile Key-RSA-1 -keyForm PEM -days 365 To create an Intermediate-CA, server or client certificate 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create Certificate. The Create Certificate dialog box appears. 3. In the Certificate File Name text box, type the name of the certificate being created, for example, Cert-IntermediateCA-1. Note: Instead of typing the filename, you can use the browse button to launch the NetScaler file browser and select the file visually. 4. Select the check box next to the file format of the certificate, for example, PEM. 5. Select the check box next to the type of certificate being created, for example Intermediate-CA. 6. In the Certificate Request File Name text box, type the name of CSR created for the certificate, for example, Certificate-Request-2. 7. In the Validity Period (Number of Days) text box, type the duration in days the certificate is valid for, for example, 365. 8. In the CA-Certificate File Name text box, type the name of the CA certificate that will issue this intermediate certificate. For example, Cert- RootCA-1. 9. Select the radio button next to the format in which the CA certificate has been created, for example, PEM. 10. In the CA Key File Name text box, type the name of the key corresponding to the CA certificate, for example, Key-RSA-1. 11. Select the radio button next to the format in which the key has been created, for example, PEM. Chapter 6 Secure Sockets Layer (SSL) Acceleration 373 12. In the PEM Passphrase (For Encrypted CA Key) text box, type the password used to encrypt the key. 13. In the CA Serial Number File text box, type the name of the file to store the serial number of the CA certificate in, for example, Serial-CA-1. 14. Click Create, then click Close. The Intermediate-CA certificate you created is saved on the NetScaler. To create an Intermediate-CA certificate using the NetScaler command line At the NetScaler command prompt, type: create ssl cert Intermediate-CA Certificate-Request-2 PEM INTM_CERT -CAcert Root-CA -CAcertForm PEM -days 365 Note: To create server and client certificates, in step 5, select the radio button next to Server Certificate and Client Certificate and in step 10, select the corresponding intermediate certificate instead of a root certificate. Creating a Chain of Certificates If the server certificate is issued by an intermediate CA (not recognized by standard Web browsers as a trusted CA), the CA certificate(s) must be sent to the client with the server’s own certificate in order for the SSL handshake to proceed successfully. Otherwise, the browser terminates the SSL session, after it fails to authenticate the server certificate. You must create a chain of certificates that will be sent to the client during the SSL handshake. This chain links the server certificate to its issuer (the intermediate CA). In order for this to work, the intermediate CA certificate file must already be installed in the NetScaler. Note: The NetScaler supports sending a maximum of 10 certificates in the chain of certificates sent to the client (one server certificate and nine CA certificates). 374 Installation and Configuration Guide - Volume 1 The following figure shows how certificates are linked in a chain. Linking of a Certificate Chain The following procedure illustrates the steps to link the server certificate Cert- Server to the intermediate CA certificates Cert-Intermediate-A, Cert- Intermediate-B and Cert-Intermediate-C. This procedure assumes that all certificates required for the procedure have been configured correctly on the NetScaler. To create a certificate chain 1. In the left pane, expand SSL, then click Certificates. The SSL Certificates page appears in the right pane. 2. Select the server certificate you want to link, for example, Cert-Server, then click the Link buttton. The Link Server Certificate dialog box appears. 3. Under CA Certificate Name, select the CA certificate to be linked to, for example, Cert-Intermediate-A. 4. Click OK. The server certificate is now linked to the intermediate certificate. To create a certificate chain using the NetScaler command line At the NetScaler command prompt, type: link ssl certkey Cert-Server Cert-Intermediate-A Repeat this procedure for intermediate certificates Cert-Intermediate-A and Cert- Intermediate-B where Cert-Intermediate-A is linked to Cert-Intermediate-B and Cert-Intermediate-B is linked to Cert-Intermediate-C. Chapter 6 Secure Sockets Layer (SSL) Acceleration 375 Managing Certificates and Keys Certificates and their corresponding keys are stored on the NetScaler in either the PEM or DER format, and are installed on the NetScaler as a certificate key pair. The following sections describe how to customize an installed certificate key pair. Replacing an Existing Server Certificate Removing or unbinding a certificate from an SSL virtual server or an SSL service will cause server downtime. The Citrix NetScaler allows certificate key pair bound to SSL virtual servers or SSL services to be updated automatically, without unbinding existing certificates and causing downtime. To update an existing certificate key pair 1. In the left pane expand SSL, then click Certificates. The SSL Certificates page appears in the right pane. 2. Select the certificate you want to update, for example Certkey-SSL-1, then click Update. The Update Certificate dialog box appears. 3. Use the Browse button next to the Certificate Filename and the Key Filename and select the new certificate and key files respectively. 4. In the Password text box, type the password used to encrypt the new key. 5. Click OK. The server certificate Certkey-SSL-1 is now updated with the new certificate and key files. To update an existing certificate key pair using the NetScaler command line At the NetScaler command prompt, type: update ssl certkey Certkey-SSL-1 Certificate-SSL-New -key Key-SSL- New Enabling the Expiry Monitor An expiry monitor configured on the NetScaler provides advance notification to the administrator before a certificate configured on the NetScaler is due to expire. The following procedure describes how to create a monitor that uses the certificate key pair Certkey-SSL-1 to notify the administrator 60 days before the certificate expires To enable an expiry monitor for a certificate 1. In the left pane expand SSL, then click Certificates. The SSL Certificates page appears in the right pane. 2. Select the certificate you want to update, for example Certkey-SSL-1, then click Update. The Update Certificate dialog box appears. 376 Installation and Configuration Guide - Volume 1 3. Select the Enable radio button. 4. In the Notification Period text box, type the required notification period value, for example, 60. Note: The notification period parameter can be set to any value between 10 and 100 days and the default notification period is 30 days. 5. Click OK. An expiry monitor is now configured for the certificate. To enable an expiry monitor for a certificate using the NetScaler command line At the NetScaler command prompt, type: set ssl certkey -expiryMonitor ENABLED -notificationPeriod 60 After you configure an expiry monitor, reporting is carried out through the syslog and nsaudit logs by default. If you want to create SNMP alerts for the same scenario, you must configure them separately. Disabling Domain Checks By default, when the Citrix NetScaler updates an SSL certificate, it checks for matching domain names. For example, if you have a certificate issued to abc.com, and you are updating it with a certificate issued to def.com, the certificate update fails. You can configure the NetScaler to ignore this domain check, so that SSL certificates can be updated across domains. To disable domain check for a certificate 1. In the left pane expand SSL, then click Certificates. The SSL Certificates page appears in the right pane. 2. Select the certificate you want to update, for example Certkey-SSL-1, then click Update. The Update Certificate dialog box appears. 3. Click the No Domain Check checkbox, then click OK. The domain check for the certificate is now disabled. To disable domain check for a certificate using the NetScaler command line At the NetScaler command prompt, type: update ssl certkey -noDomainCheck Managing Global Site Certificates A global site certificate is a special-purpose server certificate that allows export- restricted browsers to upgrade to 128-bit strong encryption . Chapter 6 Secure Sockets Layer (SSL) Acceleration 377 The global site certificate consists of a server certificate and an accompanying intermediate-CA certificate. Export versions of browsers use 40-bit encryption to initiate connections to SSL Web-servers. The server responds to connection requests by sending its certificate. The client and server then decide on an encryption strength based on the server certificate type: • If the server certificate is a normal certificate and not a global site certificate, the export client and server complete the SSL handshake and use 40-bit encryption for data transfer. • If the server certificate is a global site certificate (and if the export client feature is supported by the browser), the export client automatically upgrades to 128-bit encryption for data transfer. If the server certificate is a global site certificate, the server sends its certificate, along with the accompanying intermediate-CA certificate. The browser first validates the intermediate-CA certificate using the Root-CA certificates that come installed in browsers. On successful validation of the intermediate-CA certificate, the server certificate is validated using the intermediate-CA certificate. On successful validation, the browsers renegotiate (upgrade) the SSL connection to 128-bit encryption. With Microsoft Server Gated Cryptography (SGC), if the Microsoft IIS server is configured with an SGC certificate, export clients that receive the certificate renegotiate to 128-bit encryption. Importing a Global Site Certificate To import a global site certificate, first export the certificate and server key from the Web server. Then, before importing the global site certificate, export (convert) the certificate and key to PEM format. Note: For more instructions on exporting certificates and keys for your server type, see the section Exporting an Existing Certificate and Key. . To import a global site certificate 1. Using a text editor, copy the server certificate and the accompanying intermediate-CA certificate into two separate files. The individual PEM encoded certificate will begin with the header ----- BEGIN CERTIFICATE----- and end with the trailer -----END CERTIFICATE-----. 2. Use an FTP client to transfer the server certificate, intermediate-CA certificate, and server-key to the NetScaler. 378 Installation and Configuration Guide - Volume 1 3. Use the following command to identify the server certificate and intermediate-CA certificate from the split files. The NetScaler comes with the openssl tool installed in /usr/bin. At the FreeBSD shell prompt, enter the following command: openssl x509 –i n cer t . pem- t ext | mor e Where cert.pem is one of the split certificate files. Read the Subject field in the command output. For example, Subject: C=US, ST=Oregon, L=Portland, O=Foobar, Inc., OU=IT, CN=www.foobar.com If the CN field in the Subject matches the domain-name of your Web site, then this is the server certificate and the other certificate is the accompanying intermediate-CA certificate. 4. Add the server certificate (and its private key) on the NetScaler. For details on creating a certificate key pair on the NetScaler, refer to the section Adding a Certificate Key Pair. 5. Add the intermediate-CA certificate on the NetScaler. Use the server certificate you created in step 4 to sign this intermediate certificate. For details on creating an Intermediate-CA certificate on the NetScaler, refer to the section Generating Self- Signed Certificates. Note: An intermediate-CA certificate does not require a key. 6. Bind the server certificate to the SSL virtual server. For details on binding the server certificate to the SSL virtual server, refer to the section Binding an SSL Certificate Key Pair to the Virtual Server. Importing and Exporting SSL Certificates All SSL certificates on the NetScaler are stored and used in PEM or DER format. However, other applications (such as client browsers, and some external secure servers) use SSL certificates saved using various PKCS (public key cryptography standard) formats. The NetScaler supports the PKCS#12 format for storing certificates, which is the personal information exchange syntax standard. To allow the NetScaler to inter-operate with these applications, the NetScaler includes a tool for importing and exporting SSL certificates. Chapter 6 Secure Sockets Layer (SSL) Acceleration 379 Importing SSL Certificates The SSL certificate import tool enables you to import certificates from the PKCS#12 format to either the PEM or the DER formats. For additional security, the private key of the imported certificates can be encrypted using the DES or the DES3 algorithms before storing the certificates on the NetScaler. The following procedure describes the steps to import a PKCS#12 certificate Cert-Import-1.pfx into the NetScaler in the PEM format and store it as Cert- Import-1.pem. The private key is further encrypted using the DES algorithm using the passphrase “ImportPassphrase”. To import certificates from the PKCS#12 format 1. In the left pane expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Import PKCS#12. The Import PKCS12 dialog box appears. 3. In the Output File Name text box, type the name of the file to be created, for example, Cert-Import-1.pem. 4. In the PKCS12 File Name text box, type the name of the certificate file to be imported, for example, Cert-Import-1.pfx Note: You can navigate the file system on the NetScaler using the the Browse button. 5. In the Import Password box, type the password that was used to create the PKCS file. 6. Under Encoding Format, select the type of algorithm to be used to encrypt the private key of the imported certificate, for example, DES. 7. In the PEM Passphrase text box, type the password, if any, used to encrypt the key, for example, ImportPassphrase. Note: The PEM Passphrase option is displayed only if either the DES or the DES3 encoding formats are chosen. 8. In the Verify PEM Passphrase text box, type the same passphrase again for confirmation. 9. Click OK. The client certificate you imported is saved on the NetScaler. To import certificates from the PKCS#12 format using the NetScaler command line At the NetScaler command prompt, type: 380 Installation and Configuration Guide - Volume 1 convert ssl pkcs12 Cert-Import-1.pem -import -pkcs12File Cert- Import-1.pfx -des Exporting SSL Certificates The SSL certificate export tool enables you to export certificates saved in PEM or DER format to the PKCS#12 format. Certificates commonly need to be exported to PKCS#12 format in order to install them in a client browser that will be used for client authentication. The following procedure describes the steps to export a client certificate Cert- Client-1 into the PKCS#12 format as Cert-Client-1.pfx. The password used while exporting is ExportPassword and the private key is encrypted using the passphrase PEMPassphrase. To export certificates to the PKCS#12 format 1. In the left pane expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Export PKCS#12. The Export PKCS12 dialog box appears. 3. In the PKCS12 File Name text box, type the name of the PKCS file to be created, for example, Cert-Client-1.pfx. Note: To select an existing file on the NetScaler, click the Browse button and navigate to the required file. 4. In the Certificate File Name text box, type the name of the certificate to be converted, for example Cert-Client-1. 5. In the Key File Name text box, type the name of the key file associated with the certificate, for example, Key-Client-1. 6. In the Export Password text box, type the password to encrypt the exported key with, for example, ExportPassword. 7. In the PEM Passphrase text box, type the password, if any, used to encrypt the key, for example, PEMPassphrase. 8. Click OK. The client certificate you exported is saved on the NetScaler. To export certificates to the PKCS#12 format using the NetScaler command line At the NetScaler command prompt, type: convert ssl pkcs12 Cert-Client-1.pfx -export -certFile Cert-Client- 1 -keyFile Key-Client-1 Chapter 6 Secure Sockets Layer (SSL) Acceleration 381 Configuring Client Authentication With client authentication enabled on an SSL virtual server, the NetScaler asks for the client certificate during SSL handshake for secure connection requests being sent to this virtual server. The NetScaler checks the certificate for normal constraints, such as issuer signature and expiration date. Note: In order for the NetScaler to verify issuer signatures, the CA certificate for the client certificate must be installed on the NetScaler. If the certificate is valid, the NetScaler allows the client to access all secure resources. But if the certificate is found to be old, corrupt, or absent, the NetScaler drops the client request during the SSL handshake. However, an administrator can configure the NetScaler to proceed with the handshake even if the client does not provide a valid certificate. The NetScaler verifies the client certificate by first forming a chain of certificates, starting with the client certificate and ending with the root CA certificate for the client (for example, VeriSign). This chain includes the client certificate. The root CA certificate may contain one or more intermediate CA certificates (if the client certificate is not directly issued by the root CA). In order for the client authentication feature to work properly The CA certificates used in client certificate verification (root CA and any intermediate CA certificates) must be installed in the NetScaler and bound to the SSL virtual server This section describes the procedures involved in configuring client authentication on the NetScaler. Generating Client Certificates A client certificate includes details about the specific client system that will create secure sessions with the NetScaler. (Details of the client system are provided in the certificate.) Each client certificate is unique, and should only be used by one client system. To generate a client certificate, follow the procedure described in the section Generating Self- Signed Certificates. Converting Certificates into PKCS#12 Format Client certificates created on the NetScaler are stored in PEM or DER format, and need to be converted to PKCS#12 format before they are installed on the client system. 382 Installation and Configuration Guide - Volume 1 For details on converting a certificate from PEM or DER format to PKCS#12 format, refer to the section Exporting SSL Certificates. Configuring Client Certificate-Based Authentication on the NetScaler By default, client authentication is disabled on the NetScaler. The procedure described in this section illustrates how to configure client authentication. You can configure the NetScaler to continue with SSL handshake even if the certificate is old, corrupt, or absent. To do this, you need to configure an optional client certificate check. However, if you set the client certificate check option to Mandatory, the NetScaler terminates SSL handshake if the SSL client provides an invalid certificate. Before changing the client certificate check to Optional, be sure to define proper access control policies. Note: This command does not enable client authentication globally for all SSL virtual servers. To enable client certificate-based authentication on the NetScaler 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Select the virtual server for which you want to configure client certificate- based authentication, then click Open. 3. Click the SSL Settings tab, then click SSL Parameters. The Configure SSL Params dialog box appears. 4. In the Others group, select the Client Authentication check box. 5. Under Client Certificate, click Mandatory. Note: To configure optional client authentication, select Optional in step 5 above. 6. Click OK, and in the Configure Virtual Server (SSL Offload) dialog box, click OK. The virtual server is now configured for client authentication. To enable client certificate-based authentication on the NetScaler using the NetScaler command line At the NetScaler command prompt, type: Chapter 6 Secure Sockets Layer (SSL) Acceleration 383 set ssl vserver Vserver-SSL-1 -clientAuth ENABLED -clientCert MANDATORY Binding a CA Certificate to the Virtual Server The client certificate used for client authentication must be issued by a CA certificate present on the NetScaler. This certificate should be bound to the virtual server on the NetScaler that will carry out client authentication. You must bind the CA certificate to an SSL virtual server in such a way that the NetScaler can form a complete certificate chain when it verifies the client certificate. Otherwise, certificate chain formation fails and the client is denied access even if its certificate is valid. You can bind CA certificates to the SSL virtual server in any order. The NetScaler forms the proper order during client certificate verification The following illustration shows an SSL virtual server with three CA certificates bound to it: Cert-CA_A, Cert-CA-B, and the root CA. In the figure, Cert-CA_A is issued by Cert-CA-B, and Cert-CA-B is issued by the root CA. During client authentication, the client certificate issued by Cert-CA-A, or Cert- CA-B, or the root CA is properly verified. . Complete Certificate Chain: All Certificates Bound To bind the CA certificate to the virtual server, follow the procedure described in the section Binding an SSL Certificate Key Pair to the Virtual Server. Repeat this procedure to bind an additional CA certificate or root CA certificate to the SSL virtual server. 384 Installation and Configuration Guide - Volume 1 To create a chain of certificates on the NetScaler, refer to the section Creating a Chain of Certificates. Installing Client Certificates in the Client Browser The client certificate that you generated and converted to PKCS#12 format in the foregoing procedures should be installed in the client browser that will be used to access the secure server. During the SSL handshake, the browser displays a dialog box where you can select the client certificate to use for client authentication To install a client certificate in Internet Explorer 1. Transfer the PKCS#12 converted client certificate to the client computer. 2. Launch Internet Explorer and navigate to Tools > Internet Options. The Internet Options dialog box appears. 3. Click the Content tab, then in the Certificates group, click Certificates. The Certificates dialog box appears. 4. Under Intended Purpose, select Client Authentication. 5. Click the Personal tab, then click the Import button. The Certificate Import Wizard appears. 6. Follow the instructions in the Certificate Import Wizard. The client certificate you imported appears in the list of Personal certificates. 7. Click Close, and in the Internet Options window, click OK. To install a client certificate in Mozilla Firefox 1. Transfer the PKCS#12 converted client certificate to the client computer. 2. Launch the Firefox browser and navigate to Tools > Options. The Options dialog box appears. 3. Click the Advanced icon, then click the Encryption tab. 4. In the Certificates group, click the View Certificates button. The Certificate Manager dialog box appears. 5. Click the Your Certificates tab, then click the Import button. The Windows Explorer appears. 6. Select the client certificate, then click Open. The imported client certificate appears in the Your Certificates list. 7. Click OK. The client certificate is now installed in the Mozilla Firefox browser. Chapter 6 Secure Sockets Layer (SSL) Acceleration 385 Managing Server Authentication By default, the NetScaler will not authenticate the Web server's certificate. It is assumed that the Web server's certificate is trusted by the NetScaler that performs SSL acceleration on behalf of the Web server. However, in certain SSL deployments where data is encrypted end-to-end using SSL, you can authenticate the server. In such a situation, the NetScaler becomes the SSL client and carries out a secure transaction with the SSL server. To enable server authentication, you should bind the CA certificate that signed the server's certificate to the SSL service on the NetScaler as a CA. The following procedure describes the steps to enable server authentication on the service Service-SSL-1 and then bind the CA certificate Cert-CA-1 to the service as a CA certificate. To enable server certificate authentication 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Select the service for which you want to enable server authentication for, for example, Service-SSL-1, then click Open. The Configure Service dialog box appears. 3. Click the SSL Settings tab, then click SSL Parameters. The Configure SSL Params dialog box appears. 4. In the Others group, select the Server Authentication check box. 5. Click OK. Server authentication is now enabled for the service. To enable server certificate authentication using the NetScaler command line At the NetScaler command prompt, type: set ssl service Service-SSL-1 -serverAuth ENABLED To bind the CA certificate to the service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Select the service for which you want to enable server authentication, for example, Service-SSL-1, then click Open. The Configure Service dialog box appears. 3. Under Available Certificates, select the CA certificate you want to bind, for example Cert-CA-1, then click Add as CA. 4. Click OK. The CA certificate is now bound to the SSL service. 386 Installation and Configuration Guide - Volume 1 To bind the CA certificate to the service using the NetScaler command line At the NetScaler command prompt, type: bind ssl service Service-SSL-1 -certkeyName Cert-CA-1 Managing Certificate Revocation Lists A certificate issued by a CA typically remains valid until its expiration date. However, in some circumstances, the CA may revoke the issued certificate before the expiration date (for example, when an owner's private key is compromised, a company's or individual's name changes, or the association between the subject and the CA changes). The CA releases a Certificate Revocation List (CRL) identifying invalid certificates by serial number and issuer. CRLs play an important role in client authentication. In the absence of a CRL, client certificates revoked before their expiration dates would pass the authentication check. CRLs prevent this is from happening. Certificate authorities issue CRLs on a regular basis. You can configure the NetScaler to use a CRL to block client requests that present invalid certificates. Note: By default, CRLs are stored in the /var/netscaler/ssl directory on the NetScaler. Configuring an Existing CRL on the NetScaler Ensure that the CRL file is present in the local storage NetScaler (HDD). In the case of an HA setup, the CRL file must be present on both NetScalers, and the directory path should be the same on both NetScalers To add a CRL on the NetScaler 1. In the left pane, expand SSL and click CRL. The CRL page appears in the right pane. 2. In the CRL Name text box, type the name of the CRL being added, for example, CRL-1. 3. In the CRL File text box, type the name of the CRL file being added, for example, SSL_CRL.pem. Note: To select an existing file on the NetScaler, click the Browse button and navigate to the required file. Chapter 6 Secure Sockets Layer (SSL) Acceleration 387 4. Select the radio button next to the format of the CRL file being added, for example, select PEM. 5. Under CA Certificate, select the CA certificate next to the CRL file. Note: The CA certificate should be installed before loading the CRL. To add a CRL on the NetScaler using the command line At the NetScaler command prompt, type: add ssl crl CRL-1 SSL_CRL.pem -inform PEM Configuring CRL Refresh Parameters The NetScaler can refresh CRLs from a Web location or an LDAP directory. The NetScaler will fetch the CRL from the specified location and update its database. To configure CRL refresh on the NetScaler, use the parameters in the following table. Parameter Description Method The CRL refresh method. Binary Ensure that the CRL file is transferred using the binary mode. Server IP The IP address of the LDAP server. Port The port number used by the LDAP or the HTTP server. URL The URL of the CRL file on the HTTP server used for CRL refresh. This parameter is only used for CRL refresh with the HTTP method. Base DN The path to the CRL file on the LDAP server. Scope Specifies the level below the Base DN where the CRL file should be searched. If the scope is set to One, the CRL file search is carried out upto one level lower than the Base DN in the LDAP file structure. If the scope is set to Base, the CRL file search is carried out at the level of the Base DN in the LDAP file structure. Bind DN The user name for authentication on the LDAP server. This is used if there are user accounts created on the LDAP server. 388 Installation and Configuration Guide - Volume 1 When you specify refresh parameters and an LDAP server, the CRL does not have to be present on the local hard disk drive at the time you execute the command. The first refresh will store a copy on the local hard disk drive, in the path specified by the CRL File parameter. The default path for storing the CRL is /var/netscaler/ssl. The following procedure describes the steps to refresh the CRL file from the LDAP server 10.217.130.2, listening on port 389. The CRL file is searched at the Base DN "dc=flyers, dc=ctxs." To configure CRL auto refresh using LDAP 1. In the left pane, expand SSL, then click CRL. The CRL page appears in the right pane. 2. Select the configured CRL for which you want to update refresh parameters, then click Open. The Configure CRL dialog box appears. 3. Select the Enable CRL Auto Refresh check box. 4. In the CRL Auto Refresh Parameters group, under Method, select LDAP. 5. In the Server IP field, type 10.217.130.2 6. In the Port text box, type 389. 7. In the Base DN text box, type “dc=flyers, dc=ctxs”. 8. Under Interval, select NOW. Note: If the new CRL has been refreshed in the external repository before its actual update time as specified by the LastUpdate field of the CRL, you should immediately refresh the CRL on the NetScaler. 9. Click Create. The CRL for which you configured refresh parameters appears in the CRL page. To configure CRL auto refresh using LDAP using the NetScaler command line At the NetScaler command prompt, type: set ssl crl CRL-1 -refresh ENABLED -server 10.217.130.2 -method LDAP -port 389 -baseDN “dc=flyers, dc=ctxs” -interval NOW Password The password corresponding to the Bind DN for authentication on the LDAP server. Parameter Description Chapter 6 Secure Sockets Layer (SSL) Acceleration 389 The following procedure describes the steps to refresh a CRL file from an HTTP server listening on port 80 at the location specified by the URL http:// 10.102.19.190/CA1.crl To configure CRL auto refresh using HTTP 1. In the left pane, expand SSL, then click CRL. The CRL page appears in the right pane. 2. Select the configured CRL for which you want to update refresh parameters, then click Open. The Configure CRL dialog box appears. 3. Select the Enable CRL Auto Refresh check box. 4. In the CRL Auto Refresh Parameters group, under Method, select HTTP. 5. In the URL text box, type http://10.102.19.190/CA1.crl. 6. In the Port text box, type 80. 7. Under Interval, select NOW. Note: If the new CRL has been refreshed in the external repository before its actual update time as specified by the LastUpdate field of the CRL, you should refresh it immediately on the NetScaler. 8. Click Create. The CRL for which you configured refresh parameters appears in the CRL page. To configure CRL auto refresh using HTTP using the NetScaler command line At the NetScaler command prompt, type: set ssl crl CRL-1 -refresh ENABLED -url http://10.102.19.190/ CA1.crl -method HTTP -port 80 -interval NOW Synchronizing CRLs When the NetScaler performs SSL acceleration, it uses the most recently distributed CRL to prevent clients with revoked certificates from accessing secure resources. If CRLs are updated often, the NetScaler needs an automated mechanism to fetch the latest CRLs from the repository. You can configure the NetScaler to update CRLs automatically at a specified refresh interval or time 390 Installation and Configuration Guide - Volume 1 The NetScaler maintains an internal list of CRLs that need to be updated at regular intervals. At these specified intervals, it scans the list for CRLs that need to be updated, then connects to the remote LDAP server or HTTP server and retrieves the latest CRLs. It then replaces the local CRL list with the new CRLs. Note: If the initial CRL refresh fails, all client-authentication connections with the same issuer as the CRL are rejected as REVOKED until the CRL is successfully refreshed. To synchronize the CRL at a specific time, use the parameters in the following table. Note: If you provide an invalid number for the day of the month or day of the week, the NetScaler adjusts it to the nearest valid value and performs the refresh on that day. You can set the exact time of day the CRL is refreshed, using the parameters under the Time group. Specify time in 24-hour format (HH:MM). Creating a CRL on the NetScaler You can revoke and create CRLs for certificates you have created, or for certificates whose CA certificate you own. To create a CRL on the NetScaler, you need to perform the following tasks: Interval Days Monthly Set the day of the month the CRL refresh will be done. For example, if you want the refresh to be done on the 15th of every month, under Days, select 15. Weekly Set the day of the week the CRL refresh will be done. (Sunday=1, Monday=2, Tuesday=3, Wednesday=4, Thursday=5, Friday=6 and Saturday=7) For example, if you want the refresh to be done on tuesday every week, under Days, select 3. Daily Set the Daily argument if you want the CRL refresh to be carried out every day. Now Use the Now argument when a CRL has been refreshed in the LDAP repository before the update time specified in the LastUpdate field of the CRL. The Now argument forces an immediate refresh of the CRL on the NetScaler Never Specify the number of days after which the CRL should be refreshed. Chapter 6 Secure Sockets Layer (SSL) Acceleration 391 • Revoke invalid certificates • Create a CRL The NetScaler stores the serial number of revoked certificates in an index file. The file is updated for each certificate that is revoked by the CA. The NetScaler creates the index file the first time you revoke a certificate. To revoke a certificate and create a CRL, use the parameters in the following table. The following procedure describes the steps to revoke two invalid certificates Cert-Invalid-1 and Cert-Invalid-2 created by the CA Cert-CA-1 whose corresponding private key is Key-CA-1. The serial numbers for these certificates will be stored in the index file File- Index-1. The index file is then used to create a CRL, CRL-1. To revoke an invalid certificate 1. In the left pane expand SSL, then click CA Tools. The CA Tools page appears in the right pane. Parameter Description CA Certificate File Name The name of the CA certificate that signed the certificate being revoked. In case of CRL creation, this field specifies the name of the CA certificate that is creating the CRL. CA Key Name The name of the private key corresponding to the CA certificate. CA Key Password The password used to encrypt the CA private key, if any. Index File Name The name of the index file that stores the serial number of all revoked certificates. This file is created on the NetScaler (if not present) when the first certificate is revoked. Choose Operation The operation to be performed. Revoke Certificate - Revokes the specified invalid certificate on the NetScaler. Generate CRL - Generates a CRL for all revoked certificates on the NetScaler. Certificate File Name The name of the invalid certificate to be revoked. The certificate is revoked only if it was created using the CA certificate specified in the CA Certificate File Name field. CRL File Name The name of the CRL file being created. This file is specific to the CA certificate named in the CA Certificate File Name field. This file only contains details of certificates issued by the specified CA certificate. 392 Installation and Configuration Guide - Volume 1 2. Click CRL Management. The CRL Management dialog box appears. 3. In the CA Certificate File Name text box, type Cert-CA-1. 4. In the CA Key File Name text box, type Key-CA-1. 5. In the Index File Name text box, type File-Index-1. 6. Under Choose Operation, select Revoke Certificate. 7. In the Certificate File Name text box, type Cert-Invalid-1. 8. Click Create. The invalid certificate Cert-Invalid-1 is now revoked and its serial number updated in the specified index file. Repeat this procedure for the second certificate, Cert-Invalid-2. To revoke a certificate using the NetScaler command line At the NetScaler command prompt, type: create ssl crl Cert-CA-1 Key-CA-1 File-Index-1 -revoke Cert- Invalid-1 To create a CRL 1. In the left pane expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click CRL Management. The CRL Management dialog box appears. 3. In the CA Certificate File Name text box, type Cert-CA-1. 4. In the CA Key File Name text box, type Key-CA-1. 5. In the Index File Name text box, type File-Index-1. 6. Under Choose Operation, select Generate CRL. 7. In the CRL File Name text box, type CRL-1. 8. Click Create. The CRL CRL-1 is created on the NetScaler. To create a CRL using the NetScaler command line At the NetScaler command prompt, type: create ssl crl Cert-CA-1 Key-CA-1 File-Index-1 -genCRL CRL-1 Customizing the SSL Configuration You can use SSL virtual servers and SSL services independently for different deployments. This section describes the procedures to customize the configured virtual servers or services in such deployments. Chapter 6 Secure Sockets Layer (SSL) Acceleration 393 Note: The customizations described in this section are for an SSL virtual server, or an individual SSL service, but not for global SSL system settings. To customize the SSL configuration for an SSL virtual server, first launch the Configure SSL Params dialog box as described below To customize the SSL configuration for an SSL virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Select the virtual server for which you want to customize SSL settings, for example, Vserver-SSL-1, then click Open. The Configure Virtual Server (SSL Offload) dialog box appears. 3. Click the SSL Settings tab, then click SSL Parameters. The Configure SSL Params dialog box appears. To customize the SSL configuration for an SSL virtual server using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 To customize the SSL configuration for an SSL service, first launch the Configure SSL Params dialog box as described below To customize the SSL configuration for an SSL service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Select the service for which you want to customize SSL settings, for example, Service-SSL-1, then click Open. The Configure Service dialog box appears. 3. Click the SSL Settings tab, then click SSL Parameters. The Configure SSL Params dialog box appears. To customize the SSL configuration for an SSL service using the NetScaler command line At the NetScaler command prompt, type: set ssl service Service-SSL-1 394 Installation and Configuration Guide - Volume 1 Configuring Diffe-Hellman (DH) Parameters The DH key exchange feature enables support for Diffie-Hellman (DH) key exchange for an SSL virtual server or SSL service on the NetScaler. DH key exchange is disabled by default. You must enable this feature if you need to support ciphers that use DH as the key exchange algorithm To configure DH key exchange, use the parameters in the following table. In the following example, the DH parameters are configured to refresh the DH key after every 1000 sessions. To configure DH Parameters 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the DH Param group, select the DH check box. 3. In the Refresh Count text box, type 1000. 4. Click OK. The DH parameters are now configured to refresh the DH key after every 1000 sessions. To configure DH Parameters using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -dh ENABLED -dhCount 1000 Parameter Description DH Enable or disable DH key exchange support Refresh Count The refresh count for regeneration of the DH private- public key pair. The default value is zero (0), which specifies infinite use (no refresh). If the refresh count is set, the DH public and private key pairs are re-generated after the usage count for the key pair reaches the configured refresh count. The refresh count is a positive integer value whose value can either be 0 or any other number greater than 500.. File Path The complete path name of the DH parameter file to be installed. The default path is /nsconfig/ssl Chapter 6 Secure Sockets Layer (SSL) Acceleration 395 Configuring Ephemeral RSA This section describes the procedures to enable support for ephemeral RSA key exchange for an SSL virtual server or SSL service. By default, this feature is enabled, with the refresh count set to zero (infinite use). Ephemeral RSA allows export clients to communicate with the secure server even if the server certificate does not support export clients (1024-bit certificate). If you want to prevent export clients from accessing the secure Web object and/or resource, you need to disable the ephemeral RSA key exchange feature. To configure Ephemeral RSA, use the parameters in the following table. The following procedure describes the steps to configure the ephemeral RSA parameters to refresh the eRSA key after every 1000 sessions. To configure Ephemeral RSA 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the Ephemeral RSA group, select the eRSA check box. 3. In the Refresh Count text box, type 1000. 4. Click OK. The ephemeral RSA parameters are now configured to refresh the eRSA key after every 1000 sessions. To configure Ephemeral RSA using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -eRSA ENABLED -eRSACount 1000 Parameter Description eRSA Enable or disable the ephemeral RSA feature. Refresh Count The refresh count for regeneration of the RSA private- public key pair. The default value is zero (0), which specifies infinite use (no refresh). If the refresh count is set, the eRSA key is re-generated after the usage count for the key pair reaches the configured refresh count. The refresh count is a positive integer whose value can either be 0 or any other number greater than 500. 396 Installation and Configuration Guide - Volume 1 Configuring Session Reuse For SSL transactions, establishing the initial SSL handshake requires CPU-intensive public key encryption operations. Most handshake operations are associated with the exchange of the SSL session key (client key exchange message). Session reuse is enabled by default. Enabling session reuse reduces the server load, improves response time, and increases the number of SSL transactions per second (TPS) that can be supported by the server. With session reuse enabled, session key exchange is avoided for session resumption requests received from the client. To configure session reuse, use the parameters as in the following table The following procedure describes the steps to reuse SSL sessions for 600 seconds before clearing them from the cache. To configure session reuse 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the Session group, select the Reuse check box. 3. In the Timeout text box, type 600. 4. Click OK. The NetScaler is now configured to reuse SSL sessions for 600 seconds. To configure session reuse using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -sessReuse ENABLED -sessTimeout 600 Configuring Cipher Redirection During SSL handshake, the SSL client (browser) announces the suite of ciphers that it supports, in the configured order of cipher preference. The SSL server then selects from the cipher list a cipher that matches its own list of configured ciphers. Parameter Description Reuse Enable or disable SSL reuse. Timeout The timeout value in seconds. After the timeout passes, the session is cleared from the cache. The value is a positive integer whose default value is 300 seconds. Chapter 6 Secure Sockets Layer (SSL) Acceleration 397 If the ciphers announced by the client do not match those configured on the SSL server, the SSL handshake fails, and the failure is announced by a cryptic error message displayed in the browser. These messages rarely mention the exact cause of the error. With cipher redirection, you can configure an SSL virtual server to deliver accurate, meaningful error messages when SSL handshake fails. When SSL handshake fails, the NetScaler redirects the user to a previously configured URL, or displays an internally generated error page if no URL is configured. Note: You can configure cipher redirection only for SSL virtual servers, not for SSL services. To configure cipher redirection, use the parameters in the following table. The following procedure describes the steps to redirect the client to http:// redirectURL in case of a cipher suite mismatch. To configure cipher redirection 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the Cipher Redirect group, select the Enable check box. 3. In the Redirect URL text box, type http://redirectURL 4. Click OK. The NetScaler is now configured to redirect clients in case of a cipher suite mismatch. To configure cipher redirection using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -cipherRedirect ENABLED -cipherURL http://redirectURL Parameter Description Enable Enable or disable the Cipher Redirect feature. Redirect URL The URL where the client should be redirected in the case of a cipher suite mismatch. 398 Installation and Configuration Guide - Volume 1 Configuring SSLv2 Redirection During an SSL handshake, if the SSL protocol version supported by the client is not acceptable to the server, the server displays a cryptic error message. You can configure the server to display a precise error message (user-configured or internally generated) advising the client on the next action to be taken. Configuring the server to display this message requires that you set up SSLv2 redirection. The SSLv2 redirect feature is enabled by default (because the SSLv2 protocol is disabled by default for an SSL vserver/service). To configure SSLv2 redirection, use the parameters in the following table. The following procedure describes the steps to redirect the client to http:// sslv2URL for clients that support only the SSLv2 protocol. To configure SSLv2 redirection 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the SSLv2 Redirect group, select the Enable check box. 3. In the SSLv2 URL text box, type http://sslv2URL 4. Click OK. The NetScaler is now configured to redirect clients that only support the SSLv2 protocol. To configure SSLv2 redirection using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -sslv2Redirect ENABLED -sslv2URL http://sslv2URL Parameter Description Enable Enable or disable the SSLv2 redirect.feature. SSLv2 URL The URL where the client is redirected in case of a protocol mismatch. The target IP address must not be the same as the SSL VIP for which the SSLv2 redirect feature is enabled, or the client will go into an infinite loop of redirects. For example, if you have configured SSLv2 redirection for the secure domain https://www.foobar.com, you should not have the redirect URL configured as: https://www.foobar.com/error.html The preferred way is to redirect to a dummy SSL VIP or an HTTP VIP. Chapter 6 Secure Sockets Layer (SSL) Acceleration 399 Configuring SSL Protocol Settings The NetScaler supports the SSLv2, SSLv3, and TLSv1 protocols. Each of these can be set on the NetScaler as required. To configure SSL protocol settings, use the parameters in the following table. The following procedure describes the steps to configure support for the TLSv1 protocol. To configure TLSv1 protocol support 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the SSL Protocol group, select the TLSv1 check box. 3. Click OK.The NetScaler now supports the TLSv1 protocol. To configure TLSv1 protocol support using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -tls1 ENABLED Configuring Advanced SSL Settings To configure advanced SSL settings,use the parameters in the following table Parameter Description SSLv3 Enable or disable support for the SSLv3 protocol TLSv1 Enable or disable support for the TLSv1 protocol SSLv2 Enable or disable support for the SSLv2 protocol Parameter Description 400 Installation and Configuration Guide - Volume 1 The following procedure describes the steps to enable SSL redirect on the NetScaler To enable SSL redirect 1. Launch the Customize SSL Params dialog box, as described earlier. 2. In the Others group, select the SSL Redirect check box. 3. Click OK. SSL redirect is now enabled on the NetScaler. To enable SSL redirect using the NetScaler command line At the NetScaler command prompt, type: set ssl vserver Vserver-SSL-1 -sslRedirect ENABLED SSL Redirect This function enables or disables SSL (HTTPS) redirects for the SSL virtual server. This is required so that messages from the server are redirected properly. The redirect message from the server provides the new location for the moved object. This is contained in the Location HTTP header field. For example, Location: http://www.moved.org/here.html. For an SSL session, if the client browser receives this message, the browser tries to connect to the new location. This breaks the secure SSL session, because the object has moved from a secure site (https://) to an unsecured one (http://). Generally, browsers display a warning message on the screen and prompt the user to continue or disconnect. When enabled, the SSL redirect function automatically converts all such http:// redirect messages to https://. This does not break the client SSL session. SSL Redirect Port Rewrite Insert into the SSL header, the port on which the port rewrite is being performed Client Authentication Enable or disable client certificate-based authentication. Client Certificate Select whether the client certificate check is optional or mandatory. Server Authentication Enable or disable back-end server authentication. This setting is applicable to SSL services only. Clear Text Port This option is used in the SSL Transparent mode (*:443 SSL VIP) to set the clear text data port. The NetScaler uses this port to send decrypted clear text data to the back-end Web servers. The clear text data port can only be set on SSL virtual servers. The data port is valid only for wildcard IP (*)- based SSL offloading. Chapter 6 Secure Sockets Layer (SSL) Acceleration 401 Managing SSL Actions and Policies SSL actions and policies are used to configure vSSL customizations such as SSL insertions, support for outlook Web access, and per-directory client authentication. This section describes the procedures involved in creating these SSL actions and policies and binding them to configured SSL virtual servers and SSL transparent services. Creating SSL Actions To create an SSL action, you need to launch the Create SSL Action dialog box, then create specific SSL actions using the procedures in the sections below. To launch the Create SSL Action dialog box 1. In the left pane, expand SSL, then click Policies. The SSL page appears in the right pane. 2. Click the Actions tab. The SSL Actions page appears. 3. Click Add. The Create SSL Action dialog box appears. To launch the Create SSL Action dialog box using the Netscaler command line At the NetScaler command prompt, type: add ssl action Configuring Per-Directory Client Authentication You can configure client-side authentication on a per-directory basis. In such a configuration, the client authentication is not carried out as part of the initial SSL handshake. Instead, client authentication is configured as an SSL action, and bound to the SSL virtual server or service using the policy infrastructure. In the event of a policy match, SSL handshake is initiated and client authentication is carried out. The following procedure describes the steps to create an SSL action Action-SSL- ClientAuth to configure per-directory client authentication. To configure per directory client authentication 1. Launch the Create SSL Action dialog box as described above. 2. In the Name text box, type Action-SSL-ClientAuth. 3. In the Client Authentication group, select Enabled. 4. Click Create, then click Close. The action Action-SSL-ClientAuth that you created appears in the SSL Actions page. 402 Installation and Configuration Guide - Volume 1 To configure per directory client authenticatoin using the NetScaler command line At the NetScaler command prompt, type: add ssl action -clientAuth DOCLIENTAUTH Configuring Support for Outlook Web Access If your system uses an Outlook Web-access (OWA) server, you must insert a special header field, FRONT-END-HTTPS: ON, in HTTP requests directed to the OWA servers. This is required for the OWA servers to generate URL links as https:// instead of http://. Note: You can only enable Outlook Web Access support for HTTP-based SSL vservers and services. You can not apply it for TCP-based SSL vservers and services. The following procedure describes the steps to create an SSL action, Action-SSL- OWA that enables support for outlook Web access on the NetScaler. To create an SSL action to enable OWA support 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-OWA. 3. In the Outlook Web Access group, select Enabled from the drop-down list. 4. Click Create, then click Close. The action Action-SSL-OWA appears in the SSL Actions page. Note: Outlook Web Access support is applicable only for SSL virtual server based configurations and transparent SSL service based configurations and not for SSL configurations with backend encryption. To create an SSL action to enable OWA support using the NetScaler command line At the NetScaler command prompt, type: add ssl action -OWASupport ENABLED Chapter 6 Secure Sockets Layer (SSL) Acceleration 403 Configuring Insertion Because the NetScaler offloads all SSL-related processing from the servers, the servers only receive HTTP traffic. The NetScaler receives and processes all SSL data and does not pass it to the servers. Under certain circumstances, a user may want certain SSL information to be passed on to the servers. For example, security audits of recent SSL transactions require the client subject name (contained in an X509 certificate) to be logged at the server. This data is inserted into the HTTP header as a name-value pair and sent to the server. The entire client certificate can be inserted into the HTTP header, if required, or only the specific fields from the certificate can be inserted, such as subject, issuer, and so on. Configuring Client Certificate Insertion The client certificate can be inserted in the HTTP header of the request being sent to the Web server. The certificate is inserted in ASCII (PEM) format. You can enable Client Certificate Insertion only for HTTP-based SSL vservers and services. You cannot apply it to TCP-based SSL vservers and services Note: Before client certificate insertion can be carried out, client authentication must be enabled. The following procedure describes the steps to create an SSL action Action-SSL- ClientCert that inserts a new header X-CLIENT-CERT into the HTTP header whose value will contain the entire client certificate. To insert the client certificate 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-ClientCert. 3. In the Client Certificate group, select Enabled from the drop-down list. 4. In the Certificate Tag text box, type X-CLIENT-CERT. 5. Click Create, then click Close. The Action-SSL-ClientCert action appears in the SSL Actions page. To insert the client certificate using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-ClientCert -clientCert ENABLED - clientHeader “X-CLIENT-CERT” 404 Installation and Configuration Guide - Volume 1 Configuring Client Certificate Serial Number Insertion You can configure the NetScaler to insert the client certificate's serial number in the HTTP header of requests being sent to the Web server.You can only enable this insertion for HTTP-based SSL vservers and services. You can not apply it for TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate serial number insertion can be carried out. The following procedure describes the steps to create an SSL action Action-SSL- SerialNumber that inserts a new header X-SERIAL-NUMBER into the HTTP header whose value contains the client certificate’s serial number. To insert the client certificate serial number 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-SerialNumber. 3. In the Client Certificate Serial Number group, select Enabled from the drop down list. 4. In the Serial Number Tag text box, type X-SERIAL-NUMBER. 5. Click Create, then click Close. The action Action-SSL-SerialNumber appears in the SSL Actions page. To insert the client certificate serial number using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-SerialNumber -clientcertSerialNumber ENABLED -certSerialHeader “X-SERIAL-NUMBER” Client Certificate Subject Name (DN) Insertion You can configure the NetScaler to insert the client certificate's subject name (also known as Domain Name [DN]) in the HTTP header of the request being sent to the Web server. You can enable this insertion only for HTTP-based SSL vservers and services. You cannot apply it to TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate subject name insertion can be carried out. Chapter 6 Secure Sockets Layer (SSL) Acceleration 405 The following procedure describes the steps to create an SSL action Action-SSL- SubName that will insert a new header X-SUBJ ECT-NAME into the HTTP header whose value will contain the client certificate’s subject name. To insert the client certificate subject name 1. Launch the Create SSL Action dialog box as described earlier. 2. In the Name text box, type Action-SSL-SubName. 3. In the Client Certificate Subject (DN) group, select Enabled from the drop-down list. 4. In the Subject Tag text box, type X-SUBJ ECT-NAME. 5. Click Create, then click Close. The action Action-SSL-SubName appears in the SSL Actions page. To insert the client certificate subject name using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-SubName -clientcertSubject ENABLED - certSubjectHeader “X-SUBJECT-NAME” Configuring Client Certificate Hash Insertion You can configure the NetScaler to insert the client certificate's hash (signature) in the HTTP header of the request being sent to the Web server. You can only enable this insertion for HTTP-based SSL vservers and services. You cannot apply it to TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate hash insertion can be carried out. The following procedure describes the steps to create an SSL action Action-SSL- CertHash that will insert a new header X-CERT-HASH into the HTTP header whose value contains the client certificate's hash value. To insert the client certificate hash 1. Launch the Create SSL Action dialog bo,x as described earlier. 2. In the Name text box, type Action-SSL-CertHash. 3. In the Client Certificate Hash group, select Enabled from the drop-down list. 4. In the Hash Tag text box, type X-CERT-HASH. 406 Installation and Configuration Guide - Volume 1 5. Click Create, then click Close. The action Action-SSL-CertHash appears in the SSL Actions page. To insert the client certificate hash using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-CertHash -clientcertHash ENABLED - certHashHeader “X-CERT-HASH” Configuring Client Certificate Issuer Insertion You can configure the NetScaler to insert the client certificate’s issuer in the HTTP header of the request being sent to the Web server. You can only enable this insertion for HTTP-based SSL vservers and services. You cannot apply it for other TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate issuer insertion can be carried out. The following procedure describes the steps to create an SSL action Action-SSL- Issuer that inserts a new header X-ISSUER-NAME into the HTTP header whose value contains the client certificate's issuer tag. To insert the client certificate issuer tag 1. Launch the Create SSL Action dialog box as described earlier. 2. In the Name text box, type Action-SSL-Issuer. 3. In the Client Certificate Issuer group, select Enabled from the drop down list. 4. In the Issuer Tag text box, type X-ISSUER-NAME. 5. Click Create, then click Close. The action Action-SSL-Issuer appears in the SSL Actions page. To insert the client certificate issuer tag using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-Issuer -clientCertIssuer ENABLED - certIssuerHeader “X-ISSUER-NAME” Chapter 6 Secure Sockets Layer (SSL) Acceleration 407 Configuring SSL Session ID Insertion You can configure the NetScaler to insert the SSL session ID in the HTTP header of the request being sent to the Web-server. You can only enable this insertion for HTTP based SSL vservers and services. You cannot apply it for other TCP based SSL vservers and services. The following procedure describes the steps to create an SSL action Action-SSL- SessionID is created which inserts a new header X-SESSION-ID into the HTTP header whose value contains the SSL session ID of the client-side SSL session.. To insert the SSL session ID 1. Launch the Create SSL Action dialog box as described earlier. 2. In the Name text box, type Action-SSL-SessionID. 3. In the Session-ID group, select Enabled from the drop down list. 4. In the Session ID Tag text box, type X-SESSION-ID. 5. Click Create, then click Close. The action Action-SSL-SessionID appears in the SSL Actions page. To insert the SSL session ID using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-SessionID -sessionID ENABLED - sessionIDHeader X-SESSION-ID Configuring Cipher Suite Insertion You can configure the NetScaler to insert the cipher suite name negotiated during the SSL handshake into the HTTP header of the request being sent to the Web server. The NetScaler will insert the Cipher-name, SSL protocol, the export/non- export string, and cipher strength bit depending on the type of the browser connecting to the SSL virtual server/service. For example, Cipher-Suite: RC4- MD5 SSLv3 Non-Export 128-bit. You can only enable this insertion for HTTP-based SSL vservers and services. You cannot apply it for other TCP-based SSL vservers and services. The following procedure describes the steps to create an SSL action Action-SSL- Cipher that inserts a new header X-CIPHER-SUITE into the HTTP header whose value contains the cipher suite negotiated during the SSL handshake. To insert the cipher suite 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-Cipher. 3. In the Cipher Suite group, select Enabled from the drop-down list. 408 Installation and Configuration Guide - Volume 1 4. In the Cipher Tag text box, type X-CIPHER-SUITE. 5. Click Create, then click Close. The action Action-SSL-Cipher appears in the SSL Actions page. To insert the cipher suite using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-Cipher -cipher ENABLED -cipherHeader X- CIPHER-SUITE Configuring Client Certificate Not Before Date Insertion You can configure the NetScaler to insert the client certificate’s not-before date in the HTTP header of the request being sent to the Web server. You can only enable this insertion for HTTP-based SSL vservers and services. You cannot apply it for other TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate not-before date insertion can be carried out. The following procedure describes the steps to creat an SSL action Action-SSL- NotBefore is created that inserts a new header X-NOT-BEFORE into the HTTP header whose value contains the client certificate's not-before date. To insert the client certificate not before date 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-NotBefore. 3. In the Client Certificate Not Before Date group, select Enabled from the drop-down list. 4. In the Not Before Tag text box, type X-NOT-BEFORE. 5. Click Create, then click Close. The action Action-SSL-NotBefore appears in the SSL Actions page. To insert the client certificate not before date using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-NotBefore -clientCertNotBefore ENABLED - certNotBeforeHeader X-NOT-BEFORE Chapter 6 Secure Sockets Layer (SSL) Acceleration 409 Configuring Client Certificate Not After Date Insertion You can insert the client certificate’s not-after date in the HTTP header of the request being sent to the Web server. You can only enable this insertion for HTTP-based SSL vservers and services. You cannot apply it for other TCP-based SSL vservers and services. Note: Client authentication must be enabled before client certificate not-after date insertion can be carried out. The following procedure describes the steps to create an SSL action Action-SSL- NotAfter is created that inserts a new header X-NOT-AFTER into the HTTP header whose value contains the client certificate's not-after date. To insert the client certificate not after date 1. Launch the Create SSL Action dialog box, as described earlier. 2. In the Name text box, type Action-SSL-NotAfter. 3. In the Client Certificate Not After Date group, select Enabled from the drop-down list. 4. In the Not After Tag text box, type X-NOT-AFTER. 5. Click Create, then click Close. The action Action-SSL-NotAfter appears in the SSL Actions page. To insert the client certificate not after date using the NetScaler command line At the NetScaler command prompt, type: add ssl action Action-SSL-NotAfter -clientCertNotAfter ENABLED - certNotBeforeHeader X-NOT-AFTER Creating SSL Policies To create SSL policies, use the parameters in the following table. Parameter Description Name The name of the SSL policy. This is a mandatory parameter and cannot be changed. The name must not exceed 31 characters. Rule / Expression The configured rule against which incoming traffic is evaluated to decide whether the policy should be triggered or not. 410 Installation and Configuration Guide - Volume 1 To create an SSL policy 1. In the left pane, expand SSL, then click Policies. The SSL page appears in the right pane. 2. Click Add. The Create SSL Policy dialog box appears. 3. In the Name text box, type the name of the SSL Policy, for example, Policy-SSL-1. 4. Under Request Action, select the configured SSL action that you want to associate with this policy, for example, Action-SSL-1. 5. Under General Named Expressions, choose the built-in general expression ns_true, then click Add Expression. The expression ns_true appears in the Expression text box. Note: The ns_true general expression applies the policy to all successful (200 OK) responses generated by the NetScaler. However, if you need to filter specific responses, you can create policies with a higher level of detail. For information on configuring granular policy expressions, see the "Policies and Expressions" chapter. Click OK, then click Close. The SSL policy that you created, Policy-SSL-1, appears in the SSL Policies page. To create an SSL policy using the NetScaler command line At the NetScaler command prompt, type: add ssl policy Policy-SSL-1 -rule ns_true -reqAction Action-SSL-1 Binding SSL Policies to a Virtual Server The SSL policies that are configured on the NetScaler need to be bound to a virtual server that intercepts traffic directed to the virtual server. If the incoming data matches any of the rules configured in the SSL policy, the policy is triggered and the action associated with it is carried out. The following procedure describes the steps to bind the SSL policy Policy-SSL-1, configured in the previous section, to the SSL virtual server Vserver-SSL-1 on the NetScaler. Request Action The name of the action to be performed in the event of a policy match. The SSL actions configured on the NetScaler are listed in the Request Action drop-down box. Parameter Description Chapter 6 Secure Sockets Layer (SSL) Acceleration 411 To bind an SSL policy to a vserver 1. In the left pane, expand SSL Offload and click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server that you want to bind the responder policy to. For example, select Vserver-SSL-1, then click Open. The Configure Virtual Server (SSL Offload) dialog box appears. 3. Select the Policies tab. The policies configured on the NetScaler appear. 4. Select the check box next to Policy-SSL-1. 5. Click OK. The SSL policy Policy-SSL-1 is bound to the virtual server Vserver-SSL-1. To bind an SSL policy to a virtual server using the NetScaler command line At the NetScaler command prompt, type: bind ssl vserver Vserver-SSL-1 -policyName Policy-SSL-1 Note: You can bind SSL policies globally or to custom bind points on the NetScaler. For more information on binding policies on the NetScaler, refer to the “Policies and Expressions” chapter. Configuring Some Commonly Used SSL Configurations The SSL feature aims at ensuring that data transactions through the NetScaler remain secure. This section describes common SSL configurations, and how to customize the SSL feature for your own deployment. Configuring SSL Offloading with End-to-End Encryption A simple SSL acceleration device terminates SSL traffic (HTTPS), decrypts the SSL records, and forwards the clear text (HTTP) traffic to the back-end Web servers. The clear text traffic is vulnerable to being spoofed, read, stolen, or compromised by individuals who succeed in gaining access to the back-end network devices or Web servers. The SSL acceleration feature provides end-to- end security by re-encrypting the clear text data and using secure SSL sessions to communicate with the back-end Web servers 412 Installation and Configuration Guide - Volume 1 The following figure illustrates end-to-end SSL encryption configured on the NetScaler End-to-end SSL encryption When the NetScaler receives SSL traffic, it terminates the client's SSL session and provides hardware acceleration for SSL session creation and data decryption operations. The data flow in a NetScaler configured for back-end encryption proceeds as follows: • The client connects to a secure site, (for example, https:// www.mysite.com ) configured on the NetScaler (the SSL VIP). • When the sytem receives the HTTPS request, it decrypts the request and applies layer 4-7 content switching techniques and load-balancing policies, then selects the best back-end Web server to serve the request. • The NetScaler opens an SSL session with the selected server. • After establishing the SSL session, the NetScaler encrypts the client's request and sends it securely via the SSL session to the Web server. • The NetScaler decrypts all encrypted response packets from the Web server, then re-encrypts the response data using the client-side SSL session and sends it to the client. The SSL session multiplexing technique reuses the existing SSL sessions with the back-end Web servers, thus avoiding CPU-intensive key exchange (full handshake) operations. This reduces the overall number of SSL sessions on the server, while maintaining end-to-end security. Note: For TCP traffic, follow the procedures given in the sections that follow, but create SSL_TCP services instead of SSL services. To configure SSL with end-to-end encryption, set the parameters as described in the following sections. The following procedure describes the steps to configure the SSL feature in a basic SSL offload set up where an SSL virtual server Vserver-SSL-2 offloads SSL traffic directed to two SSL services, Service-SSL-1 and Service-SSL-2. Chapter 6 Secure Sockets Layer (SSL) Acceleration 413 Adding SSL-based Services The following procedure describes the steps to configure two SSL based services, Service-SSL-1 and Service-SSL-2 with IP addresses 10.102.20.30 and 10.102.20.31, using port number 443 To add an SSL-based service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name text box, type the name of the service being added, for example, Service-SSL-1. 4. In the Server text box, type the IP address of the server to be associated with this service, for example, 10.102.20.30. Note: If the server has been configured already, under Server, select the configured server to be associated with the service. 5. Under Protocol, select SSL. Note: For TCP services, under Protocol, select SSL_TCP. 6. In the Port text box, type the port number for the SSL service to use, for example, 443. 7. Click Create, then click Close. The SSL service you configured appears in the Services page. To create the second service, repeat the procedure, but use the service name Service-SSL-2 and IP address 10.102.20.31. To add an SSL-based service using the NetScaler command line At the NetScaler command prompt, type: add service Service-SSL-1 10.102.20.30 SSL 443 Adding an SSL-based Virtual Server Follow the procedure in the section Adding an SSL-based Virtual Server to add a virtual server Vserver-SSL-2 with an IP address of 10.102.10.20. 414 Installation and Configuration Guide - Volume 1 Binding the SSL Services to the Virtual Server The following procedure describes the steps to bind the services Service-SSL-1 and Service-SSL-2 to the virtual server Vserver-SSL-2. To bind a service to a virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Select the virtual server Vserver-SSL-2, then click Open. The Configure Virtual Server (SSL Offload) dialog box appears. 3. Click the Services tab, then select the check boxes next to the services Service-SSL-1 and Service-SSL-2. 4. Click OK. The services Service-SSL-1 and Service-SSL-2 are bound to the virtual server Vserver-SSL-2. To bind a service to a virtual server using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vsever-SSL-2 Service-SSL-1 bind lb vserver Vserver-SSL-2 Service-SSL-2 Binding an SSL Certificate Key Pair to the Virtual Server To bind an SSL certificate key pair to the virtual server Vserver-SSL-2, follow the procedures described in the section Binding an SSL Certificate Key Pair to the Virtual Server. Configuring Transparent SSL Acceleration In a transparent SSL acceleration setup, SSL clients access secure Web services using the Web server's IP address. The NetScaler is transparent to the clients and there is no need for a virtual IP address on the NetScaler that is different from the server IP address. Transparent SSL acceleration is useful for running multiple applications on the server with the same public IP and also SSL acceleration without using an additional public IP. In this scenario, clients can access different applications using the server's public IP address(es). The NetScaler offloads SSL traffic processing from the Web server and sends either clear text or encrypted traffic (depending on the configuration) to the back-end Web server. All other protocol traffic is transparent to the NetScaler and is bridged to the back-end Web servers. Thus, other applications running on the server are unaffected. There are two modes of transparent SSL acceleration: Chapter 6 Secure Sockets Layer (SSL) Acceleration 415 • Service-based transparent access, where the service type can be SSL or SSL_TCP • Virtual server-based transparent access with a wildcard IP address (*:443) Note: SSL_TCP service is used for non-HTTPS services, for example SMTPS, IMAPS, and so on. Comparison of transparent SSL Accelaration Modes The table below compares SSL service-based acceleration with wildcard IP-based transparent SSL acceleration. Configuring Service-based Transparent SSL Acceleration Enabling transparent SSL acceleration using SSL service mode causes an SSL or SSL_TCP service to be configured with the IP address of the actual back-end Web server. In this configuration, the NetScaler terminates and offloads all SSL processing and sends clear text data to the back-end Web server. The service-based mode allows detailed configuration control at the level of individual services -- you can configure each service with a different certificate, or with a different clear text port. You can also select individual services for SSL acceleration. SSL Service Based SSL VIP with Wildcard IP Configuration control level Individual service Web server farm Number of back-end servers supported 1server per service No limit Nnumber of secure Web sites that can be configured No limit One secure Web site can be configured if specific IP- based SSL Vservers are not configured. In addition to the global *:443 SSL Vserver, if specific IP:443 SSL Vservers are configured, then these Vservers can be part of different secure domains. Back-end encryption Not supported Supported One-arm mode Not supported Not supported Load balancing of back-end servers N/A Not supported 416 Installation and Configuration Guide - Volume 1 The following figure illustrates a sevice-based transparent SSL configuration.. Service-based transparent SSL acceleration You can apply service-based transparent SSL acceleration to data that use different protocols. Set the clear text port of the SSL service to the port on which the clear text data transfer between the SSL service and the server will occur. To configure service-based transparent SSL acceleration for secure HTTP-based data, configure the parameters as described in the following sections. The following procedure describes the steps to configure the SSL feature in a service-based transparent SSL setup. An SSL service, Service-SSL-Transparent is created that offloads SSL traffic directed to the Web server 192.168.1.100. The clear text data between the SSL service and the Web server is transferred using port 8080. Enabling the SSL and Load Balancing Features Follow the procedure given in the section Enabling the SSL Feature and enable the SSL and Load Balancing features on the NetScaler. Creating an SSL Service and Setting its Clear Text Port Create an SSL service Service-SSL-Transparent with an IP address of 192.168.1.100 and set its clear text port to 8080. The clear text port of the service should be set when the service is being created to enable transparent SSL acceleration. For details on creating SSL services on the NetScaler, refer to the section Adding SSL-based Services. Note: The following example sets the clear text port for HTTP-based data. To set the clear text port for non-HTTP data, choose the appropriate protocol in the corresponding steps of the procedure. Binding an SSL Certificate to the Service Because the encrypted data in this configuration needs to be decrypted by the SSL service, you must bind an SSL certificate to the service and then use the certificate for the SSL handshake. Chapter 6 Secure Sockets Layer (SSL) Acceleration 417 The following procedure describes the steps to bind the SSL certificate Certkey-1 to the SSL service Service-SSL-Transparent. For instructions on creating a certificate key pair on the NetScaler, refer to the section Adding a Certificate Key Pair. To bind an SSL certificate to a SSL service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. From the list of configured services, select the service to which you want to bind the certificate key pair. For example, select Service-SSL- Transparent, then click Open. The Configure Service dialog box appears. 3. Select the SSL Settings tab. The configured certificate key pairs configured on the NetScaler are listed in the Available area. 4. Select the certificate key pair that you want to bind to the service and click Add. The certificate key pair appears in the Configured area. 5. Click OK. The certificate pair is bound to the SSL service. To bind an SSL certificate to a SSL service using the NetScaler command line At the NetScaler command prompt, type: bind certkey Service-SSL-Transparent Certkey-SSL-1 -service Configuring a Virtual Server-based Acceleration with a Wildcard IP Address (*:443) When you enable global transparent SSL acceleration using an SSL virtual server, an *: 443 ("any IP address and port number 443") virtual server is configured on the NetScaler. The virtual server can use the SSL protocol for HTTP-based data, or the SSL_TCP protocol for non-HTTP-based data. The virtual server terminates and offloads all SSL processing and sends either clear text or encrypted data to the back-end Web server, depending on the configuration. It is easy to configure an SSL virtual server in wildcard IP address mode, because you can enable SSL acceleration for multiple servers that host secure content of a Web site; to do so, simply add an *: 443 SSL/SSL_TCP virtual server to the NetScaler, and bind the certificate for the secure Web site to this virtual server. In this mode, a single-digital certificate is required for the entire secure Web site, instead of one certificate per server. This results in significant cost savings on SSL certificates and renewals. Wildcard IP address mode also enables centralized certificate management 418 Installation and Configuration Guide - Volume 1 Configuring an SSL Virtual Server with a Wildcard IP Address The following sections explain how to configure a wildcard SSL virtual server on the NetScaler with the clear text port set to the TCP port of the Web servers to which the clear text is to be sent. The NetScaler will terminate and offload all SSL processing, and send clear text data to the Web servers on the port you have configured as the clear text port. The configured wildcard server will automatically learn the servers configured on the NetScaler, therefore you do not need to configure services for a wildcard virtual server. To configure transparent virtual server-based SSL acceleration for secure HTTP- based data, set the parameters as described in the following sections. The following procedure describes the steps to configure a wild card virtual server Vserver-SSL-WildCard with its clear text port set to 8080. Enabling the SSL and Load Balancing Features To enable the SSL and load balancing features on the NetScaler, follow the procedure in the section Enabling the SSL Feature. Configuring a Wildcard SSL Virtual Server A wildcard (*:443) virtual server intercepts incoming traffic directed to any IP address and port number 443. The following procedure describes the steps to create a wild card virtual server Vserver-SSL-WildCard on the NetScaler. To configure a wildcard virtual server 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Server (SSL Offload) dialog box appears. 3. In the Name text box, type the name of the virtual server to be created, for example Vserver-SSL-WildCard. 4. In the IP Address text box, type *. 5. Under Protocol, select SSL. 6. In the Port text box, type the port number for the virtual server to use. For example, type 443. 7. Click Create, then click Close. The virtual server you created appears in the SSL Offload Virtual Servers page. To configure a wildcard virtual server using the NetScaler command line At the NetScaler command prompt, type: Chapter 6 Secure Sockets Layer (SSL) Acceleration 419 add vserver Vserver-SSL-WildCard SSL * 443 Setting the Clear text Port for the Wildcard Virtual Server Set the clear text port of the wildcard virtual server Vserver-SSL-WildCard to 8080. To set the clear text port on an SSL virtual server, refer to the section Configuring Advanced SSL Settings. Note: This example describes the preocedure to set the clear text port for HTTP-based data. To set the clear text port for non-HTTP data, substitute the appropriate choices in the procedure. Binding an SSL Certificate Key Pair to the Virtual Server Follow the procedures in the section Binding an SSL Certificate Key Pair to the Virtual Server to bind an SSL certificate key pair to the virtual server Vserver- SSL-WildCard. Configuring SSL VIP-based Transparent Access with End-To-End Encryption The following sections explain how to configure a wildcard SSL virtual server on the NetScaler with no clear text port specified. The NetScaler will terminate and offload all SSL processing and send the encrypted data to the Web servers on the port configured on the wildcard virtual server, using a secure SSL session. Note: In this scenario, the SSL acceleration feature runs at the back end using the default configuration, with all 34 ciphers available. To configure end-to-end encryption on a global transparent wildcard virtual server, follow the procedure in the sectionConfiguring a Virtual Server-based Acceleration with a Wildcard IP Address (*:443) but do not configure a clear text port on the virtual server. Configuring the SSL feature with HTTP on the Front End and SSL on the Back-end. In this setup, an HTTP virtual server is configured on the NetScaler with SSL services bound to the virtual server. The NetScaler receives HTTP requests from the client on the configured HTTP virtual server, encrypts the data received, and sends the encrypted data to the Web servers using a secure SSL session. 420 Installation and Configuration Guide - Volume 1 This configuration is useful when you need complete end-to-end security and interaction with certain devices that can communicate only in clear text (for example, caching devices). The following figure shows the configuration HTTP on the front end and SSL on the back-end The following sections describe the procedures to configure an HTTP virtual server on the front end, with SSL services on the back end. The following procedure describes the steps to configure an HTTP virtual server Vserver-HTTP-1 with an IP address 192.168.1.100 running on port 80, and bind to it two SSL services, Service-SSL-1 with IP address 192.168.10.20 and Service-SSL-2 with IP address 192.168.10.30 to it. Enabling the SSL and Load Balancing Features Follow the procedure in the section Enabling the SSL Feature and enable the SSL and Load Balancing features on the NetScaler. Creating SSL Services Create two SSL services Service-SSL-1 and Service-SSL-2 with IP addresses 192.168.10.20 and 192.168.10.30. For a detailed explanation of creating SSL services on the NetScaler, refer to the section Adding SSL-based Services. Adding an HTTP Virtual Server Create a load balancing HTTP virtual server Vserver-HTTP-1 with IP address 192.168.1.100 running on port 80. To create a HTTP virtual server 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Servers (Load Balancing) dialog box appears. Chapter 6 Secure Sockets Layer (SSL) Acceleration 421 3. In the Name, IP Address, and Port text boxes, type Vserver-HTTP-1, 192.168.1.100, and 80. 4. Under Protocol, select HTTP. 5. Click Create and click Close. The vserver you created appears in the Load Balancing Virtual Servers page. To create a HTTP virtual server using the NetScaler command line At the NetScaler command prompt, type: add lb vserver Vserver-LB-1 HTTP 192.168.1.100 80 Binding SSL Services to the HTTP Virtual Server The following procedure describes the steps to bind the SSL services Service- SSL-1 and Service-SSL-2 to the virtual server Vserver-HTTP-1. To bind a service to an HTTP virtual server 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Select Vserver-HTTP-1 and click Open. The Configure Virtual Server (Load Balancing) dialog box appears. The services appear in the Services tab. 3. Select the Active check box next to Service-SSL-1 and click OK.The SSL service is bound to the HTTP virtual server. To bind a service to an HTTP virtual server using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-HTTP-1 Service-SSL-1 Note: To bind the SSL service Service-SSL-2 to the virtual server, repeat the procedure but in step 3, select the check box next to Service-SSL-2. Configuring SSL Offloading with Other-TCP Protocols In addition to the HTTPS protocol, the NetScaler supports SSL acceleration for other TCP-based application protocols. However, only simple requests and response-based TCP application protocols are supported. Applications that insert the server's IP address and port information in their payload are currently not supported (for example, FTPS). 422 Installation and Configuration Guide - Volume 1 Note: The STARTTLS feature for SMTP is currently not supported. Two modes are supported for SSL acceleration of Other-TCP protocols. • SSL acceleration without end-to-end encryption • SSL acceleration with end-to-end encryption Configuring SSL_TCP Based Offloading You can only configure SSL_TCP-based offloading if the SSL virtual server that receives incoming traffic is of type SSL_TCP, and the services that it sends traffic are of type TCP. SSL_TCP-based offloading is required if you need to configure the NetScaler to offload secure TCP-based traffic (such as SFTP) destined to a TCP-based server. To configure SSL_TCP-based offloading, follow the procedure described in the section Configuring an SSL Virtual Server for Basic SSL Offloading but create TCP services instead of HTTP services, and create an SSL_TCP virtual server instead of an SSL virtual server. Configuring SSL_TCP Based Offloading with End-to- End Encryption You can only configure SSL_TCP-based offloading with end-to-end encryption if the SSL virtual server that receives incoming traffic is of type SSL_TCP, and the services that it sends traffic to are also of type SSL_TCP. SSL_TCP-based offloading with end-to-end encryption is required if the NetScaler must offload secure TCP-based traffic (such as SFTP) destined to a TCP-based server. To configure SSL_TCP-based offloading, follow the procedure described in the section Configuring SSL Offloading with End-to-End Encryption but create an SSL_TCP virtual server instead of an SSL virtual server. Configuring End-to-End Encryption for TCP Based Data The NetScaler can provide SSL acceleration with back-end encryption for non- SSL TCP traffic arriving from the client. In this case, the client requests are formatted as clear text, and the NetScaler forwards them to the appropriate TCP server after encryption. To configure end-to-end encryption for TCP-based data, follow the procedure described in the section Configuring the SSL feature with HTTP on the Front End and SSL on the Back-end. but create a TCP virtual server instead of an HTTP virtual server. Chapter 6 Secure Sockets Layer (SSL) Acceleration 423 Configuring SSL Bridging SSL bridge functionality allows all secure traffic to be transparently bridged directly to the back-end Web server. The NetScaler does not accelerate this traffic. In this scenario, the Web server must handle all SSL-related processing. To configure SSL bridging, you need to enable the load balancing feature on the NetScaler. Note: It is advisable to use this configuration only if an acceleration unit (for example, a PCI-based SSL accelerator card) is installed in the Web server to handle the SSL processing overhead. In an SSL bridge setup, the NetScaler is configured to load balance and maintain server persistency for secure requests. Other features, such as content switching, Sure ConnectTM, and cache redirection do not work, because the traffic passing through the SSL accelerator is encrypted.. The following figure illustrates this configuration NetScaler configured for SSL bridging Because the NetScaler does not carry out any SSL processing in an SSL bridging setup, there is no need for SSL certificates. To configure SSL bridging, configure the parameters as described in the sections that follow. The sections that follow describe how to configure SSL bridging. The procedures explain the steps to configure SSL bridging on a NetScaler with two SSL_BRIDGE services (Service-SSL_Bridge-1 and Service-SSL_Bridge-2 with IP addresses 192.168.1.100 and 192.168.1.101), and bind them to an SSL_BRIDGE virtual server Vserver-SSL_Bridge-1, with IP address 192.168.1.10. Enabling the Load Balancing Feature You can find the load balancing feature under Basic Features on the Citrix NetScaler. 424 Installation and Configuration Guide - Volume 1 To enable the load balacing feature 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 2. In the Modes & Features group, click the Basic Features link. The Configure Basic Features dialog box appears. 3. Select the Load Balancing check box, then click OK. When the Enable/ Disable Feature(s)? message appears, Click Yes.The Load Balancing feature is enabled on the NetScaler. To enable the load balacing feature using the NetScaler command line At the NetScaler command prompt, type: enable ns feature lb Configuring SSL_BRIDGE Services The following procedure describes the steps to create two SSL_BRIDGE services Service-SSL_Bridge-1 and Service-SSL_Bridge-2 with IP addresses 192.168.1.100 and 192.168.1.101 respectively. To create an SSL_BRIDGE service 1. In the left pane, expand SSL Offload, then click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name, Server and Port text boxes, type Service- SSL_Bridge-1, 192.168.1.100 and 443. Note: If the server is already configured, under Server, select the configured server to associated with the service. 4. Under Protocol, select SSL_BRIDGE. 5. Click Create, and click Close. The SSL_BRIDGE service you configured appears in the Services page. To create an SSL_BRIDGE service using the NetScaler command line At the NetScaler command prompt, type: add service Service-SSL_Bridge-1 192.168.1.100 SSL_BRIDGE 443 Note: To create the service Service-SSL_Bridge-2, repeat the procedure, but in step 3, type Service-SSL_Bridge-2, 192.168.1.101 and 443 respectively. Chapter 6 Secure Sockets Layer (SSL) Acceleration 425 Configuring an SSL_BRIDGE Virtual Server The following procedure describes steps to create an SSL_BRIDGE virtual server Vserver-SSL_Bridge-1 with IP address 192.168.1.10. To create an SSL_BRIDGE virtual server 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Servers (Load Balancing) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type Vserver-SSL_Bridge- 1, 192.168.1.10, and 443. 4. Under Protocol select SSL_BRIDGE. 5. Click Create and click Close. The virtual server you created appears in the Load Balancing Virtual Servers page. To create an SSL_BRIDGE virtual server using the NetScaler command line At the NetScaler command prompt, type: add vserver Vserver-SSL_Bridge-1 SSL_BRIDGE 192.168.1.10 443 Binding Services to the Virtual Server The following procedure describes the steps to bind the SSL_BRIDGE services Service-SSL_Bridge-1 and Service-SSL_Bridge-2 to the virtual server Vserver- SSL_Bridge-1. To bind an SSL_BRIDGE service to an SSL_BRIDGE virtual server 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Select Vserver-SSL_Bridge-1 and click Open. The Configure Virtual Server (Load Balancing) dialog box appears and lists the configured SSL_BRIDGE services appear in the Services tab. Note: The services tab only shows services of type SSL_BRIDGE; no other services configured on the NetScaler are listed.. 3. Select the Active check box next to Service-SSL_Bridge-1 and click OK.The SSL_BRIDGE service is bound to the SSL_BRIDGE virtual server. To bind an SSL_BRIDGE service to an SSL_BRIDGE virtual server using the NetScaler command line 426 Installation and Configuration Guide - Volume 1 At the NetScaler command prompt, type: bind lb vserver Vserver-SSL_Bridge-1 Sevice-SSL_Bridge-1 Note: To bind the SSL_BRIDGE service Service-SSL_Bridge-2 to the virtual server, repeat the procedure, but in step 3 select the check box next to Service- SSL_Bridge-2. Configuring the SSL Feature for Common Used Deployment Scenarios The following section describes some common deployment scenarios for the SSL feature. The values for various parameters (such as IP addresses, site names, certificates, and so on) are specific to the lab network at Citrix. Configuring an SSL Virtual Server for Load Balancing When the NetScaler receives a client request, it performs load balancing in the following sequence • The NetScaler chooses a Web server, based on the load balancing policies you have configured. • The request is then sent to the server IP address, based on the NetScaler's mapped IP address. Chapter 6 Secure Sockets Layer (SSL) Acceleration 427 The example configuration discussed in the following sections illustrates a simple load balancing SSL setup with two HTTP services bound to an SSL virtual server. The load balancing policy type is the default (LEASTCONNECTION). The following figure shows the topology of the setup. SSL vserver used for load balancing To configure load balancing on the NetScaler, you must first create an SSL-based load balancing virtual server and two HTTP-based services, then bind the services and an SSL certificate to the virtual server. The following table lists the entities that you must configure to enable load balancing on the NetScaler. Enable the SSL and Load Balancing Features For instructions to enable the SSL offloading and load balancing features on the NetScaler, refer to the section Enabling the SSL Feature. Entity Type Name Value SSL Virtual Server Vserver-SSL-LB 192.168.1.10:443 HTTP Service Service-HTTP-1 192.168.1.100:80 Service-HTTP-2 192.168.1.101:80 SSL Certificate Certkey-1 428 Installation and Configuration Guide - Volume 1 Create HTTP Services Create two HTTP services Service-HTTP-1 and Service-HTTP-2 with IP addresses 192.168.1.100 and 192.168.1.101, and using port number 80. For details on creating HTTP services, refer to the section Adding HTTP-based Services. Create an SSL Virtual Server Create an SSL virtual server, Vserver-SSL-LB with IP address 192.168.1.10 running on port 443. For details on creating an SSL virtual server, refer to the section Adding an SSL- based Virtual Server. Bind an SSL Certificate Key Pair to the Virtual Server Bind the certkey Certkey-1 to the virtual server Vserver-SSL-LB. For details on binding a certificate key pair to a virtual server, refer to the section Binding an SSL Certificate Key Pair to the Virtual Server. Bind the HTTP Services to the Virtual Server Bind the HTTP services Service-HTTP-1 and Service-HTTP-2 to the virtual server Vserver-SSL-LB. For details on binding HTTP services to a virtual server, refer to the section Binding the HTTP Services to the Virtual Server. Configuring a Secure Content Switching Server An SSL-based content switching virtual server can redirect incoming data traffic to the appropriately configured servers based on the data traffic's content type. The incoming client request is sent to the NetScaler and decrypted by the SSL virtual server and the clear text request is forwarded to the content switching virtual server. The NetScaler then chooses a Web server based on the content switching policies you have configured. The request is then sent to the server IP address using the NetScaler's mapped IP address. The following procedure describes the steps to configuretwo address-based virtual servers to perform load balancing on the HTTP services. One virtual server, Vserver-LB-HTML, load balances the dynamic content (cgi,asp), and other, Vserver-LB-Image, load balances the static content (gif,jpeg). The load- balancing policy used is the default LEASTCONNECTION. A content-switching SSL virtual server, Vserver-CS-SSL, is then created to peform SSL acceleration and switching of HTTPS requests based on the configured content-switching policies. The address-based virtual servers are bound to the SSL-based content switching virtual servers using content switching policies. Chapter 6 Secure Sockets Layer (SSL) Acceleration 429 The following figure shows the topology of this scenario. SSL vserver used for content switching The following table summarizes the names and values of the entities that you must configure on the NetScaler. Entity Type Name Value HTTP Service Service-HTTP-1 192.168.1.100:80 Service-HTTP-2 192.168.1.101:80 Service-HTTP-3 192.168.1.102:80 Service-HTTP-4 192.168.1.103:80 Load Balancing Virtual Server Vserver-LB-HTML 192.168.1.10:80 Vserver-LB-Image 192.168.1.20:80 SSL based CS Virtual Server Vserver-SSL-CS 10.102.1.100:443 Certificate Certkey-1 430 Installation and Configuration Guide - Volume 1 Enable the SSL, Load Balancing and Content Switching Features For information about the procedures to enable the SSL offloading, content switching and load balancing features on the NetScaler, refer to the section Enabling the SSL Feature. Create HTTP Services Create four HTTP services with the names, IP addresses and port numbers shown in the following table. For details on creating HTTP services, refer to the section Adding HTTP-based Services. Create Load Balancing Virtual Servers Create two HTTP based load balancing virtual servers, Vserver-LB-HTML, with IP address 192.168.1.10 to serve dynamic content, and create Vserver-LB-Image with IP address 192.168.1.20 to serve static content. The following procedure describes the steps to create an HTTP-based virtual server, Vserver-LB-HTML, with IP address 192.168.1.10, using port 80. To create a load balancing virtual server 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. In the Load Balancing Virtual Servers page, click Add. The Create Virtual Servers (Load Balancing) dialog box appears. 3. In the Name, IP Address, and Port text boxes, type Vserver-LB-HTML, 192.168.1.10, and 80 respectively. 4. Under Protocol, select HTTP. 5. Click Create and click Close. The virtual server that you have created, appears in the Load Balancing Virtual Servers page. To create a load balancing virtual server using the NetScaler command line At the NetScaler command prompt, type Name IP Address : Port Service-HTTP-1 192.168.1.100:80 Service-HTTP-2 192.168.1.101:80 Service-HTTP-3 192.168.1.102:80 Service-HTTP-4 192.168.1.103:80 Chapter 6 Secure Sockets Layer (SSL) Acceleration 431 add lb vserver Vserver-LB-HTML HTTP 192.168.1.10 80 Note: To create the Vserver-LB-Image virtual server, repeat the procedure, but in step 3, type Vserver-LB-Image, 192.168.1.20, and 80. Bind the HTTP Services to the Virtual Server Bind the HTTP services Service-HTTP-1 and Service-HTTP-2 to the virtual server Vserver-SSL-HTML, and bind the services Service-HTTP-3 and Service- HTTP-4 to the virtual server Vserver-SSL-Image. For details on binding HTTP services to a virtual server, refer to the section Binding the HTTP Services to the Virtual Server. Create an SSL Based Content Switching Virtual Server Create an SSL-based content switching virtual server, Vserver-CS-SSL, with IP address 10.102.1.100, running on port 443. This is the virtual server that receives incoming client requests and processes them based on the configured policies. To add a content switching vserver 1. In the left pane, expand Content Switching and click Virtual Servers. The Content Switching Virtual Servers page appears in the right pane. 2. In the right pane, click Add. The Create Virtual Server (Content Switching) dialog box appears. 3. In the Name text box, type Vserver-CS-SSL. 4. In the IP Address text box, type 10.102.1.100. 5. Under Protocol, select SSL. 6. In the Port text box, type 443. 7. Click Create and click Close. The virtual server that you have created appears in the Content Switching Virtual Servers page. To add a content switching vserver using the NetScaler command line At the NetScaler command prompt, type: add cs vserver Vserver-CS-SSL 10.102.1.100 443 Creating Content Switching Policies Create content switching policies that will send requests for different types of content to different configured virtual servers on the NetScaler. These policies are then bound to the content switching virtual server configured earlier. 432 Installation and Configuration Guide - Volume 1 For details about creating content switching policies on the NetScaler, refer to the section Adding Content Switching Policies in the Content Switching chapter. Bind an SSL Certificate Key Pair to the Virtual Server Bind the certkey Certkey-1 to the virtual server Vserver-CS-SSL. For details on binding a certificate key pair to a virtual server, refer to the section Binding an SSL Certificate Key Pair to the Virtual Server. Configuring a Secure Content Switching Server with End-to-End Encryption To ensure the security of communications between the content switching virtual server and the Web servers, you can configure end-to-end encryption using the secure content switching setup described earlier. In this setup, the static and dynamic content servers both use SSL encryption. Follow the procedure described in the section Configuring a Secure Content Switching Server but create SSL services instead of HTTP services, and bind them to the SSL virtual server. You can also configure the NetScaler for SSL and content switching, with end-to- end security only for confidential text-based data. With this setup, images and other static content can travel in clear text format between the NetScaler and the back-end Web-server. To set up such a configuration, create SSL services to handle the text-based data and HTTP services for images, thenfollow the procedure in the section Configuring a Secure Content Switching Server. In this type of setup, the dynamic content server uses back-end encryption, but the static content servers communicate in clear text. Because *.gif and *.jpeg images do not have to travel in encrypted format between the NetScaler and the Web servers, you can bind HTTP services to the load balancing virtual servers that serve static content. Some advantages of such a setup are: • Server overhead is decreased and response time is improved because the static content servers communicate with the NetScaler in clear text. • Overall site performance is improved by decreasing SSL overhead for encryption, decryption, and other SSL activities involved in handling client requests for static content. Chapter 6 Secure Sockets Layer (SSL) Acceleration 433 Note: In the above configuration, the cache devices are configured to send all cache-misses to the HTTP virtual server configured on the NetScaler. The NetScaler re-encrypts the requests and sends them using the secure SSL session to the SSL services bound to the HTTP virtual server. Supported Cipher Suites The following table lists the ciphers supported by the SSL acceleration feature. Table 1: Default Ciphers supported by the NetScaler C i p h e r N a m e P r o t o c o l K e y E x c h a n g e K e y S i z e A u t h e n t i c a t i o n E n c r y p t i o n ( K e y S i z e ) M e s s a g e A u t h e n t i c a t i o n SSL3-RC4-MD5 SSLv3 RSA RSA RC4(128) MD5 SSL3-RC4-SHA SSLv3 RSA RSA RC4(128) SHA1 SSL3-DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1 TLS1-AES-256-CBC-SHA TLSv1 RSA RSA AES(256) SHA1 TLS1-AES-128-CBC-SHA TLSv1 RSA RSA AES(128) SHA1 SSL3-EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1 TLS1-DHE-DSS-RC4-SHA TLSv1 DH DSS RC4(128) SHA1 TLS1-DHE-DSS-AES-256-CBC-SHA TLSv1 DH DSS AES(256) SHA1 TLS1-DHE-DSS-AES-128-CBC-SHA TLSv1 DH DSS AES(128) SHA1 SSL3-EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1 TLS1-DHE-RSA-AES-256-CBC-SHA TLSv1 DH RSA AES(256) SHA1 TLS1-DHE-RSA-AES-128-CBC-SHA TLSv1 DH RSA AES(128) SHA1 434 Installation and Configuration Guide - Volume 1 Table 2: Additional Ciphers supported by the NetScaler C i p h e r N a m e P r o t o c o l K e y E x c h a n g e K e y S i z e A u t h e n t i c a t i o n E n c r y p t i o n ( K e y S i z e ) M e s s a g e A u t h e n t i c a t i o n SSL3-RC4-MD5 SSLv3 RSA RSA RC4(128) MD5 SSL3-RC4-SHA SSLv3 RSA RSA RC4(128) SHA1 SSL3-DES-CBC3-SHA SSLv3 RSA RSA 3DES(168) SHA1 SSL3-DES-CBC-SHA SSLv3 RSA RSA DES(56) SHA1 TLS1-EXP1024-RC4-SHA TLSv1 RSA(1024) RSA RC4(56) SHA1 Export TLS1-EXP1024-DES-CBC-SHA TLSv1 RSA(1024) RSA DES(56) SHA1 Export TLS1-AES-256-CBC-SHA TLSv1 RSA RSA AES(256) SHA1 TLS1-AES-128-CBC-SHA TLSv1 RSA RSA AES(128) SHA1 SSL3-EXP-RC4-MD5 SSLv3 RSA(512) RSA RC4(40) MD5 Export SSL3-EXP-DES-CBC-SHA SSLv3 RSA(512) RSA DES(40) SHA1 Export SSL3-EXP-RC2-CBC-MD5 SSLv3 RSA(512) RSA RC2(40) MD5 Export SSL2-RC4-MD5 SSLv2 RSA RSA RC4(128) MD5 SSL2-DES-CBC3-MD5 SSLv2 RSA RSA 3DES(168) MD5 SSL2-RC2-CBC-MD5 SSLv2 RSA RSA RC2(128) MD5 SSL2-DES-CBC-MD5 SSLv2 RSA RSA DES(56) MD5 SSL2-RC4-64-MD5 SSLv2 RSA RSA RC4(64) MD5 SSL2-EXP-RC4-MD5 SSLv2 RSA(512) RSA RC4(40) MD5 Export SSL3-EDH-DSS-DES-CBC3-SHA SSLv3 DH DSS 3DES(168) SHA1 SSL3-EDH-DSS-DES-CBC-SHA SSLv3 DH DSS DES(56) SHA1 TLS1-EXP1024-DHE-DSS-DES- CBC-SHA TLSv1 DH(1024) DSS DES(56) SHA1 Export TLS1-DHE-DSS-RC4-SHA TLSv1 DH DSS RC4(128) SHA1 Chapter 6 Secure Sockets Layer (SSL) Acceleration 435 TLS1-EXP1024-DHE-DSS-RC4- SHA TLSv1 DH(1024) DSS RC4(56) SHA1 Export TLS1-DHE-DSS-AES-256-CBC- SHA TLSv1 DH DSS AES(256) SHA1 SSL3-EXP-EDH-DSS-DES-CBC- SHA SSLv3 DH(512) DSS DES(40) SHA1 Export TLS1-DHE-DSS-AES-128-CBC- SHA TLSv1 DH DSS AES(128) SHA1 SSL3-EDH-RSA-DES-CBC-SHA SSLv3 DH RSA DES(56) SHA1 SSL3-EDH-RSA-DES-CBC3-SHA SSLv3 DH RSA 3DES(168) SHA1 SSL3-EXP-EDH-RSA-DES-CBC- SHA SSLv3 DH(512) RSA DES(40) DES(40) TLS1-DHE-RSA-AES-256-CBC- SHA TLSv1 DH RSA AES(256) SHA1 TLS1-DHE-RSA-AES-128-CBC- SHA TLSv1 DH RSA AES(128) SHA1 TLS1-EXP1024-RC4-MD5 TLSv1 RSA(1024) RSA RC4(56) MD5 Export TLS1-EXP1024-RC2-CBC-MD5 TLSv1 RSA(1024) RSA RC2(56) MD5 Export SSL2-EXP-RC2-CBC-MD5 SSLv2 RSA(512) RSA RC2(40) MD5 Export SSL3-ADH-RC4-MD5 SSLv3 DH None RC4(128) MD5 SSL3-ADH-DES-CBC-SHA SSLv3 DH None DES(56) SHA1 SSL3-ADH-DES-CBC3-SHA SSLv3 DH None 3DES(168) SHA1 TLS1-ADH-AES-128-CBC-SHA TLSv1 DH None AES(128) SHA1 TLS1-ADH-AES-256-CBC-SHA TLSv1 DH None AES(256) SHA1 SSL3-EXP-ADH-RC4-MD5 SSLv3 DH(512) None RC4(40) MD5 Export SSL3-EXP-ADH-DES-CBC-SHA SSLv3 DH(512) None DES(40) SHA1 Export 436 Installation and Configuration Guide - Volume 1 Table 3: Null Ciphers supported by the NetScaler C i p h e r N a m e P r o t o c o l K e y E x c h a n g e K e y S i z e A u t h e n t i c a t i o n E n c r y p t i o n ( K e y S i z e ) M e s s a g e A u t h e n t i c a t i o n SSL3-NULL-MD5 SSLv3 RSA RSA None MD5 SSL3-NULL-SHA SSLv3 RSA RSA None SHA1 CHAPTER 7 FIPS This chapter explains the FIPS-related functionality of the Citrix NetScaler Application Switch. It explains what FIPS is, and how to configure the basic and advanced configuration features. Topics in this chapter include: • How FIPS works • Configuring a FIPS System • Managing FIPS Keys • Configuring a Certificate Signing Request • Configuring a High Availability (HA) FIPS System. How FIPS Works FIPS (Federal Information Processing Standard) is a standard issued by the US National Institute of Standards and Technologies. FIPS specifies the security requirements for a cryptographic module utilized within a security system. Security systems protect sensitive information in computer and telecommunication systems. The FIPS system complies with the second version of this standard, FIPS-140-2. Note: Henceforth, all references to FIPS will imply FIPS-140-2. The FIPS system adheres to the FIPS-140-2 Level 2 norms. The FIPS system is equipped with a tamper-proof (tamper-evident) cryptographic module. This cryptographic module is a Cavium CN1120-NFB card, designed to comply with the FIPS 140-2 Level-2 and Level-3 norms. The Critical Security Parameters (CSPs), primarily the server's private-key, are securely stored and generated inside the cryptographic module (also referred to as the Hardware Security Module /HSM). The CSPs are never accessed outside the boundaries of the HSM. Only the super user on the system (nsroot) can to perform operations on the keys stored inside the HSM. 438 Installation and Configuration Guide - Volume 1 The following table summarizes the differences between the Citrix NetScaler system and the FIPS system. Note: Only FIPS approved ciphers can be configured on a FIPS system. The only non-FIPS cipher allowed is SSL3-RC4-SHA. The following sections have been arranged in the order in which a user might typically configure and use the FIPS system. However, certain sections have been added to make the guide more comprehensive. . Configuring a FIPS system Configuring a FIPS system is similar to configuring a non-FIPS system. For details, refer to the “Configuring the System” section in volume 1 of the Installation and Configuration Guide. However, note that the processes differ, due to the presence of the HSM on the FIPS system. As a result, you need to configure the HSM immediately after completing the generic configuration process. Important: To install FIPS, see the Citrix NetScaler Migration Guide. In the installation steps, use . / i nst al l ns - F command to install FIPS. Configuring the HSM The HSM is preconfigured with default values for the Security Officer password and the User password. The default values are: • Security Officer password - sopin123 • User password - userpin123 Note: When changing the SO password and the user password for the first time, specify sopin123 as the old SO password. Setting Citrix NetScaler Series FIPS Key storage On the hard disk On the FIPS card Cipher support All ciphers FIPS approved ciphers Accessing Keys From the hard disk Not accessible Chapter 7 FIPS 439 While the FIPS system can be used with these values, it is advisable to modify them on the HSM before using it. The HSM can be configured only by the system’s super user (nsroot) and should be configured before you run the FIPS system for the first time. Configuring the HSM allows you to specify the HSM-specific passwords. It also erases all the existing data on the HSM. Note: Due to security constraints, the system does not provide a means for retrieving this password. Store a copy of the password safely. In the event of a need to re-initialize the HSM, you will need to specify this password as the old SO password. The following sample procedure describes the steps to initialize the HSM and change the Security Officer password from “sopin123” to “fipsso123”. To configure the HSM 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the Initialize HSM button. The Initialize HSM dialog box appears. 3. In the Security Officer (SO) Password text box, type fipssso123. 4. In the Old SO Password text box, type sopin123. 5. In the User Password text box, type userpin123. 6. In the HSM Label text box, type FIPS-140-2 Level-2. 7. Click OK. The security officer password is now changed. To configure the HSM using the NetScaler command line At the NetScaler command prompt, type: set ssl fips -initHSM Level-2 fipssso123 sopin123 userpin123 - hsmLabel FIPS-140-2 This command will erase all data on the FIPS card. You must save the configuration (saveconfig) after executing this command. Do you want to continue? (Y/N) y Note: After the HSM is initialized, the current configuration of the system needs to be saved. (If this is not done, the card will not function after a system reboot.) Any subsequent attempt to change the SO password will cause the card to be locked. 440 Installation and Configuration Guide - Volume 1 Managing FIPS Keys Creating FIPS Keys Once the HSM has been configured, you should create a FIPS key. The following sample procedure describes the steps to create a FIPS key, Key- FIPS-1 with a modulus value of 1024 and an exponent of F4. To create a FIPS key 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the FIPS Keys tab. The list of configured FIPS keys appear in the FIPS keys page. 3. Click the Add button. The Create FIPS Key dialog box appears. 4. In the Fips Key Name dialog box, type Key-FIPS-1. 5. In the Modulus text box, type 1024. 6. Under Exponent, select F4. 7. Click Create. The FIPS key you just created is stored in the HSM of the system. To create a FIPS key using the NetScaler command line At the NetScaler command prompt, type: create fipskey Key-FIPS-1 -modulus 1024 -exponent f4 Exporting FIPS Keys Once created, the FIPS key needs to be exported to the hard disk. The exported key is secured using a strong asymmetric key encryption method.. The follwing sample procedure describes the steps to export the FIPS key Key- FIPS-1 to the location /nsconfig/ssl/Key-FIPS-1.key. This key is then transferred and imported on the target system. To export a FIPS key 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the FIPS Keys tab. The FIPS keys page appears. 3. Click the Export button. The Export FIPS key to a file dialog box appears. Chapter 7 FIPS 441 4. Under FIPS Key Name, select the key you want to export, for example, Key-FIPS-1. 5. In the File Name text box, type the name of the file to be exported to, for example, Key-FIPS-1.key. Note: The exported file is stored in the /nsconfig/ssl directory by default. If you choose to use any other directory, you must specify the complete path to the location. You can also use the browse button to launch the file explorer to navigate any location on the system. 6. Click Export. The FIPS key you exported is saved in the location you specified. To export a FIPS key using the NetScaler command line At the NetScaler command prompt, type: export fipskey Key-FIPS-1 -key Key-FIPS-1.key Note: To avoid errors when importing a FIPS key, wen you export the FIPS key, you need to ensure that the name of the key exported is the same as the original key name when it was created. It is recommended that you create a backup of any key created on the FIPS HSM, because, once any key on the HSM is deleted, all of the certificates associated with it are rendered useless. Also, once deleted, there is no way to create the same key again. Importing FIPS Keys You can use an existing FIPS key with your FIPS system. However, the existing FIPS key needs to be imported into its HSM. In the following example, you will import the transferred file, Key-FIPS-1.key into the system as a FIPS key with the same name. To import a FIPS key 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the FIPS Keys tab. The FIPS keys page appears. 3. Click the Import button. The Import as a FIPS Key dialog box appears. 4. Select the Import From FIPS key file. 442 Installation and Configuration Guide - Volume 1 5. In the FIPS Key Name text box, type the name of the FIPS key to be created, for example, Key-FIPS-1. 6. In the Key File Name text box, type the name of the FIPS key to be imported, for example, Key-FIPS-1.key. Note: The default location is the /nsconfig/ssl directory. If the file is located in another directory, you must specify the complete path to the location. You can use also the browse button to launch the file explorer and navigate to any location on the system. 7. Click Import. The FIPS key is now imported into the system. To import a FIPS key using the NetScaler command line At the NetScaler command prompt, type: import fipskey Key-FIPS-1 -key Key-FIPS-1.key Importing External Keys In addition to transferring FIPS keys, you can also transfer external private keys from the hard disk into the HSM. External keys are created outside the HSM, (for example, using OpenSSL). To import an external key into the HSM, you need to use an intermediate key (also known as a wrap key) within the HSM. Also, to import an external key, you first need to convert it into the PKCS8 format. The external key (in PKCS8 format) is encrypted with the wrap key before it is imported into the HSM. Generating a Wrap Key The following sample procedure describes the steps to create a wrap key Key- Wrap-1 with password wrapkey123 and salt string wrapsalt123. To generate a wrap key 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the Wrap Keys tab. The list of configured wrap keys appears in the Wrap Key page. 3. Click the Add button. The Create Wrap Key dialog box appears. 4. In the Wrap Key Name text box, type the name of the wrap key being created, for example, Key-Wrap-1. 5. In the Password text box, type the password to be used for the wrap key, for example wrapkey123. Chapter 7 FIPS 443 6. In the Salt text box, type the salt string to be used for the wrap key, for example wrapsalt123. 7. Click Create. The wrap key you created now appears in the Wrap Keys page. To generate a wrap key using the NetScaler command line At the NetScaler command prompt type create wrapkey Key-Wrap-1 -password wrapkey123 -salt wrapsalt123 Converting the External Key into the PKCS8 Format The following sample procedure describest the steps to convert the external key Key-External-1.pem on the system in the PKCS8 format as Key-PKCS8-1 . To convert the external key into the PKCS8 format 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the FIPS Keys tab. The FIPS keys page appears. 3. Click the Import button. The Import as a FIPS Key dialog box appears. 4. Select the Import From Pkcs8 file. 5. Click the Convert button.The Convert Private Key to PKCS8 Format dialog box appears. 6. In the Key Name (PKCS8 Format) text box, type the name of the file where the converted key should be stored, for example, Key-PKCS8-1. 7. In the Private Key Path text box, type the path of the external key to be converted, for example, Key-External-1.pem. 8. Under Key Format, select the format in which the external key is saved, for example, PEM. 9. In the Password text box, type the password used to encrypt the key, for example, FIPS-Password. 10. Click Convert. The external key is now converted to the PKCS8 format. To convert the external key into the PKCS8 format At the NetScaler command prompt, type: convert pkcs8 Key-PKCS8-1 Key-External-1.pem -inform PEM 444 Installation and Configuration Guide - Volume 1 Importing an External Private Key as a FIPS Key The following sample procedure describes the steps to import an external key, Key-Pkcs8-1.key with a wrap key, Key-Wrap-1 and an initialization vector, wrapkey123. To import an external private key as a FIPS key 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 2. Click the FIPS Keys tab. The FIPS keys page appears. 3. Click the Import button. The Import as a FIPS Key dialog box appears. 4. Select the Import From Pkcs8 file. 5. In the FIPS Key Name text box, type the name of the FIPS key to be created, for example, Key-Pkcs8-1. 6. In the Key File Name text box, type the name of the FIPS key to be imported, for example, Key-Pkcs8-1.key. 7. Under Wrap Key Name, select the wrap key to be used for the import, for example, Key-Wrap-1. 8. In the IV text box, type the initialization vector to be used for importing the key, for example, wrapkey123. 9. Click Create. The wrap key you created appears in the Wrap Keys page. To import an external private key as a FIPS key At the NetScaler command prompt, type: import fipskey Key-Pkcs8-1 -key Key-Pkcs8-1.key -inform PEM - wrapKeyName Key-Wrap-1 -iv wrapkey123 Note: For security reasons, delete the external private key from the hard disk after you import it into the HSM. Configuring a Certificate Signing Request To create a certificate signing request 1. In the left pane, expand SSL, then click CA Tools. The CA Tools page appears in the right pane. 2. Click Create Certificate Request. The Create Certificate Request dialog box appears. Chapter 7 FIPS 445 3. In the Request File Name text box, type the name of the CSR, for example Certificate-Request-1. 4. In the Key File Name text box, type the name of the FIPS key to be used to create the CSR, for example, Key-FIPS-1. Note: You can use the browse button to navigate to the saved key on the system. 5. Select the format the key was saved in, for example, PEM. 6. In the PEM Passphrase (For Encrypted Key), type the password used to encrypt the key. 7. Under Distinguished Name Fields, enter relevant information for each parameter. The information you enter will form the Distinguished Name (DN) of the company (web site). 8. Click Create, then click Close. The certificate signing request you created is saved on the system in the location you specified. To create a certificate signing request using the NetScaler command line At the NetScaler command prompt, type: create certreq Certificate-Request-1 -fipskeyName Key-FIPS-1 Now send the CSR to a CA for authentication and signing. Most CAs accept certificate submissions by email. The CA will return a valid certificate to the email address you used to submit the CSR. Once you have obtained the signed certificate from a CA, install the certificate and its corresponding private key on the system. Configuring a High Availability (HA) FIPS system Note: To configure two systems in the high availability (HA) mode, refer to the Accessing and Configuring a Citrix NetScaler chapter The following configuration should be performed on the primary system in the HA pair. To configure a high availability FIPS system 1. In the left pane, expand SSL, then click FIPS. The FIPS page appears in the right pane. 446 Installation and Configuration Guide - Volume 1 1. Select the FIPS Info tab, then click the Enable SIM button. The Enable HA Pair for SIM dialog box appears. 2. In the Certificate File Name text box, type the file name name and path on the source system where the FIPS certificate 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. Managing Certificates 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 1. In the left pane, expand SSL and click Certificates. The SSL Certificates page appears in the right pane. 2. Click Add. The Install Certificate dialog box appears. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand SSL Offload, then click Virtual Servers. The SSL Offload Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server you want to bind the certificate key pair to. For example, select Vserver-SSL-1, then click Open. The Configure Virtual Server (SSL Offload ) appears. 3. Select the SSL Settings tab. The list of configured certificate key pairs configured on the system are displayed in the Available area. 448 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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: 450 Installation and Configuration Guide - Volume 1 • 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. Entity Type Name Value Service Service-HTTP-1 10.102.29.191 452 Installation and Configuration Guide - Volume 1 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. Parameters Descriptions 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 Citrix NetScaler system Client requests Response from server Response sent to client Service-HTTP-1 10.102.29.191 Chapter 8 Optimizing Performance 453 To create a service with client keep-alive enabled 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 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 At the NetScaler command prompt, type: 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 appears in the right pane. 454 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 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 NetScaler command line At the NetScaler command prompt, type: 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 server’s response and delivers it to the client at the client’s speed, thus offloading the server faster and thereby improving the performance of Web sites. Chapter 8 Optimizing Performance 455 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. The topics covered in this section are: • 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 network’s 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. 456 Installation and Configuration Guide - Volume 1 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 network’s 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 Citrix NetScaler system Client requests Response from server at server network’s speed Response sent to client at client network’s speed With TCP buffering enabled Chapter 8 Optimizing Performance 457 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. Entity Type Name Value Service Service-HTTP 10.102.29.130 Citrix NetScaler system (with TCP buffering confi gured) Internet Router Origin Server Client L2 switch L2 switch Client requests Server response at server network’s speed Response sent to client at client network’s speed 458 Installation and Configuration Guide - Volume 1 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 network’s 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 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. Parameters Descriptions 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 Citrix NetScaler system Client requests Response from server at server network’s speed Response sent to client at client network’s speed Name: Service-HTTP IP address: 10.102.29.130 Chapter 8 Optimizing Performance 459 2. Click Add. The Create Service dialog box appears. 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 and 10.102.29.130. 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 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 At the NetScaler command prompt, type: 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. The topics covered in this section are: • 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 1. In the left pane, expand System and click Settings. The Settings page appears in the right pane. 2. Under the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Select or clear the TCP Buffering check box. 460 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 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 NetScaler command line At the NetScaler command prompt, type: 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. Parameters Descriptions 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. Chapter 8 Optimizing Performance 461 To set the TCP buffering parameters 1. In the left pane, expand System and click Settings. The Settings page appears in the right pane. 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 At the NetScaler command prompt, type: 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. Parameters Descriptions 462 Installation and Configuration Guide - Volume 1 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. The topics covered in this section are: • 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. Chapter 8 Optimizing Performance 463 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 Citrix NetScaler system CMP policies Client requests Response from server Compressed response 464 Installation and Configuration Guide - Volume 1 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 Citrix NetScaler system CMP policies Client requests Response from server Compressed response Service_1 LB Vserver Origin server_2 Response from server Chapter 8 Optimizing Performance 465 Basic topology The following table summarizes the name and value of the entity that you need to configure on the system. 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 Entity Type Name Value Service Service-HTTP-1 10.102.29.51 Citrix NetScaler system (with compression confi gured) Internet Router Origin Server Client L2 switch L2 switch Client requests Server response (compressible content) compressed content Origin server Service Client Citrix NetScaler system CMP policies Client requests Response from server Compressed response Name: Service-HTTP-1 IP address: 10.102.29.51 (In-built policies) 466 Installation and Configuration Guide - Volume 1 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 appears in the right pane. 2. Under the Modes & Features group, click basic features. The Configure Basic Features dialog box appears. 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 At the NetScaler command prompt, type: 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. 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 Service-HTTP-1 with IP address 10.102.29.51, listening on port 80, and with protocol type HTTP. Parameters Descriptions 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. Chapter 8 Optimizing Performance 467 To create a service 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 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.51. 4. In the Port text box, type the port number, for example, 80. 5. In the Protocol list, choose HTTP. 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 At the NetScaler command prompt, type: add service Service-HTTP-1 10.102.29.51 HTTP 80 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. The topics covered in this section are: • 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: 468 Installation and Configuration Guide - Volume 1 Warning displayed on disabling compression globally To disable the compression feature 1. In the left pane, expand System and click Settings.The Settings page appears in the right pane. 2. Under the Modes & Features group, click basic features. The Configure Basic Features dialog box appears. 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 At the NetScaler command prompt, type: 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. Chapter 8 Optimizing Performance 469 To enable or disable compression at the service level 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 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 At the NetScaler command prompt, type: 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. 470 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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. Chapter 8 Optimizing Performance 471 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) 472 Installation and Configuration Guide - Volume 1 • 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. Chapter 8 Optimizing Performance 473 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. The topics covered in this section include: • Configuring Compression Actions • Configuring Compression Policies 474 Installation and Configuration Guide - Volume 1 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. Chapter 8 Optimizing Performance 475 To view the built-in compression actions 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. Parameters Descriptions 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. 476 Installation and Configuration Guide - Volume 1 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 in the following figure. To create a compression action using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. Chapter 8 Optimizing Performance 477 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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 shown in the following figure. Details section in the Actions tab 478 Installation and Configuration Guide - Volume 1 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. Chapter 8 Optimizing Performance 479 To view the built-in compression policies 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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. The following table describes the mandatory parameters that you must configure 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. Parameters Descriptions 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. 480 Installation and Configuration Guide - Volume 1 To create a compression policy with default values 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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 At the NetScaler command prompt, type: 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. The following table describes the mandatory parameters that you must configure 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. Parameters Descriptions 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. Chapter 8 Optimizing Performance 481 To create a compression policy with user-defined values 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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-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. 11. Click Create and click Close. The compression policy that you create appears in the Policies tab on the HTTP Compression page. This is shown in the following figure. Compression policy in the HTTP Compression page 482 Installation and Configuration Guide - Volume 1 To create a compression policy with user-defined values using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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. Chapter 8 Optimizing Performance 483 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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-2, and click Add. The policy appears in the Configured box. The State check box corresponding to the selected policy is selected automatically. 484 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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 that you want to bind, for example, Policy-CMP-3. 4. Click Add. The policy appears in the Configured box. Chapter 8 Optimizing Performance 485 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 in the following figure. Globally Bound field of the compression policy To bind a compression policy globally using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click 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. 486 Installation and Configuration Guide - Volume 1 To bind a compression policy to a load balancing server using the NetScaler command line At the NetScaler command prompt, type: 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 Compression page appears in the right pane. 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 At the NetScaler command prompt, type: 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. Chapter 8 Optimizing Performance 487 To unbind a globally-bound compression policy 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 2. On the Policies tab, click Global Bindings. The Bind/Unbind Compression Policy(s) to Global dialog box appears. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click 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 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 NetScaler command line At the NetScaler command prompt, type: unbind lb vserver Vserver-LB-1 -policyName Policy-CMP-1 488 Installation and Configuration Guide - Volume 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. Chapter 8 Optimizing Performance 489 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 Deployment Scenarios This section describes deployment scenarios where compression is configured with other features such as load balancing and SSL. The topics covered in this section include: • Compression in Inline Mode • Compression with SSL 490 Installation and Configuration Guide - Volume 1 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. Citrix NetScaler system (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 Client requests Server response (compressible content) compressed content Chapter 8 Optimizing Performance 491 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 Citrix NetScaler system 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 492 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand System and click Settings.The Settings page appears in the right pane. 2. Under the Modes & Features group, click basic features. The Configure Basic Features dialog box appears. 3. Select the Compression and the Load Balancing check boxes. 4. Click OK, and click Yes on the Enable/Disable Feature(s)? message box. To enable the compression and load balancing features using the NetScaler command line At the NetScaler command prompt, type: enable feature cmp lb Expression Expression Type: General Flow Type: REQ Protocol: HTTP Qualifier: URL Operator: == Value: /*.asp Entity type Parameter Values Chapter 8 Optimizing Performance 493 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Server (Load Balancing) dialog box appears. 3. In the Name and IP Address text boxes, type Vserver-LB and 10.102.29.120. 4. In the Port text box, type 80. 5. In the Protocol list, choose HTTP. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name and Server text boxes, type Service-HTTP and 10.102.29.73. 4. In the Port text box, type 80. 5. In the Protocol list, choose HTTP. 494 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 2. On the Policies tab, click Add. The Create Compression Policy dialog box appears. 3. In the Policy Name text box, type Policy-CMP. 4. In the Response Action list, choose COMPRESS. Chapter 8 Optimizing Performance 495 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. 9. Click Create and click Close. The compression policy that you create appears on the Policies tab in the HTTP Compression page. To create a compression policy using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click the name of the virtual server, for example, Vserver-LB, 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. 4. Click OK. The compression policy is bound to the load balancing virtual server. To bind the compression policy to the vserver using the NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-LB -policyName Policy-CMP 496 Installation and Configuration Guide - Volume 1 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. Citrix NetScaler system (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 Client requests Server response (compressible content) compressed and encrypted content Chapter 8 Optimizing Performance 497 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. Entity type Parameter Values 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 Citrix NetScaler system 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 498 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand System and click Settings.The Settings page appears in the right pane. 2. Under the Modes & Features group, click basic features. The Configure Basic Features dialog box appears. 3. Select the Compression, Load Balancing, and SSL check boxes. 4. Click OK, and click Yes on the Enable/Disable Feature(s)? message box. To enable the compression, load balancing, and SSL features using the NetScaler command line At the NetScaler command prompt, type: 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 Entity type Parameter Values Chapter 8 Optimizing Performance 499 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Server (Load Balancing) dialog box appears. 3. In the Name and IP Address text boxes, type Vserver-SSL and 10.102.29.50. 4. In the Port text box, type 443. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 3. In the Service Name and Server text boxes, type Service-SSL and 10.102.29.61. 4. In the Port text box, type 443. 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. 500 Installation and Configuration Guide - Volume 1 To add a service of type SSL using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Compression and click HTTP. The HTTP Compression page appears in the right pane. 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. Chapter 8 Optimizing Performance 501 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click the name of the virtual server, for example, Vserver-SSL, 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 the compression policy to the vserver using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the left pane, expand SSL and click Certificates. The SSL Certificates page appears in the right pane. 502 Installation and Configuration Guide - Volume 1 2. Click Add. The Install Certificate dialog box appears. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Vserver-SSL, then click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 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 At the NetScaler command prompt, type: bind ssl certkey Vserver-SSL Cert-SSL Chapter 8 Optimizing Performance 503 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. 504 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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. Parameters Descriptions 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. Chapter 8 Optimizing Performance 505 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 At the NetScaler command prompt, type: set ns tcpParam - SACK value Example: set ns tcpParam -SACK ENABLED 506 Installation and Configuration Guide - Volume 1 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 508 Installation and Configuration Guide - Volume 1 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 appears in the right pane. 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. 510 Installation and Configuration Guide - Volume 1 To disable content filtering 1. In the left pane, expand System, and select Settings. The Settings page appears in the right pane. 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 page appears in the right pane. 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 1. In the left pane, expand Protection Features, and select Filter. The Filter page appears in the right pane. 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. Chapter 9 Protection Features 511 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 1. In the left pane, expand Protection Features, and select Filter. The Filter page appears in the right pane. 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. 512 Installation and Configuration Guide - Volume 1 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 Balancing) dialog box appears. 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 1. In the left pane, expand Protection Features, and select Filter. The Filter page appears in the right pane. 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 Chapter 9 Protection Features 513 • Create servers and services • Bind service to vserver • Create filter policy • Bind filter policy globally or to a vserver • Verify the configuration The following table summarizes the parameters and values of the entities you configure on the system. To enable content filtering 1. In the left pane, expand System, and click Settings. The Settings page appears in the right pane. 2. Under Modes & Features, click basic features. The Configure Basic Features dialog box appears. 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 514 Installation and Configuration Guide - Volume 1 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. 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 1. In the left pane, expand System, and click Settings. The Settings page appears in the right pane. 2. Under Modes & Features, click basic features. The Configure Basic Features dialog box appears. 3. Select theLoad Balancing 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. To add a load balancing vserver 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click Add. The Create Virtual Server (Load Balancing) dialog box 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. 1. In the left pane, expand Load Balancing and click Services. The Services page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 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-CF-1 and 10.102.11.1. 4. In the Port text box, type the port number, for example, 80. 5. In the Protocol drop-down list, select HTTP. Chapter 9 Protection Features 515 6. Click Create, and click Close. The service, which you have created, appears in the Services page. 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Click vserver-CF-1 and click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 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 page appears in the right pane. 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 1. In the left pane, expand Protection Features, and select Filter. The Filter page appears in the right pane. 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. 516 Installation and Configuration Guide - Volume 1 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 (Load Balancing) dialog box appears. 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 Chapter 9 Protection Features 517 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. 518 Installation and Configuration Guide - Volume 1 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. Chapter 9 Protection Features 519 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: 520 Installation and Configuration Guide - Volume 1 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. Chapter 9 Protection Features 521 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 1. In the left pane, expand System, and select Settings. The Settings page appears in the right pane. 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 1. In the left pane, expand System, and select Settings. The Settings page appears in the right pane. 522 Installation and Configuration Guide - Volume 1 2. Click advanced features. The Configure Advanced Features dialog box 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 1. In the left pane, expand System, and select Settings. The Settings page appears in the right pane. 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. Chapter 9 Protection Features 523 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. 524 Installation and Configuration Guide - Volume 1 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 Chapter 9 Protection Features 525 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. 526 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand System, and select Settings. The Settings page appears in the right pane. 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. A message in the status bar indicates that the selected feature is enabled. 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. Chapter 9 Protection Features 527 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. 528 Installation and Configuration Guide - Volume 1 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 Load Balancing Virtual Servers page appears in the right pane. 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 (Load Balancing) dialog box appears. 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. Verify the configuration 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 Chapter 9 Protection Features 529 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: 530 Installation and Configuration Guide - Volume 1 • 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. Chapter 9 Protection Features 531 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. 2. Click advanced features. The Configure Advanced Features dialog box 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. 532 Installation and Configuration Guide - Volume 1 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 page appears in the right pane. 2. Click Add. The Create Service dialog box appears. 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. Chapter 9 Protection Features 533 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. 534 Installation and Configuration Guide - Volume 1 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? Chapter 9 Protection Features 535 • Any or all information that can help you tune DoS attack protection. 536 Installation and Configuration Guide - Volume 1 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 538 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand System, and click Settings. The Settings page appears in the right pane. 2. Click advanced features. The Configure Advanced Features dialog box 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 appears in the right pane. 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 540 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 541 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 542 Installation and Configuration Guide - Volume 1 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™ Linux®operating 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 / et c • / usr / l ocal / net scal er / bi n • / 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 Use the following procedure to install the nswl executable and the other files on 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: Chapter 10 Web Server Logging 543 cp <pat h_t o_cd>/ Ut i l i t i es/ webl og/ Fr eebsd/ NSwebl og. t gz / t mp 2. Change to the temporary directory: 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: • / usr / l ocal / net scal er / et c • / usr / l ocal / net scal er / bi n • / usr / l ocal / net scal er / sampl es 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 Use the following procedure to install the nswl executable and the other files on 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 2. Change to the temporary directory: 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 • / usr / l ocal / net scal er / et c • / usr / l ocal / net scal er / bi n • / usr / l ocal / net scal er / sampl es 4. To verify that the package is installed, use the command: 544 Installation and Configuration Guide - Volume 1 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 Use the following procedure to install the nswl executable and the other files on 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 Chapter 10 Web Server Logging 545 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. 546 Installation and Configuration Guide - Volume 1 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. Chapter 10 Web Server Logging 547 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 Parameter Description 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. 548 Installation and Configuration Guide - Volume 1 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> <I P> <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. Chapter 10 Web Server Logging 549 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 550 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 551 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. Verifying the Configuration Check the configuration file (log.conf) for syntax errors so that logging works correctly. 552 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 553 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 554 Installation and Configuration Guide - Volume 1 # 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, # and t he f i l e name i s / dat adi sk5/ net scal er / l og/ NS<host name>/ 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 ogI nt er val Dai l y # l ogFi l eSi zeLi mi t 20 # 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 eSi zeLi mi t 20 # 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 ########## Chapter 10 Web Server Logging 555 # 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 ogI nt er val Dai l y # l ogFi l eSi zeLi mi t 10 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) 556 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 557 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 12: 21: 16 GET / spor t s/ f oot bal l . ht ml 12: 45: 52 GET / spor t s/ f oot bal l . ht ml 12: 57: 34 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. 558 Installation and Configuration Guide - Volume 1 • 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. Chapter 10 Web Server Logging 559 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 560 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 561 # and t he f i l e name i s / dat adi sk5/ net scal er / l og/ NS<host name>/ 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 eSi zeLi mi t 20 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. 562 Installation and Configuration Guide - Volume 1 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 Chapter 10 Web Server Logging 563 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 564 Installation and Configuration Guide - Volume 1 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) Chapter 10 Web Server Logging 565 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 ) 566 Installation and Configuration Guide - Volume 1 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 568 Installation and Configuration Guide - Volume 1 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: Parameter Description 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. Parameter Description 570 Installation and Configuration Guide - Volume 1 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 Chapter 11 Configuring Audit Server Logging 571 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 Policies page appears in the right pane. 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. 572 Installation and Configuration Guide - Volume 1 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 page appears in the right pane. 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: Operating System Software Requirements Windows • Windows XP Professional - Version 2002 • Windows 2003 server • Windows 2000/NT Chapter 11 Configuring Audit Server Logging 573 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 Operating System Software Requirements 574 Installation and Configuration Guide - Volume 1 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: • / usr / l ocal / net scal er / et c • / usr / l ocal / net scal er / bi n • / usr / l ocal / net scal er / sampl es 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. Chapter 11 Configuring Audit Server Logging 575 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: • / usr / l ocal / net scal er / et c • / usr / l ocal / net scal er / bi n • / usr / l ocal / net scal er / sampl es 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 This section describes the procedure to uninstall audit server logging on a server that runs on the FreeBSD operating system. To uninstall audit server logging At a command prompt, type the following command to uninstall the audit server logging package: pkg_del et e NSaudi t ser ver 576 Installation and Configuration Guide - Volume 1 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 This section describes the procedure to uninstall audit server logging on a server that runs on the Windows operating system. To uninstall audit server logging 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. Chapter 11 Configuring Audit Server Logging 577 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 <pat h t o conf i gur at i on 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 <pat h t o conf i gur at i on 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 <pat h t o conf i gur at i on f i l e> Windows Only: Installs the audit server logging client as a service on Windows. 578 Installation and Configuration Guide - Volume 1 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 Chapter 11 Configuring Audit Server Logging 579 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 <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 580 Installation and Configuration Guide - Volume 1 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 Chapter 11 Configuring Audit Server Logging 581 • 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. 582 Installation and Configuration Guide - Volume 1 • 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. Chapter 11 Configuring Audit Server Logging 583 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 ogI nt er val Hour l y l ogFi l eSi zeLi mi t 10 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 584 Installation and Configuration Guide - Volume 1 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 Chapter 11 Configuring Audit Server Logging 585 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 ogFi l eSi zeLi mi t 10 # 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 l ogI nt er val Hour l y l ogFi l eSi zeLi mi t 10 l ogFi l enameFor mat audi t l og%{%y%m%d}t . l og 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 586 Installation and Configuration Guide - Volume 1 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 Chapter 11 Configuring Audit Server Logging 587 To create an audit server action 1. In the left pane, expand System, and click Auditing. The Auditing 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 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 1. In the left pane, expand System, Auditing, and click Policies. The Policies page appears in the right pane. 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 588 Installation and Configuration Guide - Volume 1 To globally bind the audit log policy 1. In the left pane, expand System, Auditing, and click Policies. The Policies page appears in the right pane. 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 Chapter 11 Configuring Audit Server Logging 589 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 l ogI nt er val Hour l y l ogFi l eSi zeLi mi t 10 l ogFi l enameFor mat audi t l og%{%y%m%d}t . l og 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 ! 590 Installation and Configuration Guide - Volume 1 CHAPTER 12 Advanced Network Configuration This chapter describes the advanced networking features of the NetScaler and provides configuration instructions. Topics in this chapter include: • Reverse Network Address Translation • Dynamic Routing • Route Health Injection • 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. 592 Installation and Configuration Guide - Volume 1 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 Routes. The Routes page appears in the details pane. 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. Parameter Description Network Network or subnet from which the traffic is flowing. Netmask Subnet mask of the network. 594 Installation and Configuration Guide - Volume 1 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 configuration utility 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. Parameter Description Available NAT IP (s) NAT IP(s) assigned to a source IP or NetScaler IP. Chapter 12 Advanced Network Configuration 595 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 NetScaler command line 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. 596 Installation and Configuration Guide - Volume 1 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 in the details pane. 2. Click the Extended ACL tab and click Add. The Add ACL dialog box appears. Parameter Description 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. Chapter 12 Advanced Network Configuration 597 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. 7. Click Create and click Close. To configure an ACL using the NetScaler command line At the NetScaler command prompt, type: 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 the configuration utility 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. 5. In the Available NAT IP (s) list box, select the NAT IP address that you 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. 7. Click Create and click Close. To configure RNAT to change the Source IP Address based on an ACL using the NetScaler command line At the NetScaler command prompt, type: set rnat acl1 -natip 209.165.202.129 598 Installation and Configuration Guide - Volume 1 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. To apply an ACL using the NetScaler command line At the NetScaler command prompt, type: 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 in the details pane. Chapter 12 Advanced Network Configuration 599 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, 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. 7. Click Create and click Close. To configure an ACL using the NetScaler command line At the NetScaler command prompt, type: 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 the configuration utility 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. 8. Click Create, and then click Close. 600 Installation and Configuration Guide - Volume 1 To set RNAT to change the Source IP address and Destination Port using the NetScaler command line At the NetScaler command prompt, type: 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. To apply an ACL using the NetScaler command line At the NetScaler command prompt, type: 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: Chapter 12 Advanced Network Configuration 601 • 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 table. 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 Parameter Description 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 Parameter Description 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 602 Installation and Configuration Guide - Volume 1 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 Chapter 12 Advanced Network Configuration 603 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click 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. 4. Click OK. The Enable/Disable Feature(s)? message appears. 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 604 Installation and Configuration Guide - Volume 1 2. Under the Modes & Features group, click advanced features. The Configure Advanced Features dialog box appears. 3. Do one of the following: • To enable RIP routing, select the RIP Routing check box. • To disable RIP routing, clear the RIP Routing check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable or disable RIP routing using the NetScaler command line At the NetScaler command prompt, type one of the following: 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. Parameter Description Passive Interface Name of the passive interface. Network Broadcast network on which RIP is to be run. Netmask Subnet mask for the broadcast network. Chapter 12 Advanced Network Configuration 605 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 At the NetScaler command prompt, type: 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. Parameter Description 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. Parameter Description Passive Interface Sets the mode of the interface to listen only. 606 Installation and Configuration Guide - Volume 1 To limit RIP propagations 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. 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 At the NetScaler command prompt, type: 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 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. Select the Learn Routes check box. Click OK. To configure RIP to learn routes using the NetScaler command line At the NetScaler command prompt, type: set router rip -learnRoute Parameter Description 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. Chapter 12 Advanced Network Configuration 607 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 At the NetScaler command prompt, type: 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 608 Installation and Configuration Guide - Volume 1 • 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click advanced features. The Configure Advanced Features dialog box appears. 3. Do one of the following: • To enable OSPF routing, select the OSPF Routing check box. • To disable OSPF routing, clear the OSPF Routing check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable or disable OSPF routing using the NetScaler command line At the NetScaler command prompt, type one of the following: 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 • Controlling Route Learning • Viewing OSPF Settings The following table lists and describes the parameters required to configure OSPF. Chapter 12 Advanced Network Configuration 609 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 At the NetScaler command prompt, type: 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. Parameter Description 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. 610 Installation and Configuration Guide - Volume 1 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. 3. Click Open. The Configure OSPF dialog box appears. 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 At the NetScaler command prompt, type: 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. Parameter Description 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. Parameter Description Passive Interface Sets the mode of the interface to listen only. Chapter 12 Advanced Network Configuration 611 To limit OSPF propagations to a single interface 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 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. Click OK. To limit OSPF propagations to a single interface using the NetScaler command line At the NetScaler command prompt, type: set router ospf -passiveInterface 1/8 Controlling Route Learning The following table lists and describes the parameters required to control route learning. To configure OSPF to learn routes 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 network for which you want to configure RIP, for example, 0.0.0.0. 3. Click Open. The Configure OSPF dialog box appears. 4. Select the Learn Routes check box. Click OK. To configure OSPF to advertise routes using the NetScaler command line At the NetScaler command prompt, type: set route ospf -learnRoute Parameter Description 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. 612 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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: Chapter 12 Advanced Network Configuration 613 • 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click advanced features. The Configure Advanced Features dialog box appears. 3. Do one of the following: • To enable BGP routing, select the BGP Routing check box. • To disable BGP routing, clear the BGP Routing check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable or disable BGP routing using the NetScaler command line At the NetScaler command prompt, type: 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. 614 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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. Parameter Description Autonomous System BGP autonomous system. Parameter Description 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. Chapter 12 Advanced Network Configuration 615 To configure BGP to advertise routes 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. 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 At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network, expand Routing, and click BGP. The BGP page appears in the details pane. 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 At the NetScaler command prompt, type: 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. 616 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 Route Health Injection 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. Chapter 12 Advanced Network Configuration 617 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 appears in the details pane. 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. 3. Click Open. The Configure IP dialog box appears. 4. Under Host Route, select the Enable check box. 5. Click OK. To enable RHI using the NetScaler command line At the NetScaler command prompt, type: set ip 10.102.29.54 -hostroute enabled 618 Installation and Configuration Guide - Volume 1 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 1. In the navigation pane, expand Network, expand Routing, and 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 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. Parameter Description 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. Parameter Description 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. Chapter 12 Advanced Network Configuration 619 5. Select Enable. 6. Under Protocol, select OSPF check box. Click Create and click Close. To advertise networks using the NetScaler command line At the NetScaler command prompt, type: add route 10.102.29.0 255.255.255.0 10.102.29.50 -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 At the NetScaler command prompt, type: 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. 620 Installation and Configuration Guide - Volume 1 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. Chapter 12 Advanced Network Configuration 621 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 the following table. 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. Parameter Description 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. 622 Installation and Configuration Guide - Volume 1 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 configured on the NetScaler. 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 Parameters Description 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. Entity Type Name Value Monitor monitor-HTTP-1 10.10.10.11 Service service-ANY-1 10.102.29.50 LB Vserver vserver-LB-1 NA Chapter 12 Advanced Network Configuration 623 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 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 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. 6. Click Create and click Close. To create a transparent monitor using the NetScaler command line At the NetScaler command prompt, type: 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 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-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. 6. Click Add. The monitor appears in the Configured box. 624 Installation and Configuration Guide - Volume 1 7. Click Create and click Close. To create a service and bind the monitor to it using the NetScaler command line At the NetScaler command prompt, type: 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 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 Servers (Load Balancing) dialog box 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. 7. Click Create and click Close. To create an LB vserver and bind the service to it using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure LB method and persistence, for example, vserver-LB-1. Chapter 12 Advanced Network Configuration 625 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box 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 At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. 5. Click Create and click Close. To configure link LB using the NetScaler command line At the NetScaler command prompt, type: 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. 626 Installation and Configuration Guide - Volume 1 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 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, R1, 10.102.29.4, and *. 4. In the Protocol drop-down list box, select the type of the service, for example, ANY. 5. Click Create and click Close. 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 At the NetScaler command prompt, type: add service R1 10.102.29.4 ANY * add service R2 10.102.29.5 ANY * Entity Type Name Value LB Service R1 10.102.29.4 R2 10.102.29.5 LB Vserver vserver-LB-Pri-1 NA vserver-LB-Sec-1 NA Chapter 12 Advanced Network Configuration 627 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 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 Servers (Load Balancing) dialog box appears. 3. In the Name text box, type the name of the vserver, for example, vserver- 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 *. 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, R1. 7. Click the Method and Persistence tab. In the drop-down list box, under LB Method, select round robin. 8. Click Create and click Close. To create a primary router using the NetScaler command line At the NetScaler command prompt, type: 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 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 Servers (Load Balancing) dialog box appears. 3. In the Name text box, type the name of the vserver, for example, vserver- LB-sec-1, and select the Directly Addressable check box. 628 Installation and Configuration Guide - Volume 1 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 *. 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, R2. 7. Click the Method and Persistence tab. In the drop-down list box under LB Method, select round robin. 8. Click Create and click Close. To create a secondary router using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure the backup vserver, for example, vserver-LB-Pri-1. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 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 At the NetScaler command prompt, type: 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. To configure link LB using the configuration utility Chapter 12 Advanced Network Configuration 629 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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, 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. 5. Click Create and click Close. To configure link LB using the NetScaler command line At the NetScaler command prompt, type: 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. Entity Type Name Value Monitor monitor-HTTP-1 NA LB Service route1 10.102.29.5 LB Vserver vserver-LB-3 NA 630 Installation and Configuration Guide - Volume 1 To create a transparent 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 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. 6. Click Create and click Close. To create a transparent monitor using the NetScaler command line At the NetScaler command prompt, type: 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 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, route1, 10.102.29.5, 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. 6. Click Add. The monitor appears in the Configured box. 7. Click Create and click Close. To create a service and bind the monitor to it using the NetScaler command line At the NetScaler command prompt, type: add service route1 10.102.29.5 ANY * Chapter 12 Advanced Network Configuration 631 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 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 Servers (Load Balancing) dialog box appears. 3. In the Name text box, type the name of the vserver, for example, vserver- LB-3. 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, route1. 7. Click Create and click Close. To create an LB server and bind the service to it using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to configure the LB method and persistence, for example, vserver-LB-3. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box 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. Click OK. 632 Installation and Configuration Guide - Volume 1 To set the LB method and persistence using the NetScaler command line At the NetScaler command prompt, type: 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. To configure link LB using the configuration utility 1. In the navigation pane, expand Networks, expand Routing, and click Routes. The Routes page appears in the details pane. 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.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. 5. Click Create and click Close. To configure link LB using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. 5. In the Available NAT IP (s) list box, select the NAT IP address that you 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. Chapter 12 Advanced Network Configuration 633 To configure RNAT using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Select the Use Subnet IP check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable subnet IP mode using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click modes. The Configure Modes dialog box appears. 3. Do one of the following: • To enable Path MTU Discovery, select the Path MTU Discovery check box. • To disable Path MTU Discovery, clear the Path MTU Discovery check box. 634 Installation and Configuration Guide - Volume 1 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. To enable or disable Path MTU discovery using the NetScaler command line At the NetScaler command prompt, type one of the following: 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. Chapter 12 Advanced Network Configuration 635 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 636 Installation and Configuration Guide - Volume 1 • 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). 6. Click Create, and then click Close. To add an IP Tunnel using the NetScaler command line At the NetScaler command prompt, type: 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. Chapter 12 Advanced Network Configuration 637 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 At the NetScaler command prompt, type: sh iptunnel To view the IP Tunnel configuration using the configuration utility 1. In the navigation pane, expand Network, and click IP Tunnels. 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 At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network, and click IP Tunnels. 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. 638 Installation and Configuration Guide - Volume 1 To remove an IP Tunnel using the NetScaler command line At the NetScaler command prompt, type: 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. Don’t 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. Chapter 12 Advanced Network Configuration 639 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. 4. Do one of the following: • 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 Don’t 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 Don’t fragment and drop packet if CPU usage is => textbox. 6. Click Ok. To customize the IP Tunnel using the NetScaler command line At the NetScaler command prompt, type: 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. 640 Installation and Configuration Guide - Volume 1 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). Chapter 12 Advanced Network Configuration 641 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. 642 Installation and Configuration Guide - Volume 1 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. Chapter 12 Advanced Network Configuration 643 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 644 Installation and Configuration Guide - Volume 1 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. Chapter 12 Advanced Network Configuration 645 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. 646 Installation and Configuration Guide - Volume 1 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 Chapter 12 Advanced Network Configuration 647 • 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 1. In the navigation pane, expand System and click Settings. The Settings page appears in the details pane. 2. Under the Modes & Features group, click advanced features. The Configure Advanced Features dialog box appears. 3. Do one of the following: • To enable IPv6, select the IPv6 Protocol Translation check box. • To disable IPv6, clear the IPv6 Protocol Translation check box. 4. Click OK. The Enable/Disable Feature(s)? message appears. 5. Click Yes. 648 Installation and Configuration Guide - Volume 1 To enable or disable IPv6 using the NetScaler command line At the NetScaler command prompt, type one of the following: 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 1. In the navigation pane, expand Network and click IPs. The IPs page appears in the details pane. 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. 5. Click Create and click Close. Parameters Description 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. Chapter 12 Advanced Network Configuration 649 To add an IPv6 address using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network and click IPs. The IPs page appears in the details pane. 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. 6. Click Create and click Close. To add an IPv6 address with prefix length using the NetScaler command line At the NetScaler command prompt, type: add nsip6 2002::50/64 -scope global -type NSIP Verifying the Configuration The following procedure describes the steps to view the IPv6 addresses configured on the NetScaler. 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 At the NetScaler command prompt, type: show ns ip6 650 Installation and Configuration Guide - Volume 1 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 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 Servers (Load Balancing) dialog box 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. 5. In the Protocol drop-down list box, select the type of the vserver, for example, HTTP. 6. Click Create and click Close. To add an IPv6 vserver using the NetScaler command line At the NetScaler command prompt, type: 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. Chapter 12 Advanced Network Configuration 651 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 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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. 5. Click Create and click Close. To add a IPv6 route with VLAN using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 2. Click the IPV6 tab. 3. Select the network from which you want to remove the route, for example,::/0. 4. Click Remove. The Remove pop-up window appears. 5. Click Yes. To remove an IPv6 route using the NetScaler command line At the NetScaler command prompt, type: rm route6 ::/0 2001::1 652 Installation and Configuration Guide - Volume 1 Verifying the Configuration The following procedure describes the steps to verify the configured IPv6 routes by viewing them. To view the IPv6 routes using the configuration utility 1. In the navigation pane, expand Network, expand Routing, and click Routes. The Routes page appears in the details pane. 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 At the NetScaler command prompt, type: 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 At the NetScaler command prompt, type: 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. Chapter 12 Advanced Network Configuration 653 2. Click Clear. To remove neighbor discovery entries using the NetScaler command line At the NetScaler command prompt, type: 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 At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Network and click IPs. The IPs page 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 At the NetScaler command prompt, type: stat protocol ipv6 -detail 654 Installation and Configuration Guide - Volume 1 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. Entity Type Name Value LB Vserver VS1_IPv6 2002::9 Services SVC1 10.102.29.1 SVC2 10.102.29.2 Chapter 12 Advanced Network Configuration 655 The following figure shows the entities and values of the parameters to be configured on the NetScaler. 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 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, SVC1, 10.102.29.1, and 80. 4. In the Protocol drop-down list box, select the type of the service, for example, HTTP. 5. Click Create and click Close. 656 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 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 Servers (Load Balancing) dialog box 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. 5. Click Create and click Close. To create an IPv6 vserver using the NetScaler command line At the NetScaler command prompt, type: 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 1. In the navigation pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the details pane. 2. Select the vserver for which you want to bind the service, for example, SVC1. 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 corresponding to the service that you want to bind to the vserver, for example, SVC1. Click OK. 5. Repeat Steps 1-4 to bind the service SVC2 to the vserver, VS1_IPv6. Chapter 12 Advanced Network Configuration 657 To bind a service to an LB vserver using the NetScaler command line At the NetScaler command prompt, type: 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 configuration utility 1. In the navigation pane, expand Networks and click IPs. The IPs page appears in the details pane. 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 NetScaler command line At the NetScaler command prompt, type: set ns ip6 2002::9 -map 200.200.200.200 658 Installation and Configuration Guide - Volume 1 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 appears in the details pane. 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 At the NetScaler command prompt, type: 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. Chapter 12 Advanced Network Configuration 659 To enable VIP insertion 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. In the Load Balancing Virtual Servers page, select the vserver that you want to enable port insertion, for example, select VS1_IPv6. 3. Click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 4. Click the Advanced tab. 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 At the NetScaler command prompt, type: set lb vserver VS1_IPv6 -insertVserverIPPort ON 660 Installation and Configuration Guide - Volume 1 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. 662 Installation and Configuration Guide - Volume 1 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 user’s 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 Features dialog box appears. 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 At the NetScaler command prompt, type: 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 At the NetScaler command prompt, type: 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. 664 Installation and Configuration Guide - Volume 1 To configure a rewrite action 1. In the left pane, expand Rewrite, then click Actions. The Rewrite Actions page appears in the right pane. 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 At the NetScaler command prompt, type: 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 and the action associated with it is carried out. 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 page appears in the right pane. 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. Chapter 13 URL Rewrite 665 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 At the NetScaler command prompt, type: 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. 666 Installation and Configuration Guide - Volume 1 To bind a rewrite policy to a load balancing vserver 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server you want to bind 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 At the NetScaler command prompt, type: bind lb vserver Vserver-LB-1 -policyname Policy-Rewrite-1 Verifying the Configuration 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. Chapter 13 URL Rewrite 667 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 1. In the left pane, expand Rewrite, then click Actions. The Rewrite Actions page appears in the right pane. 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 At the NetScaler command prompt, type: 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. 668 Installation and Configuration Guide - Volume 1 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. For example, if you want 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") In the String expression for insertion text text area, type a string expression that describes the new string you want to insert. For example, if you want to 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 In the Expression to choose target location text area, type a string expression that describes the string after which you want to insert a new string. For example, if you want 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.") In the String expression for insertion text text area, type a string expression that describes the new string you want to insert. For example, if you want to insert the new string "en." after the string "www." in the hostname, type "en." in the text area. Chapter 13 URL Rewrite 669 REPLACE: Replaces the designated string in the HTTP header or body with a different string In the Expression to choose target text reference text area, type a string expression that describes the string you want to replace with a new string. For example, if you want to replace the entire hostname in the Host header, type HTTP.REQ.HOSTNAM E.SERVER in the text area. In the String expression for replacement text text area, type a string expression that describes the new string you want to insert. For example, if you want to 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. In the Expression to choose target text reference to be deleted text area, type a string expression that describes the string you want to delete. For example, if you want 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. For example, if you want to delete the cache- control header from HTTP responses, type HTTP.RES.HEADER ("Cache-Control") in the text area. Type of Rewrite Action 670 Installation and Configuration Guide - Volume 1 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 expression that describes 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 In the Expression to choose target text references text area, type the part of either the HTTP request or response where you want to carry out the replacement. In the String expression for replacement text text area, type a string expression that describes the new string you 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. In the Expression to choose target text references text area, type the part of either the HTTP request or response where you want the deletion to occur. In the Pattern text area, type a 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 pattern in the target text reference. In the Expression to choose target text references text area, type the part of either the HTTP request or response where you want the deletion to occur. In the String expression for replacement text text area, type a string expression that describes the new string you want to insert In the Pattern text area, type a 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 pattern in the target text reference. In the Expression to choose target text references text area, type the part of either the HTTP request or response where you want the deletion to occur. In the String expression for replacement text text area, type a string expression that describes the new string you want to insert In the Pattern text area, type a string pattern before which the insertion should occur Type of Rewrite Action Chapter 13 URL Rewrite 671 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 1. In the left pane, expand Rewrite, then click Actions. The Rewrite Actions page appears in the right pane. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Rewrite, then click Actions. The Rewrite Actions page appears in the right pane. 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 At the NetScaler command prompt, type: rm rewrite action Action-Rewrite-1 672 Installation and Configuration Guide - Volume 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 page appears in the right pane. 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 At the NetScaler command prompt, type: 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. Chapter 13 URL Rewrite 673 To remove a configured rewrite policy 1. In the left pane, expand Rewrite and click Policies. The Rewrite Policies page appears in the right pane. 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 At the NetScaler command prompt, type: rm rewrite policy Policy-Rewrite-1 Configuring the Rewrite Feature for Commonly Used Deployment Scenarios 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. 674 Installation and Configuration Guide - Volume 1 • 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 NetScaler’s rewrite rule syntax. • Redirect marketing keyword requests. The marketing department at Example, Inc. sets up simplified URLs for certain predefined keyword searches on the company’s Web site. • Redirect an old home page. Example, Inc. recently acquired a smaller competitor, and it now redirects requests for the acquired company’s 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. Chapter 13 URL Rewrite 675 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 Name Action Name Undefined Action Expression Policy-Rewrite- Header_Delete Action-Rewrite- Header_Delete NOREWRITE HTTP.REQ.IS_VALID 676 Installation and Configuration Guide - Volume 1 Note: For information on using the NetScaler policy infrastructure to bind policy expressions on the NetScaler, refer to the “Policies and Expressions” 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 Name Type of Rewrite Action Header Name Value Action-Rewrite- SSL_YES INSERT_HTTP_HE ADER SSL YES Action Name Type of Rewrite Action Header Name Value Action-Rewrite- SSL_NO INSERT_HTTP_HE ADER SSL NO Policy Name Action Name Undefined Action Expression Policy-Rewrite- SSL_YES Action-Rewrite- SSL_YES NOREWRITE CLIENT.TCP.DSTPOR T.EQ(443) Policy Name Action Name Undefined Action Expression Policy-Rewrite- SSL_NO Action-Rewrite- SSL_NO NOREWRITE CLIENT.TCP.DSTPOR T.EQ(80) Chapter 13 URL Rewrite 677 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. Note: For information on using the NetScaler policy infrastructure to bind policy expressions on the NetScaler, refer to the “Policies and Expressions” 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. Note: For information on using the NetScaler policy infrastructure to bind policy expressions on the NetScaler, refer to the “Policies and Expressions” 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 Name Type of Rewrite 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 Name Action Name Undefined Action Expression Policy-Rewrite- Server_Mask Action-Rewrite- Server_Mask NOREWRITE HTTP.RES.IS_VALID 678 Installation and Configuration Guide - Volume 1 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 Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Request_Server_Repl ace REPLACE HTTP.REQ.HOS TNAME.SERVE R "web.hq.example.net" Action Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Response_Server_R eplace REPLACE HTTP.RES.HEA DER("Server") "www.example.com" Policy Name Action Name Undefined Action Expression Policy-Rewrite- Request_Server_R eplace Action-Rewrite- Request_Server_R eplace NOREWRITE HTTP.REQ.HOSTNA ME.SERVER.EQ("ww w.example.com") Policy Name Action Name Undefined Action Expression Policy-Rewrite- Response_Server_ Replace Action-Rewrite- Response_Server_ Replace NOREWRITE HTTP.RES.HEADER(" Server").EQ("web.hq.ex ample.net") Chapter 13 URL Rewrite 679 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. Note: For information on using the NetScaler policy infrastructure to bind policy expressions on the NetScaler, refer to the “Policies and Expressions” 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 the following table. Action Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Display_Results_Nul SiteID REPLACE HTTP.REQ.URL "/results2.html" 680 Installation and Configuration Guide - Volume 1 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 Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Display_Results REPLACE HTTP.REQ.URL "/results.html" Policy Name Action Name Undefined Action Expression 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 Name Action Name Undefined Action Expression 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")) Chapter 13 URL Rewrite 681 Example 7: Marketing Keyword Redirection The marketing department at Example, Inc. wants to set up simplified URLs for certain predefined keyword searches on the company’s 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 Name Type of Rewrite Action Expression to choose target location String expression for replacement text Action-Rewrite- Modify_URL INSERT_BEFORE HTTP.REQ.URL. PATH.GET(1) ""go/ kwsearch.aspkeyword ="l" Policy Name Action Name Undefined Action Expression Policy-Rewrite- Modify_URL Action-Rewrite- Modify_URL NOREWRITE HTTP.REQ.HOSTNA ME.SERVER.EQ("ww w.example.com") 682 Installation and Configuration Guide - Volume 1 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 Name Type of Rewrite Action Expression to choose target reference String expression for 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 Name Action Name Undefined Action Expression Policy-Rewrite- Replace_Hosthead er Action-Rewrite- Replace_Hosthead er NOREWRITE HTTP.REQ.HEADER(" Host").EQ("www.exam ple.com") Action Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Replace_URLr REPLACE HTTP.REQ.URL. PATH_AND_QU ERY "/products/page.htm" Chapter 13 URL Rewrite 683 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 Name Type of Rewrite Action Expression to choose target reference String expression for replacement text Action-Rewrite- Replace_Host REPLACE HTTP.REQ.HOS TNAME "www.newcompany.c om" Policy Name Action Name Undefined Action Expression Policy-Rewrite- Replace-None NOREWRITE !HTTP.REQ.HOSTNA ME.SERVER.EQ("ww w.purchasedcompany.co m") Policy Name Action Name Undefined Action Expression Policy-Rewrite- Replace-Host Action-Rewrite- Replace_Host NOREWRITE HTTP.REQ.HOSTNA ME.SERVER.EQ("ww w.purchasedcompany.co m") Policy Name Action Name Undefined Action Expression Policy-Rewrite- Replace-URL Action-Rewrite- Replace_URL NOREWRITE HTTP.REQ.IS_VALID 684 Installation and Configuration Guide - Volume 1 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. Topics in this chapter include: • 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. 686 Installation and Configuration Guide - Volume 1 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, 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 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 At the NetScaler command prompt, type: 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. Parameter Description Action Name The name of the filter action. This is a mandatory parameter and cannot be changed. The name must not exceed 32 characters. Qualifier Select the type of filter action being performed. The following filter actions can be configured • Reset • Add • Corrupt • Forward • ErrorCode • Drop 688 Installation and Configuration Guide - Volume 1 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 page appears in the right pane. 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 At the NetScaler command prompt, type: 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. Parameter Description Chapter 14 HTML Injection 689 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 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. 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. Parameter Description Filter Namer The name of the filter policy. This is a mandatory parameter and cannot be changed. The name must not exceed 32 characters. 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 690 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 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 Open. The Configure Virtual Server (Load Balancing) dialog box 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 At the NetScaler command prompt, type: 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. Verifying the Configuration Verify that the HTML Injection feature is accurately configured to insert the required data into the HTTP response header. Chapter 14 HTML Injection 691 Viewing the Configured Filter Actions In this section, you will verify that the filter action Action-Filter-1 is accurately configured on the NetScaler. To view configured filter actions 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Protection Features, then click Filter. The Filter Policies page appears in the right pane. 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 At the NetScaler command prompt, type: show filter policy To view details about the filter policy Policy-Filter-1, type show filter policy Policy-Filter-1 692 Installation and Configuration Guide - Volume 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 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server to which you want to bind the filter policy for example, Vserver-LB-1. Click Open. The Configure Virtual Server (Load Balancing) appears. 3. Select the Policies tab to view the policies configured on the NetScaler. 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 the NetScaler command line At the NetScaler command prompt, type: show lb vserver Vserver-LB-1 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. Chapter 14 HTML Injection 693 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 64 bit integer 20 digit number Gives the time, in microseconds, 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 64 bit integer 20 digit number Gives the time, in microseconds, when Netscaler forwarded the first byte of a request to the backend server. It is valid in both prebody and postbody. HTTP.REQ.SEND_T IME_END 64 bit integer 20 digit number Gives the time, in microseconds, 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 64 bit integer 20 digit number Gives the time, in microseconds, when Netscaler received the first byte of a response from the backend server. It is valid in both prebody and postbody. HTTP.RES.RECEIV E_TIME_END 64 bit integer 20 digit number Gives the time, in microseconds, when Netscaler received the last byte of a response from the backend server. It is valid only in postbody. 694 Installation and Configuration Guide - Volume 1 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 64 bit integer 20 digit number Gives the time, in microseconds, 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 64 bit integer 20 digit number Gives the time, in microseconds, when Netscaler forwarded the last byte of a response to the client. It is valid only in postbody. Name Type JavaScript Type Comment Chapter 14 HTML Injection 695 * 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 696 Installation and Configuration Guide - Volume 1 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 appears in the right pane. 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 At the NetScaler command prompt, type: set filter prebodyinjection prebody.js To specify files to be used for postbody injection 1. In the left pane, click Protection Features. The Protection Features page appears in the right pane. 2. In the Protection Features Overview group, click the HTML Injection link. The Configure HTML Injection dialog box appears. Chapter 14 HTML Injection 697 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 At the NetScaler command prompt, type: 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. Creating Filter Actions 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 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears on the right pane. 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-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 At the NetScaler command prompt, type: add filter action Action-Filter-Prebody add prebody To add a Postbody Filter Action, 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears on the right pane. 2. Click the Actions tab. 698 Installation and Configuration Guide - Volume 1 3. Click Add. The Create Filter Action dialog box appears. See figure above. 4. In the Action Name text box, type Action-Filter-Postbody. 5. Under Qualifier, choose Add. 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 At the NetScaler command prompt, type: add filter action Action-Filter-Postbody add postbody Creating Filter Policies 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 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. 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 At the NetScaler command prompt, type: add filter policy Policy-Filter-Prebody -rule ns_true -resAction Action-Filter-Prebody To add a postbody filter policy 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. Chapter 14 HTML Injection 699 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, 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-Postbody, appears in the Filter Policies page. To add a postbody filter policy using the NetScaler command line At the NetScaler command prompt, type: add filter policy Policy-Filter-Postbody -rule ns_true -resAction Action-Filter-Postbody Binding Filter Policies 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 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server you want to bind the 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 NetScaler command line At the NetScaler command prompt, type: bind lb vserver Vserver-LB-2 -policyname Policy-Filter-Prebody 700 Installation and Configuration Guide - Volume 1 To bind a postbody filter policy to a load balancing vserver, 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server you want to bind the 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 NetScaler command line At the NetScaler command prompt, type: 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. Chapter 14 HTML Injection 701 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 702 Installation and Configuration Guide - Volume 1 Enabling the HTML Injection Feature To enable the HTML Injection feature 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 2. In the Modes & Features group, click 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. 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, 1. In the left pane, click Protection Features. The Protection Features page appears in the right pane. Chapter 14 HTML Injection 703 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, 1. In the left pane, click Protection Features. The Protection Features page appears in the right pane. 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 Creating Filter Actions 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 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears on the right pane. 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-Prebody. 5. Under Qualifier, choose Add. 6. In the Value list, select Prebody. 7. Click Create. The filter action Action-Filter-Prebody is created. 704 Installation and Configuration Guide - Volume 1 To add a Postbody Filter Action, 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears on the right pane. 2. Click the Actions tab. 3. Click Add. The Create Filter Action dialog box appears. See figure above. 4. In the Action Name text box, type Action-Filter-Postbody. 5. Under Qualifier, choose Add. 6. In the Value list, select Postbody. 7. Click Create. The filter action Action-Filter-Postbody is created. Creating Filter Policies 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 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. 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-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 postbody filter policy, 1. In the left pane, expand Protection Features, then click Filter. The Filter page appears in the right pane. 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. Chapter 14 HTML Injection 705 4. Under Response Action, choose the filter action, Action-Filter-Postbody, 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-Postbody, appears in the Filter Policies page. Binding Filter Policies 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, 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Select Vserver-LB-ENS and click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 3. Select the Policies tab to view the policies 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-ENS. To bind the postbody filter policy to the load balancing vserver, 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. Select Vserver-LB-ENS and click Open. The Configure Virtual Server (Load Balancing) dialog box appears. 3. Select the Policies tab to view the policies 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-ENS. To measure application performance with a Citrix Edgesight for NetScaler server using the NetScaler command line At the NetScaler command prompt, type: enable ns feature htmlinjection 706 Installation and Configuration Guide - Volume 1 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. Topics in this chapter include: • 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. 708 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand System, then click Settings. The Settings page appears in the right pane. 2. In the Modes & Features group, click Advanced Features. The Configure Advanced Features dialog box appears. 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 At the NetScaler command prompt, type: 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. 710 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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. Parameter Description 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. Chapter 15 Responder 711 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 At the NetScaler command prompt, type: 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 and the action associated with it is carried out. This section describes the procedures to configure responder policies. Creating Responder Policies The following table describes the parameters you must configure to create a responder policy Parameter Description 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. 712 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand Protection Features, then expand Responder and 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 At the NetScaler command prompt, type: 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. Chapter 15 Responder 713 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 1. In the left pane, expand Load Balancing and click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 2. From the list of virtual servers, select the virtual server to which you want to bind the responder policy. For example, select 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 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 At the NetScaler command prompt, type: 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. Verifying the Configuration 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. 714 Installation and Configuration Guide - Volume 1 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 At the NetScaler command prompt, type: 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 At the NetScaler command prompt, type: 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. Chapter 15 Responder 715 To verify that the responder polices are bound to the load balancing vserver 1. In the left pane, expand Load Balancing, then click Virtual Servers. The Load Balancing Virtual Servers page appears in the right pane. 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 At the NetScaler command prompt, type: show lb vserver Vserver-LB-1 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 The following table describes the parameters you must configure to create a redirect action Parameter Description Name The name of the action. This is a mandatory parameter and cannot be changed. The action name must not exceed 31 characters. 716 Installation and Configuration Guide - Volume 1 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 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. 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 At the NetScaler command prompt, type: add responder action Action-Responder-2 redirect “http:// redirectURL” Managing Responder Actions This section describes the procedures to manage any responder 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. 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. Parameter Description Chapter 15 Responder 717 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 1. In the left pane, expand Protection Features, then expand Responder and click Actions. The Responder Actions page appears in the right pane. 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Protection Features, then expand Responder and click Actions. The Responder Actions page appears in the right pane. 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 At the NetScaler command prompt, type: set responder action Action-Responder-1 -target “new_string” 718 Installation and Configuration Guide - Volume 1 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 1. In the left pane, expand Protection Features, then expand Responder and click Actions. The Responder Actions page appears in the right pane. 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 1. In the left pane, expand Protection Features, then expand Responder and click Policies. The Responder Policies page appears in the right pane. Chapter 15 Responder 719 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 At the NetScaler command prompt, type: 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 1. In the left pane, expand Protection Features, then expand Responder and click Policies. The Responder Policies page appears in the right pane. 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 At the NetScaler command prompt, type: rm responder policy Policy-Responder-1 Note: Responder policy removal fails if the policy is bound to any point on the NetScaler 720 Installation and Configuration Guide - Volume 1 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. 722 Installation and Configuration Guide - Volume 1 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 developer’s 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. 724 Installation and Configuration Guide - Volume 1 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> [ <I PAddr ess> <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. 726 Installation and Configuration Guide - Volume 1 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> <I PAddr ess xsi : t ype=" xsd: st r i ng" >10. 100. 101. 1</ I PAddr ess> <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] " > <i t emxsi : t ype=" ns: l bvser ver " > <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> <I PAddr ess xsi : t ype=" xsd: st r i ng >10. 100. 101. 1 </ I PAddr ess> <por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t > </ i t em> <i t emxsi : t ype=" ns: l bvser ver " > <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> <I PAddr ess xsi : t ype=" xsd: st r i ng >10. 100. 101. 2 </ I PAddr ess> <por t xsi : t ype=" xsd: unsi gnedI nt " >80</ por t > </ i t em> </ Li st > </ ns: get l bvser ver Response> 728 Installation and Configuration Guide - Volume 1 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. 730 Installation and Configuration Guide - Volume 1 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. pem–key / 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. pem–key / nsconf i g/ ssl / ssl / r sakey. pem 732 Installation and Configuration Guide - Volume 1 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 system’s 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. 734 Installation and Configuration Guide - Volume 1 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 736 Installation and Configuration Guide - Volume 1 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 compétent. WarningRead the installation instructions carefully before you connect the system to its power source. Attention Avant de brancher le système sur la source d'alimentation, consulter les directives d'installation. SAFETY PERSONNEL WARNING QUALIFIED PERSONNEL WARNING INSTALLATION WARNING 738 Installation and Configuration Guide - Volume 1 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'accéder à cet équ ipement connecté aux lignes électriques, arracher tout bijou (anneaux, colliers et montres compris). Lorsqu'ils sont branchés à l'alimentation et reliés à la terre, les objets métalliques chauffent, ce qui peut provoquer des blessures graves ou souder l'objet métallique 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 châssis 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 système principal de déconnexion. WarningThe device is designed to work with TN power systems. Attention Ce dispositif a été conçu pour fonctionner avec des systèmes 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 connectée en premier et déconnectée 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 hôte est relié à la terre lors de l'utilisation normale. WarningThis product relies on the building’s 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 dépend de l'installation électrique du local. Vérifier 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 système non équipé d'un commutateur marche-arrêt, débrancher le cordon d'alimentation. GROUND CONNECTION WARNING GROUNDED EQUIPMENT WARNING CIRCUIT BREAKER (15 A) WARNING NO ON/OFF SWITCH WARNING 740 Installation and Configuration Guide - Volume 1 WarningCare must be given while/before connecting units to the supply circuit so that the wiring is not overloaded. Attention Veillez à bien connecter les unités 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 building’s installation for short-circuit (overcurrent). Attention Ne pas travailler sur le système ni brancher ou débrancher les câbles pendant un orage. Pour ce qui est de la protection contre les courts-circuits (surtension), ce produit dépend 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 systèmes munis d'un commutateur marche-arrêt, des tensions de ligne sont présentes dans l'alimentation quand le cordon est branché, même si le commutateur est à l'arrêt. Avec les systèmes sans commutateur marche-arrêt, 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 opérations de montage ou de réparation de cette unité en casier, il convient de prendre des précautions spéciales afin de maintenir la stabilité du système. Les directives ci-dessous sont destinées à assurer la protection du personnel: • Si cette unité constitue la seule unité montée en casier, elle doit être placée dans le bas. • Si cette unité est montée dans un casier partiellement rempli, charger le casier de bas en haut en plaçant l'élément le plus lourd dans le bas. • Si le casier est équipé de dispositifs stabilisateurs, installer les stabilisateurs avant de monter ou de réparer 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 généralement soumis à des lois et/ou directives de respect de l’environment. Renseignez-vous auprès de l’organisme compétent. 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 742 Installation and Configuration Guide - Volume 1 Attention Danger d'explosion si la pile (batterie) (CR 2032) n'est pas remplacée correctement. Ne la remplacer que par une pile (batterie) de type équivalent, recommandée par le fabricant. Jeter les piles (batteries) usagées conformément 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 power supply in volts -5.500 through - 4.500 Volts No +12.0 V Supply Voltage Measures the +12V power supply in volts 10.800 through 13.200 Volts No -12.0 V Supply Voltage Measures the -12V power supply in volts -13.200 through -10.800 Volts No Battery Voltage (Volts) Measures the battery voltage Platform- dependent No 744 Installation and Configuration Guide - Volume 1 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 Description Reference 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 Description Reference Values SNMP Alarm Support 746 Installation and Configuration Guide - Volume 1 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 10010 • 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 • Citrix NetScaler MPX 15000 • Citrix NetScaler MPX 17000 Citrix NetScaler 7000 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. 748 Installation and Configuration Guide - Volume 1 Citrix NetScaler 7000 Front Panel The LCD display provides real-time information about the appliance’s 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 The Citrix NetScaler 9010 is a 2U appliance that ships with 1 single-core 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 750 Installation and Configuration Guide - Volume 1 Citrix NetScaler 9010 Front Panel with SFP Ports For all 9010 models, the LCD display provides real-time information about the appliance’s 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: • One RS232 serial console port. • 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. 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. 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 Citrix NetScaler 9010 Back Panel 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 removable compact flash that is used to store the operating system. • A removable hard disk drive that is used to store user data. • 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 752 Installation and Configuration Guide - Volume 1 Citrix NetScaler 10010 The Citrix NetScaler 10010 is a 2U appliance that ships with 1 single-core processor and 4 gigabytes (GB) of memory. The following figure shows the front panel of the 10010. Citrix NetScaler 10010 Front Panel The LCD display provides real-time information about the appliance’s 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 10010 has the following ports: • One RS232 serial console port. • 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. 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. The following figure shows the back panel of the 10010. LCD Console Port SFP Ports 10/100/1000BASE-T Ethernet Ports Appendix E 753 Citrix NetScaler 10010 Back Panel The following components are visible on the back panel of the 10010: • A power switch, which turns off power to the 10010, just as if you were to unplug both power supplies. • One 10/100BASE-T copper Ethernet port, numbered 0/1. • A removable compact flash that is used to store the operating system. • A removable hard disk drive that is used to store user data. • 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. Press this button to stop the power alarm from sounding when you have plugged the 10010 into only one power outlet or when one power supply is malfunctioning and you want to continue operating the 10010 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 10010 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 754 Installation and Configuration Guide - Volume 1 Citrix NetScaler 12000 and 12000-10G The Citrix NetScaler 12000 is a 2U appliance that ships with 2 single-core 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 The LCD display provides real-time information about the appliance’s 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. Console Port SFP Ports LCD Console Port SFP Ports LCD 10-Gigabit XFP Ports Appendix E 755 The 12000 has the following ports: • One RS232 serial console port. • 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. 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. The following figure shows the back panel of all 12000 models. 756 Installation and Configuration Guide - Volume 1 Citrix NetScaler 12000 Back Panel The following components are visible on the back panel of the 12000: • A power switch, which turns off power to the 12000, just as if you were to unplug both power supplies. • One 10/100/1000BASE-T copper Ethernet port, numbered 0/1. • A removable compact flash that is used to store the operating system. • A removable hard disk drive that is used to store user data. • A non-maskable interrupt (NMI) button, which signals the 12000 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 12000 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 12000 into only one power outlet or when one power supply is malfunctioning and you want to continue operating the 12000 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 12000 functions properly with a single power supply; the extra power supply serves as a backup. Citrix NetScaler MPX 5500 The Citrix NetScaler MPX 5500 is a 1U appliance that ships with 1 dual-core processor and 4 gigabytes (GB) of memory. Disable Alarm Button Fans Power Supply Power Switch Hard Disk Drive 10/100BASE-T Ethernet Port 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 The LCD display provides real-time information about the appliance’s 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. Note: The LCD keypad is not available in this release. The MPX 5500 has the following ports: • One RS232 serial console port. • 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. 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. The following figure shows the back panel of the MPX 5500. Console Port Management Ports Ethernet Ports LCD LCD Keypad 758 Installation and Configuration Guide - Volume 1 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. • A removable hard disk drive that is used to store user data. • 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 perform an orderly shutdown after saving all files. You must use a pen, 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 LCD display provides real-time information about the appliance’s 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. Note: The LCD keypad is not available in this release. The MPX 7500 and MPX 9500 appliance has the following ports: • One RS232 serial console port. • Two 10/100/1000Base-T copper Ethernet ports numbered 0/1 and 0/2 from left to right. These ports are used to connect directly to the appliance for system administration functions. • 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. 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. The following figure shows the back panel of the MPX 7500 and MPX 9500. Console Port Management Ports Ethernet Ports LCD LCD Keypad 760 Installation and Configuration Guide - Volume 1 Citrix NetScaler MPX 7500/9500 Back Panel The following components are visible on the back panel of the MPX 7500 and MPX 9500: • A 4 GB removable compact flash that is used to store the operating system. • 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. • A removable hard disk drive that is used to store user data. • One USB port. Note: The USB port is not available in this release. • A non-maskable interrupt (NMI) button, which signals the appliance to perform an orderly shutdown after saving all files. You must use a pen, pencil, or other pointed object to press this red button, which is located inside a small hole to prevent it being pressed accidentally. • A disable alarm button. This button is functional only when the appliance has two power supplies. Press this button to stop the power alarm from sounding when you have 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 LCD display provides real-time information about the appliance’s 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. Note: The LCD keypad is not available in this release. The MPX 9700, MPX 10500, and MPX 12500 appliances have the following ports: • One RS232 serial console port. • Two 10/100/1000Base-T copper Ethernet ports numbered 0/1 and 0/2 from left to right. These ports are used to connect directly to the appliance for system administration functions. • 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 762 Installation and Configuration Guide - Volume 1 • 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. 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. 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 4 GB removable compact flash that is used to store the operating system. • 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. • A removable hard disk drive that is used to store user data. • One USB port. Note: The USB port is not available in this release. • A non-maskable interrupt (NMI) button, which signals the appliance to perform an orderly shutdown after saving all files. You must use a pen, pencil, or other pointed object to press this red button, which is located inside a small hole to prevent it being pressed accidentally. 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. Press this button to stop the power alarm from sounding when you have 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. Citrix NetScaler MPX 15000 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 LCD display provides real-time information about the appliance’s 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 appliance has the following ports: • One RS232 serial console port. • 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 764 Installation and Configuration Guide - Volume 1 • 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. 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. The following figure shows the back panel of the MPX 15000. Citrix NetScaler MPX 15000 Back Panel The following components are visible on the back panel of the MPX 15000: • A removable hard disk drive that is used to store user data. • 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 MPX 15000 functions properly with a single power supply; the extra power supply serves as a backup. • A non-maskable interrupt (NMI) button, which signals the MPX 15000 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 removable compact flash that is used to store the operating system. Fans Power Supply Hard Disk Drives Compact Flash NMÌ Button Appendix E 765 Citrix NetScaler MPX 17000 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 The LCD display provides real-time information about the appliance’s 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. Depending on the model, the appliance has the following ports: • One RS232 serial console port. • 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 766 Installation and Configuration Guide - Volume 1 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. 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 figure shows the back panel of the MPX 17000. Citrix NetScaler MPX 17000 Back Panel The following components are visible on the back of the MPX 17000: • One removable hard disk drive that is used to store user data. • 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 MPX 17000 functions properly with a single power supply; the extra power supply serves as a backup. • A non-maskable interrupt (NMI) button, which signals the MPX 17000 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 removable compact flash that is used to store the operating system. 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 768 Installation and Configuration Guide - Volume 1 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 page appears in the right pane. 770 Installation and Configuration Guide - Volume 1 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. 772 Installation and Configuration Guide - Volume 1 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. 774 Installation and Configuration Guide - Volume 1 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 shown in the following figure. 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 776 Installation and Configuration Guide - Volume 1 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, and flow control OFF. 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, and flow control OFF. 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, and flow control OFF. Indicates a speed rate of 100 megabits per second, half duplex mode, and flow control OFF. 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 # 778 Installation and Configuration Guide - Volume 1 Indicates receive speed is 75% of line speed. Indicates receive speed is 100% of line speed. 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. 780 Installation and Configuration Guide - Volume 1 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 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 : 180 sec Ser ver : 360 sec Cl i ent I P: DI SABLED Ser ver I D : 0 Moni t or Thr eshol d : 0 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 Max Conn: 0 Max Req: 0 Max Bandwi dt h: 0 kbi t s Use Sour ce I P: NO 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 : 360 sec Ser ver : 360 sec Cl i ent I P: DI SABLED Ser ver I D : 0 Moni t or Thr eshol d : 0 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 782 Installation and Configuration Guide - Volume 1 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. 784 Installation and Configuration Guide - Volume 1 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 786 Installation and Configuration Guide - Volume 1 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. 788 Installation and Configuration Guide - Volume 1 > 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 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 n12345 newsopi n12345 newuser pi n12345 - 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: 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 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 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 790 Installation and Configuration Guide - Volume 1 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 properties, 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 viewing properties, 80 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 IPv6 address types, 644 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 466, 469 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 neighbor discovery, 641 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 792 Installation and Configuration Guide - Volume 1 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 link load balancing, 622 load balancing setup, 323 metrics, 253 network interfaces, 67 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 link load balancing, 629 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 content filtering 508 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 viewing properties, 327 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 794 Installation and Configuration Guide - Volume 1 customizing content switching setup, 334 load balancing configuration, 131 monitors, 247 customizing, W3C format 556 D default buffer size web server logging 539 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 HA command propagation 19 HA synchronization 17 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 service, 208 enabling on vserver, 200 dynamic routing concepts, 602 enabling and disabling, 603 dynamic routing protocols viewing routes, 619 dynamic spillover configuring, 190 E egress rules applying, 83 enable responder 708 Index 795 enable feature compression 466 content filtering 509 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 content switching, 321 delayed cleanup of vserver connections, 345 HA command propagation 19 HA synchronization 17 HTML Injection 686 load balancing, 115 OSPF, 608 RHI, 617 RIP, 603 SNIP mode, 45 URL Rewriting 662 use source IP address, 216 web server logging 538 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 link aggregate channels, 78 MBF mode, 59 monitors, 229 network interfaces, 70 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 work load manager, 259 entry time-out session, 621 event undefined 709 extended ACLs clearing, 103 configuring, 100 creating, 100 enabling and disabling, 103 removing, 102 resetting priorities, 104 verifying, 106 viewing properties, 106 viewing statistics, 107 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 796 Installation and Configuration Guide - Volume 1 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 enabling and disabling, 52 managing, 51 modifying, 47 removing, 51 viewing properties, 53 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 enabling and disabling, 647 multicast listener discovery, 641 neighbor discovery, 642 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 viewing properties, 80 large scale deployment managing, 263 layer 2 mode enabling and disabling, 57 layer 3 mode enabling and disabling, 58 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 798 Installation and Configuration Guide - Volume 1 link aggregate channel binding an interface, 74 creating, 73 enabling and disabling, 78 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 network interfaces, 69 rewrite actions 666 servers, 125 service groups, 272 services, 127 static routes, 650 VLANs, 92 vservers, 129 work load manager, 262 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 enabling and disabling, 59 measuring application performance 700 memory usage limit TCP buffering 461 metric table creating, 254 unbinding, 256 metric tables removing, 255 viewing properties, 256 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 content switching policies, 331 host header, 657 IP addresses, 47 LB configuration, 125 monitors, 226 service groups, 270 VLANs, 91 work load manager, 261 modifying,HA configuration 13 monitor enabling and disabling, 229 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 800 Installation and Configuration Guide - Volume 1 network interface binding to VLAN, 90 clearing statistics, 71 configuring, 67 enabling and disabling, 70 managing, 69 resetting, 70 unbinding froma VLAN, 92 verifying, 71 viewing properties, 72 viewing statistics, 72 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 configuring, 299, 307 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 enabling and disabling, 633 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 load balancing configuration, 185 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 content switching policies, 334 content switching vservers, 330 extended ACLs, 102 IP Addresses, 51 IPv6 routes, 651 link aggregate channels, 77 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 work load manager, 262 renumbering extended ACLs, 104 requesting NAT statistics, 600 resetting network interfaces, 70 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 verifying configuration 34 route monitor,binding to HA node 34 802 Installation and Configuration Guide - Volume 1 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 enabling and disabling, 126 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 enabling and disabling, 128 managing, 127 removing, 127 unbinding froma vserver, 129 viewing bindings, 125 viewing properties, 124 viewing statistics, 124 service group binding an IP address, 268 binding to a vserver, 267 configuring, 266 creating, 266 enabling and disabling, 274 managing, 272 modifying, 270 removing, 272 unbinding a member, 273 unbinding froma vserver, 273 unbinding monitors, 274 viewing properties, 275 viewing statistics, 276 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 viewing properties, 99 viewing statistics, 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 configuring, 188, 341 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 verifying configuration 359 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 804 Installation and Configuration Guide - Volume 1 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 configuring, 199, 207 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 configure service 458, 460 configured parameters 458 definition 454 enabling on service, 210 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 content switching, 320 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 work load manager, 262 unbinding content switching policies content switching vservers, 329 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 IPv6 address types, 644 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) enabling and disabling, 64 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 link aggregate channels, 80 load balancing configuration, 123 network interfaces, 71 simple ACLs, 99 VLANs, 94 verifying configuration HTML Injection 690 viewing content switching policies, 328 discovered neighbors, 652 filter actions 691 filter policies 691 IPv6 addresses, 649 load balancing configuration, 328 monitors, 231 service bindings, 125 virtual server 692 vserver properties, 123 work load manager, 263 806 Installation and Configuration Guide - Volume 1 viewing properties ARP entries, 56 bridge tables, 108 channels, 80 content switching vservers, 327 extended ACLs, 106 IP addresses, 53 LACP, 80 metric tables, 256 network interfaces, 72 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 viewing properties, 94 viewing statistics, 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 viewing statistics, 123 vserver parameters usage, 120, 322 vservers binding policies, 325 binding to work load manager, 260 viewing properties, 123 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 web server logging 537 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