Module mod_cache

Module mod_cache supports directives for the IBM® HTTP Server for i Web server.

Summary

This module contains directives that define support for the HTTP Proxy function which includes the proxy caching function.

Cache Expiry Times

Cache expiry times are different than expiry times provided in HTTP response data. Cache expiry times are calculated by caching agents (such as a proxy server), whereas expiry times in HTTP response data are provided by content servers (for example, via HTTP Expires headers). If cacheable data from content servers contains expiry times, a caching agent (or proxy) must use cache expiry times that are no later than the corresponding data expiry times. In other words, caching agents may not serve data from cache after it has expired, however they may stop serving it from cache prior to such time.

If content servers do not provide expiry times for cacheable data, the caching agent (or proxy) may try to use other response information to calculate acceptable cache expiry times, or it may use some arbitrary default value, as determined by the administrator.

Note: Response data is considered cacheable for the proxy function if it satisfies criteria described under Criteria for Local Proxy Cache.

The proxy function follows these rules to determine which directive settings to use to calculate cache expiry times for HTTP proxy response data stored in the local proxy cache.

  1. If HTTP response data contains expiry times (via Expires header for HTTP requests only) these times are also used as cache expiry times.
  2. If HTTP response data does not contain expiry times, but does contain information pertaining to when it was last modified (via Last-Modified header for HTTP requests, or MDTM command for FTP requests), the CacheLastModifiedFactor and CacheMaxExpire directive settings are used to calculate cache expiry times.
  3. If HTTP response data does not contain expiry times, nor does it contain information pertaining to when it was last modified, the CacheDefaultExpire directive setting is used to calculate arbitrary cache expiry times.
Note: The first rule has one exception. If response code 304 (Not Modified) is received for HTTP requests, Expires headers (if any) are not used to set new cache expiry time. The second rule is applied (for 304 responses) if last modified times from cached data are available to recalculate new cache expiry times. If last modified times are not available from cached data, the third rule is applied.

Criteria for Local Proxy Cache

When configured, the server handles certain requests using the proxy function to obtain data from remote servers, which it then serves as HTTP proxy response data. It does this when acting as either a forward proxy or a reverse proxy (see ProxyRequests or ProxyReverse). By default, the proxy function obtains and handles data separately for each request. The server may be made more efficient, however, by using a local proxy cache to store HTTP proxy response data locally, which it then serves multiple times for multiple requests. The server is more efficient since remote servers need only be contacted when data in the local proxy cache expires.

Not all response data obtained by the server is cached and served for multiple requests, due mostly for reasons involving privacy, version control (frequency of change), and negotiable content. This type of response data is not considered cacheable and must be obtained from remote servers for each request.

Standard Criteria

Standard criteria for the server's local proxy cache and proxy function, in regards to response data obtained using specified protocols, is described in the following lists. This criteria is used to determine whether HTTP proxy response data is cacheable and may be served multiple times for multiple requests.

HTTP response data:

  • Only data requested using the GET method is cacheable.
  • Only data received on a request that does not end with a '/' is cacheable.
    • 200 (OK)
    • 203 (Non Authoritative)
    • 300 (Multiple Choices)
    • 301 (Moved Permanently)
    • 304 (Not Modified)
  • If data contains an Expires header, the header must be valid.
    Note: This does not apply to data that does not contain an Expires header.
  • If data contains an Expires header, the header must not specify a time that has already past (according to local system time).
  • If data contains an Expires header, the expiration time must be greater than the configured minimum expiration time.
  • Data received with response code 200 (OK) must contain either a Last-Modified header or an ETag header. This requirement is waived if on is specified for the CacheIgnoreNoLastMod directive.
  • Data received with response code 304 (Not Modified) is not cacheable if a previous version is not already in cache.
  • If data contains a Cache-Control header, the header must not specify the value "no-store" or "private".
  • If data contains a Pragma header, the header must not specify the value "no-cache".
  • If the request provides an Authorization header (possibly used by the remote server), response data must contain a Cache-Control header that specifies one or more of the following values: "s-maxage", "must-revalidate" or "public".
  • If data contains a Content-Length header, the header must not specify a value that exceeds the minimum or maximum data size limits set by the CacheMinFileSize and CacheMaxFileSize directives. See Additional Criteria for more information.

