granicus.if.org Git - apache/blob - docs/manual/mod/mod_cache_disk.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 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   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
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  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.
  21 -->
  22
  23 <modulesynopsis metafile="mod_cache_disk.xml.meta">
  24
  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>
  30
  31 <summary>
  32     <p><module>mod_cache_disk</module> implements a disk based storage
  33     manager for <module>mod_cache</module>.</p>
  34
  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
  37     URL.</p>
  38
  39     <p>Multiple content negotiated responses can be stored concurrently,
  40     however the caching of partial content is not yet supported by this
  41     module.</p>
  42
  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>
  47
  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>
  52
  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>
  57     </note>
  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
  66       cache.</p>
  67     </note>
  68 </summary>
  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>
  72
  73 <directivesynopsis>
  74 <name>CacheRoot</name>
  75 <description>The directory root under which cache files are
  76 stored</description>
  77 <syntax>CacheRoot <var>directory</var></syntax>
  78 <contextlist><context>server config</context><context>virtual host</context>
  79 </contextlist>
  80
  81 <usage>
  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>
  91
  92     <highlight language="config">
  93       CacheRoot c:/cacheroot
  94     </highlight>
  95 </usage>
  96 </directivesynopsis>
  97
  98 <directivesynopsis>
  99 <name>CacheDirLevels</name>
 100 <description>The number of levels of subdirectories in the
 101 cache.</description>
 102 <syntax>CacheDirLevels <var>levels</var></syntax>
 103 <default>CacheDirLevels 2</default>
 104 <contextlist><context>server config</context><context>virtual host</context>
 105 </contextlist>
 106
 107 <usage>
 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
 115     level.</p>
 116
 117     <note>
 118       <p>The result of <directive>CacheDirLevels</directive>*
 119       <directive module="mod_cache_disk">CacheDirLength</directive> must
 120       not be higher than 20.</p>
 121     </note>
 122
 123 </usage>
 124 </directivesynopsis>
 125
 126 <directivesynopsis>
 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>
 132 </contextlist>
 133
 134 <usage>
 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
 142     level.</p>
 143
 144     <note>
 145       <p>The result of <directive module="mod_cache_disk"
 146       >CacheDirLevels</directive>* <directive>CacheDirLength</directive>
 147       must not be higher than 20.</p>
 148     </note>
 149
 150 </usage>
 151 </directivesynopsis>
 152
 153 <directivesynopsis>
 154 <name>CacheMinFileSize</name>
 155 <description>The minimum size (in bytes) of a document to be placed in the
 156 cache</description>
 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>
 163 </contextlist>
 164
 165 <usage>
 166     <p>The <directive>CacheMinFileSize</directive> directive sets the
 167     minimum size, in bytes, for a document to be considered for storage
 168     in the cache.</p>
 169
 170     <highlight language="config">
 171       CacheMinFileSize 64
 172     </highlight>
 173 </usage>
 174 </directivesynopsis>
 175
 176 <directivesynopsis>
 177 <name>CacheMaxFileSize</name>
 178 <description>The maximum size (in bytes) of a document to be placed in the
 179 cache</description>
 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>
 186 </contextlist>
 187
 188 <usage>
 189     <p>The <directive>CacheMaxFileSize</directive> directive sets the
 190     maximum size, in bytes, for a document to be considered for storage in
 191     the cache.</p>
 192
 193     <highlight language="config">
 194       CacheMaxFileSize 64000
 195     </highlight>
 196 </usage>
 197 </directivesynopsis>
 198
 199 <directivesynopsis>
 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>
 209 </contextlist>
 210
 211 <usage>
 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>
 219
 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>
 222
 223     <highlight language="config">
 224       CacheReadSize 102400
 225     </highlight>
 226 </usage>
 227 </directivesynopsis>
 228
 229 <directivesynopsis>
 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>
 239 </contextlist>
 240
 241 <usage>
 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>
 247
 248     <p>The default of zero disables this option.</p>
 249
 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
 255     than expected.</p>
 256
 257     <highlight language="config">
 258       CacheReadTime 1000
 259     </highlight>
 260 </usage>
 261 </directivesynopsis>
 262
 263 </modulesynopsis>