mod_negotiation.html revision e0b181d3bfa99dfb992df3024b397660cb7afbe9
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
381a2a9a387f449fab7d0c7e97c4184c26963abfdr XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
381a2a9a387f449fab7d0c7e97c4184c26963abfdr This file is generated from xml source: DO NOT EDIT
381a2a9a387f449fab7d0c7e97c4184c26963abfdr XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
381a2a9a387f449fab7d0c7e97c4184c26963abfdr --><title>mod_negotiation- Apache HTTP Server</title><link rel="stylesheet" type="text/css" href="/style/manual.css"/></head><body><blockquote><div align="center"><img src="/images/sub.gif" alt="[APACHE DOCUMENTATION]"/><h3>Apache HTTP Server Version 2.0</h3></div><h1 align="center">Apache Module mod_negotiation</h1><table bgcolor="#cccccc" cellpadding="0" cellspacing="1"><tr><td><table bgcolor="#ffffff"><tr><td valign="top"><span class="help">Description:</span></td><td>Provides for <a href="/content-negotiation.html">content negotiation</a></td></tr><tr><td><a class="help" href="module-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="module-dict.html#ModuleIdentifier">Module Identifier:</a></td><td>negotiation_module</td></tr></table></td></tr></table><h2>Summary</h2>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>Content negotiation, or more accurately content selection, is
381a2a9a387f449fab7d0c7e97c4184c26963abfdr the selection of the document that best matches the clients
381a2a9a387f449fab7d0c7e97c4184c26963abfdr capabilities, from one of several available documents. There
381a2a9a387f449fab7d0c7e97c4184c26963abfdr are two implementations of this.</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <li>A type map (a file with the handler
381a2a9a387f449fab7d0c7e97c4184c26963abfdr containing the variants.</li>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <li>A MultiViews search (enabled by the MultiViews <a class="directive" href="core.html#options"><code class="directive">Options</code></a>, where the server does an
381a2a9a387f449fab7d0c7e97c4184c26963abfdr implicit filename pattern match, and choose from amongst the
381a2a9a387f449fab7d0c7e97c4184c26963abfdr results.</li>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<h2>Directives</h2><ul><li><a href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li><li><a href="#forcelanguagepriority">ForceLanguagePriority</a></li><li><a href="#languagepriority">LanguagePriority</a></li></ul><p><strong>See also </strong></p><ul><li><a class="directive" href="mod_mime.html#defaultlanguage"><code class="directive">DefaultLanguage</code></a></li><li><a class="directive" href="mod_mime.html#addencoding"><code class="directive">AddEncoding</code></a></li><li><a class="directive" href="mod_mime.html#addlanguage"><code class="directive">AddLanguage</code></a></li><li><a class="directive" href="mod_mime.html#addtype"><code class="directive">AddType</code></a></li></ul><h2>Type maps</h2>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>A type map has the same format as RFC822 mail headers. It
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed contains document descriptions separated by blank lines, with
381a2a9a387f449fab7d0c7e97c4184c26963abfdr lines beginning with a hash character ('#') treated as
381a2a9a387f449fab7d0c7e97c4184c26963abfdr comments. A document description consists of several header
381a2a9a387f449fab7d0c7e97c4184c26963abfdr records; records may be continued on multiple lines if the
381a2a9a387f449fab7d0c7e97c4184c26963abfdr continuation lines start with spaces. The leading space will be
381a2a9a387f449fab7d0c7e97c4184c26963abfdr deleted and the lines concatenated. A header record consists of
381a2a9a387f449fab7d0c7e97c4184c26963abfdr a keyword name, which always ends in a colon, followed by a
381a2a9a387f449fab7d0c7e97c4184c26963abfdr value. Whitespace is allowed between the header name and value,
381a2a9a387f449fab7d0c7e97c4184c26963abfdr and between the tokens of value. The headers allowed are: </p>
f4b3ec61df05330d25f55a36b975b4d7519fdeb1dh <dd>The encoding of the file. Apache only recognizes
381a2a9a387f449fab7d0c7e97c4184c26963abfdr encodings that are defined by an <a class="directive" href="mod_mime.html#addencoding"><code class="directive">AddEncoding</code></a> directive.
381a2a9a387f449fab7d0c7e97c4184c26963abfdr This normally includes the encodings <code>x-compress</code>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr files. The <code>x-</code> prefix is ignored for encoding
381a2a9a387f449fab7d0c7e97c4184c26963abfdr comparisons.</dd>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <dd>The language of the variant, as an Internet standard
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed language tag (RFC 1766). An example is <code>en</code>,
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed meaning English.</dd>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <dd>The length of the file, in bytes. If this header is not
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed present, then the actual length of the file is used.</dd>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed The MIME media type of the document, with optional
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed parameters. Parameters are separated from the media type
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed and from one another by a semi-colon, with a syntax of
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <code>name=value</code>. Common parameters include:
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <dd>an integer specifying the version of the media type.
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed For <code>text/html</code> this defaults to 2, otherwise
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <dd>a floating-point number with a value in the range 0.0
381a2a9a387f449fab7d0c7e97c4184c26963abfdr to 1.0, indicating the relative 'quality' of this variant
381a2a9a387f449fab7d0c7e97c4184c26963abfdr compared to the other available variants, independent of
381a2a9a387f449fab7d0c7e97c4184c26963abfdr the client's capabilities. For example, a jpeg file is
381a2a9a387f449fab7d0c7e97c4184c26963abfdr usually of higher source quality than an ascii file if it
381a2a9a387f449fab7d0c7e97c4184c26963abfdr is attempting to represent a photograph. However, if the
381a2a9a387f449fab7d0c7e97c4184c26963abfdr resource being represented is ascii art, then an ascii
381a2a9a387f449fab7d0c7e97c4184c26963abfdr file would have a higher source quality than a jpeg file.
381a2a9a387f449fab7d0c7e97c4184c26963abfdr All qs values are therefore specific to a given
381a2a9a387f449fab7d0c7e97c4184c26963abfdr resource.</dd>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <blockquote>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed </blockquote>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <dd>The path to the file containing this variant, relative to
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed the map file.</dd>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p>A MultiViews search is enabled by the MultiViews <a class="directive" href="core.html#options"><code class="directive">Options</code></a>. If the server receives a
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <code>/some/dir/foo</code> does <em>not</em> exist, then the
381a2a9a387f449fab7d0c7e97c4184c26963abfdr server reads the directory looking for all files named
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <code>foo.*</code>, and effectively fakes up a type map which
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed names all those files, assigning them the same media types and
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed content-encodings it would have if the client had asked for one
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed of them by name. It then chooses the best match to the client's
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed requirements, and returns that document.</p>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed<hr/><h2><a name="CacheNegotiatedDocs">CacheNegotiatedDocs</a> <a name="cachenegotiateddocs">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Allows content-negotiated documents to be
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reedcached by proxy servers</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>CacheNegotiatedDocs on|off</td></tr><tr><td><a class="help" href="directive-dict.html#Default">Default:</a></td><td><code>CacheNegotiatedDocs off</code></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_negotiation</td></tr><tr><td valign="top" align="left"><a class="help" href="directive-dict.html#Compatibility">Compatibility:</a></td><td>The syntax changed in version 2.0.</td></tr></table></td></tr></table>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p>If set, this directive allows content-negotiated documents
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed to be cached by proxy servers. This could mean that clients
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed behind those proxys could retrieve versions of the documents
381a2a9a387f449fab7d0c7e97c4184c26963abfdr that are not the best match for their abilities, but it will
381a2a9a387f449fab7d0c7e97c4184c26963abfdr make caching more efficient.</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>This directive only applies to requests which come from
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed HTTP/1.0 browsers. HTTP/1.1 provides much better control over
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed the caching of negotiated documents, and this directive has no
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p>Prior to version 2.0,
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <code class="directive">CacheNegotiatedDocs</code> did not take an
381a2a9a387f449fab7d0c7e97c4184c26963abfdr argument; it was turned on by the presence of the directive by
381a2a9a387f449fab7d0c7e97c4184c26963abfdr itself.</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<hr/><h2><a name="ForceLanguagePriority">ForceLanguagePriority</a> <a name="forcelanguagepriority">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>Action to take if a single acceptable document is not
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reedfound</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</td></tr><tr><td><a class="help" href="directive-dict.html#Default">Default:</a></td><td><code>ForceLanguagePriority None</code></td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td><a class="help" href="directive-dict.html#Override">Override:</a></td><td>FileInfo</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_negotiation</td></tr><tr><td valign="top" align="left"><a class="help" href="directive-dict.html#Compatibility">Compatibility:</a></td><td>Available in version 2.0.30 and later</td></tr></table></td></tr></table>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>The <code class="directive">ForceLanguagePriority</code> directive uses
381a2a9a387f449fab7d0c7e97c4184c26963abfdr the given <a class="directive" href="#languagepriority"><code class="directive">LanguagePriority</code></a> to satisfy
381a2a9a387f449fab7d0c7e97c4184c26963abfdr negotation where the server could otherwise not return a single
381a2a9a387f449fab7d0c7e97c4184c26963abfdr matching document.</p>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p><code>ForceLanguagePriority Prefer</code> uses
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <code>LanguagePriority</code> to serve a one valid result, rather
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed than returning an HTTP result 300 (MULTIPLE CHOICES) when there
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed are several equally valid choices. If the directives below were
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed given, and the user's Accept-Language header assigned en and de
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed each as quality .500 (equally acceptable) then then first matching
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed variant, en, will be served.</p>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed LanguagePriority en fr de<br/>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed ForceLanguagePriority Prefer
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p><code>ForceLanguagePriority Fallback</code> uses
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <code>LanguagePriority</code> to serve a valid result, rather than
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed returning an HTTP result 406 (NOT ACCEPTABLE). If the directives
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed below were given, and the user's Accept-Language only permitted an
381a2a9a387f449fab7d0c7e97c4184c26963abfdr es language response, but such a variant isn't found, then the
381a2a9a387f449fab7d0c7e97c4184c26963abfdr first variant from the LanguagePriority list below will be
381a2a9a387f449fab7d0c7e97c4184c26963abfdr served.</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr LanguagePriority en fr de<br/>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr ForceLanguagePriority Fallback
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed <p>Both options, Prefer and Fallback, may be specified, so either the
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed first matching variant from LanguagePriority will be served if more
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed that one variant is acceptable, or first available document will be
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed served if none of the variants matched the client's acceptable list of
8ad7418892268f9f0ba29518ab332f6a26f69fc5Darren Reed languages.</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<hr/><h2><a name="LanguagePriority">LanguagePriority</a> <a name="languagepriority">Directive</a></h2><table bgcolor="#cccccc" border="0" cellspacing="0" cellpadding="1"><tr><td><table bgcolor="#ffffff"><tr><td><strong>Description: </strong></td><td>The precendence of language variants for cases where
381a2a9a387f449fab7d0c7e97c4184c26963abfdrthe client does not express a preference</td></tr><tr><td><a class="help" href="directive-dict.html#Syntax">Syntax:</a></td><td>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</td></tr><tr><td><a class="help" href="directive-dict.html#Context">Context:</a></td><td>server config, virtual host, directory, .htaccess</td></tr><tr><td><a class="help" href="directive-dict.html#Override">Override:</a></td><td>FileInfo</td></tr><tr><td><a class="help" href="directive-dict.html#Status">Status:</a></td><td>Base</td></tr><tr><td><a class="help" href="directive-dict.html#Module">Module:</a></td><td>mod_negotiation</td></tr></table></td></tr></table>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>The <code class="directive">LanguagePriority</code> sets the precedence
381a2a9a387f449fab7d0c7e97c4184c26963abfdr of language variants for the case where the client does not
381a2a9a387f449fab7d0c7e97c4184c26963abfdr express a preference, when handling a MultiViews request. The list
381a2a9a387f449fab7d0c7e97c4184c26963abfdr of <em>MIME-lang</em> are in order of decreasing preference.
381a2a9a387f449fab7d0c7e97c4184c26963abfdr Example:</p>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>LanguagePriority en fr de</code></td></tr></table></blockquote>
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <code>foo.html.fr</code> and <code>foo.html.de</code> both
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed existed, but the browser did not express a language preference,
381a2a9a387f449fab7d0c7e97c4184c26963abfdr <p>Note that this directive only has an effect if a 'best'
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed language cannot be determined by any other means or the <a class="directive" href="#forcelanguagepriority"><code class="directive">ForceLanguagePriority</code></a> directive
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed is not <code>None</code>. Correctly implemented HTTP/1.1 requests
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed will mean this directive has no effect.</p>
7ddc9b1afd18f260b9fb78ec7732facd91769131Darren Reed<hr/></blockquote><h3 align="center">Apache HTTP Server Version 2.0</h3><a href="./"><img src="/images/index.gif" alt="Index"/></a><a href="../"><img src="/images/home.gif" alt="Home"/></a></body></html>
