docs/manual/mod/mod_file_cache.html - httpd - Git at Google

 <!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 &amp;/' &gt; /www/conf/mmap.conf
   </PRE>

 <!--#include virtual="footer.html" -->
  </BODY>
 </HTML>
	<!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>