granicus.if.org Git - apache/blob - docs/manual/mod/mod_cache.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_cache.xml.meta">
  24
  25 <name>mod_cache</name>
  26 <description>RFC 2616 compliant HTTP caching filter.</description>
  27 <status>Extension</status>
  28 <sourcefile>mod_cache.c</sourcefile>
  29 <identifier>cache_module</identifier>
  30
  31 <summary>
  32     <note type="warning">This module should be used with care, as when the
  33     <directive module="mod_cache">CacheQuickHandler</directive> directive is
  34     in its default value of <strong>on</strong>, the <directive
  35     module="mod_authz_host">Allow</directive> and <directive
  36     module="mod_authz_host">Deny</directive> directives will be circumvented.
  37     You should not enable quick handler caching for any content to which you
  38     wish to limit access by client host name, address or environment
  39     variable.</note>
  40
  41     <p><module>mod_cache</module> implements an <a
  42     href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant
  43     <strong>HTTP content caching filter</strong>, with support for the caching
  44     of content negotiated responses containing the Vary header.</p>
  45
  46     <p>RFC 2616 compliant caching provides a mechanism to verify whether
  47     stale or expired content is still fresh, and can represent a significant
  48     performance boost when the origin server supports <strong>conditional
  49     requests</strong> by honouring the
  50     <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a>
  51     HTTP request header. Content is only regenerated from scratch when the content
  52     has changed, and not when the cached entry expires.</p>
  53
  54     <p>As a filter, <module>mod_cache</module> can be placed in front of
  55     content originating from any handler, including <strong>flat
  56     files</strong> (served from a slow disk cached on a fast disk), the output
  57     of a <strong>CGI script</strong> or <strong>dynamic content
  58     generator</strong>, or content <strong>proxied from another
  59     server</strong>.</p>
  60
  61     <p>In the default configuration, <module>mod_cache</module> inserts the
  62     caching filter as far forward as possible within the filter stack,
  63     utilising the <strong>quick handler</strong> to bypass all per request
  64     processing when returning content to the client. In this mode of
  65     operation, <module>mod_cache</module> may be thought of as a caching
  66     proxy server bolted to the front of the webserver, while running within
  67     the webserver itself.</p>
  68
  69     <p>When the quick handler is switched off using the
  70     <directive module="mod_cache">CacheQuickHandler</directive> directive,
  71     it becomes possible to insert the <strong>CACHE</strong> filter at a
  72     point in the filter stack chosen by the administrator. This provides the
  73     opportunity to cache content before that content is personalised by the
  74     <module>mod_include</module> filter, or optionally compressed by the
  75     <module>mod_deflate</module> filter.</p>
  76
  77     <p>Under normal operation, <module>mod_cache</module> will respond to
  78     and can be controlled by the
  79     <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control</a>
  80     and
  81     <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32">Pragma</a>
  82     headers sent from a client in a request, or from a
  83     server within a response. Under exceptional circumstances,
  84     <module>mod_cache</module> can be configured to override these headers
  85     and force site specific behaviour, however such behaviour will be limited
  86     to this cache only, and will not affect the operation of other caches
  87     that may exist between the client and server, and as a result is not
  88     recommended unless strictly necessary.</p>
  89
  90     <p>RFC 2616 allows for the cache to return stale data while the existing
  91     stale entry is refreshed from the origin server, and this is supported
  92     by <module>mod_cache</module> when the
  93     <directive module="mod_cache">CacheLock</directive> directive is suitably
  94     configured. Such responses will contain a
  95     <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
  96     HTTP header with a 110 response code. RFC 2616 also allows a cache to return
  97     stale data when the attempt made to refresh the stale data returns an
  98     error 500 or above, and this behaviour is supported by default by
  99     <module>mod_cache</module>. Such responses will contain a
 100     <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a>
 101     HTTP header with a 111 response code.</p>
 102
 103     <p><module>mod_cache</module> requires the services of one or more
 104     storage management modules. One storage management module is included in
 105     the base Apache distribution:</p>
 106     <dl>
 107     <dt><module>mod_disk_cache</module></dt>
 108     <dd>Implements a disk based storage manager. Headers and bodies are
 109     stored separately on disk, in a directory structure derived from the
 110     md5 hash of the cached URL. Multiple content negotiated responses can
 111     be stored concurrently, however the caching of partial content is not
 112     supported by this module. The <program>htcacheclean</program> tool is
 113     provided to list cached URLs, remove cached URLs, or to maintain the size
 114     of the disk cache within size and inode limits.</dd>
 115     </dl>
 116
 117     <p>Further details, discussion, and examples, are provided in the
 118     <a href="../caching.html">Caching Guide</a>.</p>
 119 </summary>
 120 <seealso><a href="../caching.html">Caching Guide</a></seealso>
 121
 122 <section id="related"><title>Related Modules and Directives</title>
 123     <related>
 124       <modulelist>
 125         <module>mod_disk_cache</module>
 126       </modulelist>
 127       <directivelist>
 128         <directive module="mod_disk_cache">CacheRoot</directive>
 129         <directive module="mod_disk_cache">CacheDirLevels</directive>
 130         <directive module="mod_disk_cache">CacheDirLength</directive>
 131         <directive module="mod_disk_cache">CacheMinFileSize</directive>
 132         <directive module="mod_disk_cache">CacheMaxFileSize</directive>
 133       </directivelist>
 134     </related>
 135 </section>
 136
 137 <section id="sampleconf"><title>Sample Configuration</title>
 138     <example><title>Sample httpd.conf</title>
 139       #<br />
 140       # Sample Cache Configuration<br />
 141       #<br />
 142       LoadModule cache_module modules/mod_cache.so<br />
 143       <br />
 144       &lt;IfModule mod_cache.c&gt;<br />
 145       <indent>
 146         LoadModule disk_cache_module modules/mod_disk_cache.so<br />
 147         &lt;IfModule mod_disk_cache.c&gt;<br />
 148         <indent>
 149           CacheRoot c:/cacheroot<br />
 150           CacheEnable disk  /<br />
 151           CacheDirLevels 5<br />
 152           CacheDirLength 3<br />
 153         </indent>
 154         &lt;/IfModule&gt; <br />
 155         <br />
 156         # When acting as a proxy, don't cache the list of security updates<br />
 157         CacheDisable http://security.update.server/update-list/<br />
 158       </indent>
 159       &lt;/IfModule&gt;
 160     </example>
 161 </section>
 162
 163 <section id="thunderingherd"><title>Avoiding the Thundering Herd</title>
 164   <p>When a cached entry becomes stale, <module>mod_cache</module> will submit
 165   a conditional request to the backend, which is expected to confirm whether the
 166   cached entry is still fresh, and send an updated entity if not.</p>
 167   <p>A small but finite amount of time exists between the time the cached entity
 168   becomes stale, and the time the stale entity is fully refreshed. On a busy
 169   server, a significant number of requests might arrive during this time, and
 170   cause a <strong>thundering herd</strong> of requests to strike the backend
 171   suddenly and unpredicably.</p>
 172   <p>To keep the thundering herd at bay, the <directive>CacheLock</directive>
 173   directive can be used to define a directory in which locks are created for
 174   URLs <strong>in flight</strong>. The lock is used as a <strong>hint</strong>
 175   by other requests to either suppress an attempt to cache (someone else has
 176   gone to fetch the entity), or to indicate that a stale entry is being refreshed
 177   (stale content will be returned in the mean time).
 178   </p>
 179   <section>
 180     <title>Initial caching of an entry</title>
 181     <p>When an entity is cached for the first time, a lock will be created for the
 182     entity until the response has been fully cached. During the lifetime of the
 183     lock, the cache will suppress the second and subsequent attempt to cache the
 184     same entity. While this doesn't hold back the thundering herd, it does stop
 185     the cache attempting to cache the same entity multiple times simultaneously.
 186     </p>
 187   </section>
 188   <section>
 189     <title>Refreshment of a stale entry</title>
 190     <p>When an entity reaches its freshness lifetime and becomes stale, a lock
 191     will be created for the entity until the response has either been confirmed as
 192     still fresh, or replaced by the backend. During the lifetime of the lock, the
 193     second and subsequent incoming request will cause stale data to be returned,
 194     and the thundering herd is kept at bay.</p>
 195   </section>
 196   <section>
 197     <title>Locks and Cache-Control: no-cache</title>
 198     <p>Locks are used as a <strong>hint only</strong> to enable the cache to be
 199     more gentle on backend servers, however the lock can be overridden if necessary.
 200     If the client sends a request with a Cache-Control header forcing a reload, any
 201     lock that may be present will be ignored, and the client's request will be
 202     honored immediately and the cached entry refreshed.</p>
 203     <p>As a further safety mechanism, locks have a configurable maximum age.
 204     Once this age has been reached, the lock is removed, and a new request is
 205     given the opportunity to create a new lock. This maximum age can be set using
 206     the <directive>CacheLockMaxAge</directive> directive, and defaults to 5
 207     seconds.
 208     </p>
 209   </section>
 210   <section>
 211     <title>Example configuration</title>
 212     <example><title>Enabling the cache lock</title>
 213       #<br />
 214       # Enable the cache lock<br />
 215       #<br />
 216       &lt;IfModule mod_cache.c&gt;<br />
 217       <indent>
 218         CacheLock on<br />
 219         CacheLockPath /tmp/mod_cache-lock<br />
 220         CacheLockMaxAge 5<br />
 221       </indent>
 222       &lt;/IfModule&gt;
 223     </example>
 224   </section>
 225 </section>
 226
 227 <section id="finecontrol"><title>Fine Control with the CACHE Filter</title>
 228   <p>Under the default mode of cache operation, the cache runs as a quick handler,
 229   short circuiting the majority of server processing and offering the highest
 230   cache performance available.</p>
 231
 232   <p>In this mode, the cache <strong>bolts onto</strong> the front of the server,
 233   acting as if a free standing RFC 2616 caching proxy had been placed in front of
 234   the server.</p>
 235
 236   <p>While this mode offers the best performance, the administrator may find that
 237   under certain circumstances they may want to perform further processing on the
 238   request after the request is cached, such as to inject personalisation into the
 239   cached page, or to apply authorisation restrictions to the content. Under these
 240   circumstances, an administrator is often forced to place independent reverse
 241   proxy servers either behind or in front of the caching server to achieve this.</p>
 242
 243   <p>To solve this problem the <directive module="mod_cache">CacheQuickHandler
 244   </directive> directive can be set to <strong>off</strong>, and the server will
 245   process all phases normally handled by a non-cached request, including the
 246   <strong>authentication and authorisation</strong> phases.</p>
 247
 248   <p>In addition, the administrator may optionally specify the <strong>precise point
 249   within the filter chain</strong> where caching is to take place by adding the
 250   <strong>CACHE</strong> filter to the output filter chain.</p>
 251
 252   <p>For example, to cache content before applying compression to the response,
 253   place the <strong>CACHE</strong> filter before the <strong>DEFLATE</strong>
 254   filter as in the example below:</p>
 255
 256   <example>
 257     # Cache content before optional compression<br />
 258     CacheQuickHandler off<br />
 259     AddOutputFilterByType CACHE;DEFLATE text/plain<br /><br />
 260   </example>
 261
 262   <p>Another option is to have content cached before personalisation is applied
 263   by <module>mod_include</module> (or another content processing filter). In this
 264   example templates containing tags understood by
 265   <module>mod_include</module> are cached before being parsed:</p>
 266
 267   <example>
 268     # Cache content before mod_include and mod_deflate<br />
 269     CacheQuickHandler off<br />
 270     AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html<br /><br />
 271   </example>
 272
 273   <p>You may place the <strong>CACHE</strong> filter anywhere you wish within the
 274   filter chain. In this example, content is cached after being parsed by
 275   <module>mod_include</module>, but before being processed by
 276   <module>mod_deflate</module>:</p>
 277
 278   <example>
 279     # Cache content between mod_include and mod_deflate<br />
 280     CacheQuickHandler off<br />
 281     AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html<br /><br />
 282   </example>
 283
 284   <note type="warning"><title>Warning:</title>If the location of the
 285   <strong>CACHE</strong> filter in the filter chain is changed for any reason,
 286   you may need to <strong>flush your cache</strong> to ensure that your data
 287   served remains consistent. <module>mod_cache</module> is not in a position
 288   to enforce this for you.</note>
 289
 290 </section>
 291
 292 <section id="status"><title>Cache Status and Logging</title>
 293   <p>Once <module>mod_cache</module> has made a decision as to whether or not
 294   an entity is to be served from cache, the detailed reason for the decision
 295   is written to the subprocess environment within the request under the
 296   <strong>cache-status</strong> key. This reason can be logged by the
 297   <directive module="mod_log_config">LogFormat</directive> directive as
 298   follows:</p>
 299
 300   <example>
 301     LogFormat "%{cache-status}e ..."
 302   </example>
 303
 304   <p>Based on the caching decision made, the reason is also written to the
 305   subprocess environment under one the following three keys, as appropriate:</p>
 306
 307   <dl>
 308     <dt>cache-hit</dt><dd>The response was served from cache.</dd>
 309     <dt>cache-revalidate</dt><dd>The response was stale and was successfully
 310       revalidated, then served from cache.</dd>
 311     <dt>cache-miss</dt><dd>The response was served from the upstream server.</dd>
 312   </dl>
 313
 314   <p>This makes it possible to support conditional logging of cached requests
 315   as per the following example:</p>
 316
 317   <example>
 318     CustomLog cached-requests.log common env=cache-hit<br />
 319     CustomLog uncached-requests.log common env=cache-miss<br />
 320     CustomLog revalidated-requests.log common env=cache-revalidate<br />
 321   </example>
 322
 323 </section>
 324
 325 <directivesynopsis>
 326 <name>CacheEnable</name>
 327 <description>Enable caching of specified URLs using a specified storage
 328 manager</description>
 329 <syntax>CacheEnable <var>cache_type</var> <var>url-string</var></syntax>
 330 <contextlist><context>server config</context><context>virtual host</context>
 331 </contextlist>
 332
 333 <usage>
 334     <p>The <directive>CacheEnable</directive> directive instructs
 335     <module>mod_cache</module> to cache urls at or below
 336     <var>url-string</var>. The cache storage manager is specified with the
 337     <var>cache_type</var> argument. If the <directive>CacheEnable</directive>
 338     directive is placed inside a <directive type="section">Location</directive>
 339     directive, the <var>url-string</var> becomes optional.
 340     <var>cache_type</var> <code>disk</code> instructs
 341     <module>mod_cache</module> to use the disk based storage manager
 342     implemented by <module>mod_disk_cache</module>.</p>
 343     <p>In the event that the URL space overlaps between different
 344     <directive>CacheEnable</directive> directives (as in the example below),
 345     each possible storage manager will be run until the first one that
 346     actually processes the request. The order in which the storage managers are
 347     run is determined by the order of the <directive>CacheEnable</directive>
 348     directives in the configuration file.</p>
 349
 350     <p>When acting as a forward proxy server, <var>url-string</var> can
 351     also be used to specify remote sites and proxy protocols which
 352     caching should be enabled for.</p>
 353
 354     <example>
 355       # Cache proxied url's<br />
 356       CacheEnable  disk  /<br /><br />
 357       # Cache FTP-proxied url's<br />
 358       CacheEnable  disk  ftp://<br /><br />
 359       # Cache content from www.apache.org<br />
 360       CacheEnable  disk  http://www.apache.org/<br />
 361     </example>
 362
 363     <p>A hostname starting with a <strong>"*"</strong> matches all hostnames with
 364     that suffix. A hostname starting with <strong>"."</strong> matches all
 365     hostnames containing the domain components that follow.</p>
 366
 367     <example>
 368       # Match www.apache.org, and fooapache.org<br />
 369       CacheEnable  disk  http://*apache.org/<br />
 370       # Match www.apache.org, but not fooapache.org<br />
 371       CacheEnable  disk  http://.apache.org/<br />
 372     </example>
 373
 374     <p> The <code>no-cache</code> environment variable can be set to
 375     disable caching on a finer grained set of resources in versions
 376     2.2.12 and later.</p>
 377
 378 </usage>
 379 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 380 </directivesynopsis>
 381
 382 <directivesynopsis>
 383 <name>CacheDisable</name>
 384 <description>Disable caching of specified URLs</description>
 385 <syntax>CacheDisable <var>url-string</var> | <var>on</var></syntax>
 386 <contextlist><context>server config</context><context>virtual host</context>
 387 </contextlist>
 388
 389 <usage>
 390     <p>The <directive>CacheDisable</directive> directive instructs
 391     <module>mod_cache</module> to <em>not</em> cache urls at or below
 392     <var>url-string</var>.</p>
 393
 394     <example><title>Example</title>
 395       CacheDisable /local_files
 396     </example>
 397
 398     <p>If used in a <directive type="section">Location</directive> directive,
 399     the path needs to be specified below the Location, or if the word "on"
 400     is used, caching for the whole location will be disabled.</p>
 401
 402     <example><title>Example</title>
 403       &lt;Location /foo&gt;<br />
 404         CacheDisable on<br />
 405       &lt;/Location&gt;<br />
 406     </example>
 407
 408     <p> The <code>no-cache</code> environment variable can be set to
 409     disable caching on a finer grained set of resources in versions
 410     2.2.12 and later.</p>
 411
 412 </usage>
 413 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 414 </directivesynopsis>
 415 <directivesynopsis>
 416 <name>CacheMaxExpire</name>
 417 <description>The maximum time in seconds to cache a document</description>
 418 <syntax>CacheMaxExpire <var>seconds</var></syntax>
 419 <default>CacheMaxExpire 86400 (one day)</default>
 420 <contextlist><context>server config</context>
 421     <context>virtual host</context>
 422     <context>directory</context>
 423     <context>.htaccess</context>
 424 </contextlist>
 425
 426 <usage>
 427     <p>The <directive>CacheMaxExpire</directive> directive specifies the maximum number of
 428     seconds for which cachable HTTP documents will be retained without checking the origin
 429     server. Thus, documents will be out of date at most this number of seconds. This maximum
 430     value is enforced even if an expiry date was supplied with the document.</p>
 431
 432     <example>
 433       CacheMaxExpire 604800
 434     </example>
 435 </usage>
 436 </directivesynopsis>
 437
 438 <directivesynopsis>
 439 <name>CacheMinExpire</name>
 440 <description>The minimum time in seconds to cache a document</description>
 441 <syntax>CacheMinExpire <var>seconds</var></syntax>
 442 <default>CacheMinExpire 0</default>
 443 <contextlist><context>server config</context>
 444   <context>virtual host</context>
 445   <context>directory</context>
 446   <context>.htaccess</context>
 447 </contextlist>
 448
 449 <usage>
 450     <p>The <directive>CacheMinExpire</directive> directive specifies the minimum number of
 451     seconds for which cachable HTTP documents will be retained without checking the origin
 452     server. This is only used if no valid expire time was supplied with the document.</p>
 453
 454
 455     <example>
 456       CacheMinExpire 3600
 457     </example>
 458 </usage>
 459 </directivesynopsis>
 460
 461 <directivesynopsis>
 462 <name>CacheDefaultExpire</name>
 463 <description>The default duration to cache a document when no expiry date is specified.</description>
 464 <syntax>CacheDefaultExpire <var>seconds</var></syntax>
 465 <default>CacheDefaultExpire 3600 (one hour)</default>
 466 <contextlist><context>server config</context>
 467   <context>virtual host</context>
 468   <context>directory</context>
 469   <context>.htaccess</context>
 470 </contextlist>
 471
 472 <usage>
 473     <p>The <directive>CacheDefaultExpire</directive> directive specifies a default time,
 474     in seconds, to cache a document if neither an expiry date nor last-modified date are provided
 475     with the document. The value specified with the <directive>CacheMaxExpire</directive>
 476     directive does <em>not</em> override this setting.</p>
 477
 478     <example>
 479       CacheDefaultExpire 86400
 480     </example>
 481 </usage>
 482 </directivesynopsis>
 483
 484 <directivesynopsis>
 485 <name>CacheIgnoreNoLastMod</name>
 486 <description>Ignore the fact that a response has no Last Modified
 487 header.</description>
 488 <syntax>CacheIgnoreNoLastMod On|Off</syntax>
 489 <default>CacheIgnoreNoLastMod Off</default>
 490 <contextlist><context>server config</context>
 491   <context>virtual host</context>
 492   <context>directory</context>
 493   <context>.htaccess</context>
 494 </contextlist>
 495
 496 <usage>
 497     <p>Ordinarily, documents without a last-modified date are not cached.
 498     Under some circumstances the last-modified date is removed (during
 499     <module>mod_include</module> processing for example) or not provided
 500     at all. The <directive>CacheIgnoreNoLastMod</directive> directive
 501     provides a way to specify that documents without last-modified dates
 502     should be considered for caching, even without a last-modified date.
 503     If neither a last-modified date nor an expiry date are provided with
 504     the document then the value specified by the
 505     <directive>CacheDefaultExpire</directive> directive will be used to
 506     generate an expiration date.</p>
 507
 508     <example>
 509       CacheIgnoreNoLastMod On
 510     </example>
 511 </usage>
 512 </directivesynopsis>
 513
 514 <directivesynopsis>
 515 <name>CacheIgnoreCacheControl</name>
 516 <description>Ignore request to not serve cached content to client</description>
 517 <syntax>CacheIgnoreCacheControl On|Off</syntax>
 518 <default>CacheIgnoreCacheControl Off</default>
 519 <contextlist><context>server config</context><context>virtual host</context>
 520 </contextlist>
 521
 522 <usage>
 523     <p>Ordinarily, requests containing a Cache-Control: no-cache or
 524     Pragma: no-cache header value will not be served from the cache.  The
 525     <directive>CacheIgnoreCacheControl</directive> directive allows this
 526     behavior to be overridden.  <directive>CacheIgnoreCacheControl On</directive>
 527     tells the server to attempt to serve the resource from the cache even
 528     if the request contains no-cache header values.  Resources requiring
 529     authorization will <em>never</em> be cached.</p>
 530
 531     <example>
 532       CacheIgnoreCacheControl On
 533     </example>
 534
 535     <note type="warning"><title>Warning:</title>
 536        This directive will allow serving from the cache even if the client has
 537        requested that the document not be served from the cache.  This might
 538        result in stale content being served.
 539     </note>
 540 </usage>
 541 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
 542 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 543 </directivesynopsis>
 544
 545 <directivesynopsis>
 546 <name>CacheIgnoreQueryString</name>
 547 <description>Ignore query string when caching</description>
 548 <syntax>CacheIgnoreQueryString On|Off</syntax>
 549 <default>CacheIgnoreQueryString Off</default>
 550 <contextlist><context>server config</context><context>virtual host</context>
 551 </contextlist>
 552
 553 <usage>
 554     <p>Ordinarily, requests with query string parameters are cached separately
 555     for each unique query string. This is according to RFC 2616/13.9 done only
 556     if an expiration time is specified. The
 557     <directive>CacheIgnoreQueryString</directive> directive tells the cache to
 558     cache requests even if no expiration time is specified, and to reply with
 559     a cached reply even if the query string differs. From a caching point of
 560     view the request is treated as if having no query string when this
 561     directive is enabled.</p>
 562
 563     <example>
 564       CacheIgnoreQueryString On
 565     </example>
 566
 567 </usage>
 568 </directivesynopsis>
 569
 570 <directivesynopsis>
 571 <name>CacheLastModifiedFactor</name>
 572 <description>The factor used to compute an expiry date based on the
 573 LastModified date.</description>
 574 <syntax>CacheLastModifiedFactor <var>float</var></syntax>
 575 <default>CacheLastModifiedFactor 0.1</default>
 576 <contextlist><context>server config</context>
 577   <context>virtual host</context>
 578   <context>directory</context>
 579   <context>.htaccess</context>
 580 </contextlist>
 581
 582 <usage>
 583     <p>In the event that a document does not provide an expiry date but does
 584     provide a last-modified date, an expiry date can be calculated based on
 585     the time since the document was last modified. The
 586     <directive>CacheLastModifiedFactor</directive> directive specifies a
 587     <var>factor</var> to be used in the generation of this expiry date
 588     according to the following formula:
 589
 590     <code>expiry-period = time-since-last-modified-date * <var>factor</var>
 591     expiry-date = current-date + expiry-period</code>
 592
 593     For example, if the document was last modified 10 hours ago, and
 594     <var>factor</var> is 0.1 then the expiry-period will be set to
 595     10*0.1 = 1 hour. If the current time was 3:00pm then the computed
 596     expiry-date would be 3:00pm + 1hour = 4:00pm.
 597
 598     If the expiry-period would be longer than that set by
 599     <directive>CacheMaxExpire</directive>, then the latter takes
 600     precedence.</p>
 601
 602     <example>
 603       CacheLastModifiedFactor 0.5
 604     </example>
 605 </usage>
 606 </directivesynopsis>
 607
 608 <directivesynopsis>
 609 <name>CacheIgnoreHeaders</name>
 610 <description>Do not store the given HTTP header(s) in the cache.
 611 </description>
 612 <syntax>CacheIgnoreHeaders <var>header-string</var> [<var>header-string</var>] ...</syntax>
 613 <default>CacheIgnoreHeaders None</default>
 614 <contextlist><context>server config</context><context>virtual host</context>
 615 </contextlist>
 616
 617 <usage>
 618     <p>According to RFC 2616, hop-by-hop HTTP headers are not stored in
 619     the cache.  The following HTTP headers are hop-by-hop headers and thus
 620     do not get stored in the cache in <em>any</em> case regardless of the
 621     setting of <directive>CacheIgnoreHeaders</directive>:</p>
 622
 623     <ul>
 624       <li><code>Connection</code></li>
 625       <li><code>Keep-Alive</code></li>
 626       <li><code>Proxy-Authenticate</code></li>
 627       <li><code>Proxy-Authorization</code></li>
 628       <li><code>TE</code></li>
 629       <li><code>Trailers</code></li>
 630       <li><code>Transfer-Encoding</code></li>
 631       <li><code>Upgrade</code></li>
 632     </ul>
 633
 634     <p><directive>CacheIgnoreHeaders</directive> specifies additional HTTP
 635     headers that should not to be stored in the cache.  For example, it makes
 636     sense in some cases to prevent cookies from being stored in the cache.</p>
 637
 638     <p><directive>CacheIgnoreHeaders</directive> takes a space separated list
 639     of HTTP headers that should not be stored in the cache. If only hop-by-hop
 640     headers not should be stored in the cache (the RFC 2616 compliant
 641     behaviour), <directive>CacheIgnoreHeaders</directive> can be set to
 642     <code>None</code>.</p>
 643
 644     <example><title>Example 1</title>
 645       CacheIgnoreHeaders Set-Cookie
 646     </example>
 647
 648     <example><title>Example 2</title>
 649       CacheIgnoreHeaders None
 650     </example>
 651
 652     <note type="warning"><title>Warning:</title>
 653       If headers like <code>Expires</code> which are needed for proper cache
 654       management are not stored due to a
 655       <directive>CacheIgnoreHeaders</directive> setting, the behaviour of
 656       mod_cache is undefined.
 657     </note>
 658 </usage>
 659 </directivesynopsis>
 660
 661 <directivesynopsis>
 662 <name>CacheIgnoreURLSessionIdentifiers</name>
 663 <description>Ignore defined session identifiers encoded in the URL when caching
 664 </description>
 665 <syntax>CacheIgnoreURLSessionIdentifiers <var>identifier</var> [<var>identifier</var>] ...</syntax>
 666 <default>CacheIgnoreURLSessionIdentifiers None</default>
 667 <contextlist><context>server config</context><context>virtual host</context>
 668 </contextlist>
 669
 670 <usage>
 671     <p>Sometimes applications encode the session identifier into the URL like in the following
 672     Examples:
 673     </p>
 674     <ul>
 675       <li><code>/someapplication/image.gif;jsessionid=123456789</code></li>
 676       <li><code>/someapplication/image.gif?PHPSESSIONID=12345678</code></li>
 677     </ul>
 678     <p>This causes cachable resources to be stored separately for each session, which
 679     is often not desired. <directive>CacheIgnoreURLSessionIdentifiers</directive> lets
 680     define a list of identifiers that are removed from the key that is used to identify
 681     an entity in the cache, such that cachable resources are not stored separately for
 682     each session.
 683     </p>
 684     <p><code>CacheIgnoreURLSessionIdentifiers None</code> clears the list of ignored
 685     identifiers. Otherwise, each identifier is added to the list.</p>
 686
 687     <example><title>Example 1</title>
 688       CacheIgnoreURLSessionIdentifiers jsessionid
 689     </example>
 690
 691     <example><title>Example 2</title>
 692       CacheIgnoreURLSessionIdentifiers None
 693     </example>
 694
 695 </usage>
 696 </directivesynopsis>
 697
 698 <directivesynopsis>
 699 <name>CacheStoreExpired</name>
 700 <description>Attempt to cache responses that the server reports as expired</description>
 701 <syntax>CacheStoreExpired On|Off</syntax>
 702 <default>CacheStoreExpired Off</default>
 703 <contextlist><context>server config</context>
 704   <context>virtual host</context>
 705   <context>directory</context>
 706   <context>.htaccess</context>
 707 </contextlist>
 708
 709 <usage>
 710     <p>Since httpd 2.2.4, responses which have already expired are not
 711        stored in the cache.  The <directive>CacheStoreExpired</directive>
 712        directive allows this behavior to be overridden.
 713        <directive>CacheStoreExpired</directive> On
 714        tells the server to attempt to cache the resource if it is stale.
 715        Subsequent requests would trigger an If-Modified-Since request of
 716        the origin server, and the response may be fulfilled from cache
 717        if the backend resource has not changed.</p>
 718
 719     <example>
 720       CacheStoreExpired On
 721     </example>
 722 </usage>
 723 </directivesynopsis>
 724
 725 <directivesynopsis>
 726 <name>CacheStorePrivate</name>
 727 <description>Attempt to cache responses that the server has marked as private</description>
 728 <syntax>CacheStorePrivate On|Off</syntax>
 729 <default>CacheStorePrivate Off</default>
 730 <contextlist><context>server config</context>
 731   <context>virtual host</context>
 732   <context>directory</context>
 733   <context>.htaccess</context>
 734 </contextlist>
 735
 736 <usage>
 737     <p>Ordinarily, responses with Cache-Control: private header values will not
 738        be stored in the cache.  The <directive>CacheStorePrivate</directive>
 739        directive allows this behavior to be overridden.
 740        <directive>CacheStorePrivate</directive> On
 741        tells the server to attempt to cache the resource even if it contains
 742        private header values.  Resources requiring authorization will
 743        <em>never</em> be cached.</p>
 744
 745     <example>
 746       CacheStorePrivate On
 747     </example>
 748
 749     <note type="warning"><title>Warning:</title>
 750        This directive will allow caching even if the upstream server has
 751        requested that the resource not be cached.  This directive is only
 752        ideal for a 'private' cache.
 753     </note>
 754 </usage>
 755 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
 756 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 757 </directivesynopsis>
 758
 759 <directivesynopsis>
 760 <name>CacheStoreNoStore</name>
 761 <description>Attempt to cache requests or responses that have been marked as no-store.</description>
 762 <syntax>CacheStoreNoStore On|Off</syntax>
 763 <default>CacheStoreNoStore Off</default>
 764 <contextlist><context>server config</context>
 765   <context>virtual host</context>
 766   <context>directory</context>
 767   <context>.htaccess</context>
 768 </contextlist>
 769
 770 <usage>
 771     <p>Ordinarily, requests or responses with Cache-Control: no-store header
 772        values will not be stored in the cache.  The
 773        <directive>CacheStoreNoCache</directive> directive allows this
 774        behavior to be overridden.  <directive>CacheStoreNoCache</directive> On
 775        tells the server to attempt to cache the resource even if it contains
 776        no-store header values.  Resources requiring authorization will
 777        <em>never</em> be cached.</p>
 778
 779     <example>
 780       CacheStoreNoStore On
 781     </example>
 782
 783     <note type="warning"><title>Warning:</title>
 784        As described in RFC 2616, the no-store directive is intended to
 785        "prevent the inadvertent release or retention of sensitive information
 786        (for example, on backup tapes)."  Enabling this option could store
 787        sensitive information in the cache.  You are hereby warned.
 788     </note>
 789 </usage>
 790 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
 791 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
 792 </directivesynopsis>
 793
 794 <directivesynopsis>
 795 <name>CacheLock</name>
 796 <description>Enable the thundering herd lock.</description>
 797 <syntax>CacheLock <var>on|off</var></syntax>
 798 <default>CacheLock off</default>
 799 <contextlist><context>server config</context><context>virtual host</context>
 800 </contextlist>
 801 <compatibility>Available in Apache 2.2.15 and later</compatibility>
 802
 803 <usage>
 804   <p>The <directive>CacheLock</directive> directive enables the thundering herd lock
 805   for the given URL space.</p>
 806
 807   <p>In a minimal configuration the following directive is all that is needed to
 808   enable the thundering herd lock in the default system temp directory.</p>
 809
 810   <example>
 811     # Enable cache lock<br />
 812     CacheLock on<br /><br />
 813   </example>
 814
 815 </usage>
 816 </directivesynopsis>
 817
 818 <directivesynopsis>
 819 <name>CacheLockPath</name>
 820 <description>Set the lock path directory.</description>
 821 <syntax>CacheLockPath <var>directory</var></syntax>
 822 <default>CacheLockPath /tmp/mod_cache-lock</default>
 823 <contextlist><context>server config</context><context>virtual host</context>
 824 </contextlist>
 825
 826 <usage>
 827   <p>The <directive>CacheLockPath</directive> directive allows you to specify the
 828   directory in which the locks are created. By default, the system's temporary
 829   folder is used. Locks consist of empty files that only exist for stale URLs
 830   in flight, so is significantly less resource intensive than the traditional
 831   disk cache.</p>
 832
 833 </usage>
 834 </directivesynopsis>
 835
 836 <directivesynopsis>
 837 <name>CacheLockMaxAge</name>
 838 <description>Set the maximum possible age of a cache lock.</description>
 839 <syntax>CacheLockMaxAge <var>integer</var></syntax>
 840 <default>CacheLockMaxAge 5</default>
 841 <contextlist><context>server config</context><context>virtual host</context>
 842 </contextlist>
 843
 844 <usage>
 845   <p>The <directive>CacheLockMaxAge</directive> directive specifies the maximum
 846   age of any cache lock.</p>
 847
 848   <p>A lock older than this value in seconds will be ignored, and the next
 849   incoming request will be given the opportunity to re-establish the lock.
 850   This mechanism prevents a slow client taking an excessively long time to refresh
 851   an entity.</p>
 852
 853 </usage>
 854 </directivesynopsis>
 855
 856 <directivesynopsis>
 857   <name>CacheQuickHandler</name>
 858   <description>Run the cache from the quick handler.</description>
 859   <syntax>CacheQuickHandler <var>on|off</var></syntax>
 860   <default>CacheQuickHandler on</default>
 861   <contextlist><context>server config</context><context>virtual host</context>
 862   </contextlist>
 863
 864   <usage>
 865     <p>The <directive module="mod_cache">CacheQuickHandler</directive> directive
 866     controls the phase in which the cache is handled.</p>
 867
 868     <p>In the default enabled configuration, the cache operates within the quick
 869     handler phase. This phase short circuits the majority of server processing,
 870     and represents the most performant mode of operation for a typical server.
 871     The cache <strong>bolts onto</strong> the front of the server, and the
 872     majority of server processing is avoided.</p>
 873
 874     <p>When disabled, the cache operates as a normal handler, and is subject to
 875     the full set of phases when handling a server request. While this mode is
 876     slower than the default, it allows the cache to be used in cases where full
 877     processing is required, such as when content is subject to authorisation.</p>
 878
 879     <example>
 880       # Run cache as a normal handler<br />
 881       CacheQuickHandler off<br /><br />
 882     </example>
 883
 884     <p>It is also possible, when the quick handler is disabled, for the
 885     administrator to choose the precise location within the filter chain where
 886     caching is to be performed, by adding the <strong>CACHE</strong> filter to
 887     the chain.</p>
 888
 889     <example>
 890       # Cache content before mod_include and mod_deflate<br />
 891       CacheQuickHandler off<br />
 892       AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html<br /><br />
 893     </example>
 894
 895     <p>If the CACHE filter is specified more than once, the last instance will
 896     apply.</p>
 897
 898   </usage>
 899 </directivesynopsis>
 900
 901 <directivesynopsis>
 902 <name>CacheHeader</name>
 903 <description>Add an X-Cache header to the response.</description>
 904 <syntax>CacheHeader <var>on|off</var></syntax>
 905 <default>CacheHeader off</default>
 906 <contextlist><context>server config</context>
 907     <context>virtual host</context>
 908     <context>directory</context>
 909     <context>.htaccess</context>
 910 </contextlist>
 911 <compatibility>Available in Apache 2.3.9 and later</compatibility>
 912
 913 <usage>
 914   <p>When the <directive module="mod_cache">CacheHeader</directive> directive
 915   is switched on, an <strong>X-Cache</strong> header will be added to the response
 916   with the cache status of this response. If the normal handler is used, this
 917   directive may appear within a <directive module="core">&lt;Directory&gt;</directive>
 918   or <directive module="core">&lt;Location&gt;</directive> directive. If the quick
 919   handler is used, this directive must appear within a server or virtual host
 920   context, otherwise the setting will be ignored.</p>
 921
 922   <dl>
 923     <dt><strong>HIT</strong></dt><dd>The entity was fresh, and was served from
 924     cache.</dd>
 925     <dt><strong>REVALIDATE</strong></dt><dd>The entity was stale, was successfully
 926     revalidated and was served from cache.</dd>
 927     <dt><strong>MISS</strong></dt><dd>The entity was fetched from the upstream
 928       server and was not served from cache.</dd>
 929   </dl>
 930
 931   <example>
 932     # Enable the X-Cache header<br />
 933     CacheHeader on<br />
 934   </example>
 935
 936   <example>
 937     X-Cache: HIT from localhost<br />
 938   </example>
 939
 940 </usage>
 941 </directivesynopsis>
 942
 943 <directivesynopsis>
 944 <name>CacheDetailHeader</name>
 945 <description>Add an X-Cache-Detail header to the response.</description>
 946 <syntax>CacheDetailHeader <var>on|off</var></syntax>
 947 <default>CacheDetailHeader off</default>
 948 <contextlist><context>server config</context>
 949       <context>virtual host</context>
 950       <context>directory</context>
 951       <context>.htaccess</context>
 952 </contextlist>
 953 <compatibility>Available in Apache 2.3.9 and later</compatibility>
 954
 955 <usage>
 956   <p>When the <directive module="mod_cache">CacheDetailHeader</directive> directive
 957   is switched on, an <strong>X-Cache-Detail</strong> header will be added to the response
 958   containing the detailed reason for a particular caching decision.</p>
 959
 960   <p>It can be useful during development of cached RESTful services to have additional
 961   information about the caching decision written to the response headers, so as to
 962   confirm whether <code>Cache-Control</code> and other headers have been correctly
 963   used by the service and client.</p>
 964
 965   <p>If the normal handler is used, this directive may appear within a
 966   <directive module="core">&lt;Directory&gt;</directive> or
 967   <directive module="core">&lt;Location&gt;</directive> directive. If the quick handler
 968   is used, this directive must appear within a server or virtual host context, otherwise
 969   the setting will be ignored.</p>
 970
 971   <example>
 972     # Enable the X-Cache-Detail header<br />
 973     CacheDetailHeader on<br />
 974   </example>
 975
 976   <example>
 977     X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost<br />
 978   </example>
 979
 980 </usage>
 981 </directivesynopsis>
 982
 983 <directivesynopsis>
 984 <name>CacheKeyBaseURL</name>
 985 <description>Override the base URL of reverse proxied cache keys.</description>
 986 <syntax>CacheKeyBaseURL <var>URL</var></syntax>
 987 <default>CacheKeyBaseURL http://example.com</default>
 988 <contextlist><context>server config</context>
 989 <context>virtual host</context>
 990 </contextlist>
 991 <compatibility>Available in Apache 2.3.9 and later</compatibility>
 992
 993 <usage>
 994   <p>When the <directive module="mod_cache">CacheKeyBaseURL</directive> directive
 995   is specified, the URL provided will be used as the base URL to calculate
 996   the URL of the cache keys in the reverse proxy configuration. When not specified,
 997   the scheme, hostname and port of the current virtual host is used to construct
 998   the cache key. When a cluster of machines is present, and all cached entries
 999   should be cached beneath the same cache key, a new base URL can be specified
