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