Module mod_cache

Important: Information for this topic supports the latest PTF levels for HTTP Server for i5/OS . It is recommended that you install the latest PTFs to upgrade to the latest level of the HTTP Server for i5/OS. Some of the topics documented here are not available prior to this update. See http://www.ibm.com/servers/eserver/iseries/software/http/services/service.htm Link outside Information Center for more information.

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:

FTP response data:

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

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_disk_cache module:

Directives

CacheDefaultExpire

Module: mod_cache
Syntax: CacheDefaultExpire period
Default: CacheDefaultExpire 3600
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: 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.

CacheExpiryCheck

Module: mod_cache
Syntax: CacheExpiryCheck on | off
Default: CacheExpiryCheck on
Context: server config, virtual host
Override: none
Origin: iSeries™
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.

CacheIgnoreNoLastMod

Module: mod_cache
Syntax: CacheIgnoreNoLastMod on | off
Default: CacheIgnoreNoLastMod 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: 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 for CacheDefaultExpire 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.

CacheLastModifiedFactor

Module: mod_cache
Syntax: CacheLastModifiedFactor factor
Default: CacheLastModifiedFactor 0.1
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: 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.

CacheMaxExpire

Module: mod_cache
Syntax: CacheMaxExpire period
Default: CacheMaxExpire 86400
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: 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.

CacheMaxFileSize

Module: mod_cache
Syntax: CacheMaxFileSize size
Default: CacheMaxFileSize 1000000
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, disk_cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheMaxFileSize 4000000

The CacheMaxFileSize directive specifies the maximum amount of data that may be stored in the proxy disk cache for a single URL, in bytes. This setting effectively placing a maximum data size limit on individual cache entries. If the disk cache function is disabled (see CacheRoot), this setting has no affect.

Parameter: size
  • The size parameter specifies the maximum number of bytes allowed for cache data entries.

    A minimum document size limits specified using CacheMinFileSize.

    Notes for local proxy cache:

    When the disk cache function is used to support a local proxy cache, this setting places a maximum data size limit on HTTP proxy responses which remain in the cache after cache maintenance has run. See the CachGcDaily or CacheGcInterval directives for more information on how the disk cache maintenance function is used to support a local proxy cache.

Example
ProxyRequests on
CacheRoot proxyCache
CacheMaxFileSize 5000000
CacheMinFileSize 400000

For this example, if 7.2 megabytes of cacheable HTTP proxy response data is available for a single proxy request but will be removed during the next cache maintenance cycle since it is larger than the 5000000 byte maximum data size limit imposed by CacheMaxFileSize. A 3.8 megabyte HTTP proxy response may be cached for subsequent proxy requests and will remain in the cache after the cache maintenance cycle has run since it is smaller than the 5000000 byte maximum data size limit and larger than the 400000 byte minimum data size limit (set by CacheMinFileSize).

If the values specified for CacheMinFileSize and CacheMaxFileSize are changed once they have been used to cache data, the server will discard existing cache data that does not adhere to the new limits when it runs disk cache maintenance. See CachGcDaily or CacheGcInterval for more details on the disk cache maintenance process.

CacheMinFileSize

Module: mod_cache
Syntax: CacheMinFileSize size
Default: CacheMinFileSize 1
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 disk_cache_module /QSYS.LIB/QHTTPSVR.LIB/QZSRCORE.SRVPGM
Example: CacheMinFileSize 40

The CacheMinFileSize directive specifies the minimum amount of data that may be stored in the proxy disk cache for a single URL, in bytes. This setting effectively places a minimum data size limit on individual cache entries. If the disk cache function is disabled (see CacheRoot), this setting has no affect.

Parameter: size
  • The size parameter specifies the minimum number of bytes allowed for cache data entries.

    A maximum document size limits specified using CacheMaxFileSize.

Notes for local proxy cache:

When the disk cache function is used to support a local proxy cache, this setting places a minimum data size limit on HTTP proxy responses which remain in the cache after cache maintenance has run. See CachGcDaily and CacheGcInterval directives for more details on the how the disk cache maintenance function is used to support a local proxy cache.

Example
ProxyRequests on
CacheRoot proxyCache
CacheMaxFileSize 5000000
CacheMinFileSize 400000

For this example, if 240 kilobytes of cacheable HTTP proxy response data is available for a single proxy request, but will be removed during the next cache maintenance cycle since it is less than the 400000 byte minimum data size limit imposed by CacheMinFileSize. A 2.7 megabyte HTTP proxy response may be cached for subsequent proxy requests and will remain in the cache after the cache maintenance cycle has run since it is larger than the 400000 byte minimum data size limit and smaller than the 5000000 byte maximum data size limit (set by CacheMaxFileSize).

If the values specified for CacheMinFileSize and CacheMaxFileSize are changed once they have been used to cache data, the server will discard existing cache data that does not adhere to the new limits when it runs disk cache maintenance. See CachGcDaily or CacheGcInterval for more details on the disk cache maintenance process.

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 disk_cache_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.