Citrix Systems Network Router 9 2 Users Manual Policy

9.2 to the manual 7326bdf5-cbfe-45df-89bf-9f7c76077eaa

: Citrix-Systems Citrix-Systems-Network-Router-9-2-Users-Manual-534679 citrix-systems-network-router-9-2-users-manual-534679 citrix-systems pdf

Open the PDF directly: View PDF .
Page Count: 302

Download
Open PDF In Browser	View PDF

Citrix NetScaler
Policy Configuration and Reference Guide

Citrix® NetScaler® 9.2

Copyright and Trademark Notice
© CITRIX SYSTEMS, INC., 2010. 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 SUBJECT
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 radiofrequency 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 © Jean-loup Gailly and Mark Adler. Copyright © 1999, 2000 by Jef 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 Juniper Networks, Inc. All rights reserved. Copyright © 2001, 2002
Networks Associates Technology, Inc. All rights reserved. Copyright (c) 2002 Networks Associates Technology, Inc. Copyright 19992001© 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 Jonathan 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 Jason L. Wright. Copyright © 2000 Theo de Raadt. Copyright © 2001 Patrik Lindergren.
All rights reserved.

Last Updated: July 2010

C ONTENTS

Contents

Preface
About This Guide . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . ix
New in This Release . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Audience . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xi
Formatting Conventions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xii
Related Documentation. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Getting Service and Support. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiii
Documentation Feedback . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . xiv

Chapter 1

Introduction to Policies and Expressions
Advanced and Classic Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .1
Benefits of Using Advanced Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .2
Basic Components of an Advanced or a Classic Policy. . . . . . . . . . . . . . . . . . . .2
How Different NetScaler Features Use Policies. . . . . . . . . . . . . . . . . . . . . . . . . .3
About Actions and Profiles . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5
About Policy Bindings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7
About Evaluation Order of Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8
Order of Evaluation Based on Traffic Flow . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
Advanced and Classic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
About Advanced Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9
About Classic Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10
About Migration from Classic to Advanced Policies and Expressions. . . . . . . . . .11
Before You Proceed . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Chapter 2

Configuring Advanced Policies
Creating or Modifying an Advanced Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14
Policy Configuration Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15

iv

Citrix NetScaler Policy Configuration and Reference Guide

Binding Advanced Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16
Feature-Specific Differences in Policy Bindings . . . . . . . . . . . . . . . . . . . . . . . .16
Bind Points and Order of Evaluation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .18
Advanced Policy Evaluation Across Features . . . . . . . . . . . . . . . . . . . . . . . . . .19
Entries in a Policy Bank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19
Evaluation Order Within a Policy Bank . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20
How Policy Evaluation Ends . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21
How Features Use Actions After Policy Evaluation . . . . . . . . . . . . . . . . . . . . .22
Binding a Policy Globally . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22
Binding a Policy to a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .24
Displaying Policy Bindings. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Unbinding an Advanced Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25
Creating Policy Labels . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Creating a Policy Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27
Binding a Policy to a Policy Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .29
Configuring a Policy Label or Virtual Server Policy Bank . . . . . . . . . . . . . . . . . . .29
Configuring a Policy Label . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .30
Configuring a Policy Bank for a Virtual Server . . . . . . . . . . . . . . . . . . . . . . . . .32
Invoking or Removing a Policy Label or Virtual Server Policy Bank . . . . . . . . . .33
Configuring and Binding Policies with the Policy Manager . . . . . . . . . . . . . . . . . .35

Chapter 3

Configuring Advanced Expressions: Getting Started
Expression Characteristics . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Basic Elements of an Advanced Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .40
Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .41
Single-Element Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Operations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .43
Basic Operations on Expression Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .44
Compound Advanced Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .45
Booleans in Compound Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Parentheses in Compound Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Compound Operations for Strings . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .46
Compound Operations for Numbers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .48
Classic Expressions in Advanced Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Configuring Advanced Expressions in a Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . .57
Configuring Named Advanced Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .60
Configuring Advanced Expressions Outside the Context of a Policy. . . . . . . . . . .61

Contents

Chapter 4

v

Advanced Expressions: Evaluating Text
About Text Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
About Operations on Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .64
Compounding and Precedence in Text Expressions. . . . . . . . . . . . . . . . . . . . . .65
Categories of Text Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .65
Guidelines for Text Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .66
Expression Prefixes for Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .67
Expression Prefixes for Text in HTTP Requests and Responses. . . . . . . . . . . .67
Expression Prefixes for VPNs and Clientless VPNs . . . . . . . . . . . . . . . . . . . . .76
Operations on Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Basic Operations on Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .86
Operations for Calculating the Length of a String . . . . . . . . . . . . . . . . . . . . . . .87
Operations for Controlling Case Sensitivity. . . . . . . . . . . . . . . . . . . . . . . . . . . .87
Complex Operations on Text . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Operations on the Length of a String . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .88
Operations on a Portion of a String. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .89
Operations for Comparing the Alphanumeric Order of Two Strings . . . . . . . .90
Extracting the nth Integer from a String of Bytes that Represent Text . . . . . . .91
Converting Text to a Hash Value . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .91
Encoding and Decoding Text by Applying the Base64 Encoding Algorithm. .92
Refining the Search in a Rewrite Action by Using the EXTEND Operator . . .92
Converting Text to Hexadecimal Format . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .93

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers
Format of Dates and Times in an Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . .96
Dates and Times in a Rewrite Action. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Expressions for the NetScaler System Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .97
Expressions for SSL Certificate Dates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .101
Expressions for HTTP Request and Response Dates . . . . . . . . . . . . . . . . . . . . . .110
Expression Prefixes for Numeric Data Other Than Date and Time . . . . . . . . . . .111

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data
About Evaluating HTTP and TCP Payload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
About Evaluating the Payload Body. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .114
Expressions for HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .115
Prefixes for HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .116
Operations for HTTP Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .122
Prefixes for Cache-Control Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126
Operations for Cache-Control Headers. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .126

vi

Citrix NetScaler Policy Configuration and Reference Guide

Expressions for Extracting Segments of URLs . . . . . . . . . . . . . . . . . . . . . . . . . . .129
Expressions for Numeric HTTP Payload Data Other Than Dates . . . . . . . . . . . .130
Operations for HTTP, HTML, and XML Encoding and “Safe” Characters. . . . .131
Expressions for TCP, UDP, and VLAN Data . . . . . . . . . . . . . . . . . . . . . . . . . . . .134
XPath and JSON Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .136

Chapter 7

Advanced Expressions: Parsing SSL Certificates
About SSL and Certificate Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .141
Prefixes for Text-Based SSL and Certificate Data . . . . . . . . . . . . . . . . . . . . . . . .142
Prefixes for Numeric Data in SSL Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . .143
Expressions for SSL Certificates . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .143

Chapter 8

Advanced Expressions: IP and MAC Addresses, Throughput, VLAN IDs
Expressions for IP Addresses and IP Subnets . . . . . . . . . . . . . . . . . . . . . . . . . . . .149
Prefixes for IPV4 Addresses and IP Subnets . . . . . . . . . . . . . . . . . . . . . . . . . .150
Operations for IPV4 Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .150
About IPv6 Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .151
Expression Prefixes for IPv6 Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .152
Operations for IPV6 Prefixes . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .153
Expressions for MAC Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Prefixes for MAC Addresses. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Operations for MAC Addresses . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .154
Expressions for Numeric Client and Server Data . . . . . . . . . . . . . . . . . . . . . . . . .155

Chapter 9

Advanced Expressions: String Sets, String Patterns, and Data Formats
Matching Text With Strings in a Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .157
Operators That Use a Pattern Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .158
Configuring a Pattern Set . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .160
Matching Text With a Pattern. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .164
Basic Characteristics of Regular Expressions. . . . . . . . . . . . . . . . . . . . . . . . . .165
Operations for Regular Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .165
Transforming Text and Numbers into Different Data Types . . . . . . . . . . . . . . . .169

Chapter 10

Advanced Policies: Controlling the Rate of Traffic
About Policies that Monitor the Traffic Rate. . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Expressions for Controlling the Traffic Rate . . . . . . . . . . . . . . . . . . . . . . . . . . . . .183
Configuring Policies That Control the Traffic Rate. . . . . . . . . . . . . . . . . . . . . . . .184

Contents

Chapter 11

vii

Advanced Policies: Sending HTTP Service Callouts to Applications
About Calling Out to an External Application. . . . . . . . . . . . . . . . . . . . . . . . . . . .186
About HTTP Callout Policies. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .186
Note on the Format of an HTTP Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Note on the Format of an HTTP Response. . . . . . . . . . . . . . . . . . . . . . . . . . . .187
Configuring an HTTP Callout Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .188
Invoking an HTTP Callout Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .193
Notes on Invoking a Callout . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .194

Chapter 12

Configuring Classic Policies and Expressions
Where Classic Policies Are Used . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .197
Viewing Classic Policies . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .200
Configuring a Classic Policy . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .201
Configuring a Classic Expression . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .203
Binding a Classic Policy. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .207
Creating Named Classic Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .209

Appendix A

Expressions Reference
Advanced Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .211
Classic Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
Operators . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .224
General Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .225
Client Security Expressions. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .228
Network-Based Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .229
Date/Time Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
File System Expressions . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .230
Built-In Named Expressions (General). . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .232
Built-In Named Expressions (Anti-Virus) . . . . . . . . . . . . . . . . . . . . . . . . . . . .235
Built-In Named Expressions (Personal Firewall) . . . . . . . . . . . . . . . . . . . . . . .235
Built-In Named Expressions (Client Security) . . . . . . . . . . . . . . . . . . . . . . . . .236

Appendix B

Summary Examples of Advanced Expressions and Policies

Appendix C

Tutorial Examples of Advanced Policies for Rewrite
Redirecting an External URL to an Internal URL . . . . . . . . . . . . . . . . . . . . . . . . .245
Redirecting a Query . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Redirecting HTTP to HTTPS . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .247
Removing Unwanted Headers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .248

viii

Citrix NetScaler Policy Configuration and Reference Guide

Reducing Web Server Redirects. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
Masking the Server Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .249
. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .250

Appendix D

Tutorial Examples of Classic Policies
Access Gateway Policy to Check for a Valid Client Certificate . . . . . . . . . . . . . .251
Application Firewall Policy to Protect a Shopping Cart Application . . . . . . . . . .252
Application Firewall Policy to Protect Scripted Web Pages . . . . . . . . . . . . . . . . .255
DNS Policy to Drop Packets from Specific IPs . . . . . . . . . . . . . . . . . . . . . . . . . . .256
SSL Policy to Require Valid Client Certificates . . . . . . . . . . . . . . . . . . . . . . . . . .257

Appendix E

Migration of Apache mod_rewrite Rules to Advanced Policies
Converting URL Variations into Canonical URLs . . . . . . . . . . . . . . . . . . . . . . . .260
Converting Host Name Variations to Canonical Host Names. . . . . . . . . . . . . . . .260
Moving a Document Root . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .261
Moving Home Directories to a New Web Server . . . . . . . . . . . . . . . . . . . . . . . . .262
Working with Structured Home Directories . . . . . . . . . . . . . . . . . . . . . . . . . . . . .262
Redirecting Invalid URLs to Other Web Servers . . . . . . . . . . . . . . . . . . . . . . . . .263
Rewriting a URL Based on Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .264
Redirecting to a New File Name (Invisible to the User) . . . . . . . . . . . . . . . . . . . .265
Redirecting to New File Name (User-Visible URL) . . . . . . . . . . . . . . . . . . . . . . .265
Accommodating Browser Dependent Content . . . . . . . . . . . . . . . . . . . . . . . . . . .266
Blocking Access by Robots . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .267
Blocking Access to Inline Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
Creating Extensionless Links . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .268
Redirecting a Working URI to a New Format . . . . . . . . . . . . . . . . . . . . . . . . . . . .270
Ensuring That a Secure Server Is Used for Selected Pages . . . . . . . . . . . . . . . . . .271

Appendix F

New Advanced Expression Operators in This Release
Operators for Extracting and Evaluating Numeric Data . . . . . . . . . . . . . . . . . . . .273
Operators for Extracting and Evaluating Text . . . . . . . . . . . . . . . . . . . . . . . . . . . .274
Operators for Extracting and Evaluating HTTP Data . . . . . . . . . . . . . . . . . . . . . .275
Operators for the CLIENT and ipv6 Expression Prefixes . . . . . . . . . . . . . . . . . . .275
XPath and JSON Operators for Evaluating XML and JSON Data . . . . . . . . . . . .276
Operators for Evaluating Groups to Which a User Belongs . . . . . . . . . . . . . . . . .276

Index

. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 277

P REFACE

Preface

Before you begin to configure policies and expressions as described in this
document, take a few minutes to review this chapter and learn about related
documentation, other support options, and ways to send us feedback.
In This Preface
About This Guide
New in This Release
Audience
Formatting Conventions
Related Documentation
Getting Service and Support
Documentation Feedback

About This Guide
The Citrix NetScaler Policy Configuration and Reference Guide provides
configuration and reference information for controlling the behavior of NetScaler
features by using policies and expressions. This guide discusses classic and
advanced policies and expressions. It also covers additional topics for advanced
policy configuration, including policy labels, HTTP service callouts, traffic rate
policies, and pattern sets.
This guide provides the following information:
•

Chapter 1, “Introduction to Policies and Expressions.” Describes the
purpose of expressions, policies, and actions, and how different NetScaler
applications make use of them.

•

Chapter 2, “Configuring Advanced Policies.” Describes the structure of
advanced policies and how to configure them individually and as policy
banks.

x

Citrix NetScaler Policy Configuration and Reference Guide

•

Chapter 3, “Configuring Advanced Expressions: Getting Started.”
Describes expression syntax and semantics, and briefly introduces how to
configure expressions and policies.

•

Chapter 4, “Advanced Expressions: Evaluating Text.” Describes
expressions that you configure when you want to operate on text (for
example, the body of an HTTP POST request or the contents of a user
certificate).

•

