mod_vhost_alias.html revision a4dcd1cff1835905106cf647a3c2e26009b5ff54
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<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>
</DIV>
<H1 ALIGN="CENTER">Module mod_vhost_alias</H1>
<P>
This module is contained in the <CODE>mod_vhost_alias.c</CODE> file
and is not compiled in by default. It should be mentioned near the
start of the <CODE>Configuration</CODE> file so that it doesn't
override the behaviour of other modules that do filename translation,
e.g. <A HREF="mod_userdir.html"><CODE>mod_userdir</CODE></A> and
<A HREF="mod_alias.html"><CODE>mod_alias</CODE></A>. It provides
support for <A HREF="/vhosts/mass.html">dynamically configured mass
virtual hosting</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:
<DL>
<DT><CODE>%%</CODE>
<DD>insert a <CODE>%</CODE>
<DT><CODE>%p</CODE>
<DD>insert the port number of the virtual host
<DT><CODE>%N.M</CODE>
<DD>insert (part of) the name
</DL>
</P>
<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:
<DL>
<DT><CODE>0</CODE>
<DD>the whole name
<DT><CODE>1</CODE>
<DD>the first part
<DT><CODE>2</CODE>
<DD>the second part
<DT><CODE>-1</CODE>
<DD>the last part
<DT><CODE>-2</CODE>
<DD>the penultimate part
<DT><CODE>2+</CODE>
<DD>the second and all subsequent parts
<DT><CODE>-2+</CODE>
<DD>the penultimate and all preceding parts
<DT><CODE>1+</CODE> and <CODE>-1+</CODE>
<DD>the same as <CODE>0</CODE>
</DL>
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:
<PRE>
UseCanonicalName Off
VirtualDocumentRoot /usr/local/apache/vhosts/%0
</PRE>
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:
<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/isp.com/e/x/a/example/directory/file.html</CODE>.
A more even spread of files can be acheived 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>
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:
<PRE>
UseCanonicalName DNS
VirtualDocumentRootIP /usr/local/apache/vhost/%1/%2/%3/%4/docs
VirtualScriptAliasIP /usr/local/apache/vhost/%1/%2/%3/%4/cgi-bin
</PRE>
A request for <CODE>http://www.example.isp.com/directory/file.html</CODE>
would be satisfied by the file
<CODE>/usr/local/apache/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/10/20/30/40/cgi-bin/script.pl</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>Directives</H2>
<UL>
<LI><A HREF="#VirtualDocumentRoot">VirtualDocumentRoot</A>
<LI><A HREF="#VirtualDocumentRootIP">VirtualDocumentRootIP</A>
<LI><A HREF="#VirtualScriptAlias">VirtualScriptAlias</A>
<LI><A HREF="#VirtualScriptAliasIP">VirtualScriptAliasIP</A>
</UL>
<HR>
<H2><A 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.5 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>VirtaulDocumentRoot</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 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.5 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 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.5 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 NAME="VirtualScriptAlias">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.5 and later.</P>
<P>
The <CODE>VirtualScriptAliasIP</CODE> directibe 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>