Product Documentation

Configuring and Using Variables

Aug 31, 2016

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

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.