FTP response data:

  • Only data requested using the GET method is cacheable.
  • Data is only cached if LIST or RETR commands return one of the following response codes:
    • 125 (OK, Data Transfer Starting)
    • 150 (OK, Opening Data Connection)
    • 226 (OK, Closing Data Connection)
    • 250 (OK)
    Note: The LIST command is used to retrieve directory listings. The RETR command is used to retrieve data files.
  • Data must contain information for an HTTP Last-Modified header (produced via MDTM command with response code 213, see Notes®: below). This requirement is waived if on is specified for the CacheIgnoreNoLastMod directive.
  • If data contains information for an HTTP Content-Length header (produced via SIZE command with response code 213), the header must not specify a value that exceeds the minimum or maximum data size limits set by the CacheMinFileSize and CacheMaxFileSize directives, respectively. See Additional Criteria for more information.

HTTPS (or SSL-tunneling over HTTP) response data:

  • Data requested using SSL-tunneling over HTTP is not cacheable.

No other protocols are supported by the proxy function.

Additional Criteria

Additional criteria for the server's local proxy cache and proxy functions may be imposed by the function providing underlying cache support. Currently, this includes only the disk cache function.

The following list describes additional restrictions on HTTP proxy response data stored in a local proxy cache, imposed by the mod_cache_disk module:

  • Cache data must not exceed the minimum or maximum data size limits set by the CacheMinFileSize and CacheMaxFileSize directives. This restriction applies regardless of Content-Length header values (if any) in HTTP proxy response data.
  • Data with cache expiry times that will expire within the minimum time margin set by the CacheTimeMargin directive is not cached. This restriction applies to HTTP proxy response data, using cache expiry times calculated according to rules described in the Cache Expiry Times. See mod_cache_disk for other restriction that may apply.

Avoiding the Thundering Herd

When a cached entry becomes stale, mod_cache will submit a conditional request to the backend, which is expected to confirm whether the cached entry is still fresh, and send an updated entity if not.

A small but finite amount of time exists between the time the cached entity becomes stale, and the time the stale entity is fully refreshed. On a busy server, a significant number of requests might arrive during this time, and cause a thundering herd of requests to strike the backend suddenly and unpredictably.

To keep the thundering herd at bay, the CacheLock directive can be used to define a directory in which locks are created for URLs in flight. The lock is used as a hint by other requests to either suppress an attempt to cache (someone else has gone to fetch the entity), or to indicate that a stale entry is being refreshed (stale content will be returned in the mean time).

Initial caching of an entry:

  • When an entity is cached for the first time, a lock will be created for the entity until the response has been fully cached. During the lifetime of the lock, the cache will suppress the second and subsequent attempt to cache the same entity. While this doesn't hold back the thundering herd, it does stop the cache attempting to cache the same entity multiple times simultaneously.

Refreshment of a stale entry:

  • When an entity reaches its freshness lifetime and becomes stale, a lock will be created for the entity until the response has either been confirmed as still fresh, or replaced by the backend. During the lifetime of the lock, the second and subsequent incoming request will cause stale data to be returned, and the thundering herd is kept at bay.

Locks and Cache-Control: no-cache:

  • Locks are used as a hint only to enable the cache to be more gentle on backend servers, however the lock can be overridden if necessary. If the client sends a request with a Cache-Control header forcing a reload, any lock that may be present will be ignored, and the client's request will be honored immediately and the cached entry refreshed.

As a further safety mechanism, locks have a configurable maximum age. Once this age has been reached, the lock is removed, and a new request is given the opportunity to create a new lock. This maximum age can be set using the CacheLockMaxAge directive, and defaults to 5 seconds.

Example:

#Enable the cache lock#

CacheLock on
CacheLockPath /QIBM/UserData/HTTPA/tmp/mod_cache-lock
CacheLockMaxAge 5

Directives

CacheDetailHeader

Module: mod_cache
Syntax: CacheDetailHeader on|off
Default:CacheDetailHeader off
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheDetailHeader on

The CacheDetailHeader directive specifies whether an X-Cache-Detail header will be added to the response containing the detailed reason for a particular caching decision.

Parameter: on | off
  • If on is specified, an X-Cache-Detail header will be added to the response.
  • If off is specified(the default) , X-Cache-Detail header will not be added to the response by default.
Example:
    # Enable the X-Cache header 
    CacheHeader on
