granicus.if.org Git - apache/blob - docs/manual/caching.html.en

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