caching.xml revision 873b0a31e61a8513a46efc6f5c2418d9ce362b42
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun<?xml-stylesheet type="text/xsl" href="style/manual.en.xsl"?>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<!-- $LastChangedRevision$ -->
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Copyright 2005 The Apache Software Foundation or its licensors, as
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun applicable.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Licensed under the Apache License, Version 2.0 (the "License");
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun you may not use this file except in compliance with the License.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun You may obtain a copy of the License at
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Unless required by applicable law or agreed to in writing, software
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun distributed under the License is distributed on an "AS IS" BASIS,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun See the License for the specific language governing permissions and
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun limitations under the License.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>This document supplements the <module>mod_cache</module>,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_disk_cache</module>, <module>mod_mem_cache</module>,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun It describes how to use Apache's caching features to accelerate web and
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun proxy serving, while avoiding common problems and misconfigurations.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>As of Apache HTTP server version 2.2 <module>mod_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun and <module>mod_file_cache</module> are no longer marked
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun experimental and are considered suitable for production use. These
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun caching architectures provide a powerful means to accelerate HTTP
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun handling, both as an origin webserver and as a proxy.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p><module>mod_cache</module> and its provider modules
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_mem_cache</module> and <module>mod_disk_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun provide intelligent, HTTP-aware caching. The content itself is stored
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in the cache, and mod_cache aims to honour all of the various HTTP
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun headers and options that control the cachability of content. It can
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun handle both local and proxied content. <module>mod_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun is aimed at both simple and complex caching configurations, where
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun you are dealing with proxied content, dynamic local content or
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun have a need to speed up access to local files which change with
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p><module>mod_file_cache</module> on the other hand presents a more
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun basic, but sometimes useful, form of caching. Rather than maintain
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the complexity of actively ensuring the cachability of URLs,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_file_cache</module> offers file-handle and memory-mapping
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun tricks to keep a cache of files as they were when Apache was last
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun started. As such, <module>mod_file_cache</module> is aimed at improving
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the access time to local static files which do not change very
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>As <module>mod_file_cache</module> presents a relatively simple
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun caching implementation, apart from the specific sections on <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_file_cache">CacheFile</directive> and <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_file_cache">MMapStatic</directive>, the explanations
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in this guide cover the <module>mod_cache</module> caching
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun architecture.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>To get the most from this document, you should be familiar with
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the basics of HTTP, and have read the Users' Guides to
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <a href="content-negotiation.html">Content negotiation</a>.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <modulelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun </modulelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directivelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheEnable</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheDisable</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_file_cache">MMapStatic</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_file_cache">CacheFile</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_file_cache">CacheFile</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="core">UseCanonicalName</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_negotiation">CacheNegotiatedDocs</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun </directivelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>There are two main stages in <module>mod_cache</module> that can
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun occur in the lifetime of a request. First, <module>mod_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun is a URL mapping module, which means that if a URL has been cached,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun and the cached version of that URL has not expired, the request will
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun be served directly by <module>mod_cache</module>.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>This means that any other stages that might ordinarily happen
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in the process of serving a request -- for example being handled
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun by <module>mod_proxy</module>, or <module>mod_rewrite</module> --
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun won't happen. But then this is the point of caching content in
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the first place.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If the URL is not found within the cache, <module>mod_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun will add a <a href="filter.html">filter</a> to the request handling. After
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun Apache has located the content by the usual means, the filter will be run
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun as the content is served. If the content is determined to be cacheable,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the content will be saved to the cache for future serving.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If the URL is found within the cache, but also found to have expired,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the filter is added anyway, but <module>mod_cache</module> will create
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun a conditional request to the backend, to determine if the cached version
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun is still current. If the cached version is still current, its
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun meta-information will be updated and the request will be served from the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun cache. If the cached version is no longer current, the cached version
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun will be deleted and the filter will save the updated content to the cache
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun as it is served.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>When caching locally generated content, ensuring that
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="core">UseCanonicalName</directive> is set to
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <code>On</code> can dramatically improve the ratio of cache hits. This
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun is because the hostname of the virtual-host serving the content forms
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun a part of the cache key. With the setting set to <code>On</code>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun virtual-hosts with multiple server names or aliases will not produce
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun differently cached entities, and instead content will be cached as
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun per the canonical hostname.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>Because caching is performed within the URL to filename translation
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun phase, cached documents will only be served in response to URL requests.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Ordinarily this is of little consequence, but there is one circumstance
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in which it matters: If you are using <a href="howto/ssi.html">Server
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun<!-- The following include can be cached -->
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun<!--#include virtual="/footer.html" -->
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun<!-- The following include can not be cached -->
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun<!--#include file="/path/to/footer.html" --></pre>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If you are using Server Side Includes, and want the benefit of speedy
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun serves from the cache, you should use <code>virtual</code> include
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>The default expiry period for cached entities is one hour, however
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun this can be easily over-ridden by using the <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_cache">CacheDefaultExpire</directive> directive. This
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun default is only used when the original source of the content does not
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun specify an expire time or time of last modification.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If a response does not include an <code>Expires</code> header but does
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun include a <code>Last-Modified</code> header, <module>mod_cache</module>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun can infer an expiry period based on the use of the <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>For local content, <module>mod_expires</module> may be used to
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun fine-tune the expiry period.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>The maximum expiry period may also be controlled by using the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheMaxExpire</directive>.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>When content expires from the cache and is re-requested from the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun backend or content provider, rather than pass on the original request,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Apache will use a conditional request instead.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>HTTP offers a number of headers which allow a client, or cache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun to discern between different versions of the same content. For
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun example if a resource was served with an "Etag:" header, it is
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun possible to make a conditional request with an "If-Match:"
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun header. If a resource was served with a "Last-Modified:" header
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun it is possible to make a conditional request with an
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun "If-Modified-Since:" header, and so on.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>When such a conditional request is made, the response differs
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun depending on whether the content matches the conditions. If a request is
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun made with an "If-Modified-Since:" header, and the content has not been
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun modified since the time indicated in the request then a terse "304 Not
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Modified" response is issued.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If the content has changed, then it is served as if the request were
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun not conditional to begin with.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>The benefits of conditional requests in relation to caching are
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun twofold. Firstly, when making such a request to the backend, if the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun content from the backend matches the content in the store, this can be
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun determined easily and without the overhead of transferring the entire
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun resource.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>Secondly, conditional requests are usually less strenuous on the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun backend. For static files, typically all that is involved is a call
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun to <code>stat()</code> or similar system call, to see if the file has
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun changed in size or modification time. As such, even if Apache is
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun caching local content, even expired content may still be served faster
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun from the cache if it has not changed. As long as reading from the cache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun store is faster than reading from the backend (e.g. an in-memory cache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun compared to reading from disk).</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>As mentioned already, the two styles of caching in Apache work
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun differently, <module>mod_file_cache</module> caching maintains file
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun contents as they were when Apache was started. When a request is
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun made for a file that is cached by this module, it is intercepted
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun and the cached file is served.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p><module>mod_cache</module> caching on the other hand is more
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun complex. When serving a request, if it has not been cached
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun previously, the caching module will determine if the content
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun is cacheable. The conditions for determining cachability of
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun a response are;</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>Caching must be enabled for this URL. See the <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_cache">CacheEnable</directive> and <directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun module="mod_cache">CacheDisable</directive> directives.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>The response must have a HTTP status code of 200, 203, 300, 301 or
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>If the request contains an "Authorization:" header, the response
91f378b5a10f2d83820902ed10ba7967a3920c18nilgun will not be cached.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>If the response contains an "Authorization:" header, it must
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun also contain an "s-maxage", "must-revalidate" or "public" option
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in the "Cache-Control:" header.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>If the URL included a query string (e.g. from a HTML form GET
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun method) it will not be cached unless the response includes an
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun "Expires:" header, as per RFC2616 section 13.9.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>If the response has a status of 200 (OK), the response must
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun also include at least one of the "Etag", "Last-Modified" or
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the "Expires" headers, unless the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun directive has been used to require otherwise.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>If the response includes the "private" option in a "Cache-Control:"
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun header, it will not be stored unless the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheStorePrivate</directive> has been
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun used to require otherwise.</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>Likewise, if the response includes the "no-store" option in a
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun "Cache-Control:" header, it will not be stored unless the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheStoreNoStore</directive> has been
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <li>A response will not be stored if it includes a "Vary:" header
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun containing the match-all "*".</li>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>In short, any content which is highly time-sensitive, or which varies
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun depending on the particulars of the request that are not covered by
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun HTTP negotiation, should not be cached.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If you have dynamic content which changes depending on the IP address
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun of the requester, or changes every 5 minutes, it should almost certainly
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun not be cached.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If on the other hand, the content served differs depending on the
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun values of various HTTP headers, it is possible that it might be possible
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun to cache it intelligently through the use of a "Vary" header.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If a response with a "Vary" header is received by
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_cache</module> when requesting content by the backend it
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun will attempt to handle it intelligently. If possible,
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun <module>mod_cache</module> will detect the headers attributed in the
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun "Vary" response in future requests and serve the correct cached
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun response.</p>
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun <p>If for example, a response is received with a vary header such as;</p>
d801763e280bd6dbf94fd5a7f952310b4959040cnilgunVary: negotiate,accept-language,accept-charset
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun <p><module>mod_cache</module> will only serve the cached content to
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun requesters with matching accept-language and accept-charset headers
d801763e280bd6dbf94fd5a7f952310b4959040cnilgun matching those of the original request.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <title>Authorisation, Access & and Control</title>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>Using <module>mod_cache</module> is very much like having a built
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun in reverse-proxy. Requests will be served by the caching module unless
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun it determines that the backend should be queried. When caching local
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun resources, this drastically changes the security model of Apache.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>As traversing a filesystem hierarchy to examine potential
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <code>.htaccess</code> files would be a very expensive operation,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun partially defeating the point of caching (to speed up requests),
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_cache</module> makes no decision about whether a cached
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun entity is authorised for serving. In other words; if
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_cache</module> has cached some content, it will be served
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun from the cache as long as that content has not expired.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If, for example, your configuration permits access to a resource by IP
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun address you should ensure that this content is not cached. You can do this by
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun using the <directive module="mod_cache">CacheDisable</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun directive, or <module>mod_expires</module>. Left unchecked,
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <module>mod_cache</module> - very much like a reverse proxy - would cache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun the content when served and then serve it to any client, on any IP
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun address.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>As requests to end-users can be served from the cache, the cache
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun itself can become a target for those wishing to deface or interfere with
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun content. It is important to bear in mind that the cache must at all
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun times be writable by the user which Apache is running as. This is in
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun stark contrast to the usually recommended situation of maintaining
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun all content unwritable by the Apache user.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>If the Apache user is compromised, for example through a flaw in
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun a CGI process, it is possible that the cache may be targeted. When
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun using <module>mod_disk_cache</module>, it is relatively easy to
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun insert or modify a cached entity.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>This presents a somewhat elevated risk in comparison to the other
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun types of attack it is possible to make as the Apache user. If you are
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun using <module>mod_disk_cache</module> you should bear this in mind -
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun ensure you upgrade Apache when security upgrades are announced and
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun run CGI processes as a non-Apache user using <a
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>When running Apache as a caching proxy server, there is also the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun potential for so-called cache poisoning. Cache Poisoning is a broad
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun term for attacks in which an attacker causes the proxy server to
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun retrieve incorrect (and usually undesirable) content from the backend.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>For example if the DNS servers used by your system running Apache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun are vulnerable to DNS cache poisoning, an attacker may be able to control
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun where Apache connects to when requesting content from the origin server.
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Another example is so-called HTTP request-smuggling attacks.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>This document is not the correct place for an in-depth discussion
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun of HTTP request smuggling (instead, try your favourite search engine)
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun however it is important to be aware that it is possible to make
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun a series of requests, and to exploit a vulnerability on an origin
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun webserver such that the attacker can entirely control the content
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun retrieved by the proxy.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <modulelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun </modulelist>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <directivelist>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <directive module="mod_file_cache">CacheFile</directive>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <directive module="mod_cache">CacheEnable</directive>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <directive module="mod_cache">CacheDisable</directive>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun </directivelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>The act of opening a file can itself be a source of delay, particularly
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun on network filesystems. By maintaining a cache of open file descriptors
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun for commonly served files, Apache can avoid this delay. Currently Apache
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun provides two different implementations of File-Handle Caching.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>The most basic form of caching present in Apache is the file-handle
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun caching provided by <module>mod_file_cache</module>. Rather than caching
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun file-contents, this cache maintains a table of open file descriptors. Files
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun to be cached in this manner are specified in the configuration file using
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun the <directive module="mod_file_cache">CacheFile</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun directive.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_file_cache">CacheFile</directive> directive
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun instructs Apache to open the file when Apache is started and to re-use
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun this file-handle for all subsequent access to this file.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <pre>CacheFile /usr/local/apache2/htdocs/index.html</pre>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>If you intend to cache a large number of files in this manner, you
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun must ensure that your operating system's limit for the number of open
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun files is set appropriately.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p>Although using <directive module="mod_file_cache">CacheFile</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun does not cause the file-contents to be cached per-se, it does mean
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun that if the file changes while Apache is running these changes will
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun not be picked up. The file will be consistently served as it was
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun when Apache was started.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>If the file is removed while Apache is running, Apache will continue
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun to maintain an open file descriptor and serve the file as it was when
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun Apache was started. This usually also means that although the file
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun will have been deleted, and not show up on the filesystem, extra free
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun space will not be recovered until Apache is stopped and the file
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun descriptor closed.</p>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <p><module>mod_mem_cache</module> also provides its own file-handle
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun caching scheme, which can be enabled via the
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheEnable</directive> directive.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <p>As with all of <module>mod_cache</module> this type of file-handle
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun caching is intelligent, and handles will not be maintained beyond
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun the expiry time of the cached content.</p>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun <modulelist>
7fdd79a6e3620562e4f9062ed5cec77bedc06c67nilgun </modulelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directivelist>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheEnable</directive>
afef0859a009a2f6acad53b5781cbbdb53fb6a33nilgun <directive module="mod_cache">CacheDisable</directive>
