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 7 --> 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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> 18<p class="apache">Apache HTTP Server Version 2.4</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<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.4</a></div><div id="page-content"><div id="preamble"><h1>Caching Guide</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/caching.html" title="English"> en </a> | 25<a href="/fr/caching.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 26<a href="/tr/caching.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 27</div> 28 29 <p>This document supplements the <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code>, 30 <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. 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> 33 </div> 34<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#introduction">Introduction</a></li> 35<li><img alt="" src="/images/down.gif" /> <a href="#http-caching">Three-state RFC2616 HTTP caching</a></li> 36<li><img alt="" src="/images/down.gif" /> <a href="#socache-caching">Two-state Key/Value Shared Object Caching</a></li> 37<li><img alt="" src="/images/down.gif" /> <a href="#file-caching">Specialized File Caching</a></li> 38<li><img alt="" src="/images/down.gif" /> <a href="#security">Security Considerations</a></li> 39</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 40<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 41<div class="section"> 42<h2><a name="introduction" id="introduction">Introduction</a></h2> 43 44 45 <p>The Apache HTTP server offers a range of caching features that 46 are designed to improve the performance of the server in various 47 ways.</p> 48 49 <dl> 50 <dt>Three-state RFC2616 HTTP caching</dt> 51 <dd> 52 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> 53 and its provider modules 54 <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> 55 provide intelligent, HTTP-aware caching. The content itself is stored 56 in the cache, and mod_cache aims to honor all of the various HTTP 57 headers and options that control the cacheability of content 58 as described in 59 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html">Section 60 13 of RFC2616</a>. 61 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> 62 is aimed at both simple and complex caching configurations, where 63 you are dealing with proxied content, dynamic local content or 64 have a need to speed up access to local files on a potentially 65 slow disk. 66 </dd> 67 68 <dt>Two-state key/value shared object caching</dt> 69 <dd> 70 The <a href="socache.html">shared object cache API</a> (socache) 71 and its provider modules provide a 72 server wide key/value based shared object cache. These modules 73 are designed to cache low level data such as SSL sessions and 74 authentication credentials. Backends allow the data to be stored 75 server wide in shared memory, or datacenter wide in a cache such 76 as memcache or distcache. 77 </dd> 78 79 <dt>Specialized file caching</dt> 80 <dd> 81 <code class="module"><a href="/mod/mod_file_cache.html">mod_file_cache</a></code> 82 offers the ability to pre-load 83 files into memory on server startup, and can improve access 84 times and save file handles on files that are accessed often, 85 as there is no need to go to disk on each request. 86 </dd> 87 </dl> 88 89 <p>To get the most from this document, you should be familiar with 90 the basics of HTTP, and have read the Users' Guides to 91 <a href="urlmapping.html">Mapping URLs to the Filesystem</a> and 92 <a href="content-negotiation.html">Content negotiation</a>.</p> 93 94 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 95<div class="section"> 96<h2><a name="http-caching" id="http-caching">Three-state RFC2616 HTTP caching</a></h2> 97 98 99 100 <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> 101 102 <p>The HTTP protocol contains built in support for an in-line caching 103 mechanism 104 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html"> 105 described by section 13 of RFC2616</a>, and the 106 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> module can be used to take advantage of 107 this.</p> 108 109 <p>Unlike a simple two state key/value cache where the content 110 disappears completely when no longer fresh, an HTTP cache includes 111 a mechanism to retain stale content, and to ask the origin server 112 whether this stale content has changed and if not, make it fresh 113 again.</p> 114 115 <p>An entry in an HTTP cache exists in one of three states:</p> 116 117 <dl> 118 <dt>Fresh</dt> 119 <dd> 120 If the content is new enough (younger than its <strong>freshness 121 lifetime</strong>), it is considered <strong>fresh</strong>. An 122 HTTP cache is free to serve fresh content without making any 123 calls to the origin server at all. 124 </dd> 125 <dt>Stale</dt> 126 <dd> 127 <p>If the content is too old (older than its <strong>freshness 128 lifetime</strong>), it is considered <strong>stale</strong>. An 129 HTTP cache should contact the origin server and check whether 130 the content is still fresh before serving stale content to a 131 client. The origin server will either respond with replacement 132 content if not still valid, or ideally, the origin server will 133 respond with a code to tell the cache the content is still 134 fresh, without the need to generate or send the content again. 135 The content becomes fresh again and the cycle continues.</p> 136 137 <p>The HTTP protocol does allow the cache to serve stale data 138 under certain circumstances, such as when an attempt to freshen 139 the data with an origin server has failed with a 5xx error, or 140 when another request is already in the process of freshening 141 the given entry. In these cases a <code>Warning</code> header 142 is added to the response.</p> 143 </dd> 144 <dt>Non Existent</dt> 145 <dd> 146 If the cache gets full, it reserves the option to delete content 147 from the cache to make space. Content can be deleted at any time, 148 and can be stale or fresh. The <a href="programs/htcacheclean.html">htcacheclean</a> tool can be 149 run on a once off basis, or deployed as a daemon to keep the size 150 of the cache within the given size, or the given number of inodes. 151 The tool attempts to delete stale content before attempting to 152 delete fresh content. 153 </dd> 154 </dl> 155 156 <p>Full details of how HTTP caching works can be found in 157 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html"> 158 Section 13 of RFC2616</a>.</p> 159 160 <h3>Interaction with the Server</h3> 161 162 163 <p>The <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> module hooks into the server in two 164 possible places depending on the value of the 165 <code class="directive"><a href="/mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code> directive: 166 </p> 167 168 <dl> 169 <dt>Quick handler phase</dt> 170 <dd> 171 <p>This phase happens very early on during the request processing, 172 just after the request has been parsed. If the content is 173 found within the cache, it is served immediately and almost 174 all request processing is bypassed.</p> 175 176 <p>In this scenario, the cache behaves as if it has been "bolted 177 on" to the front of the server.</p> 178 179 <p>This mode offers the best performance, as the majority of 180 server processing is bypassed. This mode however also bypasses the 181 authentication and authorization phases of server processing, so 182 this mode should be chosen with care when this is important.</p> 183 </dd> 184 <dt>Normal handler phase</dt> 185 <dd> 186 <p>This phase happens late in the request processing, after all 187 the request phases have completed.</p> 188 189 <p>In this scenario, the cache behaves as if it has been "bolted 190 on" to the back of the server.</p> 191 192 <p>This mode offers the most flexibility, as the potential exists 193 for caching to occur at a precisely controlled point in the filter 194 chain, and cached content can be filtered or personalized before 195 being sent to the client.</p> 196 </dd> 197 </dl> 198 199 <p>If the URL is not found within the cache, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> 200 will add a <a href="filter.html">filter</a> to the filter stack in order 201 to record the response to the cache, and then stand down, allowing normal 202 request processing to continue. If the content is determined to be 203 cacheable, the content will be saved to the cache for future serving, 204 otherwise the content will be ignored.</p> 205 206 <p>If the content found within the cache is stale, the 207 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> module converts the request into a 208 <strong>conditional request</strong>. If the origin server responds with 209 a normal response, the normal response is cached, replacing the content 210 already cached. If the origin server responds with a 304 Not Modified 211 response, the content is marked as fresh again, and the cached content 212 is served by the filter instead of saving it.</p> 213 214 215 <h3>Improving Cache Hits</h3> 216 217 218 <p>When a virtual host is known by one of many different server aliases, 219 ensuring that <code class="directive"><a href="/mod/core.html#usecanonicalname">UseCanonicalName</a></code> is 220 set to <code>On</code> can dramatically improve the ratio of cache hits. 221 This is because the hostname of the virtual-host serving the content is 222 used within the cache key. With the setting set to <code>On</code> 223 virtual-hosts with multiple server names or aliases will not produce 224 differently cached entities, and instead content will be cached as 225 per the canonical hostname.</p> 226 227 228 229 <h3>Freshness Lifetime</h3> 230 231 232 <p>Well formed content that is intended to be cached should declare an 233 explicit freshness lifetime with the <code>Cache-Control</code> 234 header's <code>max-age</code> or <code>s-maxage</code> fields, or 235 by including an <code>Expires</code> header.</p> 236 237 <p>At the same time, the origin server defined freshness lifetime can 238 be overridden by a client when the client presents their own 239 <code>Cache-Control</code> header within the request. In this case, 240 the lowest freshness lifetime between request and response wins.</p> 241 242 <p>When this freshness lifetime is missing from the request or the 243 response, a default freshness lifetime is applied. The default 244 freshness lifetime for cached entities is one hour, however 245 this can be easily over-ridden by using the <code class="directive"><a href="/mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive.</p> 246 247 <p>If a response does not include an <code>Expires</code> header but does 248 include a <code>Last-Modified</code> header, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> 249 can infer a freshness lifetime based on a heuristic, which can be 250 controlled through the use of the <code class="directive"><a href="/mod/mod_cache.html#cachelastmodifiedfactor">CacheLastModifiedFactor</a></code> directive.</p> 251 252 <p>For local content, or for remote content that does not define its own 253 <code>Expires</code> header, <code class="module"><a href="/mod/mod_expires.html">mod_expires</a></code> may be used to 254 fine-tune the freshness lifetime by adding <code>max-age</code> and 255 <code>Expires</code>.</p> 256 257 <p>The maximum freshness lifetime may also be controlled by using the 258 <code class="directive"><a href="/mod/mod_cache.html#cachemaxexpire">CacheMaxExpire</a></code>.</p> 259 260 261 262 <h3>A Brief Guide to Conditional Requests</h3> 263 264 265 <p>When content expires from the cache and becomes stale, rather than 266 pass on the original request, httpd will modify the request to make 267 it conditional instead.</p> 268 269 <p>When an <code>ETag</code> header exists in the original cached 270 response, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will add an 271 <code>If-None-Match</code> header to the request to the origin server. 272 When a <code>Last-Modified</code> header exists in the original 273 cached response, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will add an 274 <code>If-Modified-Since</code> header to the request to the origin 275 server. Performing either of these actions makes the request 276 <strong>conditional</strong>.</p> 277 278 <p>When a conditional request is received by an origin server, the 279 origin server should check whether the ETag or the Last-Modified 280 parameter has changed, as appropriate for the request. If not, the 281 origin should respond with a terse "304 Not Modified" response. This 282 signals to the cache that the stale content is still fresh should be 283 used for subsequent requests until the content's new freshness lifetime 284 is reached again.</p> 285 286 <p>If the content has changed, then the content is served as if the 287 request were not conditional to begin with.</p> 288 289 <p>Conditional requests offer two benefits. Firstly, when making such 290 a request to the origin server, if the content from the origin 291 matches the content in the cache, this can be determined easily and 292 without the overhead of transferring the entire resource.</p> 293 294 <p>Secondly, a well designed origin server will be designed in such 295 a way that conditional requests will be significantly cheaper to 296 produce than a full response. For static files, typically all that is 297 involved is a call to <code>stat()</code> or similar system call, to 298 see if the file has changed in size or modification time. As such, even 299 local content may still be served faster from the cache if it has not 300 changed.</p> 301 302 <p>Origin servers should make every effort to support conditional 303 requests as is practical, however if conditional requests are not 304 supported, the origin will respond as if the request was not 305 conditional, and the cache will respond as if the content had changed 306 and save the new content to the cache. In this case, the cache will 307 behave like a simple two state cache, where content is effectively 308 either fresh or deleted.</p> 309 310 311 <h3>What Can be Cached?</h3> 312 313 314 <p>The full definition of which responses can be cached by an HTTP 315 cache is defined in 316 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec13.html#sec13.4"> 317 RFC2616 Section 13.4 Response Cacheability</a>, and can be summed up as 318 follows:</p> 319 320 <ol> 321 <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> 322 323 <li>The response must have a HTTP status code of 200, 203, 300, 301 or 324 410.</li> 325 326 <li>The request must be a HTTP GET request.</li> 327 328 <li>If the response contains an "Authorization:" header, it must 329 also contain an "s-maxage", "must-revalidate" or "public" option 330 in the "Cache-Control:" header, or it won't be cached.</li> 331 332 <li>If the URL included a query string (e.g. from a HTML form GET 333 method) it will not be cached unless the response specifies an 334 explicit expiration by including an "Expires:" header or the max-age 335 or s-maxage directive of the "Cache-Control:" header, as per RFC2616 336 sections 13.9 and 13.2.1.</li> 337 338 <li>If the response has a status of 200 (OK), the response must 339 also include at least one of the "Etag", "Last-Modified" or 340 the "Expires" headers, or the max-age or s-maxage directive of 341 the "Cache-Control:" header, unless the 342 <code class="directive"><a href="/mod/mod_cache.html#cacheignorenolastmod">CacheIgnoreNoLastMod</a></code> 343 directive has been used to require otherwise.</li> 344 345 <li>If the response includes the "private" option in a "Cache-Control:" 346 header, it will not be stored unless the 347 <code class="directive"><a href="/mod/mod_cache.html#cachestoreprivate">CacheStorePrivate</a></code> has been 348 used to require otherwise.</li> 349 350 <li>Likewise, if the response includes the "no-store" option in a 351 "Cache-Control:" header, it will not be stored unless the 352 <code class="directive"><a href="/mod/mod_cache.html#cachestorenostore">CacheStoreNoStore</a></code> has been 353 used.</li> 354 355 <li>A response will not be stored if it includes a "Vary:" header 356 containing the match-all "*".</li> 357 </ol> 358 359 360 <h3>What Should Not be Cached?</h3> 361 362 363 <p>It should be up to the client creating the request, or the origin 364 server constructing the response to decide whether or not the content 365 should be cacheable or not by correctly setting the 366 <code>Cache-Control</code> header, and <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> should 367 be left alone to honor the wishes of the client or server as appropriate. 368 </p> 369 370 <p>Content that is time sensitive, or which varies depending on the 371 particulars of the request that are not covered by HTTP negotiation, 372 should not be cached. This content should declare itself uncacheable 373 using the <code>Cache-Control</code> header.</p> 374 375 <p>If content changes often, expressed by a freshness lifetime of minutes 376 or seconds, the content can still be cached, however it is highly 377 desirable that the origin server supports 378 <strong>conditional requests</strong> correctly to ensure that 379 full responses do not have to be generated on a regular basis.</p> 380 381 <p>Content that varies based on client provided request headers can be 382 cached through intelligent use of the <code>Vary</code> response 383 header.</p> 384 385 386 387 <h3>Variable/Negotiated Content</h3> 388 389 390 <p>When the origin server is designed to respond with different content 391 based on the value of headers in the request, for example to serve 392 multiple languages at the same URL, HTTP's caching mechanism makes it 393 possible to cache multiple variants of the same page at the same URL.</p> 394 395 <p>This is done by the origin server adding a <code>Vary</code> header 396 to indicate which headers must be taken into account by a cache when 397 determining whether two variants are different from one another.</p> 398 399 <p>If for example, a response is received with a vary header such as;</p> 400 401 <div class="example"><p><code> 402Vary: negotiate,accept-language,accept-charset 403 </code></p></div> 404 405 <p><code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will only serve the cached content to 406 requesters with accept-language and accept-charset headers 407 matching those of the original request.</p> 408 409 <p>Multiple variants of the content can be cached side by side, 410 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> uses the <code>Vary</code> header and the 411 corresponding values of the request headers listed by <code>Vary</code> 412 to decide on which of many variants to return to the client.</p> 413 414 415 <h3><a name="disk" id="disk">Caching to Disk</a></h3> 416 417 418 <p>The <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> module relies on specific backend store 419 implementations in order to manage the cache, and for caching to disk 420 <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> is provided to support this.</p> 421 422 <p>Typically the module will be configured as so;</p> 423 424 <pre class="prettyprint lang-config">CacheRoot "/var/cache/apache/" 425CacheEnable disk / 426CacheDirLevels 2 427CacheDirLength 1</pre> 428 429 430 <p>Importantly, as the cached files are locally stored, operating system 431 in-memory caching will typically be applied to their access also. So 432 although the files are stored on disk, if they are frequently accessed 433 it is likely the operating system will ensure that they are actually 434 served from memory.</p> 435 436 437 438 <h3>Understanding the Cache-Store</h3> 439 440 441 <p>To store items in the cache, <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> creates 442 a 22 character hash of the URL being requested. This hash incorporates 443 the hostname, protocol, port, path and any CGI arguments to the URL, 444 as well as elements defined by the Vary header to ensure that multiple 445 URLs do not collide with one another.</p> 446 447 <p>Each character may be any one of 64-different characters, which mean 448 that overall there are 64^22 possible hashes. For example, a URL might 449 be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used 450 as a prefix for the naming of the files specific to that URL within 451 the cache, however first it is split up into directories as per 452 the <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code> and 453 <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code> 454 directives.</p> 455 456 <p><code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code> 457 specifies how many levels of subdirectory there should be, and 458 <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code> 459 specifies how many characters should be in each directory. With 460 the example settings given above, the hash would be turned into 461 a filename prefix as 462 <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p> 463 464 <p>The overall aim of this technique is to reduce the number of 465 subdirectories or files that may be in a particular directory, 466 as most file-systems slow down as this number increases. With 467 setting of "1" for 468 <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code> 469 there can at most be 64 subdirectories at any particular level. 470 With a setting of 2 there can be 64 * 64 subdirectories, and so on. 471 Unless you have a good reason not to, using a setting of "1" 472 for <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code> 473 is recommended.</p> 474 475 <p>Setting 476 <code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code> 477 depends on how many files you anticipate to store in the cache. 478 With the setting of "2" used in the above example, a grand 479 total of 4096 subdirectories can ultimately be created. With 480 1 million files cached, this works out at roughly 245 cached 481 URLs per directory.</p> 482 483 <p>Each URL uses at least two files in the cache-store. Typically 484 there is a ".header" file, which includes meta-information about 485 the URL, such as when it is due to expire and a ".data" file 486 which is a verbatim copy of the content to be served.</p> 487 488 <p>In the case of a content negotiated via the "Vary" header, a 489 ".vary" directory will be created for the URL in question. This 490 directory will have multiple ".data" files corresponding to the 491 differently negotiated content.</p> 492 493 494 <h3>Maintaining the Disk Cache</h3> 495 496 497 <p>The <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> module makes no attempt to 498 regulate the amount of disk space used by the cache, although it 499 will gracefully stand down on any disk error and behave as if the 500 cache was never present.</p> 501 502 <p>Instead, provided with httpd is the <a href="programs/htcacheclean.html">htcacheclean</a> tool which allows you 503 to clean the cache periodically. Determining how frequently to run <a href="programs/htcacheclean.html">htcacheclean</a> and what target size to 504 use for the cache is somewhat complex and trial and error may be needed to 505 select optimal values.</p> 506 507 <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of 508 operation. It can be run as persistent daemon, or periodically from 509 cron. <a href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour 510 or more to process very large (tens of gigabytes) caches and if you are 511 running it from cron it is recommended that you determine how long a typical 512 run takes, to avoid running more than one instance at a time.</p> 513 514 <p>It is also recommended that an appropriate "nice" level is chosen for 515 htcacheclean so that the tool does not cause excessive disk io while the 516 server is running.</p> 517 518 <p class="figure"> 519 <img src="images/caching_fig1.gif" alt="" width="600" height="406" /><br /> 520 <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical 521 cache growth / clean sequence.</p> 522 523 <p>Because <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> does not itself pay attention 524 to how much space is used you should ensure that 525 <a href="programs/htcacheclean.html">htcacheclean</a> is configured to 526 leave enough "grow room" following a clean.</p> 527 528 529 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 530<div class="section"> 531<h2><a name="socache-caching" id="socache-caching">Two-state Key/Value Shared Object Caching</a></h2> 532 533 534 535 <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> 536 537 <p>The Apache HTTP server offers a low level shared object cache for 538 caching information such as SSL sessions, or authentication credentials, 539 within the <a href="socache.html">socache</a> interface.</p> 540 541 <p>Additional modules are provided for each implementation, offering the 542 following backends:</p> 543 544 <dl> 545 <dt><code class="module"><a href="/mod/mod_socache_dbm.html">mod_socache_dbm</a></code></dt> 546 <dd>DBM based shared object cache.</dd> 547 <dt><code class="module"><a href="/mod/mod_socache_dc.html">mod_socache_dc</a></code></dt> 548 <dd>Distcache based shared object cache.</dd> 549 <dt><code class="module"><a href="/mod/mod_socache_memcache.html">mod_socache_memcache</a></code></dt> 550 <dd>Memcache based shared object cache.</dd> 551 <dt><code class="module"><a href="/mod/mod_socache_shmcb.html">mod_socache_shmcb</a></code></dt> 552 <dd>Shared memory based shared object cache.</dd> 553 </dl> 554 555 <h3><a name="mod_authn_socache-caching" id="mod_authn_socache-caching">Caching Authentication Credentials</a></h3> 556 557 558 <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> 559 560 <p>The <code class="module"><a href="/mod/mod_authn_socache.html">mod_authn_socache</a></code> module allows the result of 561 authentication to be cached, relieving load on authentication backends.</p> 562 563 564 565 <h3><a name="mod_ssl-caching" id="mod_ssl-caching">Caching SSL Sessions</a></h3> 566 567 568 <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> 569 570 <p>The <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> module uses the <code>socache</code> interface 571 to provide a session cache and a stapling cache.</p> 572 573 574 575 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 576<div class="section"> 577<h2><a name="file-caching" id="file-caching">Specialized File Caching</a></h2> 578 579 580 581 <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> 582 583 <p>On platforms where a filesystem might be slow, or where file 584 handles are expensive, the option exists to pre-load files into 585 memory on startup.</p> 586 587 <p>On systems where opening files is slow, the option exists to 588 open the file on startup and cache the file handle. These 589 options can help on systems where access to static files is 590 slow.</p> 591 592 <h3><a name="filehandle" id="filehandle">File-Handle Caching</a></h3> 593 594 595 <p>The act of opening a file can itself be a source of delay, particularly 596 on network filesystems. By maintaining a cache of open file descriptors 597 for commonly served files, httpd can avoid this delay. Currently httpd 598 provides one implementation of File-Handle Caching.</p> 599 600 <h4>CacheFile</h4> 601 602 603 <p>The most basic form of caching present in httpd is the file-handle 604 caching provided by <code class="module"><a href="/mod/mod_file_cache.html">mod_file_cache</a></code>. Rather than caching 605 file-contents, this cache maintains a table of open file descriptors. Files 606 to be cached in this manner are specified in the configuration file using 607 the <code class="directive"><a href="/mod/mod_file_cache.html#cachefile">CacheFile</a></code> 608 directive.</p> 609 610 <p>The 611 <code class="directive"><a href="/mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive 612 instructs httpd to open the file when it is started and to re-use 613 this file-handle for all subsequent access to this file.</p> 614 615 <pre class="prettyprint lang-config">CacheFile /usr/local/apache2/htdocs/index.html</pre> 616 617 618 <p>If you intend to cache a large number of files in this manner, you 619 must ensure that your operating system's limit for the number of open 620 files is set appropriately.</p> 621 622 <p>Although using <code class="directive"><a href="/mod/mod_file_cache.html#cachefile">CacheFile</a></code> 623 does not cause the file-contents to be cached per-se, it does mean 624 that if the file changes while httpd is running these changes will 625 not be picked up. The file will be consistently served as it was 626 when httpd was started.</p> 627 628 <p>If the file is removed while httpd is running, it will continue 629 to maintain an open file descriptor and serve the file as it was when 630 httpd was started. This usually also means that although the file 631 will have been deleted, and not show up on the filesystem, extra free 632 space will not be recovered until httpd is stopped and the file 633 descriptor closed.</p> 634 635 636 637 638 <h3><a name="inmemory" id="inmemory">In-Memory Caching</a></h3> 639 640 641 <p>Serving directly from system memory is universally the fastest method 642 of serving content. Reading files from a disk controller or, even worse, 643 from a remote network is orders of magnitude slower. Disk controllers 644 usually involve physical processes, and network access is limited by 645 your available bandwidth. Memory access on the other hand can take mere 646 nano-seconds.</p> 647 648 <p>System memory isn't cheap though, byte for byte it's by far the most 649 expensive type of storage and it's important to ensure that it is used 650 efficiently. By caching files in memory you decrease the amount of 651 memory available on the system. As we'll see, in the case of operating 652 system caching, this is not so much of an issue, but when using 653 httpd's own in-memory caching it is important to make sure that you 654 do not allocate too much memory to a cache. Otherwise the system 655 will be forced to swap out memory, which will likely degrade 656 performance.</p> 657 658 <h4>Operating System Caching</h4> 659 660 661 <p>Almost all modern operating systems cache file-data in memory managed 662 directly by the kernel. This is a powerful feature, and for the most 663 part operating systems get it right. For example, on Linux, let's look at 664 the difference in the time it takes to read a file for the first time 665 and the second time;</p> 666 667 <div class="example"><pre>colm@coroebus:~$ time cat testfile > /dev/null 668real 0m0.065s 669user 0m0.000s 670sys 0m0.001s 671colm@coroebus:~$ time cat testfile > /dev/null 672real 0m0.003s 673user 0m0.003s 674sys 0m0.000s</pre></div> 675 676 <p>Even for this small file, there is a huge difference in the amount 677 of time it takes to read the file. This is because the kernel has cached 678 the file contents in memory.</p> 679 680 <p>By ensuring there is "spare" memory on your system, you can ensure 681 that more and more file-contents will be stored in this cache. This 682 can be a very efficient means of in-memory caching, and involves no 683 extra configuration of httpd at all.</p> 684 685 <p>Additionally, because the operating system knows when files are 686 deleted or modified, it can automatically remove file contents from the 687 cache when necessary. This is a big advantage over httpd's in-memory 688 caching which has no way of knowing when a file has changed.</p> 689 690 691 <p>Despite the performance and advantages of automatic operating system 692 caching there are some circumstances in which in-memory caching may be 693 better performed by httpd.</p> 694 695 <h4>MMapFile Caching</h4> 696 697 698 <p><code class="module"><a href="/mod/mod_file_cache.html">mod_file_cache</a></code> provides the 699 <code class="directive"><a href="/mod/mod_file_cache.html#mmapfile">MMapFile</a></code> directive, which 700 allows you to have httpd map a static file's contents into memory at 701 start time (using the mmap system call). httpd will use the in-memory 702 contents for all subsequent accesses to this file.</p> 703 704 <pre class="prettyprint lang-config">MMapFile /usr/local/apache2/htdocs/index.html</pre> 705 706 707 <p>As with the 708 <code class="directive"><a href="/mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive, any 709 changes in these files will not be picked up by httpd after it has 710 started.</p> 711 712 <p> The <code class="directive"><a href="/mod/mod_file_cache.html#mmapfile">MMapFile</a></code> 713 directive does not keep track of how much memory it allocates, so 714 you must ensure not to over-use the directive. Each httpd child 715 process will replicate this memory, so it is critically important 716 to ensure that the files mapped are not so large as to cause the 717 system to swap memory.</p> 718 719 720 721 </div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 722<div class="section"> 723<h2><a name="security" id="security">Security Considerations</a></h2> 724 725 726 <h3>Authorization and Access Control</h3> 727 728 729 <p>Using <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> in its default state where 730 <code class="directive"><a href="/mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code> is set to 731 <code>On</code> is very much like having a caching reverse-proxy bolted 732 to the front of the server. Requests will be served by the caching module 733 unless it determines that the origin server should be queried just as an 734 external cache would, and this drastically changes the security model of 735 httpd.</p> 736 737 <p>As traversing a filesystem hierarchy to examine potential 738 <code>.htaccess</code> files would be a very expensive operation, 739 partially defeating the point of caching (to speed up requests), 740 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> makes no decision about whether a cached 741 entity is authorised for serving. In other words; if 742 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> has cached some content, it will be served 743 from the cache as long as that content has not expired.</p> 744 745 <p>If, for example, your configuration permits access to a resource by IP 746 address you should ensure that this content is not cached. You can do this 747 by using the <code class="directive"><a href="/mod/mod_cache.html#cachedisable">CacheDisable</a></code> 748 directive, or <code class="module"><a href="/mod/mod_expires.html">mod_expires</a></code>. Left unchecked, 749 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> - very much like a reverse proxy - would cache 750 the content when served and then serve it to any client, on any IP 751 address.</p> 752 753 <p>When the <code class="directive"><a href="/mod/mod_cache.html#cachequickhandler">CacheQuickHandler</a></code> 754 directive is set to <code>Off</code>, the full set of request processing 755 phases are executed and the security model remains unchanged.</p> 756 757 758 <h3>Local exploits</h3> 759 760 761 <p>As requests to end-users can be served from the cache, the cache 762 itself can become a target for those wishing to deface or interfere with 763 content. It is important to bear in mind that the cache must at all 764 times be writable by the user which httpd is running as. This is in 765 stark contrast to the usually recommended situation of maintaining 766 all content unwritable by the Apache user.</p> 767 768 <p>If the Apache user is compromised, for example through a flaw in 769 a CGI process, it is possible that the cache may be targeted. When 770 using <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code>, it is relatively easy to 771 insert or modify a cached entity.</p> 772 773 <p>This presents a somewhat elevated risk in comparison to the other 774 types of attack it is possible to make as the Apache user. If you are 775 using <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code> you should bear this in mind - 776 ensure you upgrade httpd when security upgrades are announced and 777 run CGI processes as a non-Apache user using <a href="suexec.html">suEXEC</a> if possible.</p> 778 779 780 781 <h3>Cache Poisoning</h3> 782 783 784 <p>When running httpd as a caching proxy server, there is also the 785 potential for so-called cache poisoning. Cache Poisoning is a broad 786 term for attacks in which an attacker causes the proxy server to 787 retrieve incorrect (and usually undesirable) content from the origin 788 server.</p> 789 790 <p>For example if the DNS servers used by your system running httpd 791 are vulnerable to DNS cache poisoning, an attacker may be able to control 792 where httpd connects to when requesting content from the origin server. 793 Another example is so-called HTTP request-smuggling attacks.</p> 794 795 <p>This document is not the correct place for an in-depth discussion 796 of HTTP request smuggling (instead, try your favourite search engine) 797 however it is important to be aware that it is possible to make 798 a series of requests, and to exploit a vulnerability on an origin 799 webserver such that the attacker can entirely control the content 800 retrieved by the proxy.</p> 801 802 803 <h3>Denial of Service / Cachebusting</h3> 804 805 806 <p>The Vary mechanism allows multiple variants of the same URL to be 807 cached side by side. Depending on header values provided by the client, 808 the cache will select the correct variant to return to the client. This 809 mechanism can become a problem when an attempt is made to vary on a 810 header that is known to contain a wide range of possible values under 811 normal use, for example the <code>User-Agent</code> header. Depending 812 on the popularity of the particular web site thousands or millions of 813 duplicate cache entries could be created for the same URL, crowding 814 out other entries in the cache.</p> 815 816 <p>In other cases, there may be a need to change the URL of a particular 817 resource on every request, usually by adding a "cachebuster" string to 818 the URL. If this content is declared cacheable by a server for a 819 significant freshness lifetime, these entries can crowd out 820 legitimate entries in a cache. While <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> 821 provides a 822 <code class="directive"><a href="/mod/mod_cache.html#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></code> 823 directive, this directive should be used with care to ensure that 824 downstream proxy or browser caches aren't subjected to the same denial 825 of service issue.</p> 826 827 </div></div> 828<div class="bottomlang"> 829<p><span>Available Languages: </span><a href="/en/caching.html" title="English"> en </a> | 830<a href="/fr/caching.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 831<a href="/tr/caching.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 832</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> 833<script type="text/javascript"><!--//--><![CDATA[//><!-- 834var comments_shortname = 'httpd'; 835var comments_identifier = 'http://httpd.apache.org/docs/2.4/caching.html'; 836(function(w, d) { 837 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 838 d.write('<div id="comments_thread"><\/div>'); 839 var s = d.createElement('script'); 840 s.type = 'text/javascript'; 841 s.async = true; 842 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 843 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 844 } 845 else { 846 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 847 } 848})(window, document); 849//--><!]]></script></div><div id="footer"> 850<p class="apache">Copyright 2014 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> 851<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.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"><!--//--><![CDATA[//><!-- 852if (typeof(prettyPrint) !== 'undefined') { 853 prettyPrint(); 854} 855//--><!]]></script> 856</body></html>
