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 <modulesynopsis>
   5
   6 <name>mod_cache</name>
   7 <description>Content cache keyed to URIs.</description>
   8 <status>Experimental</status>
   9 <sourcefile>mod_cache.c</sourcefile>
  10 <identifier>cache_module</identifier>
  11
  12 <summary>
  13     <note type="warning">
  14       This module is experimental. Documentation is still under development...
  15     </note>
  16
  17     <p><module>mod_cache</module> implements an <a
  18     href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant HTTP
  19     content cache that can be used to cache either local or proxied content.
  20     <module>mod_cache</module> requires the services of one or more storage
  21     management modules. Two storage management modules are included in
  22     the base Apache distribution:</p>
  23     <dl>
  24     <dt><module>mod_disk_cache</module></dt>
  25     <dd>implements a disk based storage manager.</dd>
  26
  27     <dt><module>mod_mem_cache</module></dt>
  28     <dd>implements a memory based storage manager.
  29     <module>mod_mem_cache</module> can be configured to operate in two
  30     modes: caching open file descriptors or caching objects in heap storage.
  31     <module>mod_mem_cache</module> can be used to cache locally generated content
  32     or to cache backend server content for <module>mod_proxy</module> when
  33     configured using <directive module="mod_proxy">ProxyPass</directive>
  34     (aka <dfn>reverse proxy</dfn>)</dd>
  35     </dl>
  36
  37     <p>Content is stored in and retrieved from the cache using URI based keys. Content with
  38     access protection is not cached.</p>
  39 </summary>
  40
  41 <section id="related"><title>Related Modules and Directives</title>
  42     <related>
  43       <modulelist>
  44         <module>mod_disk_cache</module>
  45         <module>mod_mem_cache</module>
  46       </modulelist>
  47       <directivelist>
  48         <directive module="mod_disk_cache">CacheRoot</directive>
  49         <directive module="mod_disk_cache">CacheSize</directive>
  50         <directive module="mod_disk_cache">CacheGcInterval</directive>
  51         <directive module="mod_disk_cache">CacheDirLevels</directive>
  52         <directive module="mod_disk_cache">CacheDirLength</directive>
  53         <directive module="mod_disk_cache">CacheExpiryCheck</directive>
  54         <directive module="mod_disk_cache">CacheMinFileSize</directive>
  55         <directive module="mod_disk_cache">CacheMaxFileSize</directive>
  56         <directive module="mod_disk_cache">CacheTimeMargin</directive>
  57         <directive module="mod_disk_cache">CacheGcDaily</directive>
  58         <directive module="mod_disk_cache">CacheGcUnused</directive>
  59         <directive module="mod_disk_cache">CacheGcClean</directive>
  60         <directive module="mod_disk_cache">CacheGcMemUsage</directive>
  61         <directive module="mod_mem_cache">MCacheSize</directive>
  62         <directive module="mod_mem_cache">MCacheMaxObjectCount</directive>
  63         <directive module="mod_mem_cache">MCacheMinObjectSize</directive>
  64         <directive module="mod_mem_cache">MCacheMaxObjectSize</directive>
  65         <directive module="mod_mem_cache">MCacheRemovalAlgorithm</directive>
  66       </directivelist>
  67     </related>
  68 </section>
  69
  70 <section id="sampleconf"><title>Sample Configuration</title>
  71     <example><title>Sample httpd.conf</title>
  72       #<br />
  73       # Sample Cache Configuration<br />
  74       #<br />
  75       LoadModule cache_module modules/mod_cache.so<br />
  76       <br />
  77       &lt;IfModule mod_cache.c&gt;<br />
  78       <indent>
  79         #LoadModule disk_cache_module modules/mod_disk_cache.so<br />
  80         &lt;IfModule mod_disk_cache.c&gt;<br />
  81         <indent>
  82           CacheRoot c:/cacheroot<br />
  83           CacheSize 256<br />
  84           CacheEnable disk  /<br />
  85           CacheDirLevels 5<br />
  86           CacheDirLength 3<br />
  87         </indent>
  88         &lt;/IfModule&gt; <br />
  89         <br />
  90         LoadModule mem_cache_module modules/mod_mem_cache.so<br />
  91         &lt;IfModule mod_mem_cache.c&gt;<br />
  92         <indent>
  93           CacheEnable mem  /<br />
  94           MCacheSize 4096<br />
  95           MCacheMaxObjectCount 100<br />
  96           MCacheMinObjectSize 1<br />
  97           MCacheMaxObjectSize 2048<br />
  98         </indent>
  99         &lt;/IfModule&gt;<br />
 100       </indent>
 101       &lt;/IfModule&gt;
 102     </example>
 103 </section>
 104
 105 <directivesynopsis>
 106 <name>CacheEnable</name>
 107 <description>Enable caching of specified URLs using a specified storage
 108 manager</description>
 109 <syntax>CacheEnable <var>cache_type</var> <var>url-string</var></syntax>
 110 <contextlist><context>server config</context><context>virtual host</context>
 111 </contextlist>
 112
 113 <usage>
 114     <p>The <directive>CacheEnable</directive> directive instructs
 115     <module>mod_cache</module> to cache urls at or below
 116     <var>url-string</var>. The cache storage manager is specified with the
 117     <var>cache_type</var> argument. <var>cache_type</var> <code> mem</code>
 118     instructs <module>mod_cache</module> to use the memory based storage
 119     manager implemented by <module>mod_mem_cache</module>.
 120     <var>cache_type</var> <code>disk</code> instructs
 121     <module>mod_cache</module> to use the disk based storage manager
 122     implemented by <module>mod_disk_cache</module>.
 123     <var>cache_type</var> <code>fd</code> instructs
 124     <module>mod_cache</module> to use the file descriptor cache implemented
 125     by <module>mod_mem_cache</module>.</p>
 126     <p>In the event that the URL space overlaps between different
 127     <directive>CacheEnable</directive> directives (as in the example below),
 128     each possible storage manager will be run until the first one that
 129     actually processes the request. The order in which the storage managers are
 130     run is determined by the order of the <directive>CacheEnable</directive>
 131     directives in the configuration file.</p>
 132
 133     <example>
 134       CacheEnable  mem   /manual<br />
 135       CacheEnable  fd    /images<br />
 136       CacheEnable  disk  /<br />
 137     </example>
 138 </usage>
 139 </directivesynopsis>
 140
 141 <directivesynopsis>
 142 <name>CacheDisable</name>
 143 <description>Disable caching of specified URLs</description>
 144 <syntax>CacheDisable <var> url-string</var></syntax>
 145 <contextlist><context>server config</context><context>virtual host</context>
 146 </contextlist>
 147
 148 <usage>
 149     <p>The <directive>CacheDisable</directive> directive instructs
 150     <module>mod_cache</module> to <em>not</em> cache urls at or below
 151     <var>url-string</var>.</p>
 152
 153     <example><title>Example</title>
 154       CacheDisable /local_files
 155     </example>
 156 </usage>
 157
 158 </directivesynopsis>
 159 <directivesynopsis>
 160 <name>CacheMaxExpire</name>
 161 <description>The maximum time in seconds to cache a document</description>
 162 <syntax>CacheMaxExpire <var>seconds</var></syntax>
 163 <default>CacheMaxExpire 86400 (one day)</default>
 164 <contextlist><context>server config</context><context>virtual host</context>
 165 </contextlist>
 166
 167 <usage>
 168     <p>The <directive>CacheMaxExpire</directive> directive specifies the maximum number of
 169     seconds for which cachable HTTP documents will be retained without checking the origin
 170     server. Thus, documents will be out of date at most this number of seconds. This maximum
 171     value is enforced even if an expiry date was supplied with the document.</p>
 172
 173     <example>
 174       CacheMaxExpire 604800
 175     </example>
 176 </usage>
 177 </directivesynopsis>
 178
 179 <directivesynopsis>
 180 <name>CacheDefaultExpire</name>
 181 <description>The default duration to cache a document when no expiry date is specified.</description>
 182 <syntax>CacheDefaultExpire <var>seconds</var></syntax>
 183 <default>CacheDefaultExpire 3600 (one hour)</default>
 184 <contextlist><context>server config</context><context>virtual host</context>
 185 </contextlist>
 186
 187 <usage>
 188     <p>The <directive>CacheDefaultExpire</directive> directive specifies a default time,
 189     in seconds, to cache a document if neither an expiry date nor last-modified date are provided
 190     with the document. The value specified with the <directive>CacheMaxExpire</directive>
 191     directive does <em>not</em> override this setting.</p>
 192
 193     <example>
 194       CacheDefaultExpire 86400
 195     </example>
 196 </usage>
 197 </directivesynopsis>
 198
 199 <directivesynopsis>
 200 <name>CacheIgnoreNoLastMod</name>
 201 <description>Ignore the fact that a response has no Last Modified
 202 header.</description>
 203 <syntax>CacheIgnoreNoLastMod On|Off</syntax>
 204 <default>CacheIgnoreNoLastMod Off</default>
 205 <contextlist><context>server config</context><context>virtual host</context>
 206 </contextlist>
 207
 208 <usage>
 209     <p>Ordinarily, documents without a last-modified date are not cached.
 210     Under some circumstances the last-modified date is removed (during
 211     <module>mod_include</module> processing for example) or not provided
 212     at all. The <directive>CacheIgnoreNoLastMod</directive> directive
 213     provides a way to specify that documents without last-modified dates
 214     should be considered for caching, even without a last-modified date.
 215     If neither a last-modified date nor an expiry date are provided with
 216     the document then the value specified by the
 217     <directive>CacheDefaultExpire</directive> directive will be used to
 218     generate an expiration date.</p>
 219
 220     <example>
 221       CacheIgnoreNoLastMod On
 222     </example>
 223 </usage>
 224 </directivesynopsis>
 225
 226 <directivesynopsis>
 227 <name>CacheIgnoreCacheControl</name>
 228 <description>Ignore the fact that the client requested the content not be
 229 cached.</description>
 230 <syntax>CacheIgnoreCacheControl On|Off</syntax>
 231 <default>CacheIgnoreCacheControl Off</default>
 232 <contextlist><context>server config</context><context>virtual host</context>
 233 </contextlist>
 234
 235 <usage>
 236     <p>Ordinarily, documents with no-cache or no-store header values will not be stored in the cache.
 237     The <directive>CacheIgnoreCacheControl</directive> directive allows this behavior to be overridden.
 238     <directive>CacheIgnoreCacheControl</directive> On tells the server to attempt to cache the document
 239     even if it contains no-cache or no-store header values. Documents requiring authorization will
 240     <em>never</em> be cached.</p>
 241
 242     <example>
 243       CacheIgnoreCacheControl On
 244     </example>
 245 </usage>
 246 </directivesynopsis>
 247
 248 <directivesynopsis>
 249 <name>CacheLastModifiedFactor</name>
 250 <description>The factor used to compute an expiry date based on the
 251 LastModified date.</description>
 252 <syntax>CacheLastModifiedFactor <var>float</var></syntax>
 253 <default>CacheLastModifiedFactor 0.1</default>
 254 <contextlist><context>server config</context><context>virtual host</context>
 255 </contextlist>
 256
 257 <usage>
 258     <p>In the event that a document does not provide an expiry date but does
 259     provide a last-modified date, an expiry date can be calculated based on
 260     the time since the document was last modified. The
 261     <directive>CacheLastModifiedFactor</directive> directive specifies a
 262     <var>factor</var> to be used in the generation of this expiry date
 263     according to the following formula:
 264
 265     <code>expiry-period = time-since-last-modified-date * <var>factor</var>
 266     expiry-date = current-date + expiry-period</code>
 267
 268     For example, if the document was last modified 10 hours ago, and
 269     <var>factor</var> is 0.1 then the expiry-period will be set to
 270     10*0.1 = 1 hour. If the current time was 3:00pm then the computed
 271     expiry-date would be 3:00pm + 1hour = 4:00pm.
 272
 273     If the expiry-period would be longer than that set by
 274     <directive>CacheMaxExpire</directive>, then the latter takes
 275     precedence.</p>
 276
 277     <example>
 278       CacheLastModifiedFactor 0.5
 279     </example>
 280 </usage>
 281 </directivesynopsis>
 282
 283 <directivesynopsis>
 284 <name>CacheForceCompletion</name>
 285 <description>Percentage of document served, after which the server
 286 will complete caching the file even if the request is cancelled.</description>
 287 <syntax>CacheForceCompletion <var>Percentage</var></syntax>
 288 <default>CacheForceCompletion 60</default>
 289 <contextlist><context>server config</context><context>virtual host</context>
 290 </contextlist>
 291
 292 <usage>
 293     <p>Ordinarily, if a request is cancelled while the response is being
 294     cached and delivered to the client the processing of the response will
 295     stop and the cache entry will be removed. The
 296     <directive>CacheForceCompletion</directive> directive specifies a
 297     threshold beyond which the document will continue to be cached to
 298     completion, even if the request is cancelled.</p>
 299
 300     <p>The threshold is a percentage specified as a value between
 301     <code>1</code> and <code>100</code>. A value of <code>0</code>
 302     specifies that the default be used. A value of <code>100</code>
 303     will only cache documents that are served in their entirety. A value
 304     between 60 and 90 is recommended.</p>
 305
 306     <example>
 307       CacheForceCompletion 80
 308     </example>
 309
 310     <note type="warning"><title>Note:</title>
 311       This feature is currently <em>not</em> implemented.
 312     </note>
 313 </usage>
 314 </directivesynopsis>
 315
 316 <directivesynopsis>
 317 <name>CacheMaxStreamingBuffer</name>
 318 <description>Maximum amount of a streamed response to buffer in memory
 319 before declaring the response uncacheable</description>
 320 <syntax>CacheMaxStreamingBuffer <var>size_in_bytes</var></syntax>
 321 <default>CacheMaxStreamingBuffer 0</default>
 322 <contextlist><context>server config</context><context>virtual host</context>
 323 </contextlist>
 324
 325 <usage>
 326     <p>The <directive>CacheMaxStreamingBuffer</directive> directive
 327     specifies the maximum number of bytes of a streamed response to
 328     buffer before deciding that the response is too big to cache.
 329     A streamed response is one in which the entire content is not
 330     immediately available and in which the <code>Content-Length</code>
 331     may not be known. Sources of streaming responses include proxied
 332     responses and the output of CGI scripts. By default, a streamed
 333     response will <em>not</em> be cached unless it has a
 334     <code>Content-Length</code> header. The reason for this is to
 335     avoid using a large amount of memory to buffer a partial response
 336     that might end up being too large to fit in the cache.
 337     The <directive>CacheMaxStreamingBuffer</directive> directive allows
 338     buffering of streamed responses that don't contain a
 339     <code>Content-Length</code> up to the specified maximum amount of
 340     space. If the maximum buffer space is reached, the buffered
 341     content is discarded and the attempt to cache is abandoned.</p>
 342
 343     <note><title>Note:</title>
 344       <p>Using a nonzero value for <directive
 345       >CacheMaxStreamingBuffer</directive> will not delay the transmission
 346       of the response to the client.  As soon as <module>mod_cache</module>
 347       copies a block of streamed content into a buffer, it sends the block
 348       on to the next output filter for delivery to the client.</p>
 349     </note>
 350
 351     <example>
 352       # Enable caching of streamed responses up to 64KB:<br />
 353       CacheMaxStreamingBuffer 65536
 354     </example>
 355 </usage>
 356 </directivesynopsis>
 357
 358 </modulesynopsis>