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>,
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <module>mod_cache_disk</module>, <module>mod_file_cache</module> and <a
5302f55dd48a542de9503b1c60001de8613be789colm href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The Apache HTTP server offers a range of caching features that
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin are designed to improve the performance of the server in various
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin and its provider modules
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin provide intelligent, HTTP-aware caching. The content itself is stored
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin in the cache, and mod_cache aims to honor all of the various HTTP
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin headers and options that control the cacheability of content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin as described in
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">Section
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin 13 of RFC2616</a>.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin is aimed at both simple and complex caching configurations, where
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin you are dealing with proxied content, dynamic local content or
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin have a need to speed up access to local files on a potentially
419323944a8185b7697cc6a513ef33f0285ca324minfrin The <a href="socache.html">shared object cache API</a> (socache)
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin and its provider modules provide a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server wide key/value based shared object cache. These modules
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin are designed to cache low level data such as SSL sessions and
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin authentication credentials. Backends allow the data to be stored
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server wide in shared memory, or datacenter wide in a cache such
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin as memcache or distcache.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin offers the ability to pre-load
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin files into memory on server startup, and can improve access
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin times and save file handles on files that are accessed often,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin as there is no need to go to disk on each request.
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>To get the most from this document, you should be familiar with
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim the basics of HTTP, and have read the Users' Guides to
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <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_negotiation">CacheNegotiatedDocs</directive>
5302f55dd48a542de9503b1c60001de8613be789colm </directivelist>
5302f55dd48a542de9503b1c60001de8613be789colm </related>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The HTTP protocol contains built in support for an in-line caching
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin described by section 13 of RFC2616</a>, and the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> module can be used to take advantage of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Unlike a simple two state key/value cache where the content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin disappears completely when no longer fresh, an HTTP cache includes
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a mechanism to retain stale content, and to ask the origin server
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin whether this stale content has changed and if not, make it fresh
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>An entry in an HTTP cache exists in one of three states:</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin If the content is new enough (younger than its <strong>freshness
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin lifetime</strong>), it is considered <strong>fresh</strong>. An
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin HTTP cache is free to serve fresh content without making any
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin calls to the origin server at all.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the content is too old (older than its <strong>freshness
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin lifetime</strong>), it is considered <strong>stale</strong>. An
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin HTTP cache should contact the origin server and check whether
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the content is still fresh before serving stale content to a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin client. The origin server will either respond with replacement
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin content if not still valid, or ideally, the origin server will
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin respond with a code to tell the cache the content is still
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin fresh, without the need to generate or send the content again.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin The content becomes fresh again and the cycle continues.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The HTTP protocol does allow the cache to serve stale data
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin under certain circumstances, such as when an attempt to freshen
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the data with an origin server has failed with a 5xx error, or
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin when another request is already in the process of freshening
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the given entry. In these cases a <code>Warning</code> header
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin is added to the response.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin If the cache gets full, it reserves the option to delete content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin from the cache to make space. Content can be deleted at any time,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin and can be stale or fresh. The <a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin href="programs/htcacheclean.html">htcacheclean</a> tool can be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin run on a once off basis, or deployed as a daemon to keep the size
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin of the cache within the given size, or the given number of inodes.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin The tool attempts to delete stale content before attempting to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin delete fresh content.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Full details of how HTTP caching works can be found in
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The <module>mod_cache</module> module hooks into the server in two
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin possible places depending on the value of the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_cache">CacheQuickHandler</directive> directive:
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This phase happens very early on during the request processing,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin just after the request has been parsed. If the content is
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin found within the cache, it is served immediately and almost
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin all request processing is bypassed.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>In this scenario, the cache behaves as if it has been "bolted
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin on" to the front of the server.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This mode offers the best performance, as the majority of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server processing is bypassed. This mode however also bypasses the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin authentication and authorization phases of server processing, so
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin this mode should be chosen with care when this is important.</p>
1e529026ef53ed41ebd6b16af3bbf9da9a715b90covener <p> Requests with an "Authorization" header (for example, HTTP Basic
a99c5d4cc3cab6a62b04d52000dbc22ce1fa2d94coar Authentication) are neither cacheable nor served from the cache
1e529026ef53ed41ebd6b16af3bbf9da9a715b90covener when <module>mod_cache</module> is running in this phase.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This phase happens late in the request processing, after all
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the request phases have completed.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>In this scenario, the cache behaves as if it has been "bolted
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin on" to the back of the server.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This mode offers the most flexibility, as the potential exists
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin for caching to occur at a precisely controlled point in the filter
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin chain, and cached content can be filtered or personalized before
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin being sent to the client.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the URL is not found within the cache, <module>mod_cache</module>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin will add a <a href="filter.html">filter</a> to the filter stack in order
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to record the response to the cache, and then stand down, allowing normal
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin request processing to continue. If the content is determined to be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cacheable, the content will be saved to the cache for future serving,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin otherwise the content will be ignored.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the content found within the cache is stale, the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> module converts the request into a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <strong>conditional request</strong>. If the origin server responds with
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a normal response, the normal response is cached, replacing the content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin already cached. If the origin server responds with a 304 Not Modified
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin response, the content is marked as fresh again, and the cached content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin is served by the filter instead of saving it.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When a virtual host is known by one of many different server aliases,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin ensuring that <directive module="core">UseCanonicalName</directive> is
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin set to <code>On</code> can dramatically improve the ratio of cache hits.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin This is because the hostname of the virtual-host serving the content is
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin used within 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 </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Well formed content that is intended to be cached should declare an
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin explicit freshness lifetime with the <code>Cache-Control</code>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin header's <code>max-age</code> or <code>s-maxage</code> fields, or
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>At the same time, the origin server defined freshness lifetime can
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin be overridden by a client when the client presents their own
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>Cache-Control</code> header within the request. In this case,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the lowest freshness lifetime between request and response wins.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When this freshness lifetime is missing from the request or the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin response, a default freshness lifetime is applied. The default
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin freshness lifetime for cached entities is one hour, however
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim this can be easily over-ridden by using the <directive
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin module="mod_cache">CacheDefaultExpire</directive> directive.</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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin can infer a freshness lifetime based on a heuristic, which can be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin controlled through the use of the <directive
5302f55dd48a542de9503b1c60001de8613be789colm module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>For local content, or for remote content that does not define its own
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>Expires</code> header, <module>mod_expires</module> may be used to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin fine-tune the freshness lifetime by adding <code>max-age</code> and
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The maximum freshness lifetime may also be controlled by using the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheMaxExpire</directive>.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When content expires from the cache and becomes stale, rather than
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin pass on the original request, httpd will modify the request to make
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin it conditional instead.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When an <code>ETag</code> header exists in the original cached
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>If-None-Match</code> header to the request to the origin server.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin When a <code>Last-Modified</code> header exists in the original
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cached response, <module>mod_cache</module> will add an
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>If-Modified-Since</code> header to the request to the origin
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server. Performing either of these actions makes the request
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When a conditional request is received by an origin server, the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin origin server should check whether the ETag or the Last-Modified
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin parameter has changed, as appropriate for the request. If not, the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin origin should respond with a terse "304 Not Modified" response. This
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin signals to the cache that the stale content is still fresh should be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin used for subsequent requests until the content's new freshness lifetime
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin is reached again.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the content has changed, then the content is served as if the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin request were not conditional to begin with.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Conditional requests offer two benefits. Firstly, when making such
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a request to the origin server, if the content from the origin
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin matches the content in the cache, this can be determined easily and
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin without the overhead of transferring the entire resource.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Secondly, a well designed origin server will be designed in such
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a way that conditional requests will be significantly cheaper to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin produce than a full response. For static files, typically all that is
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin involved is a call to <code>stat()</code> or similar system call, to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin see if the file has changed in size or modification time. As such, even
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin local content may still be served faster from the cache if it has not
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin changed.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Origin servers should make every effort to support conditional
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin requests as is practical, however if conditional requests are not
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin supported, the origin will respond as if the request was not
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin conditional, and the cache will respond as if the content had changed
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin and save the new content to the cache. In this case, the cache will
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin behave like a simple two state cache, where content is effectively
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin either fresh or deleted.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The full definition of which responses can be cached by an HTTP
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cache is defined in
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.4">
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin RFC2616 Section 13.4 Response Cacheability</a>, and can be summed up as
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin follows:</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <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>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <li>The response must have a HTTP status code of 200, 203, 300, 301 or
5302f55dd48a542de9503b1c60001de8613be789colm <li>If the response contains an "Authorization:" header, it must
5302f55dd48a542de9503b1c60001de8613be789colm also contain an "s-maxage", "must-revalidate" or "public" option
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin in the "Cache-Control:" header, or it won't be cached.</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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim the "Cache-Control:" header, unless the
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <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:"
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim header, it will not be stored unless the
5302f55dd48a542de9503b1c60001de8613be789colm <directive module="mod_cache">CacheStorePrivate</directive> has been
5302f55dd48a542de9503b1c60001de8613be789colm used to require otherwise.</li>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <li>Likewise, if the response includes the "no-store" option in a
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim "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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>It should be up to the client creating the request, or the origin
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server constructing the response to decide whether or not the content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin should be cacheable or not by correctly setting the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>Cache-Control</code> header, and <module>mod_cache</module> should
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin be left alone to honor the wishes of the client or server as appropriate.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Content that is time sensitive, or which varies depending on the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin particulars of the request that are not covered by HTTP negotiation,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin should not be cached. This content should declare itself uncacheable
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If content changes often, expressed by a freshness lifetime of minutes
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin or seconds, the content can still be cached, however it is highly
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin desirable that the origin server supports
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <strong>conditional requests</strong> correctly to ensure that
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin full responses do not have to be generated on a regular basis.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Content that varies based on client provided request headers can be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cached through intelligent use of the <code>Vary</code> response
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin header.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When the origin server is designed to respond with different content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin based on the value of headers in the request, for example to serve
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin multiple languages at the same URL, HTTP's caching mechanism makes it
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin possible to cache multiple variants of the same page at the same URL.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This is done by the origin server adding a <code>Vary</code> header
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to indicate which headers must be taken into account by a cache when
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin determining whether two variants are different from one another.</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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Multiple variants of the content can be cached side by side,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> uses the <code>Vary</code> header and the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin corresponding values of the request headers listed by <code>Vary</code>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to decide on which of many variants to return to the client.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The <module>mod_cache</module> module relies on specific backend store
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin implementations in order to manage the cache, and for caching to disk
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache_disk</module> is provided to support this.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Typically the module will be configured as so;</p>
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohCacheEnable disk /
b47bddbe88fb1489893591d69d4ccab9b873af68humbedoohCacheDirLevels 2
f61184822dca5bb293f1fcef7c6eb56505431b71rbowenCacheDirLength 1
b47bddbe88fb1489893591d69d4ccab9b873af68humbedooh </highlight>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Importantly, as the cached files are locally stored, operating system
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin in-memory caching will typically be applied to their access also. So
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin although the files are stored on disk, if they are frequently accessed
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin it is likely the operating system will ensure that they are actually
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin served from memory.</p>
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <p>To store items in the cache, <module>mod_cache_disk</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,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin as well as elements defined by the Vary header to ensure that multiple
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin URLs do not collide with one another.</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
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin the <directive module="mod_cache_disk">CacheDirLevels</directive> and
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <directive module="mod_cache_disk">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm directives.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p><directive module="mod_cache_disk">CacheDirLevels</directive>
5302f55dd48a542de9503b1c60001de8613be789colm specifies how many levels of subdirectory there should be, and
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <directive module="mod_cache_disk">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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim setting of "1" for
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <directive module="mod_cache_disk">CacheDirLength</directive>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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"
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin for <directive module="mod_cache_disk">CacheDirLength</directive>
5302f55dd48a542de9503b1c60001de8613be789colm is recommended.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p>Setting
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <directive module="mod_cache_disk">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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim ".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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The <module>mod_cache_disk</module> module makes no attempt to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin regulate the amount of disk space used by the cache, although it
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin will gracefully stand down on any disk error and behave as if the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cache was never present.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin href="programs/htcacheclean.html">htcacheclean</a> tool which allows you
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to clean the cache periodically. Determining how frequently to run <a
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim operation. It can be run as persistent daemon, or periodically from
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim or more to process very large (tens of gigabytes) caches and if you are
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim 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>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>It is also recommended that an appropriate "nice" level is chosen for
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin htcacheclean so that the tool does not cause excessive disk io while the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server is running.</p>
5302f55dd48a542de9503b1c60001de8613be789colm <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
5302f55dd48a542de9503b1c60001de8613be789colm cache growth / clean sequence.</p>
78f97ce162b66a0dbfd7af4dcd9984f162569b04minfrin <p>Because <module>mod_cache_disk</module> does not itself pay attention
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim to how much space is used you should ensure that
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
5302f55dd48a542de9503b1c60001de8613be789colm leave enough "grow room" following a clean.</p>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
5302f55dd48a542de9503b1c60001de8613be789colm </section>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <title>Two-state Key/Value Shared Object Caching</title>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_authn_socache">AuthnCacheSOCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_ssl">SSLSessionCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_ssl">SSLStaplingCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The Apache HTTP server offers a low level shared object cache for
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin caching information such as SSL sessions, or authentication credentials,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin within the <a href="socache.html">socache</a> interface.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Additional modules are provided for each implementation, offering the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin following backends:</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_authn_socache">AuthnCacheSOCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The <module>mod_authn_socache</module> module allows the result of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin authentication to be cached, relieving load on authentication backends.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_ssl">SSLSessionCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_ssl">SSLStaplingCache</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The <module>mod_ssl</module> module uses the <code>socache</code> interface
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to provide a session cache and a stapling cache.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </modulelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_file_cache">CacheFile</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_file_cache">MMapFile</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin </directivelist>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>On platforms where a filesystem might be slow, or where file
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin handles are expensive, the option exists to pre-load files into
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin memory on startup.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>On systems where opening files is slow, the option exists to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin open the file on startup and cache the file handle. These
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin options can help on systems where access to static files is
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The act of opening a file can itself be a source of delay, particularly
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin on network filesystems. By maintaining a cache of open file descriptors
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin for commonly served files, httpd can avoid this delay. Currently httpd
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin provides one implementation of File-Handle Caching.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The most basic form of caching present in httpd is the file-handle
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin caching provided by <module>mod_file_cache</module>. Rather than caching
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin file-contents, this cache maintains a table of open file descriptors. Files
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to be cached in this manner are specified in the configuration file using
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the <directive module="mod_file_cache">CacheFile</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directive.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_file_cache">CacheFile</directive> directive
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin instructs httpd to open the file when it is started and to re-use
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin this file-handle for all subsequent access to this file.</p>
772b90f858a887e031ee3de346471c3aa651b6a4humbedooh </highlight>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If you intend to cache a large number of files in this manner, you
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin must ensure that your operating system's limit for the number of open
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin files is set appropriately.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Although using <directive module="mod_file_cache">CacheFile</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin does not cause the file-contents to be cached per-se, it does mean
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin that if the file changes while httpd is running these changes will
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin not be picked up. The file will be consistently served as it was
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin when httpd was started.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the file is removed while httpd is running, it will continue
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to maintain an open file descriptor and serve the file as it was when
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin httpd was started. This usually also means that although the file
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin will have been deleted, and not show up on the filesystem, extra free
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin space will not be recovered until httpd is stopped and the file
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin descriptor closed.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Serving directly from system memory is universally the fastest method
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin of serving content. Reading files from a disk controller or, even worse,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin from a remote network is orders of magnitude slower. Disk controllers
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin usually involve physical processes, and network access is limited by
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin your available bandwidth. Memory access on the other hand can take mere
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin nano-seconds.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>System memory isn't cheap though, byte for byte it's by far the most
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin expensive type of storage and it's important to ensure that it is used
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin efficiently. By caching files in memory you decrease the amount of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin memory available on the system. As we'll see, in the case of operating
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin system caching, this is not so much of an issue, but when using
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin httpd's own in-memory caching it is important to make sure that you
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin do not allocate too much memory to a cache. Otherwise the system
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin will be forced to swap out memory, which will likely degrade
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin performance.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Almost all modern operating systems cache file-data in memory managed
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directly by the kernel. This is a powerful feature, and for the most
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin part operating systems get it right. For example, on Linux, let's look at
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the difference in the time it takes to read a file for the first time
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin and the second time;</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinreal 0m0.065s
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinuser 0m0.000s
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinsys 0m0.001s
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinreal 0m0.003s
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinuser 0m0.003s
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrinsys 0m0.000s</pre>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Even for this small file, there is a huge difference in the amount
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin of time it takes to read the file. This is because the kernel has cached
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the file contents in memory.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>By ensuring there is "spare" memory on your system, you can ensure
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin that more and more file-contents will be stored in this cache. This
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin can be a very efficient means of in-memory caching, and involves no
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin extra configuration of httpd at all.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Additionally, because the operating system knows when files are
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin deleted or modified, it can automatically remove file contents from the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cache when necessary. This is a big advantage over httpd's in-memory
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin caching which has no way of knowing when a file has changed.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Despite the performance and advantages of automatic operating system
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin caching there are some circumstances in which in-memory caching may be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin better performed by httpd.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_file_cache">MMapFile</directive> directive, which
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin allows you to have httpd map a static file's contents into memory at
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin start time (using the mmap system call). httpd will use the in-memory
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin contents for all subsequent accesses to this file.</p>
772b90f858a887e031ee3de346471c3aa651b6a4humbedooh </highlight>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>As with the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_file_cache">CacheFile</directive> directive, any
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin changes in these files will not be picked up by httpd after it has
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin started.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p> The <directive module="mod_file_cache">MMapFile</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directive does not keep track of how much memory it allocates, so
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin you must ensure not to over-use the directive. Each httpd child
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin process will replicate this memory, so it is critically important
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to ensure that the files mapped are not so large as to cause the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin system to swap memory.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>Using <module>mod_cache</module> in its default state where
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_cache">CacheQuickHandler</directive> is set to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>On</code> is very much like having a caching reverse-proxy bolted
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin to the front of the server. Requests will be served by the caching module
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin unless it determines that the origin server should be queried just as an
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin external cache would, and this drastically changes the security model of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>As traversing a filesystem hierarchy to examine potential
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <code>.htaccess</code> files would be a very expensive operation,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin partially defeating the point of caching (to speed up requests),
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> makes no decision about whether a cached
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin entity is authorised for serving. In other words; if
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> has cached some content, it will be served
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin from the cache as long as that content has not expired.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If, for example, your configuration permits access to a resource by IP
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin address you should ensure that this content is not cached. You can do this
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin by using the <directive module="mod_cache">CacheDisable</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directive, or <module>mod_expires</module>. Left unchecked,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <module>mod_cache</module> - very much like a reverse proxy - would cache
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the content when served and then serve it to any client, on any IP
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin address.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When the <directive module="mod_cache">CacheQuickHandler</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directive is set to <code>Off</code>, the full set of request processing
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin phases are executed and the security model remains unchanged.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>As requests to end-users can be served from the cache, the cache
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin itself can become a target for those wishing to deface or interfere with
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin content. It is important to bear in mind that the cache must at all
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin times be writable by the user which httpd is running as. This is in
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin stark contrast to the usually recommended situation of maintaining
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin all content unwritable by the Apache user.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>If the Apache user is compromised, for example through a flaw in
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a CGI process, it is possible that the cache may be targeted. When
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin using <module>mod_cache_disk</module>, it is relatively easy to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin insert or modify a cached entity.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This presents a somewhat elevated risk in comparison to the other
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin types of attack it is possible to make as the Apache user. If you are
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin using <module>mod_cache_disk</module> you should bear this in mind -
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin ensure you upgrade httpd when security upgrades are announced and
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin run CGI processes as a non-Apache user using <a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>When running httpd as a caching proxy server, there is also the
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin potential for so-called cache poisoning. Cache Poisoning is a broad
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin term for attacks in which an attacker causes the proxy server to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin retrieve incorrect (and usually undesirable) content from the origin
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin server.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>For example if the DNS servers used by your system running httpd
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin are vulnerable to DNS cache poisoning, an attacker may be able to control
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin where httpd connects to when requesting content from the origin server.
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin Another example is so-called HTTP request-smuggling attacks.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>This document is not the correct place for an in-depth discussion
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin of HTTP request smuggling (instead, try your favourite search engine)
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin however it is important to be aware that it is possible to make
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin a series of requests, and to exploit a vulnerability on an origin
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin webserver such that the attacker can entirely control the content
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin retrieved by the proxy.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>The Vary mechanism allows multiple variants of the same URL to be
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin cached side by side. Depending on header values provided by the client,
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the cache will select the correct variant to return to the client. This
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin mechanism can become a problem when an attempt is made to vary on a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin header that is known to contain a wide range of possible values under
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin normal use, for example the <code>User-Agent</code> header. Depending
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin on the popularity of the particular web site thousands or millions of
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin duplicate cache entries could be created for the same URL, crowding
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin out other entries in the cache.</p>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <p>In other cases, there may be a need to change the URL of a particular
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin resource on every request, usually by adding a "cachebuster" string to
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin the URL. If this content is declared cacheable by a server for a
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin significant freshness lifetime, these entries can crowd out
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin legitimate entries in a cache. While <module>mod_cache</module>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin <directive module="mod_cache">CacheIgnoreURLSessionIdentifiers</directive>
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin directive, this directive should be used with care to ensure that
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin downstream proxy or browser caches aren't subjected to the same denial
47cf0686f54bab5495aae9455d7ffa7c75c2e64bminfrin of service issue.</p>
5302f55dd48a542de9503b1c60001de8613be789colm</manualpage>