Text of httpd.apache.org › docs › current › mod › mod_cache.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

mod_cache - Apache HTTP Server Version 2.4

Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.4 Apache > HTTP Server > Documentation > Version 2.4 > Modules Apache Module mod_cache Available Languages: en | fr | ja | ko Description: RFC 2616 compliant HTTP caching filter. Status: Extension Module Identifier: cache_module Source File: mod_cache.c Summary This module should be used with care, as when the CacheQuickHandler directive is in its default value of on , the Allow and Deny directives will be circumvented.

You should not enable quick handler caching for any content to which you wish to limit access by client host name, address or environment variable. mod_cache implements an RFC 2616 compliant HTTP content caching filter , with support for the caching of content negotiated responses containing the Vary header. RFC 2616 compliant caching provides a mechanism to verify whether stale or expired content is still fresh, and can represent a significant performance boost when the origin server supports conditional requests by honoring the If-None-Match ( RFC 2616 ) HTTP request header.

Content is only regenerated from scratch when the content has changed, and not when the cached entry expires. As a filter, mod_cache can be placed in front of content originating from any handler, including flat files (served from a slow disk cached on a fast disk), the output of a CGI script or dynamic content generator , or content proxied from another server . In the default configuration, mod_cache inserts the caching filter as far forward as possible within the filter stack, utilising the quick handler to bypass all per request processing when returning content to the client.

In this mode of operation, mod_cache may be thought of as a caching proxy server bolted to the front of the webserver, while running within the webserver itself. When the quick handler is switched off using the CacheQuickHandler directive, it becomes possible to insert the CACHE filter at a point in the filter stack chosen by the administrator. This provides the opportunity to cache content before that content is personalised by the mod_include filter, or optionally compressed by the mod_deflate filter.

Under normal operation, mod_cache will respond to and can be controlled by the Cache-Control ( RFC 2616 ) and Pragma ( RFC 2616 ) headers sent from a client in a request, or from a server within a response. Under exceptional circumstances, mod_cache can be configured to override these headers and force site specific behavior, however such behavior will be limited to this cache only, and will not affect the operation of other caches that may exist between the client and server, and as a result is not recommended unless strictly necessary.

RFC 2616 allows for the cache to return stale data while the existing stale entry is refreshed from the origin server, and this is supported by mod_cache when the CacheLock directive is suitably configured. Such responses will contain a Warning ( RFC 2616 ) HTTP header with a 110 response code. RFC 2616 also allows a cache to return stale data when the attempt made to refresh the stale data returns an error 500 or above, and this behavior is supported by default by mod_cache .

Such responses will contain a Warning ( RFC 2616 ) HTTP header with a 111 response code. mod_cache requires the services of one or more storage management modules. The following storage management modules are included in the base Apache distribution: mod_cache_disk Implements a disk based storage manager. Headers and bodies are stored separately on disk, in a directory structure derived from the md5 hash of the cached URL.

Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not supported by this module. The htcacheclean tool is provided to list cached URLs, remove cached URLs, or to maintain the size of the disk cache within size and inode limits. mod_cache_socache Implements a shared object cache based storage manager. Headers and bodies are stored together beneath a single key based on the URL of the response being cached.

Multiple content negotiated responses can be stored concurrently, however the caching of partial content is not supported by this module. Further details, discussion, and examples, are provided in the Caching Guide . Topics Related Modules and Directives Sample Configuration Avoiding the Thundering Herd Fine Control with the CACHE Filter Cache Status and Logging Directives CacheDefaultExpire CacheDetailHeader CacheDisable CacheEnable CacheHeader CacheIgnoreCacheControl CacheIgnoreHeaders CacheIgnoreNoLastMod CacheIgnoreQueryString CacheIgnoreURLSessionIdentifiers CacheKeyBaseURL CacheLastModifiedFactor CacheLock CacheLockMaxAge CacheLockPath CacheMaxExpire CacheMinExpire CacheQuickHandler CacheStaleOnError CacheStoreExpired CacheStoreNoStore CacheStorePrivate Bugfix checklist httpd changelog Known issues Report a bug See also Caching Guide Related Modules and Directives ¶ Related Modules Related Directives mod_cache_disk mod_cache_socache CacheRoot CacheDirLevels CacheDirLength CacheMinFileSize CacheMaxFileSize CacheSocache CacheSocacheMaxTime CacheSocacheMinTime CacheSocacheMaxSize CacheSocacheReadSize CacheSocacheReadTime Sample Configuration ¶ Sample httpd.conf # # Sample Cache Configuration # LoadModule cache_module modules/mod_cache.so <IfModule mod_cache.c> LoadModule cache_disk_module modules/mod_cache_disk.so <IfModule mod_cache_disk.c> CacheRoot "c:/cacheroot" CacheEnable disk "/" CacheDirLevels 5 CacheDirLength 3 </IfModule> # When acting as a proxy, don't cache the list of security updates CacheDisable "http://security.update.server/update-list/" </IfModule> Avoiding the Thundering Herd ¶ When a cached entry becomes stale, mod_cache 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.

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 thundering herd of requests to strike the backend suddenly and unpredictably. To keep the thundering herd at bay, the CacheLock directive can be used to define a directory in which locks are created for URLs in flight .

The lock is used as a hint 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). Initial caching of an entry 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. Refreshment of a stale entry 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.

Locks and Cache-Control: no-cache Locks are used as a hint only 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 honored immediately and the cached entry refreshed. 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 ag

The rest of this page is on the live site.