Configure policies for caching and invalidation

Policies enable the integrated cache to determine whether to try to serve a response from the cache or the origin. The NetScaler appliance provides built-in policies for integrated caching, and you can configure additional policies. When you configure a policy, you associate it with an action. An action either caches the objects to which the policy applies or invalidates (expires) the objects. Typically, you based caching policies on information in GET and POST requests. You typically base invalidation policies on the presence of the POST method in requests, along with other information. You can use any information in a GET or POST request in a caching or an invalidation policy.

You can view some of the built-in policies in the integrated cache’s Policies node in the configuration utility. The built-in policy names begin with an underscore (_).

Actions determine what the NetScaler appliance does when traffic matches a policy. The following actions are available:

  • Caching actions. Policies that you associate with the CACHE action store responses in the cache and serve them from the cache.
  • Invalidation actions. Policies that you associate with the INVAL action immediately expire cached responses and refresh them from the origin server. Note that for Web-based applications, invalidation policies often evaluate POST requests.
  • “Do not cache” actions. Policies that you associate with a NOCACHE action never store objects in the cache.
  • Provisionally cache actions. Policies that you associate with a MAYCACHE or MAYNOCACHE action depend on the outcome of additional policy evaluations.

Although the integrated cache does not store objects specified by the LOCK method, you can invalidate cached objects upon receipt of a LOCK request. For invalidation policies only, you can specify LOCK as a method by using the expression http.req.method.eq(“lock”). Unlike policies for GET and POST requests, you must enclose the LOCK method in quotes because the NetScaler appliance recognizes this method name as a string only.

After you create a policy, you bind it to a particular point in the overall processing of requests and responses. Although you create a policy before binding it, you should understand how the bind points affect the order of processing before you create your policies.

The policies bound to a particular bind point constitute a policy bank. You can use goto expressions to modify the order of execution in a policy bank. You can also invoke policies in other policy banks. In addition, you can create labels and bind policies to them. Such a label is not associated with a processing point, but the policies bound to it can be invoked from other policy banks.

Actions to associate with integrated caching policies

The following table describes actions for integrated caching policies.

Action Specification
CACHE Serves a response from the cache if the response has not expired. If the response must be fetched from the origin server, the NetScaler appliance caches the response before serving it. Even data that is updated and accessed frequently can be cached. For example, stock quotes are updated frequently, but they can be cached so that they can be served quickly to multiple users. If necessary, cached data can be refreshed immediately after it is downloaded. A CACHE action can be overridden by built-in policies.
NOCACHE Always fetches the response from the origin server and marks the response as non-storable. You typically configure NOCACHE policies for data that is sensitive or personalized.
MAY_CACHE Used in a request-time policy, this setting provisionally enables a response to be stored in a content group, pending evaluation of response-time policies. The following are possible: 1. If a matching response-time policy has a CACHE action but does not specify a content group, the response is stored in the Default group unless built-in policies override this policy. 2. If a matching response-time policy has a CACHE action and specifies the same content group as the one in the request-time policy, the response is stored in the named content group unless built-in policies override this policy. 3. If a matching response-time policy has a CACHE action but specifies a different content group from the one in the request-time policy, a NOCACHE action is applied. 4. If a matching response-time policy has a NOCACHE action, perform a NOCACHE action. 5. If there is no matching response-time policy, a CACHE action is applied, unless a built-in policy overrides this policy.
MAY_NOCACHE For a request-time policy, this setting provisionally prevents caching the response. At response time, one of following actions is taken: - If no response-time policy matches the request, the final action is NOCACHE. - If a matching response-time policy contains a CACHE action, the final action is CACHE, unless built-in policies override this policy. - If a matching response-time policy contains a NOCACHE action, the final action is NOCACHE. -If a matching response-time policy has a CACHE action but does not specify a content group, the final action is to CACHE the response in the Default content group, unless built-in policies override this policy.
INVAL Expires cached responses. Depending on how the policy and the content group are configured, all responses in one or more content groups are expired, or selected objects in the content group are expired. Note: You can specify INVAL actions in request-time policies only.

Bind points for a policy

