Variables

2015-01-16 04:39:39 UTC

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

Contents

Variables........................................................................................................

Configuring and Using Variables ...............................................................

Use Case: Caching User Privileges .............................................................

10

Use Case: Limiting the Number of Sessions ..................................................

11

Variables
The NetScaler appliance supports creation of variables of the following types:

Singleton variables. Can have a single value of one of the following types: ulong and
text (max-size). The ulong type is an unsigned 64-bit integer, the text type is a
sequence of bytes, and max-size is the maximum number of bytes in the sequence.

Map variables. Maps hold values associated with keys: each key-value pair is called a
map entry. The key for each entry is unique within the map. Maps are specified as
follows:
map (key_type, value_type, max-values).
where,

key_type is the data type of the key. It is of type text (max-size).

value_type is the data type of the values of the map. It can be of type ulong or text
(max-size).

max-values is the maximum number of entries that the map can contain. It is of
type ulong.
Values for these variables are set using assignments which must be invoked on policy
actions.

Note: Variables are not yet supported in a high-availability setup or in a cluster.

Configuring and Using Variables

You must first create a variable and then assign a value or specify the operation that must
be performed on the variable. After performing these operations, you can use the
assignment as a policy action.
Note: Once configured, a variable's settings cannot be modified or reset. If the variable
needs to be changed, the variable and all references to the variable (expressions and
assignments) must be deleted. The variable can then be re-added with new settings, and
the references (expressions and assignments) can be re-added.

Configuring and Using Variables

To configure variables by using the command line

interface
1. Create a variable.
add ns variable <name> -type <string> [-scope global] [-ifFull ( undef | lru )]
[-ifValueTooBig ( undef | truncate )] [-ifNoValue ( undef | init )] [-init <string>]
[-expires <positive_integer>] [-comment <string>]
Note: Refer to the man page "man add ns variable" for description of the command
parameters.
Example 1: Create a ulong variable named "my_counter" and initialize it to 1.
add ns variable my_counter type ulong -init 1
Example 2: Create a map named "user_privilege_map". The map will contain keys of
maximum length 15 characters and text values of maximum length 10 characters, with a
maximum of 10000 entries.
add ns variable user_privilege_map -type map(text(15),text(10),10000)
Note: If the map contains 10000 unexpired entries, assignments for new keys reuse
one of the least recently used entries. By default, an expression trying to get a value
for a non-existent key will initialize an empty text value.
2. Assign the value or specify the operation to be performed on the variable. This is done
by creating an assignment.
add ns assignment <name> -variable <expression> [-set <expression> | -add
<expression> | -sub <expression> | -append <expression> | -clear] [-comment <string>]
Note: A variable is referenced by using the variable selector ($). Therefore,
$variable1 is used to refer to text or ulong variables. Similarly,
$variable2[key-expression] is used to refer to map variables.
Example 1: Define an assignment named "inc_my_counter" that automatically adds 1 to
the "my_counter" variable.
add ns assignment inc_my_counter -variable $my_counter -add 1

Example 2: Define an assignment named "set_user_privilege" that adds to the

"user_privilege_map" variable an entry for the client's IP address with the value returned
by the "get_user_privilege" HTTP callout.
add ns assignment set_user_privilege -variable $user_privilege_map[client.ip.src.typecast_text_t] -set sy
Note: If an entry for that key already exists, the value will be replaced. Otherwise a
new entry for the key and value will be added. Based on the previous declaration for
user_privilege_map, if the map already has 10000 entries, one of the least recently
used entries will be reused for the new key and value.
3. Invoke the variable assignment in a policy.
There are two functions that can operate on map variables.

Configuring and Using Variables

$name.valueExists(key-expression). Returns true if there is a value in the map

selected by the key-expression. Otherwise returns false. This function will update
the expiration and LRU information if the map entry exists, but will not create a
new map entry if the value does not exist.

$name.valueCount. Returns the number of values currently held by the variable.

This is the number of entries in a map. For a singleton variable, this is 0 if the
variable is uninitialized or 1 otherwise.

Example: Invoke the assignment named "set_user_privilege" with a compression policy.

