github.com/krum110487/go-htaccess@v0.0.0-20240316004156-60641c8e7598/tests/data/apache_2_2_34/manual/caching.html.en (about) 1 <?xml version="1.0" encoding="ISO-8859-1"?> 2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> 4 <meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" /> 5 <!-- 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 This file is generated from xml source: DO NOT EDIT 8 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 9 --> 10 <title>Caching Guide - Apache HTTP Server Version 2.2</title> 11 <link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 12 <link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 13 <link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="./style/css/prettify.css" /> 14 <script src="./style/scripts/prettify.min.js" type="text/javascript"> 15 </script> 16 17 <link href="./images/favicon.ico" rel="shortcut icon" /><link href="http://httpd.apache.org/docs/current/caching.html" rel="canonical" /></head> 18 <body id="manual-page"><div id="page-header"> 19 <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> 20 <p class="apache">Apache HTTP Server Version 2.2</p> 21 <img alt="" src="./images/feather.gif" /></div> 22 <div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div> 23 <div id="path"> 24 <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.2</a></div><div id="page-content"><div class="retired"><h4>Please note</h4> 25 <p> This document refers to a legacy release (<strong>2.2</strong>) of Apache httpd. The active release (<strong>2.4</strong>) is documented <a href="http://httpd.apache.org/docs/current">here</a>. If you have not already upgraded, please follow <a href="http://httpd.apache.org/docs/current/upgrading.html">this link</a> for more information.</p> 26 <p>You may follow <a href="http://httpd.apache.org/docs/current/caching.html">this link</a> to go to the current version of this document.</p></div><div id="preamble"><h1>Caching Guide</h1> 27 <div class="toplang"> 28 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> | 29 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | 30 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p> 31 </div> 32 33 <p>This document supplements the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>, 34 <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>, <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code>, 35 <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. 36 It describes how to use Apache's caching features to accelerate web and 37 proxy serving, while avoiding common problems and misconfigurations.</p> 38 </div> 39 <div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li> 40 <li><img alt="" src="./images/down.gif" /> <a href="#overview">Caching Overview</a></li> 41 <li><img alt="" src="./images/down.gif" /> <a href="#security">Security Considerations</a></li> 42 <li><img alt="" src="./images/down.gif" /> <a href="#filehandle">File-Handle Caching</a></li> 43 <li><img alt="" src="./images/down.gif" /> <a href="#inmemory">In-Memory Caching</a></li> 44 <li><img alt="" src="./images/down.gif" /> <a href="#disk">Disk-based Caching</a></li> 45 </ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 46 <div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 47 <div class="section"> 48 <h2><a name="introduction" id="introduction">Introduction</a></h2> 49 50 51 <p>As of Apache HTTP server version 2.2 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> 52 and <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> are no longer marked 53 experimental and are considered suitable for production use. These 54 caching architectures provide a powerful means to accelerate HTTP 55 handling, both as an origin webserver and as a proxy.</p> 56 57 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> and its provider modules 58 <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> and <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> 59 provide intelligent, HTTP-aware caching. The content itself is stored 60 in the cache, and mod_cache aims to honour all of the various HTTP 61 headers and options that control the cachability of content. It can 62 handle both local and proxied content. <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> 63 is aimed at both simple and complex caching configurations, where 64 you are dealing with proxied content, dynamic local content or 65 have a need to speed up access to local files which change with 66 time.</p> 67 68 <p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> on the other hand presents a more 69 basic, but sometimes useful, form of caching. Rather than maintain 70 the complexity of actively ensuring the cachability of URLs, 71 <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> offers file-handle and memory-mapping 72 tricks to keep a cache of files as they were when Apache was last 73 started. As such, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> is aimed at improving 74 the access time to local static files which do not change very 75 often.</p> 76 77 <p>As <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> presents a relatively simple 78 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 79 in this guide cover the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching 80 architecture.</p> 81 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> 86 87 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 88 <div class="section"> 89 <h2><a name="overview" id="overview">Caching Overview</a></h2> 90 91 92 93 <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_mem_cache.html">mod_mem_cache</a></code></li><li><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</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> 94 95 <p>There are two main stages in <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> that can 96 occur in the lifetime of a request. First, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> 97 is a URL mapping module, which means that if a URL has been cached, 98 and the cached version of that URL has not expired, the request will 99 be served directly by <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>.</p> 100 101 <p>This means that any other stages that might ordinarily happen 102 in the process of serving a request -- for example being handled 103 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> -- 104 won't happen. But then this is the point of caching content in 105 the first place.</p> 106 107 <p>If the URL is not found within the cache, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> 108 will add a <a href="filter.html">filter</a> to the request handling. After 109 Apache has located the content by the usual means, the filter will be run 110 as the content is served. If the content is determined to be cacheable, 111 the content will be saved to the cache for future serving.</p> 112 113 <p>If the URL is found within the cache, but also found to have expired, 114 the filter is added anyway, but <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will create 115 a conditional request to the backend, to determine if the cached version 116 is still current. If the cached version is still current, its 117 meta-information will be updated and the request will be served from the 118 cache. If the cached version is no longer current, the cached version 119 will be deleted and the filter will save the updated content to the cache 120 as it is served.</p> 121 122 <h3>Improving Cache Hits</h3> 123 124 125 <p>When caching locally generated content, ensuring that 126 <code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code> is set to 127 <code>On</code> can dramatically improve the ratio of cache hits. This 128 is because the hostname of the virtual-host serving the content forms 129 a part of the cache key. With the setting set to <code>On</code> 130 virtual-hosts with multiple server names or aliases will not produce 131 differently cached entities, and instead content will be cached as 132 per the canonical hostname.</p> 133 134 <p>Because caching is performed within the URL to filename translation 135 phase, cached documents will only be served in response to URL requests. 136 Ordinarily this is of little consequence, but there is one circumstance 137 in which it matters: If you are using <a href="howto/ssi.html">Server 138 Side Includes</a>;</p> 139 140 <div class="example"><pre><!-- The following include can be cached --> 141 <!--#include virtual="/footer.html" --> 142 143 <!-- The following include can not be cached --> 144 <!--#include file="/path/to/footer.html" --></pre></div> 145 146 <p>If you are using Server Side Includes, and want the benefit of speedy 147 serves from the cache, you should use <code>virtual</code> include 148 types.</p> 149 150 151 <h3>Expiry Periods</h3> 152 153 154 <p>The default expiry period for cached entities is one hour, however 155 this can be easily over-ridden by using the <code class="directive"><a href="./mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive. This 156 default is only used when the original source of the content does not 157 specify an expire time or time of last modification.</p> 158 159 <p>If a response does not include an <code>Expires</code> header but does 160 include a <code>Last-Modified</code> header, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> 161 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> 162 163 <p>For local content, <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code> may be used to 164 fine-tune the expiry period.</p> 165 166 <p>The maximum expiry period may also be controlled by using the 167 <code class="directive"><a href="./mod/mod_cache.html#cachemaxexpire">CacheMaxExpire</a></code>.</p> 168 169 170 171 <h3>A Brief Guide to Conditional Requests</h3> 172 173 174 <p>When content expires from the cache and is re-requested from the 175 backend or content provider, rather than pass on the original request, 176 Apache will use a conditional request instead.</p> 177 178 <p>HTTP offers a number of headers which allow a client, or cache 179 to discern between different versions of the same content. For 180 example if a resource was served with an "Etag:" header, it is 181 possible to make a conditional request with an "If-None-Match:" 182 header. If a resource was served with a "Last-Modified:" header 183 it is possible to make a conditional request with an 184 "If-Modified-Since:" header, and so on.</p> 185 186 <p>When such a conditional request is made, the response differs 187 depending on whether the content matches the conditions. If a request is 188 made with an "If-Modified-Since:" header, and the content has not been 189 modified since the time indicated in the request then a terse "304 Not 190 Modified" response is issued.</p> 191 192 <p>If the content has changed, then it is served as if the request were 193 not conditional to begin with.</p> 194 195 <p>The benefits of conditional requests in relation to caching are 196 twofold. Firstly, when making such a request to the backend, if the 197 content from the backend matches the content in the store, this can be 198 determined easily and without the overhead of transferring the entire 199 resource.</p> 200 201 <p>Secondly, conditional requests are usually less strenuous on the 202 backend. For static files, typically all that is involved is a call 203 to <code>stat()</code> or similar system call, to see if the file has 204 changed in size or modification time. As such, even if Apache is 205 caching local content, even expired content may still be served faster 206 from the cache if it has not changed. As long as reading from the cache 207 store is faster than reading from the backend (e.g. an in-memory cache 208 compared to reading from disk).</p> 209 210 211 <h3>What Can be Cached?</h3> 212 213 214 <p>As mentioned already, the two styles of caching in Apache work 215 differently, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> caching maintains file 216 contents as they were when Apache was started. When a request is 217 made for a file that is cached by this module, it is intercepted 218 and the cached file is served.</p> 219 220 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching on the other hand is more 221 complex. When serving a request, if it has not been cached 222 previously, the caching module will determine if the content 223 is cacheable. The conditions for determining cachability of 224 a response are;</p> 225 226 <ol> 227 <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> 228 229 <li>The response must have a HTTP status code of 200, 203, 300, 301 or 230 410.</li> 231 232 <li>The request must be a HTTP GET request.</li> 233 234 <li>If the request contains an "Authorization:" header, the response 235 will not be cached.</li> 236 237 <li>If the response contains an "Authorization:" header, it must 238 also contain an "s-maxage", "must-revalidate" or "public" option 239 in the "Cache-Control:" header.</li> 240 241 <li>If the URL included a query string (e.g. from a HTML form GET 242 method) it will not be cached unless the response specifies an 243 explicit expiration by including an "Expires:" header or the max-age 244 or s-maxage directive of the "Cache-Control:" header, as per RFC2616 245 sections 13.9 and 13.2.1.</li> 246 247 <li>If the response has a status of 200 (OK), the response must 248 also include at least one of the "Etag", "Last-Modified" or 249 the "Expires" headers, or the max-age or s-maxage directive of 250 the "Cache-Control:" header, unless the 251 <code class="directive"><a href="./mod/mod_cache.html#cacheignorenolastmod">CacheIgnoreNoLastMod</a></code> 252 directive has been used to require otherwise.</li> 253 254 <li>If the response includes the "private" option in a "Cache-Control:" 255 header, it will not be stored unless the 256 <code class="directive"><a href="./mod/mod_cache.html#cachestoreprivate">CacheStorePrivate</a></code> has been 257 used to require otherwise.</li> 258 259 <li>Likewise, if the response includes the "no-store" option in a 260 "Cache-Control:" header, it will not be stored unless the 261 <code class="directive"><a href="./mod/mod_cache.html#cachestorenostore">CacheStoreNoStore</a></code> has been 262 used.</li> 263 264 <li>A response will not be stored if it includes a "Vary:" header 265 containing the match-all "*".</li> 266 </ol> 267 268 269 <h3>What Should Not be Cached?</h3> 270 271 272 <p>In short, any content which is highly time-sensitive, or which varies 273 depending on the particulars of the request that are not covered by 274 HTTP negotiation, should not be cached.</p> 275 276 <p>If you have dynamic content which changes depending on the IP address 277 of the requester, or changes every 5 minutes, it should almost certainly 278 not be cached.</p> 279 280 <p>If on the other hand, the content served differs depending on the 281 values of various HTTP headers, it might be possible 282 to cache it intelligently through the use of a "Vary" header.</p> 283 284 285 <h3>Variable/Negotiated Content</h3> 286 287 288 <p>If a response with a "Vary" header is received by 289 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> when requesting content by the backend it 290 will attempt to handle it intelligently. If possible, 291 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will detect the headers attributed in the 292 "Vary" response in future requests and serve the correct cached 293 response.</p> 294 295 <p>If for example, a response is received with a vary header such as;</p> 296 297 <div class="example"><p><code> 298 Vary: negotiate,accept-language,accept-charset 299 </code></p></div> 300 301 <p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will only serve the cached content to 302 requesters with accept-language and accept-charset headers 303 matching those of the original request.</p> 304 305 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 306 <div class="section"> 307 <h2><a name="security" id="security">Security Considerations</a></h2> 308 309 310 <h3>Authorization and Access Control</h3> 311 312 313 <p>Using <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> is very much like having a built 314 in reverse-proxy. Requests will be served by the caching module unless 315 it determines that the backend should be queried. When caching local 316 resources, this drastically changes the security model of Apache.</p> 317 318 <p>As traversing a filesystem hierarchy to examine potential 319 <code>.htaccess</code> files would be a very expensive operation, 320 partially defeating the point of caching (to speed up requests), 321 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> makes no decision about whether a cached 322 entity is authorised for serving. In other words; if 323 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> has cached some content, it will be served 324 from the cache as long as that content has not expired.</p> 325 326 <p>If, for example, your configuration permits access to a resource by IP 327 address you should ensure that this content is not cached. You can do this by 328 using the <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code> 329 directive, or <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code>. Left unchecked, 330 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> - very much like a reverse proxy - would cache 331 the content when served and then serve it to any client, on any IP 332 address.</p> 333 334 335 <h3>Local exploits</h3> 336 337 338 <p>As requests to end-users can be served from the cache, the cache 339 itself can become a target for those wishing to deface or interfere with 340 content. It is important to bear in mind that the cache must at all 341 times be writable by the user which Apache is running as. This is in 342 stark contrast to the usually recommended situation of maintaining 343 all content unwritable by the Apache user.</p> 344 345 <p>If the Apache user is compromised, for example through a flaw in 346 a CGI process, it is possible that the cache may be targeted. When 347 using <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>, it is relatively easy to 348 insert or modify a cached entity.</p> 349 350 <p>This presents a somewhat elevated risk in comparison to the other 351 types of attack it is possible to make as the Apache user. If you are 352 using <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> you should bear this in mind - 353 ensure you upgrade Apache when security upgrades are announced and 354 run CGI processes as a non-Apache user using <a href="suexec.html">suEXEC</a> if possible.</p> 355 356 357 358 <h3>Cache Poisoning</h3> 359 360 361 <p>When running Apache as a caching proxy server, there is also the 362 potential for so-called cache poisoning. Cache Poisoning is a broad 363 term for attacks in which an attacker causes the proxy server to 364 retrieve incorrect (and usually undesirable) content from the backend. 365 </p> 366 367 <p>For example if the DNS servers used by your system running Apache 368 are vulnerable to DNS cache poisoning, an attacker may be able to control 369 where Apache connects to when requesting content from the origin server. 370 Another example is so-called HTTP request-smuggling attacks.</p> 371 372 <p>This document is not the correct place for an in-depth discussion 373 of HTTP request smuggling (instead, try your favourite search engine) 374 however it is important to be aware that it is possible to make 375 a series of requests, and to exploit a vulnerability on an origin 376 webserver such that the attacker can entirely control the content 377 retrieved by the proxy.</p> 378 379 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 380 <div class="section"> 381 <h2><a name="filehandle" id="filehandle">File-Handle Caching</a></h2> 382 383 384 <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><li><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_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_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> 385 386 <p>The act of opening a file can itself be a source of delay, particularly 387 on network filesystems. By maintaining a cache of open file descriptors 388 for commonly served files, Apache can avoid this delay. Currently Apache 389 provides two different implementations of File-Handle Caching.</p> 390 391 <h3>CacheFile</h3> 392 393 394 <p>The most basic form of caching present in Apache is the file-handle 395 caching provided by <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code>. Rather than caching 396 file-contents, this cache maintains a table of open file descriptors. Files 397 to be cached in this manner are specified in the configuration file using 398 the <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> 399 directive.</p> 400 401 <p>The 402 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive 403 instructs Apache to open the file when Apache is started and to re-use 404 this file-handle for all subsequent access to this file.</p> 405 406 <div class="example"><pre>CacheFile /usr/local/apache2/htdocs/index.html</pre></div> 407 408 <p>If you intend to cache a large number of files in this manner, you 409 must ensure that your operating system's limit for the number of open 410 files is set appropriately.</p> 411 412 <p>Although using <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> 413 does not cause the file-contents to be cached per-se, it does mean 414 that if the file changes while Apache is running these changes will 415 not be picked up. The file will be consistently served as it was 416 when Apache was started.</p> 417 418 <p>If the file is removed while Apache is running, Apache will continue 419 to maintain an open file descriptor and serve the file as it was when 420 Apache was started. This usually also means that although the file 421 will have been deleted, and not show up on the filesystem, extra free 422 space will not be recovered until Apache is stopped and the file 423 descriptor closed.</p> 424 425 426 <h3>CacheEnable fd</h3> 427 428 429 <p><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> also provides its own file-handle 430 caching scheme, which can be enabled via the 431 <code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> directive.</p> 432 433 <div class="example"><pre>CacheEnable fd /</pre></div> 434 435 <p>As with all of <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> this type of file-handle 436 caching is intelligent, and handles will not be maintained beyond 437 the expiry time of the cached content.</p> 438 439 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 440 <div class="section"> 441 <h2><a name="inmemory" id="inmemory">In-Memory Caching</a></h2> 442 443 444 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</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#mmapfile">MMapFile</a></code></li></ul></td></tr></table> 445 446 <p>Serving directly from system memory is universally the fastest method 447 of serving content. Reading files from a disk controller or, even worse, 448 from a remote network is orders of magnitude slower. Disk controllers 449 usually involve physical processes, and network access is limited by 450 your available bandwidth. Memory access on the other hand can take mere 451 nano-seconds.</p> 452 453 <p>System memory isn't cheap though, byte for byte it's by far the most 454 expensive type of storage and it's important to ensure that it is used 455 efficiently. By caching files in memory you decrease the amount of 456 memory available on the system. As we'll see, in the case of operating 457 system caching, this is not so much of an issue, but when using 458 Apache's own in-memory caching it is important to make sure that you 459 do not allocate too much memory to a cache. Otherwise the system 460 will be forced to swap out memory, which will likely degrade 461 performance.</p> 462 463 <h3>Operating System Caching</h3> 464 465 466 <p>Almost all modern operating systems cache file-data in memory managed 467 directly by the kernel. This is a powerful feature, and for the most 468 part operating systems get it right. For example, on Linux, let's look at 469 the difference in the time it takes to read a file for the first time 470 and the second time;</p> 471 472 <div class="example"><pre>colm@coroebus:~$ time cat testfile > /dev/null 473 real 0m0.065s 474 user 0m0.000s 475 sys 0m0.001s 476 colm@coroebus:~$ time cat testfile > /dev/null 477 real 0m0.003s 478 user 0m0.003s 479 sys 0m0.000s</pre></div> 480 481 <p>Even for this small file, there is a huge difference in the amount 482 of time it takes to read the file. This is because the kernel has cached 483 the file contents in memory.</p> 484 485 <p>By ensuring there is "spare" memory on your system, you can ensure 486 that more and more file-contents will be stored in this cache. This 487 can be a very efficient means of in-memory caching, and involves no 488 extra configuration of Apache at all.</p> 489 490 <p>Additionally, because the operating system knows when files are 491 deleted or modified, it can automatically remove file contents from the 492 cache when necessary. This is a big advantage over Apache's in-memory 493 caching which has no way of knowing when a file has changed.</p> 494 495 496 <p>Despite the performance and advantages of automatic operating system 497 caching there are some circumstances in which in-memory caching may be 498 better performed by Apache.</p> 499 500 <p>Firstly, an operating system can only cache files it knows about. If 501 you are running Apache as a proxy server, the files you are caching are 502 not locally stored but remotely served. If you still want the unbeatable 503 speed of in-memory caching, Apache's own memory caching is needed.</p> 504 505 <h3>MMapFile Caching</h3> 506 507 508 <p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> provides the 509 <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code> directive, which 510 allows you to have Apache map a static file's contents into memory at 511 start time (using the mmap system call). Apache will use the in-memory 512 contents for all subsequent accesses to this file.</p> 513 514 <div class="example"><pre>MMapFile /usr/local/apache2/htdocs/index.html</pre></div> 515 516 <p>As with the 517 <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive, any 518 changes in these files will not be picked up by Apache after it has 519 started.</p> 520 521 <p> The <code class="directive"><a href="./mod/mod_file_cache.html#mmapfile">MMapFile</a></code> 522 directive does not keep track of how much memory it allocates, so 523 you must ensure not to over-use the directive. Each Apache child 524 process will replicate this memory, so it is critically important 525 to ensure that the files mapped are not so large as to cause the 526 system to swap memory.</p> 527 528 529 <h3>mod_mem_cache Caching</h3> 530 531 532 <p><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> provides a HTTP-aware intelligent 533 in-memory cache. It also uses heap memory directly, which means that 534 even if <var>MMap</var> is not supported on your system, 535 <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> may still be able to perform caching.</p> 536 537 <p>Caching of this type is enabled via;</p> 538 539 <div class="example"><pre># Enable memory caching 540 CacheEnable mem / 541 542 # Limit the size of the cache to 1 Megabyte 543 MCacheSize 1024</pre></div> 544 545 </div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div> 546 <div class="section"> 547 <h2><a name="disk" id="disk">Disk-based Caching</a></h2> 548 549 550 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_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></ul></td></tr></table> 551 552 <p><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> provides a disk-based caching mechanism 553 for <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>. As with <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> 554 this cache is intelligent and content will be served from the cache only 555 as long as it is considered valid.</p> 556 557 <p>Typically the module will be configured as so;</p> 558 559 <div class="example"><pre>CacheRoot /var/cache/apache/ 560 CacheEnable disk / 561 CacheDirLevels 2 562 CacheDirLength 1</pre></div> 563 564 <p>Importantly, as the cached files are locally stored, operating system 565 in-memory caching will typically be applied to their access also. So 566 although the files are stored on disk, if they are frequently accessed 567 it is likely the operating system will ensure that they are actually 568 served from memory.</p> 569 570 <h3>Understanding the Cache-Store</h3> 571 572 573 <p>To store items in the cache, <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> creates 574 a 22 character hash of the URL being requested. This hash incorporates 575 the hostname, protocol, port, path and any CGI arguments to the URL, 576 to ensure that multiple URLs do not collide.</p> 577 578 <p>Each character may be any one of 64-different characters, which mean 579 that overall there are 64^22 possible hashes. For example, a URL might 580 be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used 581 as a prefix for the naming of the files specific to that URL within 582 the cache, however first it is split up into directories as per 583 the <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code> and 584 <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code> 585 directives.</p> 586 587 <p><code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code> 588 specifies how many levels of subdirectory there should be, and 589 <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code> 590 specifies how many characters should be in each directory. With 591 the example settings given above, the hash would be turned into 592 a filename prefix as 593 <code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p> 594 595 <p>The overall aim of this technique is to reduce the number of 596 subdirectories or files that may be in a particular directory, 597 as most file-systems slow down as this number increases. With 598 setting of "1" for 599 <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code> 600 there can at most be 64 subdirectories at any particular level. 601 With a setting of 2 there can be 64 * 64 subdirectories, and so on. 602 Unless you have a good reason not to, using a setting of "1" 603 for <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code> 604 is recommended.</p> 605 606 <p>Setting 607 <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code> 608 depends on how many files you anticipate to store in the cache. 609 With the setting of "2" used in the above example, a grand 610 total of 4096 subdirectories can ultimately be created. With 611 1 million files cached, this works out at roughly 245 cached 612 URLs per directory.</p> 613 614 <p>Each URL uses at least two files in the cache-store. Typically 615 there is a ".header" file, which includes meta-information about 616 the URL, such as when it is due to expire and a ".data" file 617 which is a verbatim copy of the content to be served.</p> 618 619 <p>In the case of a content negotiated via the "Vary" header, a 620 ".vary" directory will be created for the URL in question. This 621 directory will have multiple ".data" files corresponding to the 622 differently negotiated content.</p> 623 624 625 <h3>Maintaining the Disk Cache</h3> 626 627 628 <p>Although <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> will remove cached content 629 as it is expired, it does not maintain any information on the total 630 size of the cache or how little free space may be left.</p> 631 632 <p>Instead, provided with Apache is the <a href="programs/htcacheclean.html">htcacheclean</a> tool which, as the name 633 suggests, allows you to clean the cache periodically. Determining 634 how frequently to run <a href="programs/htcacheclean.html">htcacheclean</a> and what target size to 635 use for the cache is somewhat complex and trial and error may be needed to 636 select optimal values.</p> 637 638 <p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of 639 operation. It can be run as persistent daemon, or periodically from 640 cron. <a href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour 641 or more to process very large (tens of gigabytes) caches and if you are 642 running it from cron it is recommended that you determine how long a typical 643 run takes, to avoid running more than one instance at a time.</p> 644 645 <p class="figure"> 646 <img src="images/caching_fig1.gif" alt="" width="600" height="406" /><br /> 647 <a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical 648 cache growth / clean sequence.</p> 649 650 <p>Because <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> does not itself pay attention 651 to how much space is used you should ensure that 652 <a href="programs/htcacheclean.html">htcacheclean</a> is configured to 653 leave enough "grow room" following a clean.</p> 654 655 656 </div></div> 657 <div class="bottomlang"> 658 <p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a> | 659 <a href="./fr/caching.html" hreflang="fr" rel="alternate" title="Français"> fr </a> | 660 <a href="./tr/caching.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p> 661 </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> 662 <script type="text/javascript"><!--//--><![CDATA[//><!-- 663 var comments_shortname = 'httpd'; 664 var comments_identifier = 'http://httpd.apache.org/docs/2.2/caching.html'; 665 (function(w, d) { 666 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 667 d.write('<div id="comments_thread"><\/div>'); 668 var s = d.createElement('script'); 669 s.type = 'text/javascript'; 670 s.async = true; 671 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 672 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 673 } 674 else { 675 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 676 } 677 })(window, document); 678 //--><!]]></script></div><div id="footer"> 679 <p class="apache">Copyright 2017 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 680 <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[//><!-- 681 if (typeof(prettyPrint) !== 'undefined') { 682 prettyPrint(); 683 } 684 //--><!]]></script> 685 </body></html>