| <?xml version="1.0"?> |
| <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <modulesynopsis> |
| |
| <name>mod_cache</name> |
| <description>Content cache keyed to URIs.</description> |
| <status>Experimental</status> |
| <sourcefile>mod_cache.c</sourcefile> |
| <identifier>cache_module</identifier> |
| |
| <summary> |
| <note type="warning"> |
| This module is experimental. Documentation is still under development... |
| </note> |
| |
| <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">CacheGcInterval</directive> |
| <directive module="mod_disk_cache">CacheDirLevels</directive> |
| <directive module="mod_disk_cache">CacheDirLength</directive> |
| <directive module="mod_disk_cache">CacheExpiryCheck</directive> |
| <directive module="mod_disk_cache">CacheMinFileSize</directive> |
| <directive module="mod_disk_cache">CacheMaxFileSize</directive> |
| <directive module="mod_disk_cache">CacheTimeMargin</directive> |
| <directive module="mod_disk_cache">CacheGcDaily</directive> |
| <directive module="mod_disk_cache">CacheGcUnused</directive> |
| <directive module="mod_disk_cache">CacheGcClean</directive> |
| <directive module="mod_disk_cache">CacheGcMemUsage</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 /> |
| <IfModule mod_disk_cache.c><br /> |
| <indent> |
| CacheRoot c:/cacheroot<br /> |
| CacheSize 256<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 the fact that the client requested the content not be |
| cached.</description> |
| <syntax>CacheIgnoreCacheControl On|Off</syntax> |
| <default>CacheIgnoreCacheControl Off</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, documents with no-cache or no-store header values will not be stored in the cache. |
| The <directive>CacheIgnoreCacheControl</directive> directive allows this behavior to be overridden. |
| <directive>CacheIgnoreCacheControl</directive> On tells the server to attempt to cache the document |
| even if it contains no-cache or no-store header values. Documents requiring authorization will |
| <em>never</em> be cached.</p> |
| |
| <example> |
| CacheIgnoreCacheControl On |
| </example> |
| </usage> |
| </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>CacheForceCompletion</name> |
| <description>Percentage of document served, after which the server |
| will complete caching the file even if the request is cancelled.</description> |
| <syntax>CacheForceCompletion <var>Percentage</var></syntax> |
| <default>CacheForceCompletion 60</default> |
| <contextlist><context>server config</context><context>virtual host</context> |
| </contextlist> |
| |
| <usage> |
| <p>Ordinarily, if a request is cancelled while the response is being |
| cached and delivered to the client the processing of the response will |
| stop and the cache entry will be removed. The |
| <directive>CacheForceCompletion</directive> directive specifies a |
| threshold beyond which the document will continue to be cached to |
| completion, even if the request is cancelled.</p> |
| |
| <p>The threshold is a percentage specified as a value between |
| <code>1</code> and <code>100</code>. A value of <code>0</code> |
| specifies that the default be used. A value of <code>100</code> |
| will only cache documents that are served in their entirety. A value |
| between 60 and 90 is recommended.</p> |
| |
| <example> |
| CacheForceCompletion 80 |
| </example> |
| |
| <note type="warning"><title>Note:</title> |
| This feature is currently <em>not</em> implemented. |
| </note> |
| </usage> |
| </directivesynopsis> |
| |
| </modulesynopsis> |