Chapter 5, “Advanced Expressions: Working with Dates, Times, and
Numbers.” Describes expressions that you configure when you want to
operate on any type of numeric data (for example, the length of a URL, a
client's IP address, or the date and time that an HTTP request was sent).

•

Chapter 6, “Advanced Expressions: Parsing HTTP, TCP, and UDP Data.”
Describes expressions for parsing IP and IPv6 addresses, MAC addresses,
and data that is specific to HTTP and TCP traffic.

•

Chapter 7, “Advanced Expressions: Parsing SSL Certificates.” Describes
how to configure expressions for SSL traffic and client certificates, for
example, how to retrieve the expiration date of a certificate or the certificate
issuer.

•

Chapter 8, “Advanced Expressions: IP and MAC Addresses, Throughput, VLAN
IDs.” Describes expressions that you can use to work with any other client-

or server-related data not discussed in other chapters.
•

Chapter 9, “Advanced Expressions: String Sets, String Patterns, and Data
Formats.” Describes expressions that you can use to parse structured text
and convert it into different formats.

•

Chapter 10, “Advanced Policies: Controlling the Rate of Traffic.”
Describes policies that you can configure to control the flow of traffic to
different destinations, primarily for the purpose of throttling excessive
traffic.

•

Chapter 11, “Advanced Policies: Sending HTTP Service Callouts to
Applications.” Describes expressions that you can use to send HTTP
requests to external applications.

•

Chapter 12, “Configuring Classic Policies and Expressions.” Provides
details on how to configure the simpler policies and expressions known as
classic policies and classic expressions.

•

Appendix A, “Expressions Reference.” A reference for classic and
advanced expression arguments.

•

Appendix B, “Summary Examples of Advanced Expressions and Policies.”
Examples of classic and advanced expressions and policies, in both quick
reference and tutorial format, that you can customize for your own use.

Preface

xi

•

Appendix C, “Tutorial Examples of Advanced Policies for Rewrite.”
Examples of advanced policies for use in the Rewrite feature.

•

Appendix D, “Tutorial Examples of Classic Policies.” Examples of classic
policies for NetScaler features such as Application Firewall and SSL.

•

Appendix E, “Migration of Apache mod_rewrite Rules to Advanced
Policies.” Examples of functions that were written using the Apache HTTP
Server mod_rewrite engine, with examples of these functions after
translation into Rewrite and Responder policies on the NetScaler.

•

Appendix F, “New Advanced Expression Operators in This Release.” A
summary of the new advanced expression operators and methods. This list
supplements the advanced expressions documented in Appendix A.

New in This Release
NetScaler nCore Technology uses multiple CPU cores for packet handling and
greatly improves the performance of many NetScaler features. Release 9.2 adds
nCore support for many additional features, including load balancing and virtual
private networks (VPNs). For a summary of the new features and remaining
unsupported nCore features, see the Citrix NetScaler 9.2 Release Notes.
You can now use advanced policies and expressions to configure Compression,
Authorization, and Application Firewall. Advanced expressions provide a rich set
of expression elements along with options to control the flow of evaluation within
a policy bank. These elements and options enable you to maximize the
capabilities of these NetScaler features. Advanced policies, which comprise a set
of rules and actions that use the advanced expression format, further enhance
your ability to analyze data at various network layers and at different points along
the flow of traffic. For more information about the benefits of using advanced
policies and expressions, see “Benefits of Using Advanced Policies,” on page 2.
The Citrix NetScaler Policy Configuration and Reference Guide has been
updated with information about new operators that you can use in advanced
policy expressions. For more information about the new expression operators, see
Appendix F, “New Advanced Expression Operators in This Release.”

Audience
This guide is intended for the following audience:
•

NetScaler administrators who want to learn more about policies and
expressions or who need to configure policies to control the behavior of
particular features.

xii

Citrix NetScaler Policy Configuration and Reference Guide

•

NetScaler programmers who want to develop advanced policies and
expressions.

The concepts and tasks described in this guide require you to have a basic
understanding of the NetScaler system and the particular feature for which you
want to configure a policy.

Formatting Conventions
This documentation uses the following formatting conventions
Formatting Conventions
Convention

Meaning

Boldface

Information that you type exactly as shown (user input);
elements in the user interface.



Placeholders for information or parameters that you
provide. For example,  in a command means
you type the actual name of a file. Also, new terms, and
words used as specific terms, as opposed to their ordinary,
descriptive meaning.

Monospace

System output or characters in a command line. User input
and placeholders also are formatted using monspace text.

{braces}

A series of items, one of which is required in command
statements. For example, { yes | no } means you must type
yes or no. Do not type the braces themselves.

[brackets]

Optional items in command statements. For example, in
the following command, [-range
positiveInteger] means that you have the option of
entering a range, but it is not required:
add lb vserver name serviceType IPAddress
port [-range positiveInteger]

Do not type the brackets themselves.
| (vertical bar)

A separator between options in braces or brackets in
command statements. For example, the following indicates
that you choose one of the following load balancing
methods:
lbMethod = ( ROUNDROBIN | LEASTCONNECTION |
LEASTRESPONSETIME | URLHASH | DOMAINHASH |
DESTINATIONIPHASH | SOURCEIPHASH |
SRCIPDESTIPHASH | LEASTBANDWIDTH |
LEASTPACKETS | TOKEN | SRCIPSRCPORTHASH |
LRTM | CALLIDHASH | CUSTOMLOAD )

… (ellipsis)

You can repeat the previous item or items in command
statements. For example, /route:DeviceName[,…] means
you can type additional DeviceNames separated by
commas.

Preface

xiii

Related Documentation
A complete set of documentation is available on the Documentation tab of your
NetScaler and from http://support.citrix.com/. (Most of the documents require
Adobe Reader, available at http://adobe.com/.)
To view the documentation

1.

From a Web browser, log on to the NetScaler.

2.

Click the Documentation tab.

3.

To view a short description of each document, hover your cursor over the
title. To open a document, click the title.

Getting Service and Support
Citrix offers a variety of resources for support with your Citrix environment,
including the following:
•

The Knowledge Center is a self-service, Web-based technical support
database that contains thousands of technical solutions, including access to
the latest hotfixes, service packs, and security bulletins.

•

Technical Support Programs for both software support and appliance
maintenance are available at a variety of support levels.

•

The Subscription Advantage program is a one-year membership that gives
you an easy way to stay current with the latest product version upgrades
and enhancements.

•

Citrix Education provides official training and certification programs on
virtually all Citrix products and technologies.

For detailed information about Citrix services and support, see the Citrix Systems
Support Web site at
http://www.citrix.com/lang/English/support.asp.
You can also participate in and follow technical discussions offered by the experts
on various Citrix products at the following sites:
•

http://community.citrix.com

•

http://twitter.com/citrixsupport

xiv

Citrix NetScaler Policy Configuration and Reference Guide

Documentation Feedback
You are encouraged to provide feedback and suggestions so that we can enhance
the documentation. You can send email to the following alias or aliases, as
appropriate. In the subject line, specify “Documentation Feedback.” Be sure to
include the document name, page number, and product release version.
•

For NetScaler documentation, send email to nsdocs_feedback@citrix.com.

•

For Command Center documentation, send email to
ccdocs_feedback@citrix.com.

•

For Access Gateway documentation, send email to
agdocs_feedback@citrix.com.

You can also provide feedback from the Knowledge Center at http://
support.citrix.com/.
To provide feedback from the Knowledge Center home page

1.

Go to the Knowledge Center home page at http://support.citrix.com.

2.

On the Knowledge Center home page, under Products, expand NetScaler,
and then click the release for which you want to provide feedback.

3.

On the Documentation tab, click the guide name, and then click Article
Feedback.

4.

On the Documentation Feedback page, complete the form, and then click
Submit.

C HAPTER 1

Introduction to Policies and
Expressions

For many NetScaler features, policies control how the feature evaluates data,
which ultimately determines what the feature does with the data. A policy uses a
logical expression, also called a rule, to evaluate requests, responses, or other
data, and applies one or more actions determined by the outcome of the
evaluation. Or a policy can apply a profile, which defines a complex action.
Some NetScaler features use advanced policies, which provide greater
capabilities than do the older, classic, policies. If you migrated to a newer release
of the NetScaler software and have configured classic policies for features that
now use advanced policies, you might have to manually migrate policies to the
advanced-policy format.
In This Chapter
Advanced and Classic Policies
Advanced and Classic Expressions
About Migration from Classic to Advanced Policies and Expressions
Before You Proceed

Advanced and Classic Policies
Classic policies evaluate basic characteristics of traffic and other data. For
example, classic policies can identify whether an HTTP request or response
contains a particular type of header or URL.
Advanced policies can perform the same type of evaluations as classic policies. In
addition, advanced policies enable you to analyze more data (for example, the
body of an HTTP request) and to configure more operations in the policy rule (for
example, transforming data in the body of a request into an HTTP header).
In addition to assigning a policy an action or profile, you bind the policy to a
particular point in the processing associated with the NetScaler features. The bind
point is one factor that determines when the policy will be evaluated.

2

Citrix NetScaler Policy Configuration and Reference Guide

Benefits of Using Advanced Policies
Advanced policies use a powerful expression language that is built on a classobject model, and they offer several options that enhance your ability to configure
the behavior of various NetScaler features. With advanced policies, you can do
the following:
•

Perform fine-grained analyses of network traffic from layers 2 through 7.

•

Evaluate any part of the header or body of an HTTP or HTTPS request or
response.

•

Bind policies to the multiple bind points that the advanced policy
infrastructure supports at the default, override, and virtual server levels.

•

Use goto expressions to transfer control to other policies and bind points, as
determined by the result of expression evaluation.

•

Use special tools such as pattern sets, policy labels, rate limit identifiers,
and HTTP callouts, which enable you to configure policies effectively for
complex use cases.

Additionally, the configuration utility extends robust graphical user interface
support for advanced policies and expressions and enables users who have
limited knowledge of networking protocols to configure policies quickly and
easily. The configuration utility also includes a policy evaluation feature for
advanced policies. You can use this feature to evaluate an advanced policy and
test its behavior before you commit it, thus reducing the risk of configuration
errors.

Basic Components of an Advanced or a Classic
Policy
Following are a few characteristics of both classic and advanced policies:
•

Name. Each policy has a unique name.

•

Rule. The rule is a logical expression that enables the NetScaler feature to
evaluate a piece of traffic or another object.
For example, a rule can enable the NetScaler to determine whether an
HTTP request originated from a particular IP address, or whether a CacheControl header in an HTTP request has the value “No-Cache”.
Advanced policies can use all of the expressions that are available in a
classic policy, with the exception of classic expressions for the SSL VPN
client. In addition, advanced policies enable you to configure more
complex expressions.

Chapter 1

•

Introduction to Policies and Expressions

3

Bindings. To ensure that the NetScaler can invoke a policy when it is
needed, you associate the policy, or bind it, to one or more bind points.
You can bind a policy globally or to a virtual server. For more information,
see “About Policy Bindings,” on page 7.

•

An associated action. An action is a separate entity from a policy. Policy
evaluation ultimately results in the NetScaler performing an action.
For example, a policy in the Integrated Cache can identify HTTP requests
for .gif or .jpeg files. An action that you associate with this policy
determines that the responses to these types of requests are served from the
cache.
For some features, you configure actions as part of a more complex set of
instructions known as a profile. For more information, see “Order of
Evaluation Based on Traffic Flow,” on page 9.

How Different NetScaler Features Use Policies
The NetScaler supports a variety of features that rely on policies for operation.
The following table summarizes how the NetScaler features use policies:
NetScaler Feature, Policy Type, and Policy Usage
Feature Name Policy Type

How You Use Policies in the Feature

System

For the Authentication function, policies contain
authentication schemes for different
authentication methods.

Classic

For example, you can configure LDAP and
certificate-based authentication schemes.
You also configure policies in the Auditing
function.
DNS

Advanced

To determine how to perform DNS resolution for
requests.

SSL

Classic

To determine when to apply an encryption
function and add certificate information to clear
text.
To provide end-to-end security, after a message is
decrypted, the SSL feature re-encrypts clear text
and uses SSL to communicate with Web servers.

Compression

Classic and
Advanced

To determine what type of traffic is compressed.

Integrated
Caching

Advanced

To determine whether HTTP responses are
cacheable.

Responder

Advanced

To configure the behavior of the Responder
function.

4

Citrix NetScaler Policy Configuration and Reference Guide

NetScaler Feature, Policy Type, and Policy Usage
Feature Name Policy Type

How You Use Policies in the Feature

Protection
Features

Classic

To configure the behavior of the Filter,
SureConnect, and Priority Queueing functions.

Content
Switching

Classic and
Advanced

To determine what server or group of servers is
responsible for serving responses, based on
characteristics of an incoming request.
Request characteristics include device type,
language, cookies, HTTP method, content type,
and associated cache server.

AAA - Traffic
Management

Classic
Exceptions:
• Traffic policies
support only
advanced
policies
• Authorization
policies support
both classic and
advanced
policies.

To check for client-side security before users log
in and establish a session.
Traffic policies, which determine whether single
sign-on (SSO) is required, use only the advanced
policy format.
Authorization policies authorize users and
groups that access intranet resources through the
appliance.

Cache
Redirection

Classic

To determine whether responses are served from
a cache or from an origin server.

Rewrite

Advanced

To identify HTTP data that you want to modify
before serving. The policies provide rules for
modifying the data.
For example, you can modify HTTP data to
redirect a request to a new home page, or a new
server, or a selected server based on the address
of the incoming request, or you can modify the
data to mask server information in a response for
security purposes.
The URL Transformer function identifies URLs
in HTTP transactions and text files for the
purpose of evaluating whether a URL should be
transformed.

Application
Firewall

Classic and
Advanced

To identify characteristics of traffic and data that
should or should not be admitted through the
firewall.

Access
Gateway,
Clientless
Access
function

Advanced

To define rewrite rules for general Web access
using the Access Gateway.

Chapter 1

Introduction to Policies and Expressions

5

NetScaler Feature, Policy Type, and Policy Usage
Feature Name Policy Type

How You Use Policies in the Feature

Access
Gateway

To determine how the Access Gateway performs
authentication, authorization, auditing, and other
functions.

Classic

Authorization policies, however, can be
configured with both classic and advanced policy
formats.

About Actions and Profiles
Policies do not themselves take action on data. Policies provide read-only logic
for evaluating traffic. To enable a feature to perform an operation based on a
policy evaluation, you configure actions or profiles and associate them with
policies.
Note: Actions and profiles are specific to particular features. For information
about assigning actions and profiles to features, see the documentation for the
individual features.

About Actions
Actions are steps that the NetScaler takes, depending on the evaluation of the
expression in the policy. For example, if an expression in a policy matches a
particular source IP address in a request, the action that is associated with this
policy determines whether the connection is permitted.
The types of actions that the NetScaler can take are feature specific. For example,
in Rewrite, actions can replace text in a request, change the destination URL for a
request, and so on. In Integrated Caching, actions determine whether HTTP
responses are served from the cache or an origin server.
In some NetScaler features actions are predefined, and in others they are
configurable. In some cases, (for example, Rewrite), you configure the actions
using the same types of expressions that you use to configure the associated
policy rule.

About Profiles
Some NetScaler features enable you to associate profiles, or both actions and
profiles, with a policy. A profile is a collection of settings that enable the feature
to perform a complex function. For example, in the Application Firewall, a
profile for XML data can perform multiple screening operations, such as
examining the data for illegal XML syntax or evidence of SQL injection.

6

Citrix NetScaler Policy Configuration and Reference Guide

Use of Actions and Profiles in Particular Features
The following table summarizes the use of actions and profiles in different
NetScaler features. The table is not exhaustive. For more information on specific
uses of actions and profiles for a feature, see the documentation for the feature.
Use of Actions and Profiles in Different NetScaler Features
Feature

Use of an Action

Use of a Profile

Application Firewall

Synonymous with a profile

All Application Firewall
features use profiles to define
complex behaviors, including
pattern-based learning.
You add these profiles to
policies.

Access Gateway

The following features of the
Access Gateway use actions:

The following features use a
profile:

• Pre-Authentication. Uses
Allow and Deny actions.
You add these actions to a
profile.
• Authorization. Uses Allow
and Deny actions. You add
these actions to a policy.
• TCP Compression. Uses
various actions. You add
these actions to a policy.

• Pre-Authentication
• Session
• Traffic
• Clientless Access
After configuring the profiles,
you add them to policies.

Rewrite

You configure URL rewrite
actions and add them to a
policy.

Not used.

Integrated Caching

You configure caching and
invalidation actions within a
policy

Not used.

AAA - Traffic
Management

You select an authentication
type, set an authorization action
of ALLOW or DENY, or set
auditing to SYSLOG or
NSLOG.

You can configure session
profiles with a default timeout
and authorization action.

Protection Features

You configure actions within
policies for the following
functions:

Not used.

•
•
•
•
SSL

Filter
Compression
Responder
SureConnect

You configure actions within
SSL policies

Not used.

Chapter 1

Introduction to Policies and Expressions

7

Use of Actions and Profiles in Different NetScaler Features
Feature

Use of an Action

Use of a Profile

System

The action is implied. For the
Authentication function, it is
either Allow or Deny. For
Auditing, it is Auditing On or
Auditing Off.

Not used.

DNS

The action is implied. It is
either Drop Packets or the
location of a DNS server.

Not used.

SSL Offload

The action is implied. It is
based on a policy that you
associate with an SSL virtual
server or a service.

Not used.

Compression

Determine the type of
compression to apply to the
data.

Not used.

Content Switching

The action is implied. If a
request matches the policy, the
request is directed to the virtual
server associated with the
policy.

Not used.

Cache Redirection

The action is implied. If a
request matches the policy, the
request is directed to the origin
server.

Not used.

About Policy Bindings
A policy is associated with, or bound to, an entity that enables the policy to be
invoked. For example, you can bind a policy to request-time evaluation that
applies to all virtual servers. A collection of policies that are bound to a particular
bind point constitutes a policy bank.

Following is an overview of different types of bind points for a policy:
Request time global. A policy can be available to all components in a feature at
request time.
Response time global. A policy can be available to all components in a feature at
response time.
Request time, virtual server-specific. A policy can be bound to request-time processing
for a particular virtual server. For example, you can bind a request-time policy
to a cache redirection virtual server to ensure that particular requests are
forwarded to a load balancing virtual server for the cache, and other requests
are sent to a load balancing virtual server for the origin.
Response time, virtual server-specific. A policy can also be bound to response-time
processing for a particular virtual server.

8

Citrix NetScaler Policy Configuration and Reference Guide

User-defined policy label. For advanced policies, you can configure custom groupings
of policies (policy banks) by defining a policy label and collecting a set of
related policies under the policy label.
Other bind points. The availability of additional bind points depends on type of policy
(classic or advanced), and specifics of the relevant NetScaler feature. For
example, classic policies that you configure for the Access Gateway have user
and group bind points.

For additional information about advanced policy bindings, see “Binding
Advanced Policies,” on page 16, “Configuring a Policy Bank for a Virtual
Server,” on page 32. For additional information on classic policy bindings, see
“Configuring a Classic Policy,” on page 201.

About Evaluation Order of Policies
For classic policies, policy groups and policies within a group are evaluated in a
particular order, depending on the following:
•

The bind point for the policy, for example, whether the policy is bound to
request-time processing for a virtual server or global response-time
processing. For example, at request time, the NetScaler evaluates all
request-time classic policies before evaluating any virtual server-specific
policies.

•

The priority level for the policy. For each point in the evaluation process, a
priority level that is assigned to a policy determines the order of evaluation
relative to other policies that share the same bind point. For example, when
the NetScaler evaluates a bank of request-time, virtual server-specific
policies, it starts with the policy that is assigned to the lowest priority value.
In classic policies, priority levels must be unique across all bind points.

For advanced policies, as with classic policies, the NetScaler selects a grouping,
or bank, of policies at a particular point in overall processing. Following is the
order of evaluation of the basic groupings, or banks, of advanced policies:
1.

Request-time global override

2.

Request-time, virtual server-specific (one bind point per virtual server)

3.

Request-time global default

4.

Response-time global override

5.

Response-time virtual server-specific

6.

Response-time global default

However, within any of the preceding banks of policies, the order of evaluation is
more flexible than in classic policies. Within a policy bank, you can point to the
next policy to be evaluated regardless of the priority level, and you can invoke
policy banks that belong to other bind points and user-defined policy banks.

Chapter 1

Introduction to Policies and Expressions

9

Order of Evaluation Based on Traffic Flow
As traffic flows through the NetScaler and is processed by various features, each
feature performs policy evaluation. Whenever a policy matches the traffic, the
NetScaler stores the action and continues processing until the data is about to
leave the NetScaler. At that point, the NetScaler typically applies all matching
actions. Integrated Caching, which only applies a final Cache or NoCache action,
is an exception.
Some policies affect the outcome of other policies. Following are examples:
•

If a response is served from the Integrated Cache, some other NetScaler
features do not process the response or the request that initiated it.

•

If the Content Filtering feature prevents a response from being served, no
subsequent features evaluate the response.

If the Application Firewall rejects an incoming request, no other features can
process it.

Advanced and Classic Expressions
One of the most fundamental components of a policy is its rule. A policy rule is a
logical expression that enables the policy to analyze traffic. Most of the policy's
functionality is derived from its expression.
An expression matches characteristics of traffic or other data with one or more
parameters and values. For example, an expression can enable the NetScaler to
accomplish the following:
•

Determine whether a request contains a certificate.

•

Determine the IP address of a client that sent a TCP request.

•

Identify the data that an HTTP request contains (for example, a popular
spreadsheet or word processing application).

•

Calculate the length of an HTTP request.

About Advanced Expressions
Any feature that uses advanced policies also uses advanced expressions. For
information on which features use advanced policies, see the table, “NetScaler
Feature, Policy Type, and Policy Usage,” on page 3.
Advanced expressions have a few other uses. In addition to configuring advanced
expressions in policy rules, you configure advanced expressions in the following
situations:

10

Citrix NetScaler Policy Configuration and Reference Guide

•

Integrated Caching: You use advanced expressions to configure a selector
for a content group in the Integrated Cache.

•

Load Balancing: You use advanced expressions to configure token
extraction for a load balancing virtual server that uses the TOKEN method
for load balancing.

•

Rewrite: You use advanced expressions to configure Rewrite actions.

•

Rate-based policies: You use advanced expressions to configure Limit
Selectors when configuring a policy to control the rate of traffic to various
servers.

Following are a few simple examples of advanced expressions:
•

An HTTP request URL contains no more than 500 characters.
http.req.url.length <= 500

•

An HTTP request contains a cookie that has fewer than 500 characters.
http.req.cookie.length < 500

•

An HTTP request URL contains a particular text string.
http.req.url.contains(".html")

About Classic Expressions
Classic expressions enable you to evaluate basic characteristics of data. They
have a structured syntax that performs string matching and other operations.
Following are a few simple examples of classic expressions:
•

An HTTP response contains a particular type of Cache Control header.
res.http.header Cache-Control contains public

•

An HTTP response contains image data.
res.http.header Content-Type contains image/

•

An SSL request contains a certificate.
req.ssl.client.cert exists

Chapter 1

Introduction to Policies and Expressions

11

About Migration from Classic to Advanced Policies and
Expressions
The NetScaler supports either classic or advanced policies within a feature. You
cannot have both types in the same feature. Over the past few releases, some
NetScaler features have migrated from using classic policies and expressions to
advanced policies and expressions. If a feature of interest to you have changed to
the advanced format, you may have to manually migrate the older information.
Following are guidelines for deciding if you need to migrate your policies:
•

If you configured classic policies in a version of the Integrated Caching
feature prior to release 9.0 and then upgrade to version 9.0 or later, there is
no impact. All legacy policies are migrated to the advanced policy format.

•

For other features, you need to manually migrate classic policies and
expressions to the advanced format if the feature has migrated its format.

Before You Proceed
Before configuring expressions and policies, be sure you understand the relevant
NetScaler feature and the structure of your data, as follows:
•

Read the documentation on the relevant feature.

•

Look at the data stream for the type of data that you want to configure.
You may want to run a trace on the type of traffic or content that you want
to configure. This will give you an idea of the parameters and values, and
operations on these parameters and values, that you need to specify in an
expression.

12

Citrix NetScaler Policy Configuration and Reference Guide

C HAPTER 2

Configuring Advanced Policies

You can create advanced policies for various NetScaler features, including DNS,
Rewrite, Responder, and Integrated Caching, and the clientless access function in
the Access Gateway. Policies control the behavior of these features.
When you create an advanced policy, you assign it a name, a rule (an expression),
feature-specific attributes, and an action that is taken when data matches the
policy. After creating the policy, you determine when it is invoked by binding it
globally or to either request-time or response-time processing for a virtual server.
Policies that share the same bind point are known as a policy bank. For example,
all policies that are bound to a virtual server constitute the policy bank for the
virtual server. When binding the policy, you assign it a priority level to specify
when it is invoked relative to other policies in the bank. In addition to assigning a
priority level, you can configure an arbitrary evaluation order for policies in a
bank by specifying Goto expressions.
In addition to policy banks that are associated with a built-in bind point or a
virtual server, you can configure policy labels. A policy label is a policy bank that
is identified by an arbitrary name. You invoke a policy label, and the policies in it,
from a global or virtual-server-specific policy bank. A policy label or a
virtual-server policy bank can be invoked from multiple policy banks.
For some features, you can use the policy manager to configure and bind policies.
In This Chapter
Creating or Modifying an Advanced Policy
Binding Advanced Policies
Unbinding an Advanced Policy
Creating Policy Labels
Configuring a Policy Label or Virtual Server Policy Bank
Invoking or Removing a Policy Label or Virtual Server Policy Bank
Configuring and Binding Policies with the Policy Manager

14

Citrix NetScaler Policy Configuration and Reference Guide

Creating or Modifying an Advanced Policy
All advanced policies have some common elements. Creating an advanced policy
consists, at minimum, of naming the policy and configuring a rule. The policy
configuration tools for the various features have areas of overlap, but also
differences. For the details of configuring a policy for a particular feature,
including associating an action with the policy, see the documentation for the
feature.
To create a policy, begin by determining the purpose of the policy. For example,
you may want to define a policy that identifies HTTP requests for image files, or
client requests that contain an SSL certificate. In addition to knowing the type of
information that you want the policy to work with, you need to know the format
of the data that the policy is analyzing.
Next, determine whether the policy is globally applicable, or if it pertains to a
particular virtual server. Also consider the effect that the order in which your
policies are evaluated (which will be determined by how you bind the policies)
will have on the policy that you are about to configure.
To create an advanced policy by using the NetScaler command line

At the NetScaler command prompt, type:
add responder|dns|cs|rewrite|cache policy  -rule
 []

To modify an existing advanced policy by using the NetScaler command line

At the NetScaler command prompt, type:
set responder|dns|cs|rewrite|cache policy  -rule
 []

Advanced-Policy Parameters
Argument

Specifies

policyName

A unique name for the policy. (Cannot be changed for an
existing policy.)
Note that in the Content Switching feature, the name cannot
start with app_ because this is a reserved name. Policies
with this name are not displayed in the configuration utility.

expression

A logical expression. See “Configuring Advanced
Expressions: Getting Started,” on page 39.

feature-specific
information

Varies by feature. Includes a built-in or user-defined action
that you associate with the policy. See the documentation for
the feature to which the policy applies.

Chapter 2

Configuring Advanced Policies

15

To create or modify an advanced policy by using the configuration utility

1.

In the navigation pane, expand the name of the feature for which you want
to configure a policy, and then click Policies. For example, you can select
Content Switching, Integrated Caching, DNS, Rewrite, or Responder.

2.

In the details pane, click Add, or select an existing policy and click Open.
A policy configuration dialog box appears.

3.

Specify values for the following parameters. (An asterisk indicates a
required parameter. For a term in parentheses, see the corresponding
parameter in the table above.)
•

Name* (policyName)

•

Expression* (expression)

•

Other parameters, as required (feature-specific information)

4.

Click Create, and then click Close.

5.

Click Save.

Note: After you create a policy, you can view the policy’s details by clicking
the policy entry in the configuration pane. Details that are highlighted and
underlined are links to the corresponding entity (for example, a named
expression).

Policy Configuration Examples
These examples show how policies and their associated actions are entered at the
NetScaler command line. In the configuration utility, the expressions would
appear in the Expression window of the feature-configuration dialog box for the
integrated caching or rewrite feature.
Following is an example of creating a caching policy. Note that actions for
caching policies are built in, so you do not need to configure them separately
from the policy.
add cache policy BranchReportsCachePolicy -rule
q{http.req.url.query.value("actionoverride").contains("branchReport
s")} -action cache

Following is an example of a Rewrite policy and action:
add rewrite action myAction1 INSERT_HTTP_HEADER "myHeader"
"valueForMyHeader"
add rewrite policy myPolicy1
"http.req.url.contains(\"myURLstring\")" myAction1

16

Citrix NetScaler Policy Configuration and Reference Guide

Note: At the command line, quote marks within a policy rule (the expression)
must be escaped or delimited with the q delimiter. For more information, see
“Configuring Advanced Expressions in a Policy,” on page 57.

Binding Advanced Policies
After defining a policy, you indicate when the policy is to be invoked by binding
the policy to a bind point and specifying a priority level. You can bind a policy to
only one bind point. A bind point can be global, that is, it can apply to all virtual
servers that you have configured. Or, a bind point can be specific to a particular
virtual server, which can be either a load balancing or a content switching virtual
server. Not all bind points are available for all features.
The order in which policies are evaluated determines the order in which they are
applied, and features typically evaluate the various policy banks in a particular
order. Sometimes, however, other features can affect the order of evaluation.
Within a policy bank, the order of evaluation depends on the values of parameters
configured in the policies. Most features apply all of the actions associated with
policies whose evaluation results in a match with the data that is being processed.
The integrated caching feature is an exception.

Feature-Specific Differences in Policy Bindings
You can bind policies to built-in, global bind points (or banks), to virtual servers,
or to policy labels.
However, the NetScaler features differ in terms of the types of bindings that are
available. The following table summarizes how you use policy bindings in
various NetScaler features that use advanced policies.
Feature-Specific Bindings for Advanced Policies
Feature Name

Virtual Servers
Policies
Bind Points
Use of Advanced Policies in
Configured in the Configured in the Configured for the the Feature
Feature
Feature
Policies

DNS

none

DNS policies

Global

To determine how to
perform DNS resolution for
requests.

Chapter 2

Configuring Advanced Policies

17

Feature-Specific Bindings for Advanced Policies
Feature Name

Virtual Servers
Policies
Bind Points
Use of Advanced Policies in
Configured in the Configured in the Configured for the the Feature
Feature
Feature
Policies

Content Switching

Content Switching
(CS)

Note: This feature
can support either
advanced or
classic policies,
but not both.

Content Switching
policies

• Content
switching or
cache
redirection
virtual server
• Policy label

To determine what server or
group of servers is
responsible for serving
responses, based on
characteristics of an
incoming request.
Request characteristics
include device type,
language, cookies, HTTP
method, content type, and
associated cache server.

Integrated
Caching

none

Caching policies

•
•
•
•

Global override
Global default
Policy label
Load balancing,
content
switching, or
SSL offload
virtual server

Responder

none

Responder
policies

•
•
•
•

Global override To configure the behavior of
Global default the Responder function.
Policy label
Load balancing,
content
switching, or
SSL offload
virtual server

Rewrite

none

Rewrite policies

•
•
•
•

Global override
Global default
Policy label
Load balancing,
content
switching, or
SSL offload
virtual server

URL Transform
function in the
Rewrite feature

none

Transformation
policies

To determine whether HTTP
responses can be stored in,
and served from, the
NetScaler's integrated
cache.

To identify HTTP data that
you want to modify before
serving. The policies
provide rules for modifying
the data.
For example, you can
modify HTTP data to
redirect a request to a
selected server based on the
address of the incoming
request, or to mask server
information in a response
for security purposes.

• Global override To identify URLs in HTTP
• Global default transactions and text files
for the purpose of evaluating
• Policy label
whether a URL should be
altered.

18

Citrix NetScaler Policy Configuration and Reference Guide

Feature-Specific Bindings for Advanced Policies
Feature Name

Virtual Servers
Policies
Bind Points
Use of Advanced Policies in
Configured in the Configured in the Configured for the the Feature
Feature
Feature
Policies

Access Gateway

VPN server

(clientless VPN
functions only)

Clientless Access
policies

• VPN Global
• VPN server

To determine how the
Access Gateway performs
authentication,
authorization, auditing, and
other functions, and to
define rewrite rules for
general Web access using
the Access Gateway.

Bind Points and Order of Evaluation
For an advanced policy to take effect, you must ensure that the policy is invoked
at some point during processing. To do so, you associate the policy with a bind
point. The collection of policies that is bound to a bind point is known as a policy
bank.
Following are the bind points that the NetScaler evaluates, listed in the typical
order of evaluation:
1.

Request-time override. When a request flows through a feature, the
NetScaler first evaluates request-time override policies for the feature.

2.

Request-time Load Balancing virtual server. If policy evaluation cannot
be completed after all the request-time override policies have been
evaluated, the NetScaler processes request-time policies for load balancing
virtual servers.

3.

Request-time Content Switching virtual server. If policy evaluation
cannot be completed after all the request-time policies for load balancing
virtual servers have been evaluated, the NetScaler processes request-time
policies for content switching virtual servers.

4.

Request-time default. If policy evaluation cannot be completed after all
request-time, virtual server-specific policies have been evaluated, the
NetScaler processes request-time default policies.

5.

Response-time override. At response time, the NetScaler starts with
policies that are bound to the response-time override bind point.

6.

Response-time Load Balancing virtual server. If policy evaluation
cannot be completed after all response-time override policies have been
evaluated, the NetScaler process the response-time policies for load
balancing virtual servers.

7.

Response-time Content Switching virtual server. If policy evaluation
cannot be completed after all policies have been evaluated for load

Chapter 2

Configuring Advanced Policies

19

balancing virtual servers, the NetScaler process the response-time policies
for content switching virtual servers.
8.

Response-time default. If policy evaluation cannot be completed after all
response-time, virtual-server-specific policies have been evaluated, the
NetScaler processes response-time default policies.

Advanced Policy Evaluation Across Features
In addition to attending to evaluation of policies within a feature, if you have
bound policies to a content switching virtual server, note that these policies are
evaluated before other policies. Binding a policy to a content switching vserver
produces a different result in NetScaler versions 9.0.x and later than in 8.x
versions. In NetScaler 9.0 and later versions, evaluation occurs as follows:
•

Content switching policies are evaluated before other policies. If a content
switching policy evaluates to TRUE, the target load balancing vserver is
selected.

•

If all content switching policies evaluate to FALSE, the default load
balancing vserver under the content switching VIP is selected.

After a target load balancing vserver is selected by the content switching process,
policies are evaluated in the following order:
1.

Policies that are bound to the global override bind point.

2.

Policies that are bound to the default load balancing vserver.

3.

Policies that are bound to the target content switching vserver.

4.

Policies that are bound to the global default bind point.

To be sure that the policies are evaluated in the intended order, follow these
guidelines:
•

Make sure that the default load balancing vserver is not directly reachable
from the outside; for example, the vserver IP address can be 0.0.0.0.

•

To prevent exposing internal data on the load balancing default vserver,
configure a policy to respond with a “503 Service Unavailable” status and
bind it to the default load balancing vserver.

Entries in a Policy Bank
Each entry in a policy bank has, at minimum, a policy and a priority level. You
can also configure entries that change the priority-based evaluation order, and you
can configure entries that invoke external policy banks.

20

Citrix NetScaler Policy Configuration and Reference Guide

The following table summarizes each entry in a policy bank.
Format of Each Entry in a Policy Bank
Policy Name

Priority

Goto
Expression

Invocation
Type

Policy Bank to
be Invoked

The policy name, or a
“dummy” policy
named NOPOLICY.
The NOPOLICY
entry controls
evaluation flow
without processing a
rule. For more
information, see
“Evaluation Order
Within a Policy
Bank,” on page 20.

An integer.

Optional.

Optional.

Optional.

Identifies the
next policy in
the bank to
evaluate, or
ends any
further
evaluation.

Indicates that
an external
policy bank
will be
invoked.

Used with
Invocation
Type. This is
the label for a
policy bank or
a virtual server
name.

This field
restricts the
choices to a
global policy
label or a
virtual server.

The NetScaler
returns to the
current bank
after
processing the
external bank.

If the policy evaluates to TRUE, the NetScaler stores the action that is associated
with the policy. If the policy evaluates to FALSE, the NetScaler evaluates the next
policy. If the policy is neither TRUE nor FALSE, the NetScaler uses the
associated Undef (undefined) action.

Evaluation Order Within a Policy Bank
Within a policy bank, the evaluation order depends on the following items:
•

A priority. The most minimal amount of information about evaluation
order is a numeric priority level. The lower the number, the higher the
priority.

•

A Goto expression. If supplied, the Goto expression indicates the next
policy to be evaluated, typically within the same policy bank.. Goto
expressions can only proceed forward in a bank. To prevent looping, a
policy bank configuration is not valid if a Goto statement points backwards
in the bank.

•

Invocation of other policy banks. Any entry can invoke an external policy
bank. The NetScaler provides a built-in entity named NOPOLICY that does
not have a rule. You can add a NOPOLICY entry in a policy bank when you
want to invoke another policy bank, but do not want to process any other
rules prior to the invocation. You can have multiple NOPOLICY entries in
multiple policy banks.

Values for a Goto expression are as follows:

Chapter 2

Configuring Advanced Policies

21

•

NEXT. This keyword selects the policy with the next higher priority level
in the current policy bank.

•

An integer. If you supply an integer, it must match the priority level of
another policy in the current policy bank.

•

END. This keyword stops evaluation after processing the current policy,
and no additional policies in this bank are processed.

•

Blank. If the Goto expression is empty, it is the same as specifying END.

•

A numeric expression. This is an advanced expression that resolves to a
priority number for another policy in the current bank.

•

USE_INVOCATION_RESULT. This phrase can be used only if you are
invoking an external policy bank. Entering this phrase causes the NetScaler
to perform one of the following actions:
•

If the final Goto in the invoked policy bank has a value of END or is
empty, the invocation result is END, and evaluation stops.

•

If the final Goto expression in the invoked policy bank is anything
other than END, the NetScaler performs a NEXT.

The following table illustrates a policy bank that uses Goto statements and policy
bank invocations.
Example of a Policy Bank That Uses Gotos and External Bank Invocations
Policy Name

Priority Goto

Invocation

Policy Bank
to be Invoked

ClientCertificatePolicy
(rule: does the request
contain a client certificate?)

100

300

None

None

SubnetPolicy (rule: is the
client from a private
subnet?)

200

NEXT

None

None

NOPOLICY

300

USE
INVOCATION
RESULT

Request
vserver

My_Request
_VServer

NOPOLICY

350

USE
INVOCATION
RESULT

Policy Label

My_Policy_
Label

WorkingHoursPolicy (rule:
is it working hours?)

400

END

None

None

How Policy Evaluation Ends
Evaluation of a policy bank ends when the following takes place:

22

Citrix NetScaler Policy Configuration and Reference Guide

•

A policy evaluates to TRUE and its Goto statement value is END.
No further policies or policy banks in this feature are evaluated.

•

An external policy bank is invoked, its evaluation returns an END, and the
Goto statement uses a value of USE_INVOCATION_RESULT or END.
Evaluation continues with the next policy bank for this feature. For
example, if the current bank is the request-time override bank, the
NetScaler next evaluates request-time policy banks for the virtual servers.

•

The NetScaler has walked through all the policy banks in this feature, but
has not encountered an END.
If this is the last entry to be evaluated in this policy bank, the NetScaler
proceeds to the next feature.

How Features Use Actions After Policy Evaluation
After evaluating all relevant policies for a particular data point (for example, an
HTTP request), the NetScaler stores all the actions that are associated with any
policy that matched the data.
For most features, all the actions from matching policies are applied to a traffic
packet as it leaves the NetScaler. The Integrated Caching feature only applies one
action: CACHE or NOCACHE. This action is associated with the policy with the
lowest priority value in the “highest priority” policy bank (for example,
request-time override policies are applied before virtual server-specific policies).

Binding a Policy Globally
The following binding procedures are typical. However, refer to the
documentation for the feature of interest to you for complete instructions.
To bind an Integrated Caching advanced policy globally by using the
NetScaler command line

At the NetScaler command prompt, type:
bind cache global  -priority  [-type
REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT]

Example
bind cache global myCachePolicy -priority 100 -type req_default

The type argument is optional to maintain backward compatibility. If you omit
the type, the policy is bound to REQ_DEFAULT or RES_DEFAULT, depending
on whether the policy rule is a response-time or a request-time expression.

Chapter 2

Configuring Advanced Policies

23

To bind a Rewrite advanced policy globally by using the NetScaler
command line

At the NetScaler command prompt, type:
bind rewrite global   [-type
REQ_OVERRIDE | REQ_DEFAULT | RES_OVERRIDE | RES_DEFAULT]

The type argument is optional for globally bound policies, to maintain
backward compatibility. If you omit the type, the policy is bound to
REQ_DEFAULT or RES_DEFAULT, depending on whether the policy rule is a
response-time or a request-time expression.
Example
bind rewrite global myPolicy1 200

To bind a Responder advanced policy globally by using the NetScaler
command line

At the NetScaler command prompt, type:
bind responder global  
[-type OVERRIDE | DEFAULT ]

To bind a DNS advanced policy globally by using the NetScaler command
line

At the NetScaler command prompt, type:
bind dns global  

To bind an Integrated Caching, Responder, or Rewrite advanced policy
globally by using the configuration utility

1.

In the navigation pane, click the name of the feature for which you want to
bind the policy.

2.

In the details pane, click  policy manager.

3.

In the Policy Manager dialog box, select the bind point to which you want
to bind the policy (for example, for Integrated Caching or Rewrite, you
could select Request and Default Global). The Responder does not
differentiate between request-time and response-time policies.

4.

Click Insert Policy and, from the Policy Name pop-up menu, select the
policy name. A priority is assigned automatically to the policy, but you can
click the cell in the Priority column and drag it anywhere within the dialog
box if you want the policy to be evaluated after other policies in this bank.
The priority is automatically reset. Note that priority values within a policy
bank must be unique.

5.

Click Apply Changes.

24

Citrix NetScaler Policy Configuration and Reference Guide

6.

Click Close.

To bind a DNS advanced policy globally by using the configuration utility

1.

In the navigation pane, expand DNS, and then click Policies.

2.

In the details pane, click Global Bindings.

3.

In the global bindings dialog box, click Insert Policy, and select the policy
that you want to bind globally.

4.

Click in the Priority field and enter the priority level.

5.

Click OK.

Binding a Policy to a Virtual Server
A globally bound policy applies to all load balancing and content switching
virtual servers.
Note that when binding a policy to a virtual server, you must identify it as a
request-time or a response-time policy.
To bind an advanced policy to a load balancing or content switching virtual
server by using the NetScaler command line

At the NetScaler command prompt, type:
bind lb|cs vserver  -policyName 
-priority  -type REQUEST|RESPONSE

To bind an advanced policy to an SSL offload virtual server by using the
NetScaler command line

At the NetScaler command prompt, type:
bind ssl vserver  -policyName 
-priority 

To bind an advanced policy to a virtual server by using the configuration
utility

1.

In the navigation pane, expand Load Balancing, Content Switching, SSL
Offload, AAA- Application Traffic, or Access Gateway, and then click
Virtual Servers.

2.

In the details pane, double-click the virtual server to which you want to
bind the policy, and then click Open.

3.

On the Policies tab, click the icon for the type of advanced policy that you
want to bind (the choices are feature-specific), and then click the name of
the policy. Note that for some features, you can bind both classic and
advanced policies to the virtual server.

Chapter 2

Configuring Advanced Policies

4.

If you are binding a policy to a Content Switching virtual server, in the
Target field select a load balancing virtual server to which traffic that
matches the policy is sent.

5.

Click OK.

25

Displaying Policy Bindings
You can display policy bindings to verify that they are correct.
To display advanced policy bindings by using the NetScaler command line

At the NetScaler command prompt, type:
show  policy 

To display global policy bindings for Integrated Caching, Rewrite, or
Responder by using the configuration utility

1.

In the navigation pane, expand the feature that contains the advanced policy
that you want to view, and then click Policy Manager.

2.

In the details pane, click the policy. Bound policies have a check mark next
to them.

3.

At the bottom of the page, under Details, next to Bound to, view the entity
to which the policy is bound.

To display global policy bindings for DNS or Clientless Access in the
Access Gateway by using the configuration utility

1.

In the navigation pane, expand DNS, and then click Policies.

2.

In the details pane, click Global Bindings.

To display global policy bindings for Content Switching by using the
configuration utility

1.

In the navigation pane, expand Content Switching, and then click Policies.

2.

In the details pane, click Show Bindings.

Unbinding an Advanced Policy
If you want to re-assign a policy or delete it, you must first remove its binding.
To unbind an advanced policy globally by using the NetScaler command
line

At the NetScaler command prompt, to unbind an Integrated Caching or Rewrite
policy, type:

26

Citrix NetScaler Policy Configuration and Reference Guide

unbind cache|rewrite global  [-type
req_override|req_default|res_override|res_default]
[-priority ]

The priority is required only for the “dummy” policy named NOPOLICY.
At the NetScaler command prompt, to unbind a Responder policy, type:
unbind responder global  [-type override|default]
[-priority ]

The priority is required only for the “dummy” policy named NOPOLICY.
At the NetScaler command prompt, to unbind a DNS policy, type:
unbind responder global 

To unbind an advanced policy from a virtual server by using the NetScaler
command line

At the NetScaler command prompt, type:
unbind  vserver  -policyName
 [-priority ] [-type REQUEST|RESPONSE]

The priority is required only for the “dummy” policy named NOPOLICY.
To unbind an Integrated Caching, Responder, or Rewrite advanced policy
globally by using the configuration utility

1.

In the navigation pane, click the feature with the policy that you want to
unbind (for example, Integrated Caching).

2.

In the details pane, click  policy manager.

3.

In the Policy Manager dialog box, select the bind point with the policy that
you want to unbind, for example, Default Global.

4.

Click the policy name that you want to unbind, and then click Unbind
Policy.

5.

Click Apply Changes.

6.

Click Close.

To unbind a DNS advanced policy globally by using the configuration utility

1.

In the navigation pane, expand DNS, and then click Policies.

2.

In the details pane, click Global Bindings.

3.

In the global bindings dialog box, in the Active column, clear the check box
next to the policy that you want to unbind.

4.

Click OK.

Chapter 2

Configuring Advanced Policies

27

To unbind an advanced policy from a Load Balancing or Content Switching
virtual server by using the configuration utility

1.

In the navigation pane, expand Load Balancing or Content Switching,
and then click Virtual Servers.

2.

In the details pane, double-click the virtual server from which you want to
unbind the policy.

3.

On the Policies tab, in the Active column, clear the check box next to the
policy that you want to unbind.

4.

Click OK.

Creating Policy Labels
In addition to the built-in bind points where you set up policy banks, you can also
configure user-defined policy labels and associate policies with them.
Within a policy label, you bind policies and specify the order of evaluation of
each policy relative to others in the bank of policies for the policy label. The
NetScaler also permits you to define an arbitrary evaluation order as follows:
•

You can use “goto” expressions to point to the next entry in the bank to be
evaluated after the current one.

•

You can use an entry in a policy bank to invoke another bank.

Creating a Policy Label
Each feature determines the type of policy that you can bind to a policy label, the
type of load balancing virtual server that you can bind the label to, and the type of
content switching virtual server from which the label can be invoked. For
example, a TCP policy label can only be bound to a TCP load balancing virtual
server. You cannot bind HTTP policies to a policy label of this type. And you can
invoke a TCP policy label only from a TCP content switching virtual server.
After configuring a new policy label, you can invoke it from one or more banks
for the built-in bind points.
To create a policy label by using the NetScaler command line

At the NetScaler command prompt, to create a caching policy label, type:
add cache policylabel  -evaluates req|res

At the NetScaler command prompt, to create a Content Switching policy label,
type:
add cs policylabel  http|tcp|rtsp|ssl

At the NetScaler command prompt, to create a Rewrite policy label, type:

28

Citrix NetScaler Policy Configuration and Reference Guide

add rewrite policylabel 
http_req|http_res|url|text|clientless_vpn_req|clientless_vpn_res

At the NetScaler command prompt, to create a Responder policy label, type:
add rewrite policylabel 

Note: Invoke this policy label from a policy bank. For more information, see
“Binding a Policy to a Policy Label,” on page 29.

To create a policy label by using the configuration utility

1.

In the navigation pane, expand the feature for which you want to create a
policy label, and then click Policy Labels.
The choices are Integrated Caching, Rewrite, Content Switching,
Rewrite, or Responder.

2.

In the details pane, click Add.

3.

In the Name box, enter a unique name for this policy label.

4.

Enter feature-specific information for the policy label. For example, for
Integrated Caching, in the Evaluates drop-down menu, you would select
REQ if you want this policy label to contain request-time policies, or select
RES if you want this policy label to contain response-time policies. For
Rewrite, you would select a Transform type. For information on integrated
caching, see the Citrix NetScaler Application Optimization Guide. For
information on rewrite, see the Citrix NetScaler Application Security
Guide.

5.

Click Create.

6.

Configure one of the built-in policy banks to invoke this policy label. For
more information, see “Binding a Policy to a Policy Label,” on page 29.

Chapter 2

Configuring Advanced Policies

29

Binding a Policy to a Policy Label
As with policy banks that are bound to the built-in bind points, each entry in a
policy label is a policy that is bound to the policy label. As with policies that are
bound globally or to a vserver, each policy that is bound to the policy label can
also invoke a policy bank or a policy label that is evaluated after the current entry
has been processed. The following table summarizes the entries in a policy label.
Entries in a Policy Bank
Attribute

Description

Name

The name of a policy, or, to invoke another policy bank without
evaluating a policy, the “dummy” policy name NOPOLICY.
You can specify NOPOLICY more than once in a policy bank, but you
can specify a named policy only once.

Priority

An integer. This setting can work with the Goto expression.

Goto Expression

Determines the next policy to evaluate in this bank. You can provide
one of the following values:
• NEXT: Go to the policy with the next higher priority.
• END: Stop evaluation.
• USE_INVOCATION_RESULT: Applicable if this entry invokes
another policy bank. If the final Goto in the invoked bank has a
value of END, evaluation stops. If the final Goto is anything other
than END, the current policy bank performs a NEXT.
• Positive number: The priority number of the next policy to be
evaluated.
• Numeric expression: An expression that produces the priority
number of the next policy to be evaluated.
The Goto can only proceed forward in a policy bank.
If you omit the Goto expression, it is the same as specifying END.

Invocation Type

Designates a policy bank type. The value can be one of the following:
• Request Vserver: Invokes request-time policies that are associated
with a virtual server.
• Response Vserver: Invokes response-time policies that are
associated with a virtual server.
• Policy label: Invokes another policy bank, as identified by the
policy label for the bank.

Invocation
Name

The name of a virtual server or a policy label, depending on the value
that you specified for the Invocation Type.

Configuring a Policy Label or Virtual Server Policy Bank
After you have created policies, and created policy banks by binding the policies,
you can perform additional configuration of polices within a label or policy bank.
For example, before you configure invocation of an external policy bank, you
might want to wait until you have configured that policy bank.

30

Citrix NetScaler Policy Configuration and Reference Guide

Configuring a Policy Label
A policy label consists of a set of policies and invocations of other policy labels
and virtual server-specific policy banks. An Invoke parameter enables you to
invoke a policy label or a virtual server-specific policy bank from any other
policy bank. A special-purpose NoPolicy entry enables you to invoke an external
bank without processing an expression (a rule). The NoPolicy entry is a
“dummy” policy that does not contain a rule.
For configuring policy labels from the NetScaler command line, note the
following elaborations of the command syntax:
•

gotoPriorityExpression is configured as described in “Entries in a Policy
Bank,” on page 29.

•

The type argument is required. This is unlike binding a conventional
policy, where this argument is optional.

•

You can invoke the bank of policies that are bound to a virtual server by
using the same method as you use for invoking a policy label.

To configure a policy label by using the NetScaler command line

At the NetScaler command prompt, type:
bind cache|rewrite|responder policylabel 
-policyName  -priority 
-gotoPriorityExpression  -invoke
reqvserver|resvserver|policylabel |

To invoke a policy label from a Rewrite policy bank with a NOPOLICY entry
by using the NetScaler command line

At the NetScaler command prompt, type:
bind rewrite global NOPOLICY 
-gotoPriorityExpression 
-type REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT
-invoke reqvserver|resvserver|policylabel
|

To invoke a policy label from an Integrated Caching policy bank by using the
NetScaler command line

At the NetScaler command prompt, type:
bind cache global NOPOLICY -priority 
-gotoPriorityExpression 
-type REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT
-invoke reqvserver|resvserver|policylabel
|

Example

Chapter 2

Configuring Advanced Policies

31

bind cache global NOPOLICY -priority 104 -gotoPriorityExpression
next -type RES_OVERRIDE -invoke resvserver lab2

To invoke a policy label from a Responder policy bank by using the
NetScaler command line

At the NetScaler command prompt, type:
bind responder global NOPOLICY 

-type OVERRIDE|DEFAULT -invoke vserver|policylabel
|

Example
bind responder global NOPOLICY 100 NEXT -type OVERRIDE -invoke
policylabel responderlabel2

To configure a policy label by using the configuration utility

1.

In the navigation pane, expand the feature for which you want to configure
a policy label, and then click Policy Labels.
The choices are Integrated Caching, Rewrite, or Responder.

2.

In the details pane, double-click the label that you want to configure.

3.

If you are adding a new policy to this policy label, click Insert Policy, and
in the Policy Name field, select New Policy. For more information about
adding a policy, see “Creating or Modifying an Advanced Policy,” on page
14.
Note that if you are invoking a policy bank, and do not want a rule to be
evaluated prior to the invocation, click Insert Policy, and in the Policy
Name field select NOPOLICY.

4.

For each entry in this policy label, configure the following:
•

Policy Name: This is already determined by the Policy Name, new
policy, or NOPOLICY entry that you inserted in this bank.

•

Priority: A numeric value that determines either an absolute order of
evaluation within the bank, or is used in conjunction with a Goto
expression.

•

Expression: The policy rule. Advanced policy expressions are
described in detail in the following chapters. For an introduction, see
“Configuring Advanced Expressions: Getting Started,” on page 39.

•

Action: The action to be taken if this policy evaluates to TRUE.

•

Goto Expression: Optional. Used to augment the Priority level to
determine the next policy or policy bank to evaluate. For more

32

Citrix NetScaler Policy Configuration and Reference Guide

information on possible values for a Goto expression, see the table,
“Entries in a Policy Bank,” on page 29.
•

Invoke: Optional. Invokes another policy bank.

Configuring a Policy Bank for a Virtual Server
You can configure a bank of policies for a virtual server. The policy bank can
contain individual policies, and each entry in the policy bank can optionally
invoke a policy label or a bank of policies that you configured for another virtual
server. If you invoke a policy label or policy bank, you can do so without
triggering an expression (a rule) by selecting a NOPOLICY “dummy” entry
instead of a policy name.
To add policies to a virtual server policy bank by using the NetScaler
command line

At the NetScaler command prompt, type:
bind lb|cs vserver  -policyName 
-priority  -gotoPriorityExpression 
-type REQUEST|RESPONSE

To invoke a policy label from a virtual server policy bank with a NOPOLICY
entry by using the NetScaler command line

At the NetScaler command prompt, type:
bind lb|cs vserver  -policyName
NOPOLICY_REWRITE|NOPOLICY_CACHE|NOPOLICY_RESPONDER -priority
 -type REQUEST|RESPONSE -gotoPriorityExpression
 -invoke reqVserver|resVserver|policyLabel
|

Example
bind lb vserver myLoadBalancingVserver1 -policyname
NOPOLICY-REWRITE -priority 200 -type REQUEST
-gotoPriorityExpression NEXT -invoke policyLabel myPolicyLabel

To configure a virtual server policy bank by using the configuration utility

1.

In the left navigation pane, expand Load Balancing, Content Switching,
SSL Offload, AAA - Application Traffic, or Access Gateway, as
appropriate, and then click Virtual Servers.

2.

In the details pane, select the virtual server that you want to configure, and
then click Open.

3.

In the Configure Virtual Server dialog box click the Policies tab.

Chapter 2

4.

Configuring Advanced Policies

33

To create a new policy in this bank, click the icon for the type of policy or
policy label that you want to add to the virtual server’s bank of policies,
click Insert Policy.
Note that if you want to invoke a policy label without evaluating a policy
rule, select the NOPOLICY “dummy” policy.

5.

6.

To configure an existing entry in this policy bank, enter the following:
•

Priority: A numeric value that determines either an absolute order of
evaluation within the bank or is used in conjunction with a Goto
expression.

•

Expression: The policy rule. Advanced policy expressions are
described in detail in the following chapters. For an introduction, see
“Configuring Advanced Expressions: Getting Started,” on page 39.

•

Action: The action to be taken if this policy evaluates to TRUE.

•

Goto Expression: Optional. Determines the next policy or policy
bank to evaluate. For more information on possible values for a Goto
expression, see the table, “Entries in a Policy Bank,” on page 29.

•

Invoke: Optional. To invoke another policy bank, select the name of
the policy label or virtual server policy bank that you want to invoke.

When you are done, click OK.

Invoking or Removing a Policy Label or Virtual Server
Policy Bank
Unlike a policy, which can only be bound once, you can use a policy label or a
virtual server’s policy bank any number of times by invoking it. Invocation can
be performed from two places:
•

From the binding for a named policy in a policy bank.

•

From the binding for a NOPOLICY “dummy” entry in a policy bank.

Typically, the policy label must be of the same type as the policy from which it is
invoked. For example, you would invoke a Responder policy label from a
Responder policy.
Note: When binding or unbinding a global NOPOLICY entry in a policy bank
at the command line, you specify a priority to distinguish one NOPOLICY entry
from another.

34

Citrix NetScaler Policy Configuration and Reference Guide
To invoke a policy label or virtual server policy bank by using the NetScaler
command line

At the NetScaler command prompt, for Rewrite or Integrated Caching, type:
bind cache|rewrite global  -priority
 [-gotoPriorityExpression ] -type
REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT] -invoke
reqvserver|resvserver|policylabel 

Example
bind cache global myCachePolicy -priority 100 -type req_override
-invoke policylabel myCachePolicyLabel

At the NetScaler command prompt, for the Responder, type:
bind responder global  
[] -type
REQ_OVERRIDE|REQ_DEFAULT|OVERRIDE|DEFAULT -invoke
vserver|policylabel 

Example
bind responder global testpolicy3 300 -invoke policylabel
myResponderLabel

At the NetScaler command prompt, for a virtual server, type:
bind lb vserver  -policyName  -priority
 [-gotoPriorityExpression ] -type
REQUEST|RESPONSE -invoke reqvserver|resvserver|policylabel


Example
bind lb vserver myLBVserver -policyname testCachePolicy -priority
5555 -type request -invoke policylabel cachePolicyLabel

To remove a policy label invocation from a NOPOLICY entry by using the
NetScaler command line

At the NetScaler command prompt, for Rewrite or Integrated Caching, type:
unbind rewrite|cache global NOPOLICY -priority 
-type REQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT

Example
unbind rewrite global NOPOLICY -priority 100 -type REQ_OVERRIDE 200

At the NetScaler command prompt, for the Responder, type:
unbind responder global NOPOLICY -priority  -type
OVERRIDE|DEFAULT

Example
unbind responder global NOPOLICY -priority 200 -type OVERRIDE

At the NetScaler command prompt, for a virtual server, type:

Chapter 2

Configuring Advanced Policies

35

unbind lb|cs vserver  -policyName
NOPOLICY-REWRITE|NOPOLICY-RESPONDER|NOPOLICY-CACHE -type
REQUEST|RESPONSE -priority 

Example
unbind lb vserver myLBVserver -policyName NOPOLICY-REWRITE
-priority 200 -type REQUEST

To invoke a policy label or virtual server policy bank by using the
configuration utility

1.

Bind a policy, as described in “Binding a Policy Globally,” on page 22,
“Binding a Policy to a Virtual Server,” on page 24, or “Binding a Policy to
a Policy Label,” on page 29.
Alternatively, you can enter a NOPOLICY “dummy” entry instead of a
policy name. You do this if you do not want to evaluate a policy before
evaluating the policy bank.

2.

In the Invoke field, select the name of the policy label or virtual server
policy bank that you want to evaluate if traffic matches the bound policy.

To remove a policy label invocation by using the configuration utility

Open the policy and clear the Invoke field. Unbinding the policy also removes
the invocation of the label.

Configuring and Binding Policies with the Policy
Manager
Some applications provide a specialized Policy Manager in the NetScaler
configuration utility to simplify configuring policy banks. It also lets you find and
delete policies and actions that are not being used.
The Policy Manager is currently available for the Rewrite, Integrated Caching,
and Responder features.
The following are keyboard equivalents for the procedures in this section:
•

For editing a cell in the Policy Manager, you can tab to the cell and click F2
or press the space bar on the keyboard.

•

To select an entry in a drop-down menu, you can tab to the entry, press the
space bar to view the drop-down menu, use the up- and down-arrow keys to
navigate to the entry that you want, and press the space bar again to select
the entry.

•

To cancel a selection in a drop-down menu, press the Escape key.

36

Citrix NetScaler Policy Configuration and Reference Guide

•

To insert a policy, tab to the row above the insertion point and click
Control + Insert, or click Insert Policy.

•

To remove a policy, tab to the row that contains the policy and press Delete.
Note that when you delete the policy, the NetScaler searches the Goto
Expression values of other policies in the bank. If any of these Goto
Expression values match the priority level of the deleted policy, they are
removed.

To configure policy bindings and banks by using the Policy Manager

1.

In the navigation pane, click the feature to which you want to configure the
policy bank.
The choices are Responder, Integrated Caching, or Rewrite.

2.

In the details pane, click  policy manager.

3.

For features other than Responder, determine the bind point, click Request
or Response, and then click one of the request-time or response-time bind
points. The options are Override Global, LB Virtual Server, CS Virtual
Server, Default Global, or Policy Label.
If you are configuring the Responder, the Request and Response flow
types are not available.

4.

To bind a policy to this bind point, click Insert Policy, and select a
previously configured policy, a NOPOLICY label, or the New policy
option. Depending on the option that you select, you have the following
choices:
•

New policy: Create the policy as described in “Creating or Modifying
an Advanced Policy,” on page 14, and then configure the priority
level, GoTo expression, and policy invocation as described in the
table, "Format of Each Entry in a Policy Bank" on page 20.

•

Existing policy, NOPOLICY, or NOPOLICY:
Configure the priority level, GoTo expression, and policy invocation
as described in the table, "Format of Each Entry in a Policy Bank" on
page 20.

5.

Repeat the preceding steps to add entries to this policy bank.

6.

To modify the priority level for an entry, you can do any of the following:
•

Double-click the Priority field for an entry and edit the value.

•

Click and drag a policy to another row in the table.

•

Click Regenerate Priorities.

Chapter 2

Configuring Advanced Policies

37

In all three cases, priority levels of all other policies are modified as needed
to accommodate the new value. Goto Expressions with integer values are
also updated automatically. For example, if you change a priority value of
10 to 100, all policies with a Goto Expression value of 10 are updated to
the value 100.
7.

To change the policy, action, or policy bank invocation for an row in the
table, click the down arrow to the right of the entry and do one of the
following:
•

To change the policy, select another policy name or select New
Policy and follow the steps in “Creating or Modifying an Advanced
Policy,” on page 14.

•

To change the Goto Expression, select Next, End,
USE_INVOCATION_RESULT, or select more and enter a
advanced expression whose result returns the priority level of another
entry in this policy bank.

•

To modify an invocation, select an existing policy bank, or click New
Policy Label and follow the steps in “Binding a Policy to a Policy
Label,” on page 29.

8.

To unbind a policy or a policy label invocation from this bank, click any
field in the row that contains the policy or policy label, and then click
Unbind Policy.

9.

When you are done, click Apply Changes.

To remove unused policies by using the Policy Manager

1.

In the navigation pane, click the feature for which you want to configure the
policy bank.
The choices are Responder, Integrated Caching, or Rewrite.

2.

In the details pane, click  policy manager.

3.

In the  Policy Manager dialog box, click Cleanup
Configuration.

4.

In the Cleanup Configuration dialog box, select the items that you want to
delete, and then click Remove.

5.

Click Close.

38

Citrix NetScaler Policy Configuration and Reference Guide

C HAPTER 3

Configuring Advanced Expressions:
Getting Started

Advanced policies evaluate data on the basis of information that you supply in
advanced expressions. An advanced expression analyzes data elements (for
example, HTTP headers, source IP addresses, the NetScaler system time, and
POST body data).
To create an advanced expression, you select a prefix that identifies a piece of
data that you want to analyze, and then you specify an operation to perform on the
data. For example, an operation can match a piece of data with a text string that
you specify, or it can transform a text string into an HTTP header. Other
operations match a returned string with a set of strings or a string pattern. You
configure compound expressions by specifying Boolean and arithmetic operators,
and by using parentheses to control the order of evaluation. You can also include
classic expressions in an advanced expression.
Advanced expressions are typically part of a policy, and you can assign names to
frequently used expressions so that you do not have to enter the full expression
repeatedly in multiple policies. But for some features, you configure advanced
expressions outside the context of a policy.
In This Chapter
Expression Characteristics
Basic Elements of an Advanced Expression
Compound Advanced Expressions
Classic Expressions in Advanced Expressions
Configuring Advanced Expressions in a Policy
Configuring Named Advanced Expressions
Configuring Advanced Expressions Outside the Context of a Policy

40

Citrix NetScaler Policy Configuration and Reference Guide

Expression Characteristics
Policies and a few other entities include rules that the NetScaler uses to evaluate a
packet in the traffic flowing through it, to extract data from the NetScaler system
itself, to send a request (a callout) to an external application, or to analyze another
piece of data. A rule takes the form of a logical expression that is compared
against traffic and ultimately returns values of TRUE or FALSE.
The elements of the rule can themselves return TRUE or FALSE, string, or
numeric values.
Before configuring an advanced expression, you need to understand the
characteristics of the data that the policy or other entity is to evaluate. For
example, when working with the Integrated Caching feature, a policy determines
what data can be stored in the cache. With Integrated Caching, you need to know
the URLs, headers, and other data in the HTTP requests and responses that the
NetScaler receives. With this knowledge, you can configure policies that match
the actual data and enable the NetScaler to manage caching for HTTP traffic. This
information helps you determine the type of expression that you need to
configure in the policy.

Basic Elements of an Advanced Expression
An advanced expression consists of, at a minimum, a prefix (or a single element
used in place of a prefix). Most expressions also specify an operation to be
performed on the data that the prefix identifies. You format an expression, of up
to 1,499 characters, as follows:
. [
.. . .]

Where:
•

 is an anchor point for starting an expression.
The prefix is a period-delimited key that identifies a unit of data. For
example, the following prefix examines HTTP requests for the presence of
a header named Content-Type:
http.req.header("Content-Type")

Prefixes can also be used on their own to return the value of the object that
the prefix identifies.
•

 identifies an evaluation that is to be performed on the data
identified by the prefix.
For example, consider the following expression:
http.req.header("Content-Type").eq("text/html")

Chapter 3

Configuring Advanced Expressions: Getting Started

41

In this expression, the following is the operator component:
eq("text/html")

This operator causes the NetScaler to evaluate any HTTP requests that
contain a Content-Type header, and in particular, to determine if the value
of this header is equal to the string text/html.
•

 is a Boolean or arithmetic operator that forms a
compound expression from multiple prefix or prefix.operation elements.
For example, consider the following expression:
http.req.header("Content-Type").eq("text/html") &&
http.req.url.contains(".html")

Prefixes
An expression prefix represents a discrete piece of data. For example, an
expression prefix can represent an HTTP URL, an HTTP Cookie header, or a
string in the body of an HTTP POST request. An expression prefix can identify
and return a wide variety of data types, including the following:
•

A client IP address in a TCP/IP packet

•

NetScaler system time

•

An external callout over HTTP

•

A TCP or UDP record type

In most cases, an expression prefix begins with one of the following keywords:
•

•

CLIENT: Identifies a characteristic of the client that is either sending a
request or receiving a response, as in the following examples:
•

The prefix client.ip.dst designates the destination IP address
in the request or response.

•

The prefix client.ip.src designates the source IP address.

HTTP: Identifies an element in an HTTP request or a response, as in the
following examples:
•

The prefix http.req.body(integer) designates the body of
the HTTP request as a multiline text object, up to the character
position designated in integer.

•

The prefix http.req.header("header_name") designates
an HTTP header, as specified in header_name.

42

Citrix NetScaler Policy Configuration and Reference Guide

•

The prefix http.req.url designates an HTTP URL in URLencoded format.

•

SERVER: Identifies an element in the server that is either processing a
request or sending a response.

•

SYS: Identifies a characteristic of the NetScaler that is processing the
traffic.

•

TARGET:Represents all the strings that result from a search in the target
text. This prefix can be used only in the string expression that specifies
replacement text in a rewrite action. The expression that is used to search
the target text must be a regular expression, and the type of action must be
REPLACE_ALL, INSERT_AFTER_ALL, or INSERT_BEFORE_ALL.
Any operator that is used with the TARGET prefix operates on all the
strings that are found in the target text.
For example, if a search that uses a regular expression finds n occurrences
of the specified string, and if the action type is REPLACE_ALL, the
expression TARGET.TO_UPPER changes the case of all n occurrences of
the string to upper case.

Note: DNS policies support only SYS, CLIENT, and SERVER objects.
In addition, in the Access Gateway, the Clientless VPN function can use the
following types of prefixes:
•

TEXT: Identifies any text element in a request or a response.

•

TARGET: Identifies the target of a connection.

•

URL: Identifies an element in the URL portion of an HTTP request or
response.

As a general rule of thumb, any expression prefix can be a self-contained
expression. For example, the following prefix is a complete expression that
returns the contents of the HTTP header specified in the string argument
(enclosed in quotation marks):
http.res.header.("myheader")

Or you can combine prefixes with simple operations to determine TRUE and
FALSE values. For example, the following returns a value of TRUE or FALSE:
http.res.header.("myheader").exists

You can also use complex operations on individual prefixes and multiple prefixes
within an expression, as in the following example:
http.req.url.length + http.req.cookie.length <= 500

Chapter 3

Configuring Advanced Expressions: Getting Started

43

Which expression prefixes you can specify depends on the NetScaler feature. The
following table describes the expression prefixes that are of interest on a perfeature basis.
Permitted Types of Expression Prefixes in Various NetScaler Feature
Feature

Types of Expression Prefix Used in the Feature

DNS

SYS, CLIENT, SERVER

Responder in Protection
Features

HTTP, SYS, CLIENT

Content Switching

HTTP, SYS, CLIENT

Rewrite

HTTP, SYS, CLIENT, SERVER, URL, TEXT,
TARGET, VPN

Integrated Caching

HTTP, SYS, CLIENT, SERVER

Access Gateway,
Clientless Access

HTTP, SYS, CLIENT, SERVER, URL, TEXT,
TARGET, VPN

Note: For details on the permitted expression prefixes in a feature, see the
documentation for that feature.

Single-Element Expressions
The simplest type of advanced expression contains a single element. This element
can be one of the following:
•

true. An advanced expression can consist simply of the value true. This
type of expression always returns a value of TRUE. It is useful for chaining
policy actions and triggering Goto expressions.

•

false. An advanced expression can consist simply of the value false.
This type of expression always returns a value of FALSE.

•

A prefix for a compound expression. For example, the prefix
HTTP.REQ.HOSTNAME is a complete expression that returns a host name, and
HTTP.REQ.URL is a complete expression that returns a URL. The prefix
could also be used in conjuction with operations and additional prefixes to
form a compound expression.

Operations
In most expressions, you specify an operation on the data that the prefix
identifies. For example, suppose that you specify the following prefix:
http.req.url

44

Citrix NetScaler Policy Configuration and Reference Guide

This prefix extracts URLs in HTTP requests. This expression prefix does not
require any operators to be used in an expression. However, when you configure
an expression that processes HTTP request URLs, you can specify operations that
analyze particular characteristics of the URL. Following are a few possibilities:
•

Search for a particular host name in the URL.

•

Search for a particular path in the URL.

•

Evaluate the length of the URL.

•

Search for a string in the URL that indicates a time stamp and convert it to
GMT.

The following is an example of a prefix that identifies an HTTP header named
Server and an operation that searches for the string IIS in the header value:
http.res.header("Server").contains("IIS")

Following is an example of a prefix that identifies host names and an operation
that searches for the string www.mycompany.com as the value of the name:
http.req.hostname.eq("www.mycompany.com")

Basic Operations on Expression Prefixes
The following table describes a few of the basic operations that can be performed
on expression prefixes:
Basic Operations for Expressions
Operation

Determines whether or not

CONTAINS(. Following is an example:
>)
http.req.header("Cache-Control").contains("nocache")
EXISTS

A particular item is present in an object. Following is an example:
http.res.header("MyHdr").exists

EQ()

A particular non-numeric value is present in an object. Following
is an example:
http.req.method.eq(post)

EQ()

A particular numeric value is present in an object. Following is an
example:
client.ip.dst.eq(10.100.10.100)

LT()

An object's value is less than a particular value. Following is an
example:
http.req.content_length.lt(5000)

Chapter 3

Configuring Advanced Expressions: Getting Started

45

Basic Operations for Expressions
Operation
GT()

Determines whether or not
An object's value is greater than a particular value. Following is
an example:
http.req.content_length.gt(5)

The following table summarizes a few of the available types of operations.
Basic Types of Operations
Operation Type

Description

Text operations

Match individual strings and sets of strings with any portion
of a target. The target can be an entire string, the start of a
string, or any portion of text in between the start and the end
of the string.
For example, you can extract the string "XYZ" from
"XYZSomeText". Or, you can compare an HTTP header
value with an array of different strings.
You can also transform text into another type of data.
Following are examples:
• Transform a string into an integer value
• Create a list from the query strings in a URL
• Transform a string into a time value

Numeric operations

Numeric operations include applying arithmetic operators,
evaluating content length, the number of items in a list,
dates, times, and IP addresses.

Compound Advanced Expressions
You can configure an advanced expression that contains Boolean or arithmetic
operators and multiple atomic operations. The following compound expression
contains a boolean AND:
http.req.hostname.eq("mycompany.com") && http.req.method.eq(post)

The following expression adds the value of two targets, and compares the result
to a third value:
http.req.url.length + http.req.cookie.length <= 500

A compound expression can contain any number of logical and arithmetic
operators. The following expression evaluates the length of an HTTP request on
the basis of its URL and cookie, evaluates text in the header, and performs a
Boolean AND on these two results:
http.req.url.length + http.req.cookie.length <= 500 &&
http.req.header.contains("some text")

46

Citrix NetScaler Policy Configuration and Reference Guide

You can use parentheses to control the order of evaluation in a compound
expression.

Booleans in Compound Expressions
You configure compound expressions with the following operators:
•

&&. This operator is a logical AND. For the expression to evaluate to
TRUE, all components that are joined by the And must evaluate to TRUE.
Following is an example:
http.req.url.hostname.eq("myHost") &&
http.req.header("myHeader").exists

•

||. This operator is a logical OR. If any component of the expression that is
joined by the OR evaluates to TRUE, the entire expression is TRUE.

•

!. Performs a logical NOT on the expression.

In some cases, the NetScaler configuration utility offers AND, NOT, and OR
operators in the Add Expression dialog box. However, these are of limited use.
Citrix recommends that you use the operators &&, ||, and ! to configure
compound expressions that use Boolean logic.

Parentheses in Compound Expressions
You can use parentheses to control the order of evaluation of an expression. The
following is an example:
http.req.url.contains("myCompany.com") ||
(http.req.url.hostname.eq("myHost") &&
http.req.header("myHeader").exists)

The following is another example:
(http.req.header("Content-Type").exists &&
http.req.header("Content-Type").eq("text/html")) ||
(http.req.header("Transfer-Encoding").exists ||
http.req.header("Content-Length").exists)

Compound Operations for Strings
The following table describes operators that you can use to configure compound
operations on string data.
String-Based Operations for Compound Advanced Expressions
All string operations
Operations that produce a string value

Chapter 3

Configuring Advanced Expressions: Getting Started

47

String-Based Operations for Compound Advanced Expressions
All string operations
str + str

Concatenates the value of the expression on the left of the operator with the
value on the right. Following is an example:
http.req.hostname + http.req.url.protocol

str + num

Concatenates the value of the expression on the left of the operator with a
numeric value on the right. Following is an example:
http.req.hostname + http.req.url.content_length

num + str

Concatenates the numeric value of the expression on the left side of the
operator with a string value on the right. Following is an example:
http.req.url.content_length + http.req.url.hostname

str + ip

Concatenates the string value of the expression on the left side of the
operator with an IP address value on the right. Following is an example:
http.req.hostname + 10.00.000.00

ip + str

Concatenates the IP address value of the expression on the left of the
operator with a string value on the right.Following is an example:
client.ip.dst + http.req.url.hostname

str1 ALT
str2

Uses the string1 or string2 value that is derived from the expression on
either side of the operator, as long as neither of these expressions is a
compound expressions.Following is an example:
http.req.hostname alt client.ip.src

Operations on strings that produce a result of TRUE or FALSE
str == str

Evaluates whether the strings on either side of the operator are the same.
Following is an example:
http.req.header("myheader") ==
http.res.header("myheader")

str <= str

Evaluates whether the string on the left side of the operator is the same as
the string on the right, or precedes it alphabetically.

str >= str

Evaluates whether the string on the left side of the operator is the same as
the string on the right, or follows it alphabetically.

str < str

Evaluates whether the string on the left side of the operator precedes the
string on the right alphabetically.

str > str

Evaluates whether the string on the left side of the operator follows the
string on the right alphabetically.

str !!= str

Evaluates whether the strings on either side of the operator are different.

Logical operations on strings

48

Citrix NetScaler Policy Configuration and Reference Guide

String-Based Operations for Compound Advanced Expressions
All string operations
bool &&
bool

This operator is a logical AND. When evaluating the components of the
compound expression, all components that are joined by the AND must
evaluate to TRUE. Following is an example:
http.req.method.eq(GET) &&
http.req.url.query.contains("viewReport &&
my_pagelabel")

bool || bool

This operator is a logical OR. When evaluating the components of the
compound expression, if any component of the expression that is joined by
the OR evaluates to TRUE, the entire expression is TRUE. Following is an
example:
http.req.url.contains(".js") ||
http.res.header.("ContentType").contains("javascript")

!bool

Performs a logical NOT on the expression.

Compound Operations for Numbers
You can configure compound numeric expressions. For example, the following
expression returns a numeric value that is the sum of an HTTP header length and
a URL length:
http.req.header.length + http.req.url.length

The following table describes operators that you can use to configure compound
expressions for numeric data.
Arithmetic Operations for Compound Advanced Expressions
Operator

Description

Arithmetic operations on number
num + num

Add the value of the expression on the left of the operator to the
value of the expression on the right. Following is an example:
http.req.content_length + http.req.url.length

num – num

Subtract the value of the expression on the right of the operator from
the value of the expression on the left.

num * num

Multiply the value of the expression on the left of the operator with
the value of the expression on the right. Following is an example:
client.interface.rxthroughput * 9

num / num

Divide the value of the expression on the left of the operator by the
value of the expression on the right.

Chapter 3

Configuring Advanced Expressions: Getting Started

49

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

num % num

Calculate the modulo, or the numeric remainder on a division of the
value of the expression on the left of the operator by the value of the
expression on the right.
For example, the values "15 mod 4" equals 3, and "12 mod 4" equals
0.

~number

Returns a number after applying a bitwise logical negation of the
number. The following example assumes that numeric.expression
returns 12 (binary 1100):
~numeric.expression.

The result of applying the ~ operator is -11 (a binary 1110011, 32
bits total with all ones to the left).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
number ^ number

Compares two bit patterns of equal length and performs an XOR
operation on each pair of corresponding bits in each number
argument, returning 1 if the bits are different, and 0 if they are the
same.
Returns a number after applying a bitwise XOR to the integer
argument and the current number value. If the values in the bitwise
comparison are the same, the returned value is a 0. The following
example assumes that numeric.expression1 returns 12 (binary 1100)
and numeric.expression2 returns 10 (binary 1010):
numeric.expression1 ^ numeric.expression2

The result of applying the ^ operator to the entire expression is 6
(binary 0110).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
number | number

Returns a number after applying a bitwise OR to the number values.
If either value in the bitwise comparison is a 1, the returned value is
a 1. The following example assumes that numeric.expression1
returns 12 (binary 1100) and numeric.expression2 returns 10 (binary
1010):
numeric.expression1 | numeric.expression2

The result of applying the | operator to the entire expression is 14
(binary 1110).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.

50

Citrix NetScaler Policy Configuration and Reference Guide

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

number & number

Compares two bit patterns of equal length and performs a bitwise
AND operation on each pair of corresponding bits, returning 1 if
both of the bits contains a value of 1, and 0 if either bits are 0.
The following example assumes that numeric.expression1 returns 12
(binary 1100) and numeric.expression2 returns 10 (binary 1010):
numeric.expression1 & numeric.expression2

The whole expression evaluates to 8 (binary 1000).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
num << num

Returns a number after a bitwise left shift of the number value by the
right-side number argument number of bits.
Note that the number of bits shifted is integer modulo 32. The
following example assumes that numeric.expression1 returns 12
(binary 1100) and numeric.expression2 returns 3:
numeric.expression1 << numeric.expression2

The result of applying the LSHIFT operator is 96 (a binary
1100000).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
num >> num

Returns a number after a bitwise right shift of the number value by
the integer argument number of bits.
Note that the number of bits shifted is integer modulo 32. The
following example assumes that numeric.expression1 returns 12
(binary 1100) and numeric.expression2 returns 3:
numeric.expression1 >> numeric.expression2

The result of applying the RSHIFT operator is 1 (a binary 0001).
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
Numeric operators that produce a result of TRUE or FALSE
num == num

Determine if the value of the expression on the left of the operator is
equal to the value of the expression on the right.

num != num

Determine if the value of the expression on the left of the operator is
not equal to the value of the expression on the right.

num > num

Determine if the value of the expression on the left of the operator is
greater than the value of the expression on the right.

num < num

Determine if the value of the expression on the left of the operator is
less than the value of the expression on the right.

num >= num

Determine if the value of the expression on the left of the operator is
greater than or equal to the value of the expression on the right.

Chapter 3

Configuring Advanced Expressions: Getting Started

51

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

num <= num

Determine if the value of the expression on the left of the operator is
less than or equal to the value of the expression on the right

Operations on numbers of data type “integer”
number.ADD
(integer)

Returns a number after adding the integer argument to the number
value.
Following is an example:
http.req.content_length.add(10)

number.SUB
(integer)

Returns a number after subtracting the integer argument from the
number value.
Following is an example:
http.req.header.length.sub(10)

number.DIV
(integer)

Returns a number after dividing the number value by the integer
argument.
Following is an example:
http.req.content_length.div(2)

number.MUL
(integer)

Returns a number after multiplying the number by the integer
argument value.
Following is an example:
http.req.content_length.mul(2)

number.
BETWEEN
(lower_integer,
higher_integer)

Returns a Boolean TRUE if the number value is greater than or
equal to the lower_integer argument and less than or equal to the
higher_integer argument.
Following is an example:
http.req.content_length.between(5, 500)

number.EQ
(integer)

Return a Boolean TRUE if the number value is equal to the integer
argument.
Following is an example:
http.req.content_length.eq(50)

number.NE
(integer)

Returns a Boolean TRUE if the value designated by number is not
equal to the argument.
Following is an example:
http.req.content_length.ne(50)

number.GE
(integer)

Return a Boolean TRUE if the number value is greater than or equal
to the integer argument.
Following is an example:
http.req.content_length.ge(500)

52

Citrix NetScaler Policy Configuration and Reference Guide

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

number.GT
(integer)

Return a Boolean TRUE if the number value is greater than the
integer argument.
Following is an example:
http.req.content_length.gt(500)

number.LE
(integer)

Return a Boolean TRUE if the number value is less than or equal to
the integer argument.
Following is an example:
http.req.content_length.le(5)

number.LT
(integer).

Return a Boolean TRUE if the number value is less than the integer
argument.
Following is an example:
http.req.content_length.lt(5)

number.NEG

Returns a number after negating the current number value.
Following is an example:
http.req.content_length.neg

number.BITAND
(integer)

Returns a number after applying a bitwise AND to the integer
argument and the current number value.
A bitwise AND operates on each pair of corresponding bits,
returning 1 if both of the bits contains a value of 1, and 0 if either bits
are 0. The following example assumes that numeric.expression
returns 12 (binary 1100):
numeric.expression.bitand(10)

The binary value of 10 is 1010, and the result of applying the
BITAND operator to the whole expression is 8 (binary 1000).
The following is another example of an expression that uses a
BITAND. Assume that the expression prior to the BITAND returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).bitand(4)

The result of this expression is 0.
An ampersand (&) performs a similar function to BITAND, but
takes another expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.

Chapter 3

Configuring Advanced Expressions: Getting Started

53

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

number.BITNEG

Returns a number after applying a bitwise logical negation of the
number. The following example assumes that numeric.expression
returns 12 (binary 1100):
numeric.expression.bitneg()

The result of applying the BITNEG operator is -11 (a binary
1110011, 32 bits total with all ones to the left).
The following is another example of an expression that uses a
BITNEG. Assume that the expression prior to the BITNEG returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).bitneg

The result of this expression is -9.
A tilde (~) performs a similar function to BITNEG, but takes another
expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
number.BITOR
(integer)

Returns a number after applying a bitwise OR to the integer
argument and the current number value. If either value in the bitwise
comparison is a 1, the returned value is a 1. The following example
assumes that numeric.expression returns 12 (binary 1100):
numeric.expression.bitor(10)

The binary value of 10 is 1010, and the result of applying the BITOR
operator to the entire expression is 14 (binary 1110).
The following is another example of an expression that uses a
BITOR. Assume that the expression prior to the BITOR returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).bitor(8)

