--- /dev/null
+<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
+<HTML>
+ <HEAD>
+ <TITLE>Apache module mod_file_cache</TITLE>
+ </HEAD>
+<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
+ <BODY
+ BGCOLOR="#FFFFFF"
+ TEXT="#000000"
+ LINK="#0000FF"
+ VLINK="#000080"
+ ALINK="#FF0000"
+ >
+<!--#include virtual="header.html" -->
+ <H1 ALIGN="CENTER">Module mod_file_cache</H1>
+ <P>
+ <STRONG>This module should be used with care. You can easily create a
+ broken site using mod_file_cache, so read this document
+ carefully.</STRONG>
+ </P>
+
+ <P>
+ <EM>Caching</EM> frequently requested files that change very
+ infrequently is a technique for reducing server load. mod_file_cache
+ provides two techniques for caching frequently requested
+ <EM>static</EM> files.
+ Through configuration directives, you can direct mod_file_cache
+ to either open then mmap()a file, or to pre-open a file and save
+ the file's open <EM>file handle</EM>. Both techniques reduce server
+ load when processing requests for these files by doing part of the
+ work (specifically, the file I/O) for serving the file when the server
+ is started rather than during each request.
+ </P>
+
+ <P>
+ <CODE>mod_file_cache</CODE> is not compiled into the server by
+ default. To use <CODE>mod_file_cache</CODE> you have to enable the
+ following line in the server build <CODE>Configuration</CODE> file:
+ <PRE>
+ AddModule modules/experimental/mod_file_cache.o
+ </PRE>
+ </P>
+
+ <P>
+ Notice: You cannot use this for speeding up CGI programs or other files
+ which are served by special content handlers. It can only be used for
+ regular files which are usually served by the Apache core content handler.
+ </P>
+
+ <P>
+ This module is an extension of and borrows heavily from the
+ mod_mmap_static module in Apache 1.3.
+ </P>
+ <H2>Summary</H2>
+ <P>
+ <CODE>mod_file_cache</CODE> caches a list of statically configured
+ files via <CODE>MMapFile</CODE> or <CODE>CacheFile</CODE> directives
+ in the main server configuration.
+ </P>
+
+ <P>
+ Not all platforms support both directives. For
+ example, Apache on Windows does not currently support the MMapStatic
+ directive, while other platforms, like AIX, support both. You will
+ receive an error message in the server error log if you attempt to
+ use an unsupported directive. If given an unsupported directive, the
+ server will start but the file will not be cached. On platforms that
+ support both directives, you should experiment with both to see
+ which works best for you.
+ </P>
+
+ <H3><CODE>MmapFile</CODE> Directive </H3>
+ <P>
+ The <CODE>MmapFile</CODE> directive of <CODE>mod_file_cache</CODE>
+ maps a list of statically configured files into memory through the
+ system call <CODE>mmap()</CODE>. This system call is available on
+ most modern Unix derivates, but not on all. There are sometimes
+ system-specific limits on the size and number of files that can be
+ mmap()d, experimentation is probably the easiest way to find out.
+ </P>
+ <P>
+ This mmap()ing is done once at server start or restart, only. So whenever
+ one of the mapped files changes on the filesystem you <EM>have</EM> to
+ restart the server (see the <A HREF="../stopping.html">Stopping and
+ Restarting</A> documentation). To reiterate that point: if the
+ files are modified <EM>in place</EM> without restarting the server
+ you may end up serving requests that are completely bogus. You
+ should update files by unlinking the old copy and putting a new
+ copy in place. Most tools such as <CODE>rdist</CODE> and
+ <CODE>mv</CODE> do this. The reason why this modules doesn't take
+ care of changes to the files is that this check would need an extra
+ <CODE>stat()</CODE> every time which is a waste and against the
+ intent of I/O reduction.
+ </P>
+
+ <H3><CODE>CacheFile</CODE> Directive </H3>
+ <P>
+ The <CODE>CacheFile</CODE> directive of <CODE>mod_file_cache</CODE>
+ opens an active <EM>handle</EM> or <EM>file descriptor</EM> to the
+ file (or files) listed in the configuration directive and places
+ these open file handles in the cache. When the file is requested,
+ the server retrieves the handle from the cache and passes it to the
+ sendfile() (or TransmitFile() on Windows), socket API.
+ </P>
+ <P>
+ Insert more details about sendfile API...
+ </P>
+ <P>
+ This file handle caching is done once at server start or restart,
+ only. So whenever one of the cached files changes on the filesystem
+ you <EM>have</EM> to restart the server (see the <A
+ HREF="../stopping.html">Stopping and Restarting</A> documentation).
+ To reiterate that point: if the files are modified <EM>in
+ place</EM> without restarting the server you may end up serving
+ requests that are completely bogus. You should update files by
+ unlinking the old copy and putting a new copy in place. Most tools
+ such as <CODE>rdist</CODE> and <CODE>mv</CODE> do this.
+ </P>
+
+ <H2>Directives</H2>
+ <UL>
+ <LI><A HREF="#mmapfile">MMapFile</A>
+ </LI>
+ <LI><A HREF="#cachefile">CacheFile</A>
+ </LI>
+ </UL>
+
+ <HR>
+
+ <H2><A NAME="mmapfile">MMapFile</A></H2>
+ <P>
+ <A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+ ><STRONG>Syntax:</STRONG></A> MMapFile <EM>filename ...</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+ ><STRONG>Default:</STRONG></A> <EM>None</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+ ><STRONG>Context:</STRONG></A> server-config
+ <BR>
+ <A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+ ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+ ><STRONG>Status:</STRONG></A> Experimental
+ <BR>
+ <A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+ ><STRONG>Module:</STRONG></A> mod_file_cache
+ <BR>
+ <A
+ HREF="directive-dict.html#Compatibility"
+ REL="Help"
+ ><STRONG>Compatibility:</STRONG></A> Only in Apache 1.3 (via
+ mod_mmap_statis) or later.
+
+ <P>
+ The <CODE>MMapFile</CODE> directive maps one or more files (given as
+ whitespace separated arguments) into memory at server startup time. They
+ are automatically unmapped on a server shutdown. When the files have changed
+ on the filesystem at least a HUP or USR1 signal should be send to the server
+ to re-mmap them.
+ </P>
+
+ <P>
+ Be careful with the <EM>filename</EM> arguments: They have to literally
+ match the filesystem path Apache's URL-to-filename translation handlers
+ create. We cannot compare inodes or other stuff to match paths through
+ symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE>
+ system calls which is not acceptable. This module may or may not work
+ with filenames rewritten by <CODE>mod_alias</CODE> or
+ <CODE>mod_rewrite</CODE>.
+ </P>
+
+ Example:
+
+ <PRE>
+ MMapFile /usr/local/apache/htdocs/index.html
+ </PRE>
+
+
+ <H2><A NAME="cachefile">CacheFile</A></H2>
+ <P>
+ <A
+ HREF="directive-dict.html#Syntax"
+ REL="Help"
+ ><STRONG>Syntax:</STRONG></A> CacheFile <EM>filename ...</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Default"
+ REL="Help"
+ ><STRONG>Default:</STRONG></A> <EM>None</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Context"
+ REL="Help"
+ ><STRONG>Context:</STRONG></A> server-config
+ <BR>
+ <A
+ HREF="directive-dict.html#Override"
+ REL="Help"
+ ><STRONG>Override:</STRONG></A> <EM>Not applicable</EM>
+ <BR>
+ <A
+ HREF="directive-dict.html#Status"
+ REL="Help"
+ ><STRONG>Status:</STRONG></A> Experimental
+ <BR>
+ <A
+ HREF="directive-dict.html#Module"
+ REL="Help"
+ ><STRONG>Module:</STRONG></A> mod_file_cache
+ <BR>
+ <A
+ HREF="directive-dict.html#Compatibility"
+ REL="Help"
+ ><STRONG>Compatibility:</STRONG></A> Only available in Apache 2.0 or later.
+
+ <P>
+ The <CODE>CacheFile</CODE> directive opens handles to one or more
+ files (given as whitespace separated arguments) and places these
+ handles into the cache at server startup time. Handles to cached
+ files are automatically closed on a server shutdown. When the files
+ have changed on the filesystem, the server should be restarted to
+ to re-cache them.
+ </P>
+
+ <P>
+ Be careful with the <EM>filename</EM> arguments: They have to literally
+ match the filesystem path Apache's URL-to-filename translation handlers
+ create. We cannot compare inodes or other stuff to match paths through
+ symbolic links <EM>etc.</EM> because that again would cost extra <CODE>stat()</CODE>
+ system calls which is not acceptable. This module may or may not work
+ with filenames rewritten by <CODE>mod_alias</CODE> or
+ <CODE>mod_rewrite</CODE>.
+ </P>
+
+ Example:
+
+ <PRE>
+ CacheFile /usr/local/apache/htdocs/index.html
+ </PRE>
+
+ <P>
+ <STRONG>Note</STRONG>: don't bother asking for a for a directive which
+ recursively caches all the files in a directory. Try this
+ instead...
+ See the <A HREF="core.html#include">Include</A> directive, and consider this command:
+ <PRE>
+ find /www/htdocs -type f -print \
+ | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
+ </PRE>
+
+<!--#include virtual="footer.html" -->
+ </BODY>
+</HTML>
projects / apache / commitdiff