1
<?xml version="1.0" encoding="ISO-8859-1"?>
2
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
4
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
5
This file is generated from xml source: DO NOT EDIT
6
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8
<title>Caching Guide - Apache HTTP Server</title>
9
<link href="./style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
10
<link href="./style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
11
<link href="./style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
12
<link href="./images/favicon.ico" rel="shortcut icon" /></head>
13
<body id="manual-page"><div id="page-header">
14
<p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p>
15
<p class="apache">Apache HTTP Server Version 2.2</p>
16
<img alt="" src="./images/feather.gif" /></div>
17
<div class="up"><a href="./"><img title="<-" alt="<-" src="./images/left.gif" /></a></div>
19
<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="./">Version 2.2</a></div><div id="page-content"><div id="preamble"><h1>Caching Guide</h1>
21
<p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a></p>
24
<p>This document supplements the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>,
25
<code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>, <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code>,
26
<code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> and <a href="programs/htcacheclean.html">htcacheclean</a> reference documentation.
27
It describes how to use Apache's caching features to accelerate web and
28
proxy serving, while avoiding common problems and misconfigurations.</p>
30
<div id="quickview"><ul id="toc"><li><img alt="" src="./images/down.gif" /> <a href="#introduction">Introduction</a></li>
31
<li><img alt="" src="./images/down.gif" /> <a href="#overview">Caching Overview</a></li>
32
<li><img alt="" src="./images/down.gif" /> <a href="#security">Security Considerations</a></li>
33
<li><img alt="" src="./images/down.gif" /> <a href="#filehandle">File-Handle Caching</a></li>
34
<li><img alt="" src="./images/down.gif" /> <a href="#inmemory">In-Memory Caching</a></li>
35
<li><img alt="" src="./images/down.gif" /> <a href="#disk">Disk-based Caching</a></li>
37
<div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
39
<h2><a name="introduction" id="introduction">Introduction</a></h2>
42
<p>As of Apache HTTP server version 2.2 <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
43
and <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> are no longer marked
44
experimental and are considered suitable for production use. These
45
caching architectures provide a powerful means to accelerate HTTP
46
handling, both as an origin webserver and as a proxy.</p>
48
<p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> and its provider modules
49
<code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> and <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>
50
provide intelligent, HTTP-aware caching. The content itself is stored
51
in the cache, and mod_cache aims to honour all of the various HTTP
52
headers and options that control the cachability of content. It can
53
handle both local and proxied content. <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
54
is aimed at both simple and complex caching configurations, where
55
you are dealing with proxied content, dynamic local content or
56
have a need to speed up access to local files which change with
59
<p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> on the other hand presents a more
60
basic, but sometimes useful, form of caching. Rather than maintain
61
the complexity of actively ensuring the cachability of URLs,
62
<code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> offers file-handle and memory-mapping
63
tricks to keep a cache of files as they were when Apache was last
64
started. As such, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> is aimed at improving
65
the access time to local static files which do not change very
68
<p>As <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> presents a relatively simple
69
caching implementation, apart from the specific sections on <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> and <code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code>, the explanations
70
in this guide cover the <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching
73
<p>To get the most from this document, you should be familiar with
74
the basics of HTTP, and have read the Users' Guides to
75
<a href="urlmapping.html">Mapping URLs to the Filesystem</a> and
76
<a href="content-negotiation.html">Content negotiation</a>.</p>
78
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
80
<h2><a name="overview" id="overview">Caching Overview</a></h2>
84
<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code></li><li><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code></li><li><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code></li><li><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code></li><li><code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code></li><li><code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code></li><li><code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code></li><li><code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code></li><li><code class="directive"><a href="./mod/mod_negotiation.html#cachenegotiateddocs">CacheNegotiatedDocs</a></code></li></ul></td></tr></table>
86
<p>There are two main stages in <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> that can
87
occur in the lifetime of a request. First, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
88
is a URL mapping module, which means that if a URL has been cached,
89
and the cached version of that URL has not expired, the request will
90
be served directly by <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>.</p>
92
<p>This means that any other stages that might ordinarily happen
93
in the process of serving a request -- for example being handled
94
by <code class="module"><a href="./mod/mod_proxy.html">mod_proxy</a></code>, or <code class="module"><a href="./mod/mod_rewrite.html">mod_rewrite</a></code> --
95
won't happen. But then this is the point of caching content in
98
<p>If the URL is not found within the cache, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
99
will add a <a href="filter.html">filter</a> to the request handling. After
100
Apache has located the content by the usual means, the filter will be run
101
as the content is served. If the content is determined to be cacheable,
102
the content will be saved to the cache for future serving.</p>
104
<p>If the URL is found within the cache, but also found to have expired,
105
the filter is added anyway, but <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will create
106
a conditional request to the backend, to determine if the cached version
107
is still current. If the cached version is still current, its
108
meta-information will be updated and the request will be served from the
109
cache. If the cached version is no longer current, the cached version
110
will be deleted and the filter will save the updated content to the cache
113
<h3>Improving Cache Hits</h3>
116
<p>When caching locally generated content, ensuring that
117
<code class="directive"><a href="./mod/core.html#usecanonicalname">UseCanonicalName</a></code> is set to
118
<code>On</code> can dramatically improve the ratio of cache hits. This
119
is because the hostname of the virtual-host serving the content forms
120
a part of the cache key. With the setting set to <code>On</code>
121
virtual-hosts with multiple server names or aliases will not produce
122
differently cached entities, and instead content will be cached as
123
per the canonical hostname.</p>
125
<p>Because caching is performed within the URL to filename translation
126
phase, cached documents will only be served in response to URL requests.
127
Ordinarily this is of little consequence, but there is one circumstance
128
in which it matters: If you are using <a href="howto/ssi.html">Server
129
Side Includes</a>;</p>
131
<div class="example"><pre>
132
<!-- The following include can be cached -->
133
<!--#include virtual="/footer.html" -->
135
<!-- The following include can not be cached -->
136
<!--#include file="/path/to/footer.html" --></pre></div>
138
<p>If you are using Server Side Includes, and want the benefit of speedy
139
serves from the cache, you should use <code>virtual</code> include
143
<h3>Expiry Periods</h3>
146
<p>The default expiry period for cached entities is one hour, however
147
this can be easily over-ridden by using the <code class="directive"><a href="./mod/mod_cache.html#cachedefaultexpire">CacheDefaultExpire</a></code> directive. This
148
default is only used when the original source of the content does not
149
specify an expire time or time of last modification.</p>
151
<p>If a response does not include an <code>Expires</code> header but does
152
include a <code>Last-Modified</code> header, <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>
153
can infer an expiry period based on the use of the <code class="directive"><a href="./mod/mod_cache.html#cachelastmodifiedfactor">CacheLastModifiedFactor</a></code> directive.</p>
155
<p>For local content, <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code> may be used to
156
fine-tune the expiry period.</p>
158
<p>The maximum expiry period may also be controlled by using the
159
<code class="directive"><a href="./mod/mod_cache.html#cachemaxexpire">CacheMaxExpire</a></code>.</p>
163
<h3>A Brief Guide to Conditional Requests</h3>
166
<p>When content expires from the cache and is re-requested from the
167
backend or content provider, rather than pass on the original request,
168
Aoache will use a conditional request instead.</p>
170
<p>HTTP offers a number of headers which allow a client, or cache
171
to discern between different versions of the same content. For
172
example if a resource was served with an "Etag:" header, it is
173
possible to make a conditional request with an "If-Match:"
174
header. If a resource was served with a "Last-Modified:" header
175
it is possible to make a conditional request with an
176
"If-Modified-Since:" header, and so on.</p>
178
<p>When such a conditional request is made, the response differs
179
depending on whether the content matches the conditions. If a request is
180
made with an "If-Modified-Since:" header, and the content has not been
181
modified since the time indicated in the request then a terse "304 Not
182
Modified" response is issued.</p>
184
<p>If the content has changed, then it is served as if the request were
185
not conditional to begin with.</p>
187
<p>The benefits of conditional requests in relation to caching are
188
twofold. Firstly, when making such a request to the backend, if the
189
content from the backend matches the content in the store, this can be
190
determined easily and without the overhead of transferring the entire
193
<p>Secondly, conditional requests are usually less strenuous on the
194
backend. For static files, typically all that is involved is a call
195
to <code>stat()</code> or similar system call, to see if the file has
196
changed in size or modification time. As such, even if Apache is
197
caching local content, even expired content may still be served faster
198
from the cache if it has not changed. As long as reading from the cache
199
store is faster than reading from the backend (e.g. an in-memory cache
200
compared to reading from disk).</p>
203
<h3>What Can be Cached?</h3>
206
<p>As mentioned already, the two styles of caching in Apache work
207
differently, <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> caching maintains file
208
contents as they were when Apache was started. When a request is
209
made for a file that is cached by this module, it is intercepted
210
and the cached file is served.</p>
212
<p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> caching on the other hand is more
213
complex. When serving a request, if it has not been cached
214
previously, the caching module will determine if the content
215
is cacheable. The conditions for determining cachability of
219
<li>Caching must be enabled for this URL. See the <code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> and <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code> directives.</li>
221
<li>The response must have a HTTP status code of 200, 203, 300, 301 or
224
<li>The request must be a HTTP GET request.</li>
226
<li>If the request contains an "Authorization:" header, the response
227
will not be cached.</li>
229
<li>If the response contains an "Authorization:" header, it must
230
also contain an "s-maxage", "must-revalidate" or "public" option
231
in the "Cache-Control:" header.</li>
233
<li>If the URL included a query string (e.g. from a HTML form GET
234
method) it will not be cached unless the response includes an
235
"Expires:" header, as per RFC2616 section 13.9.</li>
237
<li>If the response has a status of 200 (OK), the response must
238
also include at least one of the "Etag", "Last-Modified" or
239
the "Expires" headers, unless the
240
<code class="directive"><a href="./mod/mod_cache.html#cacheignorenolastmod">CacheIgnoreNoLastMod</a></code>
241
directive has been used to require otherwise.</li>
243
<li>If the response includes the "private" option in a "Cache-Control:"
244
header, it will not be stored unless the
245
<code class="directive"><a href="./mod/mod_cache.html#cachestoreprivate">CacheStorePrivate</a></code> has been
246
used to require otherwise.</li>
248
<li>Likewise, if the response includes the "no-store" option in a
249
"Cache-Control:" header, it will not be stored unless the
250
<code class="directive"><a href="./mod/mod_cache.html#cachestorenostore">CacheStoreNoStore</a></code> has been
253
<li>A response will not be stored if it includes a "Vary:" header
254
containing the match-all "*".</li>
258
<h3>What Should Not be Cached?</h3>
261
<p>In short, any content which is highly time-sensitive, or which varies
262
depending on the particulars of the request that are not covered by
263
HTTP negotiation, should not be cached.</p>
265
<p>If you have dynamic content which changes depending on the IP address
266
of the requester, or changes every 5 minutes, it should almost certainly
269
<p>If on the other hand, the content served differs depending on the
270
values of various HTTP headers, it is possible that it might be possible
271
to cache it intelligently through the use of a "Vary" header.</p>
274
<h3>Variable/Negotiated Content</h3>
277
<p>If a response with a "Vary" header is received by
278
<code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> when requesting content by the backend it
279
will attempt to handle it intelligently. If possible,
280
<code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will detect the headers attributed in the
281
"Vary" response in future requests and serve the correct cached
284
<p>If for example, a response is received with a vary header such as;</p>
286
<div class="example"><p><code>
287
Vary: negotiate,accept-language,accept-charset
290
<p><code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> will only serve the cached content to
291
requesters with matching accept-language and accept-charset headers
292
matching those of the original request.</p>
295
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
296
<div class="section">
297
<h2><a name="security" id="security">Security Considerations</a></h2>
300
<h3>Authorisation, Access & and Control</h3>
303
<p>Using <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> is very much like having a built
304
in reverse-proxy. Requests will be served by the caching module unless
305
it determines that the backend should be queried. When caching local
306
resources, this drastically changes the security model of Apache.</p>
308
<p>As traversing a filesystem hierarchy to examine potential
309
<code>.htaccess</code> files would be a very expensive operation,
310
partially defeating the point of caching (to speed up requests),
311
<code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> makes no decision about whether a cached
312
entity is authorised for serving. In other words; if
313
<code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> has cached some content, it will be served
314
from the cache as long as that content has not expired.</p>
316
<p>If, for example, your configuration permits access to a resource by IP
317
address you should ensure that this content is not cached. You can do this by
318
using the <code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code>
319
directive, or <code class="module"><a href="./mod/mod_expires.html">mod_expires</a></code>. Left unchecked,
320
<code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> - very much like a reverse proxy - would cache
321
the content when served and then serve it to any client, on any IP
325
<h3>Local exploits</h3>
328
<p>As requests to end-users can be served from the cache, the cache
329
itself can become a target for those wishing to deface or interfere with
330
content. It is important to bear in mind that the cache must at all
331
times be writable by the user which Apache is running as. This is in
332
stark contrast to the usually recommended situation of maintaining
333
all content unwritable by the Apache user.</p>
335
<p>If the Apache user is compromised, for example through a flaw in
336
a CGI process, it is possible that the cache may be targeted. When
337
using <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code>, it is relatively easy to
338
insert or modify a cached entity.</p>
340
<p>This presents a somewhat elevated risk in comparison to the other
341
types of attack it is possible to make as the Apache user. If you are
342
using <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> you should bear this in mind -
343
ensure you upgrade Apache when security upgrades are announced and
344
run CGI processes as a non-Apache user using <a href="suexec.html">suEXEC</a> if possible.</p>
348
<h3>Cache Poisoning</h3>
351
<p>When running Apache as a caching proxy server, there is also the
352
potential for so-called cache poisoning. Cache Poisoning is a broad
353
term for attacks in which an attacker causes the proxy server to
354
retrieve incorrect (and usually undesirable) content from the backend.
357
<p>For example if the DNS servers used by your system running Apache
358
are vulnerable to DNS cache poisoning, an attacker may be able to control
359
where Apache connects to when requesting content from the origin server.
360
Another example is so-called HTTP request-smuggling attacks.</p>
362
<p>This document is not the correct place for an in-depth discussion
363
of HTTP request smuggling (instead, try your favourite search engine)
364
however it is important to be aware that it is possible to make
365
a series of requests, and to exploit a vulnerability on an origin
366
webserver such that the attacker can entirely control the content
367
retrieved by the proxy.</p>
369
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
370
<div class="section">
371
<h2><a name="filehandle" id="filehandle">File-Handle Caching</a></h2>
374
<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code></li><li><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code></li></ul></td></tr></table>
376
<p>The act of opening a file can itself be a source of delay, particularly
377
on network filesystems. By maintaining a cache of open file descriptors
378
for commonly served files, Apache can avoid this delay. Currently Apache
379
provides two different implementations of File-Handle Caching.</p>
384
<p>The most basic form of caching present in Apache is the file-handle
385
caching provided by <code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code>. Rather than caching
386
file-contents, this cache maintains a table of open file descriptors. Files
387
to be cached in this manner are specified in the configuration file using
388
the <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
392
<code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive
393
instructs Apache to open the file when Apache is started and to re-use
394
this file-handle for all subsequent access to this file.</p>
396
<div class="example"><pre>CacheFile /usr/local/apache2/htdocs/index.html</pre></div>
398
<p>If you intend to cache a large number of files in this manner, you
399
must ensure that your operating system's limit for the number of open
400
files is set appropriately.</p>
402
<p>Although using <code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code>
403
does not cause the file-contents to be cached per-se, it does mean
404
that if the file changes while Apache is running these changes will
405
not be picked up. The file will be consistently served as it was
406
when Apache was started.</p>
408
<p>If the file is removed while Apache is running, Apache will continue
409
to maintain an open file descriptor and serve the file as it was when
410
Apache was started. This usually also means that although the file
411
will have been deleted, and not show up on the filesystem, extra free
412
space will not be recovered until Apache is stopped and the file
413
descriptor closed.</p>
416
<h3>CacheEnable fd</h3>
419
<p><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> also provides its own file-handle
420
caching scheme, which can be enabled via the
421
<code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code> directive.</p>
423
<div class="example"><pre>CacheEnable fd /</pre></div>
425
<p>As with all of <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code> this type of file-handle
426
caching is intelligent, and handles will not be maintained beyond
427
the expiry time of the cached content.</p>
429
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
430
<div class="section">
431
<h2><a name="inmemory" id="inmemory">In-Memory Caching</a></h2>
434
<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code></li><li><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code></li><li><code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code></li></ul></td></tr></table>
436
<p>Serving directly from system memory is universally the fastest method
437
of serving content. Reading files from a disk controller or, even worse,
438
from a remote network is orders of magnitude slower. Disk controllers
439
usually involve physical processes, and network access is limited by
440
your available bandwidth. Memory access on the other hand can take mere
443
<p>System memory isn't cheap though, byte for byte it's by far the most
444
expensive type of storage and it's important to ensure that it is used
445
efficiently. By caching files in memory you decrease the amount of
446
memory available on the system. As we'll see, in the case of operating
447
system caching, this is not so much of an issue, but when using
448
Apache's own in-memory caching it is important to make sure that you
449
do not allocate too much memory to a cache. Otherwise the system
450
will be forced to swap out memory, which will likely degrade
453
<h3>Operating System Caching</h3>
456
<p>Almost all modern operating systems cache file-data in memory managed
457
directly by the kernel. This is a powerful feature, and for the most
458
part operating systems get it right. For example, on Linux, let's look at
459
the difference in the time it takes to read a file for the first time
460
and the second time;</p>
462
<div class="example"><pre>
463
colm@coroebus:~$ time cat testfile > /dev/null
467
colm@coroebus:~$ time cat testfile > /dev/null
470
sys 0m0.000s</pre></div>
472
<p>Even for this small file, there is a huge difference in the amount
473
of time it takes to read the file. This is because the kernel has cached
474
the file contents in memory.</p>
476
<p>By ensuring there is "spare" memory on your system, you can ensure
477
that more and more file-contents will be stored in this cache. This
478
can be a very efficient means of in-memory caching, and involves no
479
extra configuration of Apache at all.</p>
481
<p>Additionally, because the operating system knows when files are
482
deleted or modified, it can automatically remove file contents from the
483
cache when neccessary. This is a big advantage over Apache's in-memory
484
caching which has no way of knowing when a file has changed.</p>
487
<p>Despite the performance and advantages of automatic operating system
488
caching there are some circumstances in which in-memory caching may be
489
better performed by Apache.</p>
491
<p>Firstly, an operating system can only cache files it knows about. If
492
you are running Apache as a proxy server, the files you are caching are
493
not locally stored but remotely served. If you still want the unbeatable
494
speed of in-memory caching, Apache's own memory caching is needed.</p>
496
<h3>MMapStatic Caching</h3>
499
<p><code class="module"><a href="./mod/mod_file_cache.html">mod_file_cache</a></code> provides the
500
<code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code> directive, which
501
allows you to have Apache map a static file's contents into memory at
502
start time (using the mmap system call). Apache will use the in-memory
503
contents for all subsequent accesses to this file.</p>
505
<div class="example"><pre>MMapStatic /usr/local/apache2/htdocs/index.html</pre></div>
508
<code class="directive"><a href="./mod/mod_file_cache.html#cachefile">CacheFile</a></code> directive, any
509
changes in these files will not be picked up by Apache after it has
512
<p> The <code class="directive"><a href="./mod/mod_file_cache.html#mmapstatic">MMapStatic</a></code>
513
directive does not keep track of how much memory it allocates, so
514
you must ensure not to over-use the directive. Each Apache child
515
process will replicate this memory, so it is critically important
516
to ensure that the files mapped are not so large as to cause the
517
system to swap memory.</p>
520
<h3>mod_mem_cache Caching</h3>
523
<p><code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> provides a HTTP-aware intelligent
524
in-memory cache. It also uses heap memory directly, which means that
525
even if <var>MMap</var> is not supported on your system,
526
<code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code> may still be able to perform caching.</p>
528
<p>Caching of this type is enabled via;</p>
530
<div class="example"><pre>
531
# Enable memory caching
534
# Limit the size of the cache to 1 Megabyte
535
MCacheSize 1024</pre></div>
537
</div><div class="top"><a href="#page-header"><img alt="top" src="./images/up.gif" /></a></div>
538
<div class="section">
539
<h2><a name="disk" id="disk">Disk-based Caching</a></h2>
542
<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code></li></ul></td><td><ul><li><code class="directive"><a href="./mod/mod_cache.html#cacheenable">CacheEnable</a></code></li><li><code class="directive"><a href="./mod/mod_cache.html#cachedisable">CacheDisable</a></code></li></ul></td></tr></table>
544
<p><code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> provides a disk-based caching mechanism
545
for <code class="module"><a href="./mod/mod_cache.html">mod_cache</a></code>. As with <code class="module"><a href="./mod/mod_mem_cache.html">mod_mem_cache</a></code>
546
this cache is intelligent and content will be served from the cache only
547
as long as it is considered valid.</p>
549
<p>Typically the module will be configured as so;</p>
551
<div class="example"><pre>
552
CacheRoot /var/cache/apache/
555
CacheDirLength 1</pre></div>
557
<p>Importantly, as the cached files are locally stored, operating system
558
in-memory caching will typically be applied to their access also. So
559
although the files are stored on disk, if they are frequently accessed
560
it is likely the operating system will ensure that they are actually
561
served from memory.</p>
563
<h3>Understanding the Cache-Store</h3>
566
<p>To store items in the cache, <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> creates
567
a 22 character hash of the url being requested. Thie hash incorporates
568
the hostname, protocol, port, path and any CGI arguments to the URL,
569
to ensure that multiple URLs do not collide.</p>
571
<p>Each character may be any one of 64-different characters, which mean
572
that overall there are 22^64 possible hashes. For example, a URL might
573
be hashed to <code>xyTGxSMO2b68mBCykqkp1w</code>. This hash is used
574
as a prefix for the naming of the files specific to that url within
575
the cache, however first it is split up into directories as per
576
the <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code> and
577
<code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code>
580
<p><code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code>
581
specifies how many levels of subdirectory there should be, and
582
<code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code>
583
specifies how many characters should be in each directory. With
584
the example settings given above, the hash would be turned into
586
<code>/var/cache/apache/x/y/TGxSMO2b68mBCykqkp1w</code>.</p>
588
<p>The overall aim of this technique is to reduce the number of
589
subdirectories or files that may be in a particular directory,
590
as most file-systems slow down as this number increases. With
592
<code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code>
593
there can at most be 64 subdirectories at any particular level.
594
With a setting of 2 there can be 64 * 64 subdirectories, and so on.
595
Unless you have a good reason not to, using a setting of "1"
596
for <code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlength">CacheDirLength</a></code>
600
<code class="directive"><a href="./mod/mod_disk_cache.html#cachedirlevels">CacheDirLevels</a></code>
601
depends on how many files you anticipate to store in the cache.
602
With the setting of "2" used in the above example, a grand
603
total of 4096 subdirectories can ultimately be created. With
604
1 million files cached, this works out at roughly 245 cached
605
urls per directory.</p>
607
<p>Each url uses at least two files in the cache-store. Typically
608
there is a ".header" file, which includes meta-information about
609
the url, such as when it is due to expire and a ".data" file
610
which is a verbatim copy of the content to be served.</p>
612
<p>In the case of a content negotiated via the "Vary" header, a
613
".vary" directory will be created for the url in question. This
614
directory will have multiple ".data" files corresponding to the
615
differently negotiated content.</p>
618
<h3>Maintaining the Disk Cache</h3>
621
<p>Although <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> will remove cached content
622
as it is expired, it does not maintain any information on the total
623
size of the cache or how little free space may be left.</p>
625
<p>Instead, provided with Apache is the <a href="programs/htcacheclean.html">htcacheclean</a> tool which, as the name
626
suggests, allows you to clean the cache periodically. Determining
627
how frequently to run <a href="programs/htcacheclean.html">htcacheclean</a> and what target size to
628
use for the cache is somewhat complex and trial and error may be needed to
629
select optimal values.</p>
631
<p><a href="programs/htcacheclean.html">htcacheclean</a> has two modes of
632
operation. It can be run as persistent daemon, or periodically from
633
cron. <a href="programs/htcacheclean.html">htcacheclean</a> can take up to an hour
634
or more to process very large (tens of gigabytes) caches and if you are
635
running it from cron it is recommended that you determine how long a typical
636
run takes, to avoid running more than one instance at a time.</p>
639
<img src="images/caching_fig1.gif" alt="" width="600" height="406" /><br />
640
<a id="figure1" name="figure1"><dfn>Figure 1</dfn></a>: Typical
641
cache growth / clean sequence.</p>
643
<p>Because <code class="module"><a href="./mod/mod_disk_cache.html">mod_disk_cache</a></code> does not itself pay attention
644
to how much space is used you should ensure that
645
<a href="programs/htcacheclean.html">htcacheclean</a> is configured to
646
leave enough "grow room" following a clean.</p>
650
<div class="bottomlang">
651
<p><span>Available Languages: </span><a href="./en/caching.html" title="English"> en </a></p>
652
</div><div id="footer">
653
<p class="apache">Copyright 2006 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
654
<p class="menu"><a href="./mod/">Modules</a> | <a href="./mod/directives.html">Directives</a> | <a href="./faq/">FAQ</a> | <a href="./glossary.html">Glossary</a> | <a href="./sitemap.html">Sitemap</a></p></div>
b'\\ No newline at end of file'
added
removed
docs/manual/caching.html.en
