Configure cookies, headers, and polling

This topic describes the procedures to configure how the cache manages cookies, HTTP headers, and origin server polling, including modifying default behavior that causes the cache to diverge from documented standards, overriding HTTP headers that might cause cacheable content to not be stored in the cache, and configuring the cache to always poll the origin for updated content under specialized circumstances.

Divergence of cache behavior from the standards

By default, the integrated cache conforms to the following standards:

  • RFC 2616, “Hypertext Transfer Protocol HTTP/1.1”
  • The caching behaviors described in RFC 2617, “HTTP Authentication: Basic and Digest Access Authentication”
  • The caching behavior described in RFC 2965, “HTTP State Management Mechanism”

The built-in policies and the Default content group attributes ensure conformance with most of these standards.

The default integrated cache behavior diverges from the specifications as follows:

  • There is limited support for the Vary header. By default, any response containing a Vary header is considered to be non-cacheable unless it is compressed. A compressed response contains Content-Encoding: gzip, Content-Encoding: deflate, or Content-Encoding: pack200-gzip and is cacheable even if it contains the Vary: Accept-Encoding header.
  • The integrated cache ignores the values of the headers Cache-Control: no-cache and Cache-Control: private. For example, a response that contains Cache-Control: no-cache=”Set-Cookie” is treated as if the response contained Cache-Control: no-cache. By default, the response is not cached.
  • An image (Content-Type = image/*) is always considered cacheable even if an image response contains Set-Cookie or Set-Cookie2 headers, or if an image request contains a Cookie header. The integrated cache removes Set-Cookie and Set-Cookie2 headers from a response before caching it. This diverges from RFC 2965. You can configure RFC-compliant behavior as follows:
add cache policy rfc_compliant_images_policy -rule "http.res.header.set-cookie2.exists || http.res.header.set-cookie.exists" -action NOCACHE


bind cache global rfc_compliant_images_policy -priority 100 -type REQ_OVERRIDE
  • The following Cache-Control headers in a request force an RFC-compliant cache to reload a cached response from the origin server:

Cache-control: max-age=0

Cache-control: no-cache

To guard against Denial of Service attacks, this behavior is not the default. For more information, see “Inserting a Cache-Control Header” section.

  • By default, the caching module considers a response to be cacheable unless a response header states otherwise. To make this behavior RFC 2616 compliant, set -weakPosRelExpiry and -weakNegResExpiry to 0 for all content groups.

Remove cookies from a response

Cookies are often personalized for a user, and typically should not be cached. The Remove Response Cookies parameter removes Set-Cookie and Set-Cookie2 headers before caching a response. By default, the Remove Response Cookies option for a content group prevents caching of responses with Set-Cookie or Set-Cookie2 headers.

Note: When images are cached, the built-in behavior is to remove the Set-Cookie and Set-Cookie2 headers before caching, no matter how the content group is configured. Note: Citrix recommends that you accept the default Remove Response Cookies for every content group that stores embedded responses, for example, images.

To configure Remove Response Cookies for a content group by using the command line interface:

At the command prompt, type:

set cache contentgroup <name> -removeCookies YES

To configure Remove Response Cookies for a content group by using the configuration utility

  1. Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
  2. On Others tab, in the Settings group, select Remove response cookies option.

Inserting HTTP headers at response time

The integrated cache can insert HTTP headers in responses that result from cache hits. The NetScaler® appliance does not alter headers in responses that result from cache misses.

The following table describes headers that you can insert in a response. |Header|Specification| |— |— | |Age|Provides the age of the response in seconds, calculated from the time the response was generated at the origin server. By default, the cache inserts an Age header for every response that is served from the cache.| |via|Lists protocols and recipients between the start and end points for a request or a response. The NetScaler appliance inserts a Via header in every response that it serves from the cache. The default value of the inserted header is “NS-CACHE-9.2:last octet of the NetScaler IP address.” | |ETag|The cache supports response validation using Last-Modified and ETag headers to determine if a response is stale. The cache inserts an ETag in a response only if it caches the response and the origin server has not inserted its own ETag header. The ETag value is an arbitrary unique number. The ETag value for a response changes if it is refreshed from the origin server, but it stays the same if the server sends a 304 (object not updated) response.Origin servers typically do not generate validators for dynamic content because dynamic content is considered non-cacheable. You can override this behavior. With ETag header insertion, the cache is permitted to not serve full responses. Instead, the user agent is required to cache the dynamic response sent by the integrated cache the first time. To force a user agent to cache a response, you configure the integrated cache to insert an ETag header and replace the origin-provided Cache-Control header.| |Cache-Control|The NetScaler appliance typically does not modify cacheability headers in responses that is serves from the origin server. If the origin server sends a response that is labeled as non-cacheable, the client treats the response as non-cacheable even if the NetScaler appliance caches the response. To cache dynamic responses in a user agent, you can replace Cache-Control headers from the origin server. This applies only to user agents and other intervening caches. They do not affect the integrated cache. For more information, see “Inserting a Cache-Control Header” section.|

Insert an age, via, or ETag header

The following procedures describe how to insert Age, Via, and ETag headers.

To insert an Age, Via, or Etag header by using the command line interface:

At the command prompt, type:

set cache contentgroup <name> -insertVia YES -insertAge YES -insertETag YES

To insert an Age, Via, or Etag header by using the GUI

  1. Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
  2. On Others tab, in the HTTP Header Insertions group, select the Via, Age, or ETag options, as appropriate.
  3. The values for the other header types are calculated automatically. Note that you configure the Via value in the main settings for the cache.

Insert a cache-control header

When the integrated cache replaces a Cache-Control header that the origin server inserted, it also replaces the Expires header. The new Expires header contains an expiration time in the past. This ensures that HTTP/1.0 clients and caches (that do not understand the Cache-Control header) do not cache the content.

To insert a cache-control header by using the command line interface

At the command prompt, type:

set cache contentgroup <name> -cacheControl <value>

To insert a cache-control header by using the configuration utility

  1. Navigate to Optimization > Integrated Caching > Content Groups, and
    1. Click Expiry Method tab, clear the heuristic and default expiry settings and set the relevant value in Expire content after text box.
    2. Click Others tab and type the header you want to insert in the Cache-Control text box. Alternatively, click Configure to set the Cache-Control directives in cached responses.

Ignoring cache-control and pragma headers in requests

By default, the caching module processes Cache-Control and Pragma headers. The following tokens in Cache-Control headers are processed as described in RFC 2616.

  • max-age
  • max-stale
  • only-if-cached
  • no-cache

A Pragma: no-cache header in a request is treated in the same way as a Cache-Control: no-cache header.

If you configure the caching module to ignore Cache-Control and Pragma headers, a request that contains a Cache-Control: No-Cache header causes the NetScaler appliance to retrieve the response from the origin server, but the cached response is not updated. If the caching module processes Cache-Control and Pragma headers, the cached response is refreshed.

The following table summarizes the implications of various settings for these headers and the Ignore Browser’s Reload Request setting.

Setting for Ignore Cache-Control and Pragma Headers Setting for Ignore Browser’s Reload Request Outcome
Yes Yes or No Ignore the Cache-Control and Pragma headers from the client, including the Cache-Control: no-cache directive.
No Yes The Cache-Control: no-cache header produces a cache miss, but a response that is already in the cache is not refreshed.
No No A request that contains a Cache-Control: no-cache header causes a cache miss and the stored response is refreshed.

To ignore Cache-Control and Pragma headers in a request by using the command line interface

At the command prompt, type:

set cache contentgroup <name> -ignoreReqCachingHdrs YES

To ignore browser reload requests by using the command line interface

At the command prompt, type:

set cache contentgroup <name> -ignoreReloadReq NO

Note: By default, the -ignoreReloadReq parameter is set to YES.

To ignore Cache-Control and Pragma headers in a request by using the GUI

  1. Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
  2. On Others tab, in the Settings group, select Ignore Cache-control and Pragma Headers in Requests option.

Example of a policy to ignore Cache-Control headers

In the following example, you configure a request-time override policy to cache responses that contain Content-type: image/* regardless of the Cache-Control header in the response.

To configure a request-time override policy to cache all responses with image/*

Flush the cache using the Invalidate All option.

For more information, see “Flushing Responses in a Content Group.”

Configure a new cache policy, and direct the policy to a particular content group. For more information, see “Configuring a Policy in the Integrated Cache.”

Ensure the content group that the policy uses is configured to ignore Cache-Control headers, as described in “Ignoring Cache-Control and Pragma Headers in Requests.”

Bind the policy to the request-time override policy bank.

For more information, see Globally Binding an Integrated Caching Policy topic.

Polling the origin server every time a request is received

You can configure the NetScaler appliance to always consult the origin server before serving a stored response. This is known as Poll Every Time (PET). When the NetScaler appliance consults the origin server and the PET response has not expired, a full response from the origin server does not overwrite cached content. This property is useful when serving client-specific content.

After a PET response expires, the NetScaler appliance refreshes it when the first full response arrives from the origin server.

The Poll Every Time (PET) function works as follows:

For a cached response that has validators in the form of an ETag or a Last-Modified header, if the response expires it is automatically marked PET and cached.

You can configure PET for a content group.

If you configure a content group as PET, every response in the content group is marked PET. The PET content group can store responses that do not have validators. Responses that are automatically marked PET are always expired. Responses that belong to a PET content group can expire after a delay, based on how you configure the content group.

Two types of requests are affected by polling:

  • Conditional Requests: A client issues a conditional request to ensure that the response that it has is the most recent copy. A user-agent request for a cached PET response is always converted to a conditional request and sent to the origin server. A conditional request has validators in If-Modified-Since or If-None-Match headers. The If-Modified-Since header contains the time from the Last-Modified header. An If-None-Match header contains the response’s ETag header value. If the client’s copy of the response is fresh, the origin server replies with 304 Not Modified. If the copy is stale, a conditional response generates a 200 OK that contains the entire response.
  • Non-Coditional Requests: A non-conditional request can only generate a 200 OK that contains the entire response.
Origin Server Response Action
Send the full response The origin server sends the response as-is to the client. If the cached response has expired, it is refreshed.
304 Not Modified The following header values in the 304 response are merged with the cached response and the cached response is served to the client: Date, Expires, Age, Cache-Control header Max-Age, and S-Maxage tokens
401 Unauthorized; 400 Bad Request; 405 Method Not Allowed; 406 Not Acceptable; 407 Proxy Authentication Required The origin’s response is served as-is to the client. The cached response is not changed.
Any other error response, for example, 404 Not Found The origin’s response is served as-is to the client. The cached response is removed.

Note The Poll Every Time parameter treats the affected responses as non-storable.

To configure poll every time by using the command line interface

At the command prompt, type:

add cache contentgroup <contentGroupName > -pollEveryTime YES

To configure poll every time by using the GUI

  1. Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
  2. On Others tab, in the Settings group, select Poll every time (validate cached content with origin for every request) option.

PET and client-specific content

The PET function can ensure that content is customized for a client. For example, a Web site that serves content in multiple languages examines the Accept-Language request header to select the language for the content that it is serving. For a multi-language Web site where English is the predominant language, all English language content can be cached in a PET content group. This ensures that every request goes to the origin server to determine the language for the response. If the response is English, and the content has not changed, the origin server can serve a 304 Not Modified to the cache.

The following example shows commands to cache English responses in a PET content group, configure a named expression that identifies English responses in the cache, and configure a policy that uses this content group and named expression. Bold is used for emphasis:

add cache contentgroup EnglishLanguageGroup -pollEveryTime YES
add expression containsENExpression –rule "http.res.header(\\"Content-Language\\").contains(\\"en\\")"
add cache policy englishPolicy -rule containsENExpression -action CACHE -storeInGroup englishLanguageGroup
bind cache policy englishPolicy -priority 100 -precedeDefRules NO

PET and authentication, authorization, and auditing

Outlook Web Access (OWA) is a good example of dynamically generated content that benefits from PET. All mail responses (*.EML objects) have an ETag validator that enables them to be stored as PET responses.

Every request for a mail response travels to the origin server, even if the response is cached. The origin server determines whether the requestor is authenticated and authorized. It also verifies that the response exists in the origin server. If all results are positive, the origin server sends a 304 Not Modified response.