granicus.if.org Git - apache/blob - docs/manual/mod/mod_mime.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_mime.xml.meta">
  24
  25 <name>mod_mime</name>
  26 <description>Associates the requested filename's extensions
  27     with the file's behavior (handlers and filters)
  28     and content (mime-type, language, character set and
  29     encoding)</description>
  30 <status>Base</status>
  31 <sourcefile>mod_mime.c</sourcefile>
  32 <identifier>mime_module</identifier>
  33
  34 <summary>
  35     <p>This module is used to assign content metadata to the content
  36     selected for an HTTP response by mapping patterns in the
  37     URI or filenames to the metadata values.  For example, the filename
  38     extensions of content files often define the content's Internet
  39     media type, language, character set, and content-encoding. This
  40     information is sent in HTTP messages containing that content and
  41     used in content negotiation when selecting alternatives, such that
  42     the user's preferences are respected when choosing one of several
  43     possible contents to serve. See
  44     <module>mod_negotiation</module> for more information
  45     about <a href="../content-negotiation.html">content negotiation</a>.</p>
  46
  47     <p>The directives <directive
  48     module="mod_mime">AddCharset</directive>, <directive
  49     module="mod_mime">AddEncoding</directive>, <directive
  50     module="mod_mime">AddLanguage</directive> and <directive
  51     module="mod_mime">AddType</directive> are all used to map file
  52     extensions onto the metadata for that file. Respectively
  53     they set the character set, content-encoding, content-language,
  54     and <glossary>media-type</glossary> (content-type) of documents.  The directive <directive
  55     module="mod_mime">TypesConfig</directive> is used to specify a
  56     file which also maps extensions onto media types. </p>
  57
  58     <p>In addition, <module>mod_mime</module> may define the <a
  59     href="../handler.html">handler</a> and <a
  60     href="../filter.html">filters</a> that originate and process
  61     content.  The directives <directive
  62     module="mod_mime">AddHandler</directive>, <directive
  63     module="mod_mime">AddOutputFilter</directive>, and <directive
  64     module="mod_mime">AddInputFilter</directive> control the modules
  65     or scripts that serve the document.  The <directive
  66     module="mod_mime">MultiviewsMatch</directive> directive allows
  67     <module>mod_negotiation</module> to consider these file extensions
  68     to be included when testing Multiviews matches.</p>
  69
  70     <p>While <module>mod_mime</module> associates metadata
  71     with filename extensions, the <module>core</module> server
  72     provides directives that are used to associate all the files in a
  73     given container (<em>e.g.</em>, <directive type="section"
  74     module="core">Location</directive>, <directive type="section"
  75     module="core">Directory</directive>, or <directive type="section"
  76     module="core">Files</directive>) with particular
  77     metadata. These directives include <directive
  78     module="core">ForceType</directive>, <directive
  79     module="core">SetHandler</directive>, <directive
  80     module="core">SetInputFilter</directive>, and <directive
  81     module="core">SetOutputFilter</directive>.  The core directives
  82     override any filename extension mappings defined in
  83     <module>mod_mime</module>.</p>
  84
  85     <p>Note that changing the metadata for a file does not
  86     change the value of the <code>Last-Modified</code> header.
  87     Thus, previously cached copies may still be used by a client or
  88     proxy, with the previous headers. If you change the
  89     metadata (language, content type, character set or
  90     encoding) you may need to 'touch' affected files (updating
  91     their last modified date) to ensure that all visitors are
  92     receive the corrected content headers.</p>
  93 </summary>
  94 <seealso><directive
  95 module="mod_mime_magic">MimeMagicFile</directive></seealso>
  96 <seealso><directive module="core">AddDefaultCharset</directive></seealso>
  97 <seealso><directive module="core">ForceType</directive></seealso>
  98 <seealso><directive module="core">SetHandler</directive></seealso>
  99 <seealso><directive module="core">SetInputFilter</directive></seealso>
 100 <seealso><directive module="core">SetOutputFilter</directive></seealso>
 101
 102 <section id="multipleext"><title>Files with Multiple Extensions</title>
 103     <p>Files can have more than one extension; the order of the
 104     extensions is <em>normally</em> irrelevant. For example, if the
 105     file <code>welcome.html.fr</code> maps onto content type
 106     <code>text/html</code> and language French then the file
 107     <code>welcome.fr.html</code> will map onto exactly the same
 108     information.  If more than one extension is given that maps onto
 109     the same type of metadata, then the one to the right will
 110     be used, except for languages and content encodings. For example,
 111     if <code>.gif</code> maps to the <glossary>media-type</glossary>
 112     <code>image/gif</code> and <code>.html</code> maps to the
 113     media-type <code>text/html</code>, then the file
 114     <code>welcome.gif.html</code> will be associated with the
 115     media-type <code>text/html</code>.</p>
 116
 117     <p><a href="#charset-lang">Languages</a> and <a href="#contentencoding"
 118     >content encodings</a> are treated accumulative, because one can assign
 119     more than one language or encoding to a particular resource. For example,
 120     the file <code>welcome.html.en.de</code> will be delivered with
 121     <code>Content-Language: en, de</code> and <code>Content-Type:
 122     text/html</code>.</p>
 123
 124     <p>Care should be taken when a file with multiple extensions
 125     gets associated with both a <glossary>media-type</glossary>
 126     and a handler. This will
 127     usually result in the request being handled by the module associated
 128     with the handler. For example, if the <code>.imap</code>
 129     extension is mapped to the handler <code>imap-file</code> (from
 130     <module>mod_imagemap</module>) and the <code>.html</code> extension is
 131     mapped to the media-type <code>text/html</code>, then the file
 132     <code>world.imap.html</code> will be associated with both the
 133     <code>imap-file</code> handler and <code>text/html</code> media-type.
 134     When it is processed, the <code>imap-file</code> handler will be used,
 135     and so it will be treated as a <module>mod_imagemap</module> imagemap
 136     file.</p>
 137
 138     <p>If you would prefer only the last dot-separated part of the
 139     filename to be mapped to a particular piece of meta-data, then do
 140     not use the <code>Add*</code> directives. For example, if you wish
 141     to have the file <code>foo.html.cgi</code> processed as a CGI
 142     script, but not the file <code>bar.cgi.html</code>, then instead
 143     of using <code>AddHandler cgi-script .cgi</code>, use</p>
 144
 145     <example><title>Configure handler based on final extension only</title>
 146     <highlight language="config">
 147 &lt;FilesMatch "[^.]+\.cgi$"&gt;
 148   SetHandler cgi-script
 149 &lt;/FilesMatch&gt;
 150     </highlight>
 151     </example>
 152
 153 </section>
 154
 155 <section id="contentencoding"><title>Content encoding</title>
 156     <p>A file of a particular <glossary>media-type</glossary> can additionally be encoded a
 157     particular way to simplify transmission over the Internet.
 158     While this usually will refer to compression, such as
 159     <code>gzip</code>, it can also refer to encryption, such a
 160     <code>pgp</code> or to an encoding such as UUencoding, which is
 161     designed for transmitting a binary file in an ASCII (text)
 162     format.</p>
 163
 164     <p>The <a href="http://www.ietf.org/rfc/rfc2616.txt">HTTP/1.1
 165     RFC</a>, section 14.11 puts it this way:</p>
 166
 167     <blockquote cite="http://www.ietf.org/rfc/rfc2616.txt">
 168       <p>The Content-Encoding entity-header field is used as a modifier to
 169       the media-type. When present, its value indicates what additional
 170       content codings have been applied to the entity-body, and thus what
 171       decoding mechanisms must be applied in order to obtain the media-type
 172       referenced by the Content-Type header field. Content-Encoding is
 173       primarily used to allow a document to be compressed without losing
 174       the identity of its underlying media type.</p>
 175     </blockquote>
 176
 177     <p>By using more than one file extension (see <a
 178     href="#multipleext">section above about multiple file
 179     extensions</a>), you can indicate that a file is of a
 180     particular <em>type</em>, and also has a particular
 181     <em>encoding</em>. </p>
 182
 183     <p>For example, you may have a file which is a Microsoft Word
 184     document, which is pkzipped to reduce its size. If the
 185     <code>.doc</code> extension is associated with the Microsoft
 186     Word file type, and the <code>.zip</code> extension is
 187     associated with the pkzip file encoding, then the file
 188     <code>Resume.doc.zip</code> would be known to be a pkzip'ed Word
 189     document.</p>
 190
 191     <p>Apache sends a <code>Content-encoding</code> header with the
 192     resource, in order to tell the client browser about the
 193     encoding method.</p>
 194
 195     <highlight language="config">
 196 Content-encoding: pkzip
 197     </highlight>
 198 </section>
 199
 200 <section id="charset-lang"><title>Character sets and languages</title>
 201     <p>In addition to file type and the file encoding,
 202     another important piece of information is what language a
 203     particular document is in, and in what character set the file
 204     should be displayed. For example, the document might be written
 205     in the Vietnamese alphabet, or in Cyrillic, and should be
 206     displayed as such. This information, also, is transmitted in
 207     HTTP headers.</p>
 208
 209     <p>The character set, language, encoding and mime type are all
 210     used in the process of content negotiation (See
 211     <module>mod_negotiation</module>) to determine
 212     which document to give to the client, when there are
 213     alternative documents in more than one character set, language,
 214     encoding or mime type. All filename extensions associations
 215     created with <directive module="mod_mime">AddCharset</directive>,
 216     <directive module="mod_mime">AddEncoding</directive>, <directive
 217     module="mod_mime">AddLanguage</directive> and <directive
 218     module="mod_mime">AddType</directive> directives
 219     (and extensions listed in the <directive module="mod_mime_magic"
 220     >MimeMagicFile</directive>) participate in this select process.
 221     Filename extensions that are only associated using the <directive
 222     module="mod_mime">AddHandler</directive>, <directive module="mod_mime"
 223     >AddInputFilter</directive> or <directive module="mod_mime"
 224     >AddOutputFilter</directive> directives may be included or excluded
 225     from matching by using the <directive module="mod_mime"
 226     >MultiviewsMatch</directive> directive.</p>
 227
 228     <section id="charset"><title>Charset</title>
 229       <p>To convey this further information, Apache optionally sends
 230       a <code>Content-Language</code> header, to specify the language
 231       that the document is in, and can append additional information
 232       onto the <code>Content-Type</code> header to indicate the
 233       particular character set that should be used to correctly
 234       render the information.</p>
 235
 236       <example>
 237 Content-Language: en, fr
 238 Content-Type: text/plain; charset=ISO-8859-1
 239       </example>
 240
 241       <p>The language specification is the two-letter abbreviation
 242       for the language. The <code>charset</code> is the name of the
 243       particular character set which should be used.</p>
 244     </section>
 245 </section>
 246
 247 <directivesynopsis>
 248 <name>AddCharset</name>
 249 <description>Maps the given filename extensions to the specified content
 250 charset</description>
 251 <syntax>AddCharset <var>charset</var> <var>extension</var>
 252 [<var>extension</var>] ...</syntax>
 253 <contextlist><context>server config</context><context>virtual host</context>
 254 <context>directory</context><context>.htaccess</context></contextlist>
 255 <override>FileInfo</override>
 256
 257 <usage>
 258     <p>The <directive>AddCharset</directive> directive maps the given
 259     filename extensions to the specified content charset (the Internet
 260     registered name for a given character encoding). <var>charset</var>
 261     is the <a href="http://www.iana.org/assignments/character-sets">media
 262     type's charset parameter</a> for resources with filenames containing
 263     <var>extension</var>. This mapping is added to any already in force,
 264     overriding any mappings that already exist for the same
 265     <var>extension</var>.</p>
 266
 267     <example><title>Example</title>
 268     <highlight language="config">
 269 AddLanguage ja .ja
 270 AddCharset EUC-JP .euc
 271 AddCharset ISO-2022-JP .jis
 272 AddCharset SHIFT_JIS .sjis
 273       </highlight>
 274     </example>
 275
 276     <p>Then the document <code>xxxx.ja.jis</code> will be treated
 277     as being a Japanese document whose charset is <code>ISO-2022-JP</code>
 278     (as will the document <code>xxxx.jis.ja</code>). The
 279     <directive>AddCharset</directive> directive is useful for both to
 280     inform the client about the character encoding of the document so that
 281     the document can be interpreted and displayed appropriately, and for <a
 282     href="../content-negotiation.html">content negotiation</a>,
 283     where the server returns one from several documents based on
 284     the client's charset preference.</p>
 285
 286     <p>The <var>extension</var> argument is case-insensitive and can
 287     be specified with or without a leading dot. Filenames may have <a
 288     href="#multipleext">multiple extensions</a> and the
 289     <var>extension</var> argument will be compared against each of
 290     them.</p>
 291
 292 </usage>
 293 <seealso><module>mod_negotiation</module></seealso>
 294 <seealso><directive module="core">AddDefaultCharset</directive></seealso>
 295 </directivesynopsis>
 296
 297 <directivesynopsis>
 298 <name>AddEncoding</name>
 299 <description>Maps the given filename extensions to the specified encoding
 300 type</description>
 301 <syntax>AddEncoding <var>encoding</var> <var>extension</var>
 302 [<var>extension</var>] ...</syntax>
 303 <contextlist><context>server config</context><context>virtual host</context>
 304 <context>directory</context><context>.htaccess</context></contextlist>
 305 <override>FileInfo</override>
 306
 307 <usage>
 308     <p>The <directive>AddEncoding</directive> directive maps the given
 309     filename extensions to the specified HTTP content-encoding.
 310     <var>encoding</var> is the HTTP content coding to append to the
 311     value of the Content-Encoding header field for documents named with the
 312     <var>extension</var>. This mapping is added to any already in force,
 313     overriding any mappings that already exist for the same
 314     <var>extension</var>.</p>
 315
 316     <example><title>Example</title>
 317     <highlight language="config">
 318 AddEncoding x-gzip .gz
 319 AddEncoding x-compress .Z
 320       </highlight>
 321     </example>
 322
 323     <p>This will cause filenames containing the <code>.gz</code> extension
 324     to be marked as encoded using the <code>x-gzip</code> encoding, and
 325     filenames containing the <code>.Z</code> extension to be marked as
 326     encoded with <code>x-compress</code>.</p>
 327
 328     <p>Old clients expect <code>x-gzip</code> and <code>x-compress</code>,
 329     however the standard dictates that they're equivalent to
 330     <code>gzip</code> and <code>compress</code> respectively. Apache does
 331     content encoding comparisons by ignoring any leading <code>x-</code>.
 332     When responding with an encoding Apache will use whatever form
 333     (<em>i.e.</em>, <code>x-foo</code> or <code>foo</code>) the
 334     client requested. If the client didn't specifically request a
 335     particular form Apache will use the form given by the
 336     <code>AddEncoding</code> directive. To make this long story
 337     short, you should always use <code>x-gzip</code> and
 338     <code>x-compress</code> for these two specific encodings. More
 339     recent encodings, such as <code>deflate</code>, should be
 340     specified without the <code>x-</code>.</p>
 341
 342     <p>The <var>extension</var> argument is case-insensitive and can
 343     be specified with or without a leading dot. Filenames may have <a
 344     href="#multipleext">multiple extensions</a> and the
 345     <var>extension</var> argument will be compared against each of
 346     them.</p>
 347 </usage>
 348 </directivesynopsis>
 349
 350 <directivesynopsis>
 351 <name>AddHandler</name>
 352 <description>Maps the filename extensions to the specified
 353 handler</description>
 354 <syntax>AddHandler <var>handler-name</var> <var>extension</var>
 355 [<var>extension</var>] ...</syntax>
 356 <contextlist><context>server config</context><context>virtual host</context>
 357 <context>directory</context><context>.htaccess</context></contextlist>
 358 <override>FileInfo</override>
 359
 360 <usage>
 361     <p>Files having the name <var>extension</var> will be served by the
 362     specified <var><a href="../handler.html">handler-name</a></var>. This
 363     mapping is added to any already in force, overriding any mappings that
 364     already exist for the same <var>extension</var>. For example, to
 365     activate CGI scripts with the file extension <code>.cgi</code>, you
 366     might use:</p>
 367
 368     <highlight language="config">
 369 AddHandler cgi-script .cgi
 370     </highlight>
 371
 372     <p>Once that has been put into your httpd.conf file, any file containing
 373     the <code>.cgi</code> extension will be treated as a CGI program.</p>
 374
 375     <p>The <var>extension</var> argument is case-insensitive and can
 376     be specified with or without a leading dot. Filenames may have <a
 377     href="#multipleext">multiple extensions</a> and the
 378     <var>extension</var> argument will be compared against each of
 379     them.</p>
 380 </usage>
 381 <seealso><directive module="core">SetHandler</directive></seealso>
 382 </directivesynopsis>
 383
 384 <directivesynopsis>
 385 <name>AddInputFilter</name>
 386 <description>Maps filename extensions to the filters that will process
 387 client requests</description>
 388 <syntax>AddInputFilter <var>filter</var>[;<var>filter</var>...]
 389 <var>extension</var> [<var>extension</var>] ...</syntax>
 390 <contextlist><context>server config</context><context>virtual host</context>
 391 <context>directory</context><context>.htaccess</context></contextlist>
 392 <override>FileInfo</override>
 393
 394 <usage>
 395     <p><directive>AddInputFilter</directive> maps the filename extension
 396     <var>extension</var> to the <a href="../filter.html">filters</a> which
 397     will process client requests and POST input when they are received by
 398     the server. This is in addition to any filters defined elsewhere,
 399     including the <directive module="core">SetInputFilter</directive>
 400     directive. This mapping is merged over any already in force, overriding
 401     any mappings that already exist for the same <var>extension</var>.</p>
 402
 403     <p>If more than one <var>filter</var> is specified, they must be separated
 404     by semicolons in the order in which they should process the
 405     content. The <var>filter</var> is case-insensitive.</p>
 406
 407     <p>The <var>extension</var> argument is case-insensitive and can
 408     be specified with or without a leading dot. Filenames may have <a
 409     href="#multipleext">multiple extensions</a> and the
 410     <var>extension</var> argument will be compared against each of
 411     them.</p>
 412
 413 </usage>
 414 <seealso><directive module="mod_mime">RemoveInputFilter</directive></seealso>
 415 <seealso><directive module="core">SetInputFilter</directive></seealso>
 416 </directivesynopsis>
 417
 418 <directivesynopsis>
 419 <name>AddLanguage</name>
 420 <description>Maps the given filename extension to the specified content
 421 language</description>
 422 <syntax>AddLanguage <var>language-tag</var> <var>extension</var>
 423 [<var>extension</var>] ...</syntax>
 424 <contextlist><context>server config</context><context>virtual host</context>
 425 <context>directory</context><context>.htaccess</context></contextlist>
 426 <override>FileInfo</override>
 427
 428 <usage>
 429     <p>The <directive>AddLanguage</directive> directive maps the given
 430     filename extension to the specified content language.  Files with the
 431     filename <var>extension</var> are assigned an HTTP Content-Language
 432     value of <var>language-tag</var> corresponding to the language
 433     identifiers defined by RFC 3066.
 434     This directive overrides any mappings that already exist for the same
 435     <var>extension</var>.</p>
 436
 437     <example><title>Example</title>
 438     <highlight language="config">
 439 AddEncoding x-compress .Z
 440 AddLanguage en .en
 441 AddLanguage fr .fr
 442       </highlight>
 443     </example>
 444
 445     <p>Then the document <code>xxxx.en.Z</code> will be treated as
 446     being a compressed English document (as will the document
 447     <code>xxxx.Z.en</code>). Although the content language is
 448     reported to the client, the browser is unlikely to use this
 449     information. The <directive>AddLanguage</directive> directive is
 450     more useful for <a href="../content-negotiation.html">content
 451     negotiation</a>, where the server returns one from several documents
 452     based on the client's language preference.</p>
 453
 454     <p>If multiple language assignments are made for the same
 455     extension, the last one encountered is the one that is used.
 456     That is, for the case of:</p>
 457
 458     <highlight language="config">
 459 AddLanguage en .en
 460 AddLanguage en-gb .en
 461 AddLanguage en-us .en
 462     </highlight>
 463
 464     <p>documents with the extension <code>.en</code> would be treated as
 465     being <code>en-us</code>.</p>
 466
 467     <p>The <var>extension</var> argument is case-insensitive and can
 468     be specified with or without a leading dot. Filenames may have <a
 469     href="#multipleext">multiple extensions</a> and the
 470     <var>extension</var> argument will be compared against each of
 471     them.</p>
 472 </usage>
 473 <seealso><module>mod_negotiation</module></seealso>
 474 </directivesynopsis>
 475
 476 <directivesynopsis>
 477 <name>AddOutputFilter</name>
 478 <description>Maps filename extensions to the filters that will process
 479 responses from the server</description>
 480 <syntax>AddOutputFilter <var>filter</var>[;<var>filter</var>...]
 481 <var>extension</var> [<var>extension</var>] ...</syntax>
 482 <contextlist><context>server config</context><context>virtual host</context>
 483 <context>directory</context><context>.htaccess</context></contextlist>
 484 <override>FileInfo</override>
 485
 486 <usage>
 487     <p>The <directive>AddOutputFilter</directive> directive maps the
 488     filename extension <var>extension</var> to the <a
 489     href="../filter.html">filters</a> which will process responses
 490     from the server before they are sent to the client. This is in
 491     addition to any filters defined elsewhere, including <directive
 492     module="core">SetOutputFilter</directive> and <directive module="mod_filter"
 493     >AddOutputFilterByType</directive> directive. This mapping is merged
 494     over any already in force, overriding any mappings that already exist
 495     for the same <var>extension</var>.</p>
 496
 497     <p>For example, the following configuration will process all
 498     <code>.shtml</code> files for server-side includes and will then
 499     compress the output using <module>mod_deflate</module>.</p>
 500
 501     <highlight language="config">
 502 AddOutputFilter INCLUDES;DEFLATE shtml
 503     </highlight>
 504
 505     <p>If more than one filter is specified, they must be separated
 506     by semicolons in the order in which they should process the
 507     content. The <var>filter</var> argument is case-insensitive.</p>
 508
 509     <p>The <var>extension</var> argument is case-insensitive and can
 510     be specified with or without a leading dot. Filenames may have <a
 511     href="#multipleext">multiple extensions</a> and the
 512     <var>extension</var> argument will be compared against each of
 513     them.</p>
 514
 515     <p>Note that when defining a set of filters using the
 516     <directive module="mod_mime">AddOutputFilter</directive> directive,
 517     any definition made will replace any previous definition made by
 518     the <directive module="mod_mime">AddOutputFilter</directive>
 519     directive.</p>
 520
 521     <highlight language="config">
 522 # Effective filter "DEFLATE"
 523 AddOutputFilter DEFLATE shtml
 524 &lt;Location "/foo"&gt;
 525   # Effective filter "INCLUDES", replacing "DEFLATE"
 526   AddOutputFilter INCLUDES shtml
 527 &lt;/Location&gt;
 528 &lt;Location "/bar"&gt;
 529   # Effective filter "INCLUDES;DEFLATE", replacing "DEFLATE"
 530   AddOutputFilter INCLUDES;DEFLATE shtml
 531 &lt;/Location&gt;
 532 &lt;Location "/bar/baz"&gt;
 533   # Effective filter "BUFFER", replacing "INCLUDES;DEFLATE"
 534   AddOutputFilter BUFFER shtml
 535 &lt;/Location&gt;
 536 &lt;Location "/bar/baz/buz"&gt;
 537   # No effective filter, replacing "BUFFER"
 538   RemoveOutputFilter shtml
 539 &lt;/Location&gt;
 540     </highlight>
 541 </usage>
 542 <seealso><directive module="mod_mime">RemoveOutputFilter</directive></seealso>
 543 <seealso><directive module="core">SetOutputFilter</directive></seealso>
 544 </directivesynopsis>
 545
 546 <directivesynopsis>
 547 <name>AddType</name>
 548 <description>Maps the given filename extensions onto the specified content
 549 type</description>
 550 <syntax>AddType <var>media-type</var> <var>extension</var>
 551 [<var>extension</var>] ...</syntax>
 552 <contextlist><context>server config</context><context>virtual host</context>
 553 <context>directory</context><context>.htaccess</context></contextlist>
 554 <override>FileInfo</override>
 555
 556 <usage>
 557     <p>The <directive>AddType</directive> directive maps the given
 558     filename extensions onto the specified content
 559     type. <var>media-type</var> is the <glossary ref="media-type">media
 560     type</glossary> to use for filenames containing
 561     <var>extension</var>. This mapping is added to any already in
 562     force, overriding any mappings that already exist for the same
 563     <var>extension</var>.</p>
 564
 565     <note>
 566       It is recommended that new media types be added using the
 567       <directive>AddType</directive> directive rather than changing the
 568       <directive module="mod_mime">TypesConfig</directive> file.
 569     </note>
 570
 571     <example><title>Example</title>
 572     <highlight language="config">
 573 AddType image/gif .gif
 574     </highlight>
 575     </example>
 576
 577     <p>Or, to specify multiple file extensions in one directive:</p>
 578
 579     <example><title>Example</title>
 580     <highlight language="config">
 581 AddType image/jpeg jpeg jpg jpe
 582     </highlight>
 583     </example>
 584
 585     <p>The <var>extension</var> argument is case-insensitive and can
 586     be specified with or without a leading dot. Filenames may have <a
 587     href="#multipleext">multiple extensions</a> and the
 588     <var>extension</var> argument will be compared against each of
 589     them.</p>
 590
 591     <p>A similar effect to <module>mod_negotiation</module>'s
 592     <directive module="mod_negotiation">LanguagePriority</directive>
 593     can be achieved by qualifying a <var>media-type</var> with
 594     <code>qs</code>:</p>
 595
 596     <example><title>Example</title>
 597     <highlight language="config">
 598 AddType application/rss+xml;qs=0.8 .xml
 599     </highlight>
 600     </example>
 601
 602     <p>This is useful in situations, <em>e.g.</em> when a client
 603     requesting <code>Accept: */*</code> can not actually processes
 604     the content returned by the server.</p>
 605
 606     <p>This directive primarily configures the content types generated for
 607     static files served out of the filesystem.  For resources other than
 608     static files, where the generator of the response typically specifies
 609     a Content-Type, this directive has no effect.</p>
 610
 611
 612     <note><title>Note</title>
 613     <p>If no handler is explicitly set for a request, the specified content
 614     type will also be used as the handler name. </p>
 615
 616     <p>When explicit directives such as
 617     <directive module="core" >SetHandler</directive> or
 618     <directive module="mod_mime">AddHandler</directive> do not apply
 619     to the current request, the internal handler name normally set by those
 620     directives is instead set to the content type specified by this directive.
 621     </p>
 622     <p>
 623     This is a historical behavior that may be used by some third-party modules
 624     (such as mod_php) for taking responsibility for the matching request.
 625     </p>
 626
 627     <p>Configurations that rely on such "synthetic" types should be avoided.
 628     Additionally, configurations that restrict access to
 629     <directive module="core" >SetHandler</directive> or
 630     <directive module="mod_mime">AddHandler</directive> should
 631     restrict access to this directive as well.</p>
 632     </note>
 633
 634 </usage>
 635 <seealso><directive module="core">ForceType</directive></seealso>
 636 <seealso><module>mod_negotiation</module></seealso>
 637 </directivesynopsis>
 638
 639 <directivesynopsis>
 640 <name>MultiviewsMatch</name>
 641 <description>The types of files that will be included when searching for
 642 a matching file with MultiViews</description>
 643 <syntax>MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers
 644 [Handlers|Filters]</syntax>
 645 <default>MultiviewsMatch NegotiatedOnly</default>
 646 <contextlist><context>server config</context><context>virtual host</context>
 647 <context>directory</context><context>.htaccess</context></contextlist>
 648 <override>FileInfo</override>
 649
 650 <usage>
 651     <p><directive>MultiviewsMatch</directive> permits three different
 652     behaviors for <a href="mod_negotiation.html">mod_negotiation</a>'s
 653     Multiviews feature.  Multiviews allows a request for a file,
 654     <em>e.g.</em> <code>index.html</code>, to match any negotiated
 655     extensions following the base request, <em>e.g.</em>
 656     <code>index.html.en</code>, <code>index.html.fr</code>, or
 657     <code>index.html.gz</code>.</p>
 658
 659     <p>The <code>NegotiatedOnly</code> option provides that every extension
 660     following the base name must correlate to a recognized
 661     <module>mod_mime</module> extension for content negotiation, <em>e.g.</em>
 662     Charset, Content-Type, Language, or Encoding.  This is the strictest
 663     implementation with the fewest unexpected side effects, and is the
 664     default behavior.</p>
 665
 666     <p>To include extensions associated with Handlers and/or Filters,
 667     set the <directive>MultiviewsMatch</directive> directive to either
 668     <code>Handlers</code>, <code>Filters</code>, or both option keywords.
 669     If all other factors are equal, the smallest file will be served,
 670     <em>e.g.</em> in deciding between <code>index.html.cgi</code> of 500
 671     bytes and <code>index.html.pl</code> of 1000 bytes, the <code>.cgi</code>
 672     file would win in this example. Users of <code>.asis</code> files
 673     might prefer to use the Handler option, if <code>.asis</code> files are
 674     associated with the <code>asis-handler</code>.</p>
 675
 676     <p>You may finally allow <code>Any</code> extensions to match, even if
 677     <module>mod_mime</module> doesn't recognize the extension. This can cause
 678     unpredictable results, such as serving .old or .bak files the webmaster
 679     never expected to be served.</p>
 680
 681     <p>For example, the following configuration will allow handlers
 682     and filters to participate in Multviews, but will exclude unknown
 683     files:</p>
 684
 685     <highlight language="config">
 686 MultiviewsMatch Handlers Filters
 687     </highlight>
 688
 689     <p><directive>MultiviewsMatch</directive> is not allowed in a
 690     <directive type="section" module="core">Location</directive> or <directive
 691     type="section" module="core">LocationMatch</directive> section.</p>
 692
 693 </usage>
 694 <seealso><directive module="core">Options</directive></seealso>
 695 <seealso><module>mod_negotiation</module></seealso>
 696 </directivesynopsis>
 697
 698 <directivesynopsis>
 699 <name>DefaultLanguage</name>
 700 <description>Defines a default language-tag to be sent in the Content-Language
 701 header field for all resources in the current context that have not been
 702 assigned a language-tag by some other means.</description>
 703 <syntax>DefaultLanguage <var>language-tag</var></syntax>
 704 <contextlist><context>server config</context><context>virtual host</context>
 705 <context>directory</context><context>.htaccess</context></contextlist>
 706 <override>FileInfo</override>
 707
 708 <usage>
 709     <p>The <directive>DefaultLanguage</directive> directive tells Apache
 710     that all resources in the directive's scope (<em>e.g.</em>, all resources
 711     covered by the current <directive module="core" type="section"
 712     >Directory</directive> container) that don't have an explicit language
 713     extension (such as <code>.fr</code> or <code>.de</code> as configured
 714     by <directive module="mod_mime">AddLanguage</directive>) should be
 715     assigned a Content-Language of <var>language-tag</var>. This allows
 716     entire directory trees to be marked as containing Dutch content, for
 717     instance, without having to rename each file. Note that unlike using
 718     extensions to specify languages, <directive>DefaultLanguage</directive>
 719     can only specify a single language.</p>
 720
 721     <p>If no <directive>DefaultLanguage</directive> directive is in force
 722     and a file does not have any language extensions as configured
 723     by <directive module="mod_mime">AddLanguage</directive>, then no
 724     Content-Language header field will be generated.</p>
 725
 726     <example><title>Example</title>
 727     <highlight language="config">
 728 DefaultLanguage en
 729     </highlight>
 730     </example>
 731 </usage>
 732 <seealso><module>mod_negotiation</module></seealso>
 733 </directivesynopsis>
 734
 735 <directivesynopsis>
 736 <name>ModMimeUsePathInfo</name>
 737 <description>Tells <module>mod_mime</module> to treat <code>path_info</code>
 738 components as part of the filename</description>
 739 <syntax>ModMimeUsePathInfo On|Off</syntax>
 740 <default>ModMimeUsePathInfo Off</default>
 741 <contextlist><context>directory</context></contextlist>
 742
 743 <usage>
 744     <p>The <directive>ModMimeUsePathInfo</directive> directive is used to
 745     combine the filename with the <code>path_info</code> URL component to
 746     apply <module>mod_mime</module>'s directives to the request. The default
 747     value is <code>Off</code> - therefore, the <code>path_info</code>
 748     component is ignored.</p>
 749
 750     <p>This directive is recommended when you have a virtual filesystem.</p>
 751
 752     <example><title>Example</title>
 753     <highlight language="config">
 754 ModMimeUsePathInfo On
 755     </highlight>
 756     </example>
 757
 758     <p>If you have a request for <code>/index.php/foo.shtml</code>
 759     <module>mod_mime</module> will now treat the
 760     incoming request as <code>/index.php/foo.shtml</code> and directives
 761     like <code>AddOutputFilter INCLUDES .shtml</code> will add the
 762     <code>INCLUDES</code> filter to the request. If <directive
 763     >ModMimeUsePathInfo</directive> is not set, the
 764     <code>INCLUDES</code> filter will not be added. This will work
 765     analogously for virtual paths, such as those defined by
 766     <directive type="section">Location</directive></p>
 767 </usage>
 768 <seealso><directive module="core">AcceptPathInfo</directive></seealso>
 769 </directivesynopsis>
 770
 771 <directivesynopsis>
 772 <name>RemoveCharset</name>
 773 <description>Removes any character set associations for a set of file
 774 extensions</description>
 775 <syntax>RemoveCharset <var>extension</var> [<var>extension</var>]
 776 ...</syntax>
 777 <contextlist><context>virtual host</context><context>directory</context>
 778 <context>.htaccess</context></contextlist>
 779 <override>FileInfo</override>
 780
 781 <usage>
 782     <p>The <directive>RemoveCharset</directive> directive removes any
 783     character set associations for files with the given extensions.
 784     This allows <code>.htaccess</code> files in subdirectories to
 785     undo any associations inherited from parent directories or the
 786     server config files.</p>
 787
 788     <p>The <var>extension</var> argument is case-insensitive and can
 789     be specified with or without a leading dot.</p>
 790
 791     <example><title>Example</title>
 792     <highlight language="config">
 793 RemoveCharset .html .shtml
 794     </highlight>
 795     </example>
 796 </usage>
 797 </directivesynopsis>
 798
 799 <directivesynopsis>
 800 <name>RemoveEncoding</name>
 801 <description>Removes any content encoding associations for a set of file
 802 extensions</description>
 803 <syntax>RemoveEncoding <var>extension</var> [<var>extension</var>]
 804 ...</syntax>
 805 <contextlist><context>virtual host</context><context>directory</context>
 806 <context>.htaccess</context></contextlist>
 807 <override>FileInfo</override>
 808
 809 <usage>
 810     <p>The <directive>RemoveEncoding</directive> directive removes any
 811     encoding associations for files with the given extensions. This
 812     allows <code>.htaccess</code> files in subdirectories to undo
 813     any associations inherited from parent directories or the
 814     server config files. An example of its use might be:</p>
 815
 816     <example><title>/foo/.htaccess:</title>
 817     <highlight language="config">
 818 AddEncoding x-gzip .gz
 819 AddType text/plain .asc
 820 &lt;Files "*.gz.asc"&gt;
 821     RemoveEncoding .gz
 822 &lt;/Files&gt;
 823       </highlight>
 824     </example>
 825
 826     <p>This will cause <code>foo.gz</code> to be marked as being
 827     encoded with the gzip method, but <code>foo.gz.asc</code> as an
 828     unencoded plaintext file.</p>
 829
 830     <note><title>Note</title>
 831       <p><directive>RemoveEncoding</directive> directives are processed
 832       <em>after</em> any <directive module="mod_mime">AddEncoding</directive>
 833       directives, so it is possible they may undo the effects of the latter
 834       if both occur within the same directory configuration.</p>
 835     </note>
 836
 837     <p>The <var>extension</var> argument is case-insensitive and can
 838     be specified with or without a leading dot.</p>
 839 </usage>
 840 </directivesynopsis>
 841
 842 <directivesynopsis>
 843 <name>RemoveHandler</name>
 844 <description>Removes any handler associations for a set of file
 845 extensions</description>
 846 <syntax>RemoveHandler <var>extension</var> [<var>extension</var>]
 847 ...</syntax>
 848 <contextlist><context>virtual host</context><context>directory</context>
 849 <context>.htaccess</context></contextlist>
 850 <override>FileInfo</override>
 851
 852 <usage>
 853     <p>The <directive>RemoveHandler</directive> directive removes any
 854     handler associations for files with the given extensions. This allows
 855     <code>.htaccess</code> files in subdirectories to undo any
 856     associations inherited from parent directories or the server
 857     config files. An example of its use might be:</p>
 858
 859     <example><title>/foo/.htaccess:</title>
 860     <highlight language="config">
 861 AddHandler server-parsed .html
 862     </highlight>
 863     </example>
 864
 865     <example><title>/foo/bar/.htaccess:</title>
 866     <highlight language="config">
 867 RemoveHandler .html
 868     </highlight>
 869     </example>
 870
 871     <p>This has the effect of returning <code>.html</code> files in
 872     the <code>/foo/bar</code> directory to being treated as normal
 873     files, rather than as candidates for parsing (see the <module
 874     >mod_include</module> module).</p>
 875
 876     <p>The <var>extension</var> argument is case-insensitive and can
 877     be specified with or without a leading dot.</p>
 878 </usage>
 879 </directivesynopsis>
 880
 881 <directivesynopsis>
 882 <name>RemoveInputFilter</name>
 883 <description>Removes any input filter associations for a set of file
 884 extensions</description>
 885 <syntax>RemoveInputFilter <var>extension</var> [<var>extension</var>]
 886 ...</syntax>
 887 <contextlist><context>virtual host</context><context>directory</context>
 888 <context>.htaccess</context></contextlist>
 889 <override>FileInfo</override>
 890
 891 <usage>
 892     <p>The <directive>RemoveInputFilter</directive> directive removes any
 893     input <a href="../filter.html">filter</a> associations for files with
 894     the given extensions.
 895     This allows <code>.htaccess</code> files in subdirectories to
 896     undo any associations inherited from parent directories or the
 897     server config files.</p>
 898
 899     <p>The <var>extension</var> argument is case-insensitive and can
 900     be specified with or without a leading dot.</p>
 901 </usage>
 902 <seealso><directive module="mod_mime">AddInputFilter</directive></seealso>
 903 <seealso><directive module="core">SetInputFilter</directive></seealso>
 904 </directivesynopsis>
 905
 906 <directivesynopsis>
 907 <name>RemoveLanguage</name>
 908 <description>Removes any language associations for a set of file
 909 extensions</description>
 910 <syntax>RemoveLanguage <var>extension</var> [<var>extension</var>]
 911 ...</syntax>
 912 <contextlist><context>virtual host</context><context>directory</context>
 913 <context>.htaccess</context></contextlist>
 914 <override>FileInfo</override>
 915
 916 <usage>
 917     <p>The <directive>RemoveLanguage</directive> directive removes any
 918     language associations for files with the given extensions. This
 919     allows <code>.htaccess</code> files in subdirectories to undo
 920     any associations inherited from parent directories or the
 921     server config files.</p>
 922
 923     <p>The <var>extension</var> argument is case-insensitive and can
 924     be specified with or without a leading dot.</p>
 925 </usage>
 926 </directivesynopsis>
 927
 928 <directivesynopsis>
 929 <name>RemoveOutputFilter</name>
 930 <description>Removes any output filter associations for a set of file
 931 extensions</description>
 932 <syntax>RemoveOutputFilter <var>extension</var> [<var>extension</var>]
 933 ...</syntax>
 934 <contextlist><context>virtual host</context><context>directory</context>
 935 <context>.htaccess</context></contextlist>
 936 <override>FileInfo</override>
 937
 938 <usage>
 939     <p>The <directive>RemoveOutputFilter</directive> directive removes any
 940     output <a href="../filter.html">filter</a> associations for files with
 941     the given extensions.
 942     This allows <code>.htaccess</code> files in subdirectories to
 943     undo any associations inherited from parent directories or the
 944     server config files.</p>
 945
 946     <p>The <var>extension</var> argument is case-insensitive and can
 947     be specified with or without a leading dot.</p>
 948
 949     <example><title>Example</title>
 950     <highlight language="config">
 951 RemoveOutputFilter shtml
 952     </highlight>
 953     </example>
 954 </usage>
 955 <seealso><directive module="mod_mime">AddOutputFilter</directive></seealso>
 956 </directivesynopsis>
 957
 958 <directivesynopsis>
 959 <name>RemoveType</name>
 960 <description>Removes any content type associations for a set of file
 961 extensions</description>
 962 <syntax>RemoveType <var>extension</var> [<var>extension</var>]
 963 ...</syntax>
 964 <contextlist><context>virtual host</context><context>directory</context>
 965 <context>.htaccess</context></contextlist>
 966 <override>FileInfo</override>
 967
 968 <usage>
 969     <p>The <directive>RemoveType</directive> directive removes any
 970     <glossary ref="media-type">media type</glossary> associations for files with
 971     the given extensions. This allows <code>.htaccess</code> files in
 972     subdirectories to undo any associations inherited from parent
 973     directories or the server config files. An example of its use
 974     might be:</p>
 975
 976     <example><title>/foo/.htaccess:</title>
 977     <highlight language="config">
 978 RemoveType .cgi
 979     </highlight>
 980     </example>
 981
 982     <p>This will remove any special handling of <code>.cgi</code>
 983     files in the <code>/foo/</code> directory and any beneath it,
 984     causing responses containing those files to omit the HTTP
 985     Content-Type header field.</p>
 986
 987     <note><title>Note</title>
 988       <p><directive>RemoveType</directive> directives are processed
 989       <em>after</em> any <directive module="mod_mime">AddType</directive>
 990       directives, so it is possible they may undo the effects of the
 991       latter if both occur within the same directory configuration.</p>
 992     </note>
 993
 994     <p>The <var>extension</var> argument is case-insensitive and can
 995     be specified with or without a leading dot.</p>
 996 </usage>
 997 </directivesynopsis>
 998
 999 <directivesynopsis>
1000 <name>TypesConfig</name>
1001 <description>The location of the <code>mime.types</code> file</description>
1002 <syntax>TypesConfig <var>file-path</var></syntax>
1003 <default>TypesConfig conf/mime.types</default>
1004 <contextlist><context>server config</context></contextlist>
1005
1006 <usage>
1007     <p>The <directive>TypesConfig</directive> directive sets the
1008     location of the <glossary ref="media-type">media types</glossary>
1009     configuration file. <var>File-path</var> is relative to the
1010     <directive module="core">ServerRoot</directive>. This file sets
1011     the default list of mappings from filename extensions to content
1012     types. Most administrators use the <code>mime.types</code> file
1013     provided by their OS, which associates common filename
1014     extensions with the official list of IANA registered media types
1015     maintained at <a href=
1016     "http://www.iana.org/assignments/media-types/index.html"
1017     >http://www.iana.org/assignments/media-types/index.html</a>
1018     as well as a large number of unofficial types.  This
1019     simplifies the <code>httpd.conf</code> file by providing the
1020     majority of media-type definitions, and may be overridden by
1021     <directive module="mod_mime">AddType</directive> directives as
1022     needed. You should not edit the <code>mime.types</code> file,
1023     because it may be replaced when you upgrade your server.</p>
1024
1025     <p>The file contains lines in the format of the arguments to
1026     an <directive module="mod_mime">AddType</directive> directive:</p>
1027
1028     <example>
1029       <var>media-type</var> [<var>extension</var>] ...
1030     </example>
1031
1032     <p>The case of the extension does not matter. Blank lines, and lines
1033     beginning with a hash character (<code>#</code>) are ignored.
1034     Empty lines are there for completeness (of the mime.types file).
1035     Apache httpd can still determine these types with <module
1036     >mod_mime_magic</module>.
1037     </p>
1038
1039     <note>
1040       Please do <strong>not</strong> send requests to the Apache HTTP
1041       Server Project to add any new entries in the distributed
1042       <code>mime.types</code> file unless (1) they are already
1043       registered with IANA, and (2) they use widely accepted,
1044       non-conflicting filename extensions across platforms.
1045       <code>category/x-subtype</code> requests will be automatically
1046       rejected, as will any new two-letter extensions as they will
1047       likely conflict later with the already crowded language and
1048       character set namespace.
1049     </note>
1050 </usage>
1051 <seealso><module>mod_mime_magic</module></seealso>
1052 </directivesynopsis>
1053
1054 <directivesynopsis>
1055 <name>MimeOptions</name>
1056 <description>Configures mod_mime behavior</description>
1057 <syntax>MimeOptions <var>option</var> [<var>option</var>] ...</syntax>
1058 <contextlist><context>server config</context>
1059 <context>virtual host</context><context>directory</context>
1060 <context>.htaccess</context>
1061 </contextlist>
1062 <override>FileInfo</override>
1063 <compatibility>Apache HTTP Server 2.5.1 and later</compatibility>
1064
1065 <usage>
1066     <p>The <directive>MimeOptions</directive> directive configures certain
1067     behaviors of <module>mod_mime</module>. <var>Option</var> can
1068     be one of</p>
1069
1070     <dl>
1071       <dt><code>TypesLastExtension</code></dt>
1072       <dd>This option only consider the last (right-most) filename extension
1073       when determining a files Content-Type.</dd>
1074       <dt><code>NoTypesLastExtension</code></dt>
1075       <dd>This option can be used to revert to the default behavior of testing
1076       every filename extension when determining a files Content-Type.</dd>
1077       <dt><code>AllLastExtension</code></dt>
1078       <dd>This option only consider the last (right-most) filename extension
1079       when scanning filenames.</dd>
1080       <dt><code>NoAllLastExtension</code></dt>
1081       <dd>This option can be used to revert to the default behavior of scanning
1082       every filename extension. Only useful if
1083       <code>MimeOptions AllLastExtension</code> has been used in a lower precedence
1084       configuration section</dd>
1085       <dt><code>Disable</code></dt>
1086       <dd>All assignment of metadata based on the filename is skipped.</dd>
1087       <dt><code>Enable</code></dt>
1088       <dd>Re-enables file extension checking by this module. Only useful if a lower
1089       precedence configuration section has specified
1090       <code>MimeOptions Disable</code>.</dd>
1091     </dl>
1092 </usage>
1093 </directivesynopsis>
1094 </modulesynopsis>