X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost

CacheHeader

Module: mod_cache
Syntax: CacheHeader on|off
Default: CacheHeader off
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheHeader on

The CacheHeader directive specifies whether an X-Cache header will be added to the response with the cache status of this response.

Parameter: on | off
  • If on is specified, an X-Cache header will be added to the response.
  • If off is specified (the default) , X-Cache header will not be added to the response by default.

If the normal handler is used, this directive may appear within a <Directory> or <Location> directive. If the quick handler is used, this directive must appear within a server or virtual host context, otherwise the setting will be ignored.

HIT

The entity was fresh, and was served from cache.

REVALIDATE

The entity was stale, was successfully revalidated and was served from cache.

MISS

The entity was fetched from the upstream server and was not served from cache.

Example: 

 # Enable the X-Cache header 
 CacheHeader on

X-Cache: HIT from localhost

CacheDefaultExpire

Module: mod_cache
Syntax: CacheDefaultExpire period
Default: CacheDefaultExpire 3600
Context: server config, Virtual Host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheDefaultExpire 3

The CacheDefaultExpire directive specifies the default number of seconds in which cacheable HTTP proxy response data will be set to expire within the local proxy cache, starting from the time it is obtained by the server.

Parameter: period
  • The period parameter defines the default cache expiry period, in seconds.

This setting is used to calculate arbitrary cache expiry times for HTTP proxy response data stored in the local proxy cache. See Cache Expiry Times for more information on how the server determines which settings to use to calculate cache expiry times. See the CacheIgnoreNoLastMod directive for information relating to how cache criteria may be waived for this setting to take affect.

If this setting is used, cache expiry times are calculated by adding the specified number of seconds to the time that data is received by the proxy function.

Example:
ProxyRequests on
CacheRoot proxyCache
CacheDefaultExpire 3600
CacheMaxExpire 86400
CacheLastModifiedFactor 0.3

In the example, if a cacheable data is retrieved from a server that does not provide an expiry time (via HTTP Expires header), nor does it indicate when the data was last modified (via HTTP Last-Modified header, or FTP MDTM command), the server will cache and serve the data for 3600 seconds (since CacheDefaultExpire is set to 3600 and "on" is specified for CacheIgnoreNoLastMod). If an expiry time or last-modified time is provided, CacheDefaultExpire would not be used (see Cache Expiry Times).

Note: Response data is considered cacheable for the proxy function if it satisfies criteria described under Criteria for Local Proxy Cache.

(1) The following conditions will negate this directive:

  1. off is specified for both ProxyRequests and ProxyReverse
  2. off is specified for CacheOn.
  3. CacheRoot is not specified
  4. on is specified for ProxyNoConnect

CacheDisable

Module: mod_cache
Syntax: CacheDisable url-string| on
Default: none
Context: server config, virtual host, directory
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheDisable /local_files

The CacheDisable directive instructs Module mod_cache to not cache urls at or below url-string.

If used in a <Location> directive, the path needs to be specified below the Location, or if the word "on" is used, caching for the whole location will be disabled.

Example:
<Location /foo>
   CacheDisable on
</Location>

The no-cache environment variable can be set to disable caching on a finer grained set of resources

CacheDisable will not make ProxyNoCache obsolete. They can be used in conjunction with each other (CacheDisable will have precedence). CacheDisable also takes presidence over CacheEnable directives, no matter the order.

Note: The directive can't be specified in <Directory>, <Limit> and <Files> directives.

CacheEnable

Module: mod_cache
Syntax: CacheEnable cache_type [url-string]
Default: none
Context: server config, virtual host, directory
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
LoadModule cache_disk_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheEnable disk

The CacheEnable directive instructs mod_cache to cache urls at or below url-string. The cache storage manager is specified with the cache_type argument (note: we do not support types socache implemented by mod_cache_socache). The CacheEnable directive can alternatively be placed inside either <Location> or <LocationMatch> sections to indicate the content is cacheable. Cache_type disk instructs mod_cache to use the disk based storage manager implemented by mod_cache_disk.

CacheEnable directives within <Location> or <LocationMatch> sections are processed before globally defined CacheEnable directives.

When acting as a forward proxy server, url-string must minimally begin with a protocol for which caching should be enabled.

Example 1 

