2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
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.
23 <modulesynopsis metafile="mod_cache_disk.xml.meta">
25 <name>mod_cache_disk</name>
26 <description>Disk based storage module for the HTTP caching filter.</description>
27 <status>Extension</status>
28 <sourcefile>mod_cache_disk.c</sourcefile>
29 <identifier>cache_disk_module</identifier>
32 <p><module>mod_cache_disk</module> implements a disk based storage
33 manager for <module>mod_cache</module>.</p>
35 <p>The headers and bodies of cached responses are stored separately on
36 disk, in a directory structure derived from the md5 hash of the cached
39 <p>Multiple content negotiated responses can be stored concurrently,
40 however the caching of partial content is not yet supported by this
43 <p>Atomic cache updates to both header and body files are achieved
44 without the need for locking by storing the device and inode numbers of
45 the body file within the header file. This has the side effect that
46 cache entries manually moved into the cache will be ignored.</p>
48 <p>The <program>htcacheclean</program> tool is provided to list cached
49 URLs, remove cached URLs, or to maintain the size of the disk cache
50 within size and/or inode limits. The tool can be run on demand, or
51 can be daemonized to offer continuous monitoring of directory sizes.</p>
53 <note><title>Note:</title>
54 <p><module>mod_cache_disk</module> requires the services of
55 <module>mod_cache</module>, which must be
56 loaded before mod_cache_disk.</p>
58 <note><title>Note:</title>
59 <p><module>mod_cache_disk</module> uses the sendfile feature to
60 serve files from the cache when supported by the platform, and
61 when enabled with <directive module="core">EnableSendfile</directive>.
62 However, per-directory and .htaccess configuration of
63 <directive module="core">EnableSendfile</directive> are ignored by
64 <module>mod_cache_disk</module> as the corresponding settings are not
65 available to the module when a request is being served from the
69 <seealso><module>mod_cache</module></seealso>
70 <seealso><module>mod_cache_socache</module></seealso>
71 <seealso><a href="../caching.html">Caching Guide</a></seealso>
74 <name>CacheRoot</name>
75 <description>The directory root under which cache files are
77 <syntax>CacheRoot <var>directory</var></syntax>
78 <contextlist><context>server config</context><context>virtual host</context>
82 <p>The <directive>CacheRoot</directive> directive defines the name of
83 the directory on the disk to contain cache files. If the <module
84 >mod_cache_disk</module> module has been loaded or compiled in to the
85 Apache server, this directive <em>must</em> be defined. Failing to
86 provide a value for <directive>CacheRoot</directive> will result in
87 a configuration file processing error. The <directive
88 module="mod_cache_disk">CacheDirLevels</directive> and <directive
89 module="mod_cache_disk">CacheDirLength</directive> directives define
90 the structure of the directories under the specified root directory.</p>
92 <highlight language="config">
93 CacheRoot c:/cacheroot
99 <name>CacheDirLevels</name>
100 <description>The number of levels of subdirectories in the
102 <syntax>CacheDirLevels <var>levels</var></syntax>
103 <default>CacheDirLevels 2</default>
104 <contextlist><context>server config</context><context>virtual host</context>
108 <p>The <directive>CacheDirLevels</directive> directive sets the number
109 of subdirectory levels in the cache. Cached data will be saved this
110 many directory levels below the <directive module="mod_cache_disk"
111 >CacheRoot</directive> directory.</p>
112 <p>A high value for <directive>CacheDirLevels</directive> combined
113 with a low value for <directive>CacheDirLength</directive> will result in
114 a relatively deep hierarchy, with a small number of subdirectories at each
118 <p>The result of <directive>CacheDirLevels</directive>*
119 <directive module="mod_cache_disk">CacheDirLength</directive> must
120 not be higher than 20.</p>
127 <name>CacheDirLength</name>
128 <description>The number of characters in subdirectory names</description>
129 <syntax>CacheDirLength <var>length</var></syntax>
130 <default>CacheDirLength 2</default>
131 <contextlist><context>server config</context><context>virtual host</context>
135 <p>The <directive>CacheDirLength</directive> directive sets the number
136 of characters for each subdirectory name in the cache hierarchy. It can
137 be used in conjunction with <directive>CacheDirLevels</directive> to
138 determine the approximate structure of your cache hierarchy.</p>
139 <p>A high value for <directive>CacheDirLength</directive> combined
140 with a low value for <directive>CacheDirLevels</directive> will result in
141 a relatively flat hierarchy, with a large number of subdirectories at each
145 <p>The result of <directive module="mod_cache_disk"
146 >CacheDirLevels</directive>* <directive>CacheDirLength</directive>
147 must not be higher than 20.</p>
154 <name>CacheMinFileSize</name>
155 <description>The minimum size (in bytes) of a document to be placed in the
157 <syntax>CacheMinFileSize <var>bytes</var></syntax>
158 <default>CacheMinFileSize 1</default>
159 <contextlist><context>server config</context>
160 <context>virtual host</context>
161 <context>directory</context>
162 <context>.htaccess</context>
166 <p>The <directive>CacheMinFileSize</directive> directive sets the
167 minimum size, in bytes, for a document to be considered for storage
170 <highlight language="config">
177 <name>CacheMaxFileSize</name>
178 <description>The maximum size (in bytes) of a document to be placed in the
180 <syntax>CacheMaxFileSize <var>bytes</var></syntax>
181 <default>CacheMaxFileSize 1000000</default>
182 <contextlist><context>server config</context>
183 <context>virtual host</context>
184 <context>directory</context>
185 <context>.htaccess</context>
189 <p>The <directive>CacheMaxFileSize</directive> directive sets the
190 maximum size, in bytes, for a document to be considered for storage in
193 <highlight language="config">
194 CacheMaxFileSize 64000
200 <name>CacheReadSize</name>
201 <description>The minimum size (in bytes) of the document to read and be cached
202 before sending the data downstream</description>
203 <syntax>CacheReadSize <var>bytes</var></syntax>
204 <default>CacheReadSize 0</default>
205 <contextlist><context>server config</context>
206 <context>virtual host</context>
207 <context>directory</context>
208 <context>.htaccess</context>
212 <p>The <directive>CacheReadSize</directive> directive sets the
213 minimum amount of data, in bytes, to be read from the backend before the
214 data is sent to the client. The default of zero causes all data read of
215 any size to be passed downstream to the client immediately as it arrives.
216 Setting this to a higher value causes the disk cache to buffer at least
217 this amount before sending the result to the client. This can improve
218 performance when caching content from a reverse proxy.</p>
220 <p>This directive only takes effect when the data is being saved to the
221 cache, as opposed to data being served from the cache.</p>
223 <highlight language="config">
230 <name>CacheReadTime</name>
231 <description>The minimum time (in milliseconds) that should elapse while reading
232 before data is sent downstream</description>
233 <syntax>CacheReadTime <var>milliseconds</var></syntax>
234 <default>CacheReadTime 0</default>
235 <contextlist><context>server config</context>
236 <context>virtual host</context>
237 <context>directory</context>
238 <context>.htaccess</context>
242 <p>The <directive>CacheReadTime</directive> directive sets the minimum amount
243 of elapsed time that should pass before making an attempt to send data
244 downstream to the client. During the time period, data will be buffered
245 before sending the result to the client. This can improve performance when
246 caching content from a reverse proxy.</p>
248 <p>The default of zero disables this option.</p>
250 <p>This directive only takes effect when the data is being saved to the
251 cache, as opposed to data being served from the cache. It is recommended
252 that this option be used alongside the
253 <directive module="mod_cache_disk">CacheReadSize</directive> directive to
254 ensure that the server does not buffer excessively should data arrive faster
257 <highlight language="config">