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     <highlight language="config">
  66 ExpiresDefault "<var>base</var>  [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
  67 ExpiresByType type/encoding "<var>base</var>  [plus <var>num</var> <var>type</var>] [<var>num</var> <var>type</var>] ..."
  68     </highlight>
  69
  70     <p>where <var>base</var> is one of:</p>
  71
  72     <ul>
  73       <li><code>access</code></li>
  74
  75       <li><code>now</code> (equivalent to
  76       '<code>access</code>')</li>
  77
  78       <li><code>modification</code></li>
  79     </ul>
  80
  81     <p>The <code>plus</code> keyword is optional. <var>num</var>
  82     should be an integer value [acceptable to <code>atoi()</code>],
  83     and <var>type</var> is one of:</p>
  84
  85     <ul>
  86       <li><code>years</code></li>
  87       <li><code>months</code></li>
  88       <li><code>weeks</code></li>
  89       <li><code>days</code></li>
  90       <li><code>hours</code></li>
  91       <li><code>minutes</code></li>
  92       <li><code>seconds</code></li>
  93     </ul>
  94
  95     <p>For example, any of the following directives can be used to
  96     make documents expire 1 month after being accessed, by
  97     default:</p>
  98
  99     <highlight language="config">
 100 ExpiresDefault "access plus 1 month"
 101 ExpiresDefault "access plus 4 weeks"
 102 ExpiresDefault "access plus 30 days"
 103     </highlight>
 104
 105     <p>The expiry time can be fine-tuned by adding several
 106     '<var>num</var> <var>type</var>' clauses:</p>
 107
 108     <highlight language="config">
 109 ExpiresByType text/html "access plus 1 month 15 days 2 hours"
 110 ExpiresByType image/gif "modification plus 5 hours 3 minutes"
 111     </highlight>
 112
 113     <p>Note that if you use a modification date based setting, the
 114     Expires header will <strong>not</strong> be added to content
 115     that does not come from a file on disk. This is due to the fact
 116     that there is no modification time for such content.</p>
 117 </section>
 118
 119 <directivesynopsis>
 120 <name>ExpiresActive</name>
 121 <description>Enables generation of <code>Expires</code>
 122 headers</description>
 123 <syntax>ExpiresActive On|Off</syntax>
 124 <default>ExpiresActive Off</default>
 125 <contextlist><context>server config</context>
 126 <context>virtual host</context><context>directory</context>
 127 <context>.htaccess</context></contextlist>
 128 <override>Indexes</override>
 129
 130 <usage>
 131     <p>This directive enables or disables the generation of the
 132     <code>Expires</code> and <code>Cache-Control</code> headers for
 133     the document realm in question.  (That is, if found in an
 134     <code>.htaccess</code> file, for instance, it applies only to
 135     documents generated from that directory.) If set to
 136     <code>Off</code>, the headers will not be generated for any
 137     document in the realm (unless overridden at a lower level, such as
 138     an <code>.htaccess</code> file overriding a server config
 139     file). If set to <code>On</code>, the headers will be added to
 140     served documents according to the criteria defined by the
 141     <directive module="mod_expires">ExpiresByType</directive> and
 142     <directive module="mod_expires">ExpiresDefault</directive>
 143     directives (<em>q.v.</em>).</p>
 144
 145     <p>Note that this directive does not guarantee that an
 146     <code>Expires</code> or <code>Cache-Control</code> header will be
 147     generated. If the criteria aren't met, no header will be sent, and
 148     the effect will be as though this directive wasn't even
 149     specified.</p>
 150  </usage>
 151 </directivesynopsis>
 152
 153 <directivesynopsis>
 154 <name>ExpiresByType</name>
 155 <description>Value of the <code>Expires</code> header configured
 156 by MIME type</description>
 157 <syntax>ExpiresByType <var>MIME-type</var>
 158 <var>&lt;code&gt;seconds</var></syntax>
 159 <contextlist><context>server config</context><context>virtual host</context>
 160 <context>directory</context><context>.htaccess</context></contextlist>
 161 <override>Indexes</override>
 162
 163 <usage>
 164     <p>This directive defines the value of the <code>Expires</code>
 165     header and the <code>max-age</code> directive of the
 166     <code>Cache-Control</code> header generated for documents of the
 167     specified type (<em>e.g.</em>, <code>text/html</code>). The second
 168     argument sets the number of seconds that will be added to a base
 169     time to construct the expiration date.  The <code>Cache-Control:
 170     max-age</code> is calculated by subtracting the request time from
 171     the expiration date and expressing the result in seconds.</p>
 172
 173     <p>The base time is either the last modification time of the
 174     file, or the time of the client's access to the document. Which
 175     should be used is specified by the
 176     <code><var>&lt;code&gt;</var></code> field; <code>M</code>
 177     means that the file's last modification time should be used as
 178     the base time, and <code>A</code> means the client's access
 179     time should be used.</p>
 180
 181     <p>The difference in effect is subtle. If <code>M</code> is used,
 182     all current copies of the document in all caches will expire at
 183     the same time, which can be good for something like a weekly
 184     notice that's always found at the same URL. If <code>A</code> is
 185     used, the date of expiration is different for each client; this
 186     can be good for image files that don't change very often,
 187     particularly for a set of related documents that all refer to
 188     the same images (<em>i.e.</em>, the images will be accessed
 189     repeatedly within a relatively short timespan).</p>
 190
 191     <example><title>Example:</title>
 192     <highlight language="config">
 193 # enable expirations
 194 ExpiresActive On
 195 # expire GIF images after a month in the client's cache
 196 ExpiresByType image/gif A2592000
 197 # HTML documents are good for a week from the
 198 # time they were changed
 199 ExpiresByType text/html M604800
 200       </highlight>
 201     </example>
 202
 203     <p>Note that this directive only has effect if
 204     <code>ExpiresActive On</code> has been specified. It overrides,
 205     for the specified MIME type <em>only</em>, any expiration date
 206     set by the <directive module="mod_expires">ExpiresDefault</directive>
 207     directive.</p>
 208
 209     <p>You can also specify the expiration time calculation using
 210     an <a href="#AltSyn">alternate syntax</a>, described earlier in
 211     this document.</p>
 212 </usage>
 213 </directivesynopsis>
 214
 215 <directivesynopsis>
 216 <name>ExpiresDefault</name>
 217 <description>Default algorithm for calculating expiration time</description>
 218 <syntax>ExpiresDefault <var>&lt;code&gt;seconds</var></syntax>
 219 <contextlist><context>server config</context><context>virtual host</context>
 220 <context>directory</context><context>.htaccess</context></contextlist>
 221 <override>Indexes</override>
 222
 223 <usage>
 224     <p>This directive sets the default algorithm for calculating the
 225     expiration time for all documents in the affected realm. It can be
 226     overridden on a type-by-type basis by the <directive
 227     module="mod_expires">ExpiresByType</directive> directive. See the
 228     description of that directive for details about the syntax of the
 229     argument, and the <a href="#AltSyn">alternate syntax</a>
 230     description as well.</p>
 231 </usage>
 232 </directivesynopsis>
 233 </modulesynopsis>
 234