# Cache content (normal handler only)
CacheQuickHandler off
<LocationMatch /foo>
    CacheEnable disk
</LocationMatch>

Example 2 

# Cache regex (normal handler only)
CacheQuickHandler off
<LocationMatch /foo$>
    CacheEnable disk
</LocationMatch>

Example 3

# Cache all but forward proxy url's  (normal or quick handler)
CacheEnable disk /

Example 4

# Cache FTP-proxied url's (normal or quick handler)
CacheEnable disk ftp://

Example 5

# Cache forward proxy  content from www.apache.org (normal or quick handler)
CacheEnable disk http://www.apache.org/

A hostname starting with a "*" matches all hostnames with that suffix. A hostname starting with "." matches all hostnames containing the domain components that follow.

Example 6

# Match www.example.org, and fooexample.org
CacheEnable  disk  http://*example.org/

Example 7

# Match www.example.org, but not fooexample.org
CacheEnable  disk  http://.example.org/

A hostname starting with a "*" matches all hostnames with that suffix. A hostname starting with "." matches all hostnames containing the domain components that follow.

# Match www.example.org, and fooexample.org
CacheEnable  disk  http://*example.org/

# Match www.example.org, but not fooexample.org
CacheEnable  disk  http://.example.org/

The no-cache environment variable can be set to disable caching on a finer grained set of resources.

IBM i has an additional enhancement to CacheEnable. If %%PROXY%% is specified as the url-string, all proxy requests will be cached (unless disabled by CacheDisable). This makes it easy for the customer to cache all proxy requests (they then do not have to maintain a list of CacheEnable protocols).

  # Cache all proxied url's
  CacheEnable disk %%PROXY%%

The IBM i HTTP server only supports cache_type disk (mod_cache_disk). If you wish to improve caching performance, use FRCA or memory based local cache mechanisms (CacheLocal directives). Implementing the CacheEnable directive will not make DynamicCache obsolete. URL's specified by CacheEnable will take precedence over dynamic cache, and will mark the request as not being a candidate for Dynamic Cache.

CacheExpiryCheck

Module: mod_cache
Syntax: CacheExpiryCheck on | off
Default: CacheExpiryCheck on
Context: server config, virtual host
Override: none
Origin: IBM
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheExpiryCheck on

The CacheExpiryCheck directive specifies whether the server is to observe cache expiry times when cached data is requested using the disk cache function (see CacheRoot).

Parameter: on | off
  • If on is specified (the default), the server will perform and apply all cache expiry time checks for data currently available in cache.
  • If off is specified, cache expiry times will not be observed and cached data (if any) will always be available.

Cache expiry time checks may be disabled (off) when the content of the cache is managed by an application or process other than the server itself. If the content of the cache is not managed by an application or process other than the server, this setting must be set to on (the default) to prevent the disk cache function from making expired data appear valid.

Note: When the disk cache function is used to support a local proxy cache, this setting determines whether cache expiry times are observed for the proxy function. Once cached, data is usually available from cache until its respective cache expiry times has passed. However, if cache expiry time checks are disabled (CacheExpiryCheck off), the proxy function will serve cached HTTP proxy response data regardless of whether it has expired. This effectively causes the disk cache function to ignore cache expiry times calculated using the CacheDefaultExpire, CacheMaxExpire, and CacheLastModifiedFactor directives for a local proxy cache, as well as any expiry time provided via Expires headers (for HTTP requests).

See the CacheRoot directive for more information on how the disk cache function is used to support a local proxy cache.

CacheIgnoreCacheControl

Module: mod_cache
Syntax: CacheIgnoreCacheControl on | off
Default: CacheIgnoreCacheControl off
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows: LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheIgnoreCacheControl on

The CacheIgnoreCacheControl directive specifies whether the server is to observe certain cache controlling request headers (for example, Cache-Control and Pragma) when handling requests using the proxy function.

Parameter: on | off
  • If on is specified, the server will not observe cache controlling request headers.
  • If off is specified (the default), the server will observe cache controlling request headers when HTTP proxy response data is available from the local proxy cache.

By default, the server observes certain cache controlling request headers (for example, "Cache-Control : no-store" and "Pragma : no-cache") when handling requests using the proxy function. If such headers are present in HTTP request data sent to the server, the proxy function will not serve HTTP proxy response data from the local proxy cache since these headers indicate that cached data is not wanted. However, if on is specified for this setting, the proxy function will ignore cache controlling request headers and serve HTTP proxy response data from cache, if it is available.

  • Setting ProxyRequests and ProxyReverse to off negates this directive.
  • This directive is used only if CacheRoot is set.

