Configure cookies, headers, and polling
This topic explains how to configure cache manages cookies, HTTP headers, and origin server polling. This includes modifying the 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 cache to always poll the origin for updated content.
Related information
Divergence of cache behavior from the standards
By default, the integrated cache adheres to the following RFC standards:
-
RFC 2616, “HTTP 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 specification as follows:
-
There is a 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.
-
By default, the caching module considers a response to be cacheable unless a response header state otherwise. To make this behavior RFC 2616 compliant, set
-weakPosRelExpiryand-weakNegResExpiryto 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.
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
Configure Remove Response Cookies for a content group by using the NetScaler GUI
-
Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
-
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 requests. 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-10.0: last octet of the NetScaler IP address.” For more information, see "Configuring Global Attributes for Caching." |
Tag |
The cache supports response validation using Last-Modified and Tag headers to determine if a response is stale. The cache inserts an Tag in a response only if it caches the response and the origin server has not inserted its own Tag header. The Tag value is an arbitrary unique number. The Tag 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 Tag 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 Tag 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. |
| 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.” For more information, see "Configuring Global Attributes for Caching." |
Tag |
The cache supports response validation using the Last-Modified and Tag headers to determine if a response is stale. The cache inserts an Tag in a response only if it caches the response and the origin server has not inserted its own Tag header. The Tag value is an arbitrary unique number. The Tag 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 Tag 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 Tag 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. |
Insert an age, via, or Tag header
The following procedures describe how to insert Age, Via, and ETag headers.
Insert an Age, Via, or Etag header by using the NetScaler command interface:
At the command prompt, type:
set cache contentgroup <name> -insertVia YES -insertAge YES -insertETag YES
Configure the Age, Via, or Etag header by using the NetScaler GUI
-
Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
-
On the Others tab, in the HTTP Header Insertions group, select the Via, Age, or ETag options, as appropriate.
-
The values for the other header types are calculated automatically. 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.
Insert a cache-control header by using the NetScaler command interface
At the command prompt, type:
set cache contentgroup <name> -cacheControl <value>
Insert a cache-control header by using the NetScaler GUI
-
Navigate to Optimization > Integrated Caching > Content Groups, and
-
Click the Expiry Method tab, clear the heuristic and default expiry settings and set the relevant value in the Expire content after text box.
-
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.
-
Ignore cache-control and pragma headers in requests
By default, the caching module processes Cache-Control and Pragma headers. The following tokens in the 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 the 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 the 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.
Ignore Cache-Control and Pragma headers in a request by using the GUI
-
Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
-
On the Others tab, in the Settings group, select Ignore Cache-control and Pragma Headers in the 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.
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.
Poll 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 a Tag 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 the
If-Modified-SinceorIf-None-Matchheaders. TheIf-Modified-Sinceheader contains the time from theLast-Modifiedheader. An If-None-Match header contains the response's Tag 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-Conditional 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
Poll by using the GUI
-
Navigate to Optimization > Integrated Caching > Content Groups, and select the content group.
-
On the 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 website 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 website 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.