Configure selectors and basic content groups

You can configure selectors and apply them to content groups. When you add a selector to one or more content groups, you specify whether the selector is to be used for identifying cache hits or identifying cached objects to be invalidated (expired). Selectors are optional. Alternatively, you can configure content groups to use hit parameters and invalidation parameters. However, Citrix recommends that you configure selectors.

After configuring selectors, or deciding to use parameters instead, you are ready to set up a basic content group. After creating the basic content group, you need to decide how objects should be expired from the cache, and configure cache expiration. You can further modify the cache as described in “Improving Cache Performance” and “Configuring Cookies, Headers, and Polling”, but you might first want to configure caching policies.

Note

Content group parameters and selectors are used only at request time, and you typically associate them with policies that use MAY_CACHE or MAY_NOCACHE actions.

Advantages of selectors

A selector is a filter that locates particular objects in a content group. If you do not configure a selector, the appliance appliance looks for an exact match in the content group. This can lead to multiple copies of the same object residing in a content group. For example, a content group that does not have a selector may need to store URLs for host1.domain.com\mypage.htm, host2.domain.com\mypage.htm, and host3.domain.com\mypage.htm. In contrast, a selector can match just the URL (mypage.html, using the expression http.req.url) and the domain (.com, using the expression http.req.hostname.domain), allowing the requests to be satisfied by the same URL.

Selector expressions can perform simple matching of parameters (for example, to find objects that match a few query string parameters and their values). A selector expression can use Boolean logic, arithmetic operations, and combinations of attributes to identify objects (for example, segments of a URL stem, a query string, a string in a POST request body, a string in an HTTP header, a cookie). Selectors can also perform programmatic functions to analyze information in a request. For example, a selector can extract text in a POST body, convert the text into a list, and extract a specific item from the list.

For more information about expressions and what you can specify in an expression, see ”Policies and Expressions.”

Use parameters Instead of selectors

Although Citrix recommends the use of selectors with a content group, you can instead configure hit parameters and invalidation parameters. For example, suppose that you configure three hit parameters in a content group for bug reports: BugID, Issuer, and Assignee. If a request contains BugID=456, with Issuer=RohitV and Assignee=Robert, the NetScaler appliance can serve responses that match these parameter-value pairs.

Invalidation parameters in a content group expire cached entries. For example, suppose that BugID is ab invalidation parameter and a user issues a POST request to update a bug report. An invalidation policy directs the request to this content group, and the invalidation parameter for the content group expires all cached responses that match the BugID value. (The next time a user issues a GET request for this report, a caching policy can enable the NetScaler appliance to refresh the cached entry for the report from the origin server.)

Note that the same parameter can be used as a hit parameter or an invalidation parameter.

Content groups extract request parameters in the following order:

  • URL query
  • POST body
  • Cookie header

After the first occurrence of a parameter, regardless of where it occurred in the request, all its subsequent occurrences are ignored. For example, if a parameter exists both in the URL query and in the POST body, only the one in the URL query is considered.

If you decide to use hit and invalidation parameters for a content group, configure the parameters when you configure the content group.

Note: Citrix recommends that you use selectors rather than parameterized content groups, because selectors are more flexible and can be adapted to more types of data.

Configure a selector

A content group can use a hit selector to retrieve cache hits or use an invalidation selector to expired cached objects and fetch new ones from the origin server.

A selector contains a name and a logical expression, called an advanced expression.

For more information about advanced expressions, see “Policies and Expressions.”

To configure a selector, you assign it a name and enter one or more expressions. As a best practice, a selector expression should include the URL stem and host, unless there is a strong reason to omit them.

To configure a selector by using the CLI

At the command prompt, type:

add cache selector <selectorName> ( <rule> ... )

>add cache selector product_selector "http.req.url.query.value("ProductId")" "http.req.url.query.value("BatchNum")" "http.req.url.query.value("depotLocation")"

> add cache selector batch_selector "http.req.url.query.value("ProductId")" "http.req.url.query.value("BatchId")" "http.req.url.query.value("depotLocation")"

> add cache selector product_id_selector "http.req.url.query.value("ProductId")"

> add cache selector batchnum_selector "http.req.url.query.value("BatchNum")" "http.req.url.query.value("depotLocation")"

> add cache selector batchid_selector "http.req.url.query.value("depotLocation")" "http.req.url.query.value("BatchId")"

To configure a selector by using the GUI

Navigate to Optimization > Integrated Caching > Cache Selectors, and add the cache selector.

Content groups

