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