The result of this expression is 8.
A bar (|) performs a similar function to BITOR, but takes another
expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.

54

Citrix NetScaler Policy Configuration and Reference Guide

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

number.BITXOR
(integer)

Returns a number after applying a bitwise XOR to the integer
argument and the current number value. If the values in the bitwise
comparison are the same, the returned value is a 0. The following
example assumes that numeric.expression returns 12 (binary 1100):
numeric.expression.bitxor(10)

The binary value of 10 is 1010, and the result of applying the
BITXOR operator to the entire expression is 6 (binary 0110).
The following is another example of an expression that uses a
BITXOR. Assume that the expression prior to the BITXOR returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).bitxor(8)

The result of this expression is 0.
A caret (^) performs a similar function to BITXOR, but takes
another expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
number.LSHIFT
(integer)

Returns a number after a bitwise left shift of the number value by the
integer argument number of bits.
Note that the number of bits shifted is integer modulo 32. The
following example assumes that numeric.expression returns 12
(binary 1100):
numeric.expression.lshift(3)

The result of applying the LSHIFT operator is 96 (a binary
1100000).
The following is another example of an expression that uses an
LSHIFT. Assume that the expression prior to the LSHIFT returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).lshift(2)

The result of this expression is 32.
A double less-than (<<) performs a similar function to LSHIFT, but
takes another expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.