A content group is a container for cached objects that can be served in a response. When you first enable the integrated cache, cacheable objects are stored in a content group named Default. You can create new content groups that have unique properties. For example, you can define separate content groups for image data, bug reports, and stock quotes, and you can configure the stock quote content group to be refreshed more often than the other groups.

You can configure expiration of an entire content group or selected entries in a content group.

The data in a content group can be static or dynamic, as follows:

  • Static content groups. Finds an exact match between the URL stem and host name on the request and the URL stem and host name of the response.
  • Dynamic content groups. Looks for objects that contains particular parameter-value pairs, arbitrary strings, or string patterns. Dynamic content groups are useful when caching data that is updated frequently (for example, a bug report or a stock quote).

Serve a hit from a content group

  1. A user enters search criteria for an item, such as a bug report, and clicks the Find button in an HTML form.
  2. The browser issues one or more HTTP GET requests. These requests contain parameters (for example, the bug owner, bug ID, and so on).
  3. When the NetScaler appliance receives the requests, it searches for a matching policy, and if it finds a caching policy that matches these requests, it directs the requests to a content group.
  4. The content group looks for appropriate objects in the content group, usually based on criteria that you configure in a selector.

For example, the content group can retrieve responses that match NameField=username and BugID=ID.

  1. If it finds matching objects, the NetScaler appliance can serve them to the user’s browser, where they are assembled into a complete response (for example, a bug report).

Invalidate an object in a content group

  1. A user modifies data (for example, the user modifies the bug report and clicks the Submit button).
  2. The browser sends this data in the form of one or more HTTP requests. For example, it can send a bug report in the form of several HTTP POST requests that contain information about the bug owner and bug ID.
  3. The NetScaler appliance matches the requests against invalidation policies. Typically, these policies are configured to detect the HTTP POST method.
  4. If the request matches an invalidation policy, the NetScaler appliance searches the content group that is associated with this policy, and expires responses that match the configured criteria for invalidation.

For example, an invalidation selector can find responses that match NameField=username and BugID=ID.

  1. The next time the NetScaler appliance receives a GET request for these responses, it fetches refreshed versions from the origin server, caches the refreshed responses, and serves these responses to the user’s browser, where they are assembled into a complete bug report.

Set up a basic content group

By default, all cached data is stored in the default content group. You can configure additional content groups and specify these content groups in one or more policies.

You can configure content groups for static content, and you must configure content groups for dynamic content. You can modify the configuration of any content group, including the default group.

To set up a basic content group by using the command line interface

At the command prompt, type:

add cache contentgroup <name> (-hitSelector <hitSelectorName> -invalSelector <invalidationSelectorName> | -hitParams <hitParamName> -invalParams<invalidationParamName>) -type <type> [-relExpiry <sec> | -relExpiryMilliSec <msec>] [-heurExpiryParam <positiveInteger>]

> add cache contentgroup Products_Details –hitSelector product_selector –invalSelector id_selector

> add cache contentgroup bugrep -hitParams IssuePage RecordID Template TableId -invalParams RecordID -relExpiry 864000

To set up a basic content group by using the GUI

Navigate to Optimization > Integrated Caching > Content Groups, and create the content group.

Expire or flush cached objects

If a response does not have an Expires header or a Cache-Control header with an expiration time (Max-Age or Smax-Age), you must expire objects in a content group by using one of the following methods:

  • Configure content group expiration settings to determine whether and how long to keep the object.
  • Configure an invalidation policy and action for the content group. For more information, see “Configuring Policies for Caching and Invalidation.”
  • Expire the content group or objects within it manually.

After a cached response expires, the NetScaler appliance refreshes it the next time the client issues a request for the response. By default, when the cache is full, the NetScaler appliance replaces the least recently used response first.

The following list describes methods for expiring cached responses using settings for a content group. Typically, these methods are specified as a percent or in seconds:

  • Manual. Manually invalidate all responses in a content group or all responses in the cache.
  • Response-based. Specific expiration intervals for positive and negative responses. Response-based expiry is considered only if the Last-Modified header is missing in the response.
  • Heuristic expiry. For responses that have a Last-Modified header, heuristic expiry is a percentage of the time since the response was modified (calculated as current time minus the Last-Modified time, multiplied by the heuristic expiry value). For example, if a Last-Modified header indicates that a response was updated 2 hours ago, and the heuristic expiry setting is 10%, cached objects expire after 0.2 hours. This method assumes that frequently updated responses need to be expired more often.
  • Absolute or relative. Specify an exact (absolute) time when the response expires every day, in HH:MM format, local time or GMT. Local time may not work in all time zones.