CacheIgnoreHeaders

Module: mod_cache
Syntax: CacheIgnoreHeaders header-string [header-string]
Default: CacheIgnoreHeaders None
Context: server, virtual host
Override: none
Origin: Apache
Example 1: CacheIgnoreHeaders Set-Cookie
Example 2: CacheIgnoreHeaders None
Do not store the given HTTP headers in the cache. According to RFC 2616, hop-by-hop HTTP headers are not stored in the cache. The following HTTP headers are hop-by-hop headers and thus do not get stored in the cache in any case regardless of the setting of CacheIgnoreHeaders:
  • Connection
  • Keep-Alive
  • Proxy-Authenticate
  • TE
  • Trailers
  • Transfer-Encoding
  • Upgrade
CacheIgnoreHeaders specifies additional HTTP headers that should not be stored in the cache. For example, it makes sense in some cases to prevent cookies from being stored in the cache.

CacheIgnoreHeaders takes a space separated list of HTTP headers that should not be stored in the cache. If only hop-by-hop headers should not be stored in the cache (the RFC 2616 compliant behaviour), CacheIgnoreHeaders can be set to None.

Warning: If headers like Expires which are needed for proper cache management are not stored due to a CacheIgnoreHeaders setting, the behaviour of mod_cache is undefined.

CacheIgnoreNoLastMod

Module: mod_cache
Syntax: CacheIgnoreNoLastMod on | off
Default: CacheIgnoreNoLastMod off
Context: Server, Virtual Host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheIgnoreNoLastMod on

The CacheIgnoreNoLastMod directive specifies whether the server may cache HTTP proxy response data in the local proxy cache, if it does not contain a Last-Modified header or an ETag header.

Parameter: on | off
  • If off is specified (the default), the server requires either an ETag header or a Last-Modified header to be present in all HTTP proxy response data cached in the local proxy cache.
  • If on is specified, the server will not require an ETag header or Last-Modified header to be present in HTTP proxy response data cached in the local proxy cache.

By default, if data does not contain either an ETag header or a Last-Modified header, the server does not consider it cacheable. Specifying on for this setting waives this criteria. See Criteria for Local Proxy Cache for more information.

Example One:
ProxyRequests on 
CacheRoot proxyCache
CacheIgnoreNoLastMod off 
CacheDefaultExpire 1

In the example, if data is received from a server that does not provide an expiry time (via HTTP Expires header), nor does it have an ETag or Last-Modified header, it is not considered cacheable since off is specified for CacheIgnoreNoLastMod. The server serves the data for the current request, but does not cache it for subsequent requests. The settings forCacheDefaultExpire is not used.

Example Two:
ProxyRequests on
CacheRoot proxyCache
CacheIgnoreNoLastMod on
CacheDefaultExpire 1

In this example, if data is received from a server that does not provide an expiry time (via HTTP Expires header), nor does it have an ETag or Last-Modified header (as in example one), it is still considered cacheable since on is specified for CacheIgnoreNoLastMod. The server serves the data for the current request, and may calculate a cache expiry time using CacheDefaultExpire to cache it for subsequent requests, assuming it satisfies all other cache criteria.

Note: Response data is considered cacheable for the proxy function if it satisfies criteria described under Criteria for Local Proxy Cache.
  • Setting ProxyRequests and ProxyReverse to off negates this directive.
  • Setting ProxyNoConnect to on negates this directive.
  • This directive is used only if CacheRoot is set.

CacheIgnoreURLSessionIdentifiers

Module: mod_cache
Syntax: CacheIgnoreURLSessionIdentifiers identifier [identifier] ...
Default: CacheIgnoreURLSessionIdentifiers None
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example:CacheIgnoreURLSessionIdentifiers jsessionid

The CacheIgnoreURLSessionIdentifiers directive ignores defined session identifiers encoded in the URL when caching

Sometimes applications encode the session identifier into the URL like in the following Examples:

  • /someapplication/image.gif;jsessionid=123456789
  • /someapplication/image.gif?PHPSESSIONID=12345678

