mod_expires.html revision f9b3be308809978f797e0c57b296147532a4313c
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran BGCOLOR="#FFFFFF"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran TEXT="#000000"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran LINK="#0000FF"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran VLINK="#000080"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ALINK="#FF0000"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <!--#include virtual="header.html" -->
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran This module is contained in the <CODE>mod_expires.c</CODE> file, and
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran is <STRONG>not</STRONG> compiled in by default. It provides for the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran generation of <CODE>Expires</CODE> headers according to user-specified
571909175b4f9a1ef15ec4afead6d6d463dbe760Dana Myers This module controls the setting of the <CODE>Expires</CODE> HTTP
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran header in server responses. The expiration date can set to be
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu relative to either the time the source file was last modified, or to
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran the time of the client access.
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran The <CODE>Expires</CODE> HTTP header is an instruction to the client
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran about the document's validity and persistence. If cached, the document
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran may be fetched from the cache rather than from the source until this
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran time has passed. After that, the cache copy is considered
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran "expired" and invalid, and a new copy must be obtained from
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresactive"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresActive</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresbytype"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresByType</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresdefault"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresDefault</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresActive directive
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu <!--%plaintext <?INDEX {\tt ExpiresActive} directive> -->
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>Syntax:</STRONG> ExpiresActive <EM>boolean</EM>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran This directive enables or disables the generation of the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <CODE>Expires</CODE> header for the document realm in question. (That
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran is, if found in an <CODE>.htaccess</CODE> file, for instance, it
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran applies only to documents generated from that directory.) If set to
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <EM><CODE>Off</CODE></EM>, no <CODE>Expires</CODE> header will be
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran generated for any document in the realm (unless overridden at a lower
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran level, such as an <CODE>.htaccess</CODE> file overriding a server
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran config file). If set to <EM><CODE>On</CODE></EM>, the header will be
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran added to served documents according to the criteria defined by the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresbytype"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresByType</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresdefault"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresDefault</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran Note that this directive does not guarantee that an
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <CODE>Expires</CODE> header will be generated. If the criteria aren't
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran met, no header will be sent, and the effect will be as though this
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran directive wasn't even specified.
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresByType directive
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <!--%plaintext <?INDEX {\tt ExpiresByType} directive> -->
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>Syntax:</STRONG> ExpiresByType <EM>mime-type <code>seconds</EM>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran This directive defines the value of the <CODE>Expires</CODE> header
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran generated for documents of the specified type (<EM>e.g.</EM>,
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <CODE>text/html</CODE>). The second argument sets the number of
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran seconds that will be added to a base time to construct the expiration
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran The base time is either the last modification time of the file, or the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran time of the client's access to the document. Which should be used is
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran specified by the <CODE><EM><code></EM></CODE> field;
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>M</STRONG> means that the file's last modification time should
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran be used as the base time, and <STRONG>A</STRONG> means the client's
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran access time should be used.
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran The difference in effect is subtle. If <EM>M</EM> is used, all current
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran copies of the document in all caches will expire at the same time,
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran which can be good for something like a weekly notice that's always
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu found at the same URL. If <EM>A</EM> is used, the date of expiration
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran is different for each client; this can be good for image files that
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran don't change very often, particularly for a set of related documents
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran that all refer to the same images (<EM>i.e.</EM>, the images will be
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran accessed repeatedly within a relatively short timespan).
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresActive On # enable expirations
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresByType image/gif A2592000 # expire GIF images after a month
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu # in the client's cache
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu ExpiresByType text/html M604800 # HTML documents are good for a
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu # week from the time they were
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu # changed, period
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu Note that this directive only has effect if <CODE>ExpiresActive
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu On</CODE> has been specified. It overrides, for the specified MIME
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu type <EM>only</EM>, any expiration date set by the
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu HREF="#expiresdefault"
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu >ExpiresDefault</A>
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu You can also specify the expiration time calculation using an
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu HREF="#AltSyn"
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu >alternate syntax</A>,
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu described later in this document.
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu ExpiresDefault directive
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu <!--%plaintext <?INDEX {\tt ExpiresDefault} directive> -->
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu <STRONG>Syntax:</STRONG> ExpiresDefault <EM><code>seconds</EM>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <STRONG>Context:</STRONG> server config, virtual host, directory, .htaccess
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran This directive sets the default algorithm for calculating the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran expiration time for all documents in the affected realm. It can be
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran overridden on a type-by-type basis by the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresbytype"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >ExpiresByType</A>
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu directive. See the description of that directive for details about
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu the syntax of the argument, and the
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#AltSyn"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran >alternate syntax</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran description as well.
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <A NAME="AltSyn">Alternate Interval Syntax</A>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresdefault"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran HREF="#expiresbytype"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran directives can also be defined in a more readable syntax of the form:
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <DD><CODE>ExpiresDefault "<base> [plus] {<num> <type>}*"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresByType type/encoding "<base> [plus] {<num> <type>}*"</CODE>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran where <base> is one of:
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <LI><SAMP>now</SAMP> (equivalent to '<SAMP>access</SAMP>')
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran The '<SAMP>plus</SAMP>' keyword is optional. <num> should be an
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran integer value [acceptable to <SAMP>atoi()</SAMP>], and <type>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran For example, any of the following directives can be used to make
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran documents expire 1 month after being accessed, by default:
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <DD><CODE>ExpiresDefault "access plus 1 month"
a31148363f598def767ac48c5d82e1572e44b935Gerry Liu ExpiresDefault "access plus 4 weeks"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresDefault "access plus 30 days"</CODE>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran The expiry time can be fine-tuned by adding several '<num> <type>'
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <DD><CODE>ExpiresByType text/html "access plus 1 month 15 days 2 hours"
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran ExpiresByType image/gif "modification plus 5 hours 3 minutes"</CODE>
b72d5b75fd6f5bb08d29f65652d60058fc3a2608Michael Corcoran <!--#include virtual="footer.html" -->