1<?xml version="1.0" encoding="ISO-8859-1"?> 2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> 3<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- 4 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 5 This file is generated from xml source: DO NOT EDIT 6 XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX 7 --> 8<title>mod_negotiation - Apache HTTP Server</title> 9<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> 10<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> 11<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body> 17<div id="page-header"> 18<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 19<p class="apache">Apache HTTP Server Version 2.4</p> 20<img alt="" src="/images/feather.gif" /></div> 21<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 22<div id="path"> 23<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Modules</a></div> 24<div id="page-content"> 25<div id="preamble"><h1>Apache Module mod_negotiation</h1> 26<div class="toplang"> 27<p><span>Available Languages: </span><a href="/en/mod/mod_negotiation.html" title="English"> en </a> | 28<a href="/fr/mod/mod_negotiation.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 29<a href="/ja/mod/mod_negotiation.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 30</div> 31<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides for <a href="/content-negotiation.html">content negotiation</a></td></tr> 32<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Base</td></tr> 33<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>negotiation_module</td></tr> 34<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_negotiation.c</td></tr></table> 35<h3>Summary</h3> 36 37 <p>Content negotiation, or more accurately content selection, is 38 the selection of the document that best matches the clients 39 capabilities, from one of several available documents. There 40 are two implementations of this.</p> 41 42 <ul> 43 <li>A type map (a file with the handler 44 <code>type-map</code>) which explicitly lists the files 45 containing the variants.</li> 46 47 <li>A Multiviews search (enabled by the <code>Multiviews</code> 48 <code class="directive"><a href="/mod/core.html#options">Options</a></code>), where the server does 49 an implicit filename pattern match, and choose from amongst the 50 results.</li> 51 </ul> 52</div> 53<div id="quickview"><h3 class="directives">Directives</h3> 54<ul id="toc"> 55<li><img alt="" src="/images/down.gif" /> <a href="#cachenegotiateddocs">CacheNegotiatedDocs</a></li> 56<li><img alt="" src="/images/down.gif" /> <a href="#forcelanguagepriority">ForceLanguagePriority</a></li> 57<li><img alt="" src="/images/down.gif" /> <a href="#languagepriority">LanguagePriority</a></li> 58</ul> 59<h3>Topics</h3> 60<ul id="topics"> 61<li><img alt="" src="/images/down.gif" /> <a href="#typemaps">Type maps</a></li> 62<li><img alt="" src="/images/down.gif" /> <a href="#multiviews">Multiviews</a></li> 63</ul><h3>See also</h3> 64<ul class="seealso"> 65<li><code class="directive"><a href="/mod/core.html#options">Options</a></code></li> 66<li><code class="module"><a href="/mod/mod_mime.html">mod_mime</a></code></li> 67<li><a href="/content-negotiation.html">Content 68Negotiation</a></li> 69<li><a href="/env.html">Environment Variables</a></li> 70</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 71<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 72<div class="section"> 73<h2><a name="typemaps" id="typemaps">Type maps</a></h2> 74 <p>A type map has a format similar to RFC822 mail headers. It 75 contains document descriptions separated by blank lines, with 76 lines beginning with a hash character ('#') treated as 77 comments. A document description consists of several header 78 records; records may be continued on multiple lines if the 79 continuation lines start with spaces. The leading space will be 80 deleted and the lines concatenated. A header record consists of 81 a keyword name, which always ends in a colon, followed by a 82 value. Whitespace is allowed between the header name and value, 83 and between the tokens of value. The headers allowed are: </p> 84 85 <dl> 86 <dt><code>Content-Encoding:</code></dt> 87 <dd>The encoding of the file. Apache only recognizes 88 encodings that are defined by an <code class="directive"><a href="/mod/mod_mime.html#addencoding">AddEncoding</a></code> directive. 89 This normally includes the encodings <code>x-compress</code> 90 for compress'd files, and <code>x-gzip</code> for gzip'd 91 files. The <code>x-</code> prefix is ignored for encoding 92 comparisons.</dd> 93 94 <dt><code>Content-Language:</code></dt> 95 <dd>The language(s) of the variant, as an Internet standard 96 language tag (<a href="http://www.ietf.org/rfc/rfc1766.txt">RFC 1766</a>). An example is <code>en</code>, 97 meaning English. If the variant contains more than one 98 language, they are separated by a comma.</dd> 99 100 <dt><code>Content-Length:</code></dt> 101 <dd>The length of the file, in bytes. If this header is not 102 present, then the actual length of the file is used.</dd> 103 104 <dt><code>Content-Type:</code></dt> 105 106 <dd> 107 The <a class="glossarylink" href="/glossary.html#mime-type" title="see glossary">MIME media type</a> of 108 the document, with optional parameters. Parameters are 109 separated from the media type and from one another by a 110 semi-colon, with a syntax of <code>name=value</code>. Common 111 parameters include: 112 113 <dl> 114 <dt><code>level</code></dt> 115 <dd>an integer specifying the version of the media type. 116 For <code>text/html</code> this defaults to 2, otherwise 117 0.</dd> 118 119 <dt><code>qs</code></dt> 120 <dd>a floating-point number with a value in the range 0[.000] 121 to 1[.000], indicating the relative 'quality' of this variant 122 compared to the other available variants, independent of 123 the client's capabilities. For example, a jpeg file is 124 usually of higher source quality than an ascii file if it 125 is attempting to represent a photograph. However, if the 126 resource being represented is ascii art, then an ascii 127 file would have a higher source quality than a jpeg file. 128 All <code>qs</code> values are therefore specific to a given 129 resource.</dd> 130 </dl> 131 132 <div class="example"><h3>Example</h3><p><code> 133 Content-Type: image/jpeg; qs=0.8 134 </code></p></div> 135 </dd> 136 137 <dt><code>URI:</code></dt> 138 <dd>uri of the file containing the variant (of the given 139 media type, encoded with the given content encoding). These 140 are interpreted as URLs relative to the map file; they must 141 be on the same server, and they must refer to files to 142 which the client would be granted access if they were to be 143 requested directly.</dd> 144 145 <dt><code>Body:</code></dt> 146 <dd>The actual content of the resource may 147 be included in the type-map file using the Body header. This 148 header must contain a string that designates a delimiter for 149 the body content. Then all following lines in the type map 150 file will be considered part of the resource body until the 151 delimiter string is found. 152 153 <div class="example"><h3>Example:</h3><p><code> 154 Body:----xyz----<br /> 155 <html><br /> 156 <body><br /> 157 <p>Content of the page.</p><br /> 158 </body><br /> 159 </html><br /> 160 ----xyz---- 161 </code></p></div> 162 </dd> 163 </dl> 164 165 <p>Consider, for example, a resource called 166 <code>document.html</code> which is available in English, French, 167 and German. The files for each of these are called 168 <code>document.html.en</code>, <code>document.html.fr</code>, and 169 <code>document.html.de</code>, respectively. The type map file will 170 be called <code>document.html.var</code>, and will contain the 171 following:</p> 172 173 <div class="example"><p><code> 174 URI: document.html<br /> 175 <br /> 176 Content-language: en<br /> 177 Content-type: text/html<br /> 178 URI: document.html.en<br /> 179 <br /> 180 Content-language: fr<br /> 181 Content-type: text/html<br /> 182 URI: document.html.fr<br /> 183 <br /> 184 Content-language: de<br /> 185 Content-type: text/html<br /> 186 URI: document.html.de<br /> 187 <br /> 188 189 </code></p></div> 190 191 <p>All four of these files should be placed in the same directory, 192 and the <code>.var</code> file should be associated with the 193 <code>type-map</code> handler with an <code class="directive"><a href="/mod/mod_mime.html#addhandler">AddHandler</a></code> directive:</p> 194 195 <pre class="prettyprint lang-config">AddHandler type-map .var</pre> 196 197 198 <p>A request for <code>document.html.var</code> in this directory will 199 result in choosing the variant which most closely matches the language preference 200 specified in the user's <code>Accept-Language</code> request 201 header.</p> 202 203 <p>If <code>Multiviews</code> is enabled, and <code class="directive"><a href="/mod/mod_mime.html#multiviewsmatch">MultiviewsMatch</a></code> is set to "handlers" or "any", a request to 204 <code>document.html</code> will discover <code>document.html.var</code> and 205 continue negotiating with the explicit type map.</p> 206 207 <p>Other configuration directives, such as <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> can be used to map <code>document.html</code> to 208 <code>document.html.var</code>.</p> 209 210</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 211<div class="section"> 212<h2><a name="multiviews" id="multiviews">Multiviews</a></h2> 213 <p>A Multiviews search is enabled by the <code>Multiviews</code> 214 <code class="directive"><a href="/mod/core.html#options">Options</a></code>. If the server receives a 215 request for <code>/some/dir/foo</code> and 216 <code>/some/dir/foo</code> does <em>not</em> exist, then the 217 server reads the directory looking for all files named 218 <code>foo.*</code>, and effectively fakes up a type map which 219 names all those files, assigning them the same media types and 220 content-encodings it would have if the client had asked for one 221 of them by name. It then chooses the best match to the client's 222 requirements, and returns that document.</p> 223 224 <p>The <code class="directive"><a href="/mod/mod_mime.html#multiviewsmatch">MultiviewsMatch</a></code> 225 directive configures whether Apache will consider files 226 that do not have content negotiation meta-information assigned 227 to them when choosing files.</p> 228</div> 229<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 230<div class="directive-section"><h2><a name="CacheNegotiatedDocs" id="CacheNegotiatedDocs">CacheNegotiatedDocs</a> <a name="cachenegotiateddocs" id="cachenegotiateddocs">Directive</a></h2> 231<table class="directive"> 232<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Allows content-negotiated documents to be 233cached by proxy servers</td></tr> 234<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>CacheNegotiatedDocs On|Off</code></td></tr> 235<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>CacheNegotiatedDocs Off</code></td></tr> 236<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr> 237<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 238<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 239</table> 240 <p>If set, this directive allows content-negotiated documents 241 to be cached by proxy servers. This could mean that clients 242 behind those proxys could retrieve versions of the documents 243 that are not the best match for their abilities, but it will 244 make caching more efficient.</p> 245 246 <p>This directive only applies to requests which come from 247 HTTP/1.0 browsers. HTTP/1.1 provides much better control over 248 the caching of negotiated documents, and this directive has no 249 effect in responses to HTTP/1.1 requests.</p> 250 251 252</div> 253<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 254<div class="directive-section"><h2><a name="ForceLanguagePriority" id="ForceLanguagePriority">ForceLanguagePriority</a> <a name="forcelanguagepriority" id="forcelanguagepriority">Directive</a></h2> 255<table class="directive"> 256<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Action to take if a single acceptable document is not 257found</td></tr> 258<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>ForceLanguagePriority None|Prefer|Fallback [Prefer|Fallback]</code></td></tr> 259<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>ForceLanguagePriority Prefer</code></td></tr> 260<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 261<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 262<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 263<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 264</table> 265 <p>The <code class="directive">ForceLanguagePriority</code> directive uses 266 the given <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to satisfy 267 negotiation where the server could otherwise not return a single 268 matching document.</p> 269 270 <p><code>ForceLanguagePriority Prefer</code> uses 271 <code>LanguagePriority</code> to serve a one valid result, rather 272 than returning an HTTP result 300 (MULTIPLE CHOICES) when there 273 are several equally valid choices. If the directives below were 274 given, and the user's <code>Accept-Language</code> header assigned 275 <code>en</code> and <code>de</code> each as quality <code>.500</code> 276 (equally acceptable) then the first matching variant, <code>en</code>, 277 will be served.</p> 278 279 <pre class="prettyprint lang-config">LanguagePriority en fr de 280ForceLanguagePriority Prefer</pre> 281 282 283 <p><code>ForceLanguagePriority Fallback</code> uses 284 <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> to 285 serve a valid result, rather than returning an HTTP result 406 286 (NOT ACCEPTABLE). If the directives below were given, and the user's 287 <code>Accept-Language</code> only permitted an <code>es</code> 288 language response, but such a variant isn't found, then the first 289 variant from the <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> list below will be served.</p> 290 291 <pre class="prettyprint lang-config">LanguagePriority en fr de 292ForceLanguagePriority Fallback</pre> 293 294 295 <p>Both options, <code>Prefer</code> and <code>Fallback</code>, may be 296 specified, so either the first matching variant from <code class="directive"><a href="#languagepriority">LanguagePriority</a></code> will be served if 297 more than one variant is acceptable, or first available document will 298 be served if none of the variants matched the client's acceptable list 299 of languages.</p> 300 301<h3>See also</h3> 302<ul> 303<li><code class="directive"><a href="/mod/mod_mime.html#addlanguage">AddLanguage</a></code></li> 304</ul> 305</div> 306<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 307<div class="directive-section"><h2><a name="LanguagePriority" id="LanguagePriority">LanguagePriority</a> <a name="languagepriority" id="languagepriority">Directive</a></h2> 308<table class="directive"> 309<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>The precendence of language variants for cases where 310the client does not express a preference</td></tr> 311<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>LanguagePriority <var>MIME-lang</var> [<var>MIME-lang</var>] 312...</code></td></tr> 313<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr> 314<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr> 315<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Base</td></tr> 316<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_negotiation</td></tr> 317</table> 318 <p>The <code class="directive">LanguagePriority</code> sets the precedence 319 of language variants for the case where the client does not 320 express a preference, when handling a Multiviews request. The list 321 of <var>MIME-lang</var> are in order of decreasing preference.</p> 322 323 <pre class="prettyprint lang-config">LanguagePriority en fr de</pre> 324 325 326 <p>For a request for <code>foo.html</code>, where 327 <code>foo.html.fr</code> and <code>foo.html.de</code> both 328 existed, but the browser did not express a language preference, 329 then <code>foo.html.fr</code> would be returned.</p> 330 331 <p>Note that this directive only has an effect if a 'best' 332 language cannot be determined by any other means or the <code class="directive"><a href="#forcelanguagepriority">ForceLanguagePriority</a></code> directive 333 is not <code>None</code>. In general, the client determines the 334 language preference, not the server.</p> 335 336<h3>See also</h3> 337<ul> 338<li><code class="directive"><a href="/mod/mod_mime.html#addlanguage">AddLanguage</a></code></li> 339</ul> 340</div> 341</div> 342<div class="bottomlang"> 343<p><span>Available Languages: </span><a href="/en/mod/mod_negotiation.html" title="English"> en </a> | 344<a href="/fr/mod/mod_negotiation.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 345<a href="/ja/mod/mod_negotiation.html" hreflang="ja" rel="alternate" title="Japanese"> ja </a></p> 346</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 347<script type="text/javascript"><!--//--><![CDATA[//><!-- 348var comments_shortname = 'httpd'; 349var comments_identifier = 'http://httpd.apache.org/docs/2.4/mod/mod_negotiation.html'; 350(function(w, d) { 351 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 352 d.write('<div id="comments_thread"><\/div>'); 353 var s = d.createElement('script'); 354 s.type = 'text/javascript'; 355 s.async = true; 356 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 357 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 358 } 359 else { 360 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 361 } 362})(window, document); 363//--><!]]></script></div><div id="footer"> 364<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 365<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 366if (typeof(prettyPrint) !== 'undefined') { 367 prettyPrint(); 368} 369//--><!]]></script> 370</body></html>
