mod_expires.xml revision 69cdc59729e1a733aafee3ef613eadfb8e437c11
ad53c2449238379699243be05926645262e9581eChristian Maeder<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski<!-- $LastChangedRevision$ -->
e899b993b4f642217274fda6f462fe1318ae3626Christian Maeder Licensed to the Apache Software Foundation (ASF) under one or more
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder contributor license agreements. See the NOTICE file distributed with
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder this work for additional information regarding copyright ownership.
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder The ASF licenses this file to You under the Apache License, Version 2.0
e6d40133bc9f858308654afb1262b8b483ec5922Till Mossakowski (the "License"); you may not use this file except in compliance with
679d3f541f7a9ede4079e045f7758873bb901872Till Mossakowski the License. You may obtain a copy of the License at
56c56b2181e76c239929ddade2925ba5c3f3fffdChristian Maeder Unless required by applicable law or agreed to in writing, software
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder distributed under the License is distributed on an "AS IS" BASIS,
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
306763c67bb99228487345b32ab8c5c6cd41f23cChristian Maeder See the License for the specific language governing permissions and
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder limitations under the License.
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<modulesynopsis metafile="mod_expires.xml.meta">
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<description>Generation of <code>Expires</code> and
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder<code>Cache-Control</code> HTTP headers according to user-specified
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maedercriteria</description>
1842453990fed8a1bd7a5ac792d7982c1d2bfcd5Christian Maeder <p>This module controls the setting of the <code>Expires</code>
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder HTTP header and the <code>max-age</code> directive of the
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian Maeder <code>Cache-Control</code> HTTP header in server responses. The
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maeder expiration date can set to be relative to either the time the
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian Maeder source file was last modified, or to the time of the client
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian Maeder <p>These HTTP headers are an instruction to the client about the
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder document's validity and persistence. If cached, the document may
1bc5dccbf0083a620ae1181c717fea75e4af5e5cChristian Maeder be fetched from the cache rather than from the source until this
b60a22e76e983e8129c5dae4d713fe2794ed7054Christian Maeder time has passed. After that, the cache copy is considered
ba904a15082557e939db689fcfba0c68c9a4f740Christian Maeder "expired" and invalid, and a new copy must be obtained from the
f3e815e0f960f2c002904b18ad75c149a3827d9fChristian Maeder <p>To modify <code>Cache-Control</code> directives other than
4b136ad539bd9f4e115dff4eee4d552a42d4437eChristian Maeder href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">RFC
b91b82fd2625c349da6284f252cf4c50a6519650Christian Maeder 2616 section 14.9</a>), you can use the <directive
e1abb0a8a17632e11db927958ab8cf58635bdf96Christian Maeder module="mod_headers">Header</directive> directive.</p>
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian Maeder <p> When the <code>Expires</code> header is already part of the response
697e63e30aa3c309a1ef1f9357745111f8dfc5a9Christian Maeder generated by the server, for example when generated by a CGI script or
54ea981a0503c396c2923a1c06421c6235baf27fChristian Maeder proxied from an origin server, this module does not change or add
e1abb0a8a17632e11db927958ab8cf58635bdf96Christian Maeder an <code>Expires</code> or <code>Cache-Control</code> header.</p>
df9a64f1f61bf944b2116f92fce7083ff291debcChristian Maeder<section id="AltSyn"><title>Alternate Interval Syntax</title>
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian Maeder <p>The <directive module="mod_expires">ExpiresDefault</directive> and
df9a64f1f61bf944b2116f92fce7083ff291debcChristian Maeder <directive module="mod_expires">ExpiresByType</directive> directives
f4651a172fa4d00037b061fbe4df71abc69f12b5Christian Maeder can also be defined in a more readable syntax of the form:</p>
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian MaederExpiresDefault "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
5b14cb4855372bd9578cc07a9f6f9f3076bc033cChristian MaederExpiresByType type/encoding "<var>base</var> [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder <p>The <code>plus</code> keyword is optional. <var>num</var>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder should be an integer value [acceptable to <code>atoi()</code>],
e46d78f7c6324ed9f1a191d46b6e5732e61e1835Simon Ulbricht <p>For example, any of the following directives can be used to
7a6c50ecdec40e0278e8ed4fdadfd669112d887dChristian Maeder make documents expire 1 month after being accessed, by
7a6c50ecdec40e0278e8ed4fdadfd669112d887dChristian MaederExpiresDefault "access plus 1 month"
22dac733a93bc32b8db195625edea6364079a89eChristian MaederExpiresDefault "access plus 4 weeks"
22dac733a93bc32b8db195625edea6364079a89eChristian MaederExpiresDefault "access plus 30 days"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder <p>The expiry time can be fine-tuned by adding several
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder '<var>num</var> <var>type</var>' clauses:</p>
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian MaederExpiresByType text/html "access plus 1 month 15 days 2 hours"
4fc9de0da898448f1d3597ebbd8c04a066464c21Christian MaederExpiresByType image/gif "modification plus 5 hours 3 minutes"
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder <p>Note that if you use a modification date based setting, the
a4cb1786d23060c8521a88f08f9909589fa83a12Christian Maeder Expires header will <strong>not</strong> be added to content
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder that does not come from a file on disk. This is due to the fact
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder that there is no modification time for such content.</p>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder<directivesynopsis>
c5653d37b37dcc025ff6dd1eada95ae67116e699Christian Maeder<description>Enables generation of <code>Expires</code>
22dac733a93bc32b8db195625edea6364079a89eChristian Maederheaders</description>
f4651a172fa4d00037b061fbe4df71abc69f12b5Christian Maeder<contextlist><context>server config</context>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder<context>virtual host</context><context>directory</context>
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder <p>This directive enables or disables the generation of the
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder <code>Expires</code> and <code>Cache-Control</code> headers for
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder the document realm in question. (That is, if found in an
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder <code>.htaccess</code> file, for instance, it applies only to
e49fd57c63845c7806860a9736ad09f6d44dbaedChristian Maeder documents generated from that directory.) If set to
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder <code>Off</code>, the headers will not be generated for any
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder document in the realm (unless overridden at a lower level, such as
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder an <code>.htaccess</code> file overriding a server config
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maeder file). If set to <code>On</code>, the headers will be added to
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maeder served documents according to the criteria defined by the
ad53c2449238379699243be05926645262e9581eChristian Maeder <directive module="mod_expires">ExpiresByType</directive> and
17d4f8c5576d93f36cafe68161cdb960ec49ce7cChristian Maeder <directive module="mod_expires">ExpiresDefault</directive>
0155c8d32b79581866f07cc593aa8a4c722ceef2Christian Maeder <p>Note that this directive does not guarantee that an
bfb2ae5ac1ccfacbfa29ffa240838461e18f4d49Christian Maeder <code>Expires</code> or <code>Cache-Control</code> header will be
0bc3e99a05ed12fafe271ab855c15c866b50827cMihai Codescu generated. If the criteria aren't met, no header will be sent, and
b5a5755f7d034f5ebc9f7f45e878c68695e139c4Thiemo Wiedemeyer the effect will be as though this directive wasn't even
b5a5755f7d034f5ebc9f7f45e878c68695e139c4Thiemo Wiedemeyer specified.</p>
c488ac18796ad6383b1edf7fa2820edc8296c89eChristian Maeder</directivesynopsis>
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder<directivesynopsis>
7ad31de80b6544478f15dde43e22f0b7f612c438Thiemo Wiedemeyer<description>Value of the <code>Expires</code> header configured
295566c1778f463b624caf1be714b70d808e2a51Ewaryst Schulzby MIME type</description>
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder<contextlist><context>server config</context><context>virtual host</context>
0d0278c34a374b29c2d6c58b39b8b56e283d48e8Christian Maeder<context>directory</context><context>.htaccess</context></contextlist>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder <p>This directive defines the value of the <code>Expires</code>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder header and the <code>max-age</code> directive of the
b46e2dfbd64caaedc51507fbff7f08f4d2b4d080Christian Maeder <code>Cache-Control</code> header generated for documents of the
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maeder specified type (<em>e.g.</em>, <code>text/html</code>). The second
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maeder argument sets the number of seconds that will be added to a base
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maeder time to construct the expiration date. The <code>Cache-Control:
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maeder max-age</code> is calculated by subtracting the request time from
c72a6b711518a31fe947a03601426d06c59edbd2Christian Maeder the expiration date and expressing the result in seconds.</p>
8a2beea4bd05c640b6848837c2ab0399f22afb72Christian Maeder <p>The base time is either the last modification time of the
c72a6b711518a31fe947a03601426d06c59edbd2Christian Maeder file, or the time of the client's access to the document. Which
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder should be used is specified by the
74d9a385499bf903b24848dff450a153f525bda7Christian Maeder <code><var><code></var></code> field; <code>M</code>
c72a6b711518a31fe947a03601426d06c59edbd2Christian Maeder means that the file's last modification time should be used as
95c3e5d11dcee331dc3876a9bf0c1d6daa38e2caChristian Maeder the base time, and <code>A</code> means the client's access
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder time should be used.</p>
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder <p>The difference in effect is subtle. If <code>M</code> is used,
db7143998eee23e3d781f1f1e97e953bb831df1fTill Mossakowski all current copies of the document in all caches will expire at
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder the same time, which can be good for something like a weekly
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder notice that's always found at the same URL. If <code>A</code> is
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder used, the date of expiration is different for each client; this
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder can be good for image files that don't change very often,
2b6aa5d5fc7da111461c0837f1a0abe0f35fa984Christian Maeder particularly for a set of related documents that all refer to
9a9860760c6f30558e5e60049692b6fc63904590Markus Gross the same images (<em>i.e.</em>, the images will be accessed
4f8a6dee8333cac3769f6952d64965867e017f4dChristian Maeder repeatedly within a relatively short timespan).</p>
591c279c7bacf79bccdb1e7417cc44130527d895Christian Maeder# enable expirations
9a9860760c6f30558e5e60049692b6fc63904590Markus GrossExpiresActive On
df5eb1b8e587946c9d072f4ee6ac7d001719b034Christian Maeder# expire GIF images after a month in the client's cache
260bfc3b7dc8ed037b7d98ee044302415db6fcd7Christian Maeder# HTML documents are good for a week from the
260bfc3b7dc8ed037b7d98ee044302415db6fcd7Christian Maeder# time they were changed
591c279c7bacf79bccdb1e7417cc44130527d895Christian Maeder <p>Note that this directive only has effect if
591c279c7bacf79bccdb1e7417cc44130527d895Christian Maeder <code>ExpiresActive On</code> has been specified. It overrides,
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder for the specified MIME type <em>only</em>, any expiration date
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder set by the <directive module="mod_expires">ExpiresDefault</directive>
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder directive.</p>
92487d2ec0c4f9fa81e0213311e214861d232f42Thiemo Wiedemeyer <p>You can also specify the expiration time calculation using
92487d2ec0c4f9fa81e0213311e214861d232f42Thiemo Wiedemeyer an <a href="#AltSyn">alternate syntax</a>, described earlier in
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder this document.</p>
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder</directivesynopsis>
a3963596b8a24e870708767e064a9e24cfa7e5edChristian Maeder<directivesynopsis>
15a50ae940b17c65d2b3c68918a26de29e565370Thiemo Wiedemeyer<description>Default algorithm for calculating expiration time</description>
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer<syntax>ExpiresDefault <var><code>seconds</var></syntax>
5b00a9d748d5bea461601ed7ed5198dfd30cf2d2Thiemo Wiedemeyer<contextlist><context>server config</context><context>virtual host</context>
39a2520d13a7d43f0c0fa71b94255c3f7c500005Christian Maeder<context>directory</context><context>.htaccess</context></contextlist>
84ba39232a012abf2085c8a421ebce6abc52d56eThiemo Wiedemeyer <p>This directive sets the default algorithm for calculating the
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder expiration time for all documents in the affected realm. It can be
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder overridden on a type-by-type basis by the <directive
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder module="mod_expires">ExpiresByType</directive> directive. See the
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder description of that directive for details about the syntax of the
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder argument, and the <a href="#AltSyn">alternate syntax</a>
38e6a7281140deb96436868d396e1a0a3c934c2cChristian Maeder description as well.</p>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder</directivesynopsis>
22dac733a93bc32b8db195625edea6364079a89eChristian Maeder</modulesynopsis>