1 <?xml version="1.0" encoding="ISO-8859-1"?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head>
4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
7 This file is generated from xml source: DO NOT EDIT
8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
10 <title>Caching Guide - Apache HTTP Server Version 2.5</title>
11 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
12 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
13 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" />
14 <script src="./style/scripts/prettify.min.js" type="text/javascript">
17 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
18 <body id="manual-page"><div id="page-header">
19 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
20 <p class="apache">Apache HTTP Server Version 2.5</p>
21 <img alt="" src="./images/feather.png" /></div>
22 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
24 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.5</a></div><div id="page-content"><div id="preamble"><h1>Caching Guide</h1>
26 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> |
27 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
28 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
31 <p>This document supplements the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>,
32 <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code>, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> and <a href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
33 It describes how to use the Apache HTTP Server's caching features to accelerate web and
34 proxy serving, while avoiding common problems and misconfigurations.</p>
36 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li>
37 <li><img alt="" src="./images/down.gif" /> <a href="#http-caching">Three-state RFC2616 HTTP caching</a></li>
38 <li><img alt="" src="./images/down.gif" /> <a href="#examples">Cache Setup Examples</a></li>
39 <li><img alt="" src="./images/down.gif" /> <a href="#socache-caching">General Two-state Key/Value Shared Object Caching</a></li>
40 <li><img alt="" src="./images/down.gif" /> <a href="#file-caching">Specialized File Caching</a></li>
41 <li><img alt="" src="./images/down.gif" /> <a href="#security">Security Considerations</a></li>
42 </ul><h3>See also</h3><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
43 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
45 <h2><a name="introduction" id="introduction">Introduction</a></h2>
48 <p>The Apache HTTP server offers a range of caching features that
49 are designed to improve the performance of the server in various
53 <dt>Three-state RFC2616 HTTP caching</dt>
55 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
56 and its provider modules
57 <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code>
58 provide intelligent, HTTP-aware caching. The content itself is stored
59 in the cache, and mod_cache aims to honor all of the various HTTP
60 headers and options that control the cacheability of content
62 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">Section
64 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
65 is aimed at both simple and complex caching configurations, where
66 you are dealing with proxied content, dynamic local content or
67 have a need to speed up access to local files on a potentially
71 <dt>Two-state key/value shared object caching</dt>
73 The <a href="socache.html">shared object cache API</a> (socache)
74 and its provider modules provide a
75 server wide key/value based shared object cache. These modules
76 are designed to cache low level data such as SSL sessions and
77 authentication credentials. Backends allow the data to be stored
78 server wide in shared memory, or datacenter wide in a cache such
79 as memcache or distcache.
82 <dt>Specialized file caching</dt>
84 <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code>
85 offers the ability to pre-load
86 files into memory on server startup, and can improve access
87 times and save file handles on files that are accessed often,
88 as there is no need to go to disk on each request.
92 <p>To get the most from this document, you should be familiar with
93 the basics of HTTP, and have read the Users' Guides to
94 <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
95 <a href="content-negotiation.html">Content negotiation</a>.</p>
97 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
99 <h2><a name="http-caching" id="http-caching">Three-state RFC2616 HTTP caching</a></h2>
103 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code></li><li><code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code></li><li><code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code></li><li><code class="directive"><a href="./mod/mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</a></code></li></ul></td></tr></table>
105 <p>The HTTP protocol contains built in support for an in-line caching
107 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
108 described by section 13 of RFC2616</a>, and the
109 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> module can be used to take advantage of
112 <p>Unlike a simple two state key/value cache where the content
113 disappears completely when no longer fresh, an HTTP cache includes
114 a mechanism to retain stale content, and to ask the origin server
115 whether this stale content has changed and if not, make it fresh
118 <p>An entry in an HTTP cache exists in one of three states:</p>
123 If the content is new enough (younger than its <strong>freshness
124 lifetime</strong>), it is considered <strong>fresh</strong>. An
125 HTTP cache is free to serve fresh content without making any
126 calls to the origin server at all.
130 <p>If the content is too old (older than its <strong>freshness
131 lifetime</strong>), it is considered <strong>stale</strong>. An
132 HTTP cache should contact the origin server and check whether
133 the content is still fresh before serving stale content to a
134 client. The origin server will either respond with replacement
135 content if not still valid, or ideally, the origin server will
136 respond with a code to tell the cache the content is still
137 fresh, without the need to generate or send the content again.
138 The content becomes fresh again and the cycle continues.</p>
140 <p>The HTTP protocol does allow the cache to serve stale data
141 under certain circumstances, such as when an attempt to freshen
142 the data with an origin server has failed with a 5xx error, or
143 when another request is already in the process of freshening
144 the given entry. In these cases a <code>Warning</code> header
145 is added to the response.</p>
147 <dt>Non Existent</dt>
149 If the cache gets full, it reserves the option to delete content
150 from the cache to make space. Content can be deleted at any time,
151 and can be stale or fresh. The <a href="programs/htcacheclean.html">htcacheclean</a> tool can be
152 run on a once off basis, or deployed as a daemon to keep the size
153 of the cache within the given size, or the given number of inodes.
154 The tool attempts to delete stale content before attempting to
155 delete fresh content.
159 <p>Full details of how HTTP caching works can be found in
160 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
161 Section 13 of RFC2616</a>.</p>
163 <h3>Interaction with the Server</h3>
166 <p>The <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> module hooks into the server in two
167 possible places depending on the value of the
168 <code class="directive"><a href="./mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code> directive:
172 <dt>Quick handler phase</dt>
174 <p>This phase happens very early on during the request processing,
175 just after the request has been parsed. If the content is
176 found within the cache, it is served immediately and almost
177 all request processing is bypassed.</p>
179 <p>In this scenario, the cache behaves as if it has been "bolted
180 on" to the front of the server.</p>
182 <p>This mode offers the best performance, as the majority of
183 server processing is bypassed. This mode however also bypasses the
184 authentication and authorization phases of server processing, so
185 this mode should be chosen with care when this is important.</p>
187 <p> Requests with an "Authorization" header (for example, HTTP Basic
188 Authentication) are neither cacheable nor served from the cache
189 when <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> is running in this phase.</p>
191 <dt>Normal handler phase</dt>
193 <p>This phase happens late in the request processing, after all
194 the request phases have completed.</p>
196 <p>In this scenario, the cache behaves as if it has been "bolted
197 on" to the back of the server.</p>
199 <p>This mode offers the most flexibility, as the potential exists
200 for caching to occur at a precisely controlled point in the filter
201 chain, and cached content can be filtered or personalized before
202 being sent to the client.</p>
206 <p>If the URL is not found within the cache, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
207 will add a <a href="filter.html">filter</a> to the filter stack in order
208 to record the response to the cache, and then stand down, allowing normal
209 request processing to continue. If the content is determined to be
210 cacheable, the content will be saved to the cache for future serving,
211 otherwise the content will be ignored.</p>
213 <p>If the content found within the cache is stale, the
214 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> module converts the request into a
215 <strong>conditional request</strong>. If the origin server responds with
216 a normal response, the normal response is cached, replacing the content
217 already cached. If the origin server responds with a 304 Not Modified
218 response, the content is marked as fresh again, and the cached content
219 is served by the filter instead of saving it.</p>
222 <h3>Improving Cache Hits</h3>
225 <p>When a virtual host is known by one of many different server aliases,
226 ensuring that <code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code> is
227 set to <code>On</code> can dramatically improve the ratio of cache hits.
228 This is because the hostname of the virtual-host serving the content is
229 used within the cache key. With the setting set to <code>On</code>
230 virtual-hosts with multiple server names or aliases will not produce
231 differently cached entities, and instead content will be cached as
232 per the canonical hostname.</p>
236 <h3>Freshness Lifetime</h3>
239 <p>Well formed content that is intended to be cached should declare an
240 explicit freshness lifetime with the <code>Cache-Control</code>
241 header's <code>max-age</code> or <code>s-maxage</code> fields, or
242 by including an <code>Expires</code> header.</p>
244 <p>At the same time, the origin server defined freshness lifetime can
245 be overridden by a client when the client presents their own
246 <code>Cache-Control</code> header within the request. In this case,
247 the lowest freshness lifetime between request and response wins.</p>
249 <p>When this freshness lifetime is missing from the request or the
250 response, a default freshness lifetime is applied. The default
251 freshness lifetime for cached entities is one hour, however
252 this can be easily over-ridden by using the <code class="directive"><a href="./mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive.</p>
254 <p>If a response does not include an <code>Expires</code> header but does
255 include a <code>Last-Modified</code> header, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
256 can infer a freshness lifetime based on a heuristic, which can be
257 controlled through the use of the <code class="directive"><a href="./mod/mod_cache.html#cachelastmodifiedfactor">CacheLastModifiedFactor</a></code> directive.</p>
259 <p>For local content, or for remote content that does not define its own
260 <code>Expires</code> header, <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code> may be used to
261 fine-tune the freshness lifetime by adding <code>max-age</code> and
262 <code>Expires</code>.</p>
264 <p>The maximum freshness lifetime may also be controlled by using the
265 <code class="directive"><a href="./mod/mod_cache.html#cachemaxexpire">CacheMaxExpire</a></code>.</p>
269 <h3>A Brief Guide to Conditional Requests</h3>
272 <p>When content expires from the cache and becomes stale, rather than
273 pass on the original request, httpd will modify the request to make
274 it conditional instead.</p>
276 <p>When an <code>ETag</code> header exists in the original cached
277 response, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will add an
278 <code>If-None-Match</code> header to the request to the origin server.
279 When a <code>Last-Modified</code> header exists in the original
280 cached response, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will add an
281 <code>If-Modified-Since</code> header to the request to the origin
282 server. Performing either of these actions makes the request
283 <strong>conditional</strong>.</p>
285 <p>When a conditional request is received by an origin server, the
286 origin server should check whether the ETag or the Last-Modified
287 parameter has changed, as appropriate for the request. If not, the
288 origin should respond with a terse "304 Not Modified" response. This
289 signals to the cache that the stale content is still fresh should be
290 used for subsequent requests until the content's new freshness lifetime
291 is reached again.</p>
293 <p>If the content has changed, then the content is served as if the
294 request were not conditional to begin with.</p>
296 <p>Conditional requests offer two benefits. Firstly, when making such
297 a request to the origin server, if the content from the origin
298 matches the content in the cache, this can be determined easily and
299 without the overhead of transferring the entire resource.</p>
301 <p>Secondly, a well designed origin server will be designed in such
302 a way that conditional requests will be significantly cheaper to
303 produce than a full response. For static files, typically all that is
304 involved is a call to <code>stat()</code> or similar system call, to
305 see if the file has changed in size or modification time. As such, even
306 local content may still be served faster from the cache if it has not
309 <p>Origin servers should make every effort to support conditional
310 requests as is practical, however if conditional requests are not
311 supported, the origin will respond as if the request was not
312 conditional, and the cache will respond as if the content had changed
313 and save the new content to the cache. In this case, the cache will
314 behave like a simple two state cache, where content is effectively
315 either fresh or deleted.</p>
318 <h3>What Can be Cached?</h3>
321 <p>The full definition of which responses can be cached by an HTTP
323 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.4">
324 RFC2616 Section 13.4 Response Cacheability</a>, and can be summed up as
328 <li>Caching must be enabled for this URL. See the <code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> and <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code> directives.</li>
330 <li>The response must have a HTTP status code of 200, 203, 300, 301 or
333 <li>The request must be a HTTP GET request.</li>
335 <li>If the response contains an "Authorization:" header, it must
336 also contain an "s-maxage", "must-revalidate" or "public" option
337 in the "Cache-Control:" header, or it won't be cached.</li>
339 <li>If the URL included a query string (e.g. from a HTML form GET
340 method) it will not be cached unless the response specifies an
341 explicit expiration by including an "Expires:" header or the max-age
342 or s-maxage directive of the "Cache-Control:" header, as per RFC2616
343 sections 13.9 and 13.2.1.</li>
345 <li>If the response has a status of 200 (OK), the response must
346 also include at least one of the "Etag", "Last-Modified" or
347 the "Expires" headers, or the max-age or s-maxage directive of
348 the "Cache-Control:" header, unless the
349 <code class="directive"><a href="./mod/mod_cache.html#cacheignorenolastmod">CacheIgnoreNoLastMod</a></code>
350 directive has been used to require otherwise.</li>
352 <li>If the response includes the "private" option in a "Cache-Control:"
353 header, it will not be stored unless the
354 <code class="directive"><a href="./mod/mod_cache.html#cachestoreprivate">CacheStorePrivate</a></code> has been
355 used to require otherwise.</li>
357 <li>Likewise, if the response includes the "no-store" option in a
358 "Cache-Control:" header, it will not be stored unless the
359 <code class="directive"><a href="./mod/mod_cache.html#cachestorenostore">CacheStoreNoStore</a></code> has been
362 <li>A response will not be stored if it includes a "Vary:" header
363 containing the match-all "*".</li>
367 <h3>What Should Not be Cached?</h3>
370 <p>It should be up to the client creating the request, or the origin
371 server constructing the response to decide whether or not the content
372 should be cacheable or not by correctly setting the
373 <code>Cache-Control</code> header, and <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> should
374 be left alone to honor the wishes of the client or server as appropriate.
377 <p>Content that is time sensitive, or which varies depending on the
378 particulars of the request that are not covered by HTTP negotiation,
379 should not be cached. This content should declare itself uncacheable
380 using the <code>Cache-Control</code> header.</p>
382 <p>If content changes often, expressed by a freshness lifetime of minutes
383 or seconds, the content can still be cached, however it is highly
384 desirable that the origin server supports
385 <strong>conditional requests</strong> correctly to ensure that
386 full responses do not have to be generated on a regular basis.</p>
388 <p>Content that varies based on client provided request headers can be
389 cached through intelligent use of the <code>Vary</code> response
394 <h3>Variable/Negotiated Content</h3>
397 <p>When the origin server is designed to respond with different content
398 based on the value of headers in the request, for example to serve
399 multiple languages at the same URL, HTTP's caching mechanism makes it
400 possible to cache multiple variants of the same page at the same URL.</p>
402 <p>This is done by the origin server adding a <code>Vary</code> header
403 to indicate which headers must be taken into account by a cache when
404 determining whether two variants are different from one another.</p>
406 <p>If for example, a response is received with a vary header such as;</p>
408 <div class="example"><p><code>
409 Vary: negotiate,accept-language,accept-charset
412 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will only serve the cached content to
413 requesters with accept-language and accept-charset headers
414 matching those of the original request.</p>
416 <p>Multiple variants of the content can be cached side by side,
417 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> uses the <code>Vary</code> header and the
418 corresponding values of the request headers listed by <code>Vary</code>
419 to decide on which of many variants to return to the client.</p>
422 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
423 <div class="section">
424 <h2><a name="examples" id="examples">Cache Setup Examples</a></h2>
428 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code></li><li><code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code></li><li><code class="module"><a href="./mod/mod_cache_socache.html">mod_cache_socache</a></code></li><li><code class="module"><a href="./mod/mod_socache_memcache.html">mod_socache_memcache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache_disk.html#cacheroot">CacheRoot</a></code></li><li><code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code></li><li><code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code></li><li><code class="directive"><a href="./mod/mod_cache_socache.html#cachesocache">CacheSocache</a></code></li></ul></td></tr></table>
430 <h3><a name="disk" id="disk">Caching to Disk</a></h3>
433 <p>The <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> module relies on specific backend store
434 implementations in order to manage the cache, and for caching to disk
435 <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> is provided to support this.</p>
437 <p>Typically the module will be configured as so;</p>
439 <pre class="prettyprint lang-config">CacheRoot "/var/cache/apache/"
442 CacheDirLength 1</pre>
445 <p>Importantly, as the cached files are locally stored, operating system
446 in-memory caching will typically be applied to their access also. So
447 although the files are stored on disk, if they are frequently accessed
448 it is likely the operating system will ensure that they are actually
449 served from memory.</p>
453 <h3>Understanding the Cache-Store</h3>
456 <p>To store items in the cache, <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> creates
457 a 22 character hash of the URL being requested. This hash incorporates
458 the hostname, protocol, port, path and any CGI arguments to the URL,
459 as well as elements defined by the Vary header to ensure that multiple
460 URLs do not collide with one another.</p>
462 <p>Each character may be any one of 64-different characters, which mean
463 that overall there are 64^22 possible hashes. For example, a URL might
464 be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
465 as a prefix for the naming of the files specific to that URL within
466 the cache, however first it is split up into directories as per
467 the <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code> and
468 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
471 <p><code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code>
472 specifies how many levels of subdirectory there should be, and
473 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
474 specifies how many characters should be in each directory. With
475 the example settings given above, the hash would be turned into
477 <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
479 <p>The overall aim of this technique is to reduce the number of
480 subdirectories or files that may be in a particular directory,
481 as most file-systems slow down as this number increases. With
483 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
484 there can at most be 64 subdirectories at any particular level.
485 With a setting of 2 there can be 64 * 64 subdirectories, and so on.
486 Unless you have a good reason not to, using a setting of "1"
487 for <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
491 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code>
492 depends on how many files you anticipate to store in the cache.
493 With the setting of "2" used in the above example, a grand
494 total of 4096 subdirectories can ultimately be created. With
495 1 million files cached, this works out at roughly 245 cached
496 URLs per directory.</p>
498 <p>Each URL uses at least two files in the cache-store. Typically
499 there is a ".header" file, which includes meta-information about
500 the URL, such as when it is due to expire and a ".data" file
501 which is a verbatim copy of the content to be served.</p>
503 <p>In the case of a content negotiated via the "Vary" header, a
504 ".vary" directory will be created for the URL in question. This
505 directory will have multiple ".data" files corresponding to the
506 differently negotiated content.</p>
509 <h3>Maintaining the Disk Cache</h3>
512 <p>The <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> module makes no attempt to
513 regulate the amount of disk space used by the cache, although it
514 will gracefully stand down on any disk error and behave as if the
515 cache was never present.</p>
517 <p>Instead, provided with httpd is the <a href="programs/htcacheclean.html">htcacheclean</a> tool which allows you
518 to clean the cache periodically. Determining how frequently to run <a href="programs/htcacheclean.html">htcacheclean</a> and what target size to
519 use for the cache is somewhat complex and trial and error may be needed to
520 select optimal values.</p>
522 <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
523 operation. It can be run as persistent daemon, or periodically from
524 cron. <a href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
525 or more to process very large (tens of gigabytes) caches and if you are
526 running it from cron it is recommended that you determine how long a typical
527 run takes, to avoid running more than one instance at a time.</p>
529 <p>It is also recommended that an appropriate "nice" level is chosen for
530 htcacheclean so that the tool does not cause excessive disk io while the
531 server is running.</p>
534 <img src="images/caching_fig1.gif" alt="" width="600" height="406" /><br />
535 <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
536 cache growth / clean sequence.</p>
538 <p>Because <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> does not itself pay attention
539 to how much space is used you should ensure that
540 <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
541 leave enough "grow room" following a clean.</p>
544 <h3><a name="memcache" id="memcache">Caching to memcached</a></h3>
547 <p>Using the <code class="module"><a href="./mod/mod_cache_socache.html">mod_cache_socache</a></code> module, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
548 can cache data from a variety of implementations (aka: "providers"). Using the
549 <code class="module"><a href="./mod/mod_socache_memcache.html">mod_socache_memcache</a></code> module, for example, one can specify that
550 <a href="http://memcached.org">memcached</a> is to be used as the
551 the backend storage mechanism.</p>
553 <p>Typically the module will be configured as so:</p>
555 <pre class="prettyprint lang-config">CacheEnable socache /
556 CacheSocache memcache:memcd.example.com:11211</pre>
559 <p>Additional <code>memcached</code> servers can be specified by
560 appending them to the end of the <code>CacheSocache memcache:</code>
561 line separated by commas:</p>
563 <pre class="prettyprint lang-config">CacheEnable socache /
564 CacheSocache memcache:mem1.example.com:11211,mem2.example.com:11212</pre>
567 <p>This format is also used with the other various <code class="module"><a href="./mod/mod_cache_socache.html">mod_cache_socache</a></code>
568 providers. For example:</p>
570 <pre class="prettyprint lang-config">CacheEnable socache /
571 CacheSocache shmcb:/path/to/datafile(512000)</pre>
574 <pre class="prettyprint lang-config">CacheEnable socache /
575 CacheSocache dbm:/path/to/datafile</pre>
580 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
581 <div class="section">
582 <h2><a name="socache-caching" id="socache-caching">General Two-state Key/Value Shared Object Caching</a></h2>
586 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_authn_socache.html">mod_authn_socache</a></code></li><li><code class="module"><a href="./mod/mod_socache_dbm.html">mod_socache_dbm</a></code></li><li><code class="module"><a href="./mod/mod_socache_dc.html">mod_socache_dc</a></code></li><li><code class="module"><a href="./mod/mod_socache_memcache.html">mod_socache_memcache</a></code></li><li><code class="module"><a href="./mod/mod_socache_shmcb.html">mod_socache_shmcb</a></code></li><li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_authn_socache.html#authncachesocache">AuthnCacheSOCache</a></code></li><li><code class="directive"><a href="./mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code></li><li><code class="directive"><a href="./mod/mod_ssl.html#sslstaplingcache">SSLStaplingCache</a></code></li></ul></td></tr></table>
588 <p>The Apache HTTP server offers a low level shared object cache for
589 caching information such as SSL sessions, or authentication credentials,
590 within the <a href="socache.html">socache</a> interface.</p>
592 <p>Additional modules are provided for each implementation, offering the
593 following backends:</p>
596 <dt><code class="module"><a href="./mod/mod_socache_dbm.html">mod_socache_dbm</a></code></dt>
597 <dd>DBM based shared object cache.</dd>
598 <dt><code class="module"><a href="./mod/mod_socache_dc.html">mod_socache_dc</a></code></dt>
599 <dd>Distcache based shared object cache.</dd>
600 <dt><code class="module"><a href="./mod/mod_socache_memcache.html">mod_socache_memcache</a></code></dt>
601 <dd>Memcache based shared object cache.</dd>
602 <dt><code class="module"><a href="./mod/mod_socache_shmcb.html">mod_socache_shmcb</a></code></dt>
603 <dd>Shared memory based shared object cache.</dd>
606 <h3><a name="mod_authn_socache-caching" id="mod_authn_socache-caching">Caching Authentication Credentials</a></h3>
609 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_authn_socache.html">mod_authn_socache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_authn_socache.html#authncachesocache">AuthnCacheSOCache</a></code></li></ul></td></tr></table>
611 <p>The <code class="module"><a href="./mod/mod_authn_socache.html">mod_authn_socache</a></code> module allows the result of
612 authentication to be cached, relieving load on authentication backends.</p>
616 <h3><a name="mod_ssl-caching" id="mod_ssl-caching">Caching SSL Sessions</a></h3>
619 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_ssl.html#sslsessioncache">SSLSessionCache</a></code></li><li><code class="directive"><a href="./mod/mod_ssl.html#sslstaplingcache">SSLStaplingCache</a></code></li></ul></td></tr></table>
621 <p>The <code class="module"><a href="./mod/mod_ssl.html">mod_ssl</a></code> module uses the <code>socache</code> interface
622 to provide a session cache and a stapling cache.</p>
626 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
627 <div class="section">
628 <h2><a name="file-caching" id="file-caching">Specialized File Caching</a></h2>
632 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code></li><li><code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code></li></ul></td></tr></table>
634 <p>On platforms where a filesystem might be slow, or where file
635 handles are expensive, the option exists to pre-load files into
636 memory on startup.</p>
638 <p>On systems where opening files is slow, the option exists to
639 open the file on startup and cache the file handle. These
640 options can help on systems where access to static files is
643 <h3><a name="filehandle" id="filehandle">File-Handle Caching</a></h3>
646 <p>The act of opening a file can itself be a source of delay, particularly
647 on network filesystems. By maintaining a cache of open file descriptors
648 for commonly served files, httpd can avoid this delay. Currently httpd
649 provides one implementation of File-Handle Caching.</p>
654 <p>The most basic form of caching present in httpd is the file-handle
655 caching provided by <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code>. Rather than caching
656 file-contents, this cache maintains a table of open file descriptors. Files
657 to be cached in this manner are specified in the configuration file using
658 the <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
662 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive
663 instructs httpd to open the file when it is started and to re-use
664 this file-handle for all subsequent access to this file.</p>
666 <pre class="prettyprint lang-config">CacheFile /usr/local/apache2/htdocs/index.html</pre>
669 <p>If you intend to cache a large number of files in this manner, you
670 must ensure that your operating system's limit for the number of open
671 files is set appropriately.</p>
673 <p>Although using <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
674 does not cause the file-contents to be cached per-se, it does mean
675 that if the file changes while httpd is running these changes will
676 not be picked up. The file will be consistently served as it was
677 when httpd was started.</p>
679 <p>If the file is removed while httpd is running, it will continue
680 to maintain an open file descriptor and serve the file as it was when
681 httpd was started. This usually also means that although the file
682 will have been deleted, and not show up on the filesystem, extra free
683 space will not be recovered until httpd is stopped and the file
684 descriptor closed.</p>
689 <h3><a name="inmemory" id="inmemory">In-Memory Caching</a></h3>
692 <p>Serving directly from system memory is universally the fastest method
693 of serving content. Reading files from a disk controller or, even worse,
694 from a remote network is orders of magnitude slower. Disk controllers
695 usually involve physical processes, and network access is limited by
696 your available bandwidth. Memory access on the other hand can take mere
699 <p>System memory isn't cheap though, byte for byte it's by far the most
700 expensive type of storage and it's important to ensure that it is used
701 efficiently. By caching files in memory you decrease the amount of
702 memory available on the system. As we'll see, in the case of operating
703 system caching, this is not so much of an issue, but when using
704 httpd's own in-memory caching it is important to make sure that you
705 do not allocate too much memory to a cache. Otherwise the system
706 will be forced to swap out memory, which will likely degrade
709 <h4>Operating System Caching</h4>
712 <p>Almost all modern operating systems cache file-data in memory managed
713 directly by the kernel. This is a powerful feature, and for the most
714 part operating systems get it right. For example, on Linux, let's look at
715 the difference in the time it takes to read a file for the first time
716 and the second time;</p>
718 <div class="example"><pre>colm@coroebus:~$ time cat testfile > /dev/null
722 colm@coroebus:~$ time cat testfile > /dev/null
725 sys 0m0.000s</pre></div>
727 <p>Even for this small file, there is a huge difference in the amount
728 of time it takes to read the file. This is because the kernel has cached
729 the file contents in memory.</p>
731 <p>By ensuring there is "spare" memory on your system, you can ensure
732 that more and more file-contents will be stored in this cache. This
733 can be a very efficient means of in-memory caching, and involves no
734 extra configuration of httpd at all.</p>
736 <p>Additionally, because the operating system knows when files are
737 deleted or modified, it can automatically remove file contents from the
738 cache when necessary. This is a big advantage over httpd's in-memory
739 caching which has no way of knowing when a file has changed.</p>
742 <p>Despite the performance and advantages of automatic operating system
743 caching there are some circumstances in which in-memory caching may be
744 better performed by httpd.</p>
746 <h4>MMapFile Caching</h4>
749 <p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> provides the
750 <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code> directive, which
751 allows you to have httpd map a static file's contents into memory at
752 start time (using the mmap system call). httpd will use the in-memory
753 contents for all subsequent accesses to this file.</p>
755 <pre class="prettyprint lang-config">MMapFile /usr/local/apache2/htdocs/index.html</pre>
759 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive, any
760 changes in these files will not be picked up by httpd after it has
763 <p> The <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code>
764 directive does not keep track of how much memory it allocates, so
765 you must ensure not to over-use the directive. Each httpd child
766 process will replicate this memory, so it is critically important
767 to ensure that the files mapped are not so large as to cause the
768 system to swap memory.</p>
772 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
773 <div class="section">
774 <h2><a name="security" id="security">Security Considerations</a></h2>
777 <h3>Authorization and Access Control</h3>
780 <p>Using <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> in its default state where
781 <code class="directive"><a href="./mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code> is set to
782 <code>On</code> is very much like having a caching reverse-proxy bolted
783 to the front of the server. Requests will be served by the caching module
784 unless it determines that the origin server should be queried just as an
785 external cache would, and this drastically changes the security model of
788 <p>As traversing a filesystem hierarchy to examine potential
789 <code>.htaccess</code> files would be a very expensive operation,
790 partially defeating the point of caching (to speed up requests),
791 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> makes no decision about whether a cached
792 entity is authorised for serving. In other words; if
793 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> has cached some content, it will be served
794 from the cache as long as that content has not expired.</p>
796 <p>If, for example, your configuration permits access to a resource by IP
797 address you should ensure that this content is not cached. You can do this
798 by using the <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code>
799 directive, or <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code>. Left unchecked,
800 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> - very much like a reverse proxy - would cache
801 the content when served and then serve it to any client, on any IP
804 <p>When the <code class="directive"><a href="./mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code>
805 directive is set to <code>Off</code>, the full set of request processing
806 phases are executed and the security model remains unchanged.</p>
809 <h3>Local exploits</h3>
812 <p>As requests to end-users can be served from the cache, the cache
813 itself can become a target for those wishing to deface or interfere with
814 content. It is important to bear in mind that the cache must at all
815 times be writable by the user which httpd is running as. This is in
816 stark contrast to the usually recommended situation of maintaining
817 all content unwritable by the Apache user.</p>
819 <p>If the Apache user is compromised, for example through a flaw in
820 a CGI process, it is possible that the cache may be targeted. When
821 using <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code>, it is relatively easy to
822 insert or modify a cached entity.</p>
824 <p>This presents a somewhat elevated risk in comparison to the other
825 types of attack it is possible to make as the Apache user. If you are
826 using <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> you should bear this in mind -
827 ensure you upgrade httpd when security upgrades are announced and
828 run CGI processes as a non-Apache user using <a href="suexec.html">suEXEC</a> if possible.</p>
832 <h3>Cache Poisoning</h3>
835 <p>When running httpd as a caching proxy server, there is also the
836 potential for so-called cache poisoning. Cache Poisoning is a broad
837 term for attacks in which an attacker causes the proxy server to
838 retrieve incorrect (and usually undesirable) content from the origin
841 <p>For example if the DNS servers used by your system running httpd
842 are vulnerable to DNS cache poisoning, an attacker may be able to control
843 where httpd connects to when requesting content from the origin server.
844 Another example is so-called HTTP request-smuggling attacks.</p>
846 <p>This document is not the correct place for an in-depth discussion
847 of HTTP request smuggling (instead, try your favourite search engine)
848 however it is important to be aware that it is possible to make
849 a series of requests, and to exploit a vulnerability on an origin
850 webserver such that the attacker can entirely control the content
851 retrieved by the proxy.</p>
854 <h3>Denial of Service / Cachebusting</h3>
857 <p>The Vary mechanism allows multiple variants of the same URL to be
858 cached side by side. Depending on header values provided by the client,
859 the cache will select the correct variant to return to the client. This
860 mechanism can become a problem when an attempt is made to vary on a
861 header that is known to contain a wide range of possible values under
862 normal use, for example the <code>User-Agent</code> header. Depending
863 on the popularity of the particular web site thousands or millions of
864 duplicate cache entries could be created for the same URL, crowding
865 out other entries in the cache.</p>
867 <p>In other cases, there may be a need to change the URL of a particular
868 resource on every request, usually by adding a "cachebuster" string to
869 the URL. If this content is declared cacheable by a server for a
870 significant freshness lifetime, these entries can crowd out
871 legitimate entries in a cache. While <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
873 <code class="directive"><a href="./mod/mod_cache.html#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></code>
874 directive, this directive should be used with care to ensure that
875 downstream proxy or browser caches aren't subjected to the same denial
876 of service issue.</p>
879 <div class="bottomlang">
880 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> |
881 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
882 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
883 </div><div class="top"><a href="#page-header"><img src="./images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div>
884 <script type="text/javascript"><!--//--><![CDATA[//><!--
885 var comments_shortname = 'httpd';
886 var comments_identifier = 'http://httpd.apache.org/docs/trunk/caching.html';
888 if (w.location.hostname.toLowerCase() == "httpd.apache.org") {
889 d.write('<div id="comments_thread"><\/div>');
890 var s = d.createElement('script');
891 s.type = 'text/javascript';
893 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier;
894 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
897 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>');
899 })(window, document);
900 //--><!]]></script></div><div id="footer">
901 <p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
902 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/quickreference.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><
projects / apache / blob