<li><img alt="" src="../images/down.gif" /> <a href="#cacheignoreheaders">CacheIgnoreHeaders</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cacheignorenolastmod">CacheIgnoreNoLastMod</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cacheignorequerystring">CacheIgnoreQueryString</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cacheignoreurlsessionidentifiers">CacheIgnoreURLSessionIdentifiers</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachelastmodifiedfactor">CacheLastModifiedFactor</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cachelock">CacheLock</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cachelockmaxage">CacheLockMaxAge</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#cachelockpath">CacheLockPath</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachemaxexpire">CacheMaxExpire</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cacheminexpire">CacheMinExpire</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#cachestorenostore">CacheStoreNoStore</a></li>
<ul id="topics">
<li><img alt="" src="../images/down.gif" /> <a href="#related">Related Modules and Directives</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#sampleconf">Sample Configuration</a></li>
+<li><img alt="" src="../images/down.gif" /> <a href="#thunderingherd">Avoiding the Thundering Herd</a></li>
</ul><h3>See also</h3>
<ul class="seealso">
<li><a href="../caching.html">Caching Guide</a></li>
</span>
</IfModule>
</code></p></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="section">
+<h2><a name="thunderingherd" id="thunderingherd">Avoiding the Thundering Herd</a></h2>
+ <p>When a cached entry becomes stale, <code class="module"><a href="../mod/mod_cache.html">mod_cache</a></code> will submit
+ a conditional request to the backend, which is expected to confirm whether the
+ cached entry is still fresh, and send an updated entity if not.</p>
+ <p>A small but finite amount of time exists between the time the cached entity
+ becomes stale, and the time the stale entity is fully refreshed. On a busy
+ server, a significant number of requests might arrive during this time, and
+ cause a <strong>thundering herd</strong> of requests to strike the backend
+ suddenly and unpredicably.</p>
+ <p>To keep the thundering herd at bay, the <code class="directive">CacheLock</code>
+ directive can be used to define a directory in which locks are created for
+ URLs <strong>in flight</strong>. The lock is used as a <strong>hint</strong>
+ by other requests to either suppress an attempt to cache (someone else has
+ gone to fetch the entity), or to indicate that a stale entry is being refreshed
+ (stale content will be returned in the mean time).
+ </p>
+ <h3>Initial caching of an entry</h3>
+
+ <p>When an entity is cached for the first time, a lock will be created for the
+ entity until the response has been fully cached. During the lifetime of the
+ lock, the cache will suppress the second and subsequent attempt to cache the
+ same entity. While this doesn't hold back the thundering herd, it does stop
+ the cache attempting to cache the same entity multiple times simultaneously.
+ </p>
+
+ <h3>Refreshment of a stale entry</h3>
+
+ <p>When an entity reaches its freshness lifetime and becomes stale, a lock
+ will be created for the entity until the response has either been confirmed as
+ still fresh, or replaced by the backend. During the lifetime of the lock, the
+ second and subsequent incoming request will cause stale data to be returned,
+ and the thundering herd is kept at bay.</p>
+
+ <h3>Locks and Cache-Control: no-cache</h3>
+
+ <p>Locks are used as a <strong>hint only</strong> to enable the cache to be
+ more gentle on backend servers, however the lock can be overridden if necessary.
+ If the client sends a request with a Cache-Control header forcing a reload, any
+ lock that may be present will be ignored, and the client's request will be
+ honoured immediately and the cached entry refreshed.</p>
+ <p>As a further safety mechanism, locks have a configurable maximum age.
+ Once this age has been reached, the lock is removed, and a new request is
+ given the opportunity to create a new lock. This maximum age can be set using
+ the <code class="directive">CacheLockMaxAge</code> directive, and defaults to 5
+ seconds.
+ </p>
+
+ <h3>Example configuration</h3>
+
+ <div class="example"><h3>Enabling the cache lock</h3><p><code>
+ #<br />
+ # Enable the cache lock<br />
+ #<br />
+ <IfModule mod_cache.c><br />
+ <span class="indent">
+ CacheLock on<br />
+ CacheLockPath /tmp/mod_cache-lock<br />
+ CacheLockMaxAge 5<br />
+ </span>
+ </IfModule>
+ </code></p></div>
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheDefaultExpire" id="CacheDefaultExpire">CacheDefaultExpire</a> <a name="cachedefaultexpire" id="cachedefaultexpire">Directive</a></h2>
</code></p></div>
<p> The <code>no-cache</code> environment variable can be set to
- disable caching on a finer grained set of resources.</p>
+ disable caching on a finer grained set of resources in versions
+ 2.2.12 and later.</p>
+
<h3>See also</h3>
<ul>
</code></p></div>
<p> The <code>no-cache</code> environment variable can be set to
- disable caching on a finer grained set of resources.</p>
+ disable caching on a finer grained set of resources in versions
+ 2.2.12 and later.</p>
<h3>See also</h3>
<p>Ordinarily, requests containing a Cache-Control: no-cache or
Pragma: no-cache header value will not be served from the cache. The
<code class="directive">CacheIgnoreCacheControl</code> directive allows this
- behavior to be overridden. <code class="directive">CacheIgnoreCacheControl</code>
- On tells the server to attempt to serve the resource from the cache even
+ behavior to be overridden. <code class="directive">CacheIgnoreCacheControl On</code>
+ tells the server to attempt to serve the resource from the cache even
if the request contains no-cache header values. Resources requiring
authorization will <em>never</em> be cached.</p>
</code></p></div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheIgnoreURLSessionIdentifiers" id="CacheIgnoreURLSessionIdentifiers">CacheIgnoreURLSessionIdentifiers</a> <a name="cacheignoreurlsessionidentifiers" id="cacheignoreurlsessionidentifiers">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Ignore defined session identifiers encoded in the URL when caching
+</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheIgnoreURLSessionIdentifiers <var>identifier</var> [<var>identifier</var>] ...</code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheIgnoreURLSessionIdentifiers None</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr>
+</table>
+ <p>Sometimes applications encode the session identifier into the URL like in the following
+ Examples:
+ </p>
+ <ul>
+ <li><code>/someapplication/image.gif;jsessionid=123456789</code></li>
+ <li><code>/someapplication/image.gif?PHPSESSIONID=12345678</code></li>
+ </ul>
+ <p>This causes cachable resources to be stored separately for each session, which
+ is often not desired. <code class="directive">CacheIgnoreURLSessionIdentifiers</code> lets
+ define a list of identifiers that are removed from the key that is used to identify
+ an entity in the cache, such that cachable resources are not stored separately for
+ each session.
+ </p>
+ <p><code>CacheIgnoreURLSessionIdentifiers None</code> clears the list of ignored
+ identifiers. Otherwise, each identifier is added to the list.</p>
+
+ <div class="example"><h3>Example 1</h3><p><code>
+ CacheIgnoreURLSessionIdentifiers jsessionid
+ </code></p></div>
+
+ <div class="example"><h3>Example 2</h3><p><code>
+ CacheIgnoreURLSessionIdentifiers None
+ </code></p></div>
+
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheLastModifiedFactor" id="CacheLastModifiedFactor">CacheLastModifiedFactor</a> <a name="cachelastmodifiedfactor" id="cachelastmodifiedfactor">Directive</a></h2>
CacheLastModifiedFactor 0.5
</code></p></div>
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheLock" id="CacheLock">CacheLock</a> <a name="cachelock" id="cachelock">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enable the thundering herd lock.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLock <var>on|off</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLock off</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr>
+</table>
+ <p>The <code class="directive">CacheLock</code> directive enables the thundering herd lock
+ for the given URL space.</p>
+
+ <p>In a minimal configuration the following directive is all that is needed to
+ enable the thundering herd lock in the default system temp directory.</p>
+
+ <div class="example"><p><code>
+ # Enable cache lock<br />
+ CacheLock on<br /><br />
+ </code></p></div>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheLockMaxAge" id="CacheLockMaxAge">CacheLockMaxAge</a> <a name="cachelockmaxage" id="cachelockmaxage">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the maximum possible age of a cache lock.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLockMaxAge <var>integer</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLockMaxAge 5</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr>
+</table>
+ <p>The <code class="directive">CacheLockMaxAge</code> directive specifies the maximum
+ age of any cache lock.</p>
+
+ <p>A lock older than this value in seconds will be ignored, and the next
+ incoming request will be given the opportunity to re-establish the lock.
+ This mechanism prevents a slow client taking an excessively long time to refresh
+ an entity.</p>
+
+
+</div>
+<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+<div class="directive-section"><h2><a name="CacheLockPath" id="CacheLockPath">CacheLockPath</a> <a name="cachelockpath" id="cachelockpath">Directive</a></h2>
+<table class="directive">
+<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Set the lock path directory.</td></tr>
+<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheLockPath <var>directory</var></code></td></tr>
+<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheLockPath /tmp/mod_cache-lock</code></td></tr>
+<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
+<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
+<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_cache</td></tr>
+</table>
+ <p>The <code class="directive">CacheLockPath</code> directive allows you to specify the
+ directory in which the locks are created. By default, the system's temporary
+ folder is used. Locks consist of empty files that only exist for stale URLs
+ in flight, so is significantly less resource intensive than the traditional
+ disk cache.</p>
+
+
</div>
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="directive-section"><h2><a name="CacheMaxExpire" id="CacheMaxExpire">CacheMaxExpire</a> <a name="cachemaxexpire" id="cachemaxexpire">Directive</a></h2>