You can bind the policy to one of the following bind points:

  • A global policy bank. These are the request-time default, request-time override, response-time default, and response-time override policy banks, as described in “Order of Policy Evaluation.”
  • A virtual server. Policies that you bind to a virtual server are processed after the global override policies and before the global default policies, as described in “Order of Policy Evaluation.” Note that when binding a policy to a virtual server, you bind it to either request-time or response-time processing.
  • An ad-hoc policy label. A policy label is a name assigned to a policy bank. In addition to the global labels, the integrated cache has two built-in custom policy labels:
    • _reqBuiltinDefaults. This policy label, by default, is invoked from the request-time default policy bank.
    • _resBuiltinDefaults. This policy label, by default, is invoked from the response-time default policy bank.

You can also define new policy labels. Policies bound to a user-defined policy label must be invoked from within a policy bank for one of the built-in bind points.

Important: You should bind a policy with an INVAL action to a request-time override or a response-time override bind point. To delete a policy, you must first unbind it.

Order of policy evaluation

For an advanced policy to take effect, you must ensure that the policy is invoked at some point during the NetScaler appliance’s processing of traffic. To specify the invocation time, you associate the policy with a bind point. The following are the bind points, listed in order of evaluation:

  • Request-time override. If a request matches a request-time override policy, by default request-time policy evaluation ends and the NetScaler appliance stores the action that is associated with the matching policy.
  • Request-time load balancing virtual server. If policy evaluation cannot be completed after all the request-time override policies are evaluated, the NetScaler appliance processes request-time policies that are bound to load balancing virtual servers. If the request matches one of these policies, evaluation ends and the NetScaler appliance stores the action that is associated with the matching policy.
  • Request-time content switching virtual server. Policies that are bound to this bind point are evaluated after request-time policies that are bound to load balancing virtual servers.
  • Request-time default. If policy evaluation cannot be completed after all request-time, virtual server-specific policies are evaluated, the NetScaler appliance processes request-time default policies. If the request matches a request-time default policy, by default request-time policy evaluation ends and the NetScaler appliance stores the action that is associated with the matching policy.
  • Response-time override. Similar to request-time override policy evaluation.
  • Response-time load balancing virtual server. Similar to request-time virtual server policy evaluation.
  • Response-time content switching virtual server. Similar to request-time virtual server policy evaluation.
  • Response-time default. Similar to request-time default policy evaluation.

You can associate multiple policies with each bind point. To control the order of evaluation of the policies associated with the bind point you configure a priority level. In the absence of any other flow control information, policies are evaluated according to priority level, starting with the lowest numeric priority value.

After all integrated caching policies have been evaluated, if there are conflicting actions specified in request-time and response-time policies.”

Note: Request-time policies for POST data or cookie headers must be invoked during request-time override evaluation, because the built-in request-time policies in the integrated cache return a NOCACHE action for POST requests and a MAY_NOCACHE action for requests with cookies. Note that you would associate MAY_CACHE or MAY_NOCACHE actions with a request-time policy that points to a parameterized content group. The response time policy determines whether the transaction is stored in the cache.

Configure a policy in the integrated cache

You configure new policies to handle data that the built-in policies cannot process. You configure separate policies for caching, preventing caching from occurring, and for invalidating cached data. Following are the main components of a policy for integrated caching:

  • Rule: A logical expression that evaluates an HTTP request or response.
  • Action: You associate a policy with an action to determine what to do with a request or response that matches the policy rule.

Content groups: You associate the policy with one or more content groups to identify where the action is to be performed.

To configure a policy for caching by using the command line interface

At the command prompt, type:

add cache policy <policyName> -rule <expression> -actionCACHE|MAY_CACHE|NOCACHE|MAY_NOCACHE [-storeInGroup <contentGroupName>] [-undefAction NOCACHE|RESET]

    > add cache policy image_cache -rule "http.req.url.contains(\"jpg\") || http.req.url.contains(\"jpeg\")" -action CACHE -storeingroup myImages_group -undefaction NOCACHE

    > add cache policy bugReportPolicy -rule "http.req.url.query.contains(\"IssuePage\")" -action CACHE -storeInGroup bugReportGroup

    > add cache policy my_form_policy -rule "http.req.header(\"Host\")contains(\"my.company.com\") && http.req.method.eq(\"GET\") && http.req.url.query.contains(\"v=7\")" -action CACHE -storeInGroup my_form_event

    > add cache policy viewproducts_policy –rule "http.req.url.contains(\"viewproducts.aspx\")" –action CACHE -storeInGroup Product_Details

To configure a policy for invalidation by using the command line interface

At the command prompt, type:

