ADC

Configure selectors and basic content groups

August 1, 2023

Contributed by:

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 requests 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 Citrix® ADC 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 an 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\> ... )

For information about configuring the expression or expressions, see To configure a selector expression by using the command line interface.

>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\")"

<!--NeedCopy-->

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 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 contain 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 request from a content group

A user enters search criteria for an item, such as a bug report, and clicks the Find button in an HTML form.
The browser issues one or more HTTP GET requests. These requests contain parameters (for example, the bug owner, bug ID, and so on).
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.
The content group looks for appropriate objects in the content group, based on criteria that you configure in a selector.

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

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

A user modifies data (for example, the user modifies the bug report and clicks the Submit button).
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.
The NetScaler appliance matches the requests against invalidation policies. Typically, these policies are configured to detect the HTTP POST method.
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.

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 more 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, the heuristic expiry specifies the mount of time taken from when the response was modified (calculated as the 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 must 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 some 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 overrides any expiration information in the response itself.

On download. The option Expire After Complete Response Received expires a response when 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 more 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 causes 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, the NetScaler appliance uses the “weak positive” value.
- For negative responses that lack an Expires or Cache-Control header, the 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:

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 and 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 <URL> -host <hostName> [-port <port>] [-groupName<contentGroupName>] [-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

Navigate to Optimization > Integrated Caching > Content Groups.
In the 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 Flush and 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 the 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 Deltas 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 Caching > Content Groups, select the content group, and delete.

The official version of this content is in English. Some of the Cloud Software Group documentation content is machine translated for your convenience only. Cloud Software Group has no control over machine-translated content, which may contain errors, inaccuracies or unsuitable language. No warranty of any kind, either expressed or implied, is made as to the accuracy, reliability, suitability, or correctness of any translations made from the English original into any other language, or that your Cloud Software Group product or service conforms to any machine translated content, and any warranty provided under the applicable end user license agreement or terms of service, or any other agreement with Cloud Software Group, that the product or service conforms with any documentation shall not apply to the extent that such documentation has been machine translated. Cloud Software Group will not be held responsible for any damage or issues that may arise from using machine-translated content.

Configure selectors and basic content groups

August 1, 2023

Contributed by:

August 1, 2023

Contributed by:

Configure selectors and basic content groups

Advantages of selectors

Use parameters Instead of selectors

Configure a selector

Content groups

Set up a basic content group

Expire or flush cached objects

How expiration methods are applied

Expire a content group by manual method

Configure periodic expiration of a content group

Expire individual responses

Flushing responses in a content group

Deleting a content group

In this article