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