add cache policy <policyName> -rule <expression> -action INVAL [-invalObjects "\<contentGroupName1>[,<selectorName1>"]. . .]] | [-invalGroup \<contentGroupName1>[, <contentGroupName2>. . .]] [-undefAction NOCACHE|RESET]

`> add cache policy invalidation_events_policy -rule "http.req.header("Host")contains("my.company.com") && http.req.method.eq("GET") && http.req.url.query.contains("v=8") -action INVAL -invalObjects my_form_event -undefaction NOCACHE`

> add cache policy inval_all -rule "http.req.method.eq("POST") && http.req.url.contains("jpeg")" -action INVAL -invalGroups myImages_group myApps_group PDF_group

> add cache policy bugReportInvalidationPolicy -rule "http.req.url.query.contains(\"TransitionForm\")" -action INVAL -invalObjects bugReport

> add cache policy editproducts_policy –rule "http.req.url.contains(\"editproducts.aspx\")" –action INVAL -invalObjects "Product_Details,batchnum_sel" "Products_In_Depots,batchid_sel"

To configure a policy for caching or invalidation by using the GUI

Navigate to Optimization > Integrated Caching > Policies, and create the new policy.

Globally binding an integrated caching policy

When you globally bind a policy, it is available to all virtual servers on the NetScaler appliance.

To bind an integrated caching policy globally by using the command line interface

At the command prompt, type:

bind cache global <policy> -priority <positiveInteger> [-typeREQ_OVERRIDE|REQ_DEFAULT|RES_OVERRIDE|RES_DEFAULT] [-gotoPriorityExpression <expression>] [-invoke <labelType> <labelName>]

    > bind cache global myCachePolicy -priority 100 -type req_default

Note The type argument is optional for globally bound policies, to maintain backward compatibility with policies that you defined using earlier versions of the NetScaler appliance. If you omit the type, the policy is bound to REQ_DEFAULT or RES_DEFAULT, depending on whether the policy rule is a response-time or a request-time expression. If the rule contains both request time and response time parameters, it is bound to RES_DEFAULT. Following is an example of a binding that omits the type

Following is an example of a binding that omits the type.

> bind cache global myCache Policy 200

To bind an integrated caching policy globally by using the configuration utility

Navigate to Optimization > Integrated Caching, click Cache Policy Manager and bind policies by specifying the relevant bind point and connection type (Request/Response).

Bind an integrated caching policy to a virtual server

When you bind a policy to a virtual server, it is available only to requests and responses that match the policy and that flow through the relevant virtual server.

When using the configuration utility, you can bind the policy using the configuration dialog box for the virtual server. This enables you to view all of the policies from all NetScaler modules that are bound to this virtual server. You can also use the Policy Manager configuration dialog for the integrated cache. This enables you to view only the integrated caching policies that are bound to the virtual server.

To bind an integrated caching policy to a virtual server by using the command line interface

At the command prompt, type:

  • bind lb vserver <name>@ -policyName <policyName> -priority <positiveInteger> -type(REQUEST|RESPONSE)
  • bind cs vserver <name>@ -policyName <policyName> -priority <positiveInteger> -type(REQUEST|RESPONSE)

To bind an integrated caching policy to a virtual server by using the configuration utility (virtual server method)

  • CS Virtual Server - Navigate toTraffic Management > Content Switching > Virtual Servers, select the virtual server, and bind relevant cache policies.
  • LB Virtual Server - Navigate toTraffic Management > Load Balancing > Virtual Servers, select the virtual server, and bind relevant cache policies.

To bind an integrated caching policy to a virtual server by using the configuration utility (Policy Manager method)

Navigate to OptimizationIntegrated Caching, click Cache Policy Manager, and bind cache policies by specifying the relevant bind point and connection type.

Note You can bind cache policies to both LB virtual server and CS virtual server by selecting the appropriate bind point.

How to cache compressed and uncompressed versions of a file

By default, a client that can handle compression can be served uncompressed responses or compressed responses in gzip, deflate, compress, and pack200-gzip format. If the client handles compression, an Accept-Encoding:compression format header is sent in the request. The compression type accepted by the client must match the compression type of the cached object. For example, a cached .gzip file cannot be served in response to a request with an Accept-Encoding:deflate header.

A client that cannot handle compression is served a cache miss if the cached response is compressed.

