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.
To configure variables by using the command line interface
- 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>]
<!--NeedCopy-->
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
<!--NeedCopy-->
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)
<!--NeedCopy-->
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.
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>]
<!--NeedCopy-->
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
<!--NeedCopy-->
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)
<!--NeedCopy-->
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.
-
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
<!--NeedCopy-->
Use Case to Insert HTTP header in the Response Side
The following example shows an example of a singleton variable.
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
<!--NeedCopy-->
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)
<!--NeedCopy-->
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")
<!--NeedCopy-->
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
<!--NeedCopy-->
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
<!--NeedCopy-->
Assignment action
In a NetScaler appliance, an assignment action bound to the policy is triggered when the policy rule evaluates to true. The action updates the value in the variable which can be used in subsequent policy rule evaluations. This way, the same variable can be updated and used for subsequent policy evaluations in the same feature. Previously, the appliance executed assignment actions only after evaluating all of the policies in the feature when the policies of the associated assignment actions evaluated to true. Therefore, the variable value set by the assignment action cannot be used in the subsequent policy rule evaluations within the feature.
This functionality can be understood better with a use case that controls access list for clients on a NetScaler appliance. The access decision is provided by a separate web service, with the request GET /client-access?<client-IP-address> which returns a response with “BLOCK” or “ALLOW” in the body. The HTTP callout is configured to include the IP address of the client that is associated with an incoming request. When the NetScaler appliance receives a request from a client, the appliance generates the callout request and sends it to the callout server, which hosts a database of blacklisted IP addresses and an HTTP callout agent that checks whether the client’s IP address is listed in the database. The HTTP callout agent receives the callout request, checks whether the client’s IP address is listed, and sends a response. The response is a status code, 200, 302 along with “BLOCK” or “ALLOW” in the body. Based on the status code, the appliance performs the policy evaluation. If the policy evaluation is true, the assignment action is triggered immediately and action sets the value to the variable. The appliance uses and sets this variable value for subsequent policy evaluation in the same module.
Use case for configuring assignment action
Follow the steps below to configure assignment action and use variable for subsequent policies:
-
The access decision is provided by a separate web service, with the request which returns a response with BLOCK or ALLOW in the body.
GET /url-service>/url-allowed?<URL path> -
Set up a map variable to hold the access decisions for URLs.
add ns variable url_list_map -type 'map(text(1000),text(10),10000)' -
Set up an HTTP callout to send the access request to the web service.
add policy httpCallout url_list_callout -vserver url_vs -returnType TEXT -urlStemExpr '"/url-allowed?" + HTTP.REQ.URL.PATH' -resultExpr 'HTTP.RES.BODY(10)' -
Set up an assignment action to invoke the callout to get the access decision and assign it to the map entry for the URL.
add ns assignment client_access_assn -variable '$client_access_map[CLIENT.IP.SRC.TYPECAST_TEXT_T]' -set SYS.HTTP_CALLOUT(client_access_callout) -
Set up a responder action to send a 403 response if a URL request is blocked.
add responder action url_list_block_act respondwith '"HTTP/1.1 403 Forbidden\\r\\n\\r\\n"' -
Set up a responder policy to set the map entry for the URL if it is not already set. With the immediate action enhancement, the map entry value is set when this policy is evaluated. Prior to the enhancement, the assignment was not done until all responder policies had been evaluated decision is provided by a separate web service.
add responder policy url_list_assn_pol '!$url_list_map.VALUEEXISTS(HTTP.REQ.URL.PATH)' url_list_assn -
Set up a responder policy to block access to a URL if its map entry value is BLOCK. With the immediate action enhancement, the map entry set by the preceding policy is available for use in this policy. Prior to the enhancement, the map entry would still be unset at this point.
add responder policy client_access_block_pol '$client_access_map[CLIENT.IP.SRC.TYPECAST_TEXT_T] == "BLOCK"' client_access_block_act -
Bind the responder policies to the virtual server. Note: We cannot globally bind the policies because we don’t want to execute them for the HTTP callout on a separate virtual server.
bind lb vserver vs -policyName client_access_assn_pol -priority 10 -gotoPriorityExpression NEXT -type REQUESTbind lb vserver vs -policyName client_access_block_pol -priority 20 -gotoPriorityExpression END -type REQUEST
To configure variables by using the configuration utility
- Navigate to AppExpert > NS Variables, to create a variable.
- Navigate to AppExpert > NS Assignments, to assign value(s) to the variable.
- Navigate to the appropriate feature area where you want to configure the assignment as an action.