> add cmp policy set_user_privilege_pol -rule $user_privilege_map.valueExists(client.ip.src.typecast_tex

To configure variables by using the configuration

utility
1. Navigate to AppExpert > NS Variables, to create a variable.
2. Navigate to AppExpert > NS Assignments, to assign value(s) to the variable.
3. Navigate to the appropriate feature area where you want to configure the assignment
as an action.

Parameter Descriptions (of commands listed in the

CLI procedure)
add ns variable
name
Variable name. This follows the same syntax rules as other default syntax expression
entity names:
It must begin with an alpha character (A-Z or a-z) or an underscore (_).
The rest of the characters must be alpha, numeric (0-9) or underscores.
It cannot be re or xp (reserved for regular and XPath expressions).
It cannot be a default syntax expression reserved word (e.g. SYS or HTTP).
It cannot be used for an existing default syntax expression object (HTTP callout, patset,
dataset, stringmap, or named expression).
type
Specification of the variable type; one of the following:
ulong - singleton variable with an unsigned 64-bit value.
6

Configuring and Using Variables

text(value-max-size) - singleton variable with a text string value.
map(text(key-max-size),ulong,max-entries) - map of text string keys to unsigned 64-bit
values.
map(text(key-max-size),text(value-max-size),max-entries) - map of text string keys to
text string values.
where
value-max-size is a positive integer that is the maximum number of bytes in a text string
value.
key-max-size is a positive integer that is the maximum number of bytes in a text string
key.
max-entries is a positive integer that is the maximum number of entries in a map
variable.
For a global singleton text variable, value-max-size <= 64000.
For a global map with ulong values, key-max-size <= 64000.
For a global map with text values, key-max-size + value-max-size <= 64000.
max-entries is a positive integer that is the maximum number of entries in a map
variable. This has a theoretical maximum of 2^64-1, but in actual use will be much
smaller, considering the memory available for use by the map.
Example:
map(text(10),text(20),100) specifies a map of text string keys (max size 10 bytes) to text
string values (max size 20 bytes), with 100 max entries.
scope
Scope of the variable:
global - (default) one set of values visible across all Packet Engines and, in a cluster, all
nodes
Possible values: global
Default value: NS_VAR_SCOPE_GLOBAL
ifFull
Action to perform if an assignment to a map exceeds its configured max-entries:
lru - (default) reuse the least recently used entry in the map.
undef - force the assignment to return an undefined (Undef) result to the policy
executing the assignment.
Possible values: undef, lru

Configuring and Using Variables

Default value: NS_VAR_IF_FULL_LRU
ifValueTooBig
Action to perform if an value is assigned to a text variable that exceeds its configured
max-size,
or if a key is used that exceeds its configured max-size:
truncate - (default) truncate the text string to the first max-size bytes and proceed.
undef - force the assignment or expression evaluation to return an undefined (Undef)
result to the policy executing the assignment or expression.
Possible values: undef, truncate
Default value: NS_VAR_IF_VALUE_TOO_BIG_TRUNCATE
ifNoValue
Action to perform if on a variable reference in an expression if the variable is
single-valued and uninitialized
or if the variable is a map and there is no value for the specified key:
init - (default) initialize the single-value variable, or create a map entry for the key and
the initial value,
using the -init value or its default.
undef - force the expression evaluation to return an undefined (Undef) result to the
policy executing the expression.
Possible values: undef, init
Default value: NS_VAR_IF_NO_VALUE_INIT
init
Initialization value for values in this variable. Default: 0 for ulong, NULL for text
expires
Value expiration in seconds. If the value is not referenced within the expiration period it
will be deleted. 0 (the default) means no expiration.
Maximum value: 31622400
comment
Comments associated with this variable.
View description(s) in command reference Top

Configuring and Using Variables

add ns assignment
name
Name for the assignment. Must begin with a letter, number, or the underscore character
(_), and must contain only letters, numbers, and the hyphen (-), period (.) hash (#),
space ( ), at (@), equals (=), colon (:), and underscore characters. Can be changed after
the assignment is added.
The following requirement applies only to the NetScaler CLI:
If the name includes one or more spaces, enclose the name in double or single quotation
marks (for example, "my assignment" or 'my assignment).
variable
Left hand side of the assigment, of the form $variable-name (for a singleton variabled) or
$variable-name[key-expression], where key-expression is a default syntax expression that
evaluates to a text string and provides the key to select a map entry
set
Right hand side of the assignment. The default syntax expression is evaluated and
assigned to theleft hand variable.
add
Right hand side of the assignment. The default syntax expression is evaluated and added
to the left hand variable.
sub
Right hand side of the assignment. The default syntax expression is evaluated and
subtracted from the left hand variable.
append
Right hand side of the assignment. The default syntax expression is evaluated and
appended to the left hand variable.
clear
Clear the variable value. Deallocates a text value, and for a map, the text key.
comment
Comment. Can be used to preserve information about this rewrite action.
View description(s) in command reference Top

Use Case: Caching User Privileges

In this use case, user privileges ("GOLD", "SILVER", and so on) must be retrieved from an
external web service.
To achieve this use case, perform the following operations:
1. Create an HTTP callout to fetch the user privileges from the external web service.

> add policy httpcallout get_user_privilege

> set policy httpcallout get_user_privilege -ipaddress 10.217.193.84 -port 80 -returntype text -httpmetho
2. Store the privileges in a variable.

> add ns variable user_privilege_map -type map(text(15),text(10),10000) -expires 1200

> add ns assignment set_user_privilege -variable $user_privilege_map[client.ip.src] -set sys.http_callout(
3. Create a policy to check if there is already a cached entry for the client's IP address; if
not, it calls the HTTP callout to set a map entry for the client.

> add cmp policy set_user_privilege_pol -rule $user_privilege_map.valueExists(client.ip.src).not -resActi

4. Create a policy that compresses if the cached privilege entry for the client is "GOLD".

> add cmp policy compress_if_gold_privilege_pol -rule '$user_privilege_map[client.ip.src].eq("GOLD")' -re

5. Bind the compression policies globally.
> bind cmp global set_user_privilege_pol -priority 10 NEXT
> bind cmp global compress_if_gold_privilege_pol -priority 20 END

10

Use Case: Limiting the Number of

Sessions
In this use case, the requirement is to limit the number of active backend sessions. In the
deployment, each session login has login in the URL and each session logout has logout in
the URL. On successful login, the backend sets a sessionid cookie with a unique 10
character value.
To achieve this use case, perform the following operations:
1. Create a map variable that can store each active session. The key of the map is the
sessionid. The expiry time for the variable is set to 600 seconds (10 minutes).
> add ns variable session_map -type map(text(10),ulong,100) -expires 600
2. Create the following assignments for the map variable:

Create an entry for the sessionid and set that value to 1 (this value is not actually
used).
> add ns assignment add_session -variable '$session_map[http.req.cookie.value("sessionid")]' -set 1

Deallocate the entry for a session ID, which implicitly decrements the value count
for session_map.

> add ns assignment delete_session -variable '$session_map[http.req.cookie.value("sessionid")]' -clea

3. Create responder policies for the following:

To check if a map entry exists for that sessionid in the HTTP request. The
add_session assignment is executed if the map entry does not exist.

> add responder policy add_session_pol '$session_map.valueExists(http.req.cookie.value("sessionid"))

Note: The valueExists() function in the add_session_pol policy counts as a
reference to the session's map entry, so each request resets the expiration
timeout for its session. If no requests for a session are received after 10 minutes,
the session's entry will be deallocated.

To check when the session is logged out. The delete_session assignment is

executed.
> add responder policy delete_session_pol 'http.req.url.contains("logout")' delete_session

To check for login requests and if the number of active sessions exceed 100. If
these conditions are satisfied, in order to limit the number of sessions, the user is
redirected to a page that indicates that the server is busy.

> add responder action redirect_too_busy redirect "/too_busy.html"

> add responder policy check_login_pol 'http.req.url.contains("login") && $session_map.valueCount >
4. Bind the responder policies globally.
11

Use Case: Limiting the Number of Sessions

> bind responder global add_session_pol 10 next
> bind responder global delete_session_pol 20 next
> bind responder global check_login_pol 30

12