This causes cachable resources to be stored separately for each session, which is often not desired. CacheIgnoreURLSessionIdentifiers lets define a list of identifiers that are removed from the key that is used to identify an entity in the cache, such that cachable resources are not stored separately for each session.

CacheIgnoreURLSessionIdentifiers None clears the list of ignored identifiers. Otherwise, each identifier is added to the list.

Example 1

CacheIgnoreURLSessionIdentifiers jsessionid

Example 2

CacheIgnoreURLSessionIdentifiers None

CacheKeyBaseURL

Module: mod_cache
Syntax: CacheKeyBaseURL URL
Default: None
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheKeyBaseURL http://www.example.com/

When the CacheKeyBaseURL directive is specified, the URL provided will be used as the base URL to calculate the URL of the cache keys in the reverse proxy configuration. When not specified, the scheme, hostname and port of the current virtual host is used to construct the cache key. When a cluster of machines is present, and all cached entries should be cached beneath the same cache key, a new base URL can be specified with this directive.

Example:
# Override the base URL of the cache key.
CacheKeyBaseURL http://www.example.com/
Note: Take care when setting this directive. If two separate virtual hosts are accidentally given the same base URL, entries from one virtual host will be served to the other.

CacheLastModifiedFactor

Module: mod_cache
Syntax: CacheLastModifiedFactor factor
Default: CacheLastModifiedFactor 0.1
Context: server config, Virtual Host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheLastModifiedFactor 0.3

The CacheLastModifiedFactor directive specifies a multiplication factor used in the formula: 

period = time-since-last-modification *<factor>
Parameter: factor
  • The factor parameter specifies the multiplication factor used in the formula (described above) to calculate cache expiry times.

This formula is used and setting is used along with CacheMaxExpire to calculate cache expiry times for HTTP proxy response data store in the local proxy cache, based on when the data was last modified. See Cache Expiry Times for more information on how the server determines which settings to use when calculating cache expiry times.

If this setting is used, cache expiry times are calculated by adding the lesser of the calculated period (using the formula above) and the period specified for CacheMaxExpire to the time that data is received by the proxy function. Using this method, data that has not changed recently is served from cache longer than data that has changed recently, since its last-modified time is older and will produce a greater cache expiry period. This assumes that both responses yield calculated cache expiry periods that are less than the CacheMaxExpire directive setting.

Example:
ProxyRequests on
CacheRoot proxyCache
CacheMaxExpire 86400
CacheLastModifiedFactor 0.3

In this example, if cacheable data is received from a server that does not provide an expiry time (via HTTP Expires header), but does indicate that the data was last changed 10 hours ago (via HTTP Last-Modified header, or FTP MDTM command), the server would calculate a period of 3 hours using CacheLastModifiedFactor (10 * 0.3) and would cache and serve the data for the same period of time since it is less than the maximum limit of 24 hours set by CacheMaxExpire.

Note: Response data is considered cacheable for the proxy function if it satisfies criteria described under Criteria for Local Proxy Cache.

If a similar response for this example indicates that the data was last changed 8 days ago (or 192 hours), the server would calculate a period of 57.6 hours using CacheLastModifiedFactor (192 * 0.3), but it would cache and serve the data for a period of only 24 hours since CacheMaxExpire sets a limit on the maximum period for the CacheLastModifiedFactor formula.

  • Setting ProxyRequests and ProxyReverse to off negates this directive.
  • Setting ProxyNoConnect to on negates this directive.
  • This directive is used only if CacheRoot is set.

CacheLock

Module: mod_cache
Syntax: CacheLock on|off
Default: CacheLock off
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheLock off

The CacheLock directive enables the thundering herd lock for the given URL space.

Parameter: on | off
  • The value on enables the thundering herd lock.
  • The value off disables the thundering herd lock, this is the default behavior.

In a minimal configuration the following directive is all that is needed to enable the thundering herd lock in the default cache lock temp directory /QIBM/UserData/HTTPA/tmp specified via CacheLockPath directive.

Example:


# Enable cache lock
CacheLock on

CacheLockMaxAge

Module: mod_cache
Syntax: CacheLockMaxAge integer
Default: CacheLockMaxAge 5
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheLockMaxAge 10

The CacheLockMaxAge directive specifies the maximum age of any cache lock.

