granicus.if.org Git - apache/blob - docs/manual/mod/mod_expires.xml

   1 <?xml version="1.0"?>
   2 <!DOCTYPE modulesynopsis SYSTEM "../style/modulesynopsis.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision$ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <modulesynopsis metafile="mod_expires.xml.meta">
  24
  25 <name>mod_expires</name>
  26 <description>Generation of <code>Expires</code> and
  27 <code>Cache-Control</code> HTTP headers according to user-specified
  28 criteria</description>
  29 <status>Extension</status>
  30 <sourcefile>mod_expires.c</sourcefile>
  31 <identifier>expires_module</identifier>
  32
  33 <summary>
  34     <p>This module controls the setting of the <code>Expires</code>
  35     HTTP header and the <code>max-age</code> directive of the
  36     <code>Cache-Control</code> HTTP header in server responses. The
  37     expiration date can set to be relative to either the time the
  38     source file was last modified, or to the time of the client
  39     access.</p>
  40
  41     <p>These HTTP headers are an instruction to the client about the
  42     document's validity and persistence. If cached, the document may
  43     be fetched from the cache rather than from the source until this
  44     time has passed. After that, the cache copy is considered
  45     "expired" and invalid, and a new copy must be obtained from the
  46     source.</p>
  47
  48     <p>To modify <code>Cache-Control</code> directives other than
  49     <code>max-age</code> (see <a
  50     href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec14.html#sec14.9">RFC
  51     2616 section 14.9</a>), you can use the <directive
  52     module="mod_headers">Header</directive> directive.</p>
  53
  54     <p> When the <code>Expires</code> header is already part of the response
  55     generated by the server, for example when generated by a CGI script or
  56     proxied from an origin server, this module does not change or add
  57     an <code>Expires</code> or <code>Cache-Control</code> header..</p>
  58 </summary>
  59
  60 <section id="AltSyn"><title>Alternate Interval Syntax</title>
  61     <p>The <directive module="mod_expires">ExpiresDefault</directive> and
  62     <directive module="mod_expires">ExpiresByType</directive> directives
  63     can also be defined in a more readable syntax of the form:</p>
  64
  65     <example>
  66       ExpiresDefault "&lt;base&gt; [plus] {&lt;num&gt;
  67       &lt;type&gt;}*"<br />
  68       ExpiresByType type/encoding "&lt;base&gt; [plus]
  69       {&lt;num&gt; &lt;type&gt;}*"
  70     </example>
  71
  72     <p>where &lt;base&gt; is one of:</p>
  73
  74     <ul>
  75       <li><code>access</code></li>
  76
  77       <li><code>now</code> (equivalent to
  78       '<code>access</code>')</li>
  79
  80       <li><code>modification</code></li>
  81     </ul>
  82
  83     <p>The <code>plus</code> keyword is optional. &lt;num&gt;
  84     should be an integer value [acceptable to <code>atoi()</code>],
  85     and &lt;type&gt; is one of:</p>
  86
  87     <ul>
  88       <li><code>years</code></li>
  89       <li><code>months</code></li>
  90       <li><code>weeks</code></li>
  91       <li><code>days</code></li>
  92       <li><code>hours</code></li>
  93       <li><code>minutes</code></li>
  94       <li><code>seconds</code></li>
  95     </ul>
  96
  97     <p>For example, any of the following directives can be used to
  98     make documents expire 1 month after being accessed, by
  99     default:</p>
 100
 101     <example>
 102       ExpiresDefault "access plus 1 month"<br />
 103       ExpiresDefault "access plus 4 weeks"<br />
 104       ExpiresDefault "access plus 30 days"
 105     </example>
 106
 107     <p>The expiry time can be fine-tuned by adding several
 108     '&lt;num&gt; &lt;type&gt;' clauses:</p>
 109
 110     <example>
 111       ExpiresByType text/html "access plus 1 month 15
 112       days 2 hours"<br />
 113       ExpiresByType image/gif "modification plus 5 hours 3
 114       minutes"
 115     </example>
 116
 117     <p>Note that if you use a modification date based setting, the
 118     Expires header will <strong>not</strong> be added to content
 119     that does not come from a file on disk. This is due to the fact
 120     that there is no modification time for such content.</p>
 121 </section>
 122
 123 <directivesynopsis>
 124 <name>ExpiresActive</name>
 125 <description>Enables generation of <code>Expires</code>
 126 headers</description>
 127 <syntax>ExpiresActive On|Off</syntax>
 128 <default>ExpiresActive Off</default>
 129 <contextlist><context>server config</context>
 130 <context>virtual host</context><context>directory</context>
 131 <context>.htaccess</context></contextlist>
 132 <override>Indexes</override>
 133
 134 <usage>
 135     <p>This directive enables or disables the generation of the
 136     <code>Expires</code> and <code>Cache-Control</code> headers for
 137     the document realm in question.  (That is, if found in an
 138     <code>.htaccess</code> file, for instance, it applies only to
 139     documents generated from that directory.) If set to
 140     <code>Off</code>, the headers will not be generated for any
 141     document in the realm (unless overridden at a lower level, such as
 142     an <code>.htaccess</code> file overriding a server config
 143     file). If set to <code>On</code>, the headers will be added to
 144     served documents according to the criteria defined by the
 145     <directive module="mod_expires">ExpiresByType</directive> and
 146     <directive module="mod_expires">ExpiresDefault</directive>
 147     directives (<em>q.v.</em>).</p>
 148
 149     <p>Note that this directive does not guarantee that an
 150     <code>Expires</code> or <code>Cache-Control</code> header will be
 151     generated. If the criteria aren't met, no header will be sent, and
 152     the effect will be as though this directive wasn't even
 153     specified.</p>
 154  </usage>
 155 </directivesynopsis>
 156
 157 <directivesynopsis>
 158 <name>ExpiresByType</name>
 159 <description>Value of the <code>Expires</code> header configured
 160 by MIME type</description>
 161 <syntax>ExpiresByType <var>MIME-type</var>
 162 <var>&lt;code&gt;seconds</var></syntax>
 163 <contextlist><context>server config</context><context>virtual host</context>
 164 <context>directory</context><context>.htaccess</context></contextlist>
 165 <override>Indexes</override>
 166
 167 <usage>
 168     <p>This directive defines the value of the <code>Expires</code>
 169     header and the <code>max-age</code> directive of the
 170     <code>Cache-Control</code> header generated for documents of the
 171     specified type (<em>e.g.</em>, <code>text/html</code>). The second
 172     argument sets the number of seconds that will be added to a base
 173     time to construct the expiration date.  The <code>Cache-Control:
 174     max-age</code> is calculated by subtracting the request time from
 175     the expiration date and expressing the result in seconds.</p>
 176
 177     <p>The base time is either the last modification time of the
 178     file, or the time of the client's access to the document. Which
 179     should be used is specified by the
 180     <code><var>&lt;code&gt;</var></code> field; <code>M</code>
 181     means that the file's last modification time should be used as
 182     the base time, and <code>A</code> means the client's access
 183     time should be used.</p>
 184
 185     <p>The difference in effect is subtle. If <code>M</code> is used,
 186     all current copies of the document in all caches will expire at
 187     the same time, which can be good for something like a weekly
 188     notice that's always found at the same URL. If <code>A</code> is
 189     used, the date of expiration is different for each client; this
 190     can be good for image files that don't change very often,
 191     particularly for a set of related documents that all refer to
 192     the same images (<em>i.e.</em>, the images will be accessed
 193     repeatedly within a relatively short timespan).</p>
 194
 195     <example><title>Example:</title>
 196       # enable expirations<br />
 197       ExpiresActive On<br />
 198       # expire GIF images after a month in the client's cache<br />
 199       ExpiresByType image/gif A2592000<br />
 200       # HTML documents are good for a week from the<br />
 201       # time they were changed<br />
 202       ExpiresByType text/html M604800
 203     </example>
 204
 205     <p>Note that this directive only has effect if
 206     <code>ExpiresActive On</code> has been specified. It overrides,
 207     for the specified MIME type <em>only</em>, any expiration date
 208     set by the <directive module="mod_expires">ExpiresDefault</directive>
 209     directive.</p>
 210
 211     <p>You can also specify the expiration time calculation using
 212     an <a href="#AltSyn">alternate syntax</a>, described earlier in
 213     this document.</p>
 214 </usage>
 215 </directivesynopsis>
 216
 217 <directivesynopsis>
 218 <name>ExpiresDefault</name>
 219 <description>Default algorithm for calculating expiration time</description>
 220 <syntax>ExpiresDefault <var>&lt;code&gt;seconds</var></syntax>
 221 <contextlist><context>server config</context><context>virtual host</context>
 222 <context>directory</context><context>.htaccess</context></contextlist>
 223 <override>Indexes</override>
 224
 225 <usage>
 226     <p>This directive sets the default algorithm for calculating the
 227     expiration time for all documents in the affected realm. It can be
 228     overridden on a type-by-type basis by the <directive
 229     module="mod_expires">ExpiresByType</directive> directive. See the
 230     description of that directive for details about the syntax of the
 231     argument, and the <a href="#AltSyn">alternate syntax</a>
 232     description as well.</p>
 233 </usage>
 234 </directivesynopsis>
 235 </modulesynopsis>
 236