mod_file_cache.html revision 773859b173fe03a0fb6160bcbd290829395f256b
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk BGCOLOR="#FFFFFF"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk TEXT="#000000"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk LINK="#0000FF"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk VLINK="#000080"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk ALINK="#FF0000"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk<!--#include virtual="header.html" -->
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <STRONG>This module should be used with care. You can easily create a
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk broken site using mod_file_cache, so read this document
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk carefully.</STRONG>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <EM>Caching</EM> frequently requested files that change very
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk infrequently is a technique for reducing server load. mod_file_cache
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk provides two techniques for caching frequently requested
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Through configuration directives, you can direct mod_file_cache
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk to either open then mmap()a file, or to pre-open a file and save
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the file's open <EM>file handle</EM>. Both techniques reduce server
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk load when processing requests for these files by doing part of the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk work (specifically, the file I/O) for serving the file when the server
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk is started rather than during each request.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <CODE>mod_file_cache</CODE> is not compiled into the server by
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk default. To use <CODE>mod_file_cache</CODE> you have to enable the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk following line in the server build <CODE>Configuration</CODE> file:
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Notice: You cannot use this for speeding up CGI programs or other files
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk which are served by special content handlers. It can only be used for
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk regular files which are usually served by the Apache core content handler.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This module is an extension of and borrows heavily from the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk mod_mmap_static module in Apache 1.3.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <CODE>mod_file_cache</CODE> caches a list of statically configured
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk files via <CODE>MMapFile</CODE> or <CODE>CacheFile</CODE> directives
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk in the main server configuration.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Not all platforms support both directives. For
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk example, Apache on Windows does not currently support the MMapStatic
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk directive, while other platforms, like AIX, support both. You will
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk receive an error message in the server error log if you attempt to
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk use an unsupported directive. If given an unsupported directive, the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk server will start but the file will not be cached. On platforms that
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk support both directives, you should experiment with both to see
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk which works best for you.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk The <CODE>MmapFile</CODE> directive of <CODE>mod_file_cache</CODE>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk maps a list of statically configured files into memory through the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk system call <CODE>mmap()</CODE>. This system call is available on
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk most modern Unix derivates, but not on all. There are sometimes
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk system-specific limits on the size and number of files that can be
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk mmap()d, experimentation is probably the easiest way to find out.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This mmap()ing is done once at server start or restart, only. So whenever
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk one of the mapped files changes on the filesystem you <EM>have</EM> to
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk restart the server (see the <A HREF="/stopping.html">Stopping and
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Restarting</A> documentation). To reiterate that point: if the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk files are modified <EM>in place</EM> without restarting the server
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk you may end up serving requests that are completely bogus. You
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk should update files by unlinking the old copy and putting a new
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk copy in place. Most tools such as <CODE>rdist</CODE> and
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <CODE>mv</CODE> do this. The reason why this modules doesn't take
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk care of changes to the files is that this check would need an extra
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk <CODE>stat()</CODE> every time which is a waste and against the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk intent of I/O reduction.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk The <CODE>CacheFile</CODE> directive of <CODE>mod_file_cache</CODE>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk opens an active <EM>handle</EM> or <EM>file descriptor</EM> to the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk file (or files) listed in the configuration directive and places
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk these open file handles in the cache. When the file is requested,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk the server retrieves the handle from the cache and passes it to the
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk sendfile() (or TransmitFile() on Windows), socket API.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk Insert more details about sendfile API...
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk This file handle caching is done once at server start or restart,
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk only. So whenever one of the cached files changes on the filesystem
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk you <EM>have</EM> to restart the server (see the <A
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk HREF="/stopping.html">Stopping and Restarting</A> documentation).
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk To reiterate that point: if the files are modified <EM>in
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk place</EM> without restarting the server you may end up serving
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk requests that are completely bogus. You should update files by
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk unlinking the old copy and putting a new copy in place. Most tools
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk such as <CODE>rdist</CODE> and <CODE>mv</CODE> do this.
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename ...</EM>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM>
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk HREF="directive-dict.html#Compatibility"
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk ><STRONG>Compatibility:</STRONG></A> Only in Apache 1.3 (via
c1350cf5bc50458ba79cc93ff9e0e5fe3f1aeeb0jeff.schenk mod_mmap_statis) or later.
HREF="directive-dict.html#Syntax"
HREF="directive-dict.html#Default"
HREF="directive-dict.html#Context"
HREF="directive-dict.html#Override"
HREF="directive-dict.html#Status"
HREF="directive-dict.html#Module"
HREF="directive-dict.html#Compatibility"
<!--#include virtual="footer.html" -->