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