For dynamic caching, you need to configure two content groups, one for compressed data and one for uncompressed versions of the same data. The following is an example of configuring the selectors, content groups, and policies for serving uncompressed files from the cache to clients that cannot handle compression, and serving compressed versions of the same files to client that can handle compression

    add cache selector uncompressed_response_selector http.req.url "http.req.header(\"Host\")"`

    `add cache contentGroup uncompressed_group -hitSelector uncompressed_responst_selector -invalSelector uncomp_resp_sel

    add cache policy cache_uncompressed -rule "HTTP.REQ.URL.CONTAINS(\"xyz\") && !HTTP.REQ.HEADER(\"Accept-Encoding\").EXISTS" -action CACHE -storeInGroup uncompressed_group

    bind cache global cache_uncompressed -priority 100 -gotoPriorityExpression END -type REQ_OVERRIDE

    add cache selector compressed_response_selector HTTP.REQ.URL "HTTP.REQ.HEADER(\"Host\")" "HTTP.REQ.HEADER(\"Accept-Encoding\")"

    add cache contentGroup compressed_group -hitSelector compressed_response_selector

    add cache policy cache_compressed -rule "HTTP.REQ.URL.CONTAINS(\"xyz\") && HTTP.REQ.HEADER(\"Accept-Encoding\").EXISTS" -action CACHE -storeInGroup compressed_group

    bind cache global cache_compressed -priority 200 -gotoPriorityExpression END -type REQ_OVERRIDE

Configure a policy bank for caching

All of the policies that are associated with a particular bind point are collectively known as a policy bank. In addition to configuring priority levels for policies in a bank, you can modify the order of evaluation order in a bank by configuring Goto expressions. You can further modify the evaluation order by invoking an external policy bank from within the current policy bank. You can also configure new policy banks, to which you assign your own labels. Because such policy banks are not bound to any point in the processing cycle, they can be invoked only from within other policy banks. For convenience, policy banks whose labels do not correspond to a built-in bind point are called policy labels.

In addition to controlling order of policy evaluation by binding the policy and assigning a priority level, as described in ”Binding Policies That Use the Default Syntax”, you can establish the flow within a bank of policies by configuring a Goto expression. A Goto expression overrides the flow that is determined by the priority levels. You can also control the evaluation flow by invoking an external policy bank after evaluating an entry in the current bank. Evaluation always returns to the current bank after evaluation has completed for the external bank.

The following table summarizes the entries to control evaluation in a policy bank.

Attribute Specifies
Name The name of a policy, or, to invoke another policy bank without evaluating the policy, the keyword NOPOLICY. You can specify NOPOLICY more than once in a policy bank, but you can specify a named policy only once.
Priority An integer. The lower the integer, the higher the priority.
Goto Expression Determines the next policy or policy bank to evaluate. You can provide one of the following values: 1. NEXT: Go to the policy with the next higher priority. 2. END: Stop evaluation. 3. USE_INVOCATION_RESULT: Applicable if this entry invokes another policy bank. If the final Goto in the invoked bank has a value of END, evaluation stops. If the final Goto is anything other than END, the current policy bank performs a NEXT. 4. Positive number: Priority number of the next policy to be evaluated. 5. Numeric expression: Expression that produces the priority number of the next policy to be evaluated. The Goto can only proceed forward in a policy bank. Omitting the Goto expression is the same as specifying END.
Invocation Type Designates a policy bank type. The value can be one of the following - 1. Request Vserver: Invokes request-time policies that are associated with a virtual server. 2. Response Vserver: Invokes response-time policies that are associated with a virtual server. 3. Policy label: Invokes another policy bank, as identified by the policy label for the bank.
Invocation Name Name of a virtual server or a policy label, depending on the value that you specified for the Invocation Type.

The integrated cache has two built-in policy labels, and you can configure additional policy labels:

_reqBuiltInDefaults: This policy label is invoked from the request-time default bind point. _resBuiltInDefaults: This policy label is invoked from the response-time default bind point.

To invoke a policy label in a caching policy bank by using the command line interface

At the command prompt, type:

bind cache policylabel <labelName> -policname<policyName> -priority<priority> [-gotoPriorityExpression <gotopriorityExpression>] [-invoke <labelType> <labelName>]

To invoke a policy label in a caching policy bank by using the GUI

  1. Navigate to Optimization > Integrated Caching, click Cache policy manager, and specify the relevant bind point (Override Global or Default Global) and connection type to view the list of policies bound to this bind point.
  2. If you want to invoke a policy label without evaluating a policy, click NOPOLICY.

    Note: To invoke an external policy bank, click the field in the Invoke Type column, and select the type of policy bank that you want to invoke at this point in the policy bank. This can be a global label or a virtual server bank. In the Invoke Name field, enter the label or virtual server name.

