1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
4 <TITLE>Apache module mod_mime</TITLE>
7 <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
15 <!--#include virtual="header.html" -->
16 <H1 ALIGN="CENTER">Module mod_mime</H1>
18 <p>This module provides for determining the types of files
19 from the filename and for association of handlers with files.</p>
22 HREF="module-dict.html#Status"
24 ><STRONG>Status:</STRONG></A> Base
27 HREF="module-dict.html#SourceFile"
29 ><STRONG>Source File:</STRONG></A> mod_mime.c
32 HREF="module-dict.html#ModuleIdentifier"
34 ><STRONG>Module Identifier:</STRONG></A> mime_module
39 This module is used to determine various bits of "meta information"
40 about documents. This information relates to the content of the
41 document and is returned to the browser or used in content-negotiation
42 within the server. In addition, a "handler" can be set for a document,
43 which determines how the document will be processed within the server.
47 The directives <a href="#addcharset">AddCharset</a>, <A
48 HREF="#addencoding">AddEncoding</A>, <A
49 HREF="#addhandler">AddHandler</A>, <A
50 HREF="#addlanguage">AddLanguage</A> and <A HREF="#addtype">AddType</A>
51 are all used to map file extensions onto the meta-information for that
52 file. Respectively they set the character set, content-encoding,
53 handler, content-language, and MIME-type (content-type) of documents.
54 The directive <A HREF="#typesconfig">TypesConfig</A> is used to
55 specify a file which also maps extensions onto MIME types. The
56 directives <A HREF="#forcetype">ForceType</A> and <A
57 HREF="#sethandler">SetHandler</A> are used to associated all the files
58 in a given location (<EM>e.g.</EM>, a particular directory) onto a
59 particular MIME type or handler.
63 Note that changing the type or encoding of a file does not change the
64 value of the <CODE>Last-Modified</CODE> header. Thus, previously cached
65 copies may still be used by a client or proxy, with the previous headers.
69 <li><a href="#addcharset">AddCharset</a></li>
70 <LI><A HREF="#addencoding">AddEncoding</A>
71 <LI><A HREF="#addhandler">AddHandler</A>
72 <LI><A HREF="#addlanguage">AddLanguage</A>
73 <LI><A HREF="#addtype">AddType</A>
74 <LI><A HREF="#defaultlanguage">DefaultLanguage</A>
75 <LI><A HREF="#forcetype">ForceType</A>
76 <LI><A HREF="#removehandler">RemoveHandler</A>
77 <LI><A HREF="#sethandler">SetHandler</A>
78 <LI><A HREF="#typesconfig">TypesConfig</A>
82 href="mod_mime_magic.html#mimemagicfile">MimeMagicFile</a>.</p>
84 <H2><A NAME="multipleext">Files with Multiple Extensions</A></H2>
86 Files can have more than one extension, and the order of the
87 extensions is <EM>normally</EM> irrelevant. For example, if the file
88 <CODE>welcome.html.fr</CODE> maps onto content type text/html and
89 language French then the file <CODE>welcome.fr.html</CODE> will map
90 onto exactly the same information. The only exception to this is if an
91 extension is given which Apache does not know how to handle. In this
92 case it will "forget" about any information it obtained from
93 extensions to the left of the unknown extension. So, for example, if
94 the extensions fr and html are mapped to the appropriate language and
95 type but extension xxx is not assigned to anything, then the file
96 <CODE>welcome.fr.xxx.html</CODE> will be associated with content-type
97 text/html but <EM>no</EM> language.
101 If more than one extension is given which maps onto the same type of
102 meta-information, then the one to the right will be used. For example,
103 if ".gif" maps to the MIME-type image/gif and ".html" maps to the
104 MIME-type text/html, then the file <CODE>welcome.gif.html</CODE> will
105 be associated with the MIME-type "text/html".
109 Care should be taken when a file with multiple extensions gets
110 associated with both a MIME-type and a handler. This will usually
111 result in the request being by the module associated with the
112 handler. For example, if the <CODE>.imap</CODE> extension is mapped to
113 the handler "imap-file" (from mod_imap) and the <CODE>.html</CODE>
114 extension is mapped to the MIME-type "text/html", then the file
115 <CODE>world.imap.html</CODE> will be associated with both the
116 "imap-file" handler and "text/html" MIME-type. When it is processed,
117 the "imap-file" handler will be used, and so it will be treated as a
118 mod_imap imagemap file.
122 <H2><A NAME="addcharset">AddCharset</A> directive</H2>
123 <A HREF="directive-dict.html#Syntax" REL="Help"
124 ><STRONG>Syntax:</STRONG></A> AddCharset <em>charset extension</em>
125 [<em>extension</em>] ...<br>
126 <A HREF="directive-dict.html#Context" REL="Help"
127 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
129 HREF="directive-dict.html#Override"
131 ><STRONG>Override:</STRONG></A> FileInfo<BR>
133 HREF="directive-dict.html#Status"
135 ><STRONG>Status:</STRONG></A> Base<BR>
137 HREF="directive-dict.html#Module"
139 ><STRONG>Module:</STRONG></A> mod_mime
142 The AddCharset directive maps the given filename extensions to the
143 specified content charset. <i>charset</i> is the MIME charset
144 parameter of filenames containing <i>extension</i>. This mapping is
145 added to any already in force, overriding any mappings that already
146 exist for the same <i>extension</i>.
152 AddCharset EUC-JP .euc
153 AddCharset ISO-2022-JP .jis
154 AddCharset SHIFT_JIS .sjis
158 Then the document <CODE>xxxx.ja.jis</CODE> will be treated as being a
159 Japanese document whose charset is ISO-2022-JP (as will the document
160 <CODE>xxxx.jis.ja</CODE>). The AddCharset directive is useful for both
161 to inform the client about the character encoding of the document so
162 that the document can be interpreted and displayed appropriately, and
163 for <A HREF="../content-negotiation.html">content negotiation</A>, where
164 the server returns one from several documents based on the client's
168 <p>The <em>extension</em> argument is case-insensitive, and can
169 be specified with or without a leading dot.</p>
172 <STRONG>See also</STRONG>: <A HREF="mod_negotiation.html">mod_negotiation</A>
177 <H2><A NAME="addencoding">AddEncoding</A> directive</H2>
178 <!--%plaintext <?INDEX {\tt AddEncoding} directive> -->
180 HREF="directive-dict.html#Syntax"
182 ><STRONG>Syntax:</STRONG></A> AddEncoding <EM>MIME-enc extension</em>
183 [<em>extension</EM>] ...<BR>
185 HREF="directive-dict.html#Context"
187 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
189 HREF="directive-dict.html#Override"
191 ><STRONG>Override:</STRONG></A> FileInfo<BR>
193 HREF="directive-dict.html#Status"
195 ><STRONG>Status:</STRONG></A> Base<BR>
197 HREF="directive-dict.html#Module"
199 ><STRONG>Module:</STRONG></A> mod_mime<P>
201 The AddEncoding directive maps the given filename extensions to the
202 specified encoding type. <EM>MIME-enc</EM> is the MIME encoding to use
203 for documents containing the <EM>extension</EM>. This mapping is added
204 to any already in force, overriding any mappings that already exist
205 for the same <EM>extension</EM>.
209 AddEncoding x-gzip .gz<BR>
210 AddEncoding x-compress .Z
213 This will cause filenames containing the .gz extension to be marked as
214 encoded using the x-gzip encoding, and filenames containing the .Z
215 extension to be marked as encoded with x-compress.<P>
217 Old clients expect <CODE>x-gzip</CODE> and <CODE>x-compress</CODE>,
218 however the standard dictates that they're equivalent to <CODE>gzip</CODE>
219 and <CODE>compress</CODE> respectively. Apache does content encoding
220 comparisons by ignoring any leading <CODE>x-</CODE>. When responding
221 with an encoding Apache will use whatever form (<EM>i.e.</EM>, <CODE>x-foo</CODE>
222 or <CODE>foo</CODE>) the client requested. If the client didn't
223 specifically request a particular form Apache will use the form given by
224 the <CODE>AddEncoding</CODE> directive. To make this long story short,
225 you should always use <CODE>x-gzip</CODE> and <CODE>x-compress</CODE>
226 for these two specific encodings. More recent encodings, such as
227 <CODE>deflate</CODE> should be specified without the <CODE>x-</CODE>.
229 <p>The <em>extension</em> argument is case-insensitive, and can
230 be specified with or without a leading dot.</p>
234 <STRONG>See also</STRONG>: <A HREF="#multipleext">Files with
235 multiple extensions</A>
239 <H2><A NAME="addhandler">AddHandler</A> directive</H2>
242 HREF="directive-dict.html#Syntax"
244 ><STRONG>Syntax:</STRONG></A> AddHandler <EM>handler-name extension</em>
245 [<em>extension</EM>] ...<BR>
247 HREF="directive-dict.html#Context"
249 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
251 HREF="directive-dict.html#Override"
253 ><STRONG>Override:</STRONG></A> FileInfo<BR>
255 HREF="directive-dict.html#Status"
257 ><STRONG>Status:</STRONG></A> Base<BR>
259 HREF="directive-dict.html#Module"
261 ><STRONG>Module:</STRONG></A> mod_mime
263 <P>AddHandler maps the filename extensions <EM>extension</EM> to the
264 <A HREF="../handler.html">handler</A> <EM>handler-name</EM>. This
265 mapping is added to any already in force, overriding any mappings that
266 already exist for the same <EM>extension</EM>.
268 For example, to activate CGI scripts
269 with the file extension "<CODE>.cgi</CODE>", you might use:
271 AddHandler cgi-script .cgi
274 <P>Once that has been put into your srm.conf or httpd.conf file, any
275 file containing the "<CODE>.cgi</CODE>" extension will be treated as a
278 <p>The <em>extension</em> argument is case-insensitive, and can
279 be specified with or without a leading dot.</p>
283 <STRONG>See also</STRONG>: <A HREF="#multipleext">Files with
284 multiple extensions</A>
288 <H2><A NAME="addlanguage">AddLanguage</A> directive</H2>
289 <!--%plaintext <?INDEX {\tt AddLanguage} directive> -->
291 HREF="directive-dict.html#Syntax"
293 ><STRONG>Syntax:</STRONG></A> AddLanguage <EM>MIME-lang extension</em>
294 [<em>extension</EM>] ...<BR>
296 HREF="directive-dict.html#Context"
298 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
300 HREF="directive-dict.html#Override"
302 ><STRONG>Override:</STRONG></A> FileInfo<BR>
304 HREF="directive-dict.html#Status"
306 ><STRONG>Status:</STRONG></A> Base<BR>
308 HREF="directive-dict.html#Module"
310 ><STRONG>Module:</STRONG></A> mod_mime
313 The AddLanguage directive maps the given filename extensions to the
314 specified content language. <EM>MIME-lang</EM> is the MIME language of
315 filenames containing <EM>extension</EM>. This mapping is added to any
316 already in force, overriding any mappings that already exist for the
317 same <EM>extension</EM>.
320 Example: <BLOCKQUOTE><CODE>
321 AddEncoding x-compress .Z<BR> AddLanguage en .en<BR> AddLanguage fr
322 .fr<BR> </CODE></BLOCKQUOTE>
325 Then the document <CODE>xxxx.en.Z</CODE> will be treated as being a
326 compressed English document (as will the document
327 <CODE>xxxx.Z.en</CODE>). Although the content language is reported to
328 the client, the browser is unlikely to use this information. The
329 AddLanguage directive is more useful for
330 <A HREF="../content-negotiation.html">content negotiation</A>, where
331 the server returns one from several documents based on the client's
335 If multiple language assignments are made for the same extension,
336 the last one encountered is the one that is used. That is, for the
341 AddLanguage en-uk .en
342 AddLanguage en-us .en
345 documents with the extension "<CODE>.en</CODE>" would be treated as
346 being "<CODE>en-us</CODE>".
349 <p>The <em>extension</em> argument is case-insensitive, and can
350 be specified with or without a leading dot.</p>
353 <STRONG>See also</STRONG>: <A HREF="#multipleext">Files with
354 multiple extensions</A>
356 <STRONG>See also</STRONG>: <A
357 HREF="./mod_negotiation.html">mod_negotiation</A>
362 <H2><A NAME="addtype">AddType</A> directive</H2>
363 <!--%plaintext <?INDEX {\tt AddType} directive> -->
365 HREF="directive-dict.html#Syntax"
367 ><STRONG>Syntax:</STRONG></A> AddType <EM>MIME-type extension</em>
368 [<em>extension</EM>] ...<BR>
370 HREF="directive-dict.html#Context"
372 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
374 HREF="directive-dict.html#Override"
376 ><STRONG>Override:</STRONG></A> FileInfo<BR>
378 HREF="directive-dict.html#Status"
380 ><STRONG>Status:</STRONG></A> Base<BR>
382 HREF="directive-dict.html#Module"
384 ><STRONG>Module:</STRONG></A> mod_mime<P>
386 The AddType directive maps the given filename extensions onto the
387 specified content type. <EM>MIME-enc</EM> is the MIME type to use for
388 filenames containing <EM>extension</EM>. This mapping is added to any
389 already in force, overriding any mappings that already exist for the
390 same <EM>extension</EM>. This directive can be used to add mappings
391 not listed in the MIME types file (see the <CODE><A
392 HREF="#typesconfig">TypesConfig</A></CODE> directive).
396 AddType image/gif .gif
398 It is recommended that new MIME types be added using the AddType directive
399 rather than changing the <A HREF="#typesconfig">TypesConfig</A> file.<P>
400 Note that, unlike the NCSA httpd, this directive cannot be used to set the
401 type of particular files.<P>
403 <p>The <em>extension</em> argument is case-insensitive, and can
404 be specified with or without a leading dot.</p>
408 <STRONG>See also</STRONG>: <A HREF="#multipleext">Files with
409 multiple extensions</A>
413 <H2><A NAME="defaultlanguage">DefaultLanguage</A> directive</H2>
414 <!--%plaintext <?INDEX {\tt DefaultLanguage} directive> -->
416 HREF="directive-dict.html#Syntax"
418 ><STRONG>Syntax:</STRONG></A> DefaultLanguage <EM>MIME-lang</EM><BR>
420 HREF="directive-dict.html#Context"
422 ><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
424 HREF="directive-dict.html#Override"
426 ><STRONG>Override:</STRONG></A> FileInfo<BR>
428 HREF="directive-dict.html#Status"
430 ><STRONG>Status:</STRONG></A> Base<BR>
432 HREF="directive-dict.html#Module"
434 ><STRONG>Module:</STRONG></A> mod_mime
436 The DefaultLanguage directive tells Apache that all files in the
437 directive's scope (<EM>e.g.</EM>, all files covered by the current
438 <CODE><Directory></CODE> container) that don't have an explicit
439 language extension (such as <SAMP>.fr</SAMP> or <SAMP>.de</SAMP> as
440 configured by <SAMP>AddLanguage</SAMP>) should be considered to be in
441 the specified <EM>MIME-lang</EM> language. This allows entire
442 directories to be marked as containing Dutch content, for instance,
443 without having to rename each file. Note that unlike using extensions
444 to specify languages, <SAMP>DefaultLanguage</SAMP> can only specify a
449 If no <SAMP>DefaultLanguage</SAMP> directive is in force, and a file
450 does not have any language extensions as configured by
451 <SAMP>AddLanguage</SAMP>, then that file will be considered to have no
456 <STRONG>See also</STRONG>: <A
457 HREF="./mod_negotiation.html">mod_negotiation</A>
459 <STRONG>See also</STRONG>: <A HREF="#multipleext">Files with
460 multiple extensions</A>
464 <H2><A NAME="forcetype">ForceType</A> directive</H2>
467 HREF="directive-dict.html#Syntax"
469 ><STRONG>Syntax:</STRONG></A> ForceType <EM>media-type</EM><BR>
471 HREF="directive-dict.html#Context"
473 ><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
475 HREF="directive-dict.html#Status"
477 ><STRONG>Status:</STRONG></A> Base<BR>
479 HREF="directive-dict.html#Module"
481 ><STRONG>Module:</STRONG></A> mod_mime
483 <P>When placed into an <CODE>.htaccess</CODE> file or a
484 <CODE><Directory></CODE> or <CODE><Location></CODE> section,
485 this directive forces all matching files to be served
486 as the content type given by <EM>media type</EM>. For example, if you
487 had a directory full of GIF files, but did not want to label them all with
488 ".gif", you might want to use:
492 <P>Note that this will override any filename extensions that might determine
493 the media type.</P><HR>
495 <H2><A NAME="removehandler">RemoveHandler</A> directive</H2>
498 HREF="directive-dict.html#Syntax"
500 ><STRONG>Syntax:</STRONG></A> RemoveHandler <EM>extension</em>
501 [<em>extension</em>] ...<BR>
503 HREF="directive-dict.html#Context"
505 ><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
507 HREF="directive-dict.html#Status"
509 ><STRONG>Status:</STRONG></A> Base<BR>
511 HREF="directive-dict.html#Module"
513 ><STRONG>Module:</STRONG></A> mod_mime
516 The <SAMP>RemoveHandler</SAMP> directive removes any
517 handler associations for files with the given extensions.
518 This allows <CODE>.htaccess</CODE> files in subdirectories to undo
519 any associations inherited from parent directories or the server
520 config files. An example of its use might be:
523 <DT><CODE>/foo/.htaccess:</CODE></DT>
524 <DD><CODE>AddHandler server-parsed .html</CODE></DD>
525 <DT><CODE>/foo/bar/.htaccess:</CODE></DT>
526 <DD><CODE>RemoveHandler .html</CODE></DD>
529 This has the effect of returning <SAMP>.html</SAMP> files in the
530 <SAMP>/foo/bar</SAMP> directory to being treated as normal
531 files, rather than as candidates for parsing (see the
532 <A HREF="mod_include.html"><SAMP>mod_include</SAMP></A> module).
534 <p>The <em>extension</em> argument is case-insensitive, and can
535 be specified with or without a leading dot.</p>
539 <H2><A NAME="sethandler">SetHandler</A> directive</H2>
542 HREF="directive-dict.html#Syntax"
544 ><STRONG>Syntax:</STRONG></A> SetHandler <EM>handler-name</EM><BR>
546 HREF="directive-dict.html#Context"
548 ><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
550 HREF="directive-dict.html#Status"
552 ><STRONG>Status:</STRONG></A> Base<BR>
554 HREF="directive-dict.html#Module"
556 ><STRONG>Module:</STRONG></A> mod_mime
558 <P>When placed into an <CODE>.htaccess</CODE> file or a
559 <CODE><Directory></CODE> or <CODE><Location></CODE> section,
560 this directive forces all matching files to be parsed through the
561 <A HREF="../handler.html">handler</A>
562 given by <EM>handler-name</EM>. For example, if you had a
563 directory you wanted to be parsed entirely as imagemap rule files,
564 regardless of extension, you might put the following into an
565 <CODE>.htaccess</CODE> file in that directory:
570 <P>Another example: if you wanted to have the server display a status
571 report whenever a URL of <CODE>http://servername/status</CODE> was
572 called, you might put the following into access.conf:
574 <Location /status>
575 SetHandler server-status
580 <H2><A NAME="typesconfig">TypesConfig</A> directive</H2>
581 <!--%plaintext <?INDEX {\tt TypesConfig} directive> -->
583 HREF="directive-dict.html#Syntax"
585 ><STRONG>Syntax:</STRONG></A> TypesConfig <EM>filename</EM><BR>
587 HREF="directive-dict.html#Default"
589 ><STRONG>Default:</STRONG></A> <CODE>TypesConfig conf/MIME.types</CODE><BR>
591 HREF="directive-dict.html#Context"
593 ><STRONG>Context:</STRONG></A> server config<BR>
595 HREF="directive-dict.html#Status"
597 ><STRONG>Status:</STRONG></A> Base<BR>
599 HREF="directive-dict.html#Module"
601 ><STRONG>Module:</STRONG></A> mod_mime<P>
603 The TypesConfig directive sets the location of the MIME types configuration
604 file. <EM>Filename</EM> is relative to the
605 <A HREF="core.html#serverroot">ServerRoot</A>. This file sets the default list of
606 mappings from filename extensions to content types; changing this file is not
607 recommended. Use the <A HREF="#addtype">AddType</A> directive instead. The
608 file contains lines in the format of the arguments to an AddType command:
609 <BLOCKQUOTE><EM>MIME-type extension extension ...</EM></BLOCKQUOTE>
610 The extensions are lower-cased. Blank lines, and lines beginning with a hash
611 character (`#') are ignored.<P>
613 <!--#include virtual="footer.html" -->