mod_file_cache.html revision 2de56243b49d1c39dbc467e3f9daab152c8691b8
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews This file is generated from xml source: DO NOT EDIT
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0c27b3fe77ac1d5094ba3521e8142d9e7973133fMark Andrews --><title>mod_file_cache- Apache HTTP Server</title><link href="/style/manual.css" type="text/css" rel="stylesheet"/></head><body><blockquote><div align="center"><img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_file_cache</h1><table cellspacing="1" cellpadding="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>Caches a static list of files in memory</td></tr><tr><td><a href="module-dict.html#Status" class="help">Status:</a></td><td>Experimental</td></tr><tr><td><a href="module-dict.html#ModuleIdentifier" class="help">Module Identifier:</a></td><td>file_cache_module</td></tr></table></td></tr></table><h2>Summary</h2>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<blockquote><table><tr><td bgcolor="#ffe5f5">
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas GustafssonThis module should be used with care. You can easily
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson create a broken site using mod_file_cache, so read this
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson document carefully.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p><em>Caching</em> frequently requested files that change very
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson infrequently is a technique for reducing server load.
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson mod_file_cache provides two techniques for caching frequently
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson requested <em>static</em> files. Through configuration
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson directives, you can direct mod_file_cache to either open then
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson mmap()a file, or to pre-open a file and save the file's open
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <em>file handle</em>. Both techniques reduce server load when
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson processing requests for these files by doing part of the work
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson (specifically, the file I/O) for serving the file when the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson server is started rather than during each request.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>Notice: You cannot use this for speeding up CGI programs or
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson other files which are served by special content handlers. It
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson can only be used for regular files which are usually served by
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson the Apache core content handler.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>This module is an extension of and borrows heavily from the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson mod_mmap_static module in Apache 1.3.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<h2>Directives</h2><ul><li><a href="#cachefile">CacheFile</a></li><li><a href="#mmapfile">MMapFile</a></li></ul><h2>Using mod_file_cache</h2>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p><code><a href="mod_file_cache.html">mod_file_cache</a></code> caches a list of statically
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson configured files via <a href="#mmapfile" class="directive"><code class="directive">MMapFile</code></a> or <a href="#cachefile" class="directive"><code class="directive">CacheFile</code></a> directives in the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson main server configuration.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>Not all platforms support both directives. For example, Apache
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson on Windows does not currently support the <a href="#mmapstatic" class="directive"><code class="directive">MMapStatic</code></a> directive, while
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson other platforms, like AIX, support both. You will receive an error
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson message in the server error log if you attempt to use an
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson unsupported directive. If given an unsupported directive, the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson server will start but the file will not be cached. On platforms
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson that support both directives, you should experiment with both to
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson see which works best for you.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>The <a href="#mmapfile" class="directive"><code class="directive">MmapFile</code></a>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson directive of <code><a href="mod_file_cache.html">mod_file_cache</a></code> maps a list of
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson statically configured files into memory through the system call
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <code>mmap()</code>. This system call is available on most modern
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson Unix derivates, but not on all. There are sometimes
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson system-specific limits on the size and number of files that can be
705cc52bbf49bdeedbaf255e91af2e325fc79ba5Brian Wellington mmap()d, experimentation is probably the easiest way to find
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>This mmap()ing is done once at server start or restart,
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson only. So whenever one of the mapped files changes on the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson filesystem you <em>have</em> to restart the server (see the <a href="/stopping.html">Stopping and Restarting</a>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson documentation). To reiterate that point: if the files are
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson modified <em>in place</em> without restarting the server you
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson may end up serving requests that are completely bogus. You
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson should update files by unlinking the old copy and putting a new
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson copy in place. Most tools such as <code>rdist</code> and
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <code>mv</code> do this. The reason why this modules doesn't
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson take care of changes to the files is that this check would need
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson an extra <code>stat()</code> every time which is a waste and
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson against the intent of I/O reduction.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>The <a href="#cachefile" class="directive"><code class="directive">CacheFile</code></a>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson directive of <code><a href="mod_file_cache.html">mod_file_cache</a></code> opens an active
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <em>handle</em> or <em>file descriptor</em> to the file (or files)
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson listed in the configuration directive and places these open file
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson handles in the cache. When the file is requested, the server
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson retrieves the handle from the cache and passes it to the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson sendfile() (or TransmitFile() on Windows), socket API.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>Insert more details about sendfile API...</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>This file handle caching is done once at server start or
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson restart, only. So whenever one of the cached files changes on
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson the filesystem you <em>have</em> to restart the server (see the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <a href="/stopping.html">Stopping and Restarting</a>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson documentation). To reiterate that point: if the files are
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson modified <em>in place</em> without restarting the server you
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson may end up serving requests that are completely bogus. You
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson should update files by unlinking the old copy and putting a new
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson copy in place. Most tools such as <code>rdist</code> and
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<blockquote><table><tr><td bgcolor="#e0e5f5"><p align="center"><strong>Note</strong></p> Don't bother asking for a for a
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson directive which recursively caches all the files in a
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson directory. Try this instead... See the
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <a href="core.html#include" class="directive"><code class="directive">Include</code></a> directive, and consider
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson | sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob<hr/><h2><a name="CacheFile">CacheFile</a> <a name="cachefile">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td/></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>CacheFile
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob <em>file-path</em> [<em>file-path</em>] ...</td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Experimental</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_file_cache</td></tr></table></td></tr></table>
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob <p>The <code class="directive">CacheFile</code> directive opens handles to
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob one or more files (given as whitespace separated arguments) and
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob places these handles into the cache at server startup
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob time. Handles to cached files are automatically closed on a server
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob shutdown. When the files have changed on the filesystem, the
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob server should be restarted to to re-cache them.</p>
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob <p>Be careful with the <em>file-path</em> arguments: They have
5f439956720839197eb984c397f90bdce40fa263Stephen Jacob to literally match the filesystem path Apache's URL-to-filename
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson translation handlers create. We cannot compare inodes or other
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson stuff to match paths through symbolic links <em>etc.</em>
e1f0415f3fc134cfc27757d7b015292bd623d9e4Brian Wellington because that again would cost extra <code>stat()</code> system
e1f0415f3fc134cfc27757d7b015292bd623d9e4Brian Wellington calls which is not acceptable. This module may or may not work
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson with filenames rewritten by <code><a href="mod_alias.html">mod_alias</a></code> or
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <code><a href="mod_rewrite.html">mod_rewrite</a></code>.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson CacheFile /usr/local/apache/htdocs/index.html
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<hr/><h2><a name="MMapFile">MMapFile</a> <a name="mmapfile">Directive</a></h2><table cellpadding="1" cellspacing="0" border="0" bgcolor="#cccccc"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td/></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>MMapFile <em>file-path</em> [<em>file-path</em>] ...</td></tr><tr><td><a href="directive-dict.html#Context" class="help">Context:</a></td><td>server config</td></tr><tr><td><a href="directive-dict.html#Status" class="help">Status:</a></td><td>Experimental</td></tr><tr><td><a href="directive-dict.html#Module" class="help">Module:</a></td><td>mod_file_cache</td></tr></table></td></tr></table>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>The <code class="directive">MMapFile</code> directive maps one or more files
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson (given as whitespace separated arguments) into memory at server
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson startup time. They are automatically unmapped on a server
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson shutdown. When the files have changed on the filesystem at
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson least a HUP or USR1 signal should be send to the server to
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson re-mmap them.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <p>Be careful with the <em>file-path</em> arguments: They have
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson to literally match the filesystem path Apache's URL-to-filename
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson translation handlers create. We cannot compare inodes or other
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson stuff to match paths through symbolic links <em>etc.</em>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson because that again would cost extra <code>stat()</code> system
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson calls which is not acceptable. This module may or may not work
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson with filenames rewritten by <code><a href="mod_alias.html">mod_alias</a></code> or
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson <code><a href="mod_rewrite.html">mod_rewrite</a></code>.</p>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><p align="center"><strong>Example</strong></p><code>
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson MMapFile /usr/local/apache/htdocs/index.html
c6ebabd5c3cb47ae8175abaeacbc1131f8117359Andreas Gustafsson<hr/></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="/images/index.gif" alt="Index"/></a><a href="../"><img src="/images/home.gif" alt="Home"/></a></body></html>
