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


            
            <?xml version="1.0"?>

            
            <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">

            
            <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>

            
            <!-- $LastChangedRevision$ -->


            <!--

            
             Licensed to the Apache Software Foundation (ASF) under one or more

            
             contributor license agreements.  See the NOTICE file distributed with

            
             this work for additional information regarding copyright ownership.

            
             The ASF licenses this file to You under the Apache License, Version 2.0

            
             (the "License"); you may not use this file except in compliance with

            
             the License.  You may obtain a copy of the License at


                 http://www.apache.org/licenses/LICENSE-2.0


             Unless required by applicable law or agreed to in writing, software

            
             distributed under the License is distributed on an "AS IS" BASIS,

            
             WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

            
             See the License for the specific language governing permissions and

            
             limitations under the License.

            
            -->


            <modulesynopsis metafile="mod_file_cache.xml.meta">


            <name>mod_file_cache</name>

            
            <description>Caches a static list of files in memory</description>

            
            <status>Experimental</status>

            
            <sourcefile>mod_file_cache.c</sourcefile>

            
            <identifier>file_cache_module</identifier>


            <summary>


                <note type="warning">

            
                  This module should be used with care. You can easily create a broken

            
                  site using <module>mod_file_cache</module>, so read this document

            
                  carefully.

            
                </note>


                <p><em>Caching</em> frequently requested files that change very

            
                infrequently is a technique for reducing server load.

            
                <module>mod_file_cache</module> provides two techniques for caching

            
                frequently requested <em>static</em> files. Through configuration

            
                directives, you can direct <module>mod_file_cache</module> to either

            
                open then <code>mmap()</code> 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>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

            
                <code>mod_mmap_static</code> module in Apache 1.3.</p>

            
            </summary>


            <section id="using"><title>Using mod_file_cache</title>


                <p><module>mod_file_cache</module> caches a list of statically

            
                configured files via <directive module="mod_file_cache"

            
                >MMapFile</directive> or <directive module="mod_file_cache"

            
                >CacheFile</directive> directives in the main server configuration.</p>


                <p>Not all platforms support both directives. 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>


                <section><title>MMapFile Directive</title>


                  <p>The <directive module="mod_file_cache">MMapFile</directive>

            
                  directive of <module>mod_file_cache</module> 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 derivatives, but not on all. There are sometimes system-specific

            
                  limits on the size and number of files that can be

            
                  <code>mmap()</code>ed, experimentation is probably the easiest way

            
                  to find out.</p>


                  <p>This <code>mmap()</code>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>

            
                </section>


                <section><title>CacheFile Directive</title>


                  <p>The <directive module="mod_file_cache">CacheFile</directive>

            
                  directive of <module>mod_file_cache</module> 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

            
                  <code>sendfile()</code> (or <code>TransmitFile()</code> on Windows),

            
                  socket API.</p>


                  <!-- XXX

            
                  <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>

            
                </section>


                <note><title>Note</title>

            
                  <p>Don't bother asking for a directive which recursively

            
                  caches all the files in a directory. Try this instead... See the

            
                  <directive module="core">Include</directive> directive, and consider

            
                  this command:</p>


                  <example>

            
                    find /www/htdocs -type f -print \<br />

            
                    | sed -e 's/.*/mmapfile &amp;/' &gt; /www/conf/mmap.conf

            
                  </example>

            
                </note>

            
            </section>


            <directivesynopsis>

            
            <name>MMapFile</name>

            
            <description>Map a list of files into memory at startup time</description>

            
            <syntax>MMapFile <var>file-path</var> [<var>file-path</var>] ...</syntax>

            
            <contextlist><context>server config</context></contextlist>


            <usage>

            
                <p>The <directive>MMapFile</directive> 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 <code>HUP</code> or <code>USR1</code> signal should be send to

            
                the server to re-<code>mmap()</code> them.</p>


                <p>Be careful with the <var>file-path</var> 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 <module>mod_alias</module> or

            
                <module>mod_rewrite</module>.</p>


                <example><title>Example</title>

            
                <highlight language="config">

            
                  MMapFile /usr/local/apache/htdocs/index.html

            
                  </highlight>

            
                </example>

            
            </usage>

            
            </directivesynopsis>


            <directivesynopsis>

            
            <name>CacheFile</name>

            
            <description>Cache a list of file handles at startup time</description>

            
            <syntax>CacheFile <var>file-path</var> [<var>file-path</var>] ...</syntax>

            
            <contextlist><context>server config</context></contextlist>


            <usage>

            
                <p>The <directive>CacheFile</directive> 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 re-cache them.</p>


                <p>Be careful with the <var>file-path</var> 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 <module>mod_alias</module> or

            
                <module>mod_rewrite</module>.</p>


                <example><title>Example</title>

            
                <highlight language="config">

            
                  CacheFile /usr/local/apache/htdocs/index.html

            
                  </highlight>

            
                </example>

            
            </usage>

            
            </directivesynopsis>


            </modulesynopsis>
	<?xml version="1.0"?>
	<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
	<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
	<!-- $LastChangedRevision$ -->

	<!--
	Licensed to the Apache Software Foundation (ASF) under one or more
	contributor license agreements. See the NOTICE file distributed with
	this work for additional information regarding copyright ownership.
	The ASF licenses this file to You under the Apache License, Version 2.0
	(the "License"); you may not use this file except in compliance with
	the License. You may obtain a copy of the License at

	http://www.apache.org/licenses/LICENSE-2.0

	Unless required by applicable law or agreed to in writing, software
	distributed under the License is distributed on an "AS IS" BASIS,
	WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
	See the License for the specific language governing permissions and
	limitations under the License.
	-->

	<modulesynopsis metafile="mod_file_cache.xml.meta">

	<name>mod_file_cache</name>
	<description>Caches a static list of files in memory</description>
	<status>Experimental</status>
	<sourcefile>mod_file_cache.c</sourcefile>
	<identifier>file_cache_module</identifier>

	<summary>

	<note type="warning">
	This module should be used with care. You can easily create a broken
	site using <module>mod_file_cache</module>, so read this document
	carefully.
	</note>

	<p><em>Caching</em> frequently requested files that change very
	infrequently is a technique for reducing server load.
	<module>mod_file_cache</module> provides two techniques for caching
	frequently requested <em>static</em> files. Through configuration
	directives, you can direct <module>mod_file_cache</module> to either
	open then <code>mmap()</code> 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>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
	<code>mod_mmap_static</code> module in Apache 1.3.</p>
	</summary>

	<section id="using"><title>Using mod_file_cache</title>

	<p><module>mod_file_cache</module> caches a list of statically
	configured files via <directive module="mod_file_cache"
	>MMapFile</directive> or <directive module="mod_file_cache"
	>CacheFile</directive> directives in the main server configuration.</p>

	<p>Not all platforms support both directives. 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>

	<section><title>MMapFile Directive</title>

	<p>The <directive module="mod_file_cache">MMapFile</directive>
	directive of <module>mod_file_cache</module> 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 derivatives, but not on all. There are sometimes system-specific
	limits on the size and number of files that can be
	<code>mmap()</code>ed, experimentation is probably the easiest way
	to find out.</p>

	<p>This <code>mmap()</code>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>
	</section>

	<section><title>CacheFile Directive</title>

	<p>The <directive module="mod_file_cache">CacheFile</directive>
	directive of <module>mod_file_cache</module> 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
	<code>sendfile()</code> (or <code>TransmitFile()</code> on Windows),
	socket API.</p>

	<!-- XXX
	<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>
	</section>

	<note><title>Note</title>
	<p>Don't bother asking for a directive which recursively
	caches all the files in a directory. Try this instead... See the
	<directive module="core">Include</directive> directive, and consider
	this command:</p>

	<example>
	find /www/htdocs -type f -print \<br />
	\| sed -e 's/.*/mmapfile &/' > /www/conf/mmap.conf
	</example>
	</note>
	</section>

	<directivesynopsis>
	<name>MMapFile</name>
	<description>Map a list of files into memory at startup time</description>
	<syntax>MMapFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
	<contextlist><context>server config</context></contextlist>

	<usage>
	<p>The <directive>MMapFile</directive> 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 <code>HUP</code> or <code>USR1</code> signal should be send to
	the server to re-<code>mmap()</code> them.</p>

	<p>Be careful with the <var>file-path</var> 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 <module>mod_alias</module> or
	<module>mod_rewrite</module>.</p>

	<example><title>Example</title>
	<highlight language="config">
	MMapFile /usr/local/apache/htdocs/index.html
	</highlight>
	</example>
	</usage>
	</directivesynopsis>

	<directivesynopsis>
	<name>CacheFile</name>
	<description>Cache a list of file handles at startup time</description>
	<syntax>CacheFile <var>file-path</var> [<var>file-path</var>] ...</syntax>
	<contextlist><context>server config</context></contextlist>

	<usage>
	<p>The <directive>CacheFile</directive> 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 re-cache them.</p>

	<p>Be careful with the <var>file-path</var> 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 <module>mod_alias</module> or
	<module>mod_rewrite</module>.</p>

	<example><title>Example</title>
	<highlight language="config">
	CacheFile /usr/local/apache/htdocs/index.html
	</highlight>
	</example>
	</usage>
	</directivesynopsis>

	</modulesynopsis>