Text of httpd.apache.org › docs › trunk › caching.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

Caching Guide - Apache HTTP Server Version 2.5

Modules | Directives | FAQ | Glossary | Sitemap | Report a bug Apache HTTP Server Version 2.5 Apache > HTTP Server > Documentation > Version 2.5 Caching Guide Available Languages: en | fr | tr This document supplements the mod_cache , mod_cache_disk , mod_file_cache and htcacheclean reference documentation. It describes how to use the Apache HTTP Server's caching features to accelerate web and proxy serving, while avoiding common problems and misconfigurations.

Introduction Three-state RFC2616 HTTP caching Cache Setup Examples General Two-state Key/Value Shared Object Caching Specialized File Caching Security Considerations Introduction ¶ The Apache HTTP server offers a range of caching features that are designed to improve the performance of the server in various ways. Three-state RFC2616 HTTP caching mod_cache and its provider modules mod_cache_disk provide intelligent, HTTP-aware caching.

The content itself is stored in the cache, and mod_cache aims to honor all of the various HTTP headers and options that control the cacheability of content as described in RFC 2616 . mod_cache is aimed at both simple and complex caching configurations, where you are dealing with proxied content, dynamic local content or have a need to speed up access to local files on a potentially slow disk. Two-state key/value shared object caching The shared object cache API (socache) and its provider modules provide a server wide key/value based shared object cache.

These modules are designed to cache low level data such as SSL sessions and authentication credentials. Backends allow the data to be stored server wide in shared memory, or datacenter wide in a cache such as memcache or distcache. Specialized file caching mod_file_cache offers the ability to pre-load files into memory on server startup, and can improve access times and save file handles on files that are accessed often, as there is no need to go to disk on each request.

To get the most from this document, you should be familiar with the basics of HTTP, and have read the Users' Guides to Mapping URLs to the Filesystem and Content negotiation . Three-state RFC2616 HTTP caching ¶ Related Modules Related Directives mod_cache mod_cache_disk CacheEnable CacheDisable UseCanonicalName CacheNegotiatedDocs The HTTP protocol contains built in support for an in-line caching mechanism RFC 2616 , and the mod_cache module can be used to take advantage of this.

Unlike a simple two state key/value cache where the content disappears completely when no longer fresh, an HTTP cache includes a mechanism to retain stale content, and to ask the origin server whether this stale content has changed and if not, make it fresh again. An entry in an HTTP cache exists in one of three states: Fresh If the content is new enough (younger than its freshness lifetime ), it is considered fresh .

An HTTP cache is free to serve fresh content without making any calls to the origin server at all. Stale If the content is too old (older than its freshness lifetime ), it is considered stale . An HTTP cache should contact the origin server and check whether the content is still fresh before serving stale content to a client. The origin server will either respond with replacement content if not still valid, or ideally, the origin server will respond with a code to tell the cache the content is still fresh, without the need to generate or send the content again.

The content becomes fresh again and the cycle continues. The HTTP protocol does allow the cache to serve stale data under certain circumstances, such as when an attempt to freshen the data with an origin server has failed with a 5xx error, or when another request is already in the process of freshening the given entry. In these cases a Warning header is added to the response. Non Existent If the cache gets full, it reserves the option to delete content from the cache to make space.

Content can be deleted at any time, and can be stale or fresh. The htcacheclean tool can be run on a once off basis, or deployed as a daemon to keep the size of the cache within the given size, or the given number of inodes. The tool attempts to delete stale content before attempting to delete fresh content. Full details of how HTTP caching works can be found in RFC 2616 . Interaction with the Server The mod_cache module hooks into the server in two possible places depending on the value of the CacheQuickHandler directive: Quick handler phase This phase happens very early on during the request processing, just after the request has been parsed.

If the content is found within the cache, it is served immediately and almost all request processing is bypassed. In this scenario, the cache behaves as if it has been "bolted on" to the front of the server. This mode offers the best performance, as the majority of server processing is bypassed. This mode however also bypasses the authentication and authorization phases of server processing, so this mode should be chosen with care when this is important.

Requests with an "Authorization" header (for example, HTTP Basic Authentication) are neither cacheable nor served from the cache when mod_cache is running in this phase. Normal handler phase This phase happens late in the request processing, after all the request phases have completed. In this scenario, the cache behaves as if it has been "bolted on" to the back of the server. This mode offers the most flexibility, as the potential exists for caching to occur at a precisely controlled point in the filter chain, and cached content can be filtered or personalized before being sent to the client.

If the URL is not found within the cache, mod_cache will add a filter to the filter stack in order to record the response to the cache, and then stand down, allowing normal request processing to continue. If the content is determined to be cacheable, the content will be saved to the cache for future serving, otherwise the content will be ignored. If the content found within the cache is stale, the mod_cache module converts the request into a conditional request .

If the origin server responds with a normal response, the normal response is cached, replacing the content already cached. If the origin server responds with a 304 Not Modified response, the content is marked as fresh again, and the cached content is served by the filter instead of saving it. Improving Cache Hits When a virtual host is known by one of many different server aliases, ensuring that UseCanonicalName is set to On can dramatically improve the ratio of cache hits.

This is because the hostname of the virtual-host serving the content is used within the cache key. With the setting set to On virtual-hosts with multiple server names or aliases will not produce differently cached entities, and instead content will be cached as per the canonical hostname. Freshness Lifetime Well formed content that is intended to be cached should declare an explicit freshness lifetime with the Cache-Control header's max-age or s-maxage fields, or by including an Expires header.

At the same time, the origin server defined freshness lifetime can be overridden by a client when the client presents their own Cache-Control header within the request. In this case, the lowest freshness lifetime between request and response wins. When this freshness lifetime is missing from the request or the response, a default freshness lifetime is applied. The default freshness lifetime for cached entities is one hour, however this can be easily over-ridden by using the CacheDefaultExpire directive.

If a response does not include an Expires header but does include a Last-Modified header, mod_cache can infer a freshness lifetime based on a heuristic, which can be controlled through the use of the CacheLastModifiedFactor directive. For local content, or for remote content that does not define its own Expires header, mod_expires may be used to fine-tune the freshness lifetime by adding max-age and Expires . The maximum f

The rest of this page is on the live site.