A lock older than this value in seconds will be ignored, and the next incoming request will be given the opportunity to re-establish the lock. This mechanism prevents a slow client taking an excessively long time to refresh an entity.

CacheLockPath

Module: mod_cache
Syntax: CacheLockPath directory
Default: CacheLockPath /QIBM/UserData/HTTPA/tmp
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheLockPath /QIBM/UserData/HTTPA/tmp/myCacheLock

The CacheLockPath directive allows you to specify the directory in which the locks are created. By default, /QIBM/UserData/HTTPA/tmp is used as the default cache lock directory. Locks consist of empty files that only exist for stale URLs in flight, so is significantly less resource intensive than the traditional disk cache.

Parameter: directory
  • The directory parameter accepts a file system path name to specify the file system directory for the cache lock path (see cache lock directory limits below).

The server must have *RWX data authorities and *ALL object authorities to the specified directory.

Cache lock directory limits:

  • If the directory parameter specifies an absolute path it must start with /QIBM/UserData/HTTPA/tmp, otherwise the default folder will be used.
  • If the directory parameter does not specify an absolute path (does not start with a '/'), it will be assumed to be relative to the following: /QIBM/UserData/HTTPA/tmp
Example 1 (absolute path):
       CacheLockPath /QIBM/UserData/HTTPA/tmp/myCacheLock
Example 2 (relative path):
       CacheLockPath myCacheLock

CacheMaxExpire

Module: mod_cache
Syntax: CacheMaxExpire period
Default: CacheMaxExpire 86400
Context: server config, Virtual Host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheMaxExpire 43200

The CacheMaxExpire directive specifies the maximum number of seconds in which cacheable HTTP proxy response data will be set to expire within the local proxy cache (when the CacheLastModifiedFactor directive setting is used). This setting has no affect on other settings used to calculate cache expiry times.

Parameter: period
  • The period parameter specifies the maximum cache expiry period, in seconds, that may be used when expiry times are calculated using the CacheLastModifiedFactor directive setting.

    This setting is used along with the CacheLastModifiedFactor directive setting to calculate expiry times for HTTP proxy response data stored in the local proxy cache, based on when data was last modified. See Cache Expiry Times for more information on how the server determines which settings to use when calculating cache expiry times. If this setting is used, cache expiry times are calculated by adding the lesser of the specified period and the period calculated using CacheLastModifiedFactor to the time that data is received by the proxy function.

Example
ProxyRequests on
CacheRoot proxyCache
CacheMaxExpire 86400
CacheLastModifiedFactor 0.3

In this example, if cacheable data is received from a server that does not provide an expiry time (via HTTP Expires header), but does indicate that the data was last changed 5 days ago (via HTTP Last-Modified header, or FTP MDTM command), the server would calculate a period of 1.5 days using CacheLastModifiedFactor (5 * 0.3), but it would cache and serve the data for a period of only 86400 seconds (1 day) since CacheMaxExpire sets a maximum limit of 86400 seconds.

Note: Response data is considered cacheable for the proxy function if it satisfies criteria described under Criteria for Local Proxy Cache.
  • Setting ProxyRequests and ProxyReverse to off negates this directive.
  • Setting ProxyNoConnect to on negates this directive.
  • This directive is used only if CacheRoot is set

CacheMinExpire

Module: mod_cache
Syntax: CacheMinExpire seconds
Default: CacheMinExpire 0
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheMinExpire 3600

The CacheMinExpire directive specifies the minimum number of seconds for which cachable HTTP documents will be retained without checking the origin server. This is only used if no valid expire time was supplied with the document.

CacheQuickHandler

Module: mod_cache
Syntax: CacheQuickHandler on | off
Default: CacheQuickHandler on
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheQuickHandler on

The CacheQuickHandler directive controls the phase in which the cache is handled.

Parameter: on | off
  • If on is specified (the default) , the cache operates within the quick handler phase. This phase short circuits the majority of server processing, and represents the most performant mode of operation for a typical server. The cache bolts onto the front of the server, and the majority of server processing is avoided.
  • If off is specified, the cache operates as a normal handler, and is subject to the full set of phases when handling a server request. While this mode is slower than the default, it allows the cache to be used in cases where full processing is required, such as when content is subject to authorization.

Example 1

    # Run cache as a normal handler
    CacheQuickHandler off

