Product Documentation

Configuring and Using Variables

Dec 13, 2017

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.

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 sys.http.callout(get_user_privilege)
    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.

    • $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_text_t).not -resAction set_user_privilege

Use Case to Insert HTTP header in the Response Side

The following example shows an example of a singleton variable.

1. Add a singleton variable of type text. This variable can hold maximum 100 Bytes data.

add ns variable http_req_data -type text(100) -scope transaction

2. Add an assignment action, which will be used to store the HTTP request data into the variable.

add ns assignment set_http_req_data -variable $http_req_data -set http.req.body(100)

3. Add a rewrite action to insert HTTP header, whose value will be fetched from the variable.

add rewrite action act_ins_header insert_http_header user_name $http_req_data.after_str("user_name").before_str("password")

4. Add a rewrite policy which will evaluate in the request time, and take assignment action to store data. When we hit this policy, we’ll take assignment action and store the data into the ns variable (http_req_data)
add rewrite policy pol_set_variable true set_http_req_data

bind rewrite global pol_set_variable 10 -type req_dEFAULT

5. Add a rewrite policy which will evaluate in the response time, and add an HTTP header in the response.

add rewrite policy pol_ins_header true act_ins_header

bind rewrite global pol_ins_header 10 -type res_dEFAULT

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.