Description: | Associates the requested filename's extensions with the file's behavior (handlers and filters) and content (mime-type, language, character set and encoding) |
---|---|
Status: | Base |
Module Identifier: | mime_module |
Source File: | mod_mime.c |
This module is used to assign content metadata to the content selected for an HTTP response by mapping patterns in the URI or filenames to the metadata values. For example, the filename extensions of content files often define the content's Internet media type, language, character set, and content-encoding. This information is sent in HTTP messages containing that content and used in content negotiation when selecting alternatives, such that the user's preferences are respected when choosing one of several possible contents to serve. Seemod_negotiation
for more information aboutcontent negotiation.
The directivesAddCharset
,AddEncoding
,AddLanguage
andAddType
are all used to map file extensions onto the metadata for that file. Respectively they set the character set, content-encoding, content-language, andmedia-type (content-type) of documents. The directiveTypesConfig
is used to specify a file which also maps extensions onto media types.
In addition,mod_mime
may define thehandler andfilters that originate and process content. The directivesAddHandler
,AddOutputFilter
, andAddInputFilter
control the modules or scripts that serve the document. TheMultiviewsMatch
directive allowsmod_negotiation
to consider these file extensions to be included when testing Multiviews matches.
Whilemod_mime
associates metadata with filename extensions, thecore
server provides directives that are used to associate all the files in a given container (e.g.,<Location>
,<Directory>
, or<Files>
) with particular metadata. These directives includeForceType
,SetHandler
,SetInputFilter
, andSetOutputFilter
. The core directives override any filename extension mappings defined inmod_mime
.
Note that changing the metadata for a file does not change the value of theLast-Modified
header. Thus, previously cached copies may still be used by a client or proxy, with the previous headers. If you change the metadata (language, content type, character set or encoding) you may need to 'touch' affected files (updating their last modified date) to ensure that all visitors are receive the corrected content headers.
Files can have more than one extension; the order of the extensions isnormally irrelevant. For example, if the filewelcome.html.fr
maps onto content typetext/html
and language French then the filewelcome.fr.html
will map onto exactly the same information. If more than one extension is given that maps onto the same type of metadata, then the one to the right will be used, except for languages and content encodings. For example, if.gif
maps to themedia-typeimage/gif
and.html
maps to the media-typetext/html
, then the filewelcome.gif.html
will be associated with the media-typetext/html
.
Languages andcontent encodings are treated accumulative, because one can assign more than one language or encoding to a particular resource. For example, the filewelcome.html.en.de
will be delivered withContent-Language: en, de
andContent-Type: text/html
.
Care should be taken when a file with multiple extensions gets associated with both amedia-type and a handler. This will usually result in the request being handled by the module associated with the handler. For example, if the.imap
extension is mapped to the handlerimap-file
(frommod_imagemap
) and the.html
extension is mapped to the media-typetext/html
, then the fileworld.imap.html
will be associated with both theimap-file
handler andtext/html
media-type. When it is processed, theimap-file
handler will be used, and so it will be treated as amod_imagemap
imagemap file.
If you would prefer only the last dot-separated part of the filename to be mapped to a particular piece of meta-data, then do not use theAdd*
directives. For example, if you wish to have the filefoo.html.cgi
processed as a CGI script, but not the filebar.cgi.html
, then instead of usingAddHandler cgi-script .cgi
, use
<FilesMatch "[^.]+\.cgi$"> SetHandler cgi-script</FilesMatch>
A file of a particularmedia-type can additionally be encoded a particular way to simplify transmission over the Internet. While this usually will refer to compression, such asgzip
, it can also refer to encryption, such apgp
or to an encoding such as UUencoding, which is designed for transmitting a binary file in an ASCII (text) format.
TheHTTP/1.1 RFC, section 14.11 puts it this way:
The Content-Encoding entity-header field is used as a modifier to the media-type. When present, its value indicates what additional content codings have been applied to the entity-body, and thus what decoding mechanisms must be applied in order to obtain the media-type referenced by the Content-Type header field. Content-Encoding is primarily used to allow a document to be compressed without losing the identity of its underlying media type.
By using more than one file extension (seesection above about multiple file extensions), you can indicate that a file is of a particulartype, and also has a particularencoding.
For example, you may have a file which is a Microsoft Word document, which is pkzipped to reduce its size. If the.doc
extension is associated with the Microsoft Word file type, and the.zip
extension is associated with the pkzip file encoding, then the fileResume.doc.zip
would be known to be a pkzip'ed Word document.
Apache sends aContent-encoding
header with the resource, in order to tell the client browser about the encoding method.
Content-encoding: pkzip
In addition to file type and the file encoding, another important piece of information is what language a particular document is in, and in what character set the file should be displayed. For example, the document might be written in the Vietnamese alphabet, or in Cyrillic, and should be displayed as such. This information, also, is transmitted in HTTP headers.
The character set, language, encoding and mime type are all used in the process of content negotiation (Seemod_negotiation
) to determine which document to give to the client, when there are alternative documents in more than one character set, language, encoding or mime type. All filename extensions associations created withAddCharset
,AddEncoding
,AddLanguage
andAddType
directives (and extensions listed in theMimeMagicFile
) participate in this select process. Filename extensions that are only associated using theAddHandler
,AddInputFilter
orAddOutputFilter
directives may be included or excluded from matching by using theMultiviewsMatch
directive.
To convey this further information, Apache optionally sends aContent-Language
header, to specify the language that the document is in, and can append additional information onto theContent-Type
header to indicate the particular character set that should be used to correctly render the information.
Content-Language: en, frContent-Type: text/plain; charset=ISO-8859-1
The language specification is the two-letter abbreviation for the language. Thecharset
is the name of the particular character set which should be used.
Description: | Maps the given filename extensions to the specified contentcharset |
---|---|
Syntax: | AddCharsetcharsetextension[extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheAddCharset
directive maps the given filename extensions to the specified content charset (the Internet registered name for a given character encoding).charset is themedia type's charset parameter for resources with filenames containingextension. This mapping is added to any already in force, overriding any mappings that already exist for the sameextension.
AddLanguage ja .jaAddCharset EUC-JP .eucAddCharset ISO-2022-JP .jisAddCharset SHIFT_JIS .sjis
Then the documentxxxx.ja.jis
will be treated as being a Japanese document whose charset isISO-2022-JP
(as will the documentxxxx.jis.ja
). TheAddCharset
directive is useful for both to inform the client about the character encoding of the document so that the document can be interpreted and displayed appropriately, and forcontent negotiation, where the server returns one from several documents based on the client's charset preference.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Description: | Maps the given filename extensions to the specified encodingtype |
---|---|
Syntax: | AddEncodingencodingextension[extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheAddEncoding
directive maps the given filename extensions to the specified HTTP content-encoding.encoding is the HTTP content coding to append to the value of the Content-Encoding header field for documents named with theextension. This mapping is added to any already in force, overriding any mappings that already exist for the sameextension.
AddEncoding x-gzip .gzAddEncoding x-compress .Z
This will cause filenames containing the.gz
extension to be marked as encoded using thex-gzip
encoding, and filenames containing the.Z
extension to be marked as encoded withx-compress
.
Old clients expectx-gzip
andx-compress
, however the standard dictates that they're equivalent togzip
andcompress
respectively. Apache does content encoding comparisons by ignoring any leadingx-
. When responding with an encoding Apache will use whatever form (i.e.,x-foo
orfoo
) the client requested. If the client didn't specifically request a particular form Apache will use the form given by theAddEncoding
directive. To make this long story short, you should always usex-gzip
andx-compress
for these two specific encodings. More recent encodings, such asdeflate
, should be specified without thex-
.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Description: | Maps the filename extensions to the specifiedhandler |
---|---|
Syntax: | AddHandlerhandler-nameextension[extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
Files having the nameextension will be served by the specifiedhandler-name. This mapping is added to any already in force, overriding any mappings that already exist for the sameextension. For example, to activate CGI scripts with the file extension.cgi
, you might use:
AddHandler cgi-script .cgi
Once that has been put into your httpd.conf file, any file containing the.cgi
extension will be treated as a CGI program.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Description: | Maps filename extensions to the filters that will processclient requests |
---|---|
Syntax: | AddInputFilterfilter[;filter...]extension [extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
AddInputFilter
maps the filename extensionextension to thefilters which will process client requests and POST input when they are received by the server. This is in addition to any filters defined elsewhere, including theSetInputFilter
directive. This mapping is merged over any already in force, overriding any mappings that already exist for the sameextension.
If more than onefilter is specified, they must be separated by semicolons in the order in which they should process the content. Thefilter is case-insensitive.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Description: | Maps the given filename extension to the specified contentlanguage |
---|---|
Syntax: | AddLanguagelanguage-tagextension[extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheAddLanguage
directive maps the given filename extension to the specified content language. Files with the filenameextension are assigned an HTTP Content-Language value oflanguage-tag corresponding to the language identifiers defined by RFC 3066. This directive overrides any mappings that already exist for the sameextension.
AddEncoding x-compress .ZAddLanguage en .enAddLanguage fr .fr
Then the documentxxxx.en.Z
will be treated as being a compressed English document (as will the documentxxxx.Z.en
). Although the content language is reported to the client, the browser is unlikely to use this information. TheAddLanguage
directive is more useful forcontent negotiation, where the server returns one from several documents based on the client's language preference.
If multiple language assignments are made for the same extension, the last one encountered is the one that is used. That is, for the case of:
AddLanguage en .enAddLanguage en-gb .enAddLanguage en-us .en
documents with the extension.en
would be treated as beingen-us
.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Description: | Maps filename extensions to the filters that will processresponses from the server |
---|---|
Syntax: | AddOutputFilterfilter[;filter...]extension [extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheAddOutputFilter
directive maps the filename extensionextension to thefilters which will process responses from the server before they are sent to the client. This is in addition to any filters defined elsewhere, includingSetOutputFilter
andAddOutputFilterByType
directive. This mapping is merged over any already in force, overriding any mappings that already exist for the sameextension.
For example, the following configuration will process all.shtml
files for server-side includes and will then compress the output usingmod_deflate
.
AddOutputFilter INCLUDES;DEFLATE shtml
If more than one filter is specified, they must be separated by semicolons in the order in which they should process the content. Thefilter argument is case-insensitive.
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
Note that when defining a set of filters using theAddOutputFilter
directive, any definition made will replace any previous definition made by theAddOutputFilter
directive.
# Effective filter "DEFLATE"AddOutputFilter DEFLATE shtml<Location "/foo"> # Effective filter "INCLUDES", replacing "DEFLATE" AddOutputFilter INCLUDES shtml</Location><Location "/bar"> # Effective filter "INCLUDES;DEFLATE", replacing "DEFLATE" AddOutputFilter INCLUDES;DEFLATE shtml</Location><Location "/bar/baz"> # Effective filter "BUFFER", replacing "INCLUDES;DEFLATE" AddOutputFilter BUFFER shtml</Location><Location "/bar/baz/buz"> # No effective filter, replacing "BUFFER" RemoveOutputFilter shtml</Location>
Description: | Maps the given filename extensions onto the specified contenttype |
---|---|
Syntax: | AddTypemedia-typeextension[extension] ... |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheAddType
directive maps the given filename extensions onto the specified content type.media-type is themedia type to use for filenames containingextension. This mapping is added to any already in force, overriding any mappings that already exist for the sameextension.
AddType
directive rather than changing theTypesConfig
file.AddType image/gif .gif
Or, to specify multiple file extensions in one directive:
AddType image/jpeg jpeg jpg jpe
Theextension argument is case-insensitive and can be specified with or without a leading dot. Filenames may havemultiple extensions and theextension argument will be compared against each of them.
A similar effect tomod_negotiation
'sLanguagePriority
can be achieved by qualifying amedia-type withqs
:
AddType application/rss+xml;qs=0.8 .xml
This is useful in situations,e.g. when a client requestingAccept: */*
can not actually processes the content returned by the server.
This directive primarily configures the content types generated for static files served out of the filesystem. For resources other than static files, where the generator of the response typically specifies a Content-Type, this directive has no effect.
If no handler is explicitly set for a request, the specified content type will also be used as the handler name.
When explicit directives such asSetHandler
orAddHandler
do not apply to the current request, the internal handler name normally set by those directives is instead set to the content type specified by this directive.
This is a historical behavior that may be used by some third-party modules (such as mod_php) for taking responsibility for the matching request.
Configurations that rely on such "synthetic" types should be avoided. Additionally, configurations that restrict access toSetHandler
orAddHandler
should restrict access to this directive as well.
Description: | Defines a default language-tag to be sent in the Content-Languageheader field for all resources in the current context that have not beenassigned a language-tag by some other means. |
---|---|
Syntax: | DefaultLanguagelanguage-tag |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheDefaultLanguage
directive tells Apache that all resources in the directive's scope (e.g., all resources covered by the current<Directory>
container) that don't have an explicit language extension (such as.fr
or.de
as configured byAddLanguage
) should be assigned a Content-Language oflanguage-tag. This allows entire directory trees to be marked as containing Dutch content, for instance, without having to rename each file. Note that unlike using extensions to specify languages,DefaultLanguage
can only specify a single language.
If noDefaultLanguage
directive is in force and a file does not have any language extensions as configured byAddLanguage
, then no Content-Language header field will be generated.
DefaultLanguage en
Description: | Tellsmod_mime to treatpath_info components as part of the filename |
---|---|
Syntax: | ModMimeUsePathInfo On|Off |
Default: | ModMimeUsePathInfo Off |
Context: | directory |
Status: | Base |
Module: | mod_mime |
TheModMimeUsePathInfo
directive is used to combine the filename with thepath_info
URL component to applymod_mime
's directives to the request. The default value isOff
- therefore, thepath_info
component is ignored.
This directive is recommended when you have a virtual filesystem.
ModMimeUsePathInfo On
If you have a request for/index.php/foo.shtml
mod_mime
will now treat the incoming request as/index.php/foo.shtml
and directives likeAddOutputFilter INCLUDES .shtml
will add theINCLUDES
filter to the request. IfModMimeUsePathInfo
is not set, theINCLUDES
filter will not be added. This will work analogously for virtual paths, such as those defined by<Location>
Description: | The types of files that will be included when searching fora matching file with MultiViews |
---|---|
Syntax: | MultiviewsMatch Any|NegotiatedOnly|Filters|Handlers[Handlers|Filters] |
Default: | MultiviewsMatch NegotiatedOnly |
Context: | server config, virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
MultiviewsMatch
permits three different behaviors formod_negotiation's Multiviews feature. Multiviews allows a request for a file,e.g.index.html
, to match any negotiated extensions following the base request,e.g.index.html.en
,index.html.fr
, orindex.html.gz
.
TheNegotiatedOnly
option provides that every extension following the base name must correlate to a recognizedmod_mime
extension for content negotiation,e.g. Charset, Content-Type, Language, or Encoding. This is the strictest implementation with the fewest unexpected side effects, and is the default behavior.
To include extensions associated with Handlers and/or Filters, set theMultiviewsMatch
directive to eitherHandlers
,Filters
, or both option keywords. If all other factors are equal, the smallest file will be served,e.g. in deciding betweenindex.html.cgi
of 500 bytes andindex.html.pl
of 1000 bytes, the.cgi
file would win in this example. Users of.asis
files might prefer to use the Handler option, if.asis
files are associated with theasis-handler
.
You may finally allowAny
extensions to match, even ifmod_mime
doesn't recognize the extension. This can cause unpredictable results, such as serving .old or .bak files the webmaster never expected to be served.
For example, the following configuration will allow handlers and filters to participate in Multviews, but will exclude unknown files:
MultiviewsMatch Handlers Filters
MultiviewsMatch
is not allowed in a<Location>
or<LocationMatch>
section.
Description: | Removes any character set associations for a set of fileextensions |
---|---|
Syntax: | RemoveCharsetextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveCharset
directive removes any character set associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
RemoveCharset .html .shtml
Description: | Removes any content encoding associations for a set of fileextensions |
---|---|
Syntax: | RemoveEncodingextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveEncoding
directive removes any encoding associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:
AddEncoding x-gzip .gzAddType text/plain .asc<Files "*.gz.asc"> RemoveEncoding .gz</Files>
This will causefoo.gz
to be marked as being encoded with the gzip method, butfoo.gz.asc
as an unencoded plaintext file.
RemoveEncoding
directives are processedafter anyAddEncoding
directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
Description: | Removes any handler associations for a set of fileextensions |
---|---|
Syntax: | RemoveHandlerextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveHandler
directive removes any handler associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:
AddHandler server-parsed .html
RemoveHandler .html
This has the effect of returning.html
files in the/foo/bar
directory to being treated as normal files, rather than as candidates for parsing (see themod_include
module).
Theextension argument is case-insensitive and can be specified with or without a leading dot.
Description: | Removes any input filter associations for a set of fileextensions |
---|---|
Syntax: | RemoveInputFilterextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveInputFilter
directive removes any inputfilter associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
Description: | Removes any language associations for a set of fileextensions |
---|---|
Syntax: | RemoveLanguageextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveLanguage
directive removes any language associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
Description: | Removes any output filter associations for a set of fileextensions |
---|---|
Syntax: | RemoveOutputFilterextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveOutputFilter
directive removes any outputfilter associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
RemoveOutputFilter shtml
Description: | Removes any content type associations for a set of fileextensions |
---|---|
Syntax: | RemoveTypeextension [extension]... |
Context: | virtual host, directory, .htaccess |
Override: | FileInfo |
Status: | Base |
Module: | mod_mime |
TheRemoveType
directive removes anymedia type associations for files with the given extensions. This allows.htaccess
files in subdirectories to undo any associations inherited from parent directories or the server config files. An example of its use might be:
RemoveType .cgi
This will remove any special handling of.cgi
files in the/foo/
directory and any beneath it, causing responses containing those files to omit the HTTP Content-Type header field.
RemoveType
directives are processedafter anyAddType
directives, so it is possible they may undo the effects of the latter if both occur within the same directory configuration.
Theextension argument is case-insensitive and can be specified with or without a leading dot.
Description: | The location of themime.types file |
---|---|
Syntax: | TypesConfigfile-path |
Default: | TypesConfig conf/mime.types |
Context: | server config |
Status: | Base |
Module: | mod_mime |
TheTypesConfig
directive sets the location of themedia types configuration file.File-path is relative to theServerRoot
. This file sets the default list of mappings from filename extensions to content types. Most administrators use themime.types
file provided by their OS, which associates common filename extensions with the official list of IANA registered media types maintained athttp://www.iana.org/assignments/media-types/index.html as well as a large number of unofficial types. This simplifies thehttpd.conf
file by providing the majority of media-type definitions, and may be overridden byAddType
directives as needed. You should not edit themime.types
file, because it may be replaced when you upgrade your server.
The file contains lines in the format of the arguments to anAddType
directive:
media-type [extension] ...
The case of the extension does not matter. Blank lines, and lines beginning with a hash character (#
) are ignored. Empty lines are there for completeness (of the mime.types file). Apache httpd can still determine these types withmod_mime_magic
.
mime.types
file unless (1) they are already registered with IANA, and (2) they use widely accepted, non-conflicting filename extensions across platforms.category/x-subtype
requests will be automatically rejected, as will any new two-letter extensions as they will likely conflict later with the already crowded language and character set namespace.Copyright 2025 The Apache Software Foundation.
Licensed under theApache License, Version 2.0.