Chapter 3

Configuring Advanced Expressions: Getting Started

55

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

number.RSHIFT
(integer)

Returns a number after a bitwise right shift of the number value by
the integer argument number of bits.
Note that the number of bits shifted is integer modulo 32. The
following example assumes that numeric.expression returns 12
(binary 1100):
numeric.expression.rshift(3)

The result of applying the RSHIFT operator is 1 (a binary 0001).
The following is another example of an expression that uses an
RSHIFT. Assume that the expression prior to the RSHIFT returns a
value of 8:
http.req.header(\"test\").contains_index(\"pat1\"
).rshift(2)

The result of this expression is 2.
A double greater-than (>>) performs the same function as RSHIFT,
but takes another expression as an argument rather than an integer.
Note that all returned values of less than 32 bits before applying the
operator implicitly have zeros to the left to make them 32 bits wide.
Operations on numbers of data type “double”
double.ADD(i)

Returns a value of data type double after adding the argument i to the
value represented by double.
Parameters:
i - Value of type double

double.BETWEE
N(i, j)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is greater than or equal to the lower
argument i and lesser than or equal to the upper argument j.
Parameters:
i - Lower value of type double
j - Upper value of type double

double.DIV(i)

Returns a value of data type double after dividing the value
(represented by double) by the argument i.
Parameters:
i - Value of type double

double.EQ(i)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is equal to the argument i.
Parameters:
i - Value of type double

56

Citrix NetScaler Policy Configuration and Reference Guide

Arithmetic Operations for Compound Advanced Expressions
Operator

Description

double.GE(i)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is greater than or equal to the
argument i.
Parameters:
i - Value of type double

double.GT(i)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is greater than the argument i.
Parameters:
i - Value of type double

double.LE(i)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is lesser than or equal to the
argument i.
Parameters:
i - Value of type double

double.LT(i)

Returns a Boolean value (TRUE or FALSE) that indicates whether
the value represented by double is lesser than the argument i.
Parameters:
i - Value of type double

double.MUL(i)

Returns a value of data type double after multiplying the argument i
with the value represented by double.
Parameters:
i - Value of type double

double.NE(i)

Returns Boolean value TRUE if the value represented by double is
not equal to the argument i, and FALSE otherwise.
Parameters:
i - Value of type double

double.NEG

Negates the value represented by double.

double.SUB(i)

Returns a value of data type double after subtracting the argument i
from the value represented by double.
Parameters:
i - Value of type double

Chapter 3

Configuring Advanced Expressions: Getting Started

57

Classic Expressions in Advanced Expressions
Classic expressions describe basic characteristics of traffic. In some cases, you
may want to use the classic expression syntax in an advanced policy. You can do
so with the advanced expression configuration tool. This can be helpful when
manually migrating older, classic expressions to the advanced expression format.
Note that when you upgrade the NetScaler to version 9.0 or higher, Integrated
Caching policies are automatically upgraded to advanced policy format, and the
expressions in these policies are upgraded to the advanced expression method of
describing a classic expression.
The following is the syntax for all advanced expressions that use the classic
expression syntax:
sys.eval_classic_expr("expression")

