0d26a2bd71224b954baab529bbadc4d676c35b95slive<!DOCTYPE modulesynopsis SYSTEM "/style/modulesynopsis.dtd">
e942c741056732f50da2074b36fe59805d370650slive<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
5f5d1b4cc970b7f06ff8ef6526128e9a27303d88nd<!-- $LastChangedRevision$ -->
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding Licensed to the Apache Software Foundation (ASF) under one or more
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding contributor license agreements. See the NOTICE file distributed with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding this work for additional information regarding copyright ownership.
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding The ASF licenses this file to You under the Apache License, Version 2.0
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding (the "License"); you may not use this file except in compliance with
db479b48bd4d75423ed4a45e15b75089d1a8ad72fielding the License. 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>
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedooh </highlight>
0dcb04cfa4202dd443d362f20db0de81faa2eb17nd<seealso><directive module="core">UseCanonicalName</directive></seealso>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<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>
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedoohUseCanonicalName Off
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedooh </highlight>
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>
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedoohUseCanonicalName Off
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRoot "/usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2"
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedooh </highlight>
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>
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRoot "/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>
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRoot "/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>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coar<p> A very common request by users is the ability to point multiple domains to multiple
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coardocument roots without having to worry about the length or number of parts of the
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedoohhostname being requested. If the requested hostname is <code>sub.www.domain.example.com</code>
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedooh instead of simply <code>www.domain.example.com</code>, then using %3+ will result in the document
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedoohroot being <code>/usr/local/apache/vhosts/domain.example.com/...</code> instead of the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarintended <code>example.com</code> directory. In such cases, it can be beneficial to use
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarthe combination <code>%-2.0.%-1.0</code>, which will always yield the domain name and the
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coartld, for example <code>example.com</code> regardless of the number of subdomains appended
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarto the hostname. As such, one can make a configuration that will direct all first, second
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedoohor third level subdomains to the same directory:
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRoot "/usr/local/apache/vhosts/%-2.0.%-1.0"
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedoohIn the example above, both <code>www.example.com</code> as well as <code>www.sub.example.com</code>
166443eb5bbb2dc3f6f0c41210c7a04a1ddf9e80humbedoohor <code>example.com</code> will all point to <code>/usr/local/apache/vhosts/example.com</code>.
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen <p>For IP-based virtual hosting you might use the following in
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen your configuration file:</p>
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedoohUseCanonicalName DNS
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRootIP "/usr/local/apache/vhosts/%1/%2/%3/%4/docs"
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualScriptAliasIP "/usr/local/apache/vhosts/%1/%2/%3/%4/cgi-bin"
6fcd2523fee8fb3aca9541dc7149de6048110a39humbedooh </highlight>
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>
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coarVirtualDocumentRoot "/usr/local/apache/vhosts/%2.0.%3.0"
c3c937a1510d6ff9cfa28ef3713e787f0e1a39c9coar </highlight>
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
2f46ce2a814d7f2b126dfb9f1b25fd64e2fbdc11rbowen determine where Apache HTTP Server 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
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim module="core">DocumentRoot</directive> directive's argument.
63ab8205d2d1e2e4b6e7e4f81adde8782a85ea9drbowen If <em>interpolated-directory</em> is <code>none</code> then
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim <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>
94cc3ddeb3f1a43f50a3b9dd9b30fca2f6135cfahumbedooh<directive>VirtualDocumentRoot</directive> will override any <directive
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarmodule="core">DocumentRoot</directive> directives you may have put in the same
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarcontext or child contexts. Putting a <directive>VirtualDocumentRoot</directive>
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarin the global server scope will effectively override <directive
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coarmodule="core">DocumentRoot</directive> directives in any virtual hosts defined later
5d01f40ffd657dd2ac567aacd93cabd162ddfa79coaron, unless you set <directive>VirtualDocumentRoot</directive> to <code>None</code>
94cc3ddeb3f1a43f50a3b9dd9b30fca2f6135cfahumbedoohin each virtual host.
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
2f46ce2a814d7f2b126dfb9f1b25fd64e2fbdc11rbowen determine where Apache httpd 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>
37e4418fe040292194081ed5e38beb1739b1900ehumbedooh<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>