mirror of
https://github.com/apache/httpd.git
synced 2025-05-17 15:21:13 +03:00
e3489b6948
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@87273 13f79535-47bb-0310-9956-ffa450edef68
269 lines
8.9 KiB
HTML
269 lines
8.9 KiB
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> [<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>
|
|
|
|
<hr>
|
|
|
|
<H2><A NAME="cachefile">CacheFile</A></H2>
|
|
<P>
|
|
<A
|
|
HREF="directive-dict.html#Syntax"
|
|
REL="Help"
|
|
><STRONG>Syntax:</STRONG></A> CacheFile <EM>filename</EM> [<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>
|