caching.xml revision b76a31daaa6e83bb0fd627a04f20e82bffcf1df4
5302f55dd48a542de9503b1c60001de8613be789colm<?xml-stylesheet type="text/xsl" href="style/manual.en.xsl"?>
9c6d66067c984a69a5380946a5fe3a13da3524dfnd<!-- $LastChangedRevision$ -->
031b91a62d25106ae69d4693475c79618dd5e884fielding Licensed to the Apache Software Foundation (ASF) under one or more
031b91a62d25106ae69d4693475c79618dd5e884fielding contributor license agreements. See the NOTICE file distributed with
031b91a62d25106ae69d4693475c79618dd5e884fielding this work for additional information regarding copyright ownership.
031b91a62d25106ae69d4693475c79618dd5e884fielding The ASF licenses this file to You under the Apache License, Version 2.0
031b91a62d25106ae69d4693475c79618dd5e884fielding (the "License"); you may not use this file except in compliance with
031b91a62d25106ae69d4693475c79618dd5e884fielding the License. You may obtain a copy of the License at
5302f55dd48a542de9503b1c60001de8613be789colm Unless required by applicable law or agreed to in writing, software
5302f55dd48a542de9503b1c60001de8613be789colm distributed under the License is distributed on an "AS IS" BASIS,
5302f55dd48a542de9503b1c60001de8613be789colm WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
5302f55dd48a542de9503b1c60001de8613be789colm See the License for the specific language governing permissions and
5302f55dd48a542de9503b1c60001de8613be789colm limitations under the License.
5302f55dd48a542de9503b1c60001de8613be789colm <p>This document supplements the <module>mod_cache</module>,
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi <module>mod_disk_cache</module>, <module>mod_file_cache</module> and <a
5302f55dd48a542de9503b1c60001de8613be789colm href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
8737696b024af8af0f42ffe4a70dc191913d697crbowen It describes how to use the Apache HTTP Server's caching features to accelerate web and
5302f55dd48a542de9503b1c60001de8613be789colm proxy serving, while avoiding common problems and misconfigurations.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </summary>
030108b1816bcda3d925df65357feabdce83bc94slive <p>As of Apache HTTP server version 2.2 <module>mod_cache</module>
030108b1816bcda3d925df65357feabdce83bc94slive and <module>mod_file_cache</module> are no longer marked
030108b1816bcda3d925df65357feabdce83bc94slive experimental and are considered suitable for production use. These
030108b1816bcda3d925df65357feabdce83bc94slive caching architectures provide a powerful means to accelerate HTTP
030108b1816bcda3d925df65357feabdce83bc94slive handling, both as an origin webserver and as a proxy.</p>
5302f55dd48a542de9503b1c60001de8613be789colm provide intelligent, HTTP-aware caching. The content itself is stored
b751f61885edfa8975b02c59b9604d202ffcb9bfrbowen in the cache, and mod_cache aims to honor all of the various HTTP
5302f55dd48a542de9503b1c60001de8613be789colm headers and options that control the cachability of content. It can
5302f55dd48a542de9503b1c60001de8613be789colm handle both local and proxied content. <module>mod_cache</module>
5302f55dd48a542de9503b1c60001de8613be789colm is aimed at both simple and complex caching configurations, where
5302f55dd48a542de9503b1c60001de8613be789colm you are dealing with proxied content, dynamic local content or
5302f55dd48a542de9503b1c60001de8613be789colm have a need to speed up access to local files which change with
5302f55dd48a542de9503b1c60001de8613be789colm <p><module>mod_file_cache</module> on the other hand presents a more
5302f55dd48a542de9503b1c60001de8613be789colm basic, but sometimes useful, form of caching. Rather than maintain
5302f55dd48a542de9503b1c60001de8613be789colm the complexity of actively ensuring the cachability of URLs,
5302f55dd48a542de9503b1c60001de8613be789colm <module>mod_file_cache</module> offers file-handle and memory-mapping
8737696b024af8af0f42ffe4a70dc191913d697crbowen tricks to keep a cache of files as they were when httpd was last
030108b1816bcda3d925df65357feabdce83bc94slive started. As such, <module>mod_file_cache</module> is aimed at improving
5302f55dd48a542de9503b1c60001de8613be789colm the access time to local static files which do not change very
5302f55dd48a542de9503b1c60001de8613be789colm often.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>As <module>mod_file_cache</module> presents a relatively simple
5302f55dd48a542de9503b1c60001de8613be789colm caching implementation, apart from the specific sections on <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_file_cache">CacheFile</directive> and <directive
a1066e2786436743f6791963fb266282c25e1e99lgentis module="mod_file_cache">MMapFile</directive>, the explanations
5302f55dd48a542de9503b1c60001de8613be789colm in this guide cover the <module>mod_cache</module> caching
5302f55dd48a542de9503b1c60001de8613be789colm architecture.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>To get the most from this document, you should be familiar with
5302f55dd48a542de9503b1c60001de8613be789colm the basics of HTTP, and have read the Users' Guides to
5302f55dd48a542de9503b1c60001de8613be789colm <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
5302f55dd48a542de9503b1c60001de8613be789colm <a href="content-negotiation.html">Content negotiation</a>.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm </modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_file_cache">CacheFile</directive>
a1066e2786436743f6791963fb266282c25e1e99lgentis <directive module="mod_file_cache">MMapFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_negotiation">CacheNegotiatedDocs</directive>
5302f55dd48a542de9503b1c60001de8613be789colm </directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </related>
030108b1816bcda3d925df65357feabdce83bc94slive <p>There are two main stages in <module>mod_cache</module> that can
5302f55dd48a542de9503b1c60001de8613be789colm occur in the lifetime of a request. First, <module>mod_cache</module>
5302f55dd48a542de9503b1c60001de8613be789colm is a URL mapping module, which means that if a URL has been cached,
5302f55dd48a542de9503b1c60001de8613be789colm and the cached version of that URL has not expired, the request will
030108b1816bcda3d925df65357feabdce83bc94slive <p>This means that any other stages that might ordinarily happen
030108b1816bcda3d925df65357feabdce83bc94slive in the process of serving a request -- for example being handled
030108b1816bcda3d925df65357feabdce83bc94slive by <module>mod_proxy</module>, or <module>mod_rewrite</module> --
030108b1816bcda3d925df65357feabdce83bc94slive won't happen. But then this is the point of caching content in
030108b1816bcda3d925df65357feabdce83bc94slive the first place.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If the URL is not found within the cache, <module>mod_cache</module>
5302f55dd48a542de9503b1c60001de8613be789colm will add a <a href="filter.html">filter</a> to the request handling. After
8737696b024af8af0f42ffe4a70dc191913d697crbowen httpd has located the content by the usual means, the filter will be run
5302f55dd48a542de9503b1c60001de8613be789colm as the content is served. If the content is determined to be cacheable,
5302f55dd48a542de9503b1c60001de8613be789colm the content will be saved to the cache for future serving.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If the URL is found within the cache, but also found to have expired,
5302f55dd48a542de9503b1c60001de8613be789colm the filter is added anyway, but <module>mod_cache</module> will create
5302f55dd48a542de9503b1c60001de8613be789colm a conditional request to the backend, to determine if the cached version
5302f55dd48a542de9503b1c60001de8613be789colm is still current. If the cached version is still current, its
5302f55dd48a542de9503b1c60001de8613be789colm meta-information will be updated and the request will be served from the
5302f55dd48a542de9503b1c60001de8613be789colm cache. If the cached version is no longer current, the cached version
5302f55dd48a542de9503b1c60001de8613be789colm will be deleted and the filter will save the updated content to the cache
5302f55dd48a542de9503b1c60001de8613be789colm as it is served.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>When caching locally generated content, ensuring that
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="core">UseCanonicalName</directive> is set to
5302f55dd48a542de9503b1c60001de8613be789colm <code>On</code> can dramatically improve the ratio of cache hits. This
5302f55dd48a542de9503b1c60001de8613be789colm is because the hostname of the virtual-host serving the content forms
5302f55dd48a542de9503b1c60001de8613be789colm a part of the cache key. With the setting set to <code>On</code>
5302f55dd48a542de9503b1c60001de8613be789colm virtual-hosts with multiple server names or aliases will not produce
5302f55dd48a542de9503b1c60001de8613be789colm differently cached entities, and instead content will be cached as
5302f55dd48a542de9503b1c60001de8613be789colm per the canonical hostname.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Because caching is performed within the URL to filename translation
5302f55dd48a542de9503b1c60001de8613be789colm phase, cached documents will only be served in response to URL requests.
5302f55dd48a542de9503b1c60001de8613be789colm Ordinarily this is of little consequence, but there is one circumstance
5302f55dd48a542de9503b1c60001de8613be789colm in which it matters: If you are using <a href="howto/ssi.html">Server
5302f55dd48a542de9503b1c60001de8613be789colm<!-- The following include can be cached -->
5302f55dd48a542de9503b1c60001de8613be789colm<!--#include virtual="/footer.html" -->
5302f55dd48a542de9503b1c60001de8613be789colm<!-- The following include can not be cached -->
5302f55dd48a542de9503b1c60001de8613be789colm<!--#include file="/path/to/footer.html" --></pre>
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If you are using Server Side Includes, and want the benefit of speedy
5302f55dd48a542de9503b1c60001de8613be789colm serves from the cache, you should use <code>virtual</code> include
5302f55dd48a542de9503b1c60001de8613be789colm types.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>The default expiry period for cached entities is one hour, however
5302f55dd48a542de9503b1c60001de8613be789colm this can be easily over-ridden by using the <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_cache">CacheDefaultExpire</directive> directive. This
5302f55dd48a542de9503b1c60001de8613be789colm default is only used when the original source of the content does not
5302f55dd48a542de9503b1c60001de8613be789colm specify an expire time or time of last modification.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If a response does not include an <code>Expires</code> header but does
5302f55dd48a542de9503b1c60001de8613be789colm include a <code>Last-Modified</code> header, <module>mod_cache</module>
5302f55dd48a542de9503b1c60001de8613be789colm can infer an expiry period based on the use of the <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>For local content, <module>mod_expires</module> may be used to
5302f55dd48a542de9503b1c60001de8613be789colm fine-tune the expiry period.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>The maximum expiry period may also be controlled by using the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheMaxExpire</directive>.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>When content expires from the cache and is re-requested from the
5302f55dd48a542de9503b1c60001de8613be789colm backend or content provider, rather than pass on the original request,
8737696b024af8af0f42ffe4a70dc191913d697crbowen httpd will use a conditional request instead.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>HTTP offers a number of headers which allow a client, or cache
5302f55dd48a542de9503b1c60001de8613be789colm to discern between different versions of the same content. For
5302f55dd48a542de9503b1c60001de8613be789colm example if a resource was served with an "Etag:" header, it is
70d118289160dd7005d53780b979b15b67210c54noodl possible to make a conditional request with an "If-None-Match:"
5302f55dd48a542de9503b1c60001de8613be789colm header. If a resource was served with a "Last-Modified:" header
5302f55dd48a542de9503b1c60001de8613be789colm it is possible to make a conditional request with an
5302f55dd48a542de9503b1c60001de8613be789colm "If-Modified-Since:" header, and so on.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>When such a conditional request is made, the response differs
5302f55dd48a542de9503b1c60001de8613be789colm depending on whether the content matches the conditions. If a request is
5302f55dd48a542de9503b1c60001de8613be789colm made with an "If-Modified-Since:" header, and the content has not been
5302f55dd48a542de9503b1c60001de8613be789colm modified since the time indicated in the request then a terse "304 Not
5302f55dd48a542de9503b1c60001de8613be789colm Modified" response is issued.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If the content has changed, then it is served as if the request were
5302f55dd48a542de9503b1c60001de8613be789colm not conditional to begin with.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>The benefits of conditional requests in relation to caching are
5302f55dd48a542de9503b1c60001de8613be789colm twofold. Firstly, when making such a request to the backend, if the
5302f55dd48a542de9503b1c60001de8613be789colm content from the backend matches the content in the store, this can be
5302f55dd48a542de9503b1c60001de8613be789colm determined easily and without the overhead of transferring the entire
5302f55dd48a542de9503b1c60001de8613be789colm resource.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Secondly, conditional requests are usually less strenuous on the
5302f55dd48a542de9503b1c60001de8613be789colm backend. For static files, typically all that is involved is a call
5302f55dd48a542de9503b1c60001de8613be789colm to <code>stat()</code> or similar system call, to see if the file has
8737696b024af8af0f42ffe4a70dc191913d697crbowen changed in size or modification time. As such, even if httpd is
5302f55dd48a542de9503b1c60001de8613be789colm caching local content, even expired content may still be served faster
5302f55dd48a542de9503b1c60001de8613be789colm from the cache if it has not changed. As long as reading from the cache
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi store is faster than reading from the backend (e.g. <module
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi >mod_disk_cache</module> with memory disk
5302f55dd48a542de9503b1c60001de8613be789colm compared to reading from disk).</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
8737696b024af8af0f42ffe4a70dc191913d697crbowen <p>As mentioned already, the two styles of caching in httpd work
5302f55dd48a542de9503b1c60001de8613be789colm differently, <module>mod_file_cache</module> caching maintains file
8737696b024af8af0f42ffe4a70dc191913d697crbowen contents as they were when httpd was started. When a request is
5302f55dd48a542de9503b1c60001de8613be789colm made for a file that is cached by this module, it is intercepted
5302f55dd48a542de9503b1c60001de8613be789colm and the cached file is served.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p><module>mod_cache</module> caching on the other hand is more
5302f55dd48a542de9503b1c60001de8613be789colm complex. When serving a request, if it has not been cached
5302f55dd48a542de9503b1c60001de8613be789colm previously, the caching module will determine if the content
5302f55dd48a542de9503b1c60001de8613be789colm is cacheable. The conditions for determining cachability of
5302f55dd48a542de9503b1c60001de8613be789colm a response are;</p>
5302f55dd48a542de9503b1c60001de8613be789colm <li>Caching must be enabled for this URL. See the <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_cache">CacheEnable</directive> and <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_cache">CacheDisable</directive> directives.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>The response must have a HTTP status code of 200, 203, 300, 301 or
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the request contains an "Authorization:" header, the response
5302f55dd48a542de9503b1c60001de8613be789colm will not be cached.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the response contains an "Authorization:" header, it must
5302f55dd48a542de9503b1c60001de8613be789colm also contain an "s-maxage", "must-revalidate" or "public" option
5302f55dd48a542de9503b1c60001de8613be789colm in the "Cache-Control:" header.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the URL included a query string (e.g. from a HTML form GET
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier method) it will not be cached unless the response specifies an
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier explicit expiration by including an "Expires:" header or the max-age
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier or s-maxage directive of the "Cache-Control:" header, as per RFC2616
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier sections 13.9 and 13.2.1.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the response has a status of 200 (OK), the response must
5302f55dd48a542de9503b1c60001de8613be789colm also include at least one of the "Etag", "Last-Modified" or
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier the "Expires" headers, or the max-age or s-maxage directive of
0c5eea2ba49d679f28881f92865f4352d65d6fdapoirier the "Cache-Control:" header, unless the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
5302f55dd48a542de9503b1c60001de8613be789colm directive has been used to require otherwise.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the response includes the "private" option in a "Cache-Control:"
5302f55dd48a542de9503b1c60001de8613be789colm header, it will not be stored unless the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheStorePrivate</directive> has been
5302f55dd48a542de9503b1c60001de8613be789colm used to require otherwise.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>Likewise, if the response includes the "no-store" option in a
5302f55dd48a542de9503b1c60001de8613be789colm "Cache-Control:" header, it will not be stored unless the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheStoreNoStore</directive> has been
5302f55dd48a542de9503b1c60001de8613be789colm used.</li>
5302f55dd48a542de9503b1c60001de8613be789colm <li>A response will not be stored if it includes a "Vary:" header
5302f55dd48a542de9503b1c60001de8613be789colm containing the match-all "*".</li>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>In short, any content which is highly time-sensitive, or which varies
5302f55dd48a542de9503b1c60001de8613be789colm depending on the particulars of the request that are not covered by
5302f55dd48a542de9503b1c60001de8613be789colm HTTP negotiation, should not be cached.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If you have dynamic content which changes depending on the IP address
5302f55dd48a542de9503b1c60001de8613be789colm of the requester, or changes every 5 minutes, it should almost certainly
5302f55dd48a542de9503b1c60001de8613be789colm not be cached.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If on the other hand, the content served differs depending on the
4412b850c905615791750962e5944d1e8d9ab788noodl values of various HTTP headers, it might be possible
5302f55dd48a542de9503b1c60001de8613be789colm to cache it intelligently through the use of a "Vary" header.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If a response with a "Vary" header is received by
5302f55dd48a542de9503b1c60001de8613be789colm <module>mod_cache</module> when requesting content by the backend it
5302f55dd48a542de9503b1c60001de8613be789colm will attempt to handle it intelligently. If possible,
5302f55dd48a542de9503b1c60001de8613be789colm <module>mod_cache</module> will detect the headers attributed in the
5302f55dd48a542de9503b1c60001de8613be789colm "Vary" response in future requests and serve the correct cached
5302f55dd48a542de9503b1c60001de8613be789colm response.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If for example, a response is received with a vary header such as;</p>
5302f55dd48a542de9503b1c60001de8613be789colmVary: negotiate,accept-language,accept-charset
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p><module>mod_cache</module> will only serve the cached content to
4412b850c905615791750962e5944d1e8d9ab788noodl requesters with accept-language and accept-charset headers
5302f55dd48a542de9503b1c60001de8613be789colm matching those of the original request.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <p>Using <module>mod_cache</module> is very much like having a built
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm in reverse-proxy. Requests will be served by the caching module unless
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm it determines that the backend should be queried. When caching local
8737696b024af8af0f42ffe4a70dc191913d697crbowen resources, this drastically changes the security model of httpd.</p>
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <p>As traversing a filesystem hierarchy to examine potential
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <code>.htaccess</code> files would be a very expensive operation,
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm partially defeating the point of caching (to speed up requests),
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <module>mod_cache</module> makes no decision about whether a cached
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm entity is authorised for serving. In other words; if
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <module>mod_cache</module> has cached some content, it will be served
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm from the cache as long as that content has not expired.</p>
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <p>If, for example, your configuration permits access to a resource by IP
344f36280b984743f54c31c7ae8fadf8d4ed7456rbowen address you should ensure that this content is not cached. You can do this
344f36280b984743f54c31c7ae8fadf8d4ed7456rbowen by using the <directive module="mod_cache">CacheDisable</directive>
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm directive, or <module>mod_expires</module>. Left unchecked,
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm <module>mod_cache</module> - very much like a reverse proxy - would cache
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm the content when served and then serve it to any client, on any IP
4412b850c905615791750962e5944d1e8d9ab788noodl address.</p>
b77f6f03c0b6bbc6ecd6e87358f568024733d680colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>As requests to end-users can be served from the cache, the cache
5302f55dd48a542de9503b1c60001de8613be789colm itself can become a target for those wishing to deface or interfere with
5302f55dd48a542de9503b1c60001de8613be789colm content. It is important to bear in mind that the cache must at all
8737696b024af8af0f42ffe4a70dc191913d697crbowen times be writable by the user which httpd is running as. This is in
5302f55dd48a542de9503b1c60001de8613be789colm stark contrast to the usually recommended situation of maintaining
5302f55dd48a542de9503b1c60001de8613be789colm all content unwritable by the Apache user.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If the Apache user is compromised, for example through a flaw in
5302f55dd48a542de9503b1c60001de8613be789colm a CGI process, it is possible that the cache may be targeted. When
5302f55dd48a542de9503b1c60001de8613be789colm using <module>mod_disk_cache</module>, it is relatively easy to
5302f55dd48a542de9503b1c60001de8613be789colm insert or modify a cached entity.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>This presents a somewhat elevated risk in comparison to the other
5302f55dd48a542de9503b1c60001de8613be789colm types of attack it is possible to make as the Apache user. If you are
5302f55dd48a542de9503b1c60001de8613be789colm using <module>mod_disk_cache</module> you should bear this in mind -
8737696b024af8af0f42ffe4a70dc191913d697crbowen ensure you upgrade httpd when security upgrades are announced and
5302f55dd48a542de9503b1c60001de8613be789colm run CGI processes as a non-Apache user using <a
5302f55dd48a542de9503b1c60001de8613be789colm </section>
8737696b024af8af0f42ffe4a70dc191913d697crbowen <p>When running httpd as a caching proxy server, there is also the
5302f55dd48a542de9503b1c60001de8613be789colm potential for so-called cache poisoning. Cache Poisoning is a broad
5302f55dd48a542de9503b1c60001de8613be789colm term for attacks in which an attacker causes the proxy server to
5302f55dd48a542de9503b1c60001de8613be789colm retrieve incorrect (and usually undesirable) content from the backend.
8737696b024af8af0f42ffe4a70dc191913d697crbowen <p>For example if the DNS servers used by your system running
5302f55dd48a542de9503b1c60001de8613be789colm are vulnerable to DNS cache poisoning, an attacker may be able to control
8737696b024af8af0f42ffe4a70dc191913d697crbowen where httpd connects to when requesting content from the origin server.
5302f55dd48a542de9503b1c60001de8613be789colm Another example is so-called HTTP request-smuggling attacks.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>This document is not the correct place for an in-depth discussion
5302f55dd48a542de9503b1c60001de8613be789colm of HTTP request smuggling (instead, try your favourite search engine)
5302f55dd48a542de9503b1c60001de8613be789colm however it is important to be aware that it is possible to make
5302f55dd48a542de9503b1c60001de8613be789colm a series of requests, and to exploit a vulnerability on an origin
5302f55dd48a542de9503b1c60001de8613be789colm webserver such that the attacker can entirely control the content
5302f55dd48a542de9503b1c60001de8613be789colm retrieved by the proxy.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm </modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_file_cache">CacheFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm </directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </related>
5302f55dd48a542de9503b1c60001de8613be789colm <p>The act of opening a file can itself be a source of delay, particularly
5302f55dd48a542de9503b1c60001de8613be789colm on network filesystems. By maintaining a cache of open file descriptors
8737696b024af8af0f42ffe4a70dc191913d697crbowen for commonly served files, httpd can avoid this delay. Currently
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi provides one implementation of File-Handle Caching.</p>
8737696b024af8af0f42ffe4a70dc191913d697crbowen <p>The most basic form of caching present in httpd is the file-handle
5302f55dd48a542de9503b1c60001de8613be789colm caching provided by <module>mod_file_cache</module>. Rather than caching
5302f55dd48a542de9503b1c60001de8613be789colm file-contents, this cache maintains a table of open file descriptors. Files
5302f55dd48a542de9503b1c60001de8613be789colm to be cached in this manner are specified in the configuration file using
5302f55dd48a542de9503b1c60001de8613be789colm the <directive module="mod_file_cache">CacheFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm directive.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_file_cache">CacheFile</directive> directive
8737696b024af8af0f42ffe4a70dc191913d697crbowen instructs httpd to open the file when it is started and to re-use
5302f55dd48a542de9503b1c60001de8613be789colm this file-handle for all subsequent access to this file.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <pre>CacheFile /usr/local/apache2/htdocs/index.html</pre>
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p>If you intend to cache a large number of files in this manner, you
5302f55dd48a542de9503b1c60001de8613be789colm must ensure that your operating system's limit for the number of open
5302f55dd48a542de9503b1c60001de8613be789colm files is set appropriately.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Although using <directive module="mod_file_cache">CacheFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm does not cause the file-contents to be cached per-se, it does mean
8737696b024af8af0f42ffe4a70dc191913d697crbowen that if the file changes while httpd is running these changes will
5302f55dd48a542de9503b1c60001de8613be789colm not be picked up. The file will be consistently served as it was
8737696b024af8af0f42ffe4a70dc191913d697crbowen when httpd was started.</p>
8737696b024af8af0f42ffe4a70dc191913d697crbowen <p>If the file is removed while httpd is running, it will continue
5302f55dd48a542de9503b1c60001de8613be789colm to maintain an open file descriptor and serve the file as it was when
8737696b024af8af0f42ffe4a70dc191913d697crbowen httpd was started. This usually also means that although the file
5302f55dd48a542de9503b1c60001de8613be789colm will have been deleted, and not show up on the filesystem, extra free
8737696b024af8af0f42ffe4a70dc191913d697crbowen space will not be recovered until httpd is stopped and the file
5302f55dd48a542de9503b1c60001de8613be789colm descriptor closed.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm </modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directivelist>
a1066e2786436743f6791963fb266282c25e1e99lgentis <directive module="mod_file_cache">MMapFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm </directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </related>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Serving directly from system memory is universally the fastest method
5302f55dd48a542de9503b1c60001de8613be789colm of serving content. Reading files from a disk controller or, even worse,
5302f55dd48a542de9503b1c60001de8613be789colm from a remote network is orders of magnitude slower. Disk controllers
5302f55dd48a542de9503b1c60001de8613be789colm usually involve physical processes, and network access is limited by
5302f55dd48a542de9503b1c60001de8613be789colm your available bandwidth. Memory access on the other hand can take mere
5302f55dd48a542de9503b1c60001de8613be789colm nano-seconds.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>System memory isn't cheap though, byte for byte it's by far the most
5302f55dd48a542de9503b1c60001de8613be789colm expensive type of storage and it's important to ensure that it is used
5302f55dd48a542de9503b1c60001de8613be789colm efficiently. By caching files in memory you decrease the amount of
5302f55dd48a542de9503b1c60001de8613be789colm memory available on the system. As we'll see, in the case of operating
5302f55dd48a542de9503b1c60001de8613be789colm system caching, this is not so much of an issue, but when using
8737696b024af8af0f42ffe4a70dc191913d697crbowen httpd's own in-memory caching it is important to make sure that you
5302f55dd48a542de9503b1c60001de8613be789colm do not allocate too much memory to a cache. Otherwise the system
5302f55dd48a542de9503b1c60001de8613be789colm will be forced to swap out memory, which will likely degrade
5302f55dd48a542de9503b1c60001de8613be789colm performance.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Almost all modern operating systems cache file-data in memory managed
5302f55dd48a542de9503b1c60001de8613be789colm directly by the kernel. This is a powerful feature, and for the most
5302f55dd48a542de9503b1c60001de8613be789colm part operating systems get it right. For example, on Linux, let's look at
5302f55dd48a542de9503b1c60001de8613be789colm the difference in the time it takes to read a file for the first time
5302f55dd48a542de9503b1c60001de8613be789colm and the second time;</p>
5302f55dd48a542de9503b1c60001de8613be789colmreal 0m0.065s
5302f55dd48a542de9503b1c60001de8613be789colmuser 0m0.000s
5302f55dd48a542de9503b1c60001de8613be789colmsys 0m0.001s
5302f55dd48a542de9503b1c60001de8613be789colmreal 0m0.003s
5302f55dd48a542de9503b1c60001de8613be789colmuser 0m0.003s
5302f55dd48a542de9503b1c60001de8613be789colmsys 0m0.000s</pre>
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Even for this small file, there is a huge difference in the amount
5302f55dd48a542de9503b1c60001de8613be789colm of time it takes to read the file. This is because the kernel has cached
5302f55dd48a542de9503b1c60001de8613be789colm the file contents in memory.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>By ensuring there is "spare" memory on your system, you can ensure
5302f55dd48a542de9503b1c60001de8613be789colm that more and more file-contents will be stored in this cache. This
5302f55dd48a542de9503b1c60001de8613be789colm can be a very efficient means of in-memory caching, and involves no
8737696b024af8af0f42ffe4a70dc191913d697crbowen extra configuration of httpd at all.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Additionally, because the operating system knows when files are
5302f55dd48a542de9503b1c60001de8613be789colm deleted or modified, it can automatically remove file contents from the
b76a31daaa6e83bb0fd627a04f20e82bffcf1df4poirier cache when necessary. This is a big advantage over httpd's in-memory
5302f55dd48a542de9503b1c60001de8613be789colm caching which has no way of knowing when a file has changed.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Despite the performance and advantages of automatic operating system
5302f55dd48a542de9503b1c60001de8613be789colm caching there are some circumstances in which in-memory caching may be
8737696b024af8af0f42ffe4a70dc191913d697crbowen better performed by httpd.</p>
a1066e2786436743f6791963fb266282c25e1e99lgentis <directive module="mod_file_cache">MMapFile</directive> directive, which
8737696b024af8af0f42ffe4a70dc191913d697crbowen allows you to have httpd map a static file's contents into memory at
8737696b024af8af0f42ffe4a70dc191913d697crbowen start time (using the mmap system call). httpd will use the in-memory
5302f55dd48a542de9503b1c60001de8613be789colm contents for all subsequent accesses to this file.</p>
a1066e2786436743f6791963fb266282c25e1e99lgentis <pre>MMapFile /usr/local/apache2/htdocs/index.html</pre>
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p>As with the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_file_cache">CacheFile</directive> directive, any
8737696b024af8af0f42ffe4a70dc191913d697crbowen changes in these files will not be picked up by httpd after it has
5302f55dd48a542de9503b1c60001de8613be789colm started.</p>
a1066e2786436743f6791963fb266282c25e1e99lgentis <p> The <directive module="mod_file_cache">MMapFile</directive>
5302f55dd48a542de9503b1c60001de8613be789colm directive does not keep track of how much memory it allocates, so
8737696b024af8af0f42ffe4a70dc191913d697crbowen you must ensure not to over-use the directive. Each httpd child
5302f55dd48a542de9503b1c60001de8613be789colm process will replicate this memory, so it is critically important
5302f55dd48a542de9503b1c60001de8613be789colm to ensure that the files mapped are not so large as to cause the
5302f55dd48a542de9503b1c60001de8613be789colm system to swap memory.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm </modulelist>
5302f55dd48a542de9503b1c60001de8613be789colm <directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </related>
5302f55dd48a542de9503b1c60001de8613be789colm <p><module>mod_disk_cache</module> provides a disk-based caching mechanism
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi for <module>mod_cache</module>. This cache is intelligent and content will
1a2bc936a6b4aaf5713c98a230a449fd878d1f06takashi be served from the cache only as long as it is considered valid.</p>
5302f55dd48a542de9503b1c60001de8613be789colmCacheEnable disk /
5302f55dd48a542de9503b1c60001de8613be789colmCacheDirLevels 2
5302f55dd48a542de9503b1c60001de8613be789colmCacheDirLength 1</pre>
5302f55dd48a542de9503b1c60001de8613be789colm </example>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Importantly, as the cached files are locally stored, operating system
5302f55dd48a542de9503b1c60001de8613be789colm in-memory caching will typically be applied to their access also. So
5302f55dd48a542de9503b1c60001de8613be789colm although the files are stored on disk, if they are frequently accessed
5302f55dd48a542de9503b1c60001de8613be789colm it is likely the operating system will ensure that they are actually
5302f55dd48a542de9503b1c60001de8613be789colm served from memory.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>To store items in the cache, <module>mod_disk_cache</module> creates
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony a 22 character hash of the URL being requested. This hash incorporates
5302f55dd48a542de9503b1c60001de8613be789colm the hostname, protocol, port, path and any CGI arguments to the URL,
5302f55dd48a542de9503b1c60001de8613be789colm to ensure that multiple URLs do not collide.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Each character may be any one of 64-different characters, which mean
88afe3e00379ac7ba573079b97e116e0a7d7a703noodl that overall there are 64^22 possible hashes. For example, a URL might
5302f55dd48a542de9503b1c60001de8613be789colm be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony as a prefix for the naming of the files specific to that URL within
5302f55dd48a542de9503b1c60001de8613be789colm the cache, however first it is split up into directories as per
5302f55dd48a542de9503b1c60001de8613be789colm the <directive module="mod_disk_cache">CacheDirLevels</directive> and
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_disk_cache">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm directives.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p><directive module="mod_disk_cache">CacheDirLevels</directive>
5302f55dd48a542de9503b1c60001de8613be789colm specifies how many levels of subdirectory there should be, and
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_disk_cache">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm specifies how many characters should be in each directory. With
5302f55dd48a542de9503b1c60001de8613be789colm the example settings given above, the hash would be turned into
5302f55dd48a542de9503b1c60001de8613be789colm a filename prefix as
5302f55dd48a542de9503b1c60001de8613be789colm <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>The overall aim of this technique is to reduce the number of
5302f55dd48a542de9503b1c60001de8613be789colm subdirectories or files that may be in a particular directory,
5302f55dd48a542de9503b1c60001de8613be789colm as most file-systems slow down as this number increases. With
5302f55dd48a542de9503b1c60001de8613be789colm setting of "1" for
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_disk_cache">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm there can at most be 64 subdirectories at any particular level.
5302f55dd48a542de9503b1c60001de8613be789colm With a setting of 2 there can be 64 * 64 subdirectories, and so on.
5302f55dd48a542de9503b1c60001de8613be789colm Unless you have a good reason not to, using a setting of "1"
5302f55dd48a542de9503b1c60001de8613be789colm for <directive module="mod_disk_cache">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm is recommended.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Setting
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_disk_cache">CacheDirLevels</directive>
5302f55dd48a542de9503b1c60001de8613be789colm depends on how many files you anticipate to store in the cache.
5302f55dd48a542de9503b1c60001de8613be789colm With the setting of "2" used in the above example, a grand
5302f55dd48a542de9503b1c60001de8613be789colm total of 4096 subdirectories can ultimately be created. With
5302f55dd48a542de9503b1c60001de8613be789colm 1 million files cached, this works out at roughly 245 cached
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony URLs per directory.</p>
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony <p>Each URL uses at least two files in the cache-store. Typically
5302f55dd48a542de9503b1c60001de8613be789colm there is a ".header" file, which includes meta-information about
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony the URL, such as when it is due to expire and a ".data" file
5302f55dd48a542de9503b1c60001de8613be789colm which is a verbatim copy of the content to be served.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>In the case of a content negotiated via the "Vary" header, a
28ff5a13eb62624f296027cc8ab0e76efdbd7450pctony ".vary" directory will be created for the URL in question. This
5302f55dd48a542de9503b1c60001de8613be789colm directory will have multiple ".data" files corresponding to the
5302f55dd48a542de9503b1c60001de8613be789colm differently negotiated content.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Although <module>mod_disk_cache</module> will remove cached content
5302f55dd48a542de9503b1c60001de8613be789colm as it is expired, it does not maintain any information on the total
5302f55dd48a542de9503b1c60001de8613be789colm size of the cache or how little free space may be left.</p>
5302f55dd48a542de9503b1c60001de8613be789colm href="programs/htcacheclean.html">htcacheclean</a> tool which, as the name
5302f55dd48a542de9503b1c60001de8613be789colm suggests, allows you to clean the cache periodically. Determining
5302f55dd48a542de9503b1c60001de8613be789colm how frequently to run <a
5302f55dd48a542de9503b1c60001de8613be789colm href="programs/htcacheclean.html">htcacheclean</a> and what target size to
5302f55dd48a542de9503b1c60001de8613be789colm use for the cache is somewhat complex and trial and error may be needed to
5302f55dd48a542de9503b1c60001de8613be789colm select optimal values.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
5302f55dd48a542de9503b1c60001de8613be789colm operation. It can be run as persistent daemon, or periodically from
5302f55dd48a542de9503b1c60001de8613be789colm href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
5302f55dd48a542de9503b1c60001de8613be789colm or more to process very large (tens of gigabytes) caches and if you are
5302f55dd48a542de9503b1c60001de8613be789colm running it from cron it is recommended that you determine how long a typical
5302f55dd48a542de9503b1c60001de8613be789colm run takes, to avoid running more than one instance at a time.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
5302f55dd48a542de9503b1c60001de8613be789colm cache growth / clean sequence.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <p>Because <module>mod_disk_cache</module> does not itself pay attention
5302f55dd48a542de9503b1c60001de8613be789colm to how much space is used you should ensure that
5302f55dd48a542de9503b1c60001de8613be789colm <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
5302f55dd48a542de9503b1c60001de8613be789colm leave enough "grow room" following a clean.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm</manualpage>