The following are examples of classic expressions that you can embed in an
advanced expression using this syntax:
sys.eval_classic_expr("req.ssl.client.cipher.bits > 1000")
sys.eval_classic_expr("url contains abc")
sys.eval_classic_expr("req.ip.sourceip == 10.102.1.61 -netmask
255.255.255.255")
sys.eval_classic_expr("time >= *:30:00GMT")
sys.eval_classic_expr("e1 || e2")
sys.eval_classic_expr("req.http.urllen > 50")
sys.eval_classic_expr("dayofweek == wedGMT")

Configuring Advanced Expressions in a Policy
You can configure an advanced expression of up to 1,499 characters in a policy.
The user interface for advanced expressions depends to some extent on the
feature for which you are configuring the expression, and on whether you are
configuring an expression for a policy or for another use.
When configuring expressions on the command line, you delimit the expression
by using quotation marks (“. . .”or '. . .'). Within an expression, you escape
additional quotation marks by using a back-slash (\). For example, the following
are standard methods for escaping quotation marks in an expression:
"\"abc\""
‘\"abc\"’

58

Citrix NetScaler Policy Configuration and Reference Guide

You must also use a backslash to escape question marks and other backslashes on
the command line. For example, the expression
http.req.url.contains(“\?”) requires a backslash so that the question
mark is parsed. Note that the backslash character will not appear on the command
line after you type the question mark. On the other hand, if you escape a
backslash (for example, in the expression
'http.req.url.contains("\\\\http")'), the escape characters are
echoed on the command line.
To make an entry more readable, you can escape the quotation marks for an entire
expression. At the start of the expression you enter the escape sequence “q” plus
one of the following special characters: /{<|~$^+=&%@`?.
You enter only the special character at the end of the expression, as follows:
q@http.req.url.contains("sometext") && http.req.cookie.exists@
q~http.req.url.contains("sometext") && http.req.cookie.exists~

Note that an expression that uses the { delimiter is closed with }.
For some features (for example, Integrated Caching and Responder), the
configuration utility’s policy configuration dialog box provides a secondary
dialog box for configuring expressions. This dialog box enables you to choose
from drop-down lists that show the available choices at each point during
expression configuration. You cannot use arithmetic operators in these
configuration dialogs, but most other advanced expression features are available.
To use arithmetic operators , write your expressions in free-form format.
To configure an advanced policy rule by using the NetScaler command line

At the NetScaler command prompt, type:
add cache|dns|rewrite|cs policy policyName -rule expression
featureSpecificParameters

Following is an example of configuring a caching policy:
add cache policy cacheReports -rule
q~http.req.url.query.value("actionoverride").contains("branchReport
s")~ -action cache

To configure an advanced policy expression by using the configuration
utility

1.

In the navigation pane, click the name of the feature where you want to
configure a policy, for example, you can select Integrated Caching,
Responder, DNS, Rewrite, or Content Switching, and then click Policies.

2.

Click Add.

3.

For most features, click in the Expression field. For Content Switching,
click Configure and then click Advanced Syntax.

Chapter 3

Configuring Advanced Expressions: Getting Started

59

4.

Click the Prefix icon (the house) and select the first expression prefix from
the drop-down list. For example, in Responder, the options are HTTP,
SYS, and CLIENT. The next set of applicable options appear in a dropdown list.

5.

Double-click the next option to select it, and then type a period (.). Again, a
set of applicable options appears in another drop-down list.

6.

Continue selecting options until an entry field (signalled by parentheses)
appears. When you see an entry field, enter an appropriate value in the
parentheses. For example, if you select GT(int) (greater-than, integer
format), you specify an integer in the parentheses. Text strings are delimited
by quotation marks. Following is an example:
HTTP.REQ.BODY(1000).BETWEEN("this","that")

7.

To insert an operator between two parts of a compound expression, click
the Operators icon (the sigma), and select the operator type. Following is
an example of a configured expression with a Boolean OR (signalled by
double vertical bars, ||):
HTTP.REQ.URL.EQ("www.mycompany.com")||HTTP.REQ.BODY(1
000).BETWEEN("this","that")

8.

To insert a named expression, click the down arrow next to the Add icon
(the plus sign) and select a named expression.

9.

To configure an expression by using drop-down menus, and to insert builtin expressions, click the Add icon (the plus sign). The Add Expression
dialog box works in a similar way to the main dialog box, but it provides
drop-down lists for selecting options, and it provides text fields for data
entry instead of parentheses. This dialog box also provides a Frequently
Used Expressions drop-down list that inserts commonly used expressions.
When you are done adding the expression, click OK.

10.

When finished, click Create.

To test an advanced policy expression by using the configuration utility

1.

In the navigation pane, click the name of the feature for which you want to
configure a policy (for example, you can select Integrated Caching,
Responder, DNS, Rewrite, or Content Switching), and then click
Policies.

2.

Select a policy and click Open.

3.

To test the expression, click the Advanced Expression Evaluator icon (the
check mark).

4.

In the Advanced Expression Evaluator dialog box, select the Flow Type
that matches the expression.

60

Citrix NetScaler Policy Configuration and Reference Guide

5.

In the HTTP Request Data or HTTP Response Data field, paste the
HTTP request or response that you want to parse with the expression, and
click Evaluate.
Note that you must supply a complete HTTP request or response, and the
header and body should be separated by blank line. Some programs that
trap HTTP headers do not also trap the response. If you are copying and
pasting only the header, insert a blank line at the end of the header to form a
complete HTTP request or response.

6.

Click Close to close this dialog box.

Configuring Named Advanced Expressions
Instead of re-typing the same expression multiple times in multiple policies, you
can configure a named expression and refer to the name any time you want to use
the expression in a policy. For example, you could create the following named
expressions:
•

ThisExpression: http.req.body(100).contains("this")

•

ThatExpression: http.req.body(100).contains("that")

You can then use these named expressions in a policy expression. For example,
the following is a legal expression based on the preceding examples:
ThisExpression || ThatExpression

To configure a named advanced expression by using the NetScaler
command line

At the NetScaler command prompt, type:
add policy expression expressionName rule

Following is an example:
add policy expression advancedNamedExpression
"http.req.body(100).contains(\"the other\")"

The expression can be up to 1,499 characters.
To configure a named advanced expression by using the configuration
utility

1.

In the navigation pane, expand AppExpert, and then click Expressions.

2.

Click Advanced Expressions.

3.

Click Add.

4.

Enter a name and a description for the expression.

Chapter 3

5.

Configuring Advanced Expressions: Getting Started

61

Configure the expression as described in “To configure an advanced policy
expression by using the configuration utility,” on page 58.

Configuring Advanced Expressions Outside the Context
of a Policy
A number of functions, including the following, can require an advanced
expression that is not part of a policy:
•

Integrated Caching selectors. You define multiple non-compound
expressions (selectlets) in the definition of the selector. Each selectlet is in
an implicit logical AND relationship with the others.

•

Load Balancing. You configure an expression for the TOKEN method of
load balancing for a load balancing virtual server.

•

Rewrite actions. Expressions define the location of the rewrite action and
the type of rewriting to be performed, depending on the type of rewrite
action that you are configuring. For example, a DELETE action only uses a
target expression. A REPLACE action uses a target expression and an
expression to configure the replacement text.

•

Rate-based policies: You use advanced expressions to configure Limit
Selectors. You can use these selectors when configuring policies to throttle
the rate of traffic to various servers. You define up to five non-compound
expressions (selectlets) in the definition of the selector. Each selectlet is in
an implicit logical AND with the others.

To configure an advanced expression outside a policy by using the
NetScaler command line (cache selector example)

From the NetScaler command line, enter the command for configuring the object
that requires an advanced expression. Following is an example of configuring a
cache selector. Note that line breaks in the following example are for readability.
Do not insert line breaks in the command:
add cache selector mainpage_selector
"http.req.cookie.value(\"ABC_def\")"
"http.req.url.query.value(\"_ghi\")" http.req.url.path
"http.req.body(150).typecast_nvlist_t(\'=\',\'&\').value(\"por
tlet_C{actionForm.endDate}\")"
"http.req.body(150).typecast_nvlist_t(\'=\',\'&\').value(\"por
tlet_C{actionForm.startDate}\")"

Following is an equivalent command that uses the more readable q delimiter, as
described in “Configuring Advanced Expressions in a Policy,” on page 57:
add cache selector mainpage_selector
q~http.req.cookie.value("ABC_def")~

62

Citrix NetScaler Policy Configuration and Reference Guide

q~http.req.url.query.value("_ghi")~ http.req.url.path
q~http.req.body(150).typecast_nvlist_t('=','&').value("portlet
_C{actionForm.endDate}")~
q~http.req.body(150).typecast_nvlist_t('=','&').value("portlet
_C{actionForm.startDate}")~

C HAPTER 4

Advanced Expressions: Evaluating
Text

You can configure an advanced expression to examine text in a request or a
response. For example, a expression can perform string matching on the
following types of data:
•

An HTTP header type

•

An HTTP header value

•

A user or group name in an HTTP request

•

A file type in a URL

•

A string in an HTTP POST body

You can configure text expressions to be case sensitive or case insensitive and to
use or ignore spaces.You can also configure complex expressions for text, for
example, by skipping x number of bytes before starting a search of a POST body
or by finding a string that occurs after the end of another string.
The rest of this chapter discusses the expression prefixes that extract text and the
operations that you can perform on the extracted text.
In This Chapter
About Text Expressions
Expression Prefixes for Text
Operations on Text
Complex Operations on Text
Note: You can apply complex functions to text expressions. For example, you
can transform a text string to a name-value list. Or, you can perform a match
against a pattern or set of patterns. For information on these advanced text
expressions, see “Advanced Expressions: String Sets, String Patterns, and Data
Formats,” on page 157.

64

Citrix NetScaler Policy Configuration and Reference Guide

About Text Expressions
You can configure various expressions for working with text that flows through
the NetScaler. Following are some examples of how you can parse text using an
advanced expression:
•

Determine that a particular HTTP header exists.
For example, you may want to identify HTTP requests that contains a
particular Accept-Language header for the purpose of directing the request
to a particular server.

•

Determine that a particular HTTP URL contains a particular string.
For example, you may want to block requests for particular URLs. Note
that the string can occur at the beginning, middle, or end of another string.

•

Identify a POST request that is directed to a particular application.
For example, you may want to identify all POST requests that are directed
to a database application for the purpose of refreshing cached application
data.

Note that there are specialized tools for viewing the data stream for HTTP
requests and responses. For example, you can download a Firefox Web browser
plug-in that displays HTTP request and response headers from the following
URL:
https://addons.mozilla.org/en-US/firefox/addon/3829
The following plug-in displays headers, query strings, POST data, and other
information:
https://addons.mozilla.org/en-US/firefox/addon/6647
After downloading these plug-ins, they are accessible from the Firefox Tools
menu.

About Operations on Text
A text-based expression consists of at least one prefix to identify an element of
data and usually (although not always) an operation on that prefix. Text-based
operations can apply to any part of a request or a response. Basic operations on
text include various types of string matches.
For example, the following expression compares a header value with a string:
http.req.header("myHeader").contains("some-text")

Following expressions are examples of matching a file type in a request:
http.req.url.suffix.contains("jpeg")
http.req.url.suffix.eq("jpeg")

Chapter 4

Advanced Expressions: Evaluating Text

65

In the preceding examples, the contains operator permits a partial match and
the eq operator looks for an exact match.
Other operations are available to format the string before evaluating it, for
example, to strip out quotes and white spaces, to convert the string to all
lowercase, or to concatenate strings.
Note: Complex operations are available to perform matching based on patterns
or to convert one type of text format to another type. For more information, see
“Advanced Expressions: String Sets, String Patterns, and Data Formats,” on page
157.

Compounding and Precedence in Text
Expressions
You can apply various operators to combine text prefixes or expressions. For
example, the following expression concatenates the returned values of each
prefix:
http.req.hostname + http.req.url

Following expression is an example of forming a compound text expression that
uses a logical AND. In this example, both components of the expression must be
TRUE for a request to match the expression:
http.req.method.eq(post) && http.req.body(1024).
startswith("destination=")

Note: For more information on operators for compounding, see “Compound
Advanced Expressions,” on page 45.

Categories of Text Expressions
The primary categories of text expressions that you can configure are:
•

Information in HTTP headers, HTTP URLs, and the POST body in HTTP
requests.
For more information, see “Expression Prefixes for Text in HTTP Requests
and Responses,” on page 67.

•

Information regarding a VPN or a clientless VPN.
For more information, see “Expression Prefixes for VPNs and Clientless
VPNs,” on page 76.

•

TCP payload information.

66

Citrix NetScaler Policy Configuration and Reference Guide

TCP payload expressions are discussed in another chapter. For more
information, see “Advanced Expressions: Parsing HTTP, TCP, and UDP
Data,” on page 113.
•

Text in an Secure Sockets Layer (SSL) certificate.
SSL and certificate expressions are discussed in another chapter. For
information on SSL and certificate data, see “Advanced Expressions:
Parsing SSL Certificates,” on page 141 and “Expressions for SSL
Certificate Dates,” on page 101.

Note: Parsing a document body, such as the body of a POST request, can affect
performance. You may want to test the performance impact of policies that
evaluate a document body.

Guidelines for Text Expressions
From a performance standpoint, it typically is best to use protocol-aware
functions in an expression. For example, the following expression makes use of a
protocol-aware function:
HTTP.REQ.URL.QUERY

The performance of the previous expression is typically better than the following
equivalent expression that is based on string parsing:
HTTP.REQ.URL.AFTER_STR("?")

In the first case, the expression looks specifically at the URL query. In the second
case, the expression scans the data for the first occurrence of a question mark.
There is also a performance benefit from structured parsing of text, as in the
following expression:
HTTP.REQ.HEADER("Example").TYPECAST_LIST_T(',').GET(1)

(For more information on typecasting, see “Transforming Text and Numbers into
Different Data Types,” on page 169.) The typecasting expression, which collects
comma-delimited data and structures it into a list, typically would perform better
than the following unstructured equivalent:
HTTP.REQ.HEADER("Example").AFTER_STR(",").BEFORE_STR(",")

Finally, unstructured text expressions typically have better performance than
regular expressions. For example, the following is an unstructured text
expression:
HTTP.REQ.HEADER("Example").AFTER_STR("more")

The previous expression would generally provide better performance than the
following equivalent, which uses a regular expression:

Chapter 4

Advanced Expressions: Evaluating Text

67

HTTP.REQ.HEADER("Example").AFTER_REGEX(re/more/)

For more information on regular expressions, see “Matching Text With a
Pattern,” on page 164.

Expression Prefixes for Text
The following sections discuss expression prefixes for strings.

Expression Prefixes for Text in HTTP Requests
and Responses
An HTTP request or response typically contains text, such as in the form of
headers, header values, URLs, and POST body text. You can configure
expressions to operate on one or more of these text-based items in an HTTP
request or response.
The following table describes the expression prefixes that you can configure to
extract text from different parts of an HTTP request or response.
HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.BODY(integer)

Description
Returns the body of an HTTP request as a multiline text
object, up to the character position designated in
integer.
There is no maximum value for the body argument, but
you should use as small a value as is practical. Larger
values can affect performance.
Note: Although it is possible to specify this prefix
without an integer argument, this usage is deprecated.

HTTP.REQ.HOSTNAME

Returns the HTTP host name in the first line of the
request, if there is one. Otherwise, this prefix returns the
value in the last occurrence of the HOST header.
Note that there are two similar prefixes that return host
names, as follows:
• http.req.url.hostname only returns the
host name from the URL
• http.req.header("Host") only returns the
value from the Host header. To use this value as a
host name you must typecast this string, as
illustrated in the following example: http.req.
header("host").typecast_http_
hostname_t
For more information on typecasting, see
“Transforming Text and Numbers into Different Data
Types,” on page 169.

68

Citrix NetScaler Policy Configuration and Reference Guide

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.HOSTNAME.
DOMAIN

Description
Returns the domain name part of the host name. For
example, if the host name is www.myhost.com or www.
myhost.com:8080, the domain is myhost.com.
Returns incorrect results if the host name has an IP
address. For information on expressions for IP
addresses, see “Advanced Expressions: IP and MAC
Addresses, Throughput, VLAN IDs,” on page 149.
All text operations that you specify after this prefix are
case insensitive.

HTTP.REQ.HOSTNAME.
SERVER

Returns the server name part of the host name. If the
host name is www.myhost.com or www.myhost.
com:8080, the server is www.myhost.com.
All text operations that you specify after this prefix are
case insensitive.

HTTP.REQ.METHOD

Returns the value of the METHOD in an HTTP request,
or matches the method type if you provide it as an
argument, for example, http.req.method.
eq(get). If you enclose the argument in quotes,
evaluation is case-sensitive.

HTTP.REQ.URL

Returns the HTTP URL.

HTTP.REQ.URL.HOSTNAME

Returns the host name in the HTTP URL.
Do not use this prefix in bidirectional policies.
Note that there are two similar prefixes that return host
names, as follows:
• HTTP.REQ.HOSTNAME returns the host name
from the URL if there is one; otherwise, it returns
the value in the last occurrence of the Host header.
• HTTP.REQ.HEADER("Host") only returns the
value from the Host header. To use this value as a
host name you must typecast this string, as
illustrated in the following example: http.req.
header("host").typecast_http_
hostname_t
For more information on typecasting, see
“Transforming Text and Numbers into Different Data
Types,” on page 169.

Chapter 4

Advanced Expressions: Evaluating Text

69

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.URL.HOSTNAME.
DOMAIN

Description
Returns the domain name part of the host name. For
example, if the host name is www.myhost.com or www.
myhost.com:8080, the domain is myhost.com.
This operation returns incorrect results if the host name
has an IP address. For information on expressions for IP
addresses, see “Advanced Expressions: IP and MAC
Addresses, Throughput, VLAN IDs,” on page 149.
All text operations that you specify after this prefix are
case insensitive unless explicitly set by the SET_
TEXT_MODE operator.

HTTP.REQ.URL.HOSTNAME.
SERVER

Returns the server name part of the host name. For
example, if the host name is www.myhost.com or www.
myhost.com:8080, the server is www.myhost.com.
All text operations that you specify after this prefix are
case insensitive.

HTTP.REQ.URL.PATH

Returns a slash- (/) separated list from the path in a
URL.
For example, if the URL is http://www.myhost.com/a/b/
c/mypage.html?a=1, this prefix returns the string /a/b/c/
mypage.html.
The expression http.req.url.path.get(1)
returns "a" from the preceding URL. For more
information on the GET operation, see “Expressions
for Extracting Segments of URLs,” on page 129.

HTTP.REQ.URL.PATH_AND_
QUERY

Returns the portion of the URL that follows the host
name.
For example, if the URL is http://www.myhost.com/a/b/
c/mypage.html?a=1, this prefix returns /a/b/c/mypage.
html?a=1.

HTTP.REQ.URL.PROTOCOL

Returns the protocol in the URL.
This prefix cannot be used in bidirectional policies.
Following is an example:
http.req.hostname + http.req.url.
protocol

HTTP.REQ.URL.QUERY

Returns a name-value list, using the delimiters “=” and
“&”, from the query component in the URL.
Following is an example:
http.req.url.query.contains("viewReport
&& my_pagelabel")

70

Citrix NetScaler Policy Configuration and Reference Guide

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.URL.QUERY.
VALUE

Description
Returns the value from the name-value pair in the
argument supplied to this prefix, using the delimiter “=”
from the query component in the URL.
Following is an example:
http.req.url.query.value("action")

The first component that matches the name is selected.
The matching process honors the IGNORECASE and
the NOIGNORECASE text modes. The
URLENCODED and the NOURLENCODED text
modes are ignored.
HTTP.REQ.URL.SUFFIX

Returns the file name suffix in a URL.
For example, if the path in the URL is /a/b/c/mypage.
html, this suffix selects “html”. Following is another
example:
http.req.url.suffix.contains("jpeg")

HTTP.REQ.USER

Returns the AAA user associated with the current
HTTP transaction.

HTTP.REQ.USER.EXTERNAL_ Returns a list of the external groups to which a user
belongs. The groups are separated by a comma (",").
GROUPS

For example, HTTP.REQ.USER.EXTERNAL_
GROUPS returns a comma-separated list of all the
external groups to which the user belongs.
HTTP.REQ.USER.EXTERNAL_ Ignores the empty elements in the list of external groups
to which the user belongs.
GROUPS.IGNORE_EMPTY_
ELEMENTS

If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element following "b=11" is not considered an
empty element.

For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
Then the following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT.

Chapter 4

Advanced Expressions: Evaluating Text

71

HTTP Expression Prefixes that Return Text
Prefix

Description

HTTP.REQ.USER.EXTERNAL_ Returns a list of all the external groups to which the user
belongs. The groups are separated by the given
GROUPS(sep)

delimiter.
For example, the following expression gives a list of all
the external groups, and the groups are separated by a
colon (":"):
HTTP.REQ.USER.EXTERNAL_GROUPS(':')
Parameters:
sep - delimiter
HTTP.REQ.USER.EXTERNAL_ Ignores the empty elements in the list of external groups
to which the user belongs.
GROUPS.IGNORE_EMPTY_
ELEMENTS

If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element following "b=11" is not considered an
empty element.

For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT
HTTP.REQ.USER.GROUPS

Returns a list of the internal and external groups to
which the user belongs. The groups are separated by a
comma (",").
In this list, internal groups are listed first, followed by
external groups.

72

Citrix NetScaler Policy Configuration and Reference Guide

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.USER.GROUPS.
IGNORE_EMPTY_ELEMENTS

Description
Ignores the empty elements in the list of groups to
which the user belongs.
If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element that follows "b=11" is not considered
an empty element.
For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT

HTTP.REQ.USER.
GROUPS(sep)

Returns a list of groups to which the user belongs. The
groups in the list are separated by the delimiter
specified as the argument.
For example, the following expression returns a colonseparated list of all the groups to which the user
belongs.
HTTP.REQ.USER.GROUPS(':')
In this list, internal groups are listed first, followed by
external groups.
Parameters:
sep - delimiter

Chapter 4

Advanced Expressions: Evaluating Text

73

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.USER.GROUPS.
IGNORE_EMPTY_ELEMENTS

Description
Ignores the empty elements in the list of groups to
which the user belongs.
If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element following "b=11" is not considered an
empty element.
For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT.

HTTP.REQ.USER.INTERNAL_ Returns a list of internal groups to which the user
belongs. The groups are separated by a comma (",").
GROUPS

For example, the following expression returns a
comma-separated list of all the internal groups to which
a user belongs.
HTTP.REQ.USER.INTERNAL_GROUPS
HTTP.REQ.USER.INTERNAL_ Ignores the empty elements in the list of internal groups
to which the user belongs.
GROUPS.IGNORE_EMPTY_
ELEMENTS

If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element following "b=11" is not considered an
empty element.

For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT

74

Citrix NetScaler Policy Configuration and Reference Guide

HTTP Expression Prefixes that Return Text
Prefix

Description

HTTP.REQ.USER.INTERNAL_ Returns a list of the internal groups to which the user
belongs. The groups are separated by the given
GROUPS(sep)

delimiter.
For example, the following expression returns a colonseparated list of all the internal groups to which the user
belongs.
HTTP.REQ.USER.INTERNAL_GROUPS(':')
Parameters:
sep - delimiter
HTTP.REQ.USER.INTERNAL_ Ignores the empty elements in the list of internal groups
to which the user belongs.
GROUPS.IGNORE_EMPTY_
ELEMENTS

If the element delimiter in the list is a comma (","), then
the following list has an empty element following
"a=10":
a=10,,b=11, ,c=89
But the element following "b=11" is not considered an
empty element.

For example, consider the following header in an HTTP
request packet:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(','). IGNORE_EMPTY_ELEMENTS.COUNT
The following expression returns a value of 5:
HTTP.REQ.HEADER("Cust_Header").TYPECAST_
LIST_T(',').COUNT.
HTTP.REQ.USER.IS_
MEMBER_OF(group_name)

Returns a boolean TRUE if the user who is named in
the request is a member of the argument specified in
group.
Following is an example:
http.req.user.is_member_of("mygroup")
Parameter:
group_name: The name of the group.

HTTP.REQ.USER.NAME

Returns the name of the user in the request.
Following is an example:
http.req.username.contains("rohit")

HTTP.REQ.USER.PASSWD

Returns the password of the user.

Chapter 4

Advanced Expressions: Evaluating Text

75

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.VERSION

Description
Returns the HTTP version listed in the request.
Following is an example:
http.req.version "\"HTTP/1.0\"

HTTP.RES.BODY(integer)

Returns a portion of the HTTP response body. The
length of the returned text is equal to the number in the
integer argument.
If there are fewer characters in the body than are
specified in integer, the entire body is returned.
Following is an example:
http.res.body(100).suffix('L',1)

HTTP.RES.STATUS_MSG

Returns the HTTP response status message.

HTTP.RES.VERSION

Returns the HTTP version listed in the response.

HTTP.REQ.URL.HOSTNAME.
EQ("hostname")

Returns a Boolean TRUE value if the host name
matches the hostname argument. The comparison is
case insensitive and if textmode is URLENCODED, the
host name is decoded before comparison. For example,
if the host name is www.mycompany.com., the
following is TRUE:
http.req.url.hostname.eq("www.mycompany.
com")

HTTP.REQ.URL.HOSTNAME.
PORT

Returns the port in the host name. The string following
and including the first colon (“:”) is considered the port
value. For example, if the host name is www.
mycompany.com:8080, the port is ":8080". If the host
name is www.mycompany.com: the port is ":". If the
host name is www.mycompany.com, the port is "" and
points to a location just after ".com".
If the numerical value in the port is missing, it assumes
a default value of 80 or 443 (for HTTPS connections).

HTTP.REQ.URL.HOSTNAME.
SERVER

Returns the server name portion of the host name. For
example, if the host name is www.mycompany.com or
www.mycompany.com:8080, the returned server name
is www.mycompany.com.
This method sets the text mode to case insensitive. All
text operations after this method are case insensitive.

HTTP.REQ.IS_NTLM_OR_
NEGOTIATE

Returns a Boolean TRUE if the request is a part of an
NTLM or NEGOTIATE connection.

HTTP.REQ.URL.CVPN_
ENCODE

Converts the URL to the clientless VPN format.

76

Citrix NetScaler Policy Configuration and Reference Guide

HTTP Expression Prefixes that Return Text
Prefix
HTTP.REQ.URL.PATH.
IGNORE_EMPTY_ELEMENTS

Description
Ignores the empty elements in the list. For example, if
the element delimiter in the list is a comma, the
following list has an empty element following a=10:
a=10,b=11, ,c=89
The element following b=11 is not considered an empty
element.
As another example, consider the following header:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4:
http.req.header("Cust_Header").typecast_
list_t(',').ignore_empty_elements.count

The following expression returns a value of 5:
http.req.header("Cust_Header").typecast_
list_t(','). count
HTTP.REQ.URL.QUERY.
IGNORE_EMPTY_ELEMENTS

This method ignores the empty elements in a namevalue list. For example, if the list delimiter is a
semicolon, the following list has an empty element
following a=10:
a=10;;b=11; ;c=89
The element following b=11 is not considered an empty
element.
For example, consider the following header:
Cust_Header : a=1;;b=2; ;c=3
The following expression returns a value of 4:
http.req.header("Cust_Header").typecast_
nvlist_t('=',';').ignore_empty_elements.
count

The following expression returns a value of 5:
http.req.header("Cust_Header").typecast_
nvlist_t('=',';'). count

Expression Prefixes for VPNs and Clientless
VPNs
The advanced expression engine provides prefixes that are specific to parsing
VPN or Clientless VPN data. This data includes the following:
•

Host names, domains, and URLs in VPN traffic.

•

Protocols in the VPN traffic.

Chapter 4

•

Advanced Expressions: Evaluating Text

77

Queries in the VPN traffic.

These text elements are often URLs and components of URLs. In addition to
applying the text-based operations on these elements as described elsewhere in
this chapter, you can parse these elements using operations that are specific to
parsing URLs. For more information, see “Expressions for Extracting Segments of
URLs,” on page 129.
The following table describes the expression prefixes for this type of data.
VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression

Description

VPN.BASEURL.CVPN_DECODE

Extracts the original URL from a clientless VPN
URL.

VPN.BASEURL.CVPN_ENCODE

Converts a URL to clientless VPN format.

VPN.BASEURL.HOSTNAME

Extracts the HTTP host name from the host name
in the URL.
This prefix cannot be used in bidirectional policies.

VPN.BASEURL.HOSTNAME.DOMAIN Extracts the domain name from the host name.

For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
this prefix extracts mycompany.com.
This prefix returns incorrect results if the host
name is an IP address. For information on
expressions for IP addresses, see “Advanced
Expressions: IP and MAC Addresses,
Throughput, VLAN IDs,” on page 149.
All text operations after this prefix are case
insensitive.
VPN.BASEURL.HOSTNAME.EQ
("hostname")

Returns a Boolean TRUE if the host name matches
hostname. The comparison is case insensitive.
For example, if the host name is www.
mycompany.com, the following returns TRUE:
vpn.baseurl.hostname.eq("www.
mycompany.com")

If the text mode is URLENCODED, the host name
is decoded before comparison. For more
information, see “Operations for HTTP, HTML,
and XML Encoding and “Safe” Characters,” on
page 131.

78

Citrix NetScaler Policy Configuration and Reference Guide

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression

Description

VPN.BASEURL.HOSTNAME.SERVER Evaluates the server portion of the host name.

For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the server is www.mycompany.com.
All text operations after this prefix are case
insensitive.
VPN.BASEURL.PATH

Extracts a slash- (/) separated list from the path
component of the URL. For example, this prefix
extracts /a/b/c/mypage.html from the following
URL:
http://www.mycompany.com/a/b/c/mypage.
html?a=1
The following expression selects just the “a”:
http.req.url.path.get(1)

For more information on the GET operation, see
“Expressions for Extracting Segments of URLs,”
on page 129.
VPN.BASEURL.PATH.IGNORE_
EMPTY_ELEMENTS

This prefix ignores the elements in a list. For
example, the following comma-separated list has
an empty element after “a=10”:
a=10,,b=11, ,c=89
The element following b=11 contains a space, and
by default, is not considered an empty element.
Consider the following HTTP header:
Cust_Header : 123,,24, ,15
The following expression returns a count of 4
when evaluating this header:
http.req.header("Cust_Header").
typecase_list_t(',').ignore_empty_
elements.count

The following expression returns a count of 5
when evaluating this header:
http.req.header("Cust_Header").
typecase_list_t(','). count
VPN.BASEURL.PATH_AND_QUERY Evaluates the text in the URL that follows the host

name.
For example, if the URL is http://www.
mycompany.com/a/b/c/mypage.html?a=1, this
prefix evaluates /a/b/c/mypage.html?a=1.

Chapter 4

Advanced Expressions: Evaluating Text

79

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.BASEURL.PROTOCOL

Description
Evaluates the protocol in the URL.
Do not use this prefix in bidirectional policies.

VPN.BASEURL.QUERY

Extracts a name-value list, using the “=” and “&”
delimiters from the query string in a URL.

VPN.BASEURL.QUERY.IGNORE_
EMPTY_ELEMENTS

This method ignores the empty elements in a
name-value list. For example, in the following
name-value list, there is an empty element
following “a=10”:
a=10;;b=11; ;c=89
The element following b=11 contains a space and
is not considered an empty element.
Consider the following HTTP header:
Cust_Header : a=1;;b=2; ;c=3
The following expression produces a count of 4
after evaluating this header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';').ignore_
empty_elements.count

The following expression produces a count of 5
after evaluating the header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';').
VPN.BASEURL.SUFFIX

Evaluates the file name suffix in a URL.
For example, if the path is /a/b/c/my.page.html,
this operation selects “html”.

VPN.CLIENTLESS_BASEURL

Evaluates the clientless VPN base URL.

VPN.CLIENTLESS_BASEURL.
CVPN_DECODE

Extracts the original URL from the clientless VPN
formatted URL.

VPN.CLIENTLESS_BASEURL.
CVPN_ENCODE

Converts a URL to the clientless VPN format.

VPN.CLIENTLESS_BASEURL.
HOSTNAME

Evaluates the host name in the URL.
Do not use this prefix in bidirectional policies.

80

Citrix NetScaler Policy Configuration and Reference Guide

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.CLIENTLESS_BASEURL.
HOSTNAME.DOMAIN

Description
Evaluates the domain name part of the host name.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the domain is mycompany.com.
This operation returns incorrect results if the host
name is an IP address. For information on
expressions for IP addresses, see “Advanced
Expressions: IP and MAC Addresses,
Throughput, VLAN IDs,” on page 149.
All text operations after this prefix are case
insensitive.

VPN.CLIENTLESS_BASEURL.
HOSTNAME.EQ("hostname")

Returns a Boolean TRUE if the host name matches
hostname.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the following is true:
vpn.clientless_baseurl. hostname.
eq("www.mycompany.com")

The comparison is case insensitive. If the textmode
is URLENCODED, the host name is decoded
before comparison. For more information, see
“Operations for HTTP, HTML, and XML
Encoding and “Safe” Characters,” on page 131.
VPN.CLIENTLESS_BASEURL.
HOSTNAME.SERVER

Evaluates the server part of a host name.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the server is www.mycompany.com.
All text operations after this prefix are case
insensitive.

VPN.CLIENTLESS_BASEURL.PATH Evaluates a slash- (/) separated list in the URL

path.
For example, this prefix selects /a/b/c/mypage.html
from the following URL:
http://www.mycompany.com/a/b/c/mypage.
html?a=1
The following expression selects “a” from the
preceding URL:
http.req.url.path.get(1)

For more information on the GET operation, see
“Expressions for Extracting Segments of URLs,”
on page 129.

Chapter 4

Advanced Expressions: Evaluating Text

81

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression

Description

VPN.CLIENTLESS_BASEURL.
Ignores empty elements in a list. For example, if
PATH.IGNORE_EMPTY_ELEMENTS the list delimiter is a comma (,) the following list

has an empty element following “a=10”:
a=10,b=11, ,c=89
The element following b=11 contains a space and
is not considered an empty element.
Consider the following HTTP header:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4 after
evaluating this header:
http.req.header("Cust_Header").
typecast_list_t(',').ignore_empty_
elements.count

The following expression returns a value of 5 after
evaluating this header:
http.req.header("Cust_Header").
typecast_list_t(',').
VPN.CLIENTLESS_BASEURL.
PATH_AND_QUERY

Evaluates the text following the host name in a
URL.
For example, this prefix selects /a/b/c/mypage.
html?a=1 from the following URL:
http://www.mycompany.com/a/b/c/mypage.
html?a=1

VPN.CLIENTLESS_BASEURL.
PROTOCOL

Evaluates the protocol in the URL.

VPN.CLIENTLESS_BASEURL.
QUERY

Extracts a name-value list that uses the delimiters
“=” and “&” from a URL query string.

Do not use this prefix in bidirectional policies.

82

Citrix NetScaler Policy Configuration and Reference Guide

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.CLIENTLESS_BASEURL.
QUERY.IGNORE_EMPTY_
ELEMENTS

Description
Ignores empty elements in a name-value list. For
example, the following list contains an empty
element after “a=10”:
a=10;;b=11; ;c=89
The element following b=11 contains a space and
is not considered an empty element.
As another example, consider the following http
header:
Cust_Header : a=1;;b=2; ;c=3
The following expression returns a value of 4 after
evaluating the preceding header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';').ignore_
empty_elements.count

The following expression returns a value of 5 after
evaluating the preceding header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';')
VPN.CLIENTLESS_BASEURL.
SUFFIX

Evaluates the file suffix in a URL. For example, if
the URL path is /a/b/c/mypage.html then this
operation selects html.

VPN.CLIENTLESS_HOSTURL

Selects the clientless VPN host URL.

VPN.CLIENTLESS_HOSTURL.
CVPN_DECODE

Selects the original URL from the clientless VPN
formatted URL.

VPN.CLIENTLESS_HOSTURL.
CVPN_ENCODE

Converts a URL to clientless VPN format.

VPN.CLIENTLESS_HOSTURL.
HOSTNAME

Extracts the host name in the URL.

VPN.CLIENTLESS_HOSTURL.
HOSTNAME.DOMAIN

Extracts the domain name from the host name. For
example, if the host name is www.mycompany.
com or www.mycompany.com:8080, the domain is
mycompany.com.

Do not use this prefix in bidirectional policies.

This operation returns incorrect results if the host
name contains an IP address. For information on
expressions for IP addresses, see “Advanced
Expressions: IP and MAC Addresses,
Throughput, VLAN IDs,” on page 149.
All text operations after this prefix are case
insensitive.

Chapter 4

Advanced Expressions: Evaluating Text

83

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.CLIENTLESS_HOSTURL.
HOSTNAME.EQ("hostname")

Description
Results in Boolean TRUE if the host name
matches the hostname argument. The comparison
is case insensitive.
For example, if the host name is www.
mycompany.com or www.mycompany.com., the
following expression returns TRUE:
vpn.clilentless_hosturl. hostname.
eq("www.mycompany.com")

If the text mode is URLENCODED, the host name
is decoded before comparison. For more
information, see “Operations for HTTP, HTML,
and XML Encoding and “Safe” Characters,” on
page 131.
VPN.CLIENTLESS_HOSTURL.
HOSTNAME.SERVER

Evaluates the server part of the host name.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the server is www.mycompany.com.
The comparison is case insensitive, and all text
operations after this method are case insensitive.

VPN.CLIENTLESS_HOSTURL.PATH Evaluates a slash- (/) separated list on the path

component of the URL.
For example, consider the following URL:
http://www.mycompany.com/a/b/c/mypage.
html?a=1
This prefix selects /a/b/c/mypage.html from the
preceding URL.

84

Citrix NetScaler Policy Configuration and Reference Guide

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression

Description

VPN.CLIENTLESS_HOSTURL.
This method ignores the empty elements in a list.
PATH.IGNORE_EMPTY_ELEMENTS For example, if the delimiter in a list is “,” the

following list contains an empty element after the
entry “a=10”:
a=10,b=11, ,c=89
The element following b=11 contains a space and
is not considered an empty element.
Consider the following header:
Cust_Header : 123,,24, ,15
The following expression returns a value of 4 for
this header:
http.req.header("Cust_Header").
typecast_list_t(','). ignore_empty_
elements.count

The following expression returns a value of 5 for
the same header:
http.req.header("Cust_Header").
typecast_list_t(',').
VPN.CLIENTLESS_HOSTURL.
PATH_AND_QUERY

Evaluates the portion of the URL that follows the
host name.
For example, consider the following URL:
http://www.mycompany.com/a/b/c/mypage.
html?a=1
This prefix returns /a/b/c/mypage.html?a=1 from
the preceding URL.

VPN.CLIENTLESS_HOSTURL.
PROTOCOL

Evaluates the protocol in the URL.

VPN.CLIENTLESS_HOSTURL.
QUERY

Extracts a name-value list, using the “=” and “&”
delimiters from a URL query string.

Do not use this prefix in bidirectional policies.

Chapter 4

Advanced Expressions: Evaluating Text

85

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.CLIENTLESS_HOSTURL.
QUERY.IGNORE_EMPTY_
ELEMENTS

Description
Ignores empty elements in a name-value list. For
example, the following list uses a semicolon (;)
delimiter. This list contains an empty element after
“a=10”:
a=10;;b=11; ;c=89
In the preceding example, the element following
b=11 is not considered an empty element.
Consider the following header:
Cust_Header : a=1;;b=2; ;c=3
The following expression returns a value of 4 after
evaluating this header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';').ignore_
empty_elements.count

The following expression returns a value of 5 after
evaluating the same header:
http.req.header("Cust_Header").
typecast_nvlist_t('=',';')
VPN.CLIENTLESS_HOSTURL.
SUFFIX

Extracts a file name suffix in a URL.

VPN.HOST.DOMAIN

Extracts the domain name part of the host name.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the domain is mycompany.com.

For example, if the path is /a/b/c/my.page.html,
this prefix selects html.

This prefix returns incorrect results if the host
name contains an IP address. For information on
expressions for IP addresses, see “Advanced
Expressions: IP and MAC Addresses,
Throughput, VLAN IDs,” on page 149.
All text operations after this prefix case insensitive.

86

Citrix NetScaler Policy Configuration and Reference Guide

VPN and Clientless VPN Expression Prefixes that Return Text
VPN and Clientless VPN
Expression
VPN.HOST.EQ("hostname")

Description
Returns a Boolean TRUE value if the host name
matches the hostname. The comparison is case
insensitive.
For example, if the host name is www.
mycompany.com or www.mycompany.com:8080,
the following returns TRUE:
vpn.host.eq("www.mycompany.com")
If the text mode is URLENCODED the host name
is decoded before comparison. For more
information, see “Operations for HTTP, HTML,
and XML Encoding and “Safe” Characters,” on
page 131.

VPN.HOST.SERVER

Extracts the server name part of the host name. For
example, if the host name is www.mycompany.
com or www.mycompany.com:8080, the server is
www.mycompany.com.
All text operations after this prefix are case
insensitive.

Operations on Text
The following sections describe text operations that examine text.
Be aware of the following conditions for any text-based operation:
•

For any operation that takes a string argument, the string cannot exceed 255
characters.

•

You can include white space when you specify a string in an expression.

Basic Operations on Text
The following table lists basic operations on text.
Basic Operations on Text
Basic Text Operation
text.CONTAINS("string")

Description
Returns a Boolean TRUE value if the target contains
string.
Following is an example:
http.req.url.contains(".jpeg")

Chapter 4

Advanced Expressions: Evaluating Text

87

Basic Operations on Text
Basic Text Operation
text.EQ("string")

Description
Returns a Boolean TRUE value if the target is an exact
match with string.
For example, the following expression returns a
Boolean TRUE for a URL with a host name of
“myhostabc”:
http.req.url.hostname.eq("myhostabc")

text.
STARTSWITH("string")

Returns a Boolean TRUE value if the target begins
with string.
For example, the following expression returns a
Boolean TRUE for a URL with a host name of
“myhostabc”:
http.req.url.hostname.
startswith("myhost")

text.ENDSWITH("string")

Returns a Boolean TRUE value if the target ends with
string.
For example, the following expression returns a
Boolean TRUE for a URL with a host name of
“myhostabc”:
http.req.url.hostname.endswith("abc")

Operations for Calculating the Length of a String
The following operation returns a numeric value that shows the number of
characters (not bytes) of a string:
text.LENGTH

For example, you may want to identify request URLs that exceed a particular
length. Following is the expression that implements this example:
HTTP.REQ.URL.LENGTH < 500

After taking a count of the characters or elements in a string, you can apply
numeric operations to them. For more information, see “Advanced Expressions:
Working with Dates, Times, and Numbers,” on page 95.

Operations for Controlling Case Sensitivity
The following operation turns case sensitivity on or off for an expression.
Operations on Case Sensitivity of Text
Case Operation
text.SET_TEXT_
MODE(IGNORECASE|
NOIGNORECASE)

Description
This operation turns case sensitivity on or off
for all text operations.

88

Citrix NetScaler Policy Configuration and Reference Guide

Operations on Case Sensitivity of Text
Case Operation
text.TO_LOWER

Description
Converts the target to lowercase.
For example, the string “ABCd:” is converted
to “abcd:”.

text.TO_UPPER

Converts the target to uppercase.
For example, the string “abcD:” is converted to
“ABCD:”.

Complex Operations on Text
In addition to performing simple string matching, you can configure expressions
that examine more complex aspects of text, including examining the length of a
string and looking within a text block for patterns rather than specific strings.
Be aware of the following for any text-based operation:
•

For any operation that takes a string argument, the string cannot exceed 255
characters.

•

You can include white space when you specify a string in an expression.

Operations on the Length of a String
The following operations extract strings based on a character count.
Operations on Strings Based on a Character Count
Character Count Operation
text.TRUNCATE(count)

Description
Returns a string after truncating the end of the
target by the number of characters in count.
If the entire string is shorter than count, nothing is
returned.

text.TRUNCATE(character,
count)

Returns a string after truncating the text after
character by the number of characters specified in
count.

text.PREFIX(character,
count)

Selects the longest prefix in the target that has at
most count occurrences of character.

Chapter 4

Advanced Expressions: Evaluating Text

Operations on Strings Based on a Character Count
Character Count Operation
text.SUFFIX(character,
count)

Description
Selects the longest suffix in the target that has at
most count occurrences of character.
For example, consider the following response
body:
JLEwx

The following expression returns a value of
“JLEwx”:
http.res.body(100).suffix('L',1)

The following expression returns “LLEwx”:
http.res.body(100).suffix('L',2)
text.SUBSTR(starting_
offset, length)

Select a string with length number of characters
from the target object. Begin extracting the string
after the starting_offset. If the number of
characters after the offset are fewer than the value
of the length argument, select all the remaining
characters.

text.SKIP(character, count) Select a string from the target after skipping over

the longest prefix that has at most count
occurrences of character.

Operations on a Portion of a String
You can extract a subset of a larger string using one of the operations in the
following table.
Basic Operations on a Portion of a String
Basic Text Operation
text.BEFORE_
STR("string")

Description
Returns the text that precedes the first occurrence of string.
If there is no match for string, the expression returns a text
object of 0 length.
Following is an example:
http.res.body(1024).after_str("start_
string").before_str("end_string").
contains("https")

text.AFTER_
STR("string")

Returns the text that follows the first occurrence of string.
If there is no match for string, the expression returns a text
object of 0 length.
Following is an example:
http.res.body(1024).after_str("start_
string").before_str("end_string").
contains("https")

89

90

Citrix NetScaler Policy Configuration and Reference Guide

Basic Operations on a Portion of a String
Basic Text Operation

Description

text.
BETWEEN("starting
string", "ending
string")

Returns a Boolean TRUE value if the length of the text
object is greater than or equal to the sum starting string,
ending string argument lengths, and if a prefix of the target
matches starting string, and if the suffix of the target
matches ending string.

text.PREFIX(prefix
length)

Returns the starting string from a target block of text that
contains the number of characters in the length argument.
If the prefix length argument exceeds the number of
characters in the target, the entire string is selected.

text.SUFFIX(suffix
length)

Returns the ending string from a target block of text that
contains the number of characters in the length argument. If
the suffix length argument exceeds the number characters in
the target, the entire string is selected.

text.
SUBSTR("string")

Select the first block of text in the target that matches the
string.

text.SKIP(prefix
length)

Selects the text in the target after skipping over a prefix
length number of characters.
If the entire target has fewer characters than prefix length, the
entire target is skipped.

text.STRIP_END_WS

Selects the text after removing white space from the end of
the target.

text.STRIP_START_WS Selects the text after removing white space from the

beginning of the target.
text.
UNQUOTE(character)

Selects the character, removes white space that immediately
precedes and follows the character, and if the remaining text
is quoted by character, this prefix also removes the quotes.
For example, the operation UNQUOTE('"') changes the
following text:
"abc xyz def "

To the following:
abc xyz def

Operations for Comparing the Alphanumeric
Order of Two Strings
The COMPARE operation examines the first non-matching character of two
different strings. This operation is based on lexicographic order, which is the
method used when ordering terms in dictionaries.
This operation returns the arithmetic difference between the ASCII values of the
first non-matching characters in the compared strings. The following differences
are examples:

Chapter 4

Advanced Expressions: Evaluating Text

91

•

The difference between “abc” and “abd” is -1 (based on the third pair-wise
character comparison).

•

The difference between “@” and “abc” is -33.

•

The difference between “1” and “abc” is -47.

The following is the syntax for the COMPARE operation.
text.COMPARE("string")

Extracting the nth Integer from a String of Bytes
that Represent Text
You can use the following operators to treat a string of bytes that represent text as
a sequence of 8-bit, 16-bit, or 32-bit signed or unsigned integers, and then extract
the nth integer from the sequence.
Operations for Extracting the nth Integer from a String of Bytes that Represent Text
Operation

Description

text.GET_SIGNED16(n, Treats the string of bytes represented by text as a sequence of
16-bit signed integers and returns the nth integer. The second
endianness)

argument takes a value of 0 for little endian or 1 for big
endian.
text.GET_SIGNED32(n, Treats the string of bytes represented by text as a sequence of
32-bit signed integers and returns the nth integer. The second
endianness)

argument takes a value of 0 for little endian or 1 for big
endian.
text.GET_SIGNED8(n) Treats the string of bytes represented by text as a sequence of

8-bit signed integers and returns the nth integer.
text.GET_
UNSIGNED16(n,
endianness)

Treats the string of bytes represented by text as a sequence of
16-bit unsigned integers and returns the nth integer. The
second argument takes a value of 0 for little endian or 1 for
big endian.

text.GET_
UNSIGNED8(n)

Treats the string of bytes represented by text as a sequence of
8-bit unsigned integers and returns the nth integer.

Converting Text to a Hash Value
You can convert a text string to a hash value by using the .HASH operator. This
operator returns a 31-bit positive integer as a result of the operation. Following is
the format of the expression:
text.HASH
This operator ignores case and white spaces. For example, after the operation, the
two strings "Ab c" and "a bc" would produce the same hash value.

92

Citrix NetScaler Policy Configuration and Reference Guide

Encoding and Decoding Text by Applying the
Base64 Encoding Algorithm
The following two operators encode and decode a text string by applying the
Base64 encoding algorithm:
Operators for Encoding and Decoding a Text String by Using Base64 Encoding
Operator

Description

text.B64ENCODE

Encodes the text string (designated by text) by applying the
Base64 encoding algorithm.

text.B64DECODE

Decodes the Base64-encoded string (designated by text) by
applying the Base64 decoding algorithm. The operation
raises an UNDEF if text is not in B64-encoded format.

Refining the Search in a Rewrite Action by Using
the EXTEND Operator
The EXTEND operator is used in rewrite actions that specify patterns or pattern
sets and target the bodies of HTTP packets. When a pattern match is found, the
EXTEND operator extends the scope of the search by a predefined number of
bytes on both sides of the matching string. A regular expression can then be used
to perform a rewrite on matches in this extended region. Rewrite actions that are
configured with the EXTEND operator perform rewrites faster than rewrite
actions that evaluate entire HTTP bodies using only regular expressions.
The format of the EXTEND operator is EXTEND(m,n), where m and n are the
number of bytes by which the scope of the search is extended before and after the
matching pattern, respectively. When a match is found, the new search scope
comprises m bytes that immediately precede the matching string, the string itself,
and the n bytes that follow the string. A regular expression can then be used to
perform a rewrite on a portion of this new string.
The EXTEND operator can be used only if the rewrite action in which it is used
fulfills the following requirements:
•

The search is performed by using patterns or patterns sets (not regular
expressions)

•

The rewrite action evaluates only the bodies of HTTP packets.

Additionally, the EXTEND operator can be used only with the following types of
rewrite actions:
•

replace_all

•

insert_after_all

Chapter 4

•

delete_all

•

insert_before_all

Advanced Expressions: Evaluating Text

93

For example, you might want to delete all instances of "http://exampleurl.com/"
and "http://exampleurl.au/" in the first 1000 bytes of the body. To do this, you can
configure a rewrite action to search for all instances of the string "exampleurl,"
extend the scope of the search on both sides of the string when a match is found,
and then use a regular expression to perform the rewrite in the extended region.
The following example extends the scope of the search by 20 bytes to the left and
50 bytes to the right of the matching string:
add rewrite action delurl_example delete_all 'HTTP.REQ.
BODY(1000)' -pattern exampleurl -refineSearch 'extend(20,50).
regex_select(re#http://exampleurl.(com|au)#)'

Converting Text to Hexadecimal Format
The following operator converts text to hexadecimal format and extracts the
resulting string:
text.BLOB_TO_HEX("string")

For example, this operator converts the byte string “abc” to “61:62:63”.

94

Citrix NetScaler Policy Configuration and Reference Guide

C HAPTER 5

Advanced Expressions: Working
with Dates, Times, and Numbers

Most numeric data that the NetScaler processes consists of dates and times.
However, advanced expressions also work with other numeric data, for example,
the lengths of HTTP requests and responses.
You can configure advanced expressions to evaluate and to perform operations on
dates, times, and other numeric data. For example, you can configure an
expression to perform the following:
•

Extract an expiration date and time from an SSL certificate, and determine
if it falls within a specified range.

•

Extract the NetScaler system time.

•

Extract other numeric data points, for example, a status code or a version
number.

•

Extract a full IP address or MAC address, or a subset of one.

•

Add the lengths of two strings.

This chapter concentrates on date and time data, and a few other types of nondate-related numeric data.
In This Chapter
Format of Dates and Times in an Expression
Dates and Times in a Rewrite Action
Expressions for the NetScaler System Time
Expressions for SSL Certificate Dates
Expressions for HTTP Request and Response Dates
Expression Prefixes for Numeric Data Other Than Date and Time

96

Citrix NetScaler Policy Configuration and Reference Guide

Note: Numeric operations are also covered in “Compound Operations for
Numbers,” on page 48 and “Advanced Expressions: Parsing HTTP, TCP, and
UDP Data,” on page 113.

Format of Dates and Times in an Expression
When configuring an advanced expression in a policy that works with dates and
times, for example, the NetScaler system time or a date in an SSL certificate, you
specify a time format as follows:
GMT|LOCAL [yyyy] [month] [d] [h] [m] [s]

Where:
•

yyyy is a four-digit year after GMT or LOCAL.

•

month is a three-character abbreviation for the month, for example, Jan,
Dec.

•

d is a day of the week or an integer for the date.
You cannot specify the day as Monday, Tuesday, and so on. You specify
either an integer for a specific day of the month, or you specify a date as the
first, second, third weekday of the month, and so on. Following are
examples of specifying a day of the week:
•

Sun_1 is the first Sunday of the month.

•

Sun_3 is the third Sunday of the month.

•

Wed_3 is the third Wednesday of the month.

•

30 is an example of an exact date in a month.

•

h is the hour, for example, 10h.

•

s is the number of seconds, for example, 30s.

The following example expression is TRUE if the time is between10:00 a.m. and
5:30 p.m. local time, as determined from the time zone setting on the NetScaler.
(Note that not all local time zones are supported.):
http.req.date.between(GMT 2008 Jan, GMT 2009 Jan)

The following example expression is TRUE for March and all months that follow
March in the calendar year, based on GMT time:
sys.time.ge(GMT 2008 Mar)

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

97

When you specify a date and time, note that the format is case sensitive and must
preserve the exact number of blank spaces between entries.
Note: In an expression that requires two time values, both must use GMT or both
must use LOCAL. You cannot mix the two in an expression.

Dates and Times in a Rewrite Action
Unlike using the SYS.TIME prefix in an advanced policy expression, if you
specify SYS.TIME in a rewrite action, the NetScaler returns a string in
conventional date format (for example, Sun, 06 Nov 1994 08:49:37 GMT). For
example, the following rewrite action replaces the http.res.date header
with the NetScaler system time using a conventional date format:
add rewrite action sync_date replace http.res.date sys.time

Expressions for the NetScaler System Time
The SYS.TIME expression prefix extracts the Netscaler system time. You can
configure expressions that establish whether a particular event occurred at a
particular time or within a particular time range according to the NetScaler
system time.

98

Citrix NetScaler Policy Configuration and Reference Guide

The following table describes the available expressions that you can configure
using the SYS.TIME prefix and its associated operations.
Expressions that Return NetScaler System Dates and Times
NetScaler Time
Operation
SYS.TIME.
BETWEEN(time1,
time2)

Description
Returns a Boolean TRUE if the returned value is later than
time1 and earlier than time2.
You format the time1, time2 arguments as follows:
• They must both be GMT or both LOCAL.
• Time2 must be later than time1.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following:
• sys.time.between(GMT 2004, GMT 2006)
• sys.time.between(GMT 2004 Jan, GMT 2006
Nov)
• sys.time.between(GMT 2004 Jan, GMT 2006)
• sys.time.between(GMT 2005 May Sun_1, GMT
2005 May Sun_3)
• sys.time.between(GMT 2005 May 1, GMT May
2005 1)
• sys.time.between(LOCAL 2005 May 1, LOCAL
May 2005 1)

SYS.TIME.DAY

Returns the current day of the month as a number from 1
through 31.

SYS.TIME.EQ(time) Returns a Boolean TRUE if the current time is equal to the time

argument.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.eq(GMT 2005) (TRUE in this example.)
• sys.time.eq(GMT 2005 Dec) (FALSE in this
example.)
• sys.time.eq(LOCAL 2005 May) (Evaluates to
TRUE or FALSE in this example, depending on the current
time zone.)
• sys.time.eq(GMT 10h) (TRUE in this example.)
• sys.time.eq(GMT 10h 30s) (TRUE in this
example.)
• sys.time.eq(GMT May 10h) (TRUE in this
example.)
• sys.time.eq(GMT Sun) (TRUE in this example.)
• sys.time.eq(GMT May Sun_1) (TRUE in this
example.)

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

99

Expressions that Return NetScaler System Dates and Times
NetScaler Time
Operation

Description

SYS.TIME.GE(time) Returns a Boolean TRUE if the current time is later than or

equal to time.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.ge(GMT 2004) (TRUE in this example.)
• sys.time.ge(GMT 2005 Jan) (TRUE in this
example.)
• sys.time.ge(LOCAL 2005 May) (TRUE or FALSE
in this example, depending on the current time zone.)
• sys.time.ge(GMT 8h) (TRUE in this example.)
• sys.time.ge(GMT 30m) (FALSE in this example.)
• sys.time.ge(GMT May 10h) (TRUE in this
example.)
• sys.time.ge(GMT May 10h 0m) (TRUE in this
example.)
• sys.time.ge(GMT Sun) (TRUE in this example.)
• sys.time.ge(GMT May Sun_1) (TRUE in this
example.)
SYS.TIME.GT(time) Returns a Boolean TRUE if the time value is later than the time

argument.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.gt(GMT 2004) (TRUE in this example.)
• sys.time.gt(GMT 2005 Jan) (TRUE in this
example.)
• sys.time.gt(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone. )
• sys.time.gt(GMT 8h) (TRUE in this example.)
• sys.time.gt(GMT 30m) (FALSE in this example.)
• sys.time.gt(GMT May 10h) (FALSE in this
example.)
• sys.time.gt(GMT May 10h 0m) (TRUE in this
example.)
• sys.time.gt(GMT Sun) (FALSE in this example.)
• sys.time.gt(GMT May Sun_1) (FALSE in this
example.)
SYS.TIME.HOURS

Returns the current hour as an integer from 0 to 23.

100

Citrix NetScaler Policy Configuration and Reference Guide

Expressions that Return NetScaler System Dates and Times
NetScaler Time
Operation

Description

SYS.TIME.LE(time) Returns a Boolean TRUE if the current time value precedes or

is equal to the time argument.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.le(GMT 2006) (TRUE in this example.)
• sys.time.le(GMT 2005 Dec) (TRUE in this
example.)
• sys.time.le(LOCAL 2005 May) (TRUE or
FALSE depending on the current timezone. )
• sys.time.le(GMT 8h) (FALSE in this example.)
• sys.time.le(GMT 30m) (TRUE in this example.)
• sys.time.le(GMT May 10h) (TRUE in this
example.)
• sys.time.le(GMT Jun 11h) (TRUE in this
example.)
• sys.time.le(GMT Wed) (TRUE in this example.)
• sys.time.le(GMT May Sun_1) (TRUE in this
example.)
SYS.TIME.LT(time) Returns a Boolean TRUE if the current time value precedes the

time argument.
For example, if the current time is GMT 2005 May 1 10h 15m
30s, and it is the first Sunday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.lt(GMT 2006) (TRUE in this example.)
• sys.time.lt.time.lt(GMT 2005 Dec) (TRUE
in this example.)
• sys.time.lt(LOCAL 2005 May) (TRUE or
FALSE depending on the current time zone.)
• sys.time.lt(GMT 8h) (FALSE in this example.)
• sys.time.lt(GMT 30m) (TRUE in this example.)
• sys.time.lt(GMT May 10h) (FALSE in this
example.)
• sys.time.lt(GMT Jun 11h) (TRUE in this
example.)
• sys.time.lt(GMT Wed) (TRUE in this example.)
• sys.time.lt(GMT May Sun_1) (FALSE in this
example.)
SYS.TIME.MINUTES

Returns the current minute as an integer from 0 to 59.

SYS.TIME.MONTH

Extracts the current month and returns an integer from 1
(January) to 12 (December).

SYS.TIME.
RELATIVE_BOOT

Calculates the number of seconds to the closest previous or
scheduled reboot, and returns an integer.
If the closest boot time is in the past, the integer is negative. If it
is in the future, the integer is positive.

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

101

Expressions that Return NetScaler System Dates and Times
NetScaler Time
Operation
SYS.TIME.
RELATIVE_NOW

Description
Calculates the number of seconds between the current
NetScaler system time and the specified time, and returns an
integer showing the difference.
If the designated time is in the past, the integer is negative; if it
is in the future, the integer is positive.

SYS.TIME.SECONDS

Extracts the seconds from the current NetScaler system time,
and returns that value as an integer from 0 to 59.

SYS.TIME.WEEKDAY

Returns the current weekday as a value from 0 (Sunday) to 6
(Saturday).

SYS.TIME.WITHIN
(time1, time2)

Returns a Boolean TRUE if all time elements (day, hour, and so
on) exist within the range defined by time1, time2. If you
omit an element of time in time1, for example, the day or hour,
it is assumed to have the lowest value in its range. If you omit
an element in time2, it is assumed to have the highest value of
its range.
The ranges for the elements of time are as follows: month 1-12,
day 1-31, weekday 0-6, hour 0-23, minutes 0-59 and seconds 059. If you specify the year, you must do so in both time1 and
time2.
For example, if the time is GMT 2005 May 10 10h 15m 30s,
and it is the second Tuesday of the month, you can specify the
following (evaluation results are shown in parentheses):
• sys.time.within(GMT 2004, GMT 2006)
(TRUE in this example.)
• sys.time.within(GMT 2004 Jan, GMT 2006
Mar) (FALSE, May is not in the range of January to
March.)
• sys.time.within(GMT Feb, GMT) (TRUE, May
is in the range of February to December.)
• sys.time.within(GMT Sun_1, GMT Sun_3)
(TRUE, the second Tuesday is between the first Sunday
and the third Sunday.)
• sys.time.within(GMT 2005 May 1 10h, GMT
May 2005 1 17h) (TRUE in this example.)
• sys.time.within(LOCAL 2005 May 1, LOCAL
May 2005 1) (TRUE or FALSE, depending on the
NetScaler system time zone.)

SYS.TIME.YEAR

Extracts the year from the current system time and returns that
value as a four-digit integer.

Expressions for SSL Certificate Dates
You can determine the validity period for SSL certificates by configuring an
expression that contains the following prefix:

102

Citrix NetScaler Policy Configuration and Reference Guide

CLIENT.SSL.CLIENT_CERT

The following example expression matches a particular time for expiration with
the information in the certificate:
client.ssl.client_cert.valid_not_after.eq(GMT 2009)

The following table describes time-based operations on SSL certificates.
Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation

Description

certificate.
VALID_NOT_AFTER

Returns the last day before certificate expiration. The
return format is the number of seconds since GMT
January 1, 1970 (0 hours, 0 minutes, 0 seconds).

certificate.
VALID_NOT_AFTER.
BETWEEN(time1, time2)

Returns a Boolean TRUE value if the certificate validity
is between the time1 and time2 arguments. Both time1
and time2 must be fully specified. Following are
examples:
• GMT 1995 Jan is fully specified.
• GMT Jan is not fully specified
• GMT 1995 20 is not fully specified.
• GMT Jan Mon_2 is not fully specified.
The time1 and time2 arguments must be both GMT or
both LOCAL, and time2 must be bigger than time1.
For example, if it is GMT 2005 May 1 10h 15m 30s,
and the first Sunday of the month, you can specify the
following (evaluation results are in parentheses).
• . . .between(GMT 2004, GMT 2006)
(TRUE)
• . . .between(GMT 2004 Jan, GMT 2006
Nov) (TRUE)
• . . .between(GMT 2004 Jan, GMT
2006) (TRUE)
• . . .between(GMT 2005 May Sun_1,
GMT 2005 May Sun_3) (TRUE)
• . . .between(GMT 2005 May 1, GMT
May 2005 1) (TRUE)
• . . .between(LOCAL 2005 May 1,
LOCAL May 2005 1) (TRUE or FALSE,
depending on the NetScaler system time zone.)

certificate.
VALID_NOT_AFTER.DAY

Extracts the last day of the month that the certificate is
valid, and returns a number from 1 through 31, as
appropriate for the date.

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

103

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation
certificate.
VALID_NOT_AFTER.
EQ(time)

Description
Returns a Boolean TRUE if the time is equal to the time
argument.
For example, if the current time is GMT 2005 May 1
10h 15m 30s, and it is the first Sunday of the month,
you can specify the following (evaluation results for
this example are in parentheses):
• . . .eq(GMT 2005) (TRUE)
• . . .eq(GMT 2005 Dec) (FALSE)
• . . .eq(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone)
• . . .eq(GMT 10h) (TRUE)
• . . .eq(GMT 10h 30s) (TRUE)
• . . .eq(GMT May 10h) (TRUE)
• . . .eq(GMT Sun) (TRUE)
• . . .eq(GMT May Sun_1) (TRUE)

certificate.
VALID_NOT_AFTER.
GE(time)

Returns a Boolean TRUE if the time value is greater
than or equal to the argument time.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .ge(GMT 2004) (TRUE)
• . . .ge(GMT 2005 Jan) (TRUE)
• . . .ge(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .ge(GMT 8h) (TRUE)
• . . .ge(GMT 30m) (FALSE)
• . . .ge(GMT May 10h) (TRUE)
• . . .ge(GMT May 10h 0m) (TRUE)
• . . .ge(GMT Sun) (TRUE)
• . . .ge(GMT May Sun_1) (TRUE)

certificate.
VALID_NOT_AFTER.
GT(time)

Returns a Boolean TRUE if the time value is greater
than the argument time.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .gt(GMT 2004) (TRUE)
• . . .gt(GMT 2005 Jan) (TRUE)
• . . .gt(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .gt(GMT 8h) (TRUE)
• . . .gt(GMT 30m) (FALSE)
• . . .gt(GMT May 10h) (FALSE)
• . . .gt(GMT Sun) (FALSE)
• . . .gt(GMT May Sun_1) (FALSE)

104

Citrix NetScaler Policy Configuration and Reference Guide

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation

Description

certificate.
VALID_NOT_AFTER.HOURS

Extracts the last hour that the certificate is valid and
returns that value as an integer from 0 to 23.

certificate.
VALID_NOT_AFTER.
LE(time)

Returns a Boolean TRUE if the time precedes or is
equal to the time argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .le(GMT 2006) (TRUE)
• . . .le(GMT 2005 Dec) (TRUE)
• . . .le(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .le(GMT 8h) (FALSE)
• . . .le(GMT 30m) (TRUE)
• . . .le(GMT May 10h) (TRUE)
• . . .le(GMT Jun 11h) (TRUE)
• . . .le(GMT Wed) (TRUE)
• . . .le(GMT May Sun_1) (TRUE)

certificate.
VALID_NOT_AFTER.
LT(time)

Returns a Boolean TRUE if the time precedes the time
argument.
For example, if the current time is GMT 2005 May 1
10h 15m 30s, and it is the first Sunday of the month,
you can specify the following:
• . . .lt(GMT 2006) (TRUE)
• . . .lt(GMT 2005 Dec) (TRUE)
• . . .lt(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .lt(GMT 8h) (FALSE)
• . . .lt(GMT 30m) (TRUE)
• . . .lt(GMT May 10h) (FALSE)
• . . .lt(GMT Jun 11h) (TRUE)
• . . .lt(GMT Wed) (TRUE)
• . . .lt(GMT May Sun_1) (FALSE)

certificate.
Extracts the last minute that the certificate is valid and
VALID_NOT_AFTER.MINUTES returns that value as an integer from 0 to 59.
certificate.
VALID_NOT_AFTER.MONTH

Extracts the last month that the certificate is valid and
returns that value as an integer from 1 (January) to 12
(December).

certificate.
VALID_NOT_AFTER.
RELATIVE_BOOT

Calculates the number of seconds to the closest
previous or scheduled reboot and returns an integer. If
the closest boot time is in the past, the integer is
negative. If it is in the future, the integer is positive.

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

105

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation
certificate.
VALID_NOT_AFTER.
RELATIVE_NOW

Description
Calculates the number of seconds between the current
system time and the specified time and returns an
integer. If the time is in the past, the integer is negative;
if it is in the future, the integer is positive.

certificate.
Extracts the last second that the certificate is valid and
VALID_NOT_AFTER.SECONDS returns that value as an integer from 0 to 59.
certificate.
Extracts the last weekday that the certificate is valid.
VALID_NOT_AFTER.WEEKDAY Returns a number between 0 (Sunday) and 6 (Saturday)

to give the weekday in the time value.
certificate.
VALID_NOT_AFTER.
WITHIN(time1, time2)

Returns a Boolean TRUE if the time lies within all the
ranges defined by the elements in time1, time2.
If you omit an element of time from time1, it is assumed
to have the lowest value in its range. If you omit an
element from time2, it is assumed to have the highest
value of its range. If you specify a year in time1, you
must specify it in time2.
The ranges for elements of time are as follows: month
1-12, day 1-31, weekday 0-6, hour 0-23, minutes 0-59
and seconds 0-59. For the result to be TRUE, each
element in the time must exist in the corresponding
range that you specify in time1, time2.
For example, if time is GMT 2005 May 10 10h 15m
30s, and it is the second Tuesday of the month, you can
specify the following (evaluation results are in
parentheses):
• . . .within(GMT 2004, GMT 2006)
(TRUE)
• . . .within(GMT 2004 Jan, GMT 2006
Mar) (FALSE, May is not in the range of January
to March.)
• . . .within(GMT Feb, GMT) (TRUE, May
is in the range for February to December)
• . . .within(GMT Sun_1, GMT Sun_3)
(TRUE, the second Tuesday lies within the range of
the first Sunday through the third Sunday)
• . . .within(GMT 2005 May 1 10h, GMT
May 2005 1 17h) (TRUE)
• . . .within(LOCAL 2005 May 1, LOCAL
May 2005 1) (TRUE or FALSE, depending on
the NetScaler system time zone)

certificate.
VALID_NOT_AFTER.YEAR

Extracts the last year that the certificate is valid and
returns a four-digit integer.

certificate.
VALID_NOT_BEFORE

Returns the date that the client certificate becomes
valid.
The return format is the number of seconds since GMT
January 1, 1970 (0 hours, 0 minutes, 0 seconds).

106

Citrix NetScaler Policy Configuration and Reference Guide

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation
certificate.
VALID_NOT_BEFORE.
BETWEEN(time1, time2)

Description
Returns a Boolean TRUE if the time value is between
the time1, time2 arguments. Both the time1, time2
arguments must be fully specified.
Following are examples:
• GMT 1995 Jan is fully specified.
• GMT Jan is not fully specified.
• GMT 1995 20 is not fully specified.
• GMT Jan Mon_2 is not fully specified.
The time1, time2 arguments must be both GMT or both
LOCAL, and time2 must be bigger than time1.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .between(GMT 2004, GMT 2006)
(TRUE)
• . . .between(GMT 2004 Jan, GMT 2006
Nov) (TRUE)
• . . .between(GMT 2004 Jan, GMT
2006) (TRUE)
• . . .between(GMT 2005 May Sun_1,
GMT 2005 May Sun_3) (TRUE)
• . . .between(GMT 2005 May 1, GMT
May 2005 1) (TRUE)
• . . .between(LOCAL 2005 May 1,
LOCAL May 2005 1) (TRUE or FALSE,
depending on the NetScaler system time zone.)

certificate.
VALID_NOT_BEFORE.DAY

Extracts the last day of the month that the certificate is
valid and returns that value as a number from 1 through
31 representing that day.

certificate.
VALID_NOT_BEFORE.
EQ(time)

Returns a Boolean TRUE if the time is equal to the time
argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .eq(GMT 2005) (TRUE)
• . . .eq(GMT 2005 Dec) (FALSE)
• . . .eq(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .eq(GMT 10h) (TRUE)
• . . .eq(GMT 10h 30s) (TRUE)
• . . .eq(GMT May 10h) (TRUE)
• . . .eq(GMT Sun) (TRUE)
• . . .eq(GMT May Sun_1) (TRUE)

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

107

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation
certificate.
VALID_NOT_BEFORE.
GE(time)

Description
Returns a Boolean TRUE if the time is greater than
(after) or equal to the time argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results are in parentheses):
• . . .ge(GMT 2004) (TRUE)
• . . .ge(GMT 2005 Jan) (TRUE)
• . . .ge(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .ge(GMT 8h) (TRUE)
• . . .ge(GMT 30m) (FALSE)
• . . .ge(GMT May 10h) (TRUE)
• . . .ge(GMT May 10h 0m) (TRUE)
• . . .ge(GMT Sun) (TRUE)
• . . .ge(GMT May Sun_1) (TRUE)

certificate.
VALID_NOT_BEFORE.
GT(time)

Returns a Boolean TRUE if the time occurs after the
time argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results are in parentheses):
• . . .gt(GMT 2004) (TRUE)
• . . .gt(GMT 2005 Jan) (TRUE)
• . . .gt(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .gt(GMT 8h) (TRUE)
• . . .gt(GMT 30m) (FALSE)
• . . .gt(GMT May 10h) (FALSE)
• . . .gt(GMT May 10h 0m) (TRUE)
• . . .gt(GMT Sun) (FALSE)
• . . .gt(GMT May Sun_1) (FALSE)

certificate.
VALID_NOT_BEFORE.HOURS

Extracts the last hour that the certificate is valid and
returns that value as an integer from 0 to 23.

108

Citrix NetScaler Policy Configuration and Reference Guide

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation
certificate.
VALID_NOT_BEFORE.
LE(time)

Description
Returns a Boolean TRUE if the time precedes or is
equal to the time argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .le(GMT 2006) (TRUE)
• . . .le(GMT 2005 Dec) (TRUE)
• . . .le(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .le(GMT 8h) (FALSE)
• . . .le(GMT 30m) (TRUE)
• . . .le(GMT May 10h) (TRUE)
• . . .le(GMT Jun 11h) (TRUE)
• . . .le(GMT Wed) (TRUE)
• . . .le(GMT May Sun_1) (TRUE)

certificate.
VALID_NOT_BEFORE.
LT(time)

Returns a Boolean TRUE if the time precedes the time
argument.
For example, if the time value is GMT 2005 May 1 10h
15m 30s, and it is the first Sunday of the month of May
in 2005, you can specify the following (evaluation
results for this example are in parentheses):
• . . .lt(GMT 2006) (TRUE)
• . . .lt(GMT 2005 Dec) (TRUE)
• . . .lt(LOCAL 2005 May) (TRUE or
FALSE, depending on the current time zone.)
• . . .lt(GMT 8h) (FALSE)
• . . .lt(GMT 30m) (TRUE)
• . . .lt(GMT May 10h) (FALSE)
• . . .lt(GMT Jun 11h) (TRUE)
• . . .lt(GMT Wed) (TRUE)
• . . .lt(GMT May Sun_1) (FALSE)

certificate.
VALID_NOT_BEFORE.
MINUTES

Extracts the last minute that the certificate is valid.
Returns the current minute as an integer from 0 to 59.

certificate.
VALID_NOT_BEFORE.MONTH

Extracts the last month that the certificate is valid.
Returns the current month as an integer from 1
(January) to 12 (December).

certificate.
VALID_NOT_BEFORE.
RELATIVE_BOOT

Calculates the number of seconds to the closest
previous or scheduled NetScaler reboot and returns an
integer. If the closest boot time is in the past, the integer
is negative; if it is in the future, the integer is positive.

certificate.
VALID_NOT_BEFORE.
RELATIVE_NOW

Returns the number of seconds between the current
NetScaler system time and the specified time as an
integer. If the designated time is in the past, the integer
is negative. If it is in the future, the integer is positive.

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

109

Operations on Certificate (client.ssl.client_cert) Dates and Times
SSL Certificate Operation

Description

certificate.
VALID_NOT_BEFORE.
SECONDS

Extracts the last second that the certificate is valid.
Returns the current second as an integer from 0 to 59.

certificate.
VALID_NOT_BEFORE.
WEEKDAY

Extracts the last weekday that the certificate is valid.
Returns the weekday as a number between 0 (Sunday)
and 6 (Saturday).

certificate.
VALID_NOT_BEFORE.
WITHIN(time1, time2)

Returns a Boolean TRUE if each element of time exists
within the range defined in the time1, time2 arguments.
If you omit an element of time from time1, it is assumed
to have the lowest value in its range. If you omit an
element of time from time2, it is assumed to have the
highest value in its range. If you specify a year in time1,
it must be specified in time2. The ranges for elements of
time are as follows: month 1-12, day 1-31, weekday 06, hour 0-23, minutes 0-59 and seconds 0-59.
For example, if the time is GMT 2005 May 10 10h 15m
30s, and it is the second Tuesday of the month, you can
specify the following (evaluation results are in
parentheses):
• . . .within(GMT 2004, GMT 2006)
(TRUE)
• . . .within(GMT 2004 Jan, GMT 2006
Mar) (FALSE, May is not in the range of January
to March.)
• . . .within(GMT Feb, GMT) (TRUE, May
is in the range of February to December.)
• . . .within(GMT Sun_1, GMT Sun_3)
(TRUE, the second Tuesday is between the first
Sunday and the third Sunday.)
• . . .within(GMT 2005 May 1 10h, GMT
May 2005 1 17h) (TRUE)
• . . .within(LOCAL 2005 May 1, LOCAL
May 2005 1) (TRUE or FALSE, depending on
the NetScaler system time zone)

certificate.
VALID_NOT_BEFORE.YEAR

Extracts the last year that the certificate is valid. Returns
the current year as a four-digit integer.

110

Citrix NetScaler Policy Configuration and Reference Guide

Expressions for HTTP Request and Response Dates
The following expression prefixes return the contents of the HTTP Date header as
text or as a date object.
Prefixes That Evaluate HTTP Date Headers
Prefix
HTTP.REQ.DATE

Description
Returns the contents of the HTTP Date header as
text or as a date object.The date formats
recognized are:
RFC822. Sun, 06 Jan 1980 08:49:37 GMT
RFC850. Sunday, 06-Jan-80 09:49:37 GMT
ASCTIME. Sun Jan 6 08:49:37 1980

HTTP.RES.DATE

Returns the contents of the HTTP Date header as
text or as a date object.The date formats
recognized are:
RFC822. Sun, 06 Jan 1980 8:49:37 GMT
RFC850. Sunday, 06-Jan-80 9:49:37 GMT
ASCTIME. Sun Jan 6 08:49:37 1980

These values can be evaluated as follows:
•

As a number. The numeric value of an HTTP Date header is returned in the
form of the number of seconds since Jan 1 1970.
For example, the expression http.req.date.mod(86400) returns
the number of seconds since the beginning of the day. These values can be
evaluated using the same operations as other non-date-related numeric data.
For more information, see “Expression Prefixes for Numeric Data Other
Than Date and Time,” on page 111.

•

As an HTTP header. Date headers can be evaluated using the same
operations as other HTTP headers.
For more information, see “Advanced Expressions: Parsing HTTP, TCP,
and UDP Data,” on page 113.

•

As text. Date headers can be evaluated using the same operations as other
strings.
For more information, see “Advanced Expressions: Evaluating Text,” on
page 63.

Chapter 5

Advanced Expressions: Working with Dates, Times, and Numbers

111

Expression Prefixes for Numeric Data Other Than Date
and Time
In addition to expressions that operate on time, you can configure expressions for
the following types of numeric data:
•

The length of HTTP requests, the number of HTTP headers in a request,
and so on.
For more information, see “Expressions for Numeric HTTP Payload Data
Other Than Dates,” on page 130.

•

IP and MAC addresses.
For more information, see “Expressions for IP Addresses and IP Subnets,”
on page 149.

•

Client and server data in regard to interface IDs and transaction throughput
rate.
For more information, see “Expressions for Numeric Client and Server
Data,” on page 155.

•

Numeric data in client certificates other than dates.
For information on these prefixes, including the number of days until
certificate expiration and the encryption key size, see “Prefixes for Numeric
Data in SSL Certificates,” on page 143.

112

Citrix NetScaler Policy Configuration and Reference Guide

C HAPTER 6

Advanced Expressions: Parsing
HTTP, TCP, and UDP Data

You can configure advanced expressions to parse the payload for HTTP requests
and responses, including headers and body content. For example, you can ensure
that an HTTP request or response contains a header of a particular type, or you
can extract a particular segment from a URL path. You can also configure
expressions to transform the URL encoding and apply HTML or XML “safe”
coding for subsequent evaluation.
Similarly, you can analyze the payload in a TCP or UDP packet using an
advanced expression. For example, you can extract the source or destination port
and evaluate DNS record types.
In This Chapter
About Evaluating HTTP and TCP Payload
Expressions for HTTP Headers
Expressions for Extracting Segments of URLs
Expressions for Numeric HTTP Payload Data Other Than Dates
Operations for HTTP, HTML, and XML Encoding and “Safe” Characters
Expressions for TCP, UDP, and VLAN Data
XPath and JSON Expressions
Note: You can also use text-based and numeric advanced expressions to
evaluate HTTP request and response data. For more information, see “Advanced
Expressions: Evaluating Text,” on page 63 and “Advanced Expressions: Working
with Dates, Times, and Numbers,” on page 95.

114

Citrix NetScaler Policy Configuration and Reference Guide

About Evaluating HTTP and TCP Payload
The payload of an HTTP request or response consists of header fields, URLs, the
body content, the version, status, and so on. For example, the following
expression performs a simple matching operation on an HTTP request to
determine if it contains a header named “myHeader”:
http.req.header("myHeader").exists

The following example compound expression evaluates HTTP headers. You
could use the following expression in various NetScaler features, such as
Integrated Caching, Rewrite, and Responder:
(http.req.header("Content-Type").exists && http.req.
header("Content-Type").eq("text/html")) || (http.req.
header("Transfer-Encoding").exists) || (http.req.
header("Content-Length").exists)

The payload of a TCP or UDP packet is the data portion of the packet. You can
configure advanced expressions to examine features of a TCP or UDP packet,
including the following:
•

Source and destination domains

•

Source and destination ports

•

The text in the payload

•

Record types

About Evaluating the Payload Body
There are three expression prefixes that extract text from the body of the payload,
as follows:
•

HTTP.REQ.BODY(integer). Returns the body of an HTTP request as
a multiline text object, up to the character position designated in the integer
argument. If there are fewer characters in the body than is specified in the
argument, the entire body is returned.

•

HTTP.RES.BODY(integer). Returns a portion of the HTTP response
body. The length of the returned text is equal to the number in the integer
argument. If there are fewer characters in the body than is specified in
integer, the entire body is returned.

•

CLIENT.TCP.PAYLOAD(integer). Returns TCP payload data as a
string, starting with the first character in the payload and continuing for the
number of characters in the integer argument.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

115

Following is an example that evaluates to TRUE if a response body of 1024 bytes
contains the string “https”, and this string occurs after the string “start string” and
before the string “end string”:
http.res.body(1024).after_str("start_string").before_str("end_
string").contains("https")

Note: You can apply any text operation to the payload body. For information on
operations that you can apply to text, see “Advanced Expressions: Evaluating
Text,” on page 63.

Expressions for HTTP Headers
One common method of evaluating HTTP traffic is to examine the headers in a
request or a response. A header can perform a number of functions, including the
following:
•

Provide cookies that contain data about the sender.

•

Identify the type of data that is being transmitted.

•

Identify the route that the data has traveled (the Via header).

As noted in the section “About Evaluating HTTP and TCP Payload,” on page
114, the EXISTS operation identifies if a request or a response contains a
particular object. Following is a request-time example that determines if a
particular header type exists:
http.req.header("myHeader").exists

You can configure expressions to identify almost any data in a header, including
header types and values, and almost any type of information in a Cookie header.
Note: Note that if the same operation is used to evaluate header and text data,
the header-based operation always overrides any text-based operation.

116

Citrix NetScaler Policy Configuration and Reference Guide

Prefixes for HTTP Headers
The following table describes expression prefixes that extract HTTP headers.
Prefixes That Extract HTTP Headers
HTTP Header Prefix

Description

HTTP.REQ.HEADER("header_name") Returns the contents of the HTTP header

specified by the header_name argument. The
header name cannot exceed 32 characters.
Note that this prefix returns the value from the
Host header by default. To use this value as a
host name you need to typecast it as follows:
http.req.header("host").typecast_
http_hostname_t

For more information on typecasting, see
“Transforming Text and Numbers into
Different Data Types,” on page 169.
HTTP.REQ.FULL_HEADER("header_
name")

Returns the contents of the HTTP header
specified by the header_name argument,
including the terminating \r\n\r\n. The
header name cannot exceed 32 characters.

HTTP.REQ.DATE

Returns the contents of the HTTP Date
header.The following date formats are
recognized:
RFC822. Sun, 06 Jan 1980 8:49:37 GMT
RFC850. Sunday, 06-Jan-80 9:49:37 GMT
ASCII TIME. Sun Jan 6 08:49:37 1980
To evaluate a Date header as a date object, see
“Advanced Expressions: Working with
Dates, Times, and Numbers,” on page 95.

HTTP.REQ.COOKIE

(Name/Value List) Returns the contents of the
HTTP Cookie header.

HTTP.REQ.TXID

Returns the HTTP transaction ID. The value
is a function of an internal transaction
number, system boot time and system MAC
address.

HTTP.RES.HEADER("header_name") Returns the contents of the HTTP header

specified by the header_name argument. The
header name cannot exceed 32 characters.
HTTP.RES.FULL_HEADER("header_
name")

Returns the contents of the HTTP header
specified by the header_name argument,
including the terminating \r\n\r\n. The
header name cannot exceed 32 characters.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

117

Prefixes That Extract HTTP Headers
HTTP Header Prefix
HTTP.RES.SET_COOKIE

or

Description
Returns the HTTP Set-Cookie header object
in a response.

HTTP.RES.SET_COOKIE2
HTTP.RES.SET_COOKIE("name")

or
HTTP.RES.SET_COOKIE2("name")

HTTP.RES.SET_COOKIE("name").
DOMAIN

or
HTTP.RES.SET_COOKIE2("name").
DOMAIN

Returns the cookie of the specified name if it
is present. If it is not present, returns a text
object of length 0. Returns UNDEF if more
than 15 Set-Cookie headers are present and
the specified cookie was not found in these
headers.
Returns the value of the first Domain field in
the cookie. For example, if the cookie is SetCookie : Customer = "ABC"; DOMAIN=".
abc.com"; DOMAIN=.xyz.com, the
following expression returns .abc.com:
http.res.set_cookie.
cookie("customer").domain

A string of zero length is returned if the
Domain field or its value is absent.
HTTP.RES.SET_COOKIE.
EXISTS("name")
or
HTTP.RES.SET_COOKIE2.
EXISTS("name")
HTTP.RES.SET_COOKIE.
COOKIE("name").EXPIRES

or
HTTP.RES.SET_COOKIE2.
COOKIE("name").EXPIRES

Returns a Boolean TRUE if a Cookie with the
name specified in the name argument exists in
the Set-Cookie header.
This prefix returns UNDEF if more than 15
Set-Cookie headers are present and the named
cookie is not in the first 15 headers.
Returns the Expires field of the cookie. This is
a date string that can be evaluated as a
number, as a time object, or as text. If multiple
Expires fields are present, the first one is
returned. If the Expires field is absent, a text
object of length zero is returned.
To evaluate the returned value as a time
object, see “Advanced Expressions: Working
with Dates, Times, and Numbers,” on page
95.

118

Citrix NetScaler Policy Configuration and Reference Guide

Prefixes That Extract HTTP Headers
HTTP Header Prefix
HTTP.RES.SET_COOKIE.
COOKIE("name").PATH|PATH.
GET(n)

or
HTTP.RES.SET_COOKIE2.
COOKIE("name").PATH|PATH.
GET(n)

Description
Returns the value of Path field of the cookie
as a slash- (“/”) separated list. Multiple
instances of a slash are treated as single slash.
If multiple Path fields are present, the value of
the first instance is returned.
For example, the following is a cookie with
two path fields:
Set-Cookie : Customer = "ABC";
PATH="/a//b/c"; PATH= "/x/y/z"

The following expression returns /a//b/c from
this cookie:
http.res.set_cookie.
cookie("Customer").path

The following expression returns b:
http.res.set_cookie.
cookie("Customer").path.get(2)

Quotes are stripped from the returned value.
A string of zero length is returned if the Path
field or its value is absent.
HTTP.RES.SET_COOKIE.
COOKIE("name").PATH.IGNORE_
EMPTY_ELEMENTS

or
HTTP.RES.SET_COOKIE2.
COOKIE("name").PATH.IGNORE_
EMPTY_ELEMENTS

Ignores the empty elements in the list. For
example, in the list a=10,b=11, ,c=89, the
element delimiter in the list is , and the list has
an empty element following a=10. The
element following b=11 is not considered an
empty element.
As another example, in the following
expression, if a request contains Cust_Header
: 123,,24, ,15 the following expression returns
a value of 4:
http.req.header("Cust_Header").
typecast_list_t(',').ignore_
empty_elements.count

The following expression returns a value of 5:
http.req.header("Cust_Header").
typecast_list_t(',').count

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

119

Prefixes That Extract HTTP Headers
HTTP Header Prefix

Description

HTTP.RES.SET_COOKIE.
COOKIE("name").PORT

Returns the value of Port field of the cookie.
Operate as a comma-separated list.

or

For example, the following expression returns
80. 2580 from Set-Cookie : Customer =
"ABC"; PATH="/a/b/c"; PORT= "80, 2580":

HTTP.RES.SET_COOKIE2.
COOKIE("name").PORT

http.res.set_cookie.
cookie("ABC").port

A string of zero length is returned if the Port
field or value is absent.
HTTP.RES.SET_COOKIE.
COOKIE("name").PORT.IGNORE_
EMPTY_ELEMENTS

or
HTTP.RES.SET_COOKIE2.
COOKIE("name").PORT.IGNORE_
EMPTY_ELEMENTS

Ignores the empty elements in the list. For
example, in the list a=10,b=11, ,c=89, the
element delimiter in the list is , and the list has
an empty element following a=10. The
element following b=11 is not considered an
empty element.
As another example, in the following
expression, if a request contains Cust_Header
: 123,,24, ,15 the following expression returns
a value of 4:
http.req.header("Cust_Header").
typecast_list_t(',').ignore_
empty_elements.count

The following expression returns a value of 5:
http.req.header("Cust_Header").
typecast_list_t(',').count
HTTP.RES.SET_COOKIE.
COOKIE("name").VERSION

Returns the value of the first Version field in
the cookie as a decimal integer.

or

For example, the following expression returns
1 from the cookie Set-Cookie : Customer =
"ABC"; VERSION = "1"; VERSION = "0"

HTTP.RES.SET_COOKIE2.
COOKIE("name").VERSION

http.res.set_cookie.
cookie("CUSTOMER").version

A zero is returned if the Version field or its
value is absent or if the value is not a decimal
number.
HTTP.RES.SET_COOKIE.
COOKIE("name", integer)

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer)

Returns the nth instance (0-based) of the
cookie with the specified name. If the cookie
is absent, returns a text object of length 0.
Returns UNDEF if more than 15 Set-Cookie
headers are present and the cookie is not
found.

120

Citrix NetScaler Policy Configuration and Reference Guide

Prefixes That Extract HTTP Headers
HTTP Header Prefix

Description

HTTP.RES.SET_COOKIE.
Returns the value of the Domain field of the
COOKIE("name", integer).DOMAIN first cookie with the specified name. For

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).DOMAIN

example, the following expression returns a
value of abc.com from the cookie Set-Cookie
: Customer = "ABC"; DOMAIN=".abc.com";
DOMAIN=.xyz.com
http.res.set_cookie.
cookie("CUSTOMER").domain

A string of zero length is returned if the
Domain field or its value is absent.
HTTP.RES.SET_COOKIE.
COOKIE("name", integer).
EXPIRES

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).
EXPIRES

Returns the nth instance (0-based) of the
Expires field of the cookie with the specified
name as a date string. The value can be
operated upon as a time object that supports a
number of date formats. If the Expires
attribute is absent a string of length zero is
returned.

HTTP.RES.SET_COOKIE.
Returns the value of the Path field of the nth
COOKIE("name", integer).PATH | cookie, as a '/' separated list. Multiple /s are
treated as a single /.
PATH.GET(i)

or

For example, the following expression returns
/a//b/c from the cookie Set-Cookie : Customer
= "ABC"; PATH="/a//b/c"; PATH= "/x/y/z"

HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).PATH |
http.res.set_cookie.
PATH.GET(i)
cookie("CUSTOMER").path

The following returns b:
http.res.set_cookie.
cookie("CUSTOMER").path.get(2)

A string of zero length is returned if the Path
field or its value is absent.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

121

Prefixes That Extract HTTP Headers
HTTP Header Prefix
HTTP.RES.SET_COOKIE.
COOKIE("name", integer).PATH.
IGNORE_EMPTY_ELEMENTS

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).PATH.
IGNORE_EMPTY_ELEMENTS

Description
Ignores the empty elements in the list. For
example, in the list a=10,b=11, ,c=89, the
element delimiter in the list is , and the list has
an empty element following a=10. The
element following b=11 is not considered an
empty element.
As another example, in the following
expression, if a request contains Cust_Header
: 123,,24, ,15 the following expression returns
a value of 4:
http.req.header("Cust_Header").
typecast_list_t(',').ignore_
empty_elements.count

The following expression returns a value of 5:
http.req.header("Cust_Header").
typecast_list_t(',').count
HTTP.RES.SET_COOKIE.
COOKIE("name", integer).PORT

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).PORT

Returns the value or values of the Port field of
the named cookie as a ',' separated list. For
example, the following expression returns 80,
2580 from the cookie Set-Cookie : Customer
= "ABC"; PATH="/a/b/c"; PORT= "80, 2580"
http.res.set_cookie.
cookie("ABC").port

A string of zero length is returned if the Port
field or its value is absent.
HTTP.RES.SET_COOKIE.
COOKIE("name", integer).PORT.
IGNORE_EMPTY_ELEMENTS

or
HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).PORT.
IGNORE_EMPTY_ELEMENTS

Ignores the empty elements in the list. For
example, in the list a=10,b=11, ,c=89, the
element delimiter in the list is , and the list has
an empty element following a=10. The
element following b=11 is not considered an
empty element.
As another example, in the following
expression, if a request contains Cust_Header
: 123,,24, ,15 the following expression returns
a value of 4:
http.req.header("Cust_Header").
typecast_list_t(',').ignore_
empty_elements.count

The following expression returns a value of 5:
http.req.header("Cust_Header").
typecast_list_t(',').count

122

Citrix NetScaler Policy Configuration and Reference Guide

Prefixes That Extract HTTP Headers
HTTP Header Prefix
HTTP.RES.SET_COOKIE.
COOKIE("name", integer).
VERSION

or

Description
Returns the value of Version field of the nth
cookie as a decimal integer.
A string of zero length is returned if the Port
field or its value is absent.

HTTP.RES.SET_COOKIE2.
COOKIE("name", integer).
VERSION
HTTP.RES.TXID

Returns the HTTP transaction ID. The value
is a function of an internal transaction
number, system boot time and system MAC
address.

Operations for HTTP Headers
The following table describes operations that you can specify with the prefixes
for HTTP headers.
Note that if the same operation is also used to evaluate text, the header-based
operation always overrides any text-based operation. For example, the AFTER_
STR operation, when applied to a header, overrides text-based AFTER_STR
operations for all instances of the current header type.
Operations That Evaluate HTTP Headers
HTTP Header Operation
http header.EXISTS

Description
Returns a Boolean TRUE if an instance of the specified
header type exists.
Following is an example:
http.req.header("Cache-Control").exists

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

123

Operations That Evaluate HTTP Headers
HTTP Header Operation
http header.
CONTAINS("string")

Description
Returns a Boolean TRUE if the string argument appears
in any instance of the header value.
Note: This operation overrides any text-based Contains
operations on all instances of the current header type.
Following is an example of request with two headers:
HTTP/1.1 200 OK\r\n
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n

The following returns a Boolean TRUE:
http.res.header("MyHeader").
contains("de")

The following returns FALSE. Note that the NetScaler
does not concatenate the different values.
http.res.header("MyHeader").
contains("bcd")
http header.COUNT

Returns the number of headers in a request or response,
to a maximum of 15 headers of the same type. The
result is undefined if there are more than 15 instances of
the header.
Following is sample data in a request:
HTTP/1.1 200 OK\r\n
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n

When evaluating the preceding request, the following
returns a count of 2:
http.res.header("MyHeader").count

124

Citrix NetScaler Policy Configuration and Reference Guide

Operations That Evaluate HTTP Headers
HTTP Header Operation

Description

http header.AFTER_

Extracts the text that follows the first occurrence of the
string argument.The headers are evaluated from the last
instance to the first.

STR("string")

Following is an example of a request:
HTTP/1.1 200 OK\r\n
MyHeader: 111abc\r\n
Content-Length: 200\r\n
MyHeader: 111def\r\n
\r\n

The following extracts the string "def" from the last
instance of MyHeader. This is value "111def".
http.res.header("MyHeader").after_
str("111")

The following extracts the string "c" from the first
instance of MyHeader. This is the value "abc111".
http.res.header("MyHeader").after_
str("1ab")
http header.BEFORE_

STR("string")

Extracts the text that appears prior to the first
occurrence of the input string argument.The headers are
evaluated from the last instance to the first.
Following is an example of a request that contains
headers:
HTTP/1.1 200 OK\r\n
MyHeader: abc111\r\n
Content-Length: 200\r\n
MyHeader: def111\r\n
\r\n

The following extracts the string "def" from the last
instance of MyHeader. This is the value "def111".
http.res.header("MyHeader").before_
str("111")

The following extracts the string "a" from the first
instance of MyHeader. This is the value "abc111".
http.res.header("MyHeader").before_
str("bc1")

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

125

Operations That Evaluate HTTP Headers
HTTP Header Operation
http header.
INSTANCE(instance
number)

Description
An HTTP header can occur multiple times in a request
or a response. This operation returns the header that
occurs instance number of places before the final
instance. For example, instance(0) selects the last
instance of the current type, instance(1) selects the
next-to-last instance, and so on. This prefix cannot be
used in bidirectional policies.
The instance number argument cannot exceed 14.
Following is an example of a request with two headers:
HTTP/1.1 200 OK\r\n
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n

The following returns a text object that refers to
"MyHeader: abc\r\n":
http.res.header("MyHeader").instance(1)
http header.
SUBSTR("string")

Extracts the text that matches the string argument. The
headers are evaluated from the last instance to the first.
Following is an example of a request with two headers
that contain the string “111”:
HTTP/1.1 200 OK\r\n
MyHeader: abc111\r\n
Content-Length: 200\r\n
MyHeader: 111def\r\n
\r\n

The following returns "111" from the last instance of
MyHeader. This is the header with the value "111def".
http.res.header("MyHeader").
substr("111")

126

Citrix NetScaler Policy Configuration and Reference Guide

Operations That Evaluate HTTP Headers
HTTP Header Operation
http header.
VALUE(instance number)

Description
An HTTP header can occur multiple times in a request
or a response. VALUE(0) selects the value in the last
instance, VALUE(1) selects the value in the next-tolast instance, and so on. The instance number argument
cannot exceed 14.
Following is an example of a request with two headers:
HTTP/1.1 200 OK\r\n
MyHeader: abc\r\n
Content-Length: 200\r\n
MyHeader: def\r\n
\r\n

The following returns "abc\r\n":
http.res.header("MyHeader").value(1)

Prefixes for Cache-Control Headers
The following prefixes apply specifically to Cache-Control headers.
Prefixes That Extract Cache-Control Headers
HTTP Header Prefix

Description

HTTP.REQ.CACHE_CONTROL

Returns a Cache-Control header in an HTTP
request.

HTTP.RES.CACHE_CONTROL

Returns a Cache-Control header in an HTTP
response.

Operations for Cache-Control Headers
You can apply any of the operations for HTTP headers to Cache-Control headers.
For more information, see “Operations for HTTP Headers,” on page 122.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

127

In addition, the following operations identify specific types of Cache-Control
headers. See RFC 2616 for details on these header types.
Operations That Evaluate Cache-Control Headers
HTTP Header Operation
Cache-Control header.
NAME(integer)

Description
Returns as a text value the name of the Cache-Control
header that corresponds to the nth component in a
name-value list, as specified by integer.
The index of the name-value component is 0-based. If
the index that is specified by the integer argument is
greater than the number of components in the list, a
zero-length text object is returned.
Following is an example:
http.req.cache_control.name(3).
contains("some_text")

Cache-Control header.
IS_INVALID

Returns a Boolean TRUE if the Cache-Control header
is not present in the request or response.
Following is an example:
http.req.cache_control.is_invalid

Cache-Control header.
IS_PRIVATE

Returns a Boolean TRUE if the Cache-Control header
has the value Private.
Following is an example:
http.req.cache_control.is_private

Cache-Control header.
IS_PUBLIC

Returns a Boolean TRUE if the Cache-Control header
has the value Private.
Following is an example:
http.req.cache_control.is_public

Cache-Control header.
IS_NO_STORE

Returns a Boolean TRUE if the Cache-Control header
has the value No-Store.
Following is an example:
http.req.cache_control.is_no_store

Cache-Control header.
IS_NO_CACHE

Returns a Boolean TRUE if the Cache-Control header
has the value No-Cache.
Following is an example:
http.req.cache_control.is_no_cache

Cache-Control header.
IS_MAX_AGE

Returns a Boolean TRUE if the Cache-Control header
has the value Max-Age.
Following is an example:
http.req.cache_control.is_max_age

128

Citrix NetScaler Policy Configuration and Reference Guide

Operations That Evaluate Cache-Control Headers
HTTP Header Operation
Cache-Control header.
IS_MIN_FRESH

Description
Returns a Boolean TRUE if the Cache-Control header
has the value Min-Fresh.
Following is an example:
http.req.cache_control.is_min_fresh

Cache-Control header.
IS_MAX_STALE

Returns a Boolean TRUE if the Cache-Control header
has the value Max-Stale.
Following is an example:
http.req.cache_control.is_max_stale

Cache-Control header.
IS_MUST_REVALIDATE

Returns a Boolean TRUE if the Cache-Control header
has the value Must-Revalidate.
Following is an example:
http.req.cache_control.is_must_
revalidate

Cache-Control header.
IS_NO_TRANSFORM

Returns a Boolean TRUE if the Cache-Control header
has the value No-Transform.
Following is an example:
http.req.cache_control.is_no_transform

Cache-Control header.
IS_ONLY_IF_CACHED

Returns a Boolean TRUE if the Cache-Control header
has the value Only-If-Cached.
Following is an example:
http.req.cache_control.is_only_if_cached

Cache-Control header.
IS_PROXY_REVALIDATE

Returns a Boolean TRUE if the Cache-Control header
has the value Proxy-Revalidate.
Following is an example:
http.req.cache_control.is_proxy_
revalidate

Cache-Control header.
IS_S_MAXAGE

Returns a Boolean TRUE if the Cache-Control header
has the value S-Maxage.
Following is an example:
http.req.cache_control.is_s_maxage

Cache-Control header.
IS_UNKNOWN

Returns a Boolean TRUE if the Cache-Control header
is of an unknown type.
Following is an example:
http.req.cache_control.is_unknown

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

129

Operations That Evaluate Cache-Control Headers
HTTP Header Operation
Cache-Control header.
MAX_AGE

Description
Returns the value of the Cache-Control header MaxAge. If this header is absent or invalid, 0 is returned.
Following is an example:
http.req.cache_control.max_age.le(3)

Cache-Control header.
MAX_STALE

Returns the value of the Cache-Control header MaxStale. If this header is absent or invalid, 0 is returned.
Following is an example:
http.req.cache_control.max_stale.le(3)

Cache-Control header.
MIN_FRESH

Returns the value of the Cache-Control header MinFresh. If this header is absent or invalid, 0 is returned.
Following is an example:
http.req.cache_control.min_fresh.le(3)

Cache-Control header.S_ Returns the value of the Cache-Control header SMaxage. If this header is absent or invalid, 0 is returned.
MAXAGE

Following is an example:
http.req.cache_control.s_maxage.eq(2)

Expressions for Extracting Segments of URLs
You can extract URLs and portions of URLs, such as the host name, or a segment
of the URL path. For example, the following expression identifies HTTP requests
for image files by extracting image file suffixes from the URL:
http.req.url.suffix.eq("jpeg") || http.req.url.suffix.eq("gif")

Most expressions for URLs operate on text and are described in “Expression
Prefixes for Text in HTTP Requests and Responses,” on page 67. This section
discusses the GET operation. The GET operation extracts text when used with the
following prefixes:
•

HTTP.REQ.URL.PATH

•

VPN.BASEURL.PATH

•

VPN.CLIENTLESS_BASEURL.PATH

130

Citrix NetScaler Policy Configuration and Reference Guide

The following table describes prefixes for HTTP URLs that are not described
elsewhere.
Prefixes That Extract URLs
URL Prefix
HTTP.REQ.URL.PATH.
GET(n)

Description
Returns a slash- (“/”) separated list from the URL path.
For example, consider the following URL:
http://www.mycompany.com/dir1/dir2/dir3/
index.html?a=1

The following expression returns dir1 from this URL:
http.req.url.path.get(1)

The following expression returns dir2:
http.req.url.path.get(2)
HTTP.REQ.URL.PATH.GET_
REVERSE(n)

Returns a slash- (“/”) separated list from the URL path,
starting from the end of the path. For example, consider
the following URL:
http://www.mycompany.com/dir1/dir2/dir3/
index.html?a=1

The following expression returns index.html from this
URL:
http.req.url.path.get_reverse(0)

The following expression returns dir3:
http.req.url.path.get_reverse(1)

Expressions for Numeric HTTP Payload Data Other Than
Dates
The following table describes prefixes for numeric values in HTTP data other
than dates. You would use numeric operations with the following prefixes.
Prefixes That Evaluate HTTP Request or Response Length
Prefix
HTTP.REQ.CONTENT_LENGTH

Description
Returns the length of an HTTP request as a
number.
Following is an example:
http.req.content_length < 500

HTTP.RES.CONTENT_LENGTH

Returns the length of the HTTP response as a
number.
Following is an example:
http.res.content_length <= 1000

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

131

Prefixes That Evaluate HTTP Request or Response Length
Prefix
HTTP.RES.STATUS

Description
Returns the response status code

Operations for HTTP, HTML, and XML Encoding and
“Safe” Characters
The following operations work with the encoding of HTML data in a request or
response and XML data in a POST body.
Operations That Evaluate HTML and XML Encoding
HTML or XML Operation
text.HTML_XML_SAFE

Description
Transforms special characters into XML safe
format, as in the following examples:
• A left-pointing angle bracket (<) is converted
to <
• A right-pointing angle bracket (>) is converted
to >
• An ampersand (&) is converted to &
This operation safeguards against cross-site
scripting attacks. This is a read-only operation.
After applying the transformation, additional
operators that you specify in the expression are
applied to the selected text. Following is an
example:
http.req.url.query.html_xml_safe.
contains("myQueryString")

text.HTTP_HEADER_SAFE

Converts all new line ('\n') characters in the input
text to '%0A' to enable the input to be used safely
in HTTP headers.
This operation safeguards against responsesplitting attacks. This is a read-only operation.

132

Citrix NetScaler Policy Configuration and Reference Guide

Operations That Evaluate HTML and XML Encoding
HTML or XML Operation
text.HTTP_URL_SAFE

Description
Converts unsafe URL characters to '%xx' values,
where “xx” is a hex-based representation of the
input character. For example, the ampersand (&) is
represented as %26 in URL-safe encoding. This is
a read-only operation.
Following are URL safe characters. All others are
unsafe:
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•
•

text.MARK_SAFE

Alpha-numeric characters: a-z, A-Z, 0-9
Asterix: "*"
Ampersand: "&"
At-sign: "@"
Colon: ":"
Dollar: "$"
Dot: "."
Equals: "="
Exclamation mark: "!"
Hyphen: "-"
Open and close parentheses: "(", ")"
Plus: "+"
Semicolon: ";"
Single quote: "'"
Slash: "/"
Tilde: "~"
Underscore: "_"

Marks the text as safe without applying any type of
data transformation.

text.SET_TEXT_
Transforms all %HH encoding in the byte stream.
MODE(URLENCODED|NOURLENCODE This operation works with characters (not bytes).
By default, a single byte represents a character in
D)

ASCII encoding. However, if you specify
URLENCODED mode, three bytes can represent a
character.
In the following example, a PREFIX(3) operation
selects the first 3 characters in a target.
http.req.url.hostname.prefix(3)

In the following example, the NetScaler can select
up to 9 bytes from the target:
http.req.url.hostname.set_text_
mode(urlencoded).prefix(3)
text.SET_TEXT_MODE(PLUS_AS_ Specifies how to treat the plus character (+). The
PLUS_AS_SPACE option replaces a plus
SPACE|NO_PLUS_AS_SPACE)

character with white space. For example, the text
“hello+world” becomes “hello world.” The NO_
PLUS_AS_SPACE option leaves plus characters
as they are.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

133

Operations That Evaluate HTML and XML Encoding
HTML or XML Operation

Description

text.SET_TEXT_
Specifies whether or not backslash decoding is
MODE(BACKSLASH_ENCODED|NO_ performed on the text object represented by text.
BACKSLASH_ENCODED)
If BACKSLASH_ENCODED is specified, the SET_
TEXT_MODE operator performs the following

operations on the text object:
• All occurrences of “\XXX” will be replaced
with the character “Y” (where XXX represents
a number in the octal system and Y represents
the ASCII equivalent of XXX). The valid range
of octal values for this type of encoding is 0 to
377. For example, the encoded text "http\72//"
and "http\072//" will both be decoded to "http:/
/", where the colon (:) is the ASCII equivalent
of the octal value “72”.
• All occurrences of “\xHH” will be replaced
with the character “Y” (HH represents a
number in the hexadecimal system and Y
denotes the ASCII equivalent of HH. For
example, the encoded text "http\x3a//" will be
decoded to "http://", where the colon (:) is the
ASCII equivalent of the hexadecimal value
“3a“.
• All occurrences of “\\uWWXX” will be
replaced with the character sequence “YZ”
(Where WW and XX represent two distinct
hexadecimal values and Y and Z represent their
ASCII equivalents of WW and XX respectively.
For example, the encoded text "http%u3a2f/"
and "http%u003a//" will both be decoded to
"http://", where “3a” and “2f” are two
hexadecimal values and the colon (:) and
forward slash (“/”) represent their ASCII
equivalents respectively.
• All occurrences of "\b", "\n", "\t", "\f", and "\r"
are replaced with the corresponding ASCII
characters.
If NO_BACKSLASH_ENCODED is specified,
backslash decoding is not performed on the text
object.
text.SET_TEXT_MODE(BAD_
Performs the associated undefined action if either
ENCODE_RAISE_UNDEF|NO_BAD_ the URLENCODED or the BACKSLASH_
ENCODED mode is set and bad encoding
ENCODE_RAISE_UNDEF)

corresponding to the specified encoding mode is
encountered in the text object represented by text.
If NO_BAD_ENCODE_RAISE_UNDEF is
specified, the associated undefined action will not
be performed when bad encoding is encountered in
the text object represented by text.

134

Citrix NetScaler Policy Configuration and Reference Guide

Expressions for TCP, UDP, and VLAN Data
TCP and UDP data takes the form of a string or a number. For expression prefixes
that return string values for TCP and UDP data, you can apply any text-based
operations. For more information, see “Advanced Expressions: Evaluating Text,”
on page 63.
For expression prefixes that return numeric value, such as a source port, you can
apply an arithmetic operation. For more information, see “Basic Operations on
Expression Prefixes,” on page 44 and “Compound Operations for Numbers,” on
page 48.
The following table describes prefixes that extract TCP and UDP data.
Prefixes that Extract TCP and UDP Data
GET Operation

Description

CLIENT.TCP.PAYLOAD(integer) Returns TCP payload data as a string, starting with

the first character in the payload and continuing for
the number of characters in the integer argument.
You can apply any text-based operation to this
prefix.
CLIENT.TCP.SRCPORT

Returns the ID of the current packet's source port
as a number.

CLIENT.TCP.DSTPORT

Returns the ID of the current packet's destination
port as a number.

CLIENT.UDP.DNS.DOMAIN

Returns the DNS domain name.

CLIENT.UDP.DNS.DOMAIN.
EQ("hostname")

Returns a Boolean TRUE if the domain name
matches the hostname argument. The comparison
is case insensitive.
Following is an example:
client.udp.dns.domain.eq("www.
mycompany.com")

CLIENT.UDP.DNS.IS_AAAAREC

Returns a Boolean TRUE if the record type is
AAAA. These types of records indicate an IPv6
address in forward lookups.

CLIENT.UDP.DNS.IS_ANYREC

Returns a Boolean TRUE if it is of any record type.

CLIENT.UDP.DNS.IS_AREC

Returns a Boolean TRUE if the record is type A.
Type A records provide the host address.

CLIENT.UDP.DNS.IS_CNAMEREC Returns a Boolean TRUE if the record is of type

CNAME. In systems that use multiple names to
identify a resource, there is one canonical name
and a number of aliases. The CNAME provides the
canonical name.

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

135

Prefixes that Extract TCP and UDP Data
GET Operation

Description

CLIENT.UDP.DNS.IS_MXREC

Returns a Boolean TRUE if the record is of type
MX (mail exchanger). This DNS record describes
a priority and a host name. The MX records for the
same domain name specify the email servers in the
domain and the priority for each server.

CLIENT.UDP.DNS.IS_NSREC

Returns a Boolean TRUE if the record is of type
NS. This is a name server record that includes a
host name with an associated A record. This
enables locating the domain name that is
associated with the NS record.

CLIENT.UDP.DNS.IS_PTRREC

Returns a Boolean TRUE if the record is of type
PTR. This is a domain name pointer and is often
used to associate a domain name with an IPv4
address.

CLIENT.UDP.DNS.IS_SOAREC

Returns a Boolean TRUE if the record is of type
SOA. This is a start of authority record.

CLIENT.UDP.DNS.IS_SRVREC

Returns a Boolean TRUE if the record is of type
SRV. This is a more general version of the MX
record.

CLIENT.UDP.DSTPORT

Returns the numeric ID of the current packet's
UDP destination port.

CLIENT.UDP.SRCPORT

Returns the numeric ID of the current packet's
UDP source port.

CLIENT.UDP.RADIUS

Returns RADIUS data for the current packet.

CLIENT.UDP.RADIUS.ATTR_
TYPE(type)

Returns the value for the attribute type specified as
the argument.

CLIENT.UDP.RADIUS.USERNAME Returns the RADIUS user name.
CLIENT.TCP.MSS

Returns the maximum segment size (MSS) for the
current connection as a number.

CLIENT.VLAN.ID

Returns the numeric ID of the VLAN through
which the current packet entered the NetScaler.

SERVER.TCP.DSTPORT

Returns the numeric ID of the current packet's
destination port.

SERVER.TCP.SRCPORT

Returns the numeric ID of the current packet's
source port.

SERVER.VLAN

Operates on the VLAN through which the current
packet entered the NetScaler.

SERVER.VLAN.ID

Returns the numeric ID of the VLAN through
which the current packet entered the NetScaler.

136

Citrix NetScaler Policy Configuration and Reference Guide

XPath and JSON Expressions
The advanced expression engine supports expressions for evaluating and
retrieving data from XML and JavaScript Object Notation (JSON) files. This
enables you to find specific nodes in an XML or JSON document, determine if a
node exists in the file, locate nodes in XML contexts (for example, nodes that
have specific parents or a specific attribute with a given value), and return the
contents of such nodes. Additionally, you can use XPath expressions in rewrite
expressions.
The advanced expression implementation for XPath comprises an advanced
expression prefix (such as “HTTP.REQ.BODY”) that designates XML text and
the XPATH operator that takes the XPath expression as its argument.
JSON files are either a collection of name/value pairs or an ordered list of values.
You can use the XPATH_JSON operator, which takes an XPath expression as its
argument, to process JSON files.
XPath and JSON Expression Prefixes that Return Text
XPath Prefix

Description

text.XPATH(xpathex)

Operate on an XML file and return a Boolean
value.
For example, the following expression returns
a Boolean TRUE if a node called “creator”
exists under the node “Book” within the first
1000 bytes of the XML file.
HTTP.REQ.BODY(1000).
XPATH(xp%boolean(//Book/creator)%)
Parameters:
xpathex - XPath Boolean expression

text.XPATH(xpathex)

Operate on an XML file and return a value of
data type “double.”
For example, the following expression
converts the string “36” (a price value) to a
value of data type “double” if the string is in
the first 1000 bytes of the XML file:
HTTP.REQ.BODY(1000).
XPATH(xp%number(/Book/price)%)
Parameters:
xpathex - XPath numeric expression

Chapter 6

Advanced Expressions: Parsing HTTP, TCP, and UDP Data

137

XPath Prefix

Description

text.XPATH(xpathex)

Operate on an XML file and return a node-set
or a string. Node-sets are converted to
corresponding strings by using the standard
XPath string conversion routine.
For example, the following expression selects
all the nodes that are enclosed by “/Book/
creator” (a node-set) in the first 1000 bytes of
the body:
HTTP.REQ.BODY(1000).XPATH(xp%/
Book/creator%)
Parameters:
xpathex - XPath expression

text.XPATH_JSON(xpathex)

Operate on a JSON file and return a Boolean
value.
For example, {consider the following JSON
file:
{ "Book":{ "creator":{ "person":{
"name":'' } }, "title":'