1 <?xml version="1.0" encoding="UTF-8" ?>
2 <!DOCTYPE manualpage SYSTEM "style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="caching.xml.meta">
25 <title>Caching Guide</title>
28 <p>This document supplements the <module>mod_cache</module>,
29 <module>mod_cache_disk</module>, <module>mod_file_cache</module> and <a
30 href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
31 It describes how to use the Apache HTTP Server's caching features to accelerate web and
32 proxy serving, while avoiding common problems and misconfigurations.</p>
35 <section id="introduction">
36 <title>Introduction</title>
38 <p>The Apache HTTP server offers a range of caching features that
39 are designed to improve the performance of the server in various
43 <dt>Three-state RFC2616 HTTP caching</dt>
45 <module>mod_cache</module>
46 and its provider modules
47 <module>mod_cache_disk</module>
48 provide intelligent, HTTP-aware caching. The content itself is stored
49 in the cache, and mod_cache aims to honor all of the various HTTP
50 headers and options that control the cacheability of content
52 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">Section
54 <module>mod_cache</module>
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 on a potentially
61 <dt>Two-state key/value shared object caching</dt>
63 The <a href="socache.html">shared object cache API</a> (socache)
64 and its provider modules provide a
65 server wide key/value based shared object cache. These modules
66 are designed to cache low level data such as SSL sessions and
67 authentication credentials. Backends allow the data to be stored
68 server wide in shared memory, or datacenter wide in a cache such
69 as memcache or distcache.
72 <dt>Specialized file caching</dt>
74 <module>mod_file_cache</module>
75 offers the ability to pre-load
76 files into memory on server startup, and can improve access
77 times and save file handles on files that are accessed often,
78 as there is no need to go to disk on each request.
82 <p>To get the most from this document, you should be familiar with
83 the basics of HTTP, and have read the Users' Guides to
84 <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
85 <a href="content-negotiation.html">Content negotiation</a>.</p>
89 <section id="http-caching">
91 <title>Three-state RFC2616 HTTP caching</title>
95 <module>mod_cache</module>
96 <module>mod_cache_disk</module>
99 <directive module="mod_cache">CacheEnable</directive>
100 <directive module="mod_cache">CacheDisable</directive>
101 <directive module="core">UseCanonicalName</directive>
102 <directive module="mod_negotiation">CacheNegotiatedDocs</directive>
106 <p>The HTTP protocol contains built in support for an in-line caching
108 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
109 described by section 13 of RFC2616</a>, and the
110 <module>mod_cache</module> module can be used to take advantage of
113 <p>Unlike a simple two state key/value cache where the content
114 disappears completely when no longer fresh, an HTTP cache includes
115 a mechanism to retain stale content, and to ask the origin server
116 whether this stale content has changed and if not, make it fresh
119 <p>An entry in an HTTP cache exists in one of three states:</p>
124 If the content is new enough (younger than its <strong>freshness
125 lifetime</strong>), it is considered <strong>fresh</strong>. An
126 HTTP cache is free to serve fresh content without making any
127 calls to the origin server at all.
131 <p>If the content is too old (older than its <strong>freshness
132 lifetime</strong>), it is considered <strong>stale</strong>. An
133 HTTP cache should contact the origin server and check whether
134 the content is still fresh before serving stale content to a
135 client. The origin server will either respond with replacement
136 content if not still valid, or ideally, the origin server will
137 respond with a code to tell the cache the content is still
138 fresh, without the need to generate or send the content again.
139 The content becomes fresh again and the cycle continues.</p>
141 <p>The HTTP protocol does allow the cache to serve stale data
142 under certain circumstances, such as when an attempt to freshen
143 the data with an origin server has failed with a 5xx error, or
144 when another request is already in the process of freshening
145 the given entry. In these cases a <code>Warning</code> header
146 is added to the response.</p>
148 <dt>Non Existent</dt>
150 If the cache gets full, it reserves the option to delete content
151 from the cache to make space. Content can be deleted at any time,
152 and can be stale or fresh. The <a
153 href="programs/htcacheclean.html">htcacheclean</a> tool can be
154 run on a once off basis, or deployed as a daemon to keep the size
155 of the cache within the given size, or the given number of inodes.
156 The tool attempts to delete stale content before attempting to
157 delete fresh content.
161 <p>Full details of how HTTP caching works can be found in
162 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">
163 Section 13 of RFC2616</a>.</p>
166 <title>Interaction with the Server</title>
168 <p>The <module>mod_cache</module> module hooks into the server in two
169 possible places depending on the value of the
170 <directive module="mod_cache">CacheQuickHandler</directive> directive:
174 <dt>Quick handler phase</dt>
176 <p>This phase happens very early on during the request processing,
177 just after the request has been parsed. If the content is
178 found within the cache, it is served immediately and almost
179 all request processing is bypassed.</p>
181 <p>In this scenario, the cache behaves as if it has been "bolted
182 on" to the front of the server.</p>
184 <p>This mode offers the best performance, as the majority of
185 server processing is bypassed. This mode however also bypasses the
186 authentication and authorization phases of server processing, so
187 this mode should be chosen with care when this is important.</p>
189 <p> Requests with an "Authorization" header (for example, HTTP Basic
190 Authentication) are neither cacheable nor served from the cache
191 when <module>mod_cache</module> is running in this phase.</p>
193 <dt>Normal handler phase</dt>
195 <p>This phase happens late in the request processing, after all
196 the request phases have completed.</p>
198 <p>In this scenario, the cache behaves as if it has been "bolted
199 on" to the back of the server.</p>
201 <p>This mode offers the most flexibility, as the potential exists
202 for caching to occur at a precisely controlled point in the filter
203 chain, and cached content can be filtered or personalized before
204 being sent to the client.</p>
208 <p>If the URL is not found within the cache, <module>mod_cache</module>
209 will add a <a href="filter.html">filter</a> to the filter stack in order
210 to record the response to the cache, and then stand down, allowing normal
211 request processing to continue. If the content is determined to be
212 cacheable, the content will be saved to the cache for future serving,
213 otherwise the content will be ignored.</p>
215 <p>If the content found within the cache is stale, the
216 <module>mod_cache</module> module converts the request into a
217 <strong>conditional request</strong>. If the origin server responds with
218 a normal response, the normal response is cached, replacing the content
219 already cached. If the origin server responds with a 304 Not Modified
220 response, the content is marked as fresh again, and the cached content
221 is served by the filter instead of saving it.</p>
225 <title>Improving Cache Hits</title>
227 <p>When a virtual host is known by one of many different server aliases,
228 ensuring that <directive module="core">UseCanonicalName</directive> is
229 set to <code>On</code> can dramatically improve the ratio of cache hits.
230 This is because the hostname of the virtual-host serving the content is
231 used within the cache key. With the setting set to <code>On</code>
232 virtual-hosts with multiple server names or aliases will not produce
233 differently cached entities, and instead content will be cached as
234 per the canonical hostname.</p>
239 <title>Freshness Lifetime</title>
241 <p>Well formed content that is intended to be cached should declare an
242 explicit freshness lifetime with the <code>Cache-Control</code>
243 header's <code>max-age</code> or <code>s-maxage</code> fields, or
244 by including an <code>Expires</code> header.</p>
246 <p>At the same time, the origin server defined freshness lifetime can
247 be overridden by a client when the client presents their own
248 <code>Cache-Control</code> header within the request. In this case,
249 the lowest freshness lifetime between request and response wins.</p>
251 <p>When this freshness lifetime is missing from the request or the
252 response, a default freshness lifetime is applied. The default
253 freshness lifetime for cached entities is one hour, however
254 this can be easily over-ridden by using the <directive
255 module="mod_cache">CacheDefaultExpire</directive> directive.</p>
257 <p>If a response does not include an <code>Expires</code> header but does
258 include a <code>Last-Modified</code> header, <module>mod_cache</module>
259 can infer a freshness lifetime based on a heuristic, which can be
260 controlled through the use of the <directive
261 module="mod_cache">CacheLastModifiedFactor</directive> directive.</p>
263 <p>For local content, or for remote content that does not define its own
264 <code>Expires</code> header, <module>mod_expires</module> may be used to
265 fine-tune the freshness lifetime by adding <code>max-age</code> and
266 <code>Expires</code>.</p>
268 <p>The maximum freshness lifetime may also be controlled by using the
269 <directive module="mod_cache">CacheMaxExpire</directive>.</p>
274 <title>A Brief Guide to Conditional Requests</title>
276 <p>When content expires from the cache and becomes stale, rather than
277 pass on the original request, httpd will modify the request to make
278 it conditional instead.</p>
280 <p>When an <code>ETag</code> header exists in the original cached
281 response, <module>mod_cache</module> will add an
282 <code>If-None-Match</code> header to the request to the origin server.
283 When a <code>Last-Modified</code> header exists in the original
284 cached response, <module>mod_cache</module> will add an
285 <code>If-Modified-Since</code> header to the request to the origin
286 server. Performing either of these actions makes the request
287 <strong>conditional</strong>.</p>
289 <p>When a conditional request is received by an origin server, the
290 origin server should check whether the ETag or the Last-Modified
291 parameter has changed, as appropriate for the request. If not, the
292 origin should respond with a terse "304 Not Modified" response. This
293 signals to the cache that the stale content is still fresh should be
294 used for subsequent requests until the content's new freshness lifetime
295 is reached again.</p>
297 <p>If the content has changed, then the content is served as if the
298 request were not conditional to begin with.</p>
300 <p>Conditional requests offer two benefits. Firstly, when making such
301 a request to the origin server, if the content from the origin
302 matches the content in the cache, this can be determined easily and
303 without the overhead of transferring the entire resource.</p>
305 <p>Secondly, a well designed origin server will be designed in such
306 a way that conditional requests will be significantly cheaper to
307 produce than a full response. For static files, typically all that is
308 involved is a call to <code>stat()</code> or similar system call, to
309 see if the file has changed in size or modification time. As such, even
310 local content may still be served faster from the cache if it has not
313 <p>Origin servers should make every effort to support conditional
314 requests as is practical, however if conditional requests are not
315 supported, the origin will respond as if the request was not
316 conditional, and the cache will respond as if the content had changed
317 and save the new content to the cache. In this case, the cache will
318 behave like a simple two state cache, where content is effectively
319 either fresh or deleted.</p>
323 <title>What Can be Cached?</title>
325 <p>The full definition of which responses can be cached by an HTTP
327 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.4">
328 RFC2616 Section 13.4 Response Cacheability</a>, and can be summed up as
332 <li>Caching must be enabled for this URL. See the <directive
333 module="mod_cache">CacheEnable</directive> and <directive
334 module="mod_cache">CacheDisable</directive> directives.</li>
336 <li>If the response has an HTTP status code other than 200, 203, 300,
337 301 or 410 it must also specify an "Expires" or "Cache-Control" header.
340 <li>The request must be a HTTP GET request.</li>
342 <li>If the response contains an "Authorization:" header, it must
343 also contain an "s-maxage", "must-revalidate" or "public" option
344 in the "Cache-Control:" header, or it won't be cached.</li>
346 <li>If the URL included a query string (e.g. from a HTML form GET
347 method) it will not be cached unless the response specifies an
348 explicit expiration by including an "Expires:" header or the max-age
349 or s-maxage directive of the "Cache-Control:" header, as per RFC2616
350 sections 13.9 and 13.2.1.</li>
352 <li>If the response has a status of 200 (OK), the response must
353 also include at least one of the "Etag", "Last-Modified" or
354 the "Expires" headers, or the max-age or s-maxage directive of
355 the "Cache-Control:" header, unless the
356 <directive module="mod_cache">CacheIgnoreNoLastMod</directive>
357 directive has been used to require otherwise.</li>
359 <li>If the response includes the "private" option in a "Cache-Control:"
360 header, it will not be stored unless the
361 <directive module="mod_cache">CacheStorePrivate</directive> has been
362 used to require otherwise.</li>
364 <li>Likewise, if the response includes the "no-store" option in a
365 "Cache-Control:" header, it will not be stored unless the
366 <directive module="mod_cache">CacheStoreNoStore</directive> has been
369 <li>A response will not be stored if it includes a "Vary:" header
370 containing the match-all "*".</li>
375 <title>What Should Not be Cached?</title>
377 <p>It should be up to the client creating the request, or the origin
378 server constructing the response to decide whether or not the content
379 should be cacheable or not by correctly setting the
380 <code>Cache-Control</code> header, and <module>mod_cache</module> should
381 be left alone to honor the wishes of the client or server as appropriate.
384 <p>Content that is time sensitive, or which varies depending on the
385 particulars of the request that are not covered by HTTP negotiation,
386 should not be cached. This content should declare itself uncacheable
387 using the <code>Cache-Control</code> header.</p>
389 <p>If content changes often, expressed by a freshness lifetime of minutes
390 or seconds, the content can still be cached, however it is highly
391 desirable that the origin server supports
392 <strong>conditional requests</strong> correctly to ensure that
393 full responses do not have to be generated on a regular basis.</p>
395 <p>Content that varies based on client provided request headers can be
396 cached through intelligent use of the <code>Vary</code> response
402 <title>Variable/Negotiated Content</title>
404 <p>When the origin server is designed to respond with different content
405 based on the value of headers in the request, for example to serve
406 multiple languages at the same URL, HTTP's caching mechanism makes it
407 possible to cache multiple variants of the same page at the same URL.</p>
409 <p>This is done by the origin server adding a <code>Vary</code> header
410 to indicate which headers must be taken into account by a cache when
411 determining whether two variants are different from one another.</p>
413 <p>If for example, a response is received with a vary header such as;</p>
416 Vary: negotiate,accept-language,accept-charset
419 <p><module>mod_cache</module> will only serve the cached content to
420 requesters with accept-language and accept-charset headers
421 matching those of the original request.</p>
423 <p>Multiple variants of the content can be cached side by side,
424 <module>mod_cache</module> uses the <code>Vary</code> header and the
425 corresponding values of the request headers listed by <code>Vary</code>
426 to decide on which of many variants to return to the client.</p>
431 <section id="examples">
433 <title>Cache Setup Examples</title>
437 <module>mod_cache</module>
438 <module>mod_cache_disk</module>
439 <module>mod_cache_socache</module>
440 <module>mod_socache_memcache</module>
443 <directive module="mod_cache">CacheEnable</directive>
444 <directive module="mod_cache_disk">CacheRoot</directive>
445 <directive module="mod_cache_disk">CacheDirLevels</directive>
446 <directive module="mod_cache_disk">CacheDirLength</directive>
447 <directive module="mod_cache_socache">CacheSocache</directive>
452 <title>Caching to Disk</title>
454 <p>The <module>mod_cache</module> module relies on specific backend store
455 implementations in order to manage the cache, and for caching to disk
456 <module>mod_cache_disk</module> is provided to support this.</p>
458 <p>Typically the module will be configured as so;</p>
460 <highlight language="config">
461 CacheRoot "/var/cache/apache/"
467 <p>Importantly, as the cached files are locally stored, operating system
468 in-memory caching will typically be applied to their access also. So
469 although the files are stored on disk, if they are frequently accessed
470 it is likely the operating system will ensure that they are actually
471 served from memory.</p>
476 <title>Understanding the Cache-Store</title>
478 <p>To store items in the cache, <module>mod_cache_disk</module> creates
479 a 22 character hash of the URL being requested. This hash incorporates
480 the hostname, protocol, port, path and any CGI arguments to the URL,
481 as well as elements defined by the Vary header to ensure that multiple
482 URLs do not collide with one another.</p>
484 <p>Each character may be any one of 64-different characters, which mean
485 that overall there are 64^22 possible hashes. For example, a URL might
486 be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
487 as a prefix for the naming of the files specific to that URL within
488 the cache, however first it is split up into directories as per
489 the <directive module="mod_cache_disk">CacheDirLevels</directive> and
490 <directive module="mod_cache_disk">CacheDirLength</directive>
493 <p><directive module="mod_cache_disk">CacheDirLevels</directive>
494 specifies how many levels of subdirectory there should be, and
495 <directive module="mod_cache_disk">CacheDirLength</directive>
496 specifies how many characters should be in each directory. With
497 the example settings given above, the hash would be turned into
499 <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
501 <p>The overall aim of this technique is to reduce the number of
502 subdirectories or files that may be in a particular directory,
503 as most file-systems slow down as this number increases. With
505 <directive module="mod_cache_disk">CacheDirLength</directive>
506 there can at most be 64 subdirectories at any particular level.
507 With a setting of 2 there can be 64 * 64 subdirectories, and so on.
508 Unless you have a good reason not to, using a setting of "1"
509 for <directive module="mod_cache_disk">CacheDirLength</directive>
513 <directive module="mod_cache_disk">CacheDirLevels</directive>
514 depends on how many files you anticipate to store in the cache.
515 With the setting of "2" used in the above example, a grand
516 total of 4096 subdirectories can ultimately be created. With
517 1 million files cached, this works out at roughly 245 cached
518 URLs per directory.</p>
520 <p>Each URL uses at least two files in the cache-store. Typically
521 there is a ".header" file, which includes meta-information about
522 the URL, such as when it is due to expire and a ".data" file
523 which is a verbatim copy of the content to be served.</p>
525 <p>In the case of a content negotiated via the "Vary" header, a
526 ".vary" directory will be created for the URL in question. This
527 directory will have multiple ".data" files corresponding to the
528 differently negotiated content.</p>
532 <title>Maintaining the Disk Cache</title>
534 <p>The <module>mod_cache_disk</module> module makes no attempt to
535 regulate the amount of disk space used by the cache, although it
536 will gracefully stand down on any disk error and behave as if the
537 cache was never present.</p>
539 <p>Instead, provided with httpd is the <a
540 href="programs/htcacheclean.html">htcacheclean</a> tool which allows you
541 to clean the cache periodically. Determining how frequently to run <a
542 href="programs/htcacheclean.html">htcacheclean</a> and what target size to
543 use for the cache is somewhat complex and trial and error may be needed to
544 select optimal values.</p>
546 <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
547 operation. It can be run as persistent daemon, or periodically from
549 href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
550 or more to process very large (tens of gigabytes) caches and if you are
551 running it from cron it is recommended that you determine how long a typical
552 run takes, to avoid running more than one instance at a time.</p>
554 <p>It is also recommended that an appropriate "nice" level is chosen for
555 htcacheclean so that the tool does not cause excessive disk io while the
556 server is running.</p>
559 <img src="images/caching_fig1.gif" alt="" width="600"
560 height="406" /><br />
561 <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
562 cache growth / clean sequence.</p>
564 <p>Because <module>mod_cache_disk</module> does not itself pay attention
565 to how much space is used you should ensure that
566 <a href="programs/htcacheclean.html">htcacheclean</a> is configured to
567 leave enough "grow room" following a clean.</p>
570 <section id="memcache">
571 <title>Caching to memcached</title>
573 <p>Using the <module>mod_cache_socache</module> module, <module>mod_cache</module>
574 can cache data from a variety of implementations (aka: "providers"). Using the
575 <module>mod_socache_memcache</module> module, for example, one can specify that
576 <a href="http://memcached.org">memcached</a> is to be used as the
577 the backend storage mechanism.</p>
579 <p>Typically the module will be configured as so:</p>
581 <highlight language="config">
582 CacheEnable socache /
583 CacheSocache memcache:memcd.example.com:11211
586 <p>Additional <code>memcached</code> servers can be specified by
587 appending them to the end of the <code>CacheSocache memcache:</code>
588 line separated by commas:</p>
590 <highlight language="config">
591 CacheEnable socache /
592 CacheSocache memcache:mem1.example.com:11211,mem2.example.com:11212
595 <p>This format is also used with the other various <module>mod_cache_socache</module>
596 providers. For example:</p>
598 <highlight language="config">
599 CacheEnable socache /
600 CacheSocache shmcb:/path/to/datafile(512000)
603 <highlight language="config">
604 CacheEnable socache /
605 CacheSocache dbm:/path/to/datafile
612 <section id="socache-caching">
614 <title>General Two-state Key/Value Shared Object Caching</title>
618 <module>mod_authn_socache</module>
619 <module>mod_socache_dbm</module>
620 <module>mod_socache_dc</module>
621 <module>mod_socache_memcache</module>
622 <module>mod_socache_shmcb</module>
623 <module>mod_ssl</module>
626 <directive module="mod_authn_socache">AuthnCacheSOCache</directive>
627 <directive module="mod_ssl">SSLSessionCache</directive>
628 <directive module="mod_ssl">SSLStaplingCache</directive>
632 <p>The Apache HTTP server offers a low level shared object cache for
633 caching information such as SSL sessions, or authentication credentials,
634 within the <a href="socache.html">socache</a> interface.</p>
636 <p>Additional modules are provided for each implementation, offering the
637 following backends:</p>
640 <dt><module>mod_socache_dbm</module></dt>
641 <dd>DBM based shared object cache.</dd>
642 <dt><module>mod_socache_dc</module></dt>
643 <dd>Distcache based shared object cache.</dd>
644 <dt><module>mod_socache_memcache</module></dt>
645 <dd>Memcache based shared object cache.</dd>
646 <dt><module>mod_socache_shmcb</module></dt>
647 <dd>Shared memory based shared object cache.</dd>
650 <section id="mod_authn_socache-caching">
651 <title>Caching Authentication Credentials</title>
655 <module>mod_authn_socache</module>
658 <directive module="mod_authn_socache">AuthnCacheSOCache</directive>
662 <p>The <module>mod_authn_socache</module> module allows the result of
663 authentication to be cached, relieving load on authentication backends.</p>
667 <section id="mod_ssl-caching">
668 <title>Caching SSL Sessions</title>
672 <module>mod_ssl</module>
675 <directive module="mod_ssl">SSLSessionCache</directive>
676 <directive module="mod_ssl">SSLStaplingCache</directive>
680 <p>The <module>mod_ssl</module> module uses the <code>socache</code> interface
681 to provide a session cache and a stapling cache.</p>
687 <section id="file-caching">
689 <title>Specialized File Caching</title>
693 <module>mod_file_cache</module>
696 <directive module="mod_file_cache">CacheFile</directive>
697 <directive module="mod_file_cache">MMapFile</directive>
701 <p>On platforms where a filesystem might be slow, or where file
702 handles are expensive, the option exists to pre-load files into
703 memory on startup.</p>
705 <p>On systems where opening files is slow, the option exists to
706 open the file on startup and cache the file handle. These
707 options can help on systems where access to static files is
710 <section id="filehandle">
711 <title>File-Handle Caching</title>
713 <p>The act of opening a file can itself be a source of delay, particularly
714 on network filesystems. By maintaining a cache of open file descriptors
715 for commonly served files, httpd can avoid this delay. Currently httpd
716 provides one implementation of File-Handle Caching.</p>
719 <title>CacheFile</title>
721 <p>The most basic form of caching present in httpd is the file-handle
722 caching provided by <module>mod_file_cache</module>. Rather than caching
723 file-contents, this cache maintains a table of open file descriptors. Files
724 to be cached in this manner are specified in the configuration file using
725 the <directive module="mod_file_cache">CacheFile</directive>
729 <directive module="mod_file_cache">CacheFile</directive> directive
730 instructs httpd to open the file when it is started and to re-use
731 this file-handle for all subsequent access to this file.</p>
733 <highlight language="config">
734 CacheFile /usr/local/apache2/htdocs/index.html
737 <p>If you intend to cache a large number of files in this manner, you
738 must ensure that your operating system's limit for the number of open
739 files is set appropriately.</p>
741 <p>Although using <directive module="mod_file_cache">CacheFile</directive>
742 does not cause the file-contents to be cached per-se, it does mean
743 that if the file changes while httpd is running these changes will
744 not be picked up. The file will be consistently served as it was
745 when httpd was started.</p>
747 <p>If the file is removed while httpd is running, it will continue
748 to maintain an open file descriptor and serve the file as it was when
749 httpd was started. This usually also means that although the file
750 will have been deleted, and not show up on the filesystem, extra free
751 space will not be recovered until httpd is stopped and the file
752 descriptor closed.</p>
757 <section id="inmemory">
758 <title>In-Memory Caching</title>
760 <p>Serving directly from system memory is universally the fastest method
761 of serving content. Reading files from a disk controller or, even worse,
762 from a remote network is orders of magnitude slower. Disk controllers
763 usually involve physical processes, and network access is limited by
764 your available bandwidth. Memory access on the other hand can take mere
767 <p>System memory isn't cheap though, byte for byte it's by far the most
768 expensive type of storage and it's important to ensure that it is used
769 efficiently. By caching files in memory you decrease the amount of
770 memory available on the system. As we'll see, in the case of operating
771 system caching, this is not so much of an issue, but when using
772 httpd's own in-memory caching it is important to make sure that you
773 do not allocate too much memory to a cache. Otherwise the system
774 will be forced to swap out memory, which will likely degrade
778 <title>Operating System Caching</title>
780 <p>Almost all modern operating systems cache file-data in memory managed
781 directly by the kernel. This is a powerful feature, and for the most
782 part operating systems get it right. For example, on Linux, let's look at
783 the difference in the time it takes to read a file for the first time
784 and the second time;</p>
787 colm@coroebus:~$ time cat testfile > /dev/null
791 colm@coroebus:~$ time cat testfile > /dev/null
797 <p>Even for this small file, there is a huge difference in the amount
798 of time it takes to read the file. This is because the kernel has cached
799 the file contents in memory.</p>
801 <p>By ensuring there is "spare" memory on your system, you can ensure
802 that more and more file-contents will be stored in this cache. This
803 can be a very efficient means of in-memory caching, and involves no
804 extra configuration of httpd at all.</p>
806 <p>Additionally, because the operating system knows when files are
807 deleted or modified, it can automatically remove file contents from the
808 cache when necessary. This is a big advantage over httpd's in-memory
809 caching which has no way of knowing when a file has changed.</p>
812 <p>Despite the performance and advantages of automatic operating system
813 caching there are some circumstances in which in-memory caching may be
814 better performed by httpd.</p>
817 <title>MMapFile Caching</title>
819 <p><module>mod_file_cache</module> provides the
820 <directive module="mod_file_cache">MMapFile</directive> directive, which
821 allows you to have httpd map a static file's contents into memory at
822 start time (using the mmap system call). httpd will use the in-memory
823 contents for all subsequent accesses to this file.</p>
825 <highlight language="config">
826 MMapFile /usr/local/apache2/htdocs/index.html
830 <directive module="mod_file_cache">CacheFile</directive> directive, any
831 changes in these files will not be picked up by httpd after it has
834 <p> The <directive module="mod_file_cache">MMapFile</directive>
835 directive does not keep track of how much memory it allocates, so
836 you must ensure not to over-use the directive. Each httpd child
837 process will replicate this memory, so it is critically important
838 to ensure that the files mapped are not so large as to cause the
839 system to swap memory.</p>
845 <section id="security">
846 <title>Security Considerations</title>
849 <title>Authorization and Access Control</title>
851 <p>Using <module>mod_cache</module> in its default state where
852 <directive module="mod_cache">CacheQuickHandler</directive> is set to
853 <code>On</code> is very much like having a caching reverse-proxy bolted
854 to the front of the server. Requests will be served by the caching module
855 unless it determines that the origin server should be queried just as an
856 external cache would, and this drastically changes the security model of
859 <p>As traversing a filesystem hierarchy to examine potential
860 <code>.htaccess</code> files would be a very expensive operation,
861 partially defeating the point of caching (to speed up requests),
862 <module>mod_cache</module> makes no decision about whether a cached
863 entity is authorised for serving. In other words; if
864 <module>mod_cache</module> has cached some content, it will be served
865 from the cache as long as that content has not expired.</p>
867 <p>If, for example, your configuration permits access to a resource by IP
868 address you should ensure that this content is not cached. You can do this
869 by using the <directive module="mod_cache">CacheDisable</directive>
870 directive, or <module>mod_expires</module>. Left unchecked,
871 <module>mod_cache</module> - very much like a reverse proxy - would cache
872 the content when served and then serve it to any client, on any IP
875 <p>When the <directive module="mod_cache">CacheQuickHandler</directive>
876 directive is set to <code>Off</code>, the full set of request processing
877 phases are executed and the security model remains unchanged.</p>
881 <title>Local exploits</title>
883 <p>As requests to end-users can be served from the cache, the cache
884 itself can become a target for those wishing to deface or interfere with
885 content. It is important to bear in mind that the cache must at all
886 times be writable by the user which httpd is running as. This is in
887 stark contrast to the usually recommended situation of maintaining
888 all content unwritable by the Apache user.</p>
890 <p>If the Apache user is compromised, for example through a flaw in
891 a CGI process, it is possible that the cache may be targeted. When
892 using <module>mod_cache_disk</module>, it is relatively easy to
893 insert or modify a cached entity.</p>
895 <p>This presents a somewhat elevated risk in comparison to the other
896 types of attack it is possible to make as the Apache user. If you are
897 using <module>mod_cache_disk</module> you should bear this in mind -
898 ensure you upgrade httpd when security upgrades are announced and
899 run CGI processes as a non-Apache user using <a
900 href="suexec.html">suEXEC</a> if possible.</p>
905 <title>Cache Poisoning</title>
907 <p>When running httpd as a caching proxy server, there is also the
908 potential for so-called cache poisoning. Cache Poisoning is a broad
909 term for attacks in which an attacker causes the proxy server to
910 retrieve incorrect (and usually undesirable) content from the origin
913 <p>For example if the DNS servers used by your system running httpd
914 are vulnerable to DNS cache poisoning, an attacker may be able to control
915 where httpd connects to when requesting content from the origin server.
916 Another example is so-called HTTP request-smuggling attacks.</p>
918 <p>This document is not the correct place for an in-depth discussion
919 of HTTP request smuggling (instead, try your favourite search engine)
920 however it is important to be aware that it is possible to make
921 a series of requests, and to exploit a vulnerability on an origin
922 webserver such that the attacker can entirely control the content
923 retrieved by the proxy.</p>
927 <title>Denial of Service / Cachebusting</title>
929 <p>The Vary mechanism allows multiple variants of the same URL to be
930 cached side by side. Depending on header values provided by the client,
931 the cache will select the correct variant to return to the client. This
932 mechanism can become a problem when an attempt is made to vary on a
933 header that is known to contain a wide range of possible values under
934 normal use, for example the <code>User-Agent</code> header. Depending
935 on the popularity of the particular web site thousands or millions of
936 duplicate cache entries could be created for the same URL, crowding
937 out other entries in the cache.</p>
939 <p>In other cases, there may be a need to change the URL of a particular
940 resource on every request, usually by adding a "cachebuster" string to
941 the URL. If this content is declared cacheable by a server for a
942 significant freshness lifetime, these entries can crowd out
943 legitimate entries in a cache. While <module>mod_cache</module>
945 <directive module="mod_cache">CacheIgnoreURLSessionIdentifiers</directive>
946 directive, this directive should be used with care to ensure that
947 downstream proxy or browser caches aren't subjected to the same denial
948 of service issue.</p>