mod_negotiation.html revision 049507d9fe38f0e005c97b2cc5ffb0d2636671d8
b355dcb54194f498921743ca33304eac35d89718Stephen Gallagher<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
b355dcb54194f498921743ca33304eac35d89718Stephen Gallagher <meta name="generator" content="HTML Tidy, see www.w3.org" />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <title>Apache module mod_negotiation</title>
b355dcb54194f498921743ca33304eac35d89718Stephen Gallagher <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher <!--#include virtual="header.html" -->
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher <h1 align="CENTER">Module mod_negotiation</h1>
b355dcb54194f498921743ca33304eac35d89718Stephen Gallagher href="/content-negotiation.html">content negotiation</a>.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Status:</strong></a> Base<br />
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher rel="Help"><strong>Source File:</strong></a>
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek rel="Help"><strong>Module Identifier:</strong></a>
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek negotiation_module</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan Content negotiation, or more accurately content selection, is
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan the selection of the document that best matches the clients
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan capabilities, from one of several available documents. There
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher are two implementations of this.
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <li>A type map (a file with the handler
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <code>type-map</code>) which explicitly lists the files
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher containing the variants.</li>
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher <li>A MultiViews search (enabled by the MultiViews <a
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher href="core.html#options">Option</a>, where the server does an
2ea6196484055397cc4bc011c5960f790431fa9dStephen Gallagher implicit filename pattern match, and choose from amongst the
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <li><a href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <li><a href="#forcelanguagepriority">ForceLanguagePriority</a></li>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <li><a href="#languagepriority">LanguagePriority</a></li>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan href="/mod_mime.html#defaultlanguage">DefaultLanguage</a>, <a
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher href="/mod_mime.html#addencoding">AddEncoding</a>, <a
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher href="/mod_mime.html#addlanguage">AddLanguage</a>, <a
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher href="/mod_mime.html#addtype">AddType</a>, and <a
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher A type map has the same format as RFC822 mail headers. It
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan contains document descriptions separated by blank lines, with
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher lines beginning with a hash character ('#') treated as
52261fe16203dec6e6f69177c6d0a810b47d073fStephen Gallagher comments. A document description consists of several header
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher records; records may be continued on multiple lines if the
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek continuation lines start with spaces. The leading space will be
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher deleted and the lines concatenated. A header record consists of
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher a keyword name, which always ends in a colon, followed by a
2ea6196484055397cc4bc011c5960f790431fa9dStephen Gallagher value. Whitespace is allowed between the header name and value,
2ea6196484055397cc4bc011c5960f790431fa9dStephen Gallagher and between the tokens of value. The headers allowed are:
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <dd>The encoding of the file. Apache only recognizes
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan encodings that are defined by an <a
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan href="mod_mime.html#addencoding">AddEncoding</a> directive.
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan This normally includes the encodings <code>x-compress</code>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan for compress'd files, and <code>x-gzip</code> for gzip'd
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan files. The <code>x-</code> prefix is ignored for encoding
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan comparisons.</dd>
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher <dd>The language of the variant, as an Internet standard
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher language tag (RFC 1766). An example is <code>en</code>,
2ea6196484055397cc4bc011c5960f790431fa9dStephen Gallagher meaning English.</dd>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <dd>The length of the file, in bytes. If this header is not
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher present, then the actual length of the file is used.</dd>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan The MIME media type of the document, with optional
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher parameters. Parameters are separated from the media type
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher and from one another by a semi-colon, with a syntax of
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <code>name=value</code>. Common parameters include:
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher <dd>an integer specifying the version of the media type.
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher For <code>text/html</code> this defaults to 2, otherwise
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <dd>a floating-point number with a value in the range 0.0
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher to 1.0, indicating the relative 'quality' of this variant
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan compared to the other available variants, independent of
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan the client's capabilities. For example, a jpeg file is
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher usually of higher source quality than an ascii file if it
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher is attempting to represent a photograph. However, if the
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan resource being represented is ascii art, then an ascii
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher file would have a higher source quality than a jpeg file.
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher All qs values are therefore specific to a given
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan resource.</dd>
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher <code>Content-Type: image/jpeg; qs=0.8</code>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan </blockquote>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <dd>The path to the file containing this variant, relative to
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan the map file.</dd>
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher A MultiViews search is enabled by the MultiViews <a
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek href="core.html#options">Option</a>. If the server receives a
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <code>/some/dir/foo</code> does <em>not</em> exist, then the
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan server reads the directory looking for all files named
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher <code>foo.*</code>, and effectively fakes up a type map which
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher names all those files, assigning them the same media types and
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek content-encodings it would have if the client had asked for one
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan of them by name. It then chooses the best match to the client's
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan requirements, and returns that document.
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek name="cachenegotiateddocs">CacheNegotiatedDocs</a>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan directive</h2>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Syntax:</strong></a> CacheNegotiatedDocs
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher rel="Help"><strong>Context:</strong></a> server config<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Status:</strong></a> Base<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Module:</strong></a> mod_negotiation<br />
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher <a href="directive-dict.html#Compatibility"
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher rel="Help"><strong>Compatibility:</strong></a>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan CacheNegotiatedDocs is only available in Apache 1.1 and later.
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan The syntax changed in version 2.0.
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher <p>If set, this directive allows content-negotiated documents
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher to be cached by proxy servers. This could mean that clients
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan behind those proxys could retrieve versions of the documents
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan that are not the best match for their abilities, but it will
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher make caching more efficient.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <p>This directive only applies to requests which come from
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan HTTP/1.0 browsers. HTTP/1.1 provides much better control over
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan the caching of negotiated documents, and this directive has no
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher effect in responses to HTTP/1.1 requests.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <p>Prior to version 2.0, CacheNegotiatedDocs did not take an
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan argument; it was turned on by the presence of the directive by
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan name="forcelanguagepriority">ForceLanguagePriority</a> directive</h2>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Syntax:</strong></a> ForceLanguagePriority
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan None|Prefer|Fallback [Prefer|Fallback]<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <code>ForceLanguagePriority None</code><br />
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan rel="Help"><strong>Context:</strong></a> server config, virtual
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan host, directory, .htaccess<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Override:</strong></a> FileInfo<br />
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher rel="Help"><strong>Status:</strong></a> Base<br />
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher rel="Help"><strong>Module:</strong></a> mod_negotiation<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Compatibility:</strong></a>
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher Available in version 2.0.30 and later.</p>
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher <p>The <code>ForceLanguagePriority</code> directive uses the given
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher <a href="#languagepriority">LanguagePriority</a> to satisfy
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan negotation where the server could otherwise not return a single
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher matching document.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <p><code>ForceLanguagePriority Prefer</code> uses
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <code>LanguagePriority</code> to serve a one valid result, rather
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan than returning an HTTP result 300 (MULTIPLE CHOICES) when there
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan are several equally valid choices. If the directives below were
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher given, and the user's Accept-Language header assigned en and de
c938f4ba417328fe62eded0806b2d9ca053f34a5Stephen Gallagher each as quality .500 (equally acceptable) then then first matching
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan variant, en, will be served.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan LanguagePriority en fr de<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan ForceLanguagePriority Prefer
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan <p><code>ForceLanguagePriority Fallback</code> uses
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan <code>LanguagePriority</code> to serve a valid result, rather than
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan returning an HTTP result 406 (NOT ACCEPTABLE). If the directives
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan below were given, and the user's Accept-Language only permitted an
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher es langauge response, but such a variant isn't found, then the
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher first variant from the LanguagePriority list below will be
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher LanguagePriority en fr de<br />
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher ForceLanguagePriority Fallback
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <p>Both options, Prefer and Fallback, may be specified, so either the
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher first matching variant from LanguagePriority will be served if more
64a424ec1b268427822c646f7781e26e56c197f6Jakub Hrozek that one variant is acceptable, or first available document will be
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan served if none of the variants matched the client's acceptable list of
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan languages.</p>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan name="languagepriority">LanguagePriority</a> directive</h2>
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <!--%plaintext <?INDEX {\tt LanguagePriority} directive> -->
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher rel="Help"><strong>Syntax:</strong></a> LanguagePriority
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <em>MIME-lang</em> [<em>MIME-lang</em>] ...<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Context:</strong></a> server config, virtual
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan host, directory, .htaccess<br />
f9fdc87c80f2744780c6a0f2bf5b1b57bcbb095aYuri Chornoivan rel="Help"><strong>Override:</strong></a> FileInfo<br />
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher rel="Help"><strong>Status:</strong></a> Base<br />
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan rel="Help"><strong>Module:</strong></a> mod_negotiation
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <p>The LanguagePriority sets the precedence of language
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher variants for the case where the client does not express a
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher preference, when handling a MultiViews request. The list of
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan <em>MIME-lang</em> are in order of decreasing preference.
bde69429374859acff41273c0771d2b5f5c199b1Yuri Chornoivan </blockquote>
cbe7c54c2caf718bdea7ca6660ba8193d759d2d5Stephen Gallagher For a request for <code>foo.html</code>, where
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher <code>foo.html.fr</code> and <code>foo.html.de</code> both
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher existed, but the browser did not express a language preference,
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher then <code>foo.html.fr</code> would be returned.
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher <p>Note that this directive only has an effect if a 'best'
dd3ba5c5b7d2a9d109963ae9e6c94fff34872221Stephen Gallagher language cannot be determined by any other means or the <a
056302a92862fda16351d7192600746746f38e5dStephen Gallagher href="#forcelanguagepriority">ForceLanguagePriority</a> directive
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher is not <code>None</code>. Correctly implemented HTTP/1.1 requests
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher will mean this directive has no effect.</p>
056302a92862fda16351d7192600746746f38e5dStephen Gallagher href="/mod_mime.html#defaultlanguage">DefaultLanguage</a>,
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher <a href="/mod_mime.html#addlanguage">AddLanguage</a> and
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher <a href="#forcelanguagepriority">ForceLanguagePriority</a>.
e59e09b5010f262228bbdeb92a79b733bf5854b3Stephen Gallagher <!--#include virtual="footer.html" -->