String Maps

2015-01-16 04:43:09 UTC

2015 Citrix Systems, Inc. All rights reserved. Terms of Use | Trademarks | Privacy Statement

Contents

String Maps .....................................................................................................

How String Maps Work ...........................................................................

Configuring a String Map ........................................................................

String Maps Use Cases ...........................................................................

Use Case: Responder Policy With a Redirect Action ..................................

String Maps
You can use string maps to perform pattern matching in all NetScaler features that use the
default policy syntax. A string map is a NetScaler entity that consists of key-value pairs.
The keys and values are strings in either ASCII or UTF-8 format. String comparison uses two
new functions, MAP_STRING(<string_map_name>) and
IS_STRINGMAP_KEY(<string_map_name>).
A policy configuration that uses string maps performs better than one that does string
matching through policy expressions, and you need fewer policies to perform string
matching with a large number of key-value pairs. String maps are also intuitive, simple to
configure, and result in a smaller configuration.

How String Maps Work

String maps are similar in structure to pattern sets (a pattern set defines a mapping of
index values to strings; a string map defines a mapping of strings to strings) and the
configuration commands for string maps (commands such as add, bind, unbind, remove, and
show) are syntactically similar to configuration commands for pattern sets. Also, as with
index values in a pattern set, each key in a string map must be unique across the map. The
following table illustrates a string map called url_string_map, which contains URLs as keys
and values.
Table 1. String Map "url_string_map"
Key

Value

/url_1.html

http://www.redirect_url_1.com/url_1.html

/url_2.html

http://www.redirect_url_2.com/url_2.html

/url_3.html
http://www.redirect_url_1.com/url_1.html
The following table describes the two functions that have been introduced to enable string
matching with keys in a string map. String matching is always performed with the keys.
Additionally, the following functions perform a comparison between the keys in the string
map and the complete string that is returned by the expression prefix. The examples in the
descriptions refer to the preceding example.
Table 2. String Map Functions

nction

Description

EXT>.MAP_STRING(<string_map_name>)

Checks whether the value returned by the expression prefix TEXT matches an
in the string map, and returns the value that corresponds to the key. If no key
map matches the value returned by the expression prefix, the function return
string. The IGNORECASE and NOIGNORECASE functions can be used for case
and case-sensitive comparison, respectively.

Example 1: HTTP.REQ.URL.MAP_STRING("url_string_map") checks wh

string returned by HTTP.REQ.URL is a key in the string map url_string_map.
of HTTP.REQ.URL is /url_1.html, the function returns
http://www.redirect_url_1.com/url_1.html.
Example 2:

HTTP.REQ.URL.SET_TEXT_MODE(IGNORECASE).MAP_STRING("url_stri
checks whether the string returned by HTTP.REQ.URL is a key in the string m
url_string_map. The comparison does not consider case. If the string returned
HTTP.REQ.URL is /URL_1.html, the function returns
http://www.redirect_url_1.com/url_1.html.
Parameters:
string_map_name - The string map.

How String Maps Work

EXT>.IS_STRINGMAP_KEY(<string_map_name>)

Returns TRUE if the string returned by the expression prefix TEXT is a key in
map. The IGNORECASE and NOIGNORECASE functions can be used for case-i
and case-sensitive string matching, respectively.
Example 1:
HTTP.REQ.URL.IS_STRINGMAP_KEY("url_string_map") returns TRUE
HTTP.REQ.URL is one of the keys in url_string_map.

Example 2: HTTP.REQ.URL.SET_TEXT_MODE(IGNORECASE).
IS_STRINGMAP_KEY("url_string_map") returns TRUE if the value of HT
is one of the keys in url_string_map. In this case, key lookup does not conside
Therefore, the function returns TRUE even if the value of HTTP.REQ.URL is
/URL_3.html.
Parameters:
string_map_name - The string map.

Configuring a String Map

You first create a string map and then bind key-value pairs to it. You can create a string
map from the command line interface (CLI) or the configuration utility.

To configure a string map by using the command line

interface
At the command prompt, do the following:
1. Create a string map.
add policy stringmap <name> -comment <string>
2. Bind a key-value pair to the string map.
bind policy stringmap <name> <key> <value>
Example:
> bind policy stringmap url_string_map1 "/url_1.html" "http://www.redirect_url_1.com/url_1.html"

To configure a string map by using the configuration

utility
Create a string map and bind the key-value pair to the created entity.
Navigate to AppExpert > String Maps,click Add and specify the relevant details.

Parameter Descriptions (of commands listed in the

CLI procedure)
add policy stringmap
name
Unique name for the string map. Not case sensitive. Must begin with an ASCII letter or
underscore (_) character, and must consist only of ASCII alphanumeric or underscore
characters. Must not begin with 're' or 'xp' or be a word reserved for use as a default
syntax expression qualifier prefix (such as HTTP) or enumeration value (such as ASCII).
Must not be the name of an existing named expression, pattern set, dataset, string map,
or HTTP callout.

Configuring a String Map

comment
Comments associated with the string map.
View description(s) in command reference Top

bind policy stringmap

name
Name of the string map to which to bind the key-value pair.
key
Character string constituting the key to be bound to the string map. The key is matched
against the data processed by the operation that uses the string map. The default
character set is ASCII. UTF-8 characters can be included if the character set is UTF-8.
UTF-8 characters can be entered directly (if the UI supports it) or can be encoded as a
sequence of hexadecimal bytes '\xNN'. For example, the UTF-8 character 'u' can be
encoded as '\xC3\xBC'.
View description(s) in command reference Top

String Maps Use Cases

You can use string maps in all features that support the newer default policy syntax. For
example, string maps can be used in responder redirects and rewrite actions. You can also
reuse a given string map in multiple features.

Use Case: Responder Policy With a

Redirect Action
The following use case involves a responder policy with a redirect action. In the example
below, the first four commands create the string map url_string_map and bind the
three key-value pairs used in the earlier example. After creating the map and binding the
key-value pairs, you create a responder action (act_url_redirects) that redirects the
client to the corresponding URL in the string map or to www.default.com. You also
configure a responder policy (pol_url_redirects) that checks whether requested URLs
match any of the keys in url_string_map and then performs the configured action.
Finally, you bind the responder policy to the content switching virtual server that receives
the client requests that are to be evaluated.
add stringmap url_string_map
bind stringmap url_string_map /url_1.html
http://www.redirect_url_1.com/url_1.html
bind stringmap url_string_map /url_2.html
http://www.redirect_url_2.com/url_2.html
bind stringmap url_string_map /url_3.html
http://www.redirect_url_1.com/url_1.html
add responder action act_url_redirects redirect
'HTTP.REQ.URL.MAP_STRING("url_string_map") ALT "www.default.com"'
-bypassSafetyCheck yes
add responder policy pol_url_redirects TRUE act_url_redirects
bind cs vserver csw_redirect -policyname pol_url_redirects -priority
1 -type request