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