| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Copyright 2002-2005 The Apache Software Foundation or its licensors, as |
| applicable. |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <modulesynopsis metafile="mod_cache.xml.meta"> |
| |
| <name>mod_cache</name> |
| <description>Content cache keyed to URIs.</description> |
| <status>Extension</status> |
| <sourcefile>mod_cache.c</sourcefile> |
| <identifier>cache_module</identifier> |
| |
| <summary> |
| <p><module>mod_cache</module> implements an <a |
| href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant HTTP |
| content cache that can be used to cache either local or proxied content. |
| <module>mod_cache</module> requires the services of one or more storage |
| management modules. Two storage management modules are included in |
| the base Apache distribution:</p> |
| <dl> |
| <dt><module>mod_disk_cache</module></dt> |
| <dd>implements a disk based storage manager.</dd> |
| |
| <dt><module>mod_mem_cache</module></dt> |
| <dd>implements a memory based storage manager. |
| <module>mod_mem_cache</module> can be configured to operate in two |
| modes: caching open file descriptors or caching objects in heap storage. |
| <module>mod_mem_cache</module> can be used to cache locally generated content |
| or to cache backend server content for <module>mod_proxy</module> when |
| configured using <directive module="mod_proxy">ProxyPass</directive> |
| (aka <dfn>reverse proxy</dfn>)</dd> |
| </dl> |
| |
| <p>Content is stored in and retrieved from the cache using URI based keys. Content with |
| access protection is not cached.</p> |
| </summary> |
| |
| <section id="related"><title>Related Modules and Directives</title> |
| <related> |
| <modulelist> |
| <module>mod_disk_cache</module> |
| <module>mod_mem_cache</module> |
| </modulelist> |
| <directivelist> |
| <directive module="mod_disk_cache">CacheRoot</directive> |
| <directive module="mod_disk_cache">CacheSize</directive> |
| <directive module="mod_disk_cache">CacheDirLevels</directive> |
| <directive module="mod_disk_cache">CacheDirLength</directive> |
| <directive module="mod_disk_cache">CacheMinFileSize</directive> |
| <directive module="mod_disk_cache">CacheMaxFileSize</directive> |
| <directive module="mod_mem_cache">MCacheSize</directive> |
| <directive module="mod_mem_cache">MCacheMaxObjectCount</directive> |
| <directive module="mod_mem_cache">MCacheMinObjectSize</directive> |
| <directive module="mod_mem_cache">MCacheMaxObjectSize</directive> |
| <directive module="mod_mem_cache">MCacheRemovalAlgorithm</directive> |
| <directive module="mod_mem_cache">MCacheMaxStreamingBuffer</directive> |
| </directivelist> |
| </related> |
| </section> |
| |
| <section id="sampleconf"><title>Sample Configuration</title> |
| <example><title>Sample httpd.conf</title> |
| #<br /> |
| # Sample Cache Configuration<br /> |
| #<br /> |
| LoadModule cache_module modules/mod_cache.so<br /> |
| <br /> |
| <IfModule mod_cache.c><br /> |
| <indent> |
| #LoadModule disk_cache_module modules/mod_disk_cache.so<br /> |
| # If you want to use mod_disk_cache instead of mod_mem_cache, |
| # uncomment the line above and comment out the LoadModule line below. |
| <IfModule mod_disk_cache.c><br /> |
| <indent> |
| CacheRoot c:/cacheroot<br /> |
| CacheEnable disk /<br /> |
| CacheDirLevels 5<br /> |
| CacheDirLength 3<br /> |
| </indent> |
| </IfModule> <br /> |
| <br /> |
| LoadModule mem_cache_module modules/mod_mem_cache.so<br /> |
| <IfModule mod_mem_cache.c><br /> |
| <indent> |
| CacheEnable mem /<br /> |
| MCacheSize 4096<br /> |
| MCacheMaxObjectCount 100<br /> |
| MCacheMinObjectSize 1<br /> |
| MCacheMaxObjectSize 2048<br /> |
| </indent> |
| </IfModule><br /> |
| </indent> |
| </IfModule> |
| </example> |
| </section> |
| |
| <directivesynopsis> |
| <name>CacheEnable</name> |
| <description>Enable caching of specified URLs using a specified storage |
| manager</description> |
| <syntax>CacheEnable <var>cache_type</var> <var>url-string</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>CacheEnable</directive> directive instructs |
| <module>mod_cache</module> to cache urls at or below |
| <var>url-string</var>. The cache storage manager is specified with the |
| <var>cache_type</var> argument. <var>cache_type</var> <code> mem</code> |
| instructs <module>mod_cache</module> to use the memory based storage |
| manager implemented by <module>mod_mem_cache</module>. |
| <var>cache_type</var> <code>disk</code> instructs |
| <module>mod_cache</module> to use the disk based storage manager |
| implemented by <module>mod_disk_cache</module>. |
| <var>cache_type</var> <code>fd</code> instructs |
| <module>mod_cache</module> to use the file descriptor cache implemented |
| by <module>mod_mem_cache</module>.</p> |
| <p>In the event that the URL space overlaps between different |
| <directive>CacheEnable</directive> directives (as in the example below), |
| each possible storage manager will be run until the first one that |
| actually processes the request. The order in which the storage managers are |
| run is determined by the order of the <directive>CacheEnable</directive> |
| directives in the configuration file.</p> |
| |
| <example> |
| CacheEnable mem /manual<br /> |
| CacheEnable fd /images<br /> |
| CacheEnable disk /<br /> |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheDisable</name> |
| <description>Disable caching of specified URLs</description> |
| <syntax>CacheDisable <var> url-string</var></syntax> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>CacheDisable</directive> directive instructs |
| <module>mod_cache</module> to <em>not</em> cache urls at or below |
| <var>url-string</var>.</p> |
| |
| <example><title>Example</title> |
| CacheDisable /local_files |
| </example> |
| </usage> |
| |
| </directivesynopsis> |
| <directivesynopsis> |
| <name>CacheMaxExpire</name> |
| <description>The maximum time in seconds to cache a document</description> |
| <syntax>CacheMaxExpire <var>seconds</var></syntax> |
| <default>CacheMaxExpire 86400 (one day)</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>CacheMaxExpire</directive> directive specifies the maximum number of |
| seconds for which cachable HTTP documents will be retained without checking the origin |
| server. Thus, documents will be out of date at most this number of seconds. This maximum |
| value is enforced even if an expiry date was supplied with the document.</p> |
| |
| <example> |
| CacheMaxExpire 604800 |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheDefaultExpire</name> |
| <description>The default duration to cache a document when no expiry date is specified.</description> |
| <syntax>CacheDefaultExpire <var>seconds</var></syntax> |
| <default>CacheDefaultExpire 3600 (one hour)</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>The <directive>CacheDefaultExpire</directive> directive specifies a default time, |
| in seconds, to cache a document if neither an expiry date nor last-modified date are provided |
| with the document. The value specified with the <directive>CacheMaxExpire</directive> |
| directive does <em>not</em> override this setting.</p> |
| |
| <example> |
| CacheDefaultExpire 86400 |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheIgnoreNoLastMod</name> |
| <description>Ignore the fact that a response has no Last Modified |
| header.</description> |
| <syntax>CacheIgnoreNoLastMod On|Off</syntax> |
| <default>CacheIgnoreNoLastMod Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, documents without a last-modified date are not cached. |
| Under some circumstances the last-modified date is removed (during |
| <module>mod_include</module> processing for example) or not provided |
| at all. The <directive>CacheIgnoreNoLastMod</directive> directive |
| provides a way to specify that documents without last-modified dates |
| should be considered for caching, even without a last-modified date. |
| If neither a last-modified date nor an expiry date are provided with |
| the document then the value specified by the |
| <directive>CacheDefaultExpire</directive> directive will be used to |
| generate an expiration date.</p> |
| |
| <example> |
| CacheIgnoreNoLastMod On |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheIgnoreCacheControl</name> |
| <description>Ignore request to not serve cached content to client</description> |
| <syntax>CacheIgnoreCacheControl On|Off</syntax> |
| <default>CacheIgnoreCacheControl Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, requests containing a Cache-Control: no-cache or |
| Pragma: no-cache header value will not be served from the cache. The |
| <directive>CacheIgnoreCacheControl</directive> directive allows this |
| behavior to be overridden. <directive>CacheIgnoreCacheControl</directive> |
| On tells the server to attempt to serve the resource from the cache even |
| if the request contains no-cache header values. Resources requiring |
| authorization will <em>never</em> be cached.</p> |
| |
| <example> |
| CacheIgnoreCacheControl On |
| </example> |
| |
| <note type="warning"><title>Warning:</title> |
| This directive will allow serving from the cache even if the client has |
| requested that the document not be served from the cache. This might |
| result in stale content being served. |
| </note> |
| </usage> |
| <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso> |
| <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheLastModifiedFactor</name> |
| <description>The factor used to compute an expiry date based on the |
| LastModified date.</description> |
| <syntax>CacheLastModifiedFactor <var>float</var></syntax> |
| <default>CacheLastModifiedFactor 0.1</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>In the event that a document does not provide an expiry date but does |
| provide a last-modified date, an expiry date can be calculated based on |
| the time since the document was last modified. The |
| <directive>CacheLastModifiedFactor</directive> directive specifies a |
| <var>factor</var> to be used in the generation of this expiry date |
| according to the following formula: |
| |
| <code>expiry-period = time-since-last-modified-date * <var>factor</var> |
| expiry-date = current-date + expiry-period</code> |
| |
| For example, if the document was last modified 10 hours ago, and |
| <var>factor</var> is 0.1 then the expiry-period will be set to |
| 10*0.1 = 1 hour. If the current time was 3:00pm then the computed |
| expiry-date would be 3:00pm + 1hour = 4:00pm. |
| |
| If the expiry-period would be longer than that set by |
| <directive>CacheMaxExpire</directive>, then the latter takes |
| precedence.</p> |
| |
| <example> |
| CacheLastModifiedFactor 0.5 |
| </example> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheIgnoreHeaders</name> |
| <description>Do not store the given HTTP header(s) in the cache. |
| </description> |
| <syntax>CacheIgnoreHeaders <var>header-string</var> [<var>header-string</var>] ...</syntax> |
| <default>CacheIgnoreHeaders None</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>According to RFC 2616, hop-by-hop HTTP headers are not stored in |
| the cache. The following HTTP headers are hop-by-hop headers and thus |
| do not get stored in the cache in <em>any</em> case regardless of the |
| setting of <directive>CacheIgnoreHeaders</directive>:</p> |
| |
| <ul> |
| <li><code>Connection</code></li> |
| <li><code>Keep-Alive</code></li> |
| <li><code>Proxy-Authenticate</code></li> |
| <li><code>Proxy-Authorization</code></li> |
| <li><code>TE</code></li> |
| <li><code>Trailers</code></li> |
| <li><code>Transfer-Encoding</code></li> |
| <li><code>Upgrade</code></li> |
| </ul> |
| |
| <p><directive>CacheIgnoreHeaders</directive> specifies additional HTTP |
| headers that should not to be stored in the cache. For example, it makes |
| sense in some cases to prevent cookies from being stored in the cache.</p> |
| |
| <p><directive>CacheIgnoreHeaders</directive> takes a space separated list |
| of HTTP headers that should not be stored in the cache. If only hop-by-hop |
| headers not should be stored in the cache (the RFC 2616 compliant |
| behaviour), <directive>CacheIgnoreHeaders</directive> can be set to |
| <code>None</code>.</p> |
| |
| <example><title>Example 1</title> |
| CacheIgnoreHeaders Set-Cookie |
| </example> |
| |
| <example><title>Example 2</title> |
| CacheIgnoreHeaders None |
| </example> |
| |
| <note type="warning"><title>Warning:</title> |
| If headers like <code>Expires</code> which are needed for proper cache |
| management are not stored due to a |
| <directive>CacheIgnoreHeaders</directive> setting, the behaviour of |
| mod_cache is undefined. |
| </note> |
| </usage> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheStorePrivate</name> |
| <description>Attempt to cache responses that the server has marked as private</description> |
| <syntax>CacheStorePrivate On|Off</syntax> |
| <default>CacheStorePrivate Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, responses with Cache-Control: private header values will not |
| be stored in the cache. The <directive>CacheStorePrivate</directive> |
| directive allows this behavior to be overridden. |
| <directive>CacheStorePrivate</directive> On |
| tells the server to attempt to cache the resource even if it contains |
| private header values. Resources requiring authorization will |
| <em>never</em> be cached.</p> |
| |
| <example> |
| CacheStorePrivate On |
| </example> |
| |
| <note type="warning"><title>Warning:</title> |
| This directive will allow caching even if the upstream server has |
| requested that the resource not be cached. This directive is only |
| ideal for a 'private' cache. |
| </note> |
| </usage> |
| <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso> |
| <seealso><directive module="mod_cache">CacheStoreNoStore</directive></seealso> |
| </directivesynopsis> |
| |
| <directivesynopsis> |
| <name>CacheStoreNoStore</name> |
| <description>Attempt to cache requests or responses that have been marked as no-store.</description> |
| <syntax>CacheStoreNoStore On|Off</syntax> |
| <default>CacheStoreNoStore Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, requests or responses with Cache-Control: no-store header |
| values will not be stored in the cache. The |
| <directive>CacheStoreNoCache</directive> directive allows this |
| behavior to be overridden. <directive>CacheStoreNoCache</directive> On |
| tells the server to attempt to cache the resource even if it contains |
| no-store header values. Resources requiring authorization will |
| <em>never</em> be cached.</p> |
| |
| <example> |
| CacheStoreNoStore On |
| </example> |
| |
| <note type="warning"><title>Warning:</title> |
| As described in RFC 2616, the no-store directive is intended to |
| "prevent the inadvertent release or retention of sensitive information |
| (for example, on backup tapes)." Enabling this option could store |
| sensitive information in the cache. You are hereby warned. |
| </note> |
| </usage> |
| <seealso><directive module="mod_cache">CacheIgnoreCacheControl</directive></seealso> |
| <seealso><directive module="mod_cache">CacheStorePrivate</directive></seealso> |
| </directivesynopsis> |
| </modulesynopsis> |
