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. One storage management module is 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 authorisation 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 authorisation</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><context>.htaccess</context>
 348 </contextlist>
 349
 350 <usage>
 351     <p>The <directive>CacheEnable</directive> directive instructs
 352     <module>mod_cache</module> to cache urls at or below
 353     <var>url-string</var>. The cache storage manager is specified with the
 354     <var>cache_type</var> argument. The <directive>CacheEnable</directive>
 355     directive can alternatively be placed inside either
 356     <directive type="section">Location</directive> or
 357     <directive type="section">LocationMatch</directive> sections to indicate
 358     the content is cacheable.
 359     <var>cache_type</var> <code>disk</code> instructs
 360     <module>mod_cache</module> to use the disk based storage manager
 361     implemented by <module>mod_cache_disk</module>. <var>cache_type</var>
 362     <code>socache</code> instructs <module>mod_cache</module> to use the
 363     shared object cache based storage manager implemented by
 364     <module>mod_cache_socache</module>.</p>
 365     <p>In the event that the URL space overlaps between different
 366     <directive>CacheEnable</directive> directives (as in the example below),
 367     each possible storage manager will be run until the first one that
 368     actually processes the request. The order in which the storage managers are
 369     run is determined by the order of the <directive>CacheEnable</directive>
 370     directives in the configuration file. <directive>CacheEnable</directive>
 371     directives within <directive type="section">Location</directive> or
 372     <directive type="section">LocationMatch</directive> sections are processed
 373     before globally defined <directive>CacheEnable</directive> directives.</p>
 374
 375     <p>When acting as a forward proxy server, <var>url-string</var> can
 376     also be used to specify remote sites and proxy protocols which
 377     caching should be enabled for.</p>
 378
 379     <highlight language="config">
 380 # Cache content
 381 &lt;Location /foo&gt;
 382     CacheEnable disk
 383 &lt;/Location&gt;
 384
 385 # Cache regex
 386 &lt;LocationMatch foo$&gt;
 387     CacheEnable disk
 388 &lt;/LocationMatch&gt;
 389
 390 # Cache proxied url's
 391 CacheEnable  disk  /
 392
 393 # Cache FTP-proxied url's
 394 CacheEnable  disk  ftp://
 395
 396 # Cache content from www.example.org
 397 CacheEnable  disk  http://www.example.org/
 398     </highlight>
 399
 400     <p>A hostname starting with a <strong>"*"</strong> matches all hostnames with
 401     that suffix. A hostname starting with <strong>"."</strong> matches all
 402     hostnames containing the domain components that follow.</p>
 403
 404     <highlight language="config">
 405 # Match www.example.org, and fooexample.org
 406 CacheEnable  disk  http://*example.org/
 407 # Match www.example.org, but not fooexample.org
 408 CacheEnable  disk  http://.example.org/
 409     </highlight>
 410
 411     <p> The <code>no-cache</code> environment variable can be set to
 412     disable caching on a finer grained set of resources in versions
 413     2.2.12 and later.</p>
 414
 415 </usage>
 416 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 417 </directivesynopsis>
 418
 419 <directivesynopsis>
 420 <name>CacheDisable</name>
 421 <description>Disable caching of specified URLs</description>
 422 <syntax>CacheDisable <var>url-string</var> | <var>on</var></syntax>
 423 <contextlist><context>server config</context><context>virtual host</context>
 424 <context>directory</context><context>.htaccess</context>
 425 </contextlist>
 426
 427 <usage>
 428     <p>The <directive>CacheDisable</directive> directive instructs
 429     <module>mod_cache</module> to <em>not</em> cache urls at or below
 430     <var>url-string</var>.</p>
 431
 432     <example><title>Example</title>
 433     <highlight language="config">
 434       CacheDisable /local_files
 435       </highlight>
 436     </example>
 437
 438     <p>If used in a <directive type="section">Location</directive> directive,
 439     the path needs to be specified below the Location, or if the word "on"
 440     is used, caching for the whole location will be disabled.</p>
 441
 442     <example><title>Example</title>
 443     <highlight language="config">
 444 &lt;Location /foo&gt;
 445     CacheDisable on
 446 &lt;/Location&gt;
 447       </highlight>
 448     </example>
 449
 450     <p>The <code>no-cache</code> environment variable can be set to
 451     disable caching on a finer grained set of resources in versions
 452     2.2.12 and later.</p>
 453
 454 </usage>
 455 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 456 </directivesynopsis>
 457 <directivesynopsis>
 458 <name>CacheMaxExpire</name>
 459 <description>The maximum time in seconds to cache a document</description>
 460 <syntax>CacheMaxExpire <var>seconds</var></syntax>
 461 <default>CacheMaxExpire 86400 (one day)</default>
 462 <contextlist><context>server config</context>
 463     <context>virtual host</context>
 464     <context>directory</context>
 465     <context>.htaccess</context>
 466 </contextlist>
 467
 468 <usage>
 469     <p>The <directive>CacheMaxExpire</directive> directive specifies the maximum number of
 470     seconds for which cachable HTTP documents will be retained without checking the origin
 471     server. Thus, documents will be out of date at most this number of seconds. This maximum
 472     value is enforced even if an expiry date was supplied with the document.</p>
 473
 474     <highlight language="config">
 475       CacheMaxExpire 604800
 476     </highlight>
 477 </usage>
 478 </directivesynopsis>
 479
 480 <directivesynopsis>
 481 <name>CacheMinExpire</name>
 482 <description>The minimum time in seconds to cache a document</description>
 483 <syntax>CacheMinExpire <var>seconds</var></syntax>
 484 <default>CacheMinExpire 0</default>
 485 <contextlist><context>server config</context>
 486   <context>virtual host</context>
 487   <context>directory</context>
 488   <context>.htaccess</context>
 489 </contextlist>
 490
 491 <usage>
 492     <p>The <directive>CacheMinExpire</directive> directive specifies the minimum number of
 493     seconds for which cachable HTTP documents will be retained without checking the origin
 494     server. This is only used if no valid expire time was supplied with the document.</p>
 495
 496
 497     <highlight language="config">
 498       CacheMinExpire 3600
 499     </highlight>
 500 </usage>
 501 </directivesynopsis>
 502
 503 <directivesynopsis>
 504 <name>CacheDefaultExpire</name>
 505 <description>The default duration to cache a document when no expiry date is specified.</description>
 506 <syntax>CacheDefaultExpire <var>seconds</var></syntax>
 507 <default>CacheDefaultExpire 3600 (one hour)</default>
 508 <contextlist><context>server config</context>
 509   <context>virtual host</context>
 510   <context>directory</context>
 511   <context>.htaccess</context>
 512 </contextlist>
 513
 514 <usage>
 515     <p>The <directive>CacheDefaultExpire</directive> directive specifies a default time,
 516     in seconds, to cache a document if neither an expiry date nor last-modified date are provided
 517     with the document. The value specified with the <directive>CacheMaxExpire</directive>
 518     directive does <em>not</em> override this setting.</p>
 519
 520     <highlight language="config">
 521       CacheDefaultExpire 86400
 522     </highlight>
 523 </usage>
 524 </directivesynopsis>
 525
 526 <directivesynopsis>
 527 <name>CacheIgnoreNoLastMod</name>
 528 <description>Ignore the fact that a response has no Last Modified
 529 header.</description>
 530 <syntax>CacheIgnoreNoLastMod On|Off</syntax>
 531 <default>CacheIgnoreNoLastMod Off</default>
 532 <contextlist><context>server config</context>
 533   <context>virtual host</context>
 534   <context>directory</context>
 535   <context>.htaccess</context>
 536 </contextlist>
 537
 538 <usage>
 539     <p>Ordinarily, documents without a last-modified date are not cached.
 540     Under some circumstances the last-modified date is removed (during
 541     <module>mod_include</module> processing for example) or not provided
 542     at all. The <directive>CacheIgnoreNoLastMod</directive> directive
 543     provides a way to specify that documents without last-modified dates
 544     should be considered for caching, even without a last-modified date.
 545     If neither a last-modified date nor an expiry date are provided with
 546     the document then the value specified by the
 547     <directive>CacheDefaultExpire</directive> directive will be used to
 548     generate an expiration date.</p>
 549
 550     <highlight language="config">
 551       CacheIgnoreNoLastMod On
 552     </highlight>
 553 </usage>
 554 </directivesynopsis>
 555
 556 <directivesynopsis>
 557 <name>CacheIgnoreCacheControl</name>
 558 <description>Ignore request to not serve cached content to client</description>
 559 <syntax>CacheIgnoreCacheControl On|Off</syntax>
 560 <default>CacheIgnoreCacheControl Off</default>
 561 <contextlist><context>server config</context><context>virtual host</context>
 562 </contextlist>
 563
 564 <usage>
 565     <p>Ordinarily, requests containing a Cache-Control: no-cache or
 566     Pragma: no-cache header value will not be served from the cache.  The
 567     <directive>CacheIgnoreCacheControl</directive> directive allows this
 568     behavior to be overridden.  <directive>CacheIgnoreCacheControl On</directive>
 569     tells the server to attempt to serve the resource from the cache even
 570     if the request contains no-cache header values.  Resources requiring
 571     authorization will <em>never</em> be cached.</p>
 572
 573     <highlight language="config">
 574       CacheIgnoreCacheControl On
 575     </highlight>
 576
 577     <note type="warning"><title>Warning:</title>
 578        This directive will allow serving from the cache even if the client has
 579        requested that the document not be served from the cache.  This might
 580        result in stale content being served.
 581     </note>
 582 </usage>
 583 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
 584 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 585 </directivesynopsis>
 586
 587 <directivesynopsis>
 588 <name>CacheIgnoreQueryString</name>
 589 <description>Ignore query string when caching</description>
 590 <syntax>CacheIgnoreQueryString On|Off</syntax>
 591 <default>CacheIgnoreQueryString Off</default>
 592 <contextlist><context>server config</context><context>virtual host</context>
 593 </contextlist>
 594
 595 <usage>
 596     <p>Ordinarily, requests with query string parameters are cached separately
 597     for each unique query string. This is according to RFC 2616/13.9 done only
 598     if an expiration time is specified. The
 599     <directive>CacheIgnoreQueryString</directive> directive tells the cache to
 600     cache requests even if no expiration time is specified, and to reply with
 601     a cached reply even if the query string differs. From a caching point of
 602     view the request is treated as if having no query string when this
 603     directive is enabled.</p>
 604
 605     <highlight language="config">
 606       CacheIgnoreQueryString On
 607     </highlight>
 608
 609 </usage>
 610 </directivesynopsis>
 611
 612 <directivesynopsis>
 613 <name>CacheLastModifiedFactor</name>
 614 <description>The factor used to compute an expiry date based on the
 615 LastModified date.</description>
 616 <syntax>CacheLastModifiedFactor <var>float</var></syntax>
 617 <default>CacheLastModifiedFactor 0.1</default>
 618 <contextlist><context>server config</context>
 619   <context>virtual host</context>
 620   <context>directory</context>
 621   <context>.htaccess</context>
 622 </contextlist>
 623
 624 <usage>
 625     <p>In the event that a document does not provide an expiry date but does
 626     provide a last-modified date, an expiry date can be calculated based on
 627     the time since the document was last modified. The
 628     <directive>CacheLastModifiedFactor</directive> directive specifies a
 629     <var>factor</var> to be used in the generation of this expiry date
 630     according to the following formula:
 631
 632     <code>expiry-period = time-since-last-modified-date * <var>factor</var>
 633     expiry-date = current-date + expiry-period</code>
 634
 635     For example, if the document was last modified 10 hours ago, and
 636     <var>factor</var> is 0.1 then the expiry-period will be set to
 637     10*0.1 = 1 hour. If the current time was 3:00pm then the computed
 638     expiry-date would be 3:00pm + 1hour = 4:00pm.
 639
 640     If the expiry-period would be longer than that set by
 641     <directive>CacheMaxExpire</directive>, then the latter takes
 642     precedence.</p>
 643
 644     <highlight language="config">
 645       CacheLastModifiedFactor 0.5
 646     </highlight>
 647 </usage>
 648 </directivesynopsis>
 649
 650 <directivesynopsis>
 651 <name>CacheIgnoreHeaders</name>
 652 <description>Do not store the given HTTP header(s) in the cache.
 653 </description>
 654 <syntax>CacheIgnoreHeaders <var>header-string</var> [<var>header-string</var>] ...</syntax>
 655 <default>CacheIgnoreHeaders None</default>
 656 <contextlist><context>server config</context><context>virtual host</context>
 657 </contextlist>
 658
 659 <usage>
 660     <p>According to RFC 2616, hop-by-hop HTTP headers are not stored in
 661     the cache.  The following HTTP headers are hop-by-hop headers and thus
 662     do not get stored in the cache in <em>any</em> case regardless of the
 663     setting of <directive>CacheIgnoreHeaders</directive>:</p>
 664
 665     <ul>
 666       <li><code>Connection</code></li>
 667       <li><code>Keep-Alive</code></li>
 668       <li><code>Proxy-Authenticate</code></li>
 669       <li><code>Proxy-Authorization</code></li>
 670       <li><code>TE</code></li>
 671       <li><code>Trailers</code></li>
 672       <li><code>Transfer-Encoding</code></li>
 673       <li><code>Upgrade</code></li>
 674     </ul>
 675
 676     <p><directive>CacheIgnoreHeaders</directive> specifies additional HTTP
 677     headers that should not to be stored in the cache.  For example, it makes
 678     sense in some cases to prevent cookies from being stored in the cache.</p>
 679
 680     <p><directive>CacheIgnoreHeaders</directive> takes a space separated list
 681     of HTTP headers that should not be stored in the cache. If only hop-by-hop
 682     headers not should be stored in the cache (the RFC 2616 compliant
 683     behaviour), <directive>CacheIgnoreHeaders</directive> can be set to
 684     <code>None</code>.</p>
 685
 686     <example><title>Example 1</title>
 687     <highlight language="config">
 688       CacheIgnoreHeaders Set-Cookie
 689       </highlight>
 690     </example>
 691
 692     <example><title>Example 2</title>
 693     <highlight language="config">
 694       CacheIgnoreHeaders None
 695       </highlight>
 696     </example>
 697
 698     <note type="warning"><title>Warning:</title>
 699       If headers like <code>Expires</code> which are needed for proper cache
 700       management are not stored due to a
 701       <directive>CacheIgnoreHeaders</directive> setting, the behaviour of
 702       mod_cache is undefined.
 703     </note>
 704 </usage>
 705 </directivesynopsis>
 706
 707 <directivesynopsis>
 708 <name>CacheIgnoreURLSessionIdentifiers</name>
 709 <description>Ignore defined session identifiers encoded in the URL when caching
 710 </description>
 711 <syntax>CacheIgnoreURLSessionIdentifiers <var>identifier</var> [<var>identifier</var>] ...</syntax>
 712 <default>CacheIgnoreURLSessionIdentifiers None</default>
 713 <contextlist><context>server config</context><context>virtual host</context>
 714 </contextlist>
 715
 716 <usage>
 717     <p>Sometimes applications encode the session identifier into the URL like in the following
 718     Examples:
 719     </p>
 720     <ul>
 721       <li><code>/someapplication/image.gif;jsessionid=123456789</code></li>
 722       <li><code>/someapplication/image.gif?PHPSESSIONID=12345678</code></li>
 723     </ul>
 724     <p>This causes cachable resources to be stored separately for each session, which
 725     is often not desired. <directive>CacheIgnoreURLSessionIdentifiers</directive> lets
 726     define a list of identifiers that are removed from the key that is used to identify
 727     an entity in the cache, such that cachable resources are not stored separately for
 728     each session.
 729     </p>
 730     <p><code>CacheIgnoreURLSessionIdentifiers None</code> clears the list of ignored
 731     identifiers. Otherwise, each identifier is added to the list.</p>
 732
 733     <example><title>Example 1</title>
 734     <highlight language="config">
 735       CacheIgnoreURLSessionIdentifiers jsessionid
 736       </highlight>
 737     </example>
 738
 739     <example><title>Example 2</title>
 740     <highlight language="config">
 741       CacheIgnoreURLSessionIdentifiers None
 742       </highlight>
 743     </example>
 744
 745 </usage>
 746 </directivesynopsis>
 747
 748 <directivesynopsis>
 749 <name>CacheStoreExpired</name>
 750 <description>Attempt to cache responses that the server reports as expired</description>
 751 <syntax>CacheStoreExpired On|Off</syntax>
 752 <default>CacheStoreExpired Off</default>
 753 <contextlist><context>server config</context>
 754   <context>virtual host</context>
 755   <context>directory</context>
 756   <context>.htaccess</context>
 757 </contextlist>
 758
 759 <usage>
 760     <p>Since httpd 2.2.4, responses which have already expired are not
 761        stored in the cache.  The <directive>CacheStoreExpired</directive>
 762        directive allows this behavior to be overridden.
 763        <directive>CacheStoreExpired</directive> On
 764        tells the server to attempt to cache the resource if it is stale.
 765        Subsequent requests would trigger an If-Modified-Since request of
 766        the origin server, and the response may be fulfilled from cache
 767        if the backend resource has not changed.</p>
 768
 769     <highlight language="config">
 770       CacheStoreExpired On
 771     </highlight>
 772 </usage>
 773 </directivesynopsis>
 774
 775 <directivesynopsis>
 776 <name>CacheStorePrivate</name>
 777 <description>Attempt to cache responses that the server has marked as private</description>
 778 <syntax>CacheStorePrivate On|Off</syntax>
 779 <default>CacheStorePrivate Off</default>
 780 <contextlist><context>server config</context>
 781   <context>virtual host</context>
 782   <context>directory</context>
 783   <context>.htaccess</context>
 784 </contextlist>
 785
 786 <usage>
 787     <p>Ordinarily, responses with Cache-Control: private header values will not
 788        be stored in the cache.  The <directive>CacheStorePrivate</directive>
 789        directive allows this behavior to be overridden.
 790        <directive>CacheStorePrivate</directive> On
 791        tells the server to attempt to cache the resource even if it contains
 792        private header values.  Resources requiring authorization will
 793        <em>never</em> be cached.</p>
 794
 795     <highlight language="config">
 796       CacheStorePrivate On
 797     </highlight>
 798
 799     <note type="warning"><title>Warning:</title>
 800        This directive will allow caching even if the upstream server has
 801        requested that the resource not be cached.  This directive is only
 802        ideal for a 'private' cache.
 803     </note>
 804 </usage>
 805 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
 806 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 807 </directivesynopsis>
 808
 809 <directivesynopsis>
 810 <name>CacheStoreNoStore</name>
 811 <description>Attempt to cache requests or responses that have been marked as no-store.</description>
 812 <syntax>CacheStoreNoStore On|Off</syntax>
 813 <default>CacheStoreNoStore Off</default>
 814 <contextlist><context>server config</context>
 815   <context>virtual host</context>
 816   <context>directory</context>
 817   <context>.htaccess</context>
 818 </contextlist>
 819
 820 <usage>
 821     <p>Ordinarily, requests or responses with Cache-Control: no-store header
 822        values will not be stored in the cache.  The
 823        <directive>CacheStoreNoStore</directive> directive allows this
 824        behavior to be overridden.  <directive>CacheStoreNoStore</directive> On
 825        tells the server to attempt to cache the resource even if it contains
 826        no-store header values.  Resources requiring authorization will
 827        <em>never</em> be cached.</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 <compatibility>Available in Apache 2.2.15 and later</compatibility>
 852
 853 <usage>
 854   <p>The <directive>CacheLock</directive> directive enables the thundering herd lock
 855   for the given URL space.</p>
 856
 857   <p>In a minimal configuration the following directive is all that is needed to
 858   enable the thundering herd lock in the default run-time file directory.</p>
 859
 860   <highlight language="config">
 861 # Enable cache lock
 862 CacheLock on
 863   </highlight>
 864
 865   <p>Locks consist of empty files that only exist for stale URLs in flight, so this
 866   is significantly less resource intensive than the traditional disk cache.</p>
 867 </usage>
 868 </directivesynopsis>
 869
 870 <directivesynopsis>
 871 <name>CacheLockPath</name>
 872 <description>Set the lock path directory.</description>
 873 <syntax>CacheLockPath <var>directory</var></syntax>
 874 <default>CacheLockPath mod_cache-lock</default>
 875 <contextlist><context>server config</context><context>virtual host</context>
 876 </contextlist>
 877
 878 <usage>
 879   <p>The <directive>CacheLockPath</directive> directive allows you to specify the
 880   directory in which the locks are created.  If <var>directory</var> is not an absolute
 881   path, the location specified will be relative to the value of
 882   <directive module="core">DefaultRuntimeDir</directive>.</p>
 883 </usage>
 884 </directivesynopsis>
 885
 886 <directivesynopsis>
 887 <name>CacheLockMaxAge</name>
 888 <description>Set the maximum possible age of a cache lock.</description>
 889 <syntax>CacheLockMaxAge <var>integer</var></syntax>
 890 <default>CacheLockMaxAge 5</default>
 891 <contextlist><context>server config</context><context>virtual host</context>
 892 </contextlist>
 893
 894 <usage>
 895   <p>The <directive>CacheLockMaxAge</directive> directive specifies the maximum
 896   age of any cache lock.</p>
 897
 898   <p>A lock older than this value in seconds will be ignored, and the next
 899   incoming request will be given the opportunity to re-establish the lock.
 900   This mechanism prevents a slow client taking an excessively long time to refresh
 901   an entity.</p>
 902
 903 </usage>
 904 </directivesynopsis>
 905
 906 <directivesynopsis>
 907   <name>CacheQuickHandler</name>
 908   <description>Run the cache from the quick handler.</description>
 909   <syntax>CacheQuickHandler <var>on|off</var></syntax>
 910   <default>CacheQuickHandler on</default>
 911   <contextlist><context>server config</context><context>virtual host</context>
 912   </contextlist>
 913   <compatibility>Apache HTTP Server 2.3.3 and later</compatibility>
 914
 915   <usage>
 916     <p>The <directive module="mod_cache">CacheQuickHandler</directive> directive
 917     controls the phase in which the cache is handled.</p>
 918
 919     <p>In the default enabled configuration, the cache operates within the quick
 920     handler phase. This phase short circuits the majority of server processing,
 921     and represents the most performant mode of operation for a typical server.
 922     The cache <strong>bolts onto</strong> the front of the server, and the
 923     majority of server processing is avoided.</p>
 924
 925     <p>When disabled, the cache operates as a normal handler, and is subject to
 926     the full set of phases when handling a server request. While this mode is
 927     slower than the default, it allows the cache to be used in cases where full
 928     processing is required, such as when content is subject to authorisation.</p>
 929
 930     <highlight language="config">
 931 # Run cache as a normal handler
 932 CacheQuickHandler off
 933     </highlight>
 934
 935     <p>It is also possible, when the quick handler is disabled, for the
 936     administrator to choose the precise location within the filter chain where
 937     caching is to be performed, by adding the <strong>CACHE</strong> filter to
 938     the chain.</p>
 939
 940     <highlight language="config">
 941 # Cache content before mod_include and mod_deflate
 942 CacheQuickHandler off
 943 AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html
 944     </highlight>
 945
 946     <p>If the CACHE filter is specified more than once, the last instance will
 947     apply.</p>
 948
 949   </usage>
 950 </directivesynopsis>
 951
 952 <directivesynopsis>
 953 <name>CacheHeader</name>
 954 <description>Add an X-Cache header to the response.</description>
 955 <syntax>CacheHeader <var>on|off</var></syntax>
 956 <default>CacheHeader off</default>
 957 <contextlist><context>server config</context>
 958     <context>virtual host</context>
 959     <context>directory</context>
 960     <context>.htaccess</context>
 961 </contextlist>
 962 <compatibility>Available in Apache 2.3.9 and later</compatibility>
 963
 964 <usage>
 965   <p>When the <directive module="mod_cache">CacheHeader</directive> directive
 966   is switched on, an <strong>X-Cache</strong> header will be added to the response
 967   with the cache status of this response. If the normal handler is used, this
 968   directive may appear within a <directive module="core">&lt;Directory&gt;</directive>
 969   or <directive module="core">&lt;Location&gt;</directive> directive. If the quick
 970   handler is used, this directive must appear within a server or virtual host
 971   context, otherwise the setting will be ignored.</p>
 972
 973   <dl>
 974     <dt><strong>HIT</strong></dt><dd>The entity was fresh, and was served from
 975     cache.</dd>
 976     <dt><strong>REVALIDATE</strong></dt><dd>The entity was stale, was successfully
 977     revalidated and was served from cache.</dd>
 978     <dt><strong>MISS</strong></dt><dd>The entity was fetched from the upstream
 979       server and was not served from cache.</dd>
 980   </dl>
 981
 982   <highlight language="config">
 983 # Enable the X-Cache header
 984 CacheHeader on
 985   </highlight>
 986
 987   <highlight language="config">
 988     X-Cache: HIT from localhost
 989   </highlight>
 990
 991 </usage>
 992 </directivesynopsis>
 993
 994 <directivesynopsis>
 995 <name>CacheDetailHeader</name>
 996 <description>Add an X-Cache-Detail header to the response.</description>
 997 <syntax>CacheDetailHeader <var>on|off</var></syntax>
 998 <default>CacheDetailHeader off</default>
 999 <contextlist><context>server config</context>
