mod_vhost_alias.xml revision 1597043cec6ad37fa4154bf09b0fccdabed1a239
0d26a2bd71224b954baab529bbadc4d676c35b95slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
6fbd2e53c97ea6976d93e0ac521adabc55e0fb73nd Copyright 2002-2004 The Apache Software Foundation
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Licensed under the Apache License, Version 2.0 (the "License");
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd you may not use this file except in compliance with the License.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd You may obtain a copy of the License at
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd Unless required by applicable law or agreed to in writing, software
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd distributed under the License is distributed on an "AS IS" BASIS,
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd See the License for the specific language governing permissions and
d5d794fc2f4cc9ca6d6da17cfa2cdcd8d244bacdnd limitations under the License.
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslive<description>Provides for dynamically configured mass virtual
6eef889fc0b7cd42c4c8ca7e8e094dc2c0b030fcslivehosting</description>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>This module creates dynamically configured virtual hosts, by
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen allowing the IP address and/or the <code>Host:</code> header of
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen the HTTP request to be used as part of the pathname to
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen determine what files to serve. This allows for easy use of a
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen huge number of virtual hosts with similar configurations.</p>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd <p>If <module>mod_alias</module> or <module>mod_userdir</module> are
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd used for translating URIs to filenames, they will override the
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd directives of <module>mod_vhost_alias</module> described below. For
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd example, the following configuration will map <code>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd /usr/local/apache2/cgi-bin/script.pl</code> in all cases:</p>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd </example>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd<seealso><directive module="core">UseCanonicalName</directive></seealso>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd<seealso><a href="/vhosts/mass.html">Dynamically configured mass
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>All the directives in this module interpolate a string into
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen a pathname. The interpolated string (henceforth called the
115d4988233465895664ae2e19ba6c281281a00bnd "name") may be either the server name (see the <directive
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen directive for details on how this is determined) or the IP
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen address of the virtual host on the server in dotted-quad
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen format. The interpolation is controlled by specifiers inspired
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen by <code>printf</code> which have a number of formats:</p>
1597043cec6ad37fa4154bf09b0fccdabed1a239slive<columnspec><column width=".2"/><column width=".6"/></columnspec>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<td>insert the port number of the virtual host</td></tr>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p><code>N</code> and <code>M</code> are used to specify
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen substrings of the name. <code>N</code> selects from the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen dot-separated components of the name, and <code>M</code>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen selects characters within whatever <code>N</code> has selected.
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>M</code> is optional and defaults to zero if it isn't
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen present; the dot must be present if and only if <code>M</code>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen is present. The interpretation is as follows:</p>
1597043cec6ad37fa4154bf09b0fccdabed1a239slive <columnspec><column width=".1"/><column width=".4"/></columnspec>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <td>the penultimate and all preceding parts</td></tr>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>If <code>N</code> or <code>M</code> is greater than the number
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen of parts available a single underscore is interpolated. </p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>For simple name-based virtual hosts you might use the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen following directives in your server configuration file:</p>
115d4988233465895664ae2e19ba6c281281a00bnd UseCanonicalName Off<br />
115d4988233465895664ae2e19ba6c281281a00bnd </example>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>A request for
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>http://www.example.com/directory/file.html</code> will be
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen satisfied by the file
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>/usr/local/apache/vhosts/www.example.com/directory/file.html</code>.
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>For a very large number of virtual hosts it is a good idea
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen to arrange the files to reduce the size of the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>vhosts</code> directory. To do this you might use the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen following in your configuration file:</p>
115d4988233465895664ae2e19ba6c281281a00bnd UseCanonicalName Off<br />
115d4988233465895664ae2e19ba6c281281a00bnd VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2
115d4988233465895664ae2e19ba6c281281a00bnd </example>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>A request for
115d4988233465895664ae2e19ba6c281281a00bnd <code>http://www.domain.example.com/directory/file.html</code>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen will be satisfied by the file
115d4988233465895664ae2e19ba6c281281a00bnd <code>/usr/local/apache/vhosts/example.com/d/o/m/domain/directory/file.html</code>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>A more even spread of files can be achieved by hashing from the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen end of the name, for example: </p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.-1/%2.-2/%2.-3/%2
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>The example request would come from
115d4988233465895664ae2e19ba6c281281a00bnd <code>/usr/local/apache/vhosts/example.com/n/i/a/domain/directory/file.html</code>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>The example request would come from
115d4988233465895664ae2e19ba6c281281a00bnd <code>/usr/local/apache/vhosts/example.com/d/o/m/ain/directory/file.html</code>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>For IP-based virtual hosting you might use the following in
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen your configuration file:</p>
115d4988233465895664ae2e19ba6c281281a00bnd UseCanonicalName DNS<br />
115d4988233465895664ae2e19ba6c281281a00bnd VirtualDocumentRootIP /usr/local/apache/vhosts/%1/%2/%3/%4/docs<br />
115d4988233465895664ae2e19ba6c281281a00bnd VirtualScriptAliasIP /usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin
115d4988233465895664ae2e19ba6c281281a00bnd </example>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>A request for
115d4988233465895664ae2e19ba6c281281a00bnd <code>http://www.domain.example.com/directory/file.html</code>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen would be satisfied by the file
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>/usr/local/apache/vhosts/10/20/30/40/docs/directory/file.html</code>
115d4988233465895664ae2e19ba6c281281a00bnd if the IP address of <code>www.domain.example.com</code> were
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen 10.20.30.40. A request for
115d4988233465895664ae2e19ba6c281281a00bnd <code>http://www.domain.example.com/cgi-bin/script.pl</code> would
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen be satisfied by executing the program
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>/usr/local/apache/vhosts/10/20/30/40/cgi-bin/script.pl</code>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>If you want to include the <code>.</code> character in a
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <code>VirtualDocumentRoot</code> directive, but it clashes with
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen a <code>%</code> directive, you can work around the problem in
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen the following way:</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen VirtualDocumentRoot /usr/local/apache/vhosts/%2.0.%3.0
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>A request for
115d4988233465895664ae2e19ba6c281281a00bnd <code>http://www.domain.example.com/directory/file.html</code>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen will be satisfied by the file
115d4988233465895664ae2e19ba6c281281a00bnd <code>/usr/local/apache/vhosts/domain.example/directory/file.html</code>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>The <directive module="mod_log_config">LogFormat</directive>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen directives <code>%V</code> and <code>%A</code> are useful
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen in conjunction with this module.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<directivesynopsis>
0d26a2bd71224b954baab529bbadc4d676c35b95slive<description>Dynamically configure the location of the document root
0d26a2bd71224b954baab529bbadc4d676c35b95slivefor a given virtual host</description>
115d4988233465895664ae2e19ba6c281281a00bnd<syntax>VirtualDocumentRoot <em>interpolated-directory</em>|none</syntax>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<contextlist>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</contextlist>
115d4988233465895664ae2e19ba6c281281a00bnd <p>The <directive>VirtualDocumentRoot</directive> directive allows you to
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen determine where Apache will find your documents based on the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen value of the server name. The result of expanding
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <em>interpolated-directory</em> is used as the root of the
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen document tree in a similar manner to the <directive
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen module="core">DocumentRoot</directive> directive's argument.
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen If <em>interpolated-directory</em> is <code>none</code> then
115d4988233465895664ae2e19ba6c281281a00bnd <directive>VirtualDocumentRoot</directive> is turned off. This directive
115d4988233465895664ae2e19ba6c281281a00bnd cannot be used in the same context as <directive
115d4988233465895664ae2e19ba6c281281a00bnd module="mod_vhost_alias">VirtualDocumentRootIP</directive>.</p>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</directivesynopsis>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<directivesynopsis>
0d26a2bd71224b954baab529bbadc4d676c35b95slive<description>Dynamically configure the location of the document root
0d26a2bd71224b954baab529bbadc4d676c35b95slivefor a given virtual host</description>
115d4988233465895664ae2e19ba6c281281a00bnd<syntax>VirtualDocumentRootIP <em>interpolated-directory</em>|none</syntax>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<contextlist>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</contextlist>
115d4988233465895664ae2e19ba6c281281a00bnd<p>The <directive>VirtualDocumentRootIP</directive> directive is like the
115d4988233465895664ae2e19ba6c281281a00bnd <directive module="mod_vhost_alias">VirtualDocumentRoot</directive>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen directive, except that it uses the IP address of the server end
115d4988233465895664ae2e19ba6c281281a00bnd of the connection for directory interpolation instead of the server
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</directivesynopsis>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<directivesynopsis>
0d26a2bd71224b954baab529bbadc4d676c35b95slive<description>Dynamically configure the location of the CGI directory for
0d26a2bd71224b954baab529bbadc4d676c35b95slivea given virtual host</description>
115d4988233465895664ae2e19ba6c281281a00bnd<syntax>VirtualScriptAlias <em>interpolated-directory</em>|none</syntax>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<contextlist>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</contextlist>
115d4988233465895664ae2e19ba6c281281a00bnd <p>The <directive>VirtualScriptAlias</directive> directive allows you to
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen determine where Apache will find CGI scripts in a similar
115d4988233465895664ae2e19ba6c281281a00bnd >VirtualDocumentRoot</directive> does for other documents. It matches
115d4988233465895664ae2e19ba6c281281a00bnd requests for URIs starting <code>/cgi-bin/</code>, much like <directive
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</directivesynopsis>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<directivesynopsis>
0d26a2bd71224b954baab529bbadc4d676c35b95slive<description>Dynamically configure the location of the cgi directory for
0d26a2bd71224b954baab529bbadc4d676c35b95slivea given virtual host</description>
115d4988233465895664ae2e19ba6c281281a00bnd<syntax>VirtualScriptAliasIP <em>interpolated-directory</em>|none</syntax>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen<contextlist>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</contextlist>
115d4988233465895664ae2e19ba6c281281a00bnd <p>The <directive>VirtualScriptAliasIP</directive> directive is like the
115d4988233465895664ae2e19ba6c281281a00bnd <directive module="mod_vhost_alias">VirtualScriptAlias</directive>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen directive, except that it uses the IP address of the server end
115d4988233465895664ae2e19ba6c281281a00bnd of the connection for directory interpolation instead of the server
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</directivesynopsis>
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen</modulesynopsis>