mod_negotiation.html revision ac6d1ce7ccb1950bb2145a5c2c3498235353bcb0
c636315472e4f87313af7be30b7fbcad4b8ca8a4Stephen Gallagher<html xmlns="http://www.w3.org/TR/xhtml1/strict"><head><!--
c636315472e4f87313af7be30b7fbcad4b8ca8a4Stephen GallagherXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
fd5a4eacd56700ffb08a73121aeacdc806cb0132Sumit Bose This file is generated from xml source: DO NOT EDIT
8b1f525acd20f36c836e827de3c251088961c5d9Stephen GallagherXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
8b1f525acd20f36c836e827de3c251088961c5d9Stephen Gallagher--><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>Provides for <a href="/content-negotiation.html">content negotiation</a></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>
8b1f525acd20f36c836e827de3c251088961c5d9Stephen Gallagher <p>Content negotiation, or more accurately content selection, is
8b1f525acd20f36c836e827de3c251088961c5d9Stephen Gallagher the selection of the document that best matches the clients
8b1f525acd20f36c836e827de3c251088961c5d9Stephen Gallagher capabilities, from one of several available documents. There
84ae5edab16ad6be5e3be956cb6fa031c1428eb5Stephen Gallagher are two implementations of this.</p>
df4cc3a83c5d6700b6a09ff96cb4a6b1949b1aa9Stephen Gallagher <li>A type map (a file with the handler
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>type-map</code>) which explicitly lists the files
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher containing the variants.</li>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <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
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher implicit filename pattern match, and choose from amongst the
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<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><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>Type maps</h2>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>A type map has the same format as RFC822 mail headers. It
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher contains document descriptions separated by blank lines, with
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher lines beginning with a hash character ('#') treated as
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher comments. A document description consists of several header
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher records; records may be continued on multiple lines if the
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher continuation lines start with spaces. The leading space will be
2a552e43581c74f51205c7141ec9f6e9542509f8Stephen Gallagher deleted and the lines concatenated. A header record consists of
2a552e43581c74f51205c7141ec9f6e9542509f8Stephen Gallagher a keyword name, which always ends in a colon, followed by a
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher value. Whitespace is allowed between the header name and value,
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher and between the tokens of value. The headers allowed are: </p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <dd>The encoding of the file. Apache only recognizes
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher encodings that are defined by an <a href="mod_mime.html#addencoding" class="directive"><code class="directive">AddEncoding</code></a> directive.
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher This normally includes the encodings <code>x-compress</code>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher for compress'd files, and <code>x-gzip</code> for gzip'd
eb2e21b764d03544d8161e9956d7f70b07b75f77Simo Sorce files. The <code>x-</code> prefix is ignored for encoding
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher comparisons.</dd>
4dd615c01357b8715711aad6820ba9595d3ad377Stephen Gallagher <dd>The language of the variant, as an Internet standard
4b6a0d0b3d42e5fdb457f47d9adfa5e66b160256Stephen Gallagher language tag (RFC 1766). An example is <code>en</code>,
e124844907ed6973915e4d56f5442ecd07535a12Jakub Hrozek meaning English.</dd>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <dd>The length of the file, in bytes. If this header is not
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher present, then the actual length of the file is used.</dd>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher The MIME media type of the document, with optional
be1ef1c62ad13612be5e1f879476c24452a5d6d0Stephen Gallagher parameters. Parameters are separated from the media type
be1ef1c62ad13612be5e1f879476c24452a5d6d0Stephen Gallagher and from one another by a semi-colon, with a syntax of
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>name=value</code>. Common parameters include:
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <dd>an integer specifying the version of the media type.
558998ce664055a75595371118f818084d8f2b23Jan Cholasta For <code>text/html</code> this defaults to 2, otherwise
558998ce664055a75595371118f818084d8f2b23Jan Cholasta <dd>a floating-point number with a value in the range 0.0
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher to 1.0, indicating the relative 'quality' of this variant
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher compared to the other available variants, independent of
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher the client's capabilities. For example, a jpeg file is
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher usually of higher source quality than an ascii file if it
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher is attempting to represent a photograph. However, if the
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher resource being represented is ascii art, then an ascii
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher file would have a higher source quality than a jpeg file.
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher All qs values are therefore specific to a given
c737e1444fb186e349e59bfa9dac4995b720b4b1Jan Zeleny resource.</dd>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>Content-Type: image/jpeg; qs=0.8</code>
2827b0d03f7b6bafa504d22a5d7ca39cbda048b3Pavel Březina <dd>The path to the file containing this variant, relative to
2827b0d03f7b6bafa504d22a5d7ca39cbda048b3Pavel Březina the map file.</dd>
9e80079370ff3b943832adc3c5ef430e64be0a0cJakub Hrozek <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
e7311aec8d691e5427317442387af1bc8fff3742Jan Cholasta <code>/some/dir/foo</code> does <em>not</em> exist, then the
e7311aec8d691e5427317442387af1bc8fff3742Jan Cholasta server reads the directory looking for all files named
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>foo.*</code>, and effectively fakes up a type map which
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher names all those files, assigning them the same media types and
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher content-encodings it would have if the client had asked for one
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher of them by name. It then chooses the best match to the client's
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher requirements, and returns that document.</p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<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
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallaghercached by proxy servers</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>CacheNegotiatedDocs on|off</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>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>If set, this directive allows content-negotiated documents
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher to be cached by proxy servers. This could mean that clients
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher behind those proxys could retrieve versions of the documents
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher that are not the best match for their abilities, but it will
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher make caching more efficient.</p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>This directive only applies to requests which come from
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher HTTP/1.0 browsers. HTTP/1.1 provides much better control over
69aaef8719c5cf33ed1c4090fa313ba281bf8a02Jakub Hrozek the caching of negotiated documents, and this directive has no
4dd615c01357b8715711aad6820ba9595d3ad377Stephen Gallagher effect in responses to HTTP/1.1 requests.</p>
a6098862048d4bb469130b9ff21be3020d6f2c54Sumit Bose <p>Prior to version 2.0,
a6098862048d4bb469130b9ff21be3020d6f2c54Sumit Bose <code class="directive">CacheNegotiatedDocs</code> did not take an
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher argument; it was turned on by the presence of the directive by
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<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
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagherfound</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</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>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>The <code class="directive">ForceLanguagePriority</code> directive uses
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher the given <a href="#languagepriority" class="directive"><code class="directive">LanguagePriority</code></a> to satisfy
bf5a808fa92007c325c3996e79694badfab201d4Stephen Gallagher negotation where the server could otherwise not return a single
bf5a808fa92007c325c3996e79694badfab201d4Stephen Gallagher matching document.</p>
667db40da4db362d7ca0a1f7f1c4ba40fb71795aJakub Hrozek <p><code>ForceLanguagePriority Prefer</code> uses
667db40da4db362d7ca0a1f7f1c4ba40fb71795aJakub Hrozek <code>LanguagePriority</code> to serve a one valid result, rather
bf5a808fa92007c325c3996e79694badfab201d4Stephen Gallagher than returning an HTTP result 300 (MULTIPLE CHOICES) when there
bf5a808fa92007c325c3996e79694badfab201d4Stephen Gallagher are several equally valid choices. If the directives below were
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher given, and the user's Accept-Language header assigned en and de
bf5a808fa92007c325c3996e79694badfab201d4Stephen Gallagher each as quality .500 (equally acceptable) then then first matching
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher variant, en, will be served.</p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher LanguagePriority en fr de<br>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher ForceLanguagePriority Prefer
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p><code>ForceLanguagePriority Fallback</code> uses
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>LanguagePriority</code> to serve a valid result, rather than
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher returning an HTTP result 406 (NOT ACCEPTABLE). If the directives
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher below were given, and the user's Accept-Language only permitted an
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher es langauge response, but such a variant isn't found, then the
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher first variant from the LanguagePriority list below will be
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher LanguagePriority en fr de<br>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher ForceLanguagePriority Fallback
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>Both options, Prefer and Fallback, may be specified, so either the
c7919a4fe41133cc466aa3d9431bfceee5784e7bJan Cholasta first matching variant from LanguagePriority will be served if more
b35f20cd8ecdc8308a3201e55752fb0443ec6ae4Jan Cholasta that one variant is acceptable, or first available document will be
c7919a4fe41133cc466aa3d9431bfceee5784e7bJan Cholasta served if none of the variants matched the client's acceptable list of
69aaef8719c5cf33ed1c4090fa313ba281bf8a02Jakub Hrozek languages.</p>
3b08dec5ee634f83ee18e1753d5ffe0ac5e3c458Jakub Hrozek<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
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagherthe client does not express a preference</td></tr><tr><td><a href="directive-dict.html#Syntax" class="help">Syntax:</a></td><td>LanguagePriority <em>MIME-lang</em> [<em>MIME-lang</em>] ...</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>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>The <code class="directive">LanguagePriority</code> sets the precedence
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher of language variants for the case where the client does not
c7919a4fe41133cc466aa3d9431bfceee5784e7bJan Cholasta express a preference, when handling a MultiViews request. The list
b35f20cd8ecdc8308a3201e55752fb0443ec6ae4Jan Cholasta of <em>MIME-lang</em> are in order of decreasing preference.
c7919a4fe41133cc466aa3d9431bfceee5784e7bJan Cholasta Example:</p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code>LanguagePriority en fr de</code></td></tr></table></blockquote>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <p>For a request for <code>foo.html</code>, where
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher <code>foo.html.fr</code> and <code>foo.html.de</code> both
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher existed, but the browser did not express a language preference,
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher then <code>foo.html.fr</code> would be returned.</p>
3b1df539835367cb81cd5ff0f9959947d5642e55Stephen Gallagher <p>Note that this directive only has an effect if a 'best'
3b1df539835367cb81cd5ff0f9959947d5642e55Stephen Gallagher language cannot be determined by any other means or the <a href="#forcelanguagepriority" class="directive"><code class="directive">ForceLanguagePriority</code></a> directive
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher is not <code>None</code>. Correctly implemented HTTP/1.1 requests
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher will mean this directive has no effect.</p>
551aa6c36797ed720487f5974dcadabf19e6ff9fStephen Gallagher<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>