Relative expiration specifies a number of seconds or milliseconds from the time a cache miss causes a trip to the origin server to the expiration of the response. If you specify relative expiration in milliseconds, enter a multiple of 10. This form of expiration works for all positive responses. Last-Modified, Expires, and Cache-Control headers in the response are ignored.

Absolute and relative expiration override any expiration information in the response itself.

  • On download. The option Expire After Complete Response Received expires a response as soon as it is downloaded. This is useful for frequently updated responses, for example, stock quotes. By default, this option is disabled.

Enabling both Flash Cache and Expire After Complete Response Received accelerates the performance of dynamic applications. When you enable both options, the NetScaler appliance fetches only one response for a block of simultaneous requests.

  • Pinned. By default, when the cache is full the NetScaler appliance replaces the least recently used response first. The NetScaler appliance does not apply this behavior to content groups that are marked as pinned.

If you do not configure expiration settings for a content group, the following are additional options for expiring objects in the group:

  • Configure a policy with an INVAL action that applies to the content group.
  • Enter the names of content groups when configuring a policy that uses an INVAL action.

How expiration methods are applied

Expiration works differently for positive and negative responses. Positive and negative responses are described in the table, Expiration of Positive and Negative Responses mentioned below.

The following are rules of thumb for understanding the expiration method that is applied to a content group:

  • You can control whether the NetScaler appliance evaluates response headers when deciding whether to expire an object.
  • Absolute and relative expiration cause the NetScaler appliance to ignore the response headers (they override any expiration information in the response).
  • Heuristic expiration settings and “Weak Positive” and “Weak Negative” expiration (labeled as Default values in the configuration utility) cause the NetScaler appliance to examine the response headers. These settings work together as follows:
    • The value in an Expires or Cache-Control header overrides these content group settings.
    • For positive responses that lack an Expires or Cache-Control header but have a Last-Modified header, the NetScaler appliance compares heuristic expiration settings with the header value.
    • For positive responses that lack an Expires, Cache-Control, or Last-Modified header, NetScaler appliance uses the “weak positive” value.
    • For negative responses that lack an Expires or Cache-Control header, NetScaler appliance uses the “weak negative” value.

The following table describes how these methods are applied.

Response Type

Expiration Header Type

Content Group Setting

Period the Object Remains in the Cache

Positive

Any header

Expire Content After (relExpiry) with no other settings

Use the value of the Expire Content After setting.

Positive

Any header

Expire Content At (absExpiry) with no other settings

Subtract current date from the value of the Expire Content At setting.

Positive

Any header

Expire Content After (relExpiry) and Expire content at (absExpiry)

Use the smaller of the two values for the content group settings. See the previous rows in this table.

Positive

Last-Modified (with any other headers)

Heuristic (heurExpiry Param) with any other setting

Subtract the Last-Modified date from the current date, multiply the result by the value of the heuristic expiry setting, and then divide by 100.

Positive

Last-Modified (with any other headers)

Default (positive) (weakPosRel Expiry) and no other setting

Use the value of the Default (positive) expiry setting.

Positive

Expires or Cache-Control: Max-Age header is present

Last-Modified header is absent

Heuristic (heurExpiry Param), Default (positive) (weakPosRel Expiry), or both

Subtract the current date from the Expires or the Cache-Control:Max-Age date.

Positive

no caching headers

Default (positive) (weakPosRel Expiry) and any other expiration setting

Use the value of the Default (positive) setting.

Positive

no caching headers

Heuristic (heurExpiry Param) is present

Default (positive) (weakPosRel Expiry) setting is absent

If the Last-Modified header is absent, the response is not cached or it is cached with an Already Expired status.

If the Last-Modified header is present, use the heuristic expiry value.

Negative

Expires or Cache-Control:Max-Age

Expire Content After (relExpiry), Expire Content At (absExpiry), or both settings

Subtract the current date from the value of the Expires header, or use the value of the Cache-Control:Max-Age header.

Negative

Expires or Cache-Control headers are absent

Expire Content After (relExpiry), Expire Content At (absExpiry), or both settings

Response is not cached, or is cached with an Already Expired status.

Negative

Expires or Cache-Control:Max-Age

Any setting

Subtract the current date from the Expires or Cache-Control:Max-Age date.

Negative

Expires and Cache-Control:Max-Age headers are absent

Default (negative) (weakNegRel Expiry)

