mod_cache

Overview

mod_cache module provides HTTP content cache for local and proxied content. Cached content is stored/retrieved using URI-based keys.

The way it works

• The actions that are performed after authentication/authorization events but prior to request handler execution
  • checks whether it's possible to use cached response for the current request
  • if yes, generates a key and searches cached response using this key
  • if the response is found in cache, the module gives it back to the client and request processing is over - request handler is not invoked.
• The essential request requirements to cache the response
  • request method is GET
  • request does not contain Authorization header
  • Cache-Control request header must not be no-cache. This condition is ignored if CacheIgnoreCacheControl On is used
  • Pragma request header must not be no-cache. This condition is ignored if CacheIgnoreCacheControl On is used
• The actions that are performed after request handler and filters have been applied to response
  • estimates the capability of response caching
  • checks if CacheEnable is set for this request
  • generates cache key
  • defines the period of time to store response in cache (absolute expiration time)
  • saves response in cache according to the key
• The conditions that need to be met to cache response
  • request method is GET
  • response status is 200 (200, 203, 300, 301 or 410 in Apache)
  • Expires response header contains valid "future" date
  • responses containing expiration time (i.e. Expires or Cache-Control: max-age=XX headers), Etag header or Last-Modified header. This condition is ignored if CacheIgnoreNoLastMod is used. If request has a query string, only those responses containing expiration time are cached (i.e. Expires or Cache-Control: max-age=XX headers). This condition is ignored if CacheIgnoreQueryString On is used.
  • Cache-Control request header must not be no-cache. This condition is ignored if CacheStoreNoStore On is used
  • Cache-Control request header must not be private. This condition is ignored if CacheStorePrivate On is used
  • request does not contain Authorization header (for Apache: if Cache-Control contains s-maxage, must-revalidate or public)
  • Vary response header does not contain "*".
• Cache key generation
  • normalized (canonical) request URI without QueryString or, in case if proxy request, normalized proxy request URL;
  • all QueryString parameters and their values in alphabetical order (default behavior). CacheIgnoreQueryString On directive cancels addition of request parameters to the cache key. CacheVaryByParams param1 param2 ... directive defines parameters to be included into cache key
  • all request headers specified in CacheVaryByHeaders header1 header2 ... directive. Headers are not included to the cache key by default.
  • If response contains Vary header, all request headers specified in it are included into cache key.