1000       <context>virtual host</context>
1001       <context>directory</context>
1002       <context>.htaccess</context>
1003 </contextlist>
1004 <compatibility>Available in Apache 2.3.9 and later</compatibility>
1005
1006 <usage>
1007   <p>When the <directive module="mod_cache">CacheDetailHeader</directive> directive
1008   is switched on, an <strong>X-Cache-Detail</strong> header will be added to the response
1009   containing the detailed reason for a particular caching decision.</p>
1010
1011   <p>It can be useful during development of cached RESTful services to have additional
1012   information about the caching decision written to the response headers, so as to
1013   confirm whether <code>Cache-Control</code> and other headers have been correctly
1014   used by the service and client.</p>
1015
1016   <p>If the normal handler is used, this directive may appear within a
1017   <directive module="core">&lt;Directory&gt;</directive> or
1018   <directive module="core">&lt;Location&gt;</directive> directive. If the quick handler
1019   is used, this directive must appear within a server or virtual host context, otherwise
1020   the setting will be ignored.</p>
1021
1022   <highlight language="config">
1023 # Enable the X-Cache-Detail header
1024 CacheDetailHeader on
1025   </highlight>
1026
1027   <example>
1028     X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost<br />
1029   </example>
1030
1031 </usage>
1032 </directivesynopsis>
1033
1034 <directivesynopsis>
1035 <name>CacheKeyBaseURL</name>
1036 <description>Override the base URL of reverse proxied cache keys.</description>
1037 <syntax>CacheKeyBaseURL <var>URL</var></syntax>
1038 <default>CacheKeyBaseURL http://example.com</default>
1039 <contextlist><context>server config</context>
1040 <context>virtual host</context>
1041 </contextlist>
1042 <compatibility>Available in Apache 2.3.9 and later</compatibility>
1043
1044 <usage>
1045   <p>When the <directive module="mod_cache">CacheKeyBaseURL</directive> directive
1046   is specified, the URL provided will be used as the base URL to calculate
1047   the URL of the cache keys in the reverse proxy configuration. When not specified,
1048   the scheme, hostname and port of the current virtual host is used to construct
1049   the cache key. When a cluster of machines is present, and all cached entries
1050   should be cached beneath the same cache key, a new base URL can be specified
1051   with this directive.</p>
1052
1053   <highlight language="config">
1054 # Override the base URL of the cache key.
1055 CacheKeyBaseURL http://www.example.com/
1056   </highlight>
1057
1058   <note type="warning">Take care when setting this directive. If two separate virtual
1059   hosts are accidentally given the same base URL, entries from one virtual host
1060   will be served to the other.</note>
1061
1062 </usage>
1063 </directivesynopsis>
1064
1065 <directivesynopsis>
1066 <name>CacheStaleOnError</name>
1067 <description>Serve stale content in place of 5xx responses.</description>
1068 <syntax>CacheStaleOnError <var>on|off</var></syntax>
1069 <default>CacheStaleOnError on</default>
1070 <contextlist><context>server config</context>
1071     <context>virtual host</context>
1072     <context>directory</context>
1073     <context>.htaccess</context>
1074 </contextlist>
1075 <compatibility>Available in Apache 2.3.9 and later</compatibility>
1076
1077 <usage>
1078   <p>When the <directive module="mod_cache">CacheStaleOnError</directive> directive
1079   is switched on, and when stale data is available in the cache, the cache will
1080   respond to 5xx responses from the backend by returning the stale data instead of
1081   the 5xx response. While the Cache-Control headers sent by clients will be respected,
1082   and the raw 5xx responses returned to the client on request, the 5xx response so
1083   returned to the client will not invalidate the content in the cache.</p>
1084
1085   <highlight language="config">
1086 # Serve stale data on error.
1087 CacheStaleOnError on
1088   </highlight>
1089
1090 </usage>
1091 </directivesynopsis>
1092
1093 </modulesynopsis>