It is also possible, when the quick handler is disabled, for the administrator to choose the precise location within the filter chain where caching is to be performed, by adding the CACHE filter to the chain.

Example 2

    # Cache content before mod_include and mod_deflate
    CacheQuickHandler off
    AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html

If the CACHE filter is specified more than once, the last instance will apply.

CacheStaleOnError

Module: mod_cache
Syntax: CacheStaleOnError on | off
Default: CacheStaleOnError on
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheStaleOnError on

When the CacheStaleOnError directive is switched on, and when stale data is available in the cache, the cache will respond to 5xx responses from the backend by returning the stale data instead of the 5xx response. While the Cache-Control headers sent by clients will be respected, and the raw 5xx responses returned to the client on request, the 5xx response so returned to the client will not invalidate the content in the cache.

Example

# Serve stale data on error.
CacheStaleOnError on

CacheStoreExpired

Module: mod_cache
Syntax: CacheStoreExpired on | off
Default: CacheStoreExpired Off
Context: server config, virtual host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheStoreExpired On

By default, responses which have already expired are not stored in the cache. The CacheStoreExpired directive allows this behavior to be overridden. CacheStoreExpired On tells the server to attempt to cache the resource if it is stale. Subsequent requests would trigger an If-Modified-Since request of the origin server, and the response may be fulfilled from cache if the backend resource has not changed.

CacheStoreNoStore

Module: mod_cache
Syntax: CacheStoreNoStore on | off
Default: CacheStoreNoStore Off
Context: server config, Virtual Host, directory, .htaccess
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheStoreNoStore On

Attempt to cache requests or responses that have been marked as no-store. Ordinarily, requests or responses with Cache-Control: no-store header values will not be stored in the cache. The CacheStoreNoCache directive allows this behavior to be overridden. CacheStoreNoCache On tells the server to attempt to cache the resource even if it contains no-store header values. Resources requiring authorization will never be cached.

CAUTION:
As described in RFC 2616, the no-store directive is intended to "prevent the inadvertent release or retention of sensitive information (for example, on backup tapes)." Enabling this option could store sensitive information in the cache. You are hereby warned.

CacheStorePrivate

Module: mod_cache
Syntax: CacheStorePrivate on | off
Default: CacheStorePrivate Off
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheStorePrivate On

Ordinarily, responses with Cache-Control: private header values will not be stored in the cache. The CacheStorePrivate directive allows this behavior to be overridden. CacheStorePrivate On tells the server to attempt to cache the resource even if it contains private header values. Resources requiring authorization will never be cached.

CAUTION:
This directive will allow caching even if the upstream server has requested that the resource not be cached. This directive is only ideal for a private cache.

CacheTimeMargin

Module: mod_cache
Syntax: CacheTimeMargin period
Default: CacheTimeMargin 120
Context: server config, virtual host
Override: none
Origin: Apache
Usage Considerations: A LoadModule is required in the configuration file prior to using the directive. The statement should be as follows:
LoadModule cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM 
LoadModule cache_disk module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheTimeMargin 300

The CacheTimeMargin directive specifies the minimum number of seconds remaining prior to data expiration, as indicated in the expires response header, in order for data to be cached by the server using the disk cache function. If the disk cache function is disabled (see CacheRoot), this setting has no affect.

Parameter: period
  • The period parameter specifies the minimum time margin for cache update requests (in seconds).

    The server calculates cache time margins (or periods) for cache update requests by subtracting the current system time from the computed expiry time. Data for cache update requests that produce cache time margins, that are less than the specified minimum time margin is not cached by the server.

Notes for local proxy cache:

The disk cache function uses CacheDefaultExpire, CacheLastModifiedFactor, and CacheMaxExpire directives which may produce cache time margins that are less than the minimum time margin specified by the CacheTimeMargin directive. In this case, the CacheTimeMargin directive will also be used to determine if the file will be cached. See the CacheRoot directive for more information on how the disk cache function is used to support a local proxy cache.

Example
ProxyRequests on
CacheRoot proxyCache
CacheTimeMargin 120

In this example, if cacheable HTTP proxy response data is available, the data will be served (by proxy), but it will not be cached for subsequent proxy requests if set to expire in less than 120 seconds (CacheTimeMargin 120). If the HTTP proxy response data is set to expire in more than two minutes, the data will be served (by proxy) and will also be cached for subsequent proxy requests.