• The methods of calculating period of time of HTTP response stored in cache
  • If response contains Expires header and its value is valid and does not refer to the past, cached response will be stored till the time specified in it.
  • If response contains Cache-Control header with either max-age=X or s-maxage=X, cached response will be stored in cache for X seconds.
  • If response contains Last-Modified header, cached response will be stored in cache until:
    expiry date = date + min((date - lastmod) * factor, maxexpire),
    where date — current date,
    lastmod — value of Last-Modified header,
    factor — float value set via CacheLastModifiedFactor directive (default value = 0,1),
    maxexpire — value set via CacheMaxExpire directive (default value = 86400 seconds = 1 day).
  • If mod_cache was unable to calculate expiration date using one of aforementioned methods (this is possible if response doesn't have Expires, Cache-Control, Last-Modified headers BUT has Etag header), it (date) is equated to default value of 1 hour that may be reset using CacheDefaultExpire directive.

Quick start

<Files *.php>
  # setup expiration header in response (if app does not setup it)
  ExpiresActive On
  # response expire in a hour
  ExpiresByType text/html "access 1 hour"
  # enable memory-based cache
  CacheEnable mem
</Files>

<VirtualHost www.myblog.com>
  CacheRoot c:\inetpub\cache
  CacheEnable disk /blog/
</VirtualHost>

Related articles and topics

• Web Caching: what is it?
• How mod_cache works?
• Guide: Example of mod_cache application
• Disk-based caching for IIS7
• mod_disk_cache
• mod_mem_cache
• mod_env
• mod_setenvif (extended syntax supported)
• mod_expires
• mod_headers

Enviroment variables

Examples

# enable memory-based cache
SetEnv cache-enable mem

# enable disk-based cache
SetEnv cache-enable disk

# disable cache
SetEnv cache-enable none

# clear cache if query string contains 'clear_cache_request' and client ip is 11.22.33.44
SetEnvIf (Query_String clear_cache_request) and (Remote_Addr 11\.22\.33\.44) cache-clear=1

Directives

CacheDefaultExpire

CacheDefaultExpire directive specifies a default time (in seconds) during which the document will be stored in cache if expiry date and last-modified date are not provided. The value specified in CacheMaxExpire directive does not override this setting.

Syntax

CacheDefaultExpire seconds

Default

CacheDefaultExpire 3600

Example

CacheDefaultExpire 86400

CacheDisable

CacheDisable directive stops caching for and below url-string. Url-string should be specified only for server config and must be omitted in all other locations.

Syntax

CacheDisable [url-string]

Example

# in server config
CacheDisable /some_url

# in .htaccess or directory config
CacheDisable

CacheEnable

CacheEnable directive allows caching for and below url-string. Url-string should be specified only for server config and must be omitted in all other locations.

Syntax:

CacheEnable mem|disk [url-string]

In order to use memory- or disk-based storage engine, the module must be loaded and configured if necessary. See mod_mem_cache and mod_disk_cache for details.

Example:

#in server config
CacheEnable mem /app1
CacheEnable disk /app2

# in .htaccess or directory config
CacheEnable mem

# or
CacheEnable disk

Cache functionality can also be enabled/disabled by cache-enable environment variable.

# enable disk-based caching
SetEnv cache-enable mem
# disable caching
SetEnv cache-enable none
# or like this
UnSetEnv cache-enable

Note! Value of cache-enable variable has higher priority than that of CacheEnable and CacheDisable directives.

CacheIgnoreCacheControl

CacheIgnoreCacheControl directive allows to override behavior required by Cache-Control: no-cache or Pragma: no-cache header values. CacheIgnoreCacheControl On tells the server to try serve the resource from cache even if the request contains no-cache header values. Resources requiring authorization will not be cached.

Syntax

CacheIgnoreCacheControl On|Off

Default

CacheIgnoreCacheControl Off

CacheIgnoreHeaders

Not store specified HTTP header(s) in cache.

Not supported.

Syntax

CacheIgnoreHeaders header-string [header-string] [...]

Default

CacheIgnoreHeaders None

CacheIgnoreNoLastMod

CacheIgnoreNoLastMod directive allows to say that documents without last-modified dates should be cached. If neither last-modified date nor expiry date are provided, the value specified by the CacheDefaultExpire directive will be used to generate an expiration date.

Syntax

CacheIgnoreNoLastMod On|Off

Default

CacheIgnoreNoLastMod Off

CacheLastModifiedFactor

CacheLastModifiedFactor directive allows calculate document expiry date based on its last-modified date.

Syntax

CacheLastModifiedFactor float

Default

CacheLastModifiedFactor 0.1

CacheLastModifiedFactor directive specifies a factor to be used in the generation of expiry date according to the following formula:

expiry-period = time-since-last-modified-date * factor

expiry-date = current-date + expiry-period

Example

If the document was last modified 10 hours ago, and factor is 0.1 then the expiry-period will be 10*0.1 = 1 hour. If the current time is 3:00pm, the computed expiry-date is 3:00pm + 1hour = 4:00pm. If the expiry-period is longer than that set by CacheMaxExpire, the latter prevails.

CacheMaxExpire

CacheMaxExpire directive specifies the maximum number of seconds for which cached documents will be retrieved from cache rather than taken from the origin server. CacheMaxExpire value is used only if expiration time is generated using CacheLastModifiedFactor algorithm.

Syntax

CacheMaxExpire seconds

Default

CacheMaxExpire 86400

CacheStoreNoStore

CacheStoreNoStore directive allows to enable caching for requests or responses with Cache-Control: no-store header value that normally aren't cached. Resources requiring authorization will never be cached.

Syntax

CacheStoreNoStore On|Off

Default

CacheStoreNoStore Off

CacheStorePrivate

CacheStorePrivate directive allows to enable caching for responses with Cache-Control: private header value that normally aren't cached. Resources requiring authorization will never be cached.

Syntax

CacheStorePrivate On|Off

Default

CacheStorePrivate Off

CacheVaryByParams

CacheVaryByParams directive allows to define request parameters that will be included into the cache key. The following requests /index.php?category_id=1&mode=1 and /index.php?category_id=1&mode=2 will have the same cache key despite the difference in mode parameter. In its turn this means that the second request /index.php?category_id=1&mode=2 will use the response cached for the first request /index.php?category_id=1&mode=1.

Syntax

CacheVaryByParams None|param-string [param-string] [...]

Default

By default all query parameters are included into cache key

Example

CacheVaryByParams category_id product_id

Note! CacheVaryByParams directive has no equivalent in Apache (see Compatibility chart).

CacheVaryByHeaders

CacheVaryByHeaders directive allows to define request headers that will be included into the cache key. The following identical requests with different headers Cookie: auth=1 and Cookie: auth=2 will have different caching keys and consequently different response versions in cache.

Syntax

CacheVaryByHeaders None|header-string [header-string] [...]

Default

CacheVaryByHeaders None

Example

CacheVaryByHeaders Cookie

Note! CacheVaryByHeaders directive has no equivalent in Apache (see Compatibility chart).