From: Graham Leggett Date: Mon, 1 Nov 2010 09:50:42 +0000 (+0000) Subject: Add documentation for mod_cache and mod_disk_cache. X-Git-Tag: 2.3.9~196 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=7b8e03425f65d356a988955aa69d26e537ea166b;p=thirdparty%2Fapache%2Fhttpd.git Add documentation for mod_cache and mod_disk_cache. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1029587 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_cache.xml b/docs/manual/mod/mod_cache.xml index 5c3579eae8a..fa6f493412b 100644 --- a/docs/manual/mod/mod_cache.xml +++ b/docs/manual/mod/mod_cache.xml @@ -23,7 +23,7 @@ mod_cache -Content cache keyed to URIs. +RFC 2616 compliant HTTP caching filter. Extension mod_cache.c cache_module @@ -39,18 +39,81 @@ variable.

mod_cache implements an RFC 2616 compliant HTTP - content cache that can be used to cache either local or proxied content. - mod_cache requires the services of one or more storage - management modules. One storage management module is included in + href="http://www.ietf.org/rfc/rfc2616.txt">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 honouring the + If-None-Match + 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 + and + Pragma + 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 behaviour, however such behaviour 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 + 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 behaviour is supported by default by + mod_cache. Such responses will contain a + Warning + HTTP header with a 111 response code.

+ +

mod_cache requires the services of one or more + storage management modules. One storage management module is included in the base Apache distribution:

mod_disk_cache
-
implements a disk based storage manager.
+
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.
-

Content is stored in and retrieved from the cache using URI based keys. Content with - access protection is not cached.

Further details, discussion, and examples, are provided in the Caching Guide.

@@ -167,7 +230,7 @@ cache performance available.

In this mode, the cache bolts onto the front of the server, - acting as if a free standing RFC2616 caching proxy had been placed in front of + acting as if a free standing RFC 2616 caching proxy had been placed in front of the server.

While this mode offers the best performance, the administrator may find that diff --git a/docs/manual/mod/mod_disk_cache.xml b/docs/manual/mod/mod_disk_cache.xml index 14d9a62b3e3..3bf2cd69784 100644 --- a/docs/manual/mod/mod_disk_cache.xml +++ b/docs/manual/mod/mod_disk_cache.xml @@ -23,21 +23,32 @@ mod_disk_cache -Content cache storage manager keyed to URIs +Disk based storage module for the HTTP caching filter. Extension mod_disk_cache.c disk_cache_module

mod_disk_cache implements a disk based storage - manager. It is primarily of use in conjunction with - mod_cache.

+ manager for mod_cache.

-

Content is stored in and retrieved from the cache using URI based - keys. Content with access protection is not cached.

+

The headers and bodies of cached responses are stored separately on + disk, in a directory structure derived from the md5 hash of the cached + URL.

-

htcacheclean can be used to maintain the cache - size at a maximum level.

+

Multiple content negotiated responses can be stored concurrently, + however the caching of partial content is not yet supported by this + module.

+ +

Atomic cache updates to both header and body files are achieved + without the need for locking by storing the device and inode numbers of + the body file within the header file. This has the side effect that + cache entries manually moved into the cache will be ignored.

+ +

The htcacheclean tool is provided to list cached + URLs, remove cached URLs, or to maintain the size of the disk cache + within size and/or inode limits. The tool can be run on demand, or + can be daemonized to offer continuous monitoring of directory sizes.

Note:

mod_disk_cache requires the services of