To invoke a caching policy label in a virtual server policy bank by using the command line interface

At the command prompt, type:

  • bind lb vserver <name>@ -policyName <policyName>|<NOPOLICY-CACHE> -priority<positiveInteger> -gotoPriorityExpression <expression> -type REQUEST|RESPONSE -invoke<labelType> <labelName>
  • bind cs vserver <name> -policyName <policyName>|<NOPOLICY-CACHE> -priority<positiveInteger> -gotoPriorityExpression <expression> -type REQUEST|RESPONSE -invoke<labelType> <labelName>

To invoke a caching policy label in a virtual server policy bank by using the GUI

  1. Navigate to Traffic Management > Load Balancing/Content Switching > Virtual Servers, select the virtual server, and click Policies.
  2. If you are configuring an existing entry in this bank, skip this step. If you are adding a new policy to this policy bank, or you want to use the “dummy” NOPOLICY entry, click Add, and do one of the following:
    • To configure a new policy, click Cache and configure the new policy as described in “Configuring a Policy in the Integrated Cache.”
    • To invoke a policy bank without processing a policy a rule, select the NOPOLICY-CACHEoption.

Note To invoke an external policy bank, click the field in the Invoke Type column, and select the type of policy bank that you want to invoke at this point in the policy bank. This can be a global label or a virtual server bank. In the Invoke Name field, enter the label or virtual server name.

Configure a policy label in an integrated cache

In addition to configuring policies in a policy bank for one of the built-in bind points or a virtual server, you can create caching policy labels and configure banks of policies for these new labels.

A policy label for the integrated cache can be invoked only from one of the bind points that you can view in the Policy Manager in the Integrated Caching details pane (request override, request default, response override, or response default) or the built-in policy labels_reqBuiltinDefaultsand_resBuiltinDefaults. You can invoke a policy label any number of times unlike a policy, which can only be invoked once.

The configuration utility provides an option to rename a policy label. Renaming a policy label does not affect the process of evaluation of the policies bound to the label.

Note: You can use the NOPOLICY “dummy” policy to invoke any policy label from another policy bank. The NOPOLICY entry is a placeholder that does not process a rule.

To configure a policy label for caching by using the command line interface

At the command prompt, type the following command to create a policy label and verify the configuration:

  • add cache policylabel <labelName> -evaluates (REQ|RES)
  • show cache policylabel <labelName>

Invoke this policy label from a policy bank. For more information, see “Configuring a Policy Bank for Caching.”

To configure a policy label for caching by using the GUI

Navigate to OptimizationIntegrated Caching > Policy Labels, add a policy label, and bind the cached policies.

Note: To ensure that the NetScaler processes the policy label at the right time, configure an invocation of this label in one of the policy banks that are associated with the built-in bind points.

To rename a policy label by using the GUI

Navigate to OptimizationIntegrated Caching > Policy Labels select the policy label, and rename.

Unbind and delete an integrated caching policy and policy label

You can unbind a policy from a policy bank, and you can delete it. To delete the policy, you must first unbind it. You can also remove a policy label invocation and delete a policy label. To delete the policy label, you must first remove any invocations that you have configured for the label.

You cannot unbind or delete the labels for the built-in bind points (request default, request override, response default, and response override).

To unbind a global caching policy by using the command line interface

At the command prompt, type:

unbind cache global <policy>

To unbind a virtual server-specific caching policy by using the command line interface

At the command prompt, type:

(unbind lb vserver|unbind cs vserver) <vserverName> -policyName <policyName> -type(REQUEST|RESPONSE)

To delete a caching policy by using the command line interface

At the command prompt, type:

rm cache policy <policyName>

To unbind a caching policy by using the configuration utility

Navigate to Optimization > Integrated Caching, click Cache Policy Manager, and unbind policies by specifying the relevant bind point and connection type (Request/Response).

To delete a policy label invocation by using the configuration utility

  1. Navigate to Optimization > Integrated Caching, click Cache policy manager, and specify the relevant bing point (LB virtual server or CS virtual server) and connection type to view the list of cache policies bound to this virtual server.
  2. In the policy Invoke column, clear the entry.