<?xml version="1.0"?>
<!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
-<?xml-stylesheet type="text/xsl" href="../style/manual.xsl"?>
-<modulesynopsis>
+<?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_expires.xml.meta">
<name>mod_expires</name>
-<description>Generation of
- <code>Expires</code> HTTP headers according to user-specified
- criteria</description>
+<description>Generation of <code>Expires</code> and
+<code>Cache-Control</code> HTTP headers according to user-specified
+criteria</description>
<status>Extension</status>
<sourcefile>mod_expires.c</sourcefile>
<identifier>expires_module</identifier>
<summary>
<p>This module controls the setting of the <code>Expires</code>
- HTTP header in server responses. The expiration date can set to
- be relative to either the time the source file was last
- modified, or to the time of the client access.</p>
-
- <p>The <code>Expires</code> HTTP header is an instruction to
- the client about the document's validity and persistence. If
- cached, the document may be fetched from the cache rather than
- from the source until this time has passed. After that, the
- cache copy is considered "expired" and invalid, and a new copy
- must be obtained from the source.</p>
+ HTTP header and the <code>max-age</code> directive of the
+ <code>Cache-Control</code> HTTP header in server responses. The
+ expiration date can set to be relative to either the time the
+ source file was last modified, or to the time of the client
+ access.</p>
+
+ <p>These HTTP headers are an instruction to the client about the
+ document's validity and persistence. If cached, the document may
+ be fetched from the cache rather than from the source until this
+ time has passed. After that, the cache copy is considered
+ "expired" and invalid, and a new copy must be obtained from the
+ source.</p>
+
+ <p>To modify <code>Cache-Control</code> directives other than
+ <code>max-age</code> (see <a
+ href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">RFC
+ 2616 section 14.9</a>), you can use the <directive
+ module="mod_headers">Header</directive> directive.</p>
+
+ <p> When the <code>Expires</code> header is already part of the response
+ generated by the server, for example when generated by a CGI script or
+ proxied from an origin server, this module does not change or add
+ an <code>Expires</code> or <code>Cache-Control</code> header..</p>
</summary>
-<section id="AltSyn"><title>Alternate Interval
- Syntax</title>
-
- <p>The <directive module="mod_expires">ExpiresDefault</directive> and
+<section id="AltSyn"><title>Alternate Interval Syntax</title>
+ <p>The <directive module="mod_expires">ExpiresDefault</directive> and
<directive module="mod_expires">ExpiresByType</directive> directives
can also be defined in a more readable syntax of the form:</p>
-<example>
- ExpiresDefault "<base> [plus] {<num>
+ <example>
+ ExpiresDefault "<base> [plus] {<num>
<type>}*"<br />
- ExpiresByType type/encoding "<base> [plus]
+ ExpiresByType type/encoding "<base> [plus]
{<num> <type>}*"
-</example>
+ </example>
<p>where <base> is one of:</p>
<li><code>modification</code></li>
</ul>
- <p>The '<code>plus</code>' keyword is optional. <num>
+ <p>The <code>plus</code> keyword is optional. <num>
should be an integer value [acceptable to <code>atoi()</code>],
and <type> is one of:</p>
<ul>
<li><code>years</code></li>
-
<li><code>months</code></li>
-
<li><code>weeks</code></li>
-
<li><code>days</code></li>
-
<li><code>hours</code></li>
-
<li><code>minutes</code></li>
-
<li><code>seconds</code></li>
</ul>
make documents expire 1 month after being accessed, by
default:</p>
-<example>
- ExpiresDefault "access plus 1 month"<br />
- ExpiresDefault "access plus 4 weeks"<br />
- ExpiresDefault "access plus 30 days"
-</example>
+ <example>
+ ExpiresDefault "access plus 1 month"<br />
+ ExpiresDefault "access plus 4 weeks"<br />
+ ExpiresDefault "access plus 30 days"
+ </example>
<p>The expiry time can be fine-tuned by adding several
'<num> <type>' clauses:</p>
-<example>
-ExpiresByType text/html "access plus 1 month 15
+ <example>
+ ExpiresByType text/html "access plus 1 month 15
days 2 hours"<br />
- ExpiresByType image/gif "modification plus 5 hours 3
+ ExpiresByType image/gif "modification plus 5 hours 3
minutes"
-</example>
+ </example>
<p>Note that if you use a modification date based setting, the
Expires header will <strong>not</strong> be added to content
<directivesynopsis>
<name>ExpiresActive</name>
-<description>Enables generation of <code>Expires</code> headers</description>
+<description>Enables generation of <code>Expires</code>
+headers</description>
<syntax>ExpiresActive On|Off</syntax>
+<default>ExpiresActive Off</default>
<contextlist><context>server config</context>
<context>virtual host</context><context>directory</context>
<context>.htaccess</context></contextlist>
<usage>
<p>This directive enables or disables the generation of the
- <code>Expires</code> header for the document realm in question.
- (That is, if found in an <code>.htaccess</code> file, for
- instance, it applies only to documents generated from that
- directory.) If set to <em><code>Off</code></em>, no
- <code>Expires</code> header will be generated for any document
- in the realm (unless overridden at a lower level, such as an
- <code>.htaccess</code> file overriding a server config file).
- If set to <em><code>On</code></em>, the header will be added to
- served documents according to the criteria defined by the
- <directive module="mod_expires">ExpiresByType</directive> and
- <directive module="mod_expires">ExpiresDefault</directive> directives
- (<em>q.v.</em>).</p>
+ <code>Expires</code> and <code>Cache-Control</code> headers for
+ the document realm in question. (That is, if found in an
+ <code>.htaccess</code> file, for instance, it applies only to
+ documents generated from that directory.) If set to
+ <code>Off</code>, the headers will not be generated for any
+ document in the realm (unless overridden at a lower level, such as
+ an <code>.htaccess</code> file overriding a server config
+ file). If set to <code>On</code>, the headers will be added to
+ served documents according to the criteria defined by the
+ <directive module="mod_expires">ExpiresByType</directive> and
+ <directive module="mod_expires">ExpiresDefault</directive>
+ directives (<em>q.v.</em>).</p>
<p>Note that this directive does not guarantee that an
- <code>Expires</code> header will be generated. If the criteria
- aren't met, no header will be sent, and the effect will be as
- though this directive wasn't even specified.</p>
-</usage>
+ <code>Expires</code> or <code>Cache-Control</code> header will be
+ generated. If the criteria aren't met, no header will be sent, and
+ the effect will be as though this directive wasn't even
+ specified.</p>
+ </usage>
</directivesynopsis>
<directivesynopsis>
<name>ExpiresByType</name>
<description>Value of the <code>Expires</code> header configured
by MIME type</description>
-<syntax>ExpiresByType
- <em>MIME-type <code>seconds</em></syntax>
-<contextlist><context>server config</context>
-<context>virtual host</context><context>directory</context>
-<context>.htaccess</context></contextlist>
+<syntax>ExpiresByType <var>MIME-type</var>
+<var><code>seconds</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
<override>Indexes</override>
<usage>
<p>This directive defines the value of the <code>Expires</code>
- header generated for documents of the specified type
- (<em>e.g.</em>, <code>text/html</code>). The second argument
- sets the number of seconds that will be added to a base time to
- construct the expiration date.</p>
+ header and the <code>max-age</code> directive of the
+ <code>Cache-Control</code> header generated for documents of the
+ specified type (<em>e.g.</em>, <code>text/html</code>). The second
+ argument sets the number of seconds that will be added to a base
+ time to construct the expiration date. The <code>Cache-Control:
+ max-age</code> is calculated by subtracting the request time from
+ the expiration date and expressing the result in seconds.</p>
<p>The base time is either the last modification time of the
file, or the time of the client's access to the document. Which
should be used is specified by the
- <code><em><code></em></code> field; <strong>M</strong>
+ <code><var><code></var></code> field; <code>M</code>
means that the file's last modification time should be used as
- the base time, and <strong>A</strong> means the client's access
+ the base time, and <code>A</code> means the client's access
time should be used.</p>
- <p>The difference in effect is subtle. If <em>M</em> is used,
+ <p>The difference in effect is subtle. If <code>M</code> is used,
all current copies of the document in all caches will expire at
the same time, which can be good for something like a weekly
- notice that's always found at the same URL. If <em>A</em> is
+ notice that's always found at the same URL. If <code>A</code> is
used, the date of expiration is different for each client; this
can be good for image files that don't change very often,
particularly for a set of related documents that all refer to
the same images (<em>i.e.</em>, the images will be accessed
repeatedly within a relatively short timespan).</p>
- <p><strong>Example:</strong></p>
-<example>
-# enable expirations<br />
-ExpiresActive On<br />
-# expire GIF images after a month in the client's cache<br />
-ExpiresByType image/gif A2592000<br />
-# HTML documents are good for a week from the time they were changed<br />
-ExpiresByType text/html M604800
-</example>
+ <example><title>Example:</title>
+ # enable expirations<br />
+ ExpiresActive On<br />
+ # expire GIF images after a month in the client's cache<br />
+ ExpiresByType image/gif A2592000<br />
+ # HTML documents are good for a week from the<br />
+ # time they were changed<br />
+ ExpiresByType text/html M604800
+ </example>
<p>Note that this directive only has effect if
<code>ExpiresActive On</code> has been specified. It overrides,
<directivesynopsis>
<name>ExpiresDefault</name>
<description>Default algorithm for calculating expiration time</description>
-<syntax>ExpiresDefault <em><code>seconds</em></syntax>
-<contextlist><context>server config</context>
-<context>virtual host</context><context>directory</context>
-<context>.htaccess</context></contextlist>
+<syntax>ExpiresDefault <var><code>seconds</var></syntax>
+<contextlist><context>server config</context><context>virtual host</context>
+<context>directory</context><context>.htaccess</context></contextlist>
<override>Indexes</override>
<usage>
projects / apache / blobdiff