1000   with this directive.</p>
1001
1002   <example>
1003     # Override the base URL of the cache key.<br />
1004     CacheKeyBaseURL http://www.example.com/<br />
1005   </example>
1006
1007   <note type="warning">Take care when setting this directive. If two separate virtual
1008   hosts are accidentally given the same base URL, entries from one virtual host
1009   will be served to the other.</note>
1010
1011 </usage>
1012 </directivesynopsis>
1013
1014 <directivesynopsis>
1015 <name>CacheStaleOnError</name>
1016 <description>Serve stale content in place of 5xx responses.</description>
1017 <syntax>CacheStaleOnError <var>on|off</var></syntax>
1018 <default>CacheStaleOnError on</default>
1019 <contextlist><context>server config</context>
1020     <context>virtual host</context>
1021     <context>directory</context>
1022     <context>.htaccess</context>
1023 </contextlist>
1024 <compatibility>Available in Apache 2.3.9 and later</compatibility>
1025
1026 <usage>
1027   <p>When the <directive module="mod_cache">CacheStaleOnError</directive> directive
1028   is switched on, and when stale data is available in the cache, the cache will
1029   respond to 5xx responses from the backend by returning the stale data instead of
1030   the 5xx response. While the Cache-Control headers sent by clients will be respected,
1031   and the raw 5xx responses returned to the client on request, the 5xx response so
1032   returned to the client will not invalidate the content in the cache.</p>
1033
1034   <example>
1035     # Serve stale data on error.<br />
1036     CacheStaleOnError on<br />
1037   </example>
1038
1039 </usage>
1040 </directivesynopsis>
1041
1042 </modulesynopsis>