mod_vhost_alias.html revision 2eaf662cbc81e823e8d9aeb8d54e69e63032493e
2N/A<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
2N/A "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
2N/A
2N/A<html xmlns="http://www.w3.org/1999/xhtml">
2N/A <head>
2N/A <meta name="generator" content="HTML Tidy, see www.w3.org" />
2N/A
2N/A <title>Apache module mod_vhost_alias</title>
2N/A </head>
2N/A <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
2N/A
2N/A <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
2N/A vlink="#000080" alink="#FF0000">
2N/A <!--#include virtual="header.html" -->
2N/A
2N/A <h1 align="CENTER">Module mod_vhost_alias</h1>
2N/A
2N/A <p>This module provides support for <a
2N/A href="/vhosts/mass.html">dynamically configured mass virtual
2N/A hosting</a>.</p>
3701N/A
2N/A <p><a href="module-dict.html#Status"
2N/A rel="Help"><strong>Status:</strong></a> Extension<br />
32N/A <a href="module-dict.html#SourceFile"
32N/A rel="Help"><strong>Source File:</strong></a>
313N/A mod_vhost_alias.c<br />
313N/A <a href="module-dict.html#ModuleIdentifier"
313N/A rel="Help"><strong>Module Identifier:</strong></a>
313N/A vhost_alias_module<br />
313N/A <a href="module-dict.html#Compatibility"
313N/A rel="Help"><strong>Compatibility:</strong></a> Available in
313N/A Apache 1.3.7 and later.</p>
313N/A
313N/A <h2>Summary</h2>
2104N/A
2104N/A <p>This module creates dynamically configured virtual hosts, by
313N/A allowing the IP address and/or the <code>Host:</code> header of
313N/A the HTTP request to be used as part of the pathname to
313N/A determine what files to serve. This allows for easy use of a
313N/A huge number of virtual hosts with similar configurations.</p>
2104N/A
313N/A <h2>Directives</h2>
2104N/A
127N/A <ul>
4357N/A <li><a
4357N/A href="#virtualdocumentroot">VirtualDocumentRoot</a></li>
1256N/A
4357N/A <li><a
4357N/A href="#virtualdocumentrootip">VirtualDocumentRootIP</a></li>
1256N/A
127N/A <li><a href="#virtualscriptalias">VirtualScriptAlias</a></li>
3817N/A
3817N/A <li><a
3817N/A href="#virtualscriptaliasip">VirtualScriptAliasIP</a></li>
538N/A </ul>
538N/A
538N/A <p>See also: <a
4488N/A href="core.html#usecanonicalname">UseCanonicalName</a>.</p>
538N/A
3817N/A <h2>Directory Name Interpolation</h2>
538N/A
327N/A <p>All the directives in this module interpolate a string into
327N/A a pathname. The interpolated string (henceforth called the
327N/A "name") may be either the server name (see the <a
327N/A href="core.html#usecanonicalname"><code>UseCanonicalName</code></a>
327N/A directive for details on how this is determined) or the IP
327N/A address of the virtual host on the server in dotted-quad
327N/A format. The interpolation is controlled by specifiers inspired
327N/A by <code>printf</code> which have a number of formats:</p>
327N/A
327N/A <dl>
327N/A <dt><code>%%</code></dt>
327N/A
3817N/A <dd>insert a <code>%</code></dd>
3817N/A
3817N/A <dt><code>%p</code></dt>
2217N/A
2217N/A <dd>insert the port number of the virtual host</dd>
2217N/A
2217N/A <dt><code>%N.M</code></dt>
177N/A
177N/A <dd>insert (part of) the name</dd>
4488N/A </dl>
4437N/A <br />
4488N/A <br />
4437N/A
4437N/A
4437N/A <p><code>N</code> and <code>M</code> are used to specify
3951N/A substrings of the name. <code>N</code> selects from the
3951N/A dot-separated components of the name, and <code>M</code>
3951N/A selects characters within whatever <code>N</code> has selected.
2N/A <code>M</code> is optional and defaults to zero if it isn't
3951N/A present; the dot must be present if and only if <code>M</code>
883N/A is present. The interpretation is as follows:</p>
26N/A
38N/A <dl>
38N/A <dt><code>0</code></dt>
4518N/A
4518N/A <dd>the whole name</dd>
4518N/A
4518N/A <dt><code>1</code></dt>
1043N/A
1256N/A <dd>the first part</dd>
26N/A
1043N/A <dt><code>2</code></dt>
1043N/A
477N/A <dd>the second part</dd>
538N/A
38N/A <dt><code>-1</code></dt>
3817N/A
6N/A <dd>the last part</dd>
2818N/A
3936N/A <dt><code>-2</code></dt>
3936N/A
3936N/A <dd>the penultimate part</dd>
2818N/A
2818N/A <dt><code>2+</code></dt>
2N/A
34N/A <dd>the second and all subsequent parts</dd>
34N/A
94N/A <dt><code>-2+</code></dt>
94N/A
156N/A <dd>the penultimate and all preceding parts</dd>
156N/A
34N/A <dt><code>1+</code> and <code>-1+</code></dt>
59N/A
1251N/A <dd>the same as <code>0</code></dd>
1251N/A </dl>
1256N/A If <code>N</code> or <code>M</code> is greater than the number
72N/A of parts available a single underscore is interpolated. <br />
72N/A <br />
59N/A
2N/A
85N/A <h3>Examples</h3>
61N/A
61N/A <p>For simple name-based virtual hosts you might use the
220N/A following directives in your server configuration file:</p>
61N/A<pre>
61N/A UseCanonicalName Off
1119N/A VirtualDocumentRoot /usr/local/apache/vhosts/%0
172N/A</pre>
61N/A A request for
61N/A <code>http://www.example.com/directory/file.html</code> will be
220N/A satisfied by the file
220N/A <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>.
61N/A <br />
172N/A <br />
454N/A
61N/A
172N/A <p>For a very large number of virtual hosts it is a good idea
61N/A to arrange the files to reduce the size of the
152N/A <code>vhosts</code> directory. To do this you might use the
74N/A following in your configuration file:</p>
61N/A<pre>
220N/A UseCanonicalName Off
85N/A VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2
172N/A</pre>
61N/A A request for
172N/A <code>http://www.example.isp.com/directory/file.html</code>
61N/A will be satisfied by the file
1119N/A <code>/usr/local/apache/vhosts/isp.com/e/x/a/example/directory/file.html</code>.
172N/A A more even spread of files can be achieved by hashing from the
61N/A end of the name, for example:
61N/A<pre>
220N/A VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2
61N/A</pre>
454N/A The example request would come from
61N/A <code>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</code>.
172N/A Alternatively you might use:
61N/A<pre>
172N/A VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+
61N/A</pre>
152N/A The example request would come from
152N/A <code>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</code>.
220N/A <br />
61N/A <br />
61N/A
43N/A
220N/A <p>For IP-based virtual hosting you might use the following in
43N/A your configuration file:</p>
120N/A<pre>
64N/A UseCanonicalName DNS
64N/A VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs
64N/A VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin
43N/A</pre>
43N/A A request for
120N/A <code>http://www.example.isp.com/directory/file.html</code>
64N/A would be satisfied by the file
64N/A <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code>
64N/A if the IP address of <code>www.example.com</code> were
220N/A 10.20.30.40. A request for
64N/A <code>http://www.example.isp.com/cgi-bin/script.pl</code> would
64N/A be satisfied by executing the program
486N/A <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>.
486N/A <br />
64N/A <br />
64N/A
64N/A
64N/A <p>If you want to include the <code>.</code> character in a
64N/A <code>VirtualDocumentRoot</code> directive, but it clashes with
64N/A a <code>%</code> directive, you can work around the problem in
64N/A the following way:</p>
43N/A<pre>
16N/A VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
16N/A</pre>
16N/A A request for
34N/A <code>http://www.example.isp.com/directory/file.html</code>
34N/A will be satisfied by the file
16N/A <code>/usr/local/apache/vhosts/example.isp/directory/file.html</code>.
6N/A <br />
12N/A <br />
1256N/A
12N/A
12N/A <p>The <a href="mod_log_config.html#formats">LogFormat
12N/A directives</a> <code>%V</code> and <code>%A</code> are useful
12N/A in conjunction with this module.</p>
12N/A <hr />
12N/A
12N/A <h2><a id="virtualdocumentroot"
12N/A name="virtualdocumentroot">VirtualDocumentRoot
12N/A directive</a></h2>
4085N/A
369N/A <p><a href="directive-dict.html#Syntax"
369N/A rel="Help"><strong>Syntax:</strong></a> VirtualDocumentRoot
3056N/A <em>interpolated-directory</em><br />
369N/A <a href="directive-dict.html#Default"
4085N/A rel="Help"><strong>Default:</strong></a> None<br />
61N/A <a href="directive-dict.html#Context"
61N/A rel="Help"><strong>Context:</strong></a> server config, virtual
61N/A host<br />
4085N/A <a href="directive-dict.html#Status"
61N/A rel="Help"><strong>Status:</strong></a> Extension<br />
61N/A <a href="directive-dict.html#Module"
12N/A rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br />
4085N/A <a href="directive-dict.html#Compatibility"
4085N/A rel="Help"><strong>Compatibility:</strong></a>
181N/A VirtualDocumentRoot is only available in 1.3.7 and later.</p>
181N/A
12N/A <p>The <code>VirtualDocumentRoot</code> directive allows you to
4085N/A determine where Apache will find your documents based on the
61N/A value of the server name. The result of expanding
61N/A <em>interpolated-directory</em> is used as the root of the
12N/A document tree in a similar manner to the <a
4085N/A href="core.html#documentroot"><code>DocumentRoot</code></a>
279N/A directive's argument. If <em>interpolated-directory</em> is
279N/A <code>none</code> then <code>VirtaulDocumentRoot</code> is
181N/A turned off. This directive cannot be used in the same context
181N/A as <a
181N/A href="#virtualdocumentrootip"><code>VirtualDocumentRootIP</code></a>.</p>
2N/A <hr />
3864N/A
3864N/A <h2><a id="virtualdocumentrootip"
3864N/A name="virtualdocumentrootip">VirtualDocumentRootIP
3864N/A directive</a></h2>
3558N/A
4089N/A <p><a href="directive-dict.html#Syntax"
3558N/A rel="Help"><strong>Syntax:</strong></a> VirtualDocumentRootIP
3558N/A <em>interpolated-directory</em><br />
3558N/A <a href="directive-dict.html#Default"
3558N/A rel="Help"><strong>Default:</strong></a> None<br />
3558N/A <a href="directive-dict.html#Context"
3864N/A rel="Help"><strong>Context:</strong></a> server config, virtual
3558N/A host<br />
3558N/A <a href="directive-dict.html#Status"
3864N/A rel="Help"><strong>Status:</strong></a> Extension<br />
3558N/A <a href="directive-dict.html#Module"
3558N/A rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br />
3864N/A <a href="directive-dict.html#Compatibility"
3558N/A rel="Help"><strong>Compatibility:</strong></a>
3747N/A VirtualDocumentRootIP is only available in 1.3.7 and later.</p>
3747N/A
3747N/A <p>The <code>VirtualDocumentRootIP</code> directive is like the
3558N/A <a
3558N/A href="#virtualdocumentroot"><code>VirtualDocumentRoot</code></a>
3558N/A directive, except that it uses the IP address of the server end
3558N/A of the connection instead of the server name.</p>
3558N/A <hr />
3558N/A
3558N/A <h2><a id="virtualscriptalias"
3558N/A name="virtualscriptalias">VirtualScriptAlias directive</a></h2>
3558N/A
3558N/A <p><a href="directive-dict.html#Syntax"
4286N/A rel="Help"><strong>Syntax:</strong></a> VirtualScriptAlias
3558N/A <em>interpolated-directory</em><br />
3558N/A <a href="directive-dict.html#Default"
3747N/A rel="Help"><strong>Default:</strong></a> None<br />
3558N/A <a href="directive-dict.html#Context"
3558N/A rel="Help"><strong>Context:</strong></a> server config, virtual
3558N/A host<br />
3558N/A <a href="directive-dict.html#Status"
3558N/A rel="Help"><strong>Status:</strong></a> Extension<br />
3558N/A <a href="directive-dict.html#Module"
3750N/A rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br />
3750N/A <a href="directive-dict.html#Compatibility"
3750N/A rel="Help"><strong>Compatibility:</strong></a>
3558N/A VirtualScriptAlias is only available in 1.3.7 and later.</p>
3558N/A
3558N/A <p>The <code>VirtualScriptAlias</code> directive allows you to
3864N/A determine where Apache will find CGI scripts in a similar
3558N/A manner to <a
3558N/A href="#virtualdocumentroot"><code>VirtualDocumentRoot</code></a>
3558N/A does for other documents. It matches requests for URIs starting
4286N/A <code>/cgi-bin/</code>, much like <code><a
3558N/A href="mod_alias.html#scriptalias">ScriptAlias</a>
3558N/A /cgi-bin/</code> would.</p>
3750N/A <hr />
3750N/A
3750N/A <h2><a id="virtualscriptaliasip"
3558N/A name="virtualscriptaliasip">VirtualScriptAliasIP
3558N/A directive</a></h2>
3558N/A
3558N/A <p><a href="directive-dict.html#Syntax"
3558N/A rel="Help"><strong>Syntax:</strong></a> VirtualScriptAliasIP
3558N/A <em>interpolated-directory</em><br />
3558N/A <a href="directive-dict.html#Default"
4286N/A rel="Help"><strong>Default:</strong></a> None<br />
3558N/A <a href="directive-dict.html#Context"
3558N/A rel="Help"><strong>Context:</strong></a> server config, virtual
3558N/A host<br />
3558N/A <a href="directive-dict.html#Status"
3558N/A rel="Help"><strong>Status:</strong></a> Extension<br />
3558N/A <a href="directive-dict.html#Module"
3558N/A rel="Help"><strong>Module:</strong></a> mod_vhost_alias<br />
3558N/A <a href="directive-dict.html#Compatibility"
3558N/A rel="Help"><strong>Compatibility:</strong></a>
3558N/A VirtualScriptAliasIP is only available in 1.3.7 and later.</p>
3558N/A
3558N/A <p>The <code>VirtualScriptAliasIP</code> directive is like the
3558N/A <a
3750N/A href="#virtualscriptalias"><code>VirtualScriptAlias</code></a>
3750N/A directive, except that it uses the IP address of the server end
3750N/A of the connection instead of the server name.</p>
3558N/A <hr />
181N/A
3353N/A <h3 align="CENTER">Apache HTTP Server Version 1.3</h3>
3353N/A <a href="./"><img src="/images/index.gif" alt="Index" /></a>
4089N/A <a href="../"><img src="/images/home.gif" alt="Home" /></a>
3353N/A </body>
3205N/A</html>
3205N/A
4089N/A