1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_cache - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_cache</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_cache.html" title="English"> en </a> | 28<a href="/fr/mod/mod_cache.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 29<a href="/ja/mod/mod_cache.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 30<a href="/ko/mod/mod_cache.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 31</div> 32<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>RFC 2616 compliant HTTP caching filter.</td></tr> 33<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr> 34<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>cache_module</td></tr> 35<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_cache.c</td></tr></table> 36<h3>Summary</h3> 37 38 <div class="warning">This module should be used with care, as when the 39 <code class="directive"><a href="#cachequickhandler">CacheQuickHandler</a></code> directive is 40 in its default value of <strong>on</strong>, the <code class="directive"><a href="/mod/mod_access_compat.html#allow">Allow</a></code> and <code class="directive"><a href="/mod/mod_access_compat.html#deny">Deny</a></code> directives will be circumvented. 41 You should not enable quick handler caching for any content to which you 42 wish to limit access by client host name, address or environment 43 variable.</div> 44 45 <p><code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> implements an <a href="http://www.ietf.org/rfc/rfc2616.txt">RFC 2616</a> compliant 46 <strong>HTTP content caching filter</strong>, with support for the caching 47 of content negotiated responses containing the Vary header.</p> 48 49 <p>RFC 2616 compliant caching provides a mechanism to verify whether 50 stale or expired content is still fresh, and can represent a significant 51 performance boost when the origin server supports <strong>conditional 52 requests</strong> by honouring the 53 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.26">If-None-Match</a> 54 HTTP request header. Content is only regenerated from scratch when the content 55 has changed, and not when the cached entry expires.</p> 56 57 <p>As a filter, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> can be placed in front of 58 content originating from any handler, including <strong>flat 59 files</strong> (served from a slow disk cached on a fast disk), the output 60 of a <strong>CGI script</strong> or <strong>dynamic content 61 generator</strong>, or content <strong>proxied from another 62 server</strong>.</p> 63 64 <p>In the default configuration, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> inserts the 65 caching filter as far forward as possible within the filter stack, 66 utilising the <strong>quick handler</strong> to bypass all per request 67 processing when returning content to the client. In this mode of 68 operation, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> may be thought of as a caching 69 proxy server bolted to the front of the webserver, while running within 70 the webserver itself.</p> 71 72 <p>When the quick handler is switched off using the 73 <code class="directive"><a href="#cachequickhandler">CacheQuickHandler</a></code> directive, 74 it becomes possible to insert the <strong>CACHE</strong> filter at a 75 point in the filter stack chosen by the administrator. This provides the 76 opportunity to cache content before that content is personalised by the 77 <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> filter, or optionally compressed by the 78 <code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code> filter.</p> 79 80 <p>Under normal operation, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will respond to 81 and can be controlled by the 82 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">Cache-Control</a> 83 and 84 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.32">Pragma</a> 85 headers sent from a client in a request, or from a 86 server within a response. Under exceptional circumstances, 87 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> can be configured to override these headers 88 and force site specific behaviour, however such behaviour will be limited 89 to this cache only, and will not affect the operation of other caches 90 that may exist between the client and server, and as a result is not 91 recommended unless strictly necessary.</p> 92 93 <p>RFC 2616 allows for the cache to return stale data while the existing 94 stale entry is refreshed from the origin server, and this is supported 95 by <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> when the 96 <code class="directive"><a href="#cachelock">CacheLock</a></code> directive is suitably 97 configured. Such responses will contain a 98 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a> 99 HTTP header with a 110 response code. RFC 2616 also allows a cache to return 100 stale data when the attempt made to refresh the stale data returns an 101 error 500 or above, and this behaviour is supported by default by 102 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code>. Such responses will contain a 103 <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.46">Warning</a> 104 HTTP header with a 111 response code.</p> 105 106 <p><code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> requires the services of one or more 107 storage management modules. One storage management module is included in 108 the base Apache distribution:</p> 109 <dl> 110 <dt><code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code></dt> 111 <dd>Implements a disk based storage manager. Headers and bodies are 112 stored separately on disk, in a directory structure derived from the 113 md5 hash of the cached URL. Multiple content negotiated responses can 114 be stored concurrently, however the caching of partial content is not 115 supported by this module. The <code class="program"><a href="/programs/htcacheclean.html">htcacheclean</a></code> tool is 116 provided to list cached URLs, remove cached URLs, or to maintain the size 117 of the disk cache within size and inode limits.</dd> 118 <dt><code class="module"><a href="/mod/mod_cache_socache.html">mod_cache_socache</a></code></dt> 119 <dd>Implements a shared object cache based storage manager. Headers and 120 bodies are stored together beneath a single key based on the URL of the 121 response being cached. Multiple content negotiated responses can 122 be stored concurrently, however the caching of partial content is not 123 supported by this module.</dd> 124 </dl> 125 126 <p>Further details, discussion, and examples, are provided in the 127 <a href="/caching.html">Caching Guide</a>.</p> 128</div> 129<div id="quickview"><h3 class="directives">Directives</h3> 130<ul id="toc"> 131<li><img alt="" src="/images/down.gif" /> <a href="#cachedefaultexpire">CacheDefaultExpire</a></li> 132<li><img alt="" src="/images/down.gif" /> <a href="#cachedetailheader">CacheDetailHeader</a></li> 133<li><img alt="" src="/images/down.gif" /> <a href="#cachedisable">CacheDisable</a></li> 134<li><img alt="" src="/images/down.gif" /> <a href="#cacheenable">CacheEnable</a></li> 135<li><img alt="" src="/images/down.gif" /> <a href="#cacheheader">CacheHeader</a></li> 136<li><img alt="" src="/images/down.gif" /> <a href="#cacheignorecachecontrol">CacheIgnoreCacheControl</a></li> 137<li><img alt="" src="/images/down.gif" /> <a href="#cacheignoreheaders">CacheIgnoreHeaders</a></li> 138<li><img alt="" src="/images/down.gif" /> <a href="#cacheignorenolastmod">CacheIgnoreNoLastMod</a></li> 139<li><img alt="" src="/images/down.gif" /> <a href="#cacheignorequerystring">CacheIgnoreQueryString</a></li> 140<li><img alt="" src="/images/down.gif" /> <a href="#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></li> 141<li><img alt="" src="/images/down.gif" /> <a href="#cachekeybaseurl">CacheKeyBaseURL</a></li> 142<li><img alt="" src="/images/down.gif" /> <a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a></li> 143<li><img alt="" src="/images/down.gif" /> <a href="#cachelock">CacheLock</a></li> 144<li><img alt="" src="/images/down.gif" /> <a href="#cachelockmaxage">CacheLockMaxAge</a></li> 145<li><img alt="" src="/images/down.gif" /> <a href="#cachelockpath">CacheLockPath</a></li> 146<li><img alt="" src="/images/down.gif" /> <a href="#cachemaxexpire">CacheMaxExpire</a></li> 147<li><img alt="" src="/images/down.gif" /> <a href="#cacheminexpire">CacheMinExpire</a></li> 148<li><img alt="" src="/images/down.gif" /> <a href="#cachequickhandler">CacheQuickHandler</a></li> 149<li><img alt="" src="/images/down.gif" /> <a href="#cachestaleonerror">CacheStaleOnError</a></li> 150<li><img alt="" src="/images/down.gif" /> <a href="#cachestoreexpired">CacheStoreExpired</a></li> 151<li><img alt="" src="/images/down.gif" /> <a href="#cachestorenostore">CacheStoreNoStore</a></li> 152<li><img alt="" src="/images/down.gif" /> <a href="#cachestoreprivate">CacheStorePrivate</a></li> 153</ul> 154<h3>Topics</h3> 155<ul id="topics"> 156<li><img alt="" src="/images/down.gif" /> <a href="#related">Related Modules and Directives</a></li> 157<li><img alt="" src="/images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li> 158<li><img alt="" src="/images/down.gif" /> <a href="#thunderingherd">Avoiding the Thundering Herd</a></li> 159<li><img alt="" src="/images/down.gif" /> <a href="#finecontrol">Fine Control with the CACHE Filter</a></li> 160<li><img alt="" src="/images/down.gif" /> <a href="#status">Cache Status and Logging</a></li> 161</ul><h3>See also</h3> 162<ul class="seealso"> 163<li><a href="/caching.html">Caching Guide</a></li> 164</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 165<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 166<div class="section"> 167<h2><a name="related" id="related">Related Modules and Directives</a></h2> 168 <table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code></li><li><code class="module"><a href="/mod/mod_cache_socache.html">mod_cache_socache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="/mod/mod_cache_disk.html#cacheroot">CacheRoot</a></code></li><li><code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlevels">CacheDirLevels</a></code></li><li><code class="directive"><a href="/mod/mod_cache_disk.html#cachedirlength">CacheDirLength</a></code></li><li><code class="directive"><a href="/mod/mod_cache_disk.html#cacheminfilesize">CacheMinFileSize</a></code></li><li><code class="directive"><a href="/mod/mod_cache_disk.html#cachemaxfilesize">CacheMaxFileSize</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocache">CacheSocache</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocachemaxtime">CacheSocacheMaxTime</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocachemintime">CacheSocacheMinTime</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocachemaxsize">CacheSocacheMaxSize</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocachereadsize">CacheSocacheReadSize</a></code></li><li><code class="directive"><a href="/mod/mod_cache_socache.html#cachesocachereadtime">CacheSocacheReadTime</a></code></li></ul></td></tr></table> 169</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 170<div class="section"> 171<h2><a name="sampleconf" id="sampleconf">Sample Configuration</a></h2> 172 <div class="example"><h3>Sample httpd.conf</h3><pre class="prettyprint lang-config"># 173# Sample Cache Configuration 174# 175LoadModule cache_module modules/mod_cache.so 176<IfModule mod_cache.c> 177 LoadModule cache_disk_module modules/mod_cache_disk.so 178 <IfModule mod_cache_disk.c> 179 CacheRoot c:/cacheroot 180 CacheEnable disk / 181 CacheDirLevels 5 182 CacheDirLength 3 183 </IfModule> 184 185 # When acting as a proxy, don't cache the list of security updates 186 CacheDisable http://security.update.server/update-list/ 187</IfModule></pre> 188</div> 189</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 190<div class="section"> 191<h2><a name="thunderingherd" id="thunderingherd">Avoiding the Thundering Herd</a></h2> 192 <p>When a cached entry becomes stale, <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> will submit 193 a conditional request to the backend, which is expected to confirm whether the 194 cached entry is still fresh, and send an updated entity if not.</p> 195 <p>A small but finite amount of time exists between the time the cached entity 196 becomes stale, and the time the stale entity is fully refreshed. On a busy 197 server, a significant number of requests might arrive during this time, and 198 cause a <strong>thundering herd</strong> of requests to strike the backend 199 suddenly and unpredictably.</p> 200 <p>To keep the thundering herd at bay, the <code class="directive">CacheLock</code> 201 directive can be used to define a directory in which locks are created for 202 URLs <strong>in flight</strong>. The lock is used as a <strong>hint</strong> 203 by other requests to either suppress an attempt to cache (someone else has 204 gone to fetch the entity), or to indicate that a stale entry is being refreshed 205 (stale content will be returned in the mean time). 206 </p> 207 <h3>Initial caching of an entry</h3> 208 209 <p>When an entity is cached for the first time, a lock will be created for the 210 entity until the response has been fully cached. During the lifetime of the 211 lock, the cache will suppress the second and subsequent attempt to cache the 212 same entity. While this doesn't hold back the thundering herd, it does stop 213 the cache attempting to cache the same entity multiple times simultaneously. 214 </p> 215 216 <h3>Refreshment of a stale entry</h3> 217 218 <p>When an entity reaches its freshness lifetime and becomes stale, a lock 219 will be created for the entity until the response has either been confirmed as 220 still fresh, or replaced by the backend. During the lifetime of the lock, the 221 second and subsequent incoming request will cause stale data to be returned, 222 and the thundering herd is kept at bay.</p> 223 224 <h3>Locks and Cache-Control: no-cache</h3> 225 226 <p>Locks are used as a <strong>hint only</strong> to enable the cache to be 227 more gentle on backend servers, however the lock can be overridden if necessary. 228 If the client sends a request with a Cache-Control header forcing a reload, any 229 lock that may be present will be ignored, and the client's request will be 230 honored immediately and the cached entry refreshed.</p> 231 <p>As a further safety mechanism, locks have a configurable maximum age. 232 Once this age has been reached, the lock is removed, and a new request is 233 given the opportunity to create a new lock. This maximum age can be set using 234 the <code class="directive">CacheLockMaxAge</code> directive, and defaults to 5 235 seconds. 236 </p> 237 238 <h3>Example configuration</h3> 239 240 <div class="example"><h3>Enabling the cache lock</h3><pre class="prettyprint lang-config"># 241# Enable the cache lock 242# 243<IfModule mod_cache.c> 244 CacheLock on 245 CacheLockPath /tmp/mod_cache-lock 246 CacheLockMaxAge 5 247</IfModule></pre> 248</div> 249 250</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 251<div class="section"> 252<h2><a name="finecontrol" id="finecontrol">Fine Control with the CACHE Filter</a></h2> 253 <p>Under the default mode of cache operation, the cache runs as a quick handler, 254 short circuiting the majority of server processing and offering the highest 255 cache performance available.</p> 256 257 <p>In this mode, the cache <strong>bolts onto</strong> the front of the server, 258 acting as if a free standing RFC 2616 caching proxy had been placed in front of 259 the server.</p> 260 261 <p>While this mode offers the best performance, the administrator may find that 262 under certain circumstances they may want to perform further processing on the 263 request after the request is cached, such as to inject personalisation into the 264 cached page, or to apply authorisation restrictions to the content. Under these 265 circumstances, an administrator is often forced to place independent reverse 266 proxy servers either behind or in front of the caching server to achieve this.</p> 267 268 <p>To solve this problem the <code class="directive"><a href="#cachequickhandler">CacheQuickHandler 269 </a></code> directive can be set to <strong>off</strong>, and the server will 270 process all phases normally handled by a non-cached request, including the 271 <strong>authentication and authorisation</strong> phases.</p> 272 273 <p>In addition, the administrator may optionally specify the <strong>precise point 274 within the filter chain</strong> where caching is to take place by adding the 275 <strong>CACHE</strong> filter to the output filter chain.</p> 276 277 <p>For example, to cache content before applying compression to the response, 278 place the <strong>CACHE</strong> filter before the <strong>DEFLATE</strong> 279 filter as in the example below:</p> 280 281 <pre class="prettyprint lang-config"># Cache content before optional compression 282CacheQuickHandler off 283AddOutputFilterByType CACHE;DEFLATE text/plain</pre> 284 285 286 <p>Another option is to have content cached before personalisation is applied 287 by <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> (or another content processing filter). In this 288 example templates containing tags understood by 289 <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> are cached before being parsed:</p> 290 291 <pre class="prettyprint lang-config"># Cache content before mod_include and mod_deflate 292CacheQuickHandler off 293AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html</pre> 294 295 296 <p>You may place the <strong>CACHE</strong> filter anywhere you wish within the 297 filter chain. In this example, content is cached after being parsed by 298 <code class="module"><a href="/mod/mod_include.html">mod_include</a></code>, but before being processed by 299 <code class="module"><a href="/mod/mod_deflate.html">mod_deflate</a></code>:</p> 300 301 <pre class="prettyprint lang-config"># Cache content between mod_include and mod_deflate 302CacheQuickHandler off 303AddOutputFilterByType INCLUDES;CACHE;DEFLATE text/html</pre> 304 305 306 <div class="warning"><h3>Warning:</h3>If the location of the 307 <strong>CACHE</strong> filter in the filter chain is changed for any reason, 308 you may need to <strong>flush your cache</strong> to ensure that your data 309 served remains consistent. <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> is not in a position 310 to enforce this for you.</div> 311 312</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 313<div class="section"> 314<h2><a name="status" id="status">Cache Status and Logging</a></h2> 315 <p>Once <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> has made a decision as to whether or not 316 an entity is to be served from cache, the detailed reason for the decision 317 is written to the subprocess environment within the request under the 318 <strong>cache-status</strong> key. This reason can be logged by the 319 <code class="directive"><a href="/mod/mod_log_config.html#logformat">LogFormat</a></code> directive as 320 follows:</p> 321 322 <pre class="prettyprint lang-config">LogFormat "%{cache-status}e ..."</pre> 323 324 325 <p>Based on the caching decision made, the reason is also written to the 326 subprocess environment under one the following four keys, as appropriate:</p> 327 328 <dl> 329 <dt>cache-hit</dt><dd>The response was served from cache.</dd> 330 <dt>cache-revalidate</dt><dd>The response was stale and was successfully 331 revalidated, then served from cache.</dd> 332 <dt>cache-miss</dt><dd>The response was served from the upstream server.</dd> 333 <dt>cache-invalidate</dt><dd>The cached entity was invalidated by a request 334 method other than GET or HEAD.</dd> 335 </dl> 336 337 <p>This makes it possible to support conditional logging of cached requests 338 as per the following example:</p> 339 340 <pre class="prettyprint lang-config">CustomLog cached-requests.log common env=cache-hit 341CustomLog uncached-requests.log common env=cache-miss 342CustomLog revalidated-requests.log common env=cache-revalidate 343CustomLog invalidated-requests.log common env=cache-invalidate</pre> 344 345 346 <p>For module authors, a hook called <var>cache_status</var> is available, 347 allowing modules to respond to the caching outcomes above in customised 348 ways.</p> 349</div> 350<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 351<div class="directive-section"><h2><a name="CacheDefaultExpire" id="CacheDefaultExpire">CacheDefaultExpire</a> <a name="cachedefaultexpire" id="cachedefaultexpire">Directive</a></h2> 352<table class="directive"> 353<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The default duration to cache a document when no expiry date is specified.</td></tr> 354<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheDefaultExpire <var>seconds</var></code></td></tr> 355<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheDefaultExpire 3600 (one hour)</code></td></tr> 356<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 357<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 358<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 359</table> 360 <p>The <code class="directive">CacheDefaultExpire</code> directive specifies a default time, 361 in seconds, to cache a document if neither an expiry date nor last-modified date are provided 362 with the document. The value specified with the <code class="directive">CacheMaxExpire</code> 363 directive does <em>not</em> override this setting.</p> 364 365 <pre class="prettyprint lang-config">CacheDefaultExpire 86400</pre> 366 367 368</div> 369<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 370<div class="directive-section"><h2><a name="CacheDetailHeader" id="CacheDetailHeader">CacheDetailHeader</a> <a name="cachedetailheader" id="cachedetailheader">Directive</a></h2> 371<table class="directive"> 372<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add an X-Cache-Detail header to the response.</td></tr> 373<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheDetailHeader <var>on|off</var></code></td></tr> 374<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheDetailHeader off</code></td></tr> 375<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 376<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 377<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 378<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.9 and later</td></tr> 379</table> 380 <p>When the <code class="directive"><a href="#cachedetailheader">CacheDetailHeader</a></code> directive 381 is switched on, an <strong>X-Cache-Detail</strong> header will be added to the response 382 containing the detailed reason for a particular caching decision.</p> 383 384 <p>It can be useful during development of cached RESTful services to have additional 385 information about the caching decision written to the response headers, so as to 386 confirm whether <code>Cache-Control</code> and other headers have been correctly 387 used by the service and client.</p> 388 389 <p>If the normal handler is used, this directive may appear within a 390 <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> or 391 <code class="directive"><a href="/mod/core.html#location"><Location></a></code> directive. If the quick handler 392 is used, this directive must appear within a server or virtual host context, otherwise 393 the setting will be ignored.</p> 394 395 <pre class="prettyprint lang-config"># Enable the X-Cache-Detail header 396CacheDetailHeader on</pre> 397 398 399 <div class="example"><p><code> 400 X-Cache-Detail: "conditional cache hit: entity refreshed" from localhost<br /> 401 </code></p></div> 402 403 404</div> 405<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 406<div class="directive-section"><h2><a name="CacheDisable" id="CacheDisable">CacheDisable</a> <a name="cachedisable" id="cachedisable">Directive</a></h2> 407<table class="directive"> 408<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Disable caching of specified URLs</td></tr> 409<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheDisable <var>url-string</var> | <var>on</var></code></td></tr> 410<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 411<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 412<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 413</table> 414 <p>The <code class="directive">CacheDisable</code> directive instructs 415 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> to <em>not</em> cache urls at or below 416 <var>url-string</var>.</p> 417 418 <div class="example"><h3>Example</h3><pre class="prettyprint lang-config">CacheDisable /local_files</pre> 419</div> 420 421 <p>If used in a <code class="directive"><Location></code> directive, 422 the path needs to be specified below the Location, or if the word "on" 423 is used, caching for the whole location will be disabled.</p> 424 425 <div class="example"><h3>Example</h3><pre class="prettyprint lang-config"><Location /foo> 426 CacheDisable on 427</Location></pre> 428</div> 429 430 <p>The <code>no-cache</code> environment variable can be set to 431 disable caching on a finer grained set of resources in versions 432 2.2.12 and later.</p> 433 434 435<h3>See also</h3> 436<ul> 437<li><a href="/env.html">Environment Variables in Apache</a></li> 438</ul> 439</div> 440<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 441<div class="directive-section"><h2><a name="CacheEnable" id="CacheEnable">CacheEnable</a> <a name="cacheenable" id="cacheenable">Directive</a></h2> 442<table class="directive"> 443<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable caching of specified URLs using a specified storage 444manager</td></tr> 445<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheEnable <var>cache_type</var> [<var>url-string</var>]</code></td></tr> 446<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory</td></tr> 447<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 448<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 449<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>A url-string of '/' applied to forward proxy content in 2.2 and 450 earlier.</td></tr> 451</table> 452 <p>The <code class="directive">CacheEnable</code> directive instructs 453 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> to cache urls at or below 454 <var>url-string</var>. The cache storage manager is specified with the 455 <var>cache_type</var> argument. The <code class="directive">CacheEnable</code> 456 directive can alternatively be placed inside either 457 <code class="directive"><Location></code> or 458 <code class="directive"><LocationMatch></code> sections to indicate 459 the content is cacheable. 460 <var>cache_type</var> <code>disk</code> instructs 461 <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> to use the disk based storage manager 462 implemented by <code class="module"><a href="/mod/mod_cache_disk.html">mod_cache_disk</a></code>. <var>cache_type</var> 463 <code>socache</code> instructs <code class="module"><a href="/mod/mod_cache.html">mod_cache</a></code> to use the 464 shared object cache based storage manager implemented by 465 <code class="module"><a href="/mod/mod_cache_socache.html">mod_cache_socache</a></code>.</p> 466 <p>In the event that the URL space overlaps between different 467 <code class="directive">CacheEnable</code> directives (as in the example below), 468 each possible storage manager will be run until the first one that 469 actually processes the request. The order in which the storage managers are 470 run is determined by the order of the <code class="directive">CacheEnable</code> 471 directives in the configuration file. <code class="directive">CacheEnable</code> 472 directives within <code class="directive"><Location></code> or 473 <code class="directive"><LocationMatch></code> sections are processed 474 before globally defined <code class="directive">CacheEnable</code> directives.</p> 475 476 <p>When acting as a forward proxy server, <var>url-string</var> must 477 minimally begin with a protocol for which caching should be enabled.</p> 478 479 <pre class="prettyprint lang-config"># Cache content (normal handler only) 480CacheQuickHandler off 481<Location /foo> 482 CacheEnable disk 483</Location> 484 485# Cache regex (normal handler only) 486CacheQuickHandler off 487<LocationMatch foo$> 488 CacheEnable disk 489</LocationMatch> 490 491# Cache all but forward proxy url's (normal or quick handler) 492CacheEnable disk / 493 494# Cache FTP-proxied url's (normal or quick handler) 495CacheEnable disk ftp:// 496 497# Cache forward proxy content from www.example.org (normal or quick handler) 498CacheEnable disk http://www.example.org/</pre> 499 500 501 <p>A hostname starting with a <strong>"*"</strong> matches all hostnames with 502 that suffix. A hostname starting with <strong>"."</strong> matches all 503 hostnames containing the domain components that follow.</p> 504 505 <pre class="prettyprint lang-config"># Match www.example.org, and fooexample.org 506CacheEnable disk http://*example.org/ 507# Match www.example.org, but not fooexample.org 508CacheEnable disk http://.example.org/</pre> 509 510 511 <p> The <code>no-cache</code> environment variable can be set to 512 disable caching on a finer grained set of resources in versions 513 2.2.12 and later.</p> 514 515 516<h3>See also</h3> 517<ul> 518<li><a href="/env.html">Environment Variables in Apache</a></li> 519</ul> 520</div> 521<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 522<div class="directive-section"><h2><a name="CacheHeader" id="CacheHeader">CacheHeader</a> <a name="cacheheader" id="cacheheader">Directive</a></h2> 523<table class="directive"> 524<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Add an X-Cache header to the response.</td></tr> 525<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheHeader <var>on|off</var></code></td></tr> 526<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheHeader off</code></td></tr> 527<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 528<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 529<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 530<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.9 and later</td></tr> 531</table> 532 <p>When the <code class="directive"><a href="#cacheheader">CacheHeader</a></code> directive 533 is switched on, an <strong>X-Cache</strong> header will be added to the response 534 with the cache status of this response. If the normal handler is used, this 535 directive may appear within a <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> 536 or <code class="directive"><a href="/mod/core.html#location"><Location></a></code> directive. If the quick 537 handler is used, this directive must appear within a server or virtual host 538 context, otherwise the setting will be ignored.</p> 539 540 <dl> 541 <dt><strong>HIT</strong></dt><dd>The entity was fresh, and was served from 542 cache.</dd> 543 <dt><strong>REVALIDATE</strong></dt><dd>The entity was stale, was successfully 544 revalidated and was served from cache.</dd> 545 <dt><strong>MISS</strong></dt><dd>The entity was fetched from the upstream 546 server and was not served from cache.</dd> 547 </dl> 548 549 <pre class="prettyprint lang-config"># Enable the X-Cache header 550CacheHeader on</pre> 551 552 553 <pre class="prettyprint lang-config">X-Cache: HIT from localhost</pre> 554 555 556 557</div> 558<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 559<div class="directive-section"><h2><a name="CacheIgnoreCacheControl" id="CacheIgnoreCacheControl">CacheIgnoreCacheControl</a> <a name="cacheignorecachecontrol" id="cacheignorecachecontrol">Directive</a></h2> 560<table class="directive"> 561<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ignore request to not serve cached content to client</td></tr> 562<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreCacheControl On|Off</code></td></tr> 563<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreCacheControl Off</code></td></tr> 564<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 565<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 566<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 567</table> 568 <p>Ordinarily, requests containing a Cache-Control: no-cache or 569 Pragma: no-cache header value will not be served from the cache. The 570 <code class="directive">CacheIgnoreCacheControl</code> directive allows this 571 behavior to be overridden. <code class="directive">CacheIgnoreCacheControl On</code> 572 tells the server to attempt to serve the resource from the cache even 573 if the request contains no-cache header values. Resources requiring 574 authorization will <em>never</em> be cached.</p> 575 576 <pre class="prettyprint lang-config">CacheIgnoreCacheControl On</pre> 577 578 579 <div class="warning"><h3>Warning:</h3> 580 This directive will allow serving from the cache even if the client has 581 requested that the document not be served from the cache. This might 582 result in stale content being served. 583 </div> 584 585<h3>See also</h3> 586<ul> 587<li><code class="directive"><a href="#cachestoreprivate">CacheStorePrivate</a></code></li> 588<li><code class="directive"><a href="#cachestorenostore">CacheStoreNoStore</a></code></li> 589</ul> 590</div> 591<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 592<div class="directive-section"><h2><a name="CacheIgnoreHeaders" id="CacheIgnoreHeaders">CacheIgnoreHeaders</a> <a name="cacheignoreheaders" id="cacheignoreheaders">Directive</a></h2> 593<table class="directive"> 594<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Do not store the given HTTP header(s) in the cache. 595</td></tr> 596<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreHeaders <var>header-string</var> [<var>header-string</var>] ...</code></td></tr> 597<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreHeaders None</code></td></tr> 598<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 599<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 600<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 601</table> 602 <p>According to RFC 2616, hop-by-hop HTTP headers are not stored in 603 the cache. The following HTTP headers are hop-by-hop headers and thus 604 do not get stored in the cache in <em>any</em> case regardless of the 605 setting of <code class="directive">CacheIgnoreHeaders</code>:</p> 606 607 <ul> 608 <li><code>Connection</code></li> 609 <li><code>Keep-Alive</code></li> 610 <li><code>Proxy-Authenticate</code></li> 611 <li><code>Proxy-Authorization</code></li> 612 <li><code>TE</code></li> 613 <li><code>Trailers</code></li> 614 <li><code>Transfer-Encoding</code></li> 615 <li><code>Upgrade</code></li> 616 </ul> 617 618 <p><code class="directive">CacheIgnoreHeaders</code> specifies additional HTTP 619 headers that should not to be stored in the cache. For example, it makes 620 sense in some cases to prevent cookies from being stored in the cache.</p> 621 622 <p><code class="directive">CacheIgnoreHeaders</code> takes a space separated list 623 of HTTP headers that should not be stored in the cache. If only hop-by-hop 624 headers not should be stored in the cache (the RFC 2616 compliant 625 behaviour), <code class="directive">CacheIgnoreHeaders</code> can be set to 626 <code>None</code>.</p> 627 628 <div class="example"><h3>Example 1</h3><pre class="prettyprint lang-config">CacheIgnoreHeaders Set-Cookie</pre> 629</div> 630 631 <div class="example"><h3>Example 2</h3><pre class="prettyprint lang-config">CacheIgnoreHeaders None</pre> 632</div> 633 634 <div class="warning"><h3>Warning:</h3> 635 If headers like <code>Expires</code> which are needed for proper cache 636 management are not stored due to a 637 <code class="directive">CacheIgnoreHeaders</code> setting, the behaviour of 638 mod_cache is undefined. 639 </div> 640 641</div> 642<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 643<div class="directive-section"><h2><a name="CacheIgnoreNoLastMod" id="CacheIgnoreNoLastMod">CacheIgnoreNoLastMod</a> <a name="cacheignorenolastmod" id="cacheignorenolastmod">Directive</a></h2> 644<table class="directive"> 645<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ignore the fact that a response has no Last Modified 646header.</td></tr> 647<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreNoLastMod On|Off</code></td></tr> 648<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreNoLastMod Off</code></td></tr> 649<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 650<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 651<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 652</table> 653 <p>Ordinarily, documents without a last-modified date are not cached. 654 Under some circumstances the last-modified date is removed (during 655 <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> processing for example) or not provided 656 at all. The <code class="directive">CacheIgnoreNoLastMod</code> directive 657 provides a way to specify that documents without last-modified dates 658 should be considered for caching, even without a last-modified date. 659 If neither a last-modified date nor an expiry date are provided with 660 the document then the value specified by the 661 <code class="directive">CacheDefaultExpire</code> directive will be used to 662 generate an expiration date.</p> 663 664 <pre class="prettyprint lang-config">CacheIgnoreNoLastMod On</pre> 665 666 667</div> 668<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 669<div class="directive-section"><h2><a name="CacheIgnoreQueryString" id="CacheIgnoreQueryString">CacheIgnoreQueryString</a> <a name="cacheignorequerystring" id="cacheignorequerystring">Directive</a></h2> 670<table class="directive"> 671<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ignore query string when caching</td></tr> 672<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreQueryString On|Off</code></td></tr> 673<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreQueryString Off</code></td></tr> 674<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 675<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 676<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 677</table> 678 <p>Ordinarily, requests with query string parameters are cached separately 679 for each unique query string. This is according to RFC 2616/13.9 done only 680 if an expiration time is specified. The 681 <code class="directive">CacheIgnoreQueryString</code> directive tells the cache to 682 cache requests even if no expiration time is specified, and to reply with 683 a cached reply even if the query string differs. From a caching point of 684 view the request is treated as if having no query string when this 685 directive is enabled.</p> 686 687 <pre class="prettyprint lang-config">CacheIgnoreQueryString On</pre> 688 689 690 691</div> 692<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 693<div class="directive-section"><h2><a name="CacheIgnoreURLSessionIdentifiers" id="CacheIgnoreURLSessionIdentifiers">CacheIgnoreURLSessionIdentifiers</a> <a name="cacheignoreurlsessionidentifiers" id="cacheignoreurlsessionidentifiers">Directive</a></h2> 694<table class="directive"> 695<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ignore defined session identifiers encoded in the URL when caching 696</td></tr> 697<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreURLSessionIdentifiers <var>identifier</var> [<var>identifier</var>] ...</code></td></tr> 698<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreURLSessionIdentifiers None</code></td></tr> 699<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 700<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 701<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 702</table> 703 <p>Sometimes applications encode the session identifier into the URL like in the following 704 Examples: 705 </p> 706 <ul> 707 <li><code>/someapplication/image.gif;jsessionid=123456789</code></li> 708 <li><code>/someapplication/image.gif?PHPSESSIONID=12345678</code></li> 709 </ul> 710 <p>This causes cachable resources to be stored separately for each session, which 711 is often not desired. <code class="directive">CacheIgnoreURLSessionIdentifiers</code> lets 712 define a list of identifiers that are removed from the key that is used to identify 713 an entity in the cache, such that cachable resources are not stored separately for 714 each session. 715 </p> 716 <p><code>CacheIgnoreURLSessionIdentifiers None</code> clears the list of ignored 717 identifiers. Otherwise, each identifier is added to the list.</p> 718 719 <div class="example"><h3>Example 1</h3><pre class="prettyprint lang-config">CacheIgnoreURLSessionIdentifiers jsessionid</pre> 720</div> 721 722 <div class="example"><h3>Example 2</h3><pre class="prettyprint lang-config">CacheIgnoreURLSessionIdentifiers None</pre> 723</div> 724 725 726</div> 727<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 728<div class="directive-section"><h2><a name="CacheKeyBaseURL" id="CacheKeyBaseURL">CacheKeyBaseURL</a> <a name="cachekeybaseurl" id="cachekeybaseurl">Directive</a></h2> 729<table class="directive"> 730<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Override the base URL of reverse proxied cache keys.</td></tr> 731<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheKeyBaseURL <var>URL</var></code></td></tr> 732<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheKeyBaseURL http://example.com</code></td></tr> 733<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 734<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 735<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 736<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.9 and later</td></tr> 737</table> 738 <p>When the <code class="directive"><a href="#cachekeybaseurl">CacheKeyBaseURL</a></code> directive 739 is specified, the URL provided will be used as the base URL to calculate 740 the URL of the cache keys in the reverse proxy configuration. When not specified, 741 the scheme, hostname and port of the current virtual host is used to construct 742 the cache key. When a cluster of machines is present, and all cached entries 743 should be cached beneath the same cache key, a new base URL can be specified 744 with this directive.</p> 745 746 <pre class="prettyprint lang-config"># Override the base URL of the cache key. 747CacheKeyBaseURL http://www.example.com/</pre> 748 749 750 <div class="warning">Take care when setting this directive. If two separate virtual 751 hosts are accidentally given the same base URL, entries from one virtual host 752 will be served to the other.</div> 753 754 755</div> 756<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 757<div class="directive-section"><h2><a name="CacheLastModifiedFactor" id="CacheLastModifiedFactor">CacheLastModifiedFactor</a> <a name="cachelastmodifiedfactor" id="cachelastmodifiedfactor">Directive</a></h2> 758<table class="directive"> 759<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The factor used to compute an expiry date based on the 760LastModified date.</td></tr> 761<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLastModifiedFactor <var>float</var></code></td></tr> 762<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLastModifiedFactor 0.1</code></td></tr> 763<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 764<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 765<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 766</table> 767 <p>In the event that a document does not provide an expiry date but does 768 provide a last-modified date, an expiry date can be calculated based on 769 the time since the document was last modified. The 770 <code class="directive">CacheLastModifiedFactor</code> directive specifies a 771 <var>factor</var> to be used in the generation of this expiry date 772 according to the following formula: 773 774 <code>expiry-period = time-since-last-modified-date * <var>factor</var> 775 expiry-date = current-date + expiry-period</code> 776 777 For example, if the document was last modified 10 hours ago, and 778 <var>factor</var> is 0.1 then the expiry-period will be set to 779 10*0.1 = 1 hour. If the current time was 3:00pm then the computed 780 expiry-date would be 3:00pm + 1hour = 4:00pm. 781 782 If the expiry-period would be longer than that set by 783 <code class="directive">CacheMaxExpire</code>, then the latter takes 784 precedence.</p> 785 786 <pre class="prettyprint lang-config">CacheLastModifiedFactor 0.5</pre> 787 788 789</div> 790<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 791<div class="directive-section"><h2><a name="CacheLock" id="CacheLock">CacheLock</a> <a name="cachelock" id="cachelock">Directive</a></h2> 792<table class="directive"> 793<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable the thundering herd lock.</td></tr> 794<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLock <var>on|off</var></code></td></tr> 795<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLock off</code></td></tr> 796<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 797<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 798<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 799<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.2.15 and later</td></tr> 800</table> 801 <p>The <code class="directive">CacheLock</code> directive enables the thundering herd lock 802 for the given URL space.</p> 803 804 <p>In a minimal configuration the following directive is all that is needed to 805 enable the thundering herd lock in the default system temp directory.</p> 806 807 <pre class="prettyprint lang-config"># Enable cache lock 808CacheLock on</pre> 809 810 811 812</div> 813<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 814<div class="directive-section"><h2><a name="CacheLockMaxAge" id="CacheLockMaxAge">CacheLockMaxAge</a> <a name="cachelockmaxage" id="cachelockmaxage">Directive</a></h2> 815<table class="directive"> 816<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the maximum possible age of a cache lock.</td></tr> 817<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLockMaxAge <var>integer</var></code></td></tr> 818<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLockMaxAge 5</code></td></tr> 819<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 820<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 821<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 822</table> 823 <p>The <code class="directive">CacheLockMaxAge</code> directive specifies the maximum 824 age of any cache lock.</p> 825 826 <p>A lock older than this value in seconds will be ignored, and the next 827 incoming request will be given the opportunity to re-establish the lock. 828 This mechanism prevents a slow client taking an excessively long time to refresh 829 an entity.</p> 830 831 832</div> 833<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 834<div class="directive-section"><h2><a name="CacheLockPath" id="CacheLockPath">CacheLockPath</a> <a name="cachelockpath" id="cachelockpath">Directive</a></h2> 835<table class="directive"> 836<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the lock path directory.</td></tr> 837<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLockPath <var>directory</var></code></td></tr> 838<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLockPath /tmp/mod_cache-lock</code></td></tr> 839<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 840<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 841<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 842</table> 843 <p>The <code class="directive">CacheLockPath</code> directive allows you to specify the 844 directory in which the locks are created. By default, the system's temporary 845 folder is used. Locks consist of empty files that only exist for stale URLs 846 in flight, so is significantly less resource intensive than the traditional 847 disk cache.</p> 848 849 850</div> 851<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 852<div class="directive-section"><h2><a name="CacheMaxExpire" id="CacheMaxExpire">CacheMaxExpire</a> <a name="cachemaxexpire" id="cachemaxexpire">Directive</a></h2> 853<table class="directive"> 854<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The maximum time in seconds to cache a document</td></tr> 855<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheMaxExpire <var>seconds</var></code></td></tr> 856<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheMaxExpire 86400 (one day)</code></td></tr> 857<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 858<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 859<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 860</table> 861 <p>The <code class="directive">CacheMaxExpire</code> directive specifies the maximum number of 862 seconds for which cachable HTTP documents will be retained without checking the origin 863 server. Thus, documents will be out of date at most this number of seconds. This maximum 864 value is enforced even if an expiry date was supplied with the document.</p> 865 866 <pre class="prettyprint lang-config">CacheMaxExpire 604800</pre> 867 868 869</div> 870<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 871<div class="directive-section"><h2><a name="CacheMinExpire" id="CacheMinExpire">CacheMinExpire</a> <a name="cacheminexpire" id="cacheminexpire">Directive</a></h2> 872<table class="directive"> 873<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The minimum time in seconds to cache a document</td></tr> 874<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheMinExpire <var>seconds</var></code></td></tr> 875<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheMinExpire 0</code></td></tr> 876<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 877<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 878<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 879</table> 880 <p>The <code class="directive">CacheMinExpire</code> directive specifies the minimum number of 881 seconds for which cachable HTTP documents will be retained without checking the origin 882 server. This is only used if no valid expire time was supplied with the document.</p> 883 884 885 <pre class="prettyprint lang-config">CacheMinExpire 3600</pre> 886 887 888</div> 889<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 890<div class="directive-section"><h2><a name="CacheQuickHandler" id="CacheQuickHandler">CacheQuickHandler</a> <a name="cachequickhandler" id="cachequickhandler">Directive</a></h2> 891<table class="directive"> 892<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Run the cache from the quick handler.</td></tr> 893<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheQuickHandler <var>on|off</var></code></td></tr> 894<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheQuickHandler on</code></td></tr> 895<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 896<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 897<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 898<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Apache HTTP Server 2.3.3 and later</td></tr> 899</table> 900 <p>The <code class="directive"><a href="#cachequickhandler">CacheQuickHandler</a></code> directive 901 controls the phase in which the cache is handled.</p> 902 903 <p>In the default enabled configuration, the cache operates within the quick 904 handler phase. This phase short circuits the majority of server processing, 905 and represents the most performant mode of operation for a typical server. 906 The cache <strong>bolts onto</strong> the front of the server, and the 907 majority of server processing is avoided.</p> 908 909 <p>When disabled, the cache operates as a normal handler, and is subject to 910 the full set of phases when handling a server request. While this mode is 911 slower than the default, it allows the cache to be used in cases where full 912 processing is required, such as when content is subject to authorisation.</p> 913 914 <pre class="prettyprint lang-config"># Run cache as a normal handler 915CacheQuickHandler off</pre> 916 917 918 <p>It is also possible, when the quick handler is disabled, for the 919 administrator to choose the precise location within the filter chain where 920 caching is to be performed, by adding the <strong>CACHE</strong> filter to 921 the chain.</p> 922 923 <pre class="prettyprint lang-config"># Cache content before mod_include and mod_deflate 924CacheQuickHandler off 925AddOutputFilterByType CACHE;INCLUDES;DEFLATE text/html</pre> 926 927 928 <p>If the CACHE filter is specified more than once, the last instance will 929 apply.</p> 930 931 932</div> 933<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 934<div class="directive-section"><h2><a name="CacheStaleOnError" id="CacheStaleOnError">CacheStaleOnError</a> <a name="cachestaleonerror" id="cachestaleonerror">Directive</a></h2> 935<table class="directive"> 936<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Serve stale content in place of 5xx responses.</td></tr> 937<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheStaleOnError <var>on|off</var></code></td></tr> 938<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheStaleOnError on</code></td></tr> 939<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 940<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 941<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 942<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 2.3.9 and later</td></tr> 943</table> 944 <p>When the <code class="directive"><a href="#cachestaleonerror">CacheStaleOnError</a></code> directive 945 is switched on, and when stale data is available in the cache, the cache will 946 respond to 5xx responses from the backend by returning the stale data instead of 947 the 5xx response. While the Cache-Control headers sent by clients will be respected, 948 and the raw 5xx responses returned to the client on request, the 5xx response so 949 returned to the client will not invalidate the content in the cache.</p> 950 951 <pre class="prettyprint lang-config"># Serve stale data on error. 952CacheStaleOnError on</pre> 953 954 955 956</div> 957<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 958<div class="directive-section"><h2><a name="CacheStoreExpired" id="CacheStoreExpired">CacheStoreExpired</a> <a name="cachestoreexpired" id="cachestoreexpired">Directive</a></h2> 959<table class="directive"> 960<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to cache responses that the server reports as expired</td></tr> 961<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheStoreExpired On|Off</code></td></tr> 962<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheStoreExpired Off</code></td></tr> 963<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 964<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 965<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 966</table> 967 <p>Since httpd 2.2.4, responses which have already expired are not 968 stored in the cache. The <code class="directive">CacheStoreExpired</code> 969 directive allows this behavior to be overridden. 970 <code class="directive">CacheStoreExpired</code> On 971 tells the server to attempt to cache the resource if it is stale. 972 Subsequent requests would trigger an If-Modified-Since request of 973 the origin server, and the response may be fulfilled from cache 974 if the backend resource has not changed.</p> 975 976 <pre class="prettyprint lang-config">CacheStoreExpired On</pre> 977 978 979</div> 980<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 981<div class="directive-section"><h2><a name="CacheStoreNoStore" id="CacheStoreNoStore">CacheStoreNoStore</a> <a name="cachestorenostore" id="cachestorenostore">Directive</a></h2> 982<table class="directive"> 983<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to cache requests or responses that have been marked as no-store.</td></tr> 984<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheStoreNoStore On|Off</code></td></tr> 985<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheStoreNoStore Off</code></td></tr> 986<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 987<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 988<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 989</table> 990 <p>Ordinarily, requests or responses with Cache-Control: no-store header 991 values will not be stored in the cache. The 992 <code class="directive">CacheStoreNoStore</code> directive allows this 993 behavior to be overridden. <code class="directive">CacheStoreNoStore</code> On 994 tells the server to attempt to cache the resource even if it contains 995 no-store header values. Resources requiring authorization will 996 <em>never</em> be cached.</p> 997 998 <pre class="prettyprint lang-config">CacheStoreNoStore On</pre> 999 1000 1001 <div class="warning"><h3>Warning:</h3> 1002 As described in RFC 2616, the no-store directive is intended to 1003 "prevent the inadvertent release or retention of sensitive information 1004 (for example, on backup tapes)." Enabling this option could store 1005 sensitive information in the cache. You are hereby warned. 1006 </div> 1007 1008<h3>See also</h3> 1009<ul> 1010<li><code class="directive"><a href="#cacheignorecachecontrol">CacheIgnoreCacheControl</a></code></li> 1011<li><code class="directive"><a href="#cachestoreprivate">CacheStorePrivate</a></code></li> 1012</ul> 1013</div> 1014<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 1015<div class="directive-section"><h2><a name="CacheStorePrivate" id="CacheStorePrivate">CacheStorePrivate</a> <a name="cachestoreprivate" id="cachestoreprivate">Directive</a></h2> 1016<table class="directive"> 1017<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Attempt to cache responses that the server has marked as private</td></tr> 1018<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheStorePrivate On|Off</code></td></tr> 1019<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheStorePrivate Off</code></td></tr> 1020<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 1021<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr> 1022<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr> 1023</table> 1024 <p>Ordinarily, responses with Cache-Control: private header values will not 1025 be stored in the cache. The <code class="directive">CacheStorePrivate</code> 1026 directive allows this behavior to be overridden. 1027 <code class="directive">CacheStorePrivate</code> On 1028 tells the server to attempt to cache the resource even if it contains 1029 private header values. Resources requiring authorization will 1030 <em>never</em> be cached.</p> 1031 1032 <pre class="prettyprint lang-config">CacheStorePrivate On</pre> 1033 1034 1035 <div class="warning"><h3>Warning:</h3> 1036 This directive will allow caching even if the upstream server has 1037 requested that the resource not be cached. This directive is only 1038 ideal for a 'private' cache. 1039 </div> 1040 1041<h3>See also</h3> 1042<ul> 1043<li><code class="directive"><a href="#cacheignorecachecontrol">CacheIgnoreCacheControl</a></code></li> 1044<li><code class="directive"><a href="#cachestorenostore">CacheStoreNoStore</a></code></li> 1045</ul> 1046</div> 1047</div> 1048<div class="bottomlang"> 1049<p><span>Available Languages: </span><a href="/en/mod/mod_cache.html" title="English"> en </a> | 1050<a href="/fr/mod/mod_cache.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 1051<a href="/ja/mod/mod_cache.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a> | 1052<a href="/ko/mod/mod_cache.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p> 1053</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 1054<script type="text/javascript"><!--//--><![CDATA[//><!-- 1055var comments_shortname = 'httpd'; 1056var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_cache.html'; 1057(function(w, d) { 1058 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 1059 d.write('<div id="comments_thread"><\/div>'); 1060 var s = d.createElement('script'); 1061 s.type = 'text/javascript'; 1062 s.async = true; 1063 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 1064 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 1065 } 1066 else { 1067 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 1068 } 1069})(window, document); 1070//--><!]]></script></div><div id="footer"> 1071<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 1072<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 1073if (typeof(prettyPrint) !== 'undefined') { 1074 prettyPrint(); 1075} 1076//--><!]]></script> 1077</body></html>
