mod_cache
mod_cache overview
mod_cache
module provides HTTP content cache for local and proxied content. Cached
content is stored in
Cached content is stored/retrieved using URI-based keys. Content with access
protection (e.g. with Deny directive)
is not cached.
mod_cache operation
1. After authentication/authorization events but prior to
request handler execution mod_cache comes out on the scene.
At this stage the module performs the following:
- 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.
2. Response may be cached if request meets the following requirements:
- 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 usedPragma request header must not be no-cache. This condition is ignored if CacheIgnoreCacheControl On is used
3. When request handler has completed its job and all defined
filters have been applied to response, mod_cache starts to operate.
At this stage the module performs the following:
- 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
4. The following conditions are considered when deciding whether
response is cacheable (all must be met at a time):
- 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 QueryString, 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 usedCache-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 "*".
5. Cache key generation
Response is saved in cache according to the key. This key includes:
- 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.
6. HTTP response is stored in cache for a specific period
of time that is computed in the following way:
- 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.
mod_cache directives
CacheDefaultExpire
| Description: |
Default cache duration when no expiry date is specified |
| Syntax: |
CacheDefaultExpire seconds |
| Default: |
CacheDefaultExpire 3600 (one hour) |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheDefaultExpire 86400
CacheDisable
| Description: |
Disables caching of specified URLs |
| Syntax: |
CacheDisable [url-string] |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
CacheDisable directive stops caching for and below url-string.
Url-string should be specified only for server config in all other
locations it must be omitted.
Example:
#in server config
CacheDisable /some_url
#in .htaccess or directory config
CacheDisable
CacheEnable
| Description: |
Enables caching of specified URLs |
| Syntax: |
CacheEnable mem|disk [url-string] |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
CacheEnable directive allows caching for and below url-string.
Url-string should be specified only for server config in all other
locations it must be omitted.
In order to use the 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. Example:
# enable 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 CacheEnable and CacheDisable directives.
CacheIgnoreCacheControl
| Description: |
Ignores request to not serve cached content to client |
| Syntax: |
CacheIgnoreCacheControl On|Off |
| Default: |
CacheIgnoreCacheControl Off |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheIgnoreCacheControl On
CacheIgnoreHeaders
| Description: |
Doesn't store specified HTTP header(s) in cache |
| Syntax: |
CacheIgnoreHeaders header-string [header-string] ... |
| Default: |
CacheIgnoreHeaders None |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
Not supported.
CacheIgnoreNoLastMod
| Description: |
Ignores the fact that a response has no Last Modified header |
| Syntax: |
CacheIgnoreNoLastMod On|Off |
| Default: |
CacheIgnoreNoLastMod Off |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheIgnoreNoLastMod On
CacheLastModifiedFactor
| Description: |
Sets the factor used to compute an expiry date based on the LastModified
date |
| Syntax: |
CacheLastModifiedFactor float |
| Default: |
CacheLastModifiedFactor 0.1 |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
CacheLastModifiedFactor directive allows calculate document
expiry date based on its last-modified date. CacheLastModifiedFactor
directive specifies a factor to be used in the generation of this 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 would be longer than that set by CacheMaxExpire,
the latter prevails.
Example:
CacheLastModifiedFactor 0.5
CacheMaxExpire
| Description: |
Sets maximum time in seconds to cache a document |
| Syntax: |
CacheMaxExpire seconds |
| Default: |
CacheMaxExpire 86400 (one day) |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheMaxExpire 604800
CacheStoreNoStore
| Description: |
Attempts to cache requests or responses that have been marked as no-store |
| Syntax: |
CacheStoreNoStore On|Off |
| Default: |
CacheStoreNoStore Off |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheStoreNoStore On
CacheStorePrivate
| Description: |
Attempts to cache responses that the server has marked as private |
| Syntax: |
CacheStorePrivate On|Off |
| Default: |
CacheStorePrivate Off |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheStorePrivate On
CacheVaryByParams
| Description: |
Defines request parameters to be included into cache key |
| Syntax: |
CacheVaryByParams None | param-string [param-string] ... |
| Default: |
By default all query parameters are included into cache key |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheVaryByParams category_id product_id
Note! CacheVaryByParams directive
has no equivalent in Apache (see Compatibility
chart).
CacheVaryByHeaders
| Description: |
Defines request headers to be included into cache key |
| Syntax: |
CacheVaryByHeaders None | header-string [header-string] ... |
| Default: |
CacheVaryByHeaders None |
| Context: |
server config, virtual host, directory, .htaccess |
| Module: |
mod_cache |
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.
Example:
CacheVaryByHeaders Cookie
Note! CacheVaryByHeaders directive
has no equivalent in Apache (see Compatibility
chart).