Use the value of the Default (negative) setting.

Negative

Expires and Cache-Control:Max-Age headers are absent

Any setting other than Default (negative) (weakNegRel Expiry)

Object is not cached or is cached with an Already Expired status.

Expire a content group by manual method

You can manually expire all of the entries in a content group.

To manually expire all responses in a content group by using the command line interface

At the command prompt, type:

expire cache contentGroup <name>

To manually expire all responses in a content group by using the GUI

Navigate to Optimization > Integrated Caching > Content Groups, select the content group, and click Invalidate to expire all the responses in a content group.

To manually expire all responses in the cache by using the GUI

Navigate to Optimization > Integrated Caching > Content Groups, and click Invalidate All to expire all the responses in cache.

Configure periodic expiration of a content group

You can configure a content group so that it performs selective or full expiration of its entries. The expiration interval can be fixed or relative.

To configure content group expiration by using the command line interface

At the command prompt, type:

set cache contentgroup <name> (-relExpiry|-relExpiryMilliSec|-absExpiry|-absExpiryGMT| -heurExpiryParam|-weakPosRelExpiry|-weakNegRelExpiry| -expireAtLastBye) <expirationValue>

To configure content group expiration by using the GUI

Navigate to Optimization > Integrated Caching > Content Groups, select the content group, and specify expiry method.

Expire individual responses

Expiring a response forces the NetScaler appliance to fetch a refreshed copy from the origin server. Responses that do not have validators, for example, ETag or Last-Modified headers, cannot be revalidated. As a result, flushing these responses has the same effect as expiring them.

To expire a cached response in a content group for static data, you can specify a URL that must match the stored URL. If the cached response is part of a parameterized content group, you must specify the group name as well as the exact URL stem. The host name and the port number must be the same as in the host HTTP request header of the cached response. If the port is not specified, port 80 is assumed.

To expire individual responses in a content group by using the command line interface

At the command prompt, type:

expire cache object -url  -host  [-port ] \[-groupName] [-httpMethod GET|POST]

To expire individual responses in a content group by using the CLI

At the command prompt, type the following command:

expire cache object -locator <positiveInteger>

To expire a cached response by using the GUI

Navigate to Optimization > Integrated Caching > Cached Objects, select the cached response, and expire.

To expire a response by using the GUI

Navigate to Optimization > Integrated Caching > Cached Objects, click Search and, set the search criteria to find the required cached response and expire.

Flushing responses in a content group

You can remove, or flush, all responses in a content group, some responses in a group, or all responses in the cache. Flushing a cached response frees up memory for new cached responses.

Note: To flush responses for more than one object at a time, use the configuration utility method. The command line interface does not offer this option.

To flush responses from a content group by using the command line interface

At the command prompt, type:

flush cache contentGroup <name> [-query <queryString> | [-selectorValue <selectorExpressionIDList> -host <hostName>]]

To flush responses from a content group by using the GUI

  1. Navigate OptimizationIntegrated Caching > Content Groups.
  2. In details pane, flush the responses as follows:
    • To flush all responses in all content groups, click Invalidate All, and flush all the responses.
    • To flush responses in a particular content group, select the content group, click Invalidate, and flush all the responses.

Note: If this content group uses a selector, you can selectively flush responses by entering a string in the Selector value text box, entering a host name in the Host text box. Then click Flushand OK. The Selector value can be a query string of up to 2319 characters that is used for parameterized invalidation.

If the content group uses an invalidation parameter, you can selectively flush responses by entering a string in the Query field.

If the content group uses an invalidation parameter and Invalidate objects belonging to target host is configured, enter strings in the Query and Host fields.

To flush a cached response by using the command line interface

At the command prompt, type:

flush cache object -locator <positiveInteger> | -url <URL> -host <hostName> [-port <port>] [-groupName <contentGroupName>] [-httpMethod GET|POST]

To flush a cached response by using the GUI

Navigate to Optimization > Integrated Caching > Cached Objects, select the cached object, and flush.

Deleting a content group

You can remove a content group if it is not used by any policy that stores responses in the cache. If the content group is bound to a policy, you must first remove the policy. Removing the content group removes all responses stored in that group.

You cannot remove the Default, BASEFILE, or Deltajs group. The Default group stores cached responses that do not belong in any other content group.

To delete a content group by using the command line interface

At the command prompt, type:

rm cache contentgroup <name>

To delete a content group by using the GUI

Navigate to Optimization > Integrated CachingContent Groups, select the content group, and delete.

Configure selectors and basic content groups