What Can be Cached?

This document supplements the mod_cache, mod_disk_cache, mod_file_cache and htcacheclean reference documentation. - It describes how to use Apache's caching features to accelerate web and + 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

mod_file_cache

If the URL is not found within the cache, mod_cache will add a filter to the request handling. After - Apache has located the content by the usual means, the filter will be run + httpd has located the content by the usual means, the filter will be run as the content is served. If the content is determined to be cacheable, the content will be saved to the cache for future serving.

When content expires from the cache and is re-requested from the backend or content provider, rather than pass on the original request, - Apache will use a conditional request instead.

HTTP offers a number of headers which allow a client, or cache to discern between different versions of the same content. For @@ -194,7 +194,7 @@

Secondly, conditional requests are usually less strenuous on the backend. For static files, typically all that is involved is a call to stat() or similar system call, to see if the file has - changed in size or modification time. As such, even if Apache is + changed in size or modification time. As such, even if httpd is caching local content, even expired content may still be served faster from the cache if it has not changed. As long as reading from the cache store is faster than reading from the backend (e.g. mod_disk_cache with memory disk @@ -204,9 +204,9 @@

What Can be Cached?

As mentioned already, the two styles of caching in Apache work +

As mentioned already, the two styles of caching in httpd work differently, mod_file_cache caching maintains file - contents as they were when Apache was started. When a request is + contents as they were when httpd was started. When a request is made for a file that is cached by this module, it is intercepted and the cached file is served.

Using mod_cache is very much like having a built in reverse-proxy. Requests will be served by the caching module unless it determines that the backend should be queried. When caching local - resources, this drastically changes the security model of Apache.

As traversing a filesystem hierarchy to examine potential .htaccess files would be a very expensive operation, @@ -331,7 +331,7 @@ Vary: negotiate,accept-language,accept-c

As requests to end-users can be served from the cache, the cache itself can become a target for those wishing to deface or interfere with content. It is important to bear in mind that the cache must at all - times be writable by the user which Apache is running as. This is in + times be writable by the user which httpd is running as. This is in stark contrast to the usually recommended situation of maintaining all content unwritable by the Apache user.

This presents a somewhat elevated risk in comparison to the other types of attack it is possible to make as the Apache user. If you are using mod_disk_cache you should bear this in mind - - ensure you upgrade Apache when security upgrades are announced and + ensure you upgrade httpd when security upgrades are announced and run CGI processes as a non-Apache user using suEXEC if possible.

Cache Poisoning

When running Apache as a caching proxy server, there is also the +

When running httpd as a caching proxy server, there is also the potential for so-called cache poisoning. Cache Poisoning is a broad term for attacks in which an attacker causes the proxy server to retrieve incorrect (and usually undesirable) content from the backend.

For example if the DNS servers used by your system running Apache +

For example if the DNS servers used by your system running + httpd are vulnerable to DNS cache poisoning, an attacker may be able to control - where Apache connects to when requesting content from the origin server. + where httpd connects to when requesting content from the origin server. Another example is so-called HTTP request-smuggling attacks.

This document is not the correct place for an in-depth discussion @@ -378,13 +379,14 @@ Vary: negotiate,accept-language,accept-c

The act of opening a file can itself be a source of delay, particularly on network filesystems. By maintaining a cache of open file descriptors - for commonly served files, Apache can avoid this delay. Currently Apache + for commonly served files, httpd can avoid this delay. Currently + httpd provides one implementation of File-Handle Caching.

CacheFile

The most basic form of caching present in Apache is the file-handle +

The most basic form of caching present in httpd is the file-handle caching provided by mod_file_cache. Rather than caching file-contents, this cache maintains a table of open file descriptors. Files to be cached in this manner are specified in the configuration file using @@ -393,7 +395,7 @@ Vary: negotiate,accept-language,accept-c

The CacheFile directive - instructs Apache to open the file when Apache is started and to re-use + instructs httpd to open the file when it is started and to re-use this file-handle for all subsequent access to this file.

CacheFile /usr/local/apache2/htdocs/index.html

Although using CacheFile does not cause the file-contents to be cached per-se, it does mean - that if the file changes while Apache is running these changes will + that if the file changes while httpd is running these changes will not be picked up. The file will be consistently served as it was - when Apache was started.

If the file is removed while Apache is running, Apache will continue +

If the file is removed while httpd is running, it will continue to maintain an open file descriptor and serve the file as it was when - Apache was started. This usually also means that although the file + httpd was started. This usually also means that although the file will have been deleted, and not show up on the filesystem, extra free - space will not be recovered until Apache is stopped and the file + space will not be recovered until httpd is stopped and the file descriptor closed.

By ensuring there is "spare" memory on your system, you can ensure that more and more file-contents will be stored in this cache. This can be a very efficient means of in-memory caching, and involves no - extra configuration of Apache at all.

Additionally, because the operating system knows when files are deleted or modified, it can automatically remove file contents from the - cache when neccessary. This is a big advantage over Apache's in-memory + cache when neccessary. This is a big advantage over httpd's in-memory caching which has no way of knowing when a file has changed.

Despite the performance and advantages of automatic operating system caching there are some circumstances in which in-memory caching may be - better performed by Apache.

MMapFile Caching

mod_file_cache provides the MMapFile directive, which - allows you to have Apache map a static file's contents into memory at - start time (using the mmap system call). Apache will use the in-memory + allows you to have httpd map a static file's contents into memory at + start time (using the mmap system call). httpd will use the in-memory contents for all subsequent accesses to this file.

As with the CacheFile directive, any - changes in these files will not be picked up by Apache after it has + changes in these files will not be picked up by httpd after it has started.

The MMapFile directive does not keep track of how much memory it allocates, so - you must ensure not to over-use the directive. Each Apache child + you must ensure not to over-use the directive. Each httpd child process will replicate this memory, so it is critically important to ensure that the files mapped are not so large as to cause the system to swap memory.

Instead, provided with httpd is the htcacheclean tool which, as the name suggests, allows you to clean the cache periodically. Determining how frequently to run htcacheclean and what target size to use for the cache is somewhat complex and trial and error may be needed to Modified: httpd/httpd/trunk/docs/manual/caching.xml URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/caching.xml?rev=922237&r1=922236&r2=922237&view=diff ============================================================================== --- httpd/httpd/trunk/docs/manual/caching.xml (original) +++ httpd/httpd/trunk/docs/manual/caching.xml Fri Mar 12 12:32:19 2010 @@ -28,7 +28,7 @@

This document supplements the mod_cache, mod_disk_cache, mod_file_cache and htcacheclean reference documentation. - It describes how to use Apache's caching features to accelerate web and + It describes how to use the Apache HTTP Server's caching features to accelerate web and proxy serving, while avoiding common problems and misconfigurations.

If the URL is not found within the cache, mod_cache will add a filter to the request handling. After - Apache has located the content by the usual means, the filter will be run + httpd has located the content by the usual means, the filter will be run as the content is served. If the content is determined to be cacheable, the content will be saved to the cache for future serving.

When content expires from the cache and is re-requested from the backend or content provider, rather than pass on the original request, - Apache will use a conditional request instead.

HTTP offers a number of headers which allow a client, or cache to discern between different versions of the same content. For @@ -209,7 +209,7 @@

As mentioned already, the two styles of caching in httpd work differently, mod_file_cache caching maintains file - contents as they were when Apache was started. When a request is + contents as they were when httpd was started. When a request is made for a file that is cached by this module, it is intercepted and the cached file is served.

Using mod_cache is very much like having a built in reverse-proxy. Requests will be served by the caching module unless it determines that the backend should be queried. When caching local - resources, this drastically changes the security model of Apache.

As traversing a filesystem hierarchy to examine potential .htaccess files would be a very expensive operation, @@ -349,7 +349,7 @@ Vary: negotiate,accept-language,accept-c

This presents a somewhat elevated risk in comparison to the other types of attack it is possible to make as the Apache user. If you are using mod_disk_cache you should bear this in mind - - ensure you upgrade Apache when security upgrades are announced and + ensure you upgrade httpd when security upgrades are announced and run CGI processes as a non-Apache user using suEXEC if possible.

Cache Poisoning -

When running Apache as a caching proxy server, there is also the +

For example if the DNS servers used by your system running Apache +

This document is not the correct place for an in-depth discussion @@ -404,13 +405,14 @@ Vary: negotiate,accept-language,accept-c

CacheFile -

The most basic form of caching present in Apache is the file-handle +

The most basic form of caching present in httpd is the file-handle caching provided by mod_file_cache. Rather than caching file-contents, this cache maintains a table of open file descriptors. Files to be cached in this manner are specified in the configuration file using @@ -419,7 +421,7 @@ Vary: negotiate,accept-language,accept-c

The CacheFile directive - instructs Apache to open the file when Apache is started and to re-use + instructs httpd to open the file when it is started and to re-use this file-handle for all subsequent access to this file.

@@ -432,15 +434,15 @@ Vary: negotiate,accept-language,accept-c

Although using CacheFile does not cause the file-contents to be cached per-se, it does mean - that if the file changes while Apache is running these changes will + that if the file changes while httpd is running these changes will not be picked up. The file will be consistently served as it was - when Apache was started.

+ when httpd was started.

If the file is removed while Apache is running, Apache will continue +

@@ -472,7 +474,7 @@ Vary: negotiate,accept-language,accept-c efficiently. By caching files in memory you decrease the amount of memory available on the system. As we'll see, in the case of operating system caching, this is not so much of an issue, but when using - Apache's own in-memory caching it is important to make sure that you + httpd's own in-memory caching it is important to make sure that you do not allocate too much memory to a cache. Otherwise the system will be forced to swap out memory, which will likely degrade performance.

@@ -504,25 +506,25 @@ sys 0m0.000s

+ extra configuration of httpd at all.

Despite the performance and advantages of automatic operating system caching there are some circumstances in which in-memory caching may be - better performed by Apache.