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>Content cache keyed to URIs.</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 and
  33     can be used to circumvent <directive
  34     module="mod_authz_host">Allow</directive> and <directive
  35     module="mod_authz_host">Deny</directive> directives. You
  36     should not enable caching for any content to which you wish
  37     to limit access by client host name, address or environment
  38     variable.</note>
  39
  40     <p><module>mod_cache</module> implements an <a
  41     href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant HTTP
  42     content cache that can be used to cache either local or proxied content.
  43     <module>mod_cache</module> requires the services of one or more storage
  44     management modules. One storage management module is included in
  45     the base Apache distribution:</p>
  46     <dl>
  47     <dt><module>mod_disk_cache</module></dt>
  48     <dd>implements a disk based storage manager.</dd>
  49     </dl>
  50
  51     <p>Content is stored in and retrieved from the cache using URI based keys. Content with
  52     access protection is not cached.</p>
  53     <p>Further details, discussion, and examples, are provided in the
  54     <a href="../caching.html">Caching Guide</a>.</p>
  55 </summary>
  56 <seealso><a href="../caching.html">Caching Guide</a></seealso>
  57
  58 <section id="related"><title>Related Modules and Directives</title>
  59     <related>
  60       <modulelist>
  61         <module>mod_disk_cache</module>
  62       </modulelist>
  63       <directivelist>
  64         <directive module="mod_disk_cache">CacheRoot</directive>
  65         <directive module="mod_disk_cache">CacheDirLevels</directive>
  66         <directive module="mod_disk_cache">CacheDirLength</directive>
  67         <directive module="mod_disk_cache">CacheMinFileSize</directive>
  68         <directive module="mod_disk_cache">CacheMaxFileSize</directive>
  69       </directivelist>
  70     </related>
  71 </section>
  72
  73 <section id="sampleconf"><title>Sample Configuration</title>
  74     <example><title>Sample httpd.conf</title>
  75       #<br />
  76       # Sample Cache Configuration<br />
  77       #<br />
  78       LoadModule cache_module modules/mod_cache.so<br />
  79       <br />
  80       &lt;IfModule mod_cache.c&gt;<br />
  81       <indent>
  82         LoadModule disk_cache_module modules/mod_disk_cache.so<br />
  83         &lt;IfModule mod_disk_cache.c&gt;<br />
  84         <indent>
  85           CacheRoot c:/cacheroot<br />
  86           CacheEnable disk  /<br />
  87           CacheDirLevels 5<br />
  88           CacheDirLength 3<br />
  89         </indent>
  90         &lt;/IfModule&gt; <br />
  91         <br />
  92         # When acting as a proxy, don't cache the list of security updates<br />
  93         CacheDisable http://security.update.server/update-list/<br />
  94       </indent>
  95       &lt;/IfModule&gt;
  96     </example>
  97 </section>
  98
  99 <directivesynopsis>
 100 <name>CacheEnable</name>
 101 <description>Enable caching of specified URLs using a specified storage
 102 manager</description>
 103 <syntax>CacheEnable <var>cache_type</var> <var>url-string</var></syntax>
 104 <contextlist><context>server config</context><context>virtual host</context>
 105 </contextlist>
 106
 107 <usage>
 108     <p>The <directive>CacheEnable</directive> directive instructs
 109     <module>mod_cache</module> to cache urls at or below
 110     <var>url-string</var>. The cache storage manager is specified with the
 111     <var>cache_type</var> argument.
 112     <var>cache_type</var> <code>disk</code> instructs
 113     <module>mod_cache</module> to use the disk based storage manager
 114     implemented by <module>mod_disk_cache</module>.</p>
 115     <p>In the event that the URL space overlaps between different
 116     <directive>CacheEnable</directive> directives (as in the example below),
 117     each possible storage manager will be run until the first one that
 118     actually processes the request. The order in which the storage managers are
 119     run is determined by the order of the <directive>CacheEnable</directive>
 120     directives in the configuration file.</p>
 121
 122     <p>When acting as a forward proxy server, <var>url-string</var> can
 123     also be used to specify remote sites and proxy protocols which
 124     caching should be enabled for.</p>
 125
 126     <example>
 127       # Cache proxied url's<br />
 128       CacheEnable  disk  /<br /><br />
 129       # Cache FTP-proxied url's<br />
 130       CacheEnable  disk  ftp://<br /><br />
 131       # Cache content from www.apache.org<br />
 132       CacheEnable  disk  http://www.apache.org/<br />
 133     </example>
 134
 135     <p> The <code>no-cache</code> environment variable can be set to
 136     disable caching on a finer grained set of resources.</p>
 137
 138 </usage>
 139 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 140 </directivesynopsis>
 141
 142 <directivesynopsis>
 143 <name>CacheDisable</name>
 144 <description>Disable caching of specified URLs</description>
 145 <syntax>CacheDisable <var> url-string</var></syntax>
 146 <contextlist><context>server config</context><context>virtual host</context>
 147 </contextlist>
 148
 149 <usage>
 150     <p>The <directive>CacheDisable</directive> directive instructs
 151     <module>mod_cache</module> to <em>not</em> cache urls at or below
 152     <var>url-string</var>.</p>
 153
 154     <example><title>Example</title>
 155       CacheDisable /local_files
 156     </example>
 157
 158     <p> The <code>no-cache</code> environment variable can be set to
 159     disable caching on a finer grained set of resources.</p>
 160 </usage>
 161 <seealso><a href="../env.html">Environment Variables in Apache</a></seealso>
 162 </directivesynopsis>
 163 <directivesynopsis>
 164 <name>CacheMaxExpire</name>
 165 <description>The maximum time in seconds to cache a document</description>
 166 <syntax>CacheMaxExpire <var>seconds</var></syntax>
 167 <default>CacheMaxExpire 86400 (one day)</default>
 168 <contextlist><context>server config</context><context>virtual host</context>
 169 </contextlist>
 170
 171 <usage>
 172     <p>The <directive>CacheMaxExpire</directive> directive specifies the maximum number of
 173     seconds for which cachable HTTP documents will be retained without checking the origin
 174     server. Thus, documents will be out of date at most this number of seconds. This maximum
 175     value is enforced even if an expiry date was supplied with the document.</p>
 176
 177     <example>
 178       CacheMaxExpire 604800
 179     </example>
 180 </usage>
 181 </directivesynopsis>
 182
 183 <directivesynopsis>
 184 <name>CacheMinExpire</name>
 185 <description>The minimum time in seconds to cache a document</description>
 186 <syntax>CacheMinExpire <var>seconds</var></syntax>
 187 <default>CacheMinExpire 0</default>
 188 <contextlist><context>server config</context><context>virtual host</context>
 189 </contextlist>
 190
 191 <usage>
 192     <p>The <directive>CacheMinExpire</directive> directive specifies the minimum number of
 193     seconds for which cachable HTTP documents will be retained without checking the origin
 194     server. This is only used if no valid expire time was supplied with the document.</p>
 195
 196
 197     <example>
 198       CacheMinExpire 3600
 199     </example>
 200 </usage>
 201 </directivesynopsis>
 202
 203 <directivesynopsis>
 204 <name>CacheDefaultExpire</name>
 205 <description>The default duration to cache a document when no expiry date is specified.</description>
 206 <syntax>CacheDefaultExpire <var>seconds</var></syntax>
 207 <default>CacheDefaultExpire 3600 (one hour)</default>
 208 <contextlist><context>server config</context><context>virtual host</context>
 209 </contextlist>
 210
 211 <usage>
 212     <p>The <directive>CacheDefaultExpire</directive> directive specifies a default time,
 213     in seconds, to cache a document if neither an expiry date nor last-modified date are provided
 214     with the document. The value specified with the <directive>CacheMaxExpire</directive>
 215     directive does <em>not</em> override this setting.</p>
 216
 217     <example>
 218       CacheDefaultExpire 86400
 219     </example>
 220 </usage>
 221 </directivesynopsis>
 222
 223 <directivesynopsis>
 224 <name>CacheIgnoreNoLastMod</name>
 225 <description>Ignore the fact that a response has no Last Modified
 226 header.</description>
 227 <syntax>CacheIgnoreNoLastMod On|Off</syntax>
 228 <default>CacheIgnoreNoLastMod Off</default>
 229 <contextlist><context>server config</context><context>virtual host</context>
 230 </contextlist>
 231
 232 <usage>
 233     <p>Ordinarily, documents without a last-modified date are not cached.
 234     Under some circumstances the last-modified date is removed (during
 235     <module>mod_include</module> processing for example) or not provided
 236     at all. The <directive>CacheIgnoreNoLastMod</directive> directive
 237     provides a way to specify that documents without last-modified dates
 238     should be considered for caching, even without a last-modified date.
 239     If neither a last-modified date nor an expiry date are provided with
 240     the document then the value specified by the
 241     <directive>CacheDefaultExpire</directive> directive will be used to
 242     generate an expiration date.</p>
 243
 244     <example>
 245       CacheIgnoreNoLastMod On
 246     </example>
 247 </usage>
 248 </directivesynopsis>
 249
 250 <directivesynopsis>
 251 <name>CacheIgnoreCacheControl</name>
 252 <description>Ignore request to not serve cached content to client</description>
 253 <syntax>CacheIgnoreCacheControl On|Off</syntax>
 254 <default>CacheIgnoreCacheControl Off</default>
 255 <contextlist><context>server config</context><context>virtual host</context>
 256 </contextlist>
 257
 258 <usage>
 259     <p>Ordinarily, requests containing a Cache-Control: no-cache or
 260     Pragma: no-cache header value will not be served from the cache.  The
 261     <directive>CacheIgnoreCacheControl</directive> directive allows this
 262     behavior to be overridden.  <directive>CacheIgnoreCacheControl</directive>
 263     On tells the server to attempt to serve the resource from the cache even
 264     if the request contains no-cache header values.  Resources requiring
 265     authorization will <em>never</em> be cached.</p>
 266
 267     <example>
 268       CacheIgnoreCacheControl On
 269     </example>
 270
 271     <note type="warning"><title>Warning:</title>
 272        This directive will allow serving from the cache even if the client has
 273        requested that the document not be served from the cache.  This might
 274        result in stale content being served.
 275     </note>
 276 </usage>
 277 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
 278 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 279 </directivesynopsis>
 280
 281 <directivesynopsis>
 282 <name>CacheIgnoreQueryString</name>
 283 <description>Ignore query string when caching</description>
 284 <syntax>CacheIgnoreQueryString On|Off</syntax>
 285 <default>CacheIgnoreQueryString Off</default>
 286 <contextlist><context>server config</context><context>virtual host</context>
 287 </contextlist>
 288
 289 <usage>
 290     <p>Ordinarily, requests with query string parameters are cached separately
 291     for each unique query string. This is according to RFC 2616/13.9 done only
 292     if an expiration time is specified. The
 293     <directive>CacheIgnoreQueryString</directive> directive tells the cache to
 294     cache requests even if no expiration time is specified, and to reply with
 295     a cached reply even if the query string differs. From a caching point of
 296     view the request is treated as if having no query string when this
 297     directive is enabled.</p>
 298
 299     <example>
 300       CacheIgnoreQueryString On
 301     </example>
 302
 303 </usage>
 304 </directivesynopsis>
 305
 306 <directivesynopsis>
 307 <name>CacheLastModifiedFactor</name>
 308 <description>The factor used to compute an expiry date based on the
 309 LastModified date.</description>
 310 <syntax>CacheLastModifiedFactor <var>float</var></syntax>
 311 <default>CacheLastModifiedFactor 0.1</default>
 312 <contextlist><context>server config</context><context>virtual host</context>
 313 </contextlist>
 314
 315 <usage>
 316     <p>In the event that a document does not provide an expiry date but does
 317     provide a last-modified date, an expiry date can be calculated based on
 318     the time since the document was last modified. The
 319     <directive>CacheLastModifiedFactor</directive> directive specifies a
 320     <var>factor</var> to be used in the generation of this expiry date
 321     according to the following formula:
 322
 323     <code>expiry-period = time-since-last-modified-date * <var>factor</var>
 324     expiry-date = current-date + expiry-period</code>
 325
 326     For example, if the document was last modified 10 hours ago, and
 327     <var>factor</var> is 0.1 then the expiry-period will be set to
 328     10*0.1 = 1 hour. If the current time was 3:00pm then the computed
 329     expiry-date would be 3:00pm + 1hour = 4:00pm.
 330
 331     If the expiry-period would be longer than that set by
 332     <directive>CacheMaxExpire</directive>, then the latter takes
 333     precedence.</p>
 334
 335     <example>
 336       CacheLastModifiedFactor 0.5
 337     </example>
 338 </usage>
 339 </directivesynopsis>
 340
 341 <directivesynopsis>
 342 <name>CacheIgnoreHeaders</name>
 343 <description>Do not store the given HTTP header(s) in the cache.
 344 </description>
 345 <syntax>CacheIgnoreHeaders <var>header-string</var> [<var>header-string</var>] ...</syntax>
 346 <default>CacheIgnoreHeaders None</default>
 347 <contextlist><context>server config</context><context>virtual host</context>
 348 </contextlist>
 349
 350 <usage>
 351     <p>According to RFC 2616, hop-by-hop HTTP headers are not stored in
 352     the cache.  The following HTTP headers are hop-by-hop headers and thus
 353     do not get stored in the cache in <em>any</em> case regardless of the
 354     setting of <directive>CacheIgnoreHeaders</directive>:</p>
 355
 356     <ul>
 357       <li><code>Connection</code></li>
 358       <li><code>Keep-Alive</code></li>
 359       <li><code>Proxy-Authenticate</code></li>
 360       <li><code>Proxy-Authorization</code></li>
 361       <li><code>TE</code></li>
 362       <li><code>Trailers</code></li>
 363       <li><code>Transfer-Encoding</code></li>
 364       <li><code>Upgrade</code></li>
 365     </ul>
 366
 367     <p><directive>CacheIgnoreHeaders</directive> specifies additional HTTP
 368     headers that should not to be stored in the cache.  For example, it makes
 369     sense in some cases to prevent cookies from being stored in the cache.</p>
 370
 371     <p><directive>CacheIgnoreHeaders</directive> takes a space separated list
 372     of HTTP headers that should not be stored in the cache. If only hop-by-hop
 373     headers not should be stored in the cache (the RFC 2616 compliant
 374     behaviour), <directive>CacheIgnoreHeaders</directive> can be set to
 375     <code>None</code>.</p>
 376
 377     <example><title>Example 1</title>
 378       CacheIgnoreHeaders Set-Cookie
 379     </example>
 380
 381     <example><title>Example 2</title>
 382       CacheIgnoreHeaders None
 383     </example>
 384
 385     <note type="warning"><title>Warning:</title>
 386       If headers like <code>Expires</code> which are needed for proper cache
 387       management are not stored due to a
 388       <directive>CacheIgnoreHeaders</directive> setting, the behaviour of
 389       mod_cache is undefined.
 390     </note>
 391 </usage>
 392 </directivesynopsis>
 393
 394 <directivesynopsis>
 395 <name>CacheStorePrivate</name>
 396 <description>Attempt to cache responses that the server has marked as private</description>
 397 <syntax>CacheStorePrivate On|Off</syntax>
 398 <default>CacheStorePrivate Off</default>
 399 <contextlist><context>server config</context><context>virtual host</context>
 400 </contextlist>
 401
 402 <usage>
 403     <p>Ordinarily, responses with Cache-Control: private header values will not
 404        be stored in the cache.  The <directive>CacheStorePrivate</directive>
 405        directive allows this behavior to be overridden.
 406        <directive>CacheStorePrivate</directive> On
 407        tells the server to attempt to cache the resource even if it contains
 408        private header values.  Resources requiring authorization will
 409        <em>never</em> be cached.</p>
 410
 411     <example>
 412       CacheStorePrivate On
 413     </example>
 414
 415     <note type="warning"><title>Warning:</title>
 416        This directive will allow caching even if the upstream server has
 417        requested that the resource not be cached.  This directive is only
 418        ideal for a 'private' cache.
 419     </note>
 420 </usage>
 421 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
 422 <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso>
 423 </directivesynopsis>
 424
 425 <directivesynopsis>
 426 <name>CacheStoreNoStore</name>
 427 <description>Attempt to cache requests or responses that have been marked as no-store.</description>
 428 <syntax>CacheStoreNoStore On|Off</syntax>
 429 <default>CacheStoreNoStore Off</default>
 430 <contextlist><context>server config</context><context>virtual host</context>
 431 </contextlist>
 432
 433 <usage>
 434     <p>Ordinarily, requests or responses with Cache-Control: no-store header
 435        values will not be stored in the cache.  The
 436        <directive>CacheStoreNoCache</directive> directive allows this
 437        behavior to be overridden.  <directive>CacheStoreNoCache</directive> On
 438        tells the server to attempt to cache the resource even if it contains
 439        no-store header values.  Resources requiring authorization will
 440        <em>never</em> be cached.</p>
 441
 442     <example>
 443       CacheStoreNoStore On
 444     </example>
 445
 446     <note type="warning"><title>Warning:</title>
 447        As described in RFC 2616, the no-store directive is intended to
 448        "prevent the inadvertent release or retention of sensitive information
 449        (for example, on backup tapes)."  Enabling this option could store
 450        sensitive information in the cache.  You are hereby warned.
 451     </note>
 452 </usage>
 453 <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso>
 454 <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso>
 455 </directivesynopsis>
 456 </modulesynopsis>