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 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5 This file is generated from xml source: DO NOT EDIT
6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8 <title>Caching Guide - Apache HTTP Server</title>
9 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12 <link href="./images/favicon.ico" rel="shortcut icon" /></head>
13 <body id="manual-page"><div id="page-header">
14 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
15 <p class="apache">Apache HTTP Server Version 2.3</p>
16 <img alt="" src="./images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
19 <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.3</a></div><div id="page-content"><div id="preamble"><h1>Caching Guide</h1>
21 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> |
22 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
23 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
26 <p>This document supplements the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>,
27 <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.
28 It describes how to use the Apache HTTP Server's caching features to accelerate web and
29 proxy serving, while avoiding common problems and misconfigurations.</p>
31 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li>
32 <li><img alt="" src="./images/down.gif" /> <a href="#overview">Caching Overview</a></li>
33 <li><img alt="" src="./images/down.gif" /> <a href="#security">Security Considerations</a></li>
34 <li><img alt="" src="./images/down.gif" /> <a href="#filehandle">File-Handle Caching</a></li>
35 <li><img alt="" src="./images/down.gif" /> <a href="#inmemory">In-Memory Caching</a></li>
36 <li><img alt="" src="./images/down.gif" /> <a href="#disk">Disk-based Caching</a></li>
38 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
40 <h2><a name="introduction" id="introduction">Introduction</a></h2>
43 <p>As of Apache HTTP server version 2.2 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
44 and <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> are no longer marked
45 experimental and are considered suitable for production use. These
46 caching architectures provide a powerful means to accelerate HTTP
47 handling, both as an origin webserver and as a proxy.</p>
49 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> and its provider modules
50 <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code>
51 provide intelligent, HTTP-aware caching. The content itself is stored
52 in the cache, and mod_cache aims to honor all of the various HTTP
53 headers and options that control the cachability of content. It can
54 handle both local and proxied content. <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
55 is aimed at both simple and complex caching configurations, where
56 you are dealing with proxied content, dynamic local content or
57 have a need to speed up access to local files which change with
60 <p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> on the other hand presents a more
61 basic, but sometimes useful, form of caching. Rather than maintain
62 the complexity of actively ensuring the cachability of URLs,
63 <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> offers file-handle and memory-mapping
64 tricks to keep a cache of files as they were when httpd was last
65 started. As such, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> is aimed at improving
66 the access time to local static files which do not change very
69 <p>As <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> presents a relatively simple
70 caching implementation, apart from the specific sections on <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> and <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code>, the explanations
71 in this guide cover the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching
74 <p>To get the most from this document, you should be familiar with
75 the basics of HTTP, and have read the Users' Guides to
76 <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
77 <a href="content-negotiation.html">Content negotiation</a>.</p>
79 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
81 <h2><a name="overview" id="overview">Caching Overview</a></h2>
85 <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_file_cache.html">mod_file_cache</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/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><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>
87 <p>There are two main stages in <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> that can
88 occur in the lifetime of a request. First, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
89 is a URL mapping module, which means that if a URL has been cached,
90 and the cached version of that URL has not expired, the request will
91 be served directly by <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>.</p>
93 <p>This means that any other stages that might ordinarily happen
94 in the process of serving a request -- for example being handled
95 by <code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code>, or <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code> --
96 won't happen. But then this is the point of caching content in
99 <p>If the URL is not found within the cache, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
100 will add a <a href="filter.html">filter</a> to the request handling. After
101 httpd has located the content by the usual means, the filter will be run
102 as the content is served. If the content is determined to be cacheable,
103 the content will be saved to the cache for future serving.</p>
105 <p>If the URL is found within the cache, but also found to have expired,
106 the filter is added anyway, but <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will create
107 a conditional request to the backend, to determine if the cached version
108 is still current. If the cached version is still current, its
109 meta-information will be updated and the request will be served from the
110 cache. If the cached version is no longer current, the cached version
111 will be deleted and the filter will save the updated content to the cache
114 <h3>Improving Cache Hits</h3>
117 <p>When caching locally generated content, ensuring that
118 <code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code> is set to
119 <code>On</code> can dramatically improve the ratio of cache hits. This
120 is because the hostname of the virtual-host serving the content forms
121 a part of the cache key. With the setting set to <code>On</code>
122 virtual-hosts with multiple server names or aliases will not produce
123 differently cached entities, and instead content will be cached as
124 per the canonical hostname.</p>
126 <p>Because caching is performed within the URL to filename translation
127 phase, cached documents will only be served in response to URL requests.
128 Ordinarily this is of little consequence, but there is one circumstance
129 in which it matters: If you are using <a href="howto/ssi.html">Server
130 Side Includes</a>;</p>
132 <div class="example"><p><code>
133 <!-- The following include can be cached --><br />
134 <!--#include virtual="/footer.html" --> <br />
136 <!-- The following include can not be cached --><br />
137 <!--#include file="/path/to/footer.html" -->
140 <p>If you are using Server Side Includes, and want the benefit of speedy
141 serves from the cache, you should use <code>virtual</code> include
145 <h3>Expiry Periods</h3>
148 <p>The default expiry period for cached entities is one hour, however
149 this can be easily over-ridden by using the <code class="directive"><a href="./mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive. This
150 default is only used when the original source of the content does not
151 specify an expire time or time of last modification.</p>
153 <p>If a response does not include an <code>Expires</code> header but does
154 include a <code>Last-Modified</code> header, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
155 can infer an expiry period based on the use of the <code class="directive"><a href="./mod/mod_cache.html#cachelastmodifiedfactor">CacheLastModifiedFactor</a></code> directive.</p>
157 <p>For local content, <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code> may be used to
158 fine-tune the expiry period.</p>
160 <p>The maximum expiry period may also be controlled by using the
161 <code class="directive"><a href="./mod/mod_cache.html#cachemaxexpire">CacheMaxExpire</a></code>.</p>
165 <h3>A Brief Guide to Conditional Requests</h3>
168 <p>When content expires from the cache and is re-requested from the
169 backend or content provider, rather than pass on the original request,
170 httpd will use a conditional request instead.</p>
172 <p>HTTP offers a number of headers which allow a client, or cache
173 to discern between different versions of the same content. For
174 example if a resource was served with an "Etag:" header, it is
175 possible to make a conditional request with an "If-None-Match:"
176 header. If a resource was served with a "Last-Modified:" header
177 it is possible to make a conditional request with an
178 "If-Modified-Since:" header, and so on.</p>
180 <p>When such a conditional request is made, the response differs
181 depending on whether the content matches the conditions. If a request is
182 made with an "If-Modified-Since:" header, and the content has not been
183 modified since the time indicated in the request then a terse "304 Not
184 Modified" response is issued.</p>
186 <p>If the content has changed, then it is served as if the request were
187 not conditional to begin with.</p>
189 <p>The benefits of conditional requests in relation to caching are
190 twofold. Firstly, when making such a request to the backend, if the
191 content from the backend matches the content in the store, this can be
192 determined easily and without the overhead of transferring the entire
195 <p>Secondly, conditional requests are usually less strenuous on the
196 backend. For static files, typically all that is involved is a call
197 to <code>stat()</code> or similar system call, to see if the file has
198 changed in size or modification time. As such, even if httpd is
199 caching local content, even expired content may still be served faster
200 from the cache if it has not changed. As long as reading from the cache
201 store is faster than reading from the backend (e.g. <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> with memory disk
202 compared to reading from disk).</p>
205 <h3>What Can be Cached?</h3>
208 <p>As mentioned already, the two styles of caching in httpd work
209 differently, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> caching maintains file
210 contents as they were when httpd was started. When a request is
211 made for a file that is cached by this module, it is intercepted
212 and the cached file is served.</p>
214 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching on the other hand is more
215 complex. When serving a request, if it has not been cached
216 previously, the caching module will determine if the content
217 is cacheable. The conditions for determining cachability of
221 <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>
223 <li>The response must have a HTTP status code of 200, 203, 300, 301 or
226 <li>The request must be a HTTP GET request.</li>
228 <li>If the request contains an "Authorization:" header, the response
229 will not be cached.</li>
231 <li>If the response contains an "Authorization:" header, it must
232 also contain an "s-maxage", "must-revalidate" or "public" option
233 in the "Cache-Control:" header.</li>
235 <li>If the URL included a query string (e.g. from a HTML form GET
236 method) it will not be cached unless the response specifies an
237 explicit expiration by including an "Expires:" header or the max-age
238 or s-maxage directive of the "Cache-Control:" header, as per RFC2616
239 sections 13.9 and 13.2.1.</li>
241 <li>If the response has a status of 200 (OK), the response must
242 also include at least one of the "Etag", "Last-Modified" or
243 the "Expires" headers, or the max-age or s-maxage directive of
244 the "Cache-Control:" header, unless the
245 <code class="directive"><a href="./mod/mod_cache.html#cacheignorenolastmod">CacheIgnoreNoLastMod</a></code>
246 directive has been used to require otherwise.</li>
248 <li>If the response includes the "private" option in a "Cache-Control:"
249 header, it will not be stored unless the
250 <code class="directive"><a href="./mod/mod_cache.html#cachestoreprivate">CacheStorePrivate</a></code> has been
251 used to require otherwise.</li>
253 <li>Likewise, if the response includes the "no-store" option in a
254 "Cache-Control:" header, it will not be stored unless the
255 <code class="directive"><a href="./mod/mod_cache.html#cachestorenostore">CacheStoreNoStore</a></code> has been
258 <li>A response will not be stored if it includes a "Vary:" header
259 containing the match-all "*".</li>
263 <h3>What Should Not be Cached?</h3>
266 <p>In short, any content which is highly time-sensitive, or which varies
267 depending on the particulars of the request that are not covered by
268 HTTP negotiation, should not be cached.</p>
270 <p>If you have dynamic content which changes depending on the IP address
271 of the requester, or changes every 5 minutes, it should almost certainly
274 <p>If on the other hand, the content served differs depending on the
275 values of various HTTP headers, it might be possible
276 to cache it intelligently through the use of a "Vary" header.</p>
279 <h3>Variable/Negotiated Content</h3>
282 <p>If a response with a "Vary" header is received by
283 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> when requesting content by the backend it
284 will attempt to handle it intelligently. If possible,
285 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will detect the headers attributed in the
286 "Vary" response in future requests and serve the correct cached
289 <p>If for example, a response is received with a vary header such as;</p>
291 <div class="example"><p><code>
292 Vary: negotiate,accept-language,accept-charset
295 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will only serve the cached content to
296 requesters with accept-language and accept-charset headers
297 matching those of the original request.</p>
299 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
300 <div class="section">
301 <h2><a name="security" id="security">Security Considerations</a></h2>
304 <h3>Authorization and Access Control</h3>
307 <p>Using <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> is very much like having a built
308 in reverse-proxy. Requests will be served by the caching module unless
309 it determines that the backend should be queried. When caching local
310 resources, this drastically changes the security model of httpd.</p>
312 <p>As traversing a filesystem hierarchy to examine potential
313 <code>.htaccess</code> files would be a very expensive operation,
314 partially defeating the point of caching (to speed up requests),
315 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> makes no decision about whether a cached
316 entity is authorised for serving. In other words; if
317 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> has cached some content, it will be served
318 from the cache as long as that content has not expired.</p>
320 <p>If, for example, your configuration permits access to a resource by IP
321 address you should ensure that this content is not cached. You can do this
322 by using the <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code>
323 directive, or <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code>. Left unchecked,
324 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> - very much like a reverse proxy - would cache
325 the content when served and then serve it to any client, on any IP
329 <h3>Local exploits</h3>
332 <p>As requests to end-users can be served from the cache, the cache
333 itself can become a target for those wishing to deface or interfere with
334 content. It is important to bear in mind that the cache must at all
335 times be writable by the user which httpd is running as. This is in
336 stark contrast to the usually recommended situation of maintaining
337 all content unwritable by the Apache user.</p>
339 <p>If the Apache user is compromised, for example through a flaw in
340 a CGI process, it is possible that the cache may be targeted. When
341 using <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code>, it is relatively easy to
342 insert or modify a cached entity.</p>
344 <p>This presents a somewhat elevated risk in comparison to the other
345 types of attack it is possible to make as the Apache user. If you are
346 using <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> you should bear this in mind -
347 ensure you upgrade httpd when security upgrades are announced and
348 run CGI processes as a non-Apache user using <a href="suexec.html">suEXEC</a> if possible.</p>
352 <h3>Cache Poisoning</h3>
355 <p>When running httpd as a caching proxy server, there is also the
356 potential for so-called cache poisoning. Cache Poisoning is a broad
357 term for attacks in which an attacker causes the proxy server to
358 retrieve incorrect (and usually undesirable) content from the backend.
361 <p>For example if the DNS servers used by your system running
363 are vulnerable to DNS cache poisoning, an attacker may be able to control
364 where httpd connects to when requesting content from the origin server.
365 Another example is so-called HTTP request-smuggling attacks.</p>
367 <p>This document is not the correct place for an in-depth discussion
368 of HTTP request smuggling (instead, try your favourite search engine)
369 however it is important to be aware that it is possible to make
370 a series of requests, and to exploit a vulnerability on an origin
371 webserver such that the attacker can entirely control the content
372 retrieved by the proxy.</p>
374 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
375 <div class="section">
376 <h2><a name="filehandle" id="filehandle">File-Handle Caching</a></h2>
379 <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></ul></td></tr></table>
381 <p>The act of opening a file can itself be a source of delay, particularly
382 on network filesystems. By maintaining a cache of open file descriptors
383 for commonly served files, httpd can avoid this delay. Currently
385 provides one implementation of File-Handle Caching.</p>
390 <p>The most basic form of caching present in httpd is the file-handle
391 caching provided by <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code>. Rather than caching
392 file-contents, this cache maintains a table of open file descriptors. Files
393 to be cached in this manner are specified in the configuration file using
394 the <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
398 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive
399 instructs httpd to open the file when it is started and to re-use
400 this file-handle for all subsequent access to this file.</p>
402 <div class="example"><p><code>
403 CacheFile /usr/local/apache2/htdocs/index.html
406 <p>If you intend to cache a large number of files in this manner, you
407 must ensure that your operating system's limit for the number of open
408 files is set appropriately.</p>
410 <p>Although using <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
411 does not cause the file-contents to be cached per-se, it does mean
412 that if the file changes while httpd is running these changes will
413 not be picked up. The file will be consistently served as it was
414 when httpd was started.</p>
416 <p>If the file is removed while httpd is running, it will continue
417 to maintain an open file descriptor and serve the file as it was when
418 httpd was started. This usually also means that although the file
419 will have been deleted, and not show up on the filesystem, extra free
420 space will not be recovered until httpd is stopped and the file
421 descriptor closed.</p>
424 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
425 <div class="section">
426 <h2><a name="inmemory" id="inmemory">In-Memory Caching</a></h2>
429 <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_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/mod_file_cache.html#mmapfile">MMapFile</a></code></li></ul></td></tr></table>
431 <p>Serving directly from system memory is universally the fastest method
432 of serving content. Reading files from a disk controller or, even worse,
433 from a remote network is orders of magnitude slower. Disk controllers
434 usually involve physical processes, and network access is limited by
435 your available bandwidth. Memory access on the other hand can take mere
438 <p>System memory isn't cheap though, byte for byte it's by far the most
439 expensive type of storage and it's important to ensure that it is used
440 efficiently. By caching files in memory you decrease the amount of
441 memory available on the system. As we'll see, in the case of operating
442 system caching, this is not so much of an issue, but when using
443 httpd's own in-memory caching it is important to make sure that you
444 do not allocate too much memory to a cache. Otherwise the system
445 will be forced to swap out memory, which will likely degrade
448 <h3>Operating System Caching</h3>
451 <p>Almost all modern operating systems cache file-data in memory managed
452 directly by the kernel. This is a powerful feature, and for the most
453 part operating systems get it right. For example, on Linux, let's look at
454 the difference in the time it takes to read a file for the first time
455 and the second time;</p>
457 <div class="example"><pre>
458 colm@coroebus:~$ time cat testfile > /dev/null
462 colm@coroebus:~$ time cat testfile > /dev/null
465 sys 0m0.000s</pre></div>
467 <p>Even for this small file, there is a huge difference in the amount
468 of time it takes to read the file. This is because the kernel has cached
469 the file contents in memory.</p>
471 <p>By ensuring there is "spare" memory on your system, you can ensure
472 that more and more file-contents will be stored in this cache. This
473 can be a very efficient means of in-memory caching, and involves no
474 extra configuration of httpd at all.</p>
476 <p>Additionally, because the operating system knows when files are
477 deleted or modified, it can automatically remove file contents from the
478 cache when necessary. This is a big advantage over httpd's in-memory
479 caching which has no way of knowing when a file has changed.</p>
482 <p>Despite the performance and advantages of automatic operating system
483 caching there are some circumstances in which in-memory caching may be
484 better performed by httpd.</p>
486 <h3>MMapFile Caching</h3>
489 <p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> provides the
490 <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code> directive, which
491 allows you to have httpd map a static file's contents into memory at
492 start time (using the mmap system call). httpd will use the in-memory
493 contents for all subsequent accesses to this file.</p>
495 <div class="example"><p><code>
496 MMapFile /usr/local/apache2/htdocs/index.html
500 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive, any
501 changes in these files will not be picked up by httpd after it has
504 <p> The <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code>
505 directive does not keep track of how much memory it allocates, so
506 you must ensure not to over-use the directive. Each httpd child
507 process will replicate this memory, so it is critically important
508 to ensure that the files mapped are not so large as to cause the
509 system to swap memory.</p>
511 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
512 <div class="section">
513 <h2><a name="disk" id="disk">Disk-based Caching</a></h2>
516 <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_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></ul></td></tr></table>
518 <p><code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> provides a disk-based caching mechanism
519 for <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>. This cache is intelligent and content will
520 be served from the cache only as long as it is considered valid.</p>
522 <p>Typically the module will be configured as so;</p>
524 <div class="example"><p><code>
525 CacheRoot /var/cache/apache/<br />
526 CacheEnable disk /<br />
527 CacheDirLevels 2<br />
531 <p>Importantly, as the cached files are locally stored, operating system
532 in-memory caching will typically be applied to their access also. So
533 although the files are stored on disk, if they are frequently accessed
534 it is likely the operating system will ensure that they are actually
535 served from memory.</p>
537 <h3>Understanding the Cache-Store</h3>
540 <p>To store items in the cache, <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> creates
541 a 22 character hash of the URL being requested. This hash incorporates
542 the hostname, protocol, port, path and any CGI arguments to the URL,
543 to ensure that multiple URLs do not collide.</p>
545 <p>Each character may be any one of 64-different characters, which mean
546 that overall there are 64^22 possible hashes. For example, a URL might
547 be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
548 as a prefix for the naming of the files specific to that URL within
549 the cache, however first it is split up into directories as per
550 the <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code> and
551 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
554 <p><code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code>
555 specifies how many levels of subdirectory there should be, and
556 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
557 specifies how many characters should be in each directory. With
558 the example settings given above, the hash would be turned into
560 <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
562 <p>The overall aim of this technique is to reduce the number of
563 subdirectories or files that may be in a particular directory,
564 as most file-systems slow down as this number increases. With
566 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
567 there can at most be 64 subdirectories at any particular level.
568 With a setting of 2 there can be 64 * 64 subdirectories, and so on.
569 Unless you have a good reason not to, using a setting of "1"
570 for <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code>
574 <code class="directive"><a href="./mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code>
575 depends on how many files you anticipate to store in the cache.
576 With the setting of "2" used in the above example, a grand
577 total of 4096 subdirectories can ultimately be created. With
578 1 million files cached, this works out at roughly 245 cached
579 URLs per directory.</p>
581 <p>Each URL uses at least two files in the cache-store. Typically
582 there is a ".header" file, which includes meta-information about
583 the URL, such as when it is due to expire and a ".data" file
584 which is a verbatim copy of the content to be served.</p>
586 <p>In the case of a content negotiated via the "Vary" header, a
587 ".vary" directory will be created for the URL in question. This
588 directory will have multiple ".data" files corresponding to the
589 differently negotiated content.</p>
592 <h3>Maintaining the Disk Cache</h3>
595 <p>Although <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> will remove cached content
596 as it is expired, it does not maintain any information on the total
597 size of the cache or how little free space may be left.</p>
599 <p>Instead, provided with httpd is the <a href="programs/htcacheclean.html">htcacheclean</a> tool which, as the name
600 suggests, allows you to clean the cache periodically. Determining
601 how frequently to run <a href="programs/htcacheclean.html">htcacheclean</a> and what target size to
602 use for the cache is somewhat complex and trial and error may be needed to
603 select optimal values.</p>
605 <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
606 operation. It can be run as persistent daemon, or periodically from
607 cron. <a href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
608 or more to process very large (tens of gigabytes) caches and if you are
609 running it from cron it is recommended that you determine how long a typical
610 run takes, to avoid running more than one instance at a time.</p>
613 <img src="images/caching_fig1.gif" alt="" width="600" height="406" /><br />
614 <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
615 cache growth / clean sequence.</p>
617 <p>Because <code class="module"><a href="./mod/mod_cache_disk.html">mod_cache_disk</a></code> does not itself pay attention
618 to how much space is used you should ensure that
619 <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
620 leave enough "grow room" following a clean.</p>
624 <div class="bottomlang">
625 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> |
626 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> |
627 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
628 </div><div id="footer">
629 <p class="apache">Copyright 2011 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>
630 <p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
projects / apache / blob