path: root/docs/manual/mod/mod_disk_cache.xml

<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
<!-- $LastChangedRevision$ -->

<!--
 Licensed to the Apache Software Foundation (ASF) under one or more
 contributor license agreements.  See the NOTICE file distributed with
 this work for additional information regarding copyright ownership.
 The ASF licenses this file to You 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_disk_cache.xml.meta">

<name>mod_disk_cache</name>
<description>Content cache storage manager keyed to URIs</description>
<status>Experimental</status>
<sourcefile>mod_disk_cache.c</sourcefile>
<identifier>disk_cache_module</identifier>

<summary>
    <note type="warning">
      This module is experimental. Documentation is still under development...
    </note>

    <p><module>mod_disk_cache</module> implements a disk based storage
    manager. It is primarily of use in conjunction with
    <module>mod_proxy</module>.</p>

    <p>Content is stored in and retrieved from the cache using URI based
    keys. Content with access protection is not cached.</p>

    <note><title>Note:</title>
      <p><module>mod_disk_cache</module> requires the services of
      <module>mod_cache</module>.</p>
    </note>
</summary>

<directivesynopsis>
<name>CacheRoot</name>
<description>The directory root under which cache files are
stored</description>
<syntax>CacheRoot <var>directory</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheRoot</directive> directive defines the name of
    the directory on the disk to contain cache files. If the <module
    >mod_disk_cache</module> module has been loaded or compiled in to the
    Apache server, this directive <em>must</em> be defined. Failing to
    provide a value for <directive>CacheRoot</directive> will result in
    a configuration file processing error. The <directive
    module="mod_disk_cache">CacheDirLevels</directive> and <directive
    module="mod_disk_cache">CacheDirLength</directive> directives define
    the structure of the directories under the specified root directory.</p>

    <example>
      CacheRoot c:/cacheroot
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheSize</name>
<description>The maximum amount of disk space that will be used by the
cache in KBytes</description>
<syntax>CacheSize <var>KBytes</var></syntax>
<default>CacheSize 1000000</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheSize</directive> directive sets the desired
    disk space usage of the cache, in KBytes (1024-byte units). This
    directive does not put a  hard limit on the size of the cache. The
    garbage collector will delete files until the usage is at or below the
    settings. Always use a value that is lower than the available disk
    space.</p>

    <example>
      CacheSize  5000000
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheGcInterval</name>
<description>The interval between garbage collection attempts.</description>
<syntax>CacheGcInterval <var>hours</var></syntax>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheGcInterval</directive> directive specifies the
    number of hours to wait between attempts to free up disk space.</p>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheGcInterval  24<br />
    </example>

    <note type="warning">
      The <directive>CacheGcInterval</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheDirLevels</name>
<description>The number of levels of subdirectories in the
cache.</description>
<syntax>CacheDirLevels <var>levels</var></syntax>
<default>CacheDirLevels 3</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheDirLevels</directive> directive sets the number
    of subdirectory levels in the cache. Cached data will be saved this
    many directory levels below the <directive module="mod_disk_cache"
    >CacheRoot</directive> directory.</p>

    <note>
      <p>The result of <directive>CacheDirLevels</directive>*
      <directive module="mod_disk_cache">CacheDirLength</directive> must
      not be higher than 20.</p>
    </note>

    <example>
      CacheDirLevels  5
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheDirLength</name>
<description>The number of characters in subdirectory names</description>
<syntax>CacheDirLength <var>length</var></syntax>
<default>CacheDirLength 2</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheDirLength</directive> directive sets the number
    of characters for each subdirectory name in the cache hierarchy.</p>

    <note>
      <p>The result of <directive module="mod_disk_cache"
      >CacheDirLevels</directive>* <directive>CacheDirLength</directive>
      must not be higher than 20.</p>
    </note>

    <example>
      CacheDirLength  4
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheExpiryCheck</name>
<description>Indicates if the cache observes Expires dates when seeking
files</description>
<syntax>CacheExpiryCheck On|Off</syntax>
<default>CacheExpiryCheck On</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheExpiryCheck Off<br />
    </example>

    <note type="warning">
      The <directive>CacheExpiryCheck</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheMinFileSize</name>
<description>The minimum size (in bytes) of a document to be placed in the
cache</description>
<syntax>CacheMinFileSize <var>bytes</var></syntax>
<default>CacheMinFileSize 1</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheMinFileSize</directive> directive sets the
    minimum size, in bytes, for a document to be considered for storage
    in the cache.</p>

    <example>
      CacheMinFileSize 64
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheMaxFileSize</name>
<description>The maximum size (in bytes) of a document to be placed in the
cache</description>
<syntax>CacheMaxFileSize <var>bytes</var></syntax>
<default>CacheMaxFileSize 1000000</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>The <directive>CacheMaxFileSize</directive> directive sets the
    maximum size, in bytes, for a document to be considered for storage in
    the cache.</p>

    <example>
      CacheMaxFileSize 64000
    </example>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheTimeMargin</name>
<description>The minimum time margin to cache a document</description>
<syntax>CacheTimeMargin <var>?</var></syntax>
<default>CacheTimeMargin ?</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheTimeMargin X
    </example>

    <note type="warning">
      The <directive>CacheTimeMargin</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheGcDaily</name>
<description>The recurring time each day for garbage collection to be run.
(24 hour clock)</description>
<syntax>CacheGcDaily <var>time</var></syntax>
<default>CacheGcDaily ?</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheGcDaily 23:59
    </example>

    <note type="warning">
      The <directive>CacheGcDaily</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheGcUnused</name>
<description>The time to retain unreferenced cached files that match a
URL.</description>
<syntax>CacheGcUnused <var>hours</var> <var>url-string</var></syntax>
<default>CacheGcUnused ?</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheGcUnused 12 /local_images
    </example>

    <note type="warning">
      The <directive>CacheGcUnused</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheGcClean</name>
<description>The time to retain unchanged cached files that match a
URL</description>
<syntax>CacheGcClean <var>hours</var> <var>url-string</var></syntax>
<default>CacheGcClean ?</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheGcClean 12 /daily_scripts
    </example>

    <note type="warning">
      The <directive>CacheGcClean</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

<directivesynopsis>
<name>CacheGcMemUsage</name>
<description>The maximum kilobytes of memory used for garbage
collection</description>
<syntax>CacheGcMemUsage <var>KBytes</var></syntax>
<default>CacheGcMemUsage ?</default>
<contextlist><context>server config</context><context>virtual host</context>
</contextlist>

<usage>
    <p>More detail will be added here, when the function is implemented.</p>

    <example>
      CacheGcMemUsage 16
    </example>

    <note type="warning">
      The <directive>CacheGcMemUsage</directive> directive is currently
      <em>not</em> implemented.
    </note>
</usage>
</directivesynopsis>

</modulesynopsis>