Basic elements of an advanced policy expression
An Advanced policy 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:
<prefix>.<operation> [<compound-operator> <prefix>.<operation>. . .]
where
-
<prefix>
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.
-
<operation>
identifies an evaluation that is to be performed on the data identified by the prefix.
For example, consider the following expression:
http.req.header(“Content-Type”).eq(“text/html”)
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.” For more information, see “Operations.”
-
<compound-operator>
is a Boolean or arithmetic operator that forms a compound expression from multiple prefix or prefix.operation elements.
For example, consider the following expression:
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.
- The prefix http.req.url designates an HTTP URL in URL-encoded format.
-
SERVER:
Identifies an element in the server that is either processing a request or sending a response.
-
SYS:
Identifies a characteristic of the NetScaler that is processing the traffic.
Note: Note that DNS policies support only SYS, CLIENT, and SERVER objects.
In addition, in the NetScaler Gateway, the Clientless VPN function can use the following types of prefixes:
-
TEXT:
Identifies any text element in a request or a response.
-
TARGET:
Identifies the target of a connection.
-
URL:
Identifies an element in the URL portion of an 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
Which expression prefixes you can specify depends on the NetScaler feature. The following table describes the expression prefixes that are of interest on a per-feature basis
| 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 |
| NetScaler Gateway, Clientless Access | HTTP, SYS, CLIENT, SERVER, URL, TEXT, TARGET, VPN |
Table 1. Permitted Types of Expression Prefixes in Various NetScaler Features
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 policy expression contains a single element. This element can be one of the following:
- true. An Advanced policy 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 policy 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 conjunction with operations and additional prefixes to form a compound expression.
Operations
In most expressions, you also specify an operation on the data that the prefix identifies. For example, suppose that you specify the following prefix:
http.req.url
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.
| Operation | Determines Whether or Not |
|---|---|
| CONTAINS( |
The object matches |
| 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) |
| GT( |
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.
| 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, and 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. |