<p>As of Apache HTTP server version 2.2 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
and <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> are no longer marked
experimental and are considered suitable for production use. These
caching architectures provide a powerful means to accelerate HTTP
handling, both as an origin webserver and as a proxy.</p>
<p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> and its provider modules
<code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> and <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>
provide intelligent, HTTP-aware caching. The content itself is stored
in the cache, and mod_cache aims to honour all of the various HTTP
headers and options that control the cachability of content. It can
handle both local and proxied content. <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
is aimed at both simple and complex caching configurations, where
you are dealing with proxied content, dynamic local content or
have a need to speed up access to local files which change with
time.</p>
<p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> on the other hand presents a more
basic, but sometimes useful, form of caching. Rather than maintain
the complexity of actively ensuring the cachability of URLs,
<code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> offers file-handle and memory-mapping
tricks to keep a cache of files as they were when Apache was last
started. As such, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> is aimed at improving
the access time to local static files which do not change very
often.</p>
<p>As <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> presents a relatively simple
caching implementation, apart from the specific sections on <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> and <code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code>, the explanations
in this guide cover the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching
architecture.</p>
<p>To get the most from this document, you should be familiar with
the basics of HTTP, and have read the Users' Guides to
<a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
<p>There are two main stages in <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> that can
occur in the lifetime of a request. First, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
is a URL mapping module, which means that if a URL has been cached,
and the cached version of that URL has not expired, the request will
be served directly by <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>.</p>
<p>This means that any other stages that might ordinarily happen
in the process of serving a request -- for example being handled
by <code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code>, or <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code> --
won't happen. But then this is the point of caching content in
the first place.</p>
<p>If the URL is not found within the cache, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
will add a <a href="filter.html">filter</a> to the request handling. After
Apache has located the content by the usual means, the filter will be run
as the content is served. If the content is determined to be cacheable,
the content will be saved to the cache for future serving.</p>
<p>If the URL is found within the cache, but also found to have expired,
the filter is added anyway, but <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will create
a conditional request to the backend, to determine if the cached version
is still current. If the cached version is still current, its
meta-information will be updated and the request will be served from the
cache. If the cached version is no longer current, the cached version
will be deleted and the filter will save the updated content to the cache
as it is served.</p>
<h3>Improving Cache Hits</h3>
<p>When caching locally generated content, ensuring that
<code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code> is set to
<code>On</code> can dramatically improve the ratio of cache hits. This
is because the hostname of the virtual-host serving the content forms
a part of the cache key. With the setting set to <code>On</code>
virtual-hosts with multiple server names or aliases will not produce
differently cached entities, and instead content will be cached as
per the canonical hostname.</p>
<p>Because caching is performed within the URL to filename translation
phase, cached documents will only be served in response to URL requests.
Ordinarily this is of little consequence, but there is one circumstance
in which it matters: If you are using <a href="howto/ssi.html">Server
<p>If you are using Server Side Includes, and want the benefit of speedy
serves from the cache, you should use <code>virtual</code> include
types.</p>
<h3>Expiry Periods</h3>
<p>The default expiry period for cached entities is one hour, however
this can be easily over-ridden by using the <code class="directive"><a href="./mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive. This
default is only used when the original source of the content does not
specify an expire time or time of last modification.</p>
<p>If a response does not include an <code>Expires</code> header but does
include a <code>Last-Modified</code> header, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
can infer an expiry period based on the use of the <code class="directive"><a href="./mod/mod_cache.html#cachelastmodifiedfactor">CacheLastModifiedFactor</a></code> directive.</p>
<p>For local content, <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code> may be used to
fine-tune the expiry period.</p>
<p>The maximum expiry period may also be controlled by using the
contents as they were when Apache was started. When a request is
made for a file that is cached by this module, it is intercepted
and the cached file is served.</p>
<p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching on the other hand is more
complex. When serving a request, if it has not been cached
previously, the caching module will determine if the content
is cacheable. The conditions for determining cachability of
a response are;</p>
<ol>
<li>Caching must be enabled for this URL. See the <code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> and <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code> directives.</li>
<li>The response must have a HTTP status code of 200, 203, 300, 301 or
410.</li>
<li>The request must be a HTTP GET request.</li>
<li>If the request contains an "Authorization:" header, the response
will not be cached.</li>
<li>If the response contains an "Authorization:" header, it must
also contain an "s-maxage", "must-revalidate" or "public" option
in the "Cache-Control:" header.</li>
<li>If the URL included a query string (e.g. from a HTML form GET
method) it will not be cached unless the response includes an
"Expires:" header, as per RFC2616 section 13.9.</li>
<li>If the response has a status of 200 (OK), the response must
also include at least one of the "Etag", "Last-Modified" or
<p><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> provides a disk-based caching mechanism
for <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>. As with <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code>
this cache is intelligent and content will be served from the cache only
as long as it is considered valid.</p>
<p>Typically the module will be configured as so;</p>
<div class="example"><pre>
CacheRoot /var/cache/apache/
CacheEnable disk /
CacheDirLevels 2
CacheDirLength 1</pre></div>
<p>Importantly, as the cached files are locally stored, operating system
in-memory caching will typically be applied to their access also. So
although the files are stored on disk, if they are frequently accessed
it is likely the operating system will ensure that they are actually
served from memory.</p>
<h3>Understanding the Cache-Store</h3>
<p>To store items in the cache, <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> creates
a 22 character hash of the URL being requested. This hash incorporates
the hostname, protocol, port, path and any CGI arguments to the URL,
to ensure that multiple URLs do not collide.</p>
<p>Each character may be any one of 64-different characters, which mean
that overall there are 64^22 possible hashes. For example, a URL might
be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
as a prefix for the naming of the files specific to that URL within
the cache, however first it is split up into directories as per
the <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code> and
<p class="apache">Copyright 2007 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
