+++ /dev/null
-<!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>An In-Depth Discussion of Virtual Host Matching</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">An In-Depth Discussion of Virtual Host
- Matching</h1>
-
- <p>The virtual host code was completely rewritten in
- <strong>Apache 1.3</strong>. This document attempts to explain
- exactly what Apache does when deciding what virtual host to
- serve a hit from. With the help of the new <a
- href="../mod/core.html#namevirtualhost"><samp>NameVirtualHost</samp></a>
- directive virtual host configuration should be a lot easier and
- safer than with versions prior to 1.3.</p>
-
- <p>If you just want to <cite>make it work</cite> without
- understanding how, here are <a href="examples.html">some
- examples</a>.</p>
-
- <h3>Config File Parsing</h3>
-
- <p>There is a <em>main_server</em> which consists of all the
- definitions appearing outside of
- <code><VirtualHost></code> sections. There are virtual
- servers, called <em>vhosts</em>, which are defined by <a
- href="../mod/core.html#virtualhost"><samp><VirtualHost></samp></a>
- sections.</p>
-
- <p>The directives <a
- href="../mod/mpm_common.html#listen"><samp>Listen</samp></a>, <a
- href="../mod/core.html#servername"><samp>ServerName</samp></a>,
- <a
- href="../mod/core.html#serverpath"><samp>ServerPath</samp></a>,
- and <a
- href="../mod/core.html#serveralias"><samp>ServerAlias</samp></a>
- can appear anywhere within the definition of a server. However,
- each appearance overrides the previous appearance (within that
- server).</p>
-
- <p>The default value of the <code>Listen</code> field for
- main_server is 80. The main_server has no default
- <code>ServerPath</code>, or <code>ServerAlias</code>. The
- default <code>ServerName</code> is deduced from the servers IP
- address.</p>
-
- <p>The main_server Listen directive has two functions. One
- function is to determine the default network port Apache will
- bind to. The second function is to specify the port number
- which is used in absolute URIs during redirects.</p>
-
- <p>Unlike the main_server, vhost ports <em>do not</em> affect
- what ports Apache listens for connections on.</p>
-
- <p>Each address appearing in the <code>VirtualHost</code>
- directive can have an optional port. If the port is unspecified
- it defaults to the value of the main_server's most recent
- <code>Listen</code> statement. The special port <samp>*</samp>
- indicates a wildcard that matches any port. Collectively the
- entire set of addresses (including multiple <samp>A</samp>
- record results from DNS lookups) are called the vhost's
- <em>address set</em>.</p>
-
- <p>Unless a <a
- href="../mod/core.html#namevirtualhost">NameVirtualHost</a>
- directive is used for a specific IP address the first vhost
- with that address is treated as an IP-based vhost. The IP
- address can also be the wildcard <code>*</code>.</p>
-
- <p>If name-based vhosts should be used a
- <code>NameVirtualHost</code> directive <em>must</em> appear
- with the IP address set to be used for the name-based vhosts.
- In other words, you must specify the IP address that holds the
- hostname aliases (CNAMEs) for your name-based vhosts via a
- <code>NameVirtualHost</code> directive in your configuration
- file.</p>
-
- <p>Multiple <code>NameVirtualHost</code> directives can be used
- each with a set of <code>VirtualHost</code> directives but only
- one <code>NameVirtualHost</code> directive should be used for
- each specific IP:port pair.</p>
-
- <p>The ordering of <code>NameVirtualHost</code> and
- <code>VirtualHost</code> directives is not important which
- makes the following two examples identical (only the order of
- the <code>VirtualHost</code> directives for <em>one</em>
- address set is important, see below):</p>
-<pre>
- |
- NameVirtualHost 111.22.33.44 | <VirtualHost 111.22.33.44>
- <VirtualHost 111.22.33.44> | # server A
- # server A | </VirtualHost>
- ... | <VirtualHost 111.22.33.55>
- </VirtualHost> | # server C
- <VirtualHost 111.22.33.44> | ...
- # server B | </VirtualHost>
- ... | <VirtualHost 111.22.33.44>
- </VirtualHost> | # server B
- | ...
- NameVirtualHost 111.22.33.55 | </VirtualHost>
- <VirtualHost 111.22.33.55> | <VirtualHost 111.22.33.55>
- # server C | # server D
- ... | ...
- </VirtualHost> | </VirtualHost>
- <VirtualHost 111.22.33.55> |
- # server D | NameVirtualHost 111.22.33.44
- ... | NameVirtualHost 111.22.33.55
- </VirtualHost> |
- |
-</pre>
-
- <p>(To aid the readability of your configuration you should
- prefer the left variant.)</p>
-
- <p>After parsing the <code>VirtualHost</code> directive, the
- vhost server is given a default <code>Listen</code> equal to the
- port assigned to the first name in its <code>VirtualHost</code>
- directive.</p>
-
- <p>The complete list of names in the <code>VirtualHost</code>
- directive are treated just like a <code>ServerAlias</code> (but
- are not overridden by any <code>ServerAlias</code> statement)
- if all names resolve to the same address set. Note that
- subsequent <code>Listen</code> statements for this vhost will not
- affect the ports assigned in the address set.</p>
-
- <p>During initialization a list for each IP address is
- generated and inserted into an hash table. If the IP address is
- used in a <code>NameVirtualHost</code> directive the list
- contains all name-based vhosts for the given IP address. If
- there are no vhosts defined for that address the
- <code>NameVirtualHost</code> directive is ignored and an error
- is logged. For an IP-based vhost the list in the hash table is
- empty.</p>
-
- <p>Due to a fast hashing function the overhead of hashing an IP
- address during a request is minimal and almost not existent.
- Additionally the table is optimized for IP addresses which vary
- in the last octet.</p>
-
- <p>For every vhost various default values are set. In
- particular:</p>
-
- <ol>
- <li>If a vhost has no <a
- href="../mod/core.html#serveradmin"><code>ServerAdmin</code></a>,
- <a
- href="../mod/core.html#resourceconfig"><code>ResourceConfig</code></a>,
- <a
- href="../mod/core.html#accessconfig"><code>AccessConfig</code></a>,
- <a href="../mod/core.html#timeout"><code>Timeout</code></a>,
- <a
- href="../mod/core.html#keepalivetimeout"><code>KeepAliveTimeout</code></a>,
- <a
- href="../mod/core.html#keepalive"><code>KeepAlive</code></a>,
- <a
- href="../mod/core.html#maxkeepaliverequests"><code>MaxKeepAliveRequests</code></a>,
- or <a
- href="../mod/core.html#sendbuffersize"><code>SendBufferSize</code></a>
- directive then the respective value is inherited from the
- main_server. (That is, inherited from whatever the final
- setting of that value is in the main_server.)</li>
-
- <li>The "lookup defaults" that define the default directory
- permissions for a vhost are merged with those of the
- main_server. This includes any per-directory configuration
- information for any module.</li>
-
- <li>The per-server configs for each module from the
- main_server are merged into the vhost server.</li>
- </ol>
- Essentially, the main_server is treated as "defaults" or a
- "base" on which to build each vhost. But the positioning of
- these main_server definitions in the config file is largely
- irrelevant -- the entire config of the main_server has been
- parsed when this final merging occurs. So even if a main_server
- definition appears after a vhost definition it might affect the
- vhost definition.
-
- <p>If the main_server has no <code>ServerName</code> at this
- point, then the hostname of the machine that httpd is running
- on is used instead. We will call the <em>main_server address
- set</em> those IP addresses returned by a DNS lookup on the
- <code>ServerName</code> of the main_server.</p>
-
- <p>For any undefined <code>ServerName</code> fields, a
- name-based vhost defaults to the address given first in the
- <code>VirtualHost</code> statement defining the vhost.</p>
-
- <p>Any vhost that includes the magic <samp>_default_</samp>
- wildcard is given the same <code>ServerName</code> as the
- main_server.</p>
-
- <h3>Virtual Host Matching</h3>
-
- <p>The server determines which vhost to use for a request as
- follows:</p>
-
- <h4>Hash table lookup</h4>
-
- <p>When the connection is first made by a client, the IP
- address to which the client connected is looked up in the
- internal IP hash table.</p>
-
- <p>If the lookup fails (the IP address wasn't found) the
- request is served from the <samp>_default_</samp> vhost if
- there is such a vhost for the port to which the client sent the
- request. If there is no matching <samp>_default_</samp> vhost
- the request is served from the main_server.</p>
-
- <p>If the IP address is not found in the hash table then the
- match against the port number may also result in an entry
- corresponding to a <code>NameVirtualHost *</code>, which is
- subsequently handled like other name-based vhosts.</p>
-
- <p>If the lookup succeeded (a corresponding list for the IP
- address was found) the next step is to decide if we have to
- deal with an IP-based or a name-base vhost.</p>
-
- <h4>IP-based vhost</h4>
-
- <p>If the entry we found has an empty name list then we have
- found an IP-based vhost, no further actions are performed and
- the request is served from that vhost.</p>
-
- <h4>Name-based vhost</h4>
-
- <p>If the entry corresponds to a name-based vhost the name list
- contains one or more vhost structures. This list contains the
- vhosts in the same order as the <code>VirtualHost</code>
- directives appear in the config file.</p>
-
- <p>The first vhost on this list (the first vhost in the config
- file with the specified IP address) has the highest priority
- and catches any request to an unknown server name or a request
- without a <code>Host:</code> header field.</p>
-
- <p>If the client provided a <code>Host:</code> header field the
- list is searched for a matching vhost and the first hit on a
- <code>ServerName</code> or <code>ServerAlias</code> is taken
- and the request is served from that vhost. A <code>Host:</code>
- header field can contain a port number, but Apache always
- matches against the real port to which the client sent the
- request.</p>
-
- <p>If the client submitted a HTTP/1.0 request without
- <code>Host:</code> header field we don't know to what server
- the client tried to connect and any existing
- <code>ServerPath</code> is matched against the URI from the
- request. The first matching path on the list is used and the
- request is served from that vhost.</p>
-
- <p>If no matching vhost could be found the request is served
- from the first vhost with a matching port number that is on the
- list for the IP to which the client connected (as already
- mentioned before).</p>
-
- <h4>Persistent connections</h4>
- The IP lookup described above is only done <em>once</em> for a
- particular TCP/IP session while the name lookup is done on
- <em>every</em> request during a KeepAlive/persistent
- connection. In other words a client may request pages from
- different name-based vhosts during a single persistent
- connection.
-
- <h4>Absolute URI</h4>
-
- <p>If the URI from the request is an absolute URI, and its
- hostname and port match the main server or one of the
- configured virtual hosts <em>and</em> match the address and
- port to which the client sent the request, then the
- scheme/hostname/port prefix is stripped off and the remaining
- relative URI is served by the corresponding main server or
- virtual host. If it does not match, then the URI remains
- untouched and the request is taken to be a proxy request.</p>
-
- <h3>Observations</h3>
-
- <ul>
- <li>A name-based vhost can never interfere with an IP-base
- vhost and vice versa. IP-based vhosts can only be reached
- through an IP address of its own address set and never
- through any other address. The same applies to name-based
- vhosts, they can only be reached through an IP address of the
- corresponding address set which must be defined with a
- <code>NameVirtualHost</code> directive.</li>
-
- <li><code>ServerAlias</code> and <code>ServerPath</code>
- checks are never performed for an IP-based vhost.</li>
-
- <li>The order of name-/IP-based, the <samp>_default_</samp>
- vhost and the <code>NameVirtualHost</code> directive within
- the config file is not important. Only the ordering of
- name-based vhosts for a specific address set is significant.
- The one name-based vhosts that comes first in the
- configuration file has the highest priority for its
- corresponding address set.</li>
-
- <li>For security reasons the port number given in a
- <code>Host:</code> header field is never used during the
- matching process. Apache always uses the real port to which
- the client sent the request.</li>
-
- <li>If a <code>ServerPath</code> directive exists which is a
- prefix of another <code>ServerPath</code> directive that
- appears later in the configuration file, then the former will
- always be matched and the latter will never be matched. (That
- is assuming that no <code>Host:</code> header field was
- available to disambiguate the two.)</li>
-
- <li>If two IP-based vhosts have an address in common, the
- vhost appearing first in the config file is always matched.
- Such a thing might happen inadvertently. The server will give
- a warning in the error logfile when it detects this.</li>
-
- <li>A <code>_default_</code> vhost catches a request only if
- there is no other vhost with a matching IP address
- <em>and</em> a matching port number for the request. The
- request is only caught if the port number to which the client
- sent the request matches the port number of your
- <code>_default_</code> vhost which is your standard
- <code>Listen</code> by default. A wildcard port can be
- specified (<em>i.e.</em>, <code>_default_:*</code>) to catch
- requests to any available port. This also applies to
- <code>NameVirtualHost *</code> vhosts.</li>
-
- <li>The main_server is only used to serve a request if the IP
- address and port number to which the client connected is
- unspecified and does not match any other vhost (including a
- <code>_default_</code> vhost). In other words the main_server
- only catches a request for an unspecified address/port
- combination (unless there is a <code>_default_</code> vhost
- which matches that port).</li>
-
- <li>A <code>_default_</code> vhost or the main_server is
- <em>never</em> matched for a request with an unknown or
- missing <code>Host:</code> header field if the client
- connected to an address (and port) which is used for
- name-based vhosts, <em>e.g.</em>, in a
- <code>NameVirtualHost</code> directive.</li>
-
- <li>You should never specify DNS names in
- <code>VirtualHost</code> directives because it will force
- your server to rely on DNS to boot. Furthermore it poses a
- security threat if you do not control the DNS for all the
- domains listed. There's <a href="../dns-caveats.html">more
- information</a> available on this and the next two
- topics.</li>
-
- <li><code>ServerName</code> should always be set for each
- vhost. Otherwise A DNS lookup is required for each
- vhost.</li>
- </ul>
-
- <h3>Tips</h3>
-
- <p>In addition to the tips on the <a
- href="../dns-caveats.html#tips">DNS Issues</a> page, here are
- some further tips:</p>
-
- <ul>
- <li>Place all main_server definitions before any
- <code>VirtualHost</code> definitions. (This is to aid the
- readability of the configuration -- the post-config merging
- process makes it non-obvious that definitions mixed in around
- virtual hosts might affect all virtual hosts.)</li>
-
- <li>Group corresponding <code>NameVirtualHost</code> and
- <code>VirtualHost</code> definitions in your configuration to
- ensure better readability.</li>
-
- <li>Avoid <code>ServerPaths</code> which are prefixes of
- other <code>ServerPaths</code>. If you cannot avoid this then
- you have to ensure that the longer (more specific) prefix
- vhost appears earlier in the configuration file than the
- shorter (less specific) prefix (<em>i.e.</em>, "ServerPath
- /abc" should appear after "ServerPath /abc/def").</li>
- </ul>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!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>VirtualHost Examples</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF" vlink="#000080"
- alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Virtual Host examples for common setups</h1>
-
- <p>This document attempts to answer the commonly-asked questions about
- setting up virtual hosts. These scenarios are those involving multiple
- web sites running on a single server, via <a
- href="name-based.html">name-based</a> or <a
- href="ip-based.html">IP-based</a> virtual hosts. A document should be
- coming soon about running sites on several servers behind a single
- proxy server.</p>
-
- <h2>Examples</h2>
-
- <ul>
- <li><a href="#purename">Running several name-based web sites on
- a single IP address.</a></li>
-
- <li><a href="#twoips">Name-based hosts on more than one IP
- address.</a></li>
-
- <li><a href="#intraextra">Serving the same content on different IP
- addresses (such as an internal and external address).</a></li>
-
- <li><a href="#port">Running different sites on different
- ports.</a></li>
-
- <li><a href="#ip">IP-based virtual hosting</a></li>
-
- <li><a href="#ipport">Mixed port-based and ip-based virtual
- hosts</a></li>
-
- <li><a href="#mixed">Mixed name-based and IP-based vhosts</a></li>
- </ul>
-
-<!--
-<h2>Common problems</h2>
-<ul>
-<li>mixing * ports and non-* ports with a NameVirtualHost address
-is not supported, proceeding with undefined results</li>
-<li>No matter what hostname I use, I'm getting the main server (or
-first vhost)</li>
-<li>I'm trying to use SSL on my virtual host, and I'm getting the
-wrong site</li>
-</ul>
--->
-
- <h2>Additional features</h2>
-
- <ul>
- <li><a href="#default">Using <code>_default_</code> vhosts</a></li>
-
- <li><a href="#migrate">Migrating a named-based vhost to an IP-based
- vhost</a></li>
-
- <li><a href="#serverpath">Using the <code>ServerPath</code>
- directive</a></li>
- </ul>
- <hr />
-
- <h3><a id="purename" name="purename">Running several name-based web
- sites on a single IP address.</a></h3>
-
- <a id="name" name="name"><!-- Anchor for backward compatibility with
- the previous version of this document. However, using * rather than
- the IP address will always work in a single-IP-address scenario, and
- tends to confuse people a little less anyways. --></a>
-
- <p><strong>Setup:</strong></p>
-
- <p>Your server has a single IP address, and multiple aliases (CNAMES)
- point to this machine in DNS. You want to run a web server for
- <samp>www.example1.com</samp> and <samp>www.example2.org</samp> on this
- machine.</p>
-
- <blockquote>
- <table>
- <tr>
- <td bgcolor="#e0e5f5"><strong>Note:</strong> Creating virtual
- host configurations on your Apache server does not magically
- cause DNS entries to be created for those host names. You
- <em>must</em> have the names in DNS, resolving to your IP
- address, or nobody else will be able to see your web site. You
- can put entries in your <samp>hosts</samp> file for local
- testing, but that will work only from the machine with those
- hosts entries.</td>
- </tr>
- </table>
- </blockquote>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- # Ensure that Apache listens on port 80
- Listen 80
-
- # Listen for virtual host requests on all IP addresses
- NameVirtualHost *
-
- <VirtualHost *>
- DocumentRoot /www/example1
- ServerName www.example1.com
-
- # Other directives here
-
- </VirtualHost>
-
- <VirtualHost *>
- DocumentRoot /www/example2
- ServerName www.example2.org
-
- # Other directives here
-
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>The asterisks match all addresses, so the main server serves no
- requests. Due to the fact that <samp>www.example1.com</samp> is first
- in the configuration file, it has the highest priority and can be seen
- as the <cite>default</cite> or <cite>primary</cite> server. That means
- that if a request is received that does not match one of the specified
- <samp>ServerName</samp> directives, it will be served by this first
- <samp>VirtualHost</samp>.</p>
-
- <blockquote>
- <table>
- <tr>
- <td bgcolor="#e0e5f5">
- <strong>Note:</strong>
-
- <p>You can, if you wish, replace <code>*</code> with the actual
- IP address of the system. In that case, the argument to
- <code>VirtualHost</code> <em>must</em> match the argument to
- <code>NameVirtualHost</code>:</p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- NameVirtualHost 172.20.30.40
-
- <VirtualHost 172.20.30.40>
- # etc ...
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>However, it is additionally useful to use <code>*</code>
- on systems where the IP address is not predictable - for
- example if you have a dynamic IP address with your ISP, and
- you are using some variety of dynamic DNS solution. Since
- <code>*</code> matches any IP address, this configuration
- would work without changes whenever your IP address
- changes.</p>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>The above configuration is what you will want to use in almost
- all name-based virtual hosting situations. The only think that this
- configuration will not work for, in fact, is when you are serving
- different content based on differing IP addresses or ports.</p>
-
- <hr />
-
- <h3><a id="twoips" name="twoips">Name-based hosts on more than one
- IP address.</a></h3>
-
- <blockquote>
- <table>
- <tr>
- <td bgcolor="#e0e5f5"><strong>Note:</strong> Any of the
- techniques discussed here can be extended to any number of IP
- addresses.</td>
- </tr>
- </table>
- </blockquote>
- <strong>Setup 1:</strong>
-
- <p>The server has two IP addresses. On one (<samp>172.20.30.40</samp>), we
- will serve the "main" server, <samp>server.domain.com</samp> and on the
- other (<samp>172.20.30.50</samp>), we will serve two or more virtual hosts.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 80
-
- # This is the "main" server running on 172.20.30.40
- ServerName server.domain.com
- DocumentRoot /www/mainserver
-
- # This is the other address
- NameVirtualHost 172.20.30.50
-
- <VirtualHost 172.20.30.50>
- DocumentRoot /www/example1
- ServerName www.example1.com
-
- # Other directives here ...
-
- </VirtualHost>
-
- <VirtualHost 172.20.30.50>
- DocumentRoot /www/example2
- ServerName www.example2.org
-
- # Other directives here ...
-
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>Any request to an address other than <samp>172.20.30.50</samp> will be
- served from the main server. A request to <samp>172.20.30.50</samp> with an
- unknown hostname, or no <code>Host:</code> header, will be served from
- <samp>www.example1.com</samp>.</p>
-
- <h3><a id="intraextra" name="intraextra">Serving the same content on
- different IP addresses (such as an internal and external
- address).</a></h3>
-
- <strong>Setup:</strong>
-
- <p>The server machine has two IP addresses (<samp>192.168.1.1</samp>
- and <samp>172.20.30.40</samp>). The machine is sitting between an
- internal (intranet) network and an external (internet) network. Outside
- of the network, the name <samp>server.example.com</samp> resolves to
- the external address (<samp>172.20.30.40</samp>), but inside the
- network, that same name resolves to the internal address
- (<samp>192.168.1.1</samp>).</p>
-
- <p>The server can be made to respond to internal and external requests
- with the same content, with just one <code>VirtualHost</code>
- section.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- NameVirtualHost 192.168.1.1
- NameVirtualHost 172.20.30.40
-
- <VirtualHost 192.168.1.1 172.20.30.40>
- DocumentRoot /www/server1
- ServerName server.example.com
- ServerAlias server
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>Now requests from both networks will be served from the same
- <code>VirtualHost</code>.</p>
-
- <blockquote>
- <table>
- <tr>
- <td bgcolor="#e0e5f5">
-
- <p><strong>Note:</strong> On the internal
- network, one can just use the name <code>server</code> rather
- than the fully qualified host name
- <code>server.example.com</code>.</p>
-
- <p>Note also that, in the above example, you can replace the list
- of IP addresses with <code>*</code>, which will cause the server to
- respond the same on all addresses.</p>
-
- </td>
- </tr>
- </table>
- </blockquote>
- <hr />
-
- <h3><a id="port" name="port">Running different sites on different
- ports.</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>You have multiple domains going to the same IP and also want to
- serve multiple ports. By defining the ports in the "NameVirtualHost"
- tag, you can allow this to work. If you try using <VirtualHost
- name:port> without the NameVirtualHost name:port or you try to use
- the Listen directive, your configuration will not work.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 80
- Listen 8080
-
- NameVirtualHost 172.20.30.40:80
- NameVirtualHost 172.20.30.40:8080
-
- <VirtualHost 172.20.30.40:80>
- ServerName www.example1.com
- DocumentRoot /www/domain-80
- </VirtualHost>
-
- <VirtualHost 172.20.30.40:8080>
- ServerName www.example1.com
- DocumentRoot /www/domain-8080
- </VirtualHost>
-
- <VirtualHost 172.20.30.40:80>
- ServerName www.example2.org
- DocumentRoot /www/otherdomain-80
- </VirtualHost>
-
- <VirtualHost 172.20.30.40:8080>
- ServerName www.example2.org
- DocumentRoot /www/otherdomain-8080
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
- <hr />
-
- <h3><a id="ip" name="ip">IP-based virtual hosting</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>The server has two IP addresses (<samp>172.20.30.40</samp> and
- <samp>172.20.30.50</samp>) which resolve to the names
- <samp>www.example1.com</samp> and <samp>www.example2.org</samp>
- respectively.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 80
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/example1
- ServerName www.example1.com
- </VirtualHost>
-
- <VirtualHost 172.20.30.50>
- DocumentRoot /www/example2
- ServerName www.example2.org
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>Requests for any address not specified in one of the
- <samp><VirtualHost></samp> directives (such as
- <samp>localhost</samp>, for example) will go to the main server, if
- there is one.</p>
- <hr />
-
- <h3><a id="ipport" name="ipport">Mixed port-based and ip-based
- virtual hosts</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>The server machine has two IP addresses (<samp>172.20.30.40</samp> and
- <samp>172.20.30.50</samp>) which resolve to the names
- <samp>www.example1.com</samp> and <samp>www.example2.org</samp>
- respectively. In each case, we want to run hosts on ports 80 and
- 8080.</p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 172.20.30.40:80
- Listen 172.20.30.40:8080
- Listen 172.20.30.50:80
- Listen 172.20.30.50:8080
-
- <VirtualHost 172.20.30.40:80>
- DocumentRoot /www/example1-80
- ServerName www.example1.com
- </VirtualHost>
-
- <VirtualHost 172.20.30.40:8080>
- DocumentRoot /www/example1-8080
- ServerName www.example1.com
- </VirtualHost>
-
- <VirtualHost 172.20.30.50:80>
- DocumentRoot /www/example2-80
- ServerName www.example1.org
- </VirtualHost>
-
- <VirtualHost 172.20.30.50:8080>
- DocumentRoot /www/example2-8080
- ServerName www.example2.org
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
- <hr />
-
- <h3><a id="mixed" name="mixed">Mixed name-based and IP-based
- vhosts</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>On some of my addresses, I want to do name-based virtual hosts, and
- on others, IP-based hosts.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 80
-
- NameVirtualHost 172.20.30.40
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/example1
- ServerName www.example1.com
- </VirtualHost>
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/example2
- ServerName www.example2.org
- </VirtualHost>
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/example3
- ServerName www.example3.net
- </VirtualHost>
-
- # IP-based
- <VirtualHost 172.20.30.50>
- DocumentRoot /www/example4
- ServerName www.example4.edu
- </VirtualHost>
-
- <VirtualHost 172.20.30.60>
- DocumentRoot /www/example5
- ServerName www.example5.gov
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
- <hr />
-
- <h3><a id="default" name="default">Using <code>_default_</code>
- vhosts</a></h3>
-
- <p><strong>Setup 1:</strong></p>
-
- <p>Catching <em>every</em> request to any unspecified IP address and
- port, <em>i.e.</em>, an address/port combination that is not used for
- any other virtual host.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- <VirtualHost _default_:*>
- DocumentRoot /www/default
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>Using such a default vhost with a wildcard port effectively prevents
- any request going to the main server.</p>
-
- <p>A default vhost never serves a request that was sent to an
- address/port that is used for name-based vhosts. If the request
- contained an unknown or no <code>Host:</code> header it is always
- served from the primary name-based vhost (the vhost for that
- address/port appearing first in the configuration file).</p>
-
- <p>You can use <a
- href="../mod/mod_alias.html#aliasmatch"><code>AliasMatch</code></a> or
- <a
- href="../mod/mod_rewrite.html#RewriteRule"><code>RewriteRule</code></a>
- to rewrite any request to a single information page (or script).</p>
-
- <p><strong>Setup 2:</strong></p>
-
- <p>Same as setup 1, but the server listens on several ports and we want
- to use a second <code>_default_</code> vhost for port 80.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- <VirtualHost _default_:80>
- DocumentRoot /www/default80
- # ...
- </VirtualHost>
-
- <VirtualHost _default_:*>
- DocumentRoot /www/default
- # ...
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>The default vhost for port 80 (which <em>must</em> appear before any
- default vhost with a wildcard port) catches all requests that were sent
- to an unspecified IP address. The main server is never used to serve a
- request.</p>
-
- <p><strong>Setup 3:</strong></p>
-
- <p>We want to have a default vhost for port 80, but no other default
- vhosts.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- <VirtualHost _default_:80>
- DocumentRoot /www/default
- ...
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>A request to an unspecified address on port 80 is served from the
- default vhost any other request to an unspecified address and port is
- served from the main server.</p>
- <hr />
-
- <h3><a id="migrate" name="migrate">Migrating a name-based vhost to an
- IP-based vhost</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>The name-based vhost with the hostname
- <samp>www.example2.org</samp> (from our <a
- href="#name">name-based</a> example, setup 2) should get its own IP
- address. To avoid problems with name servers or proxies who cached the
- old IP address for the name-based vhost we want to provide both
- variants during a migration phase.<br />
- The solution is easy, because we can simply add the new IP address
- (<samp>172.20.30.50</samp>) to the <code>VirtualHost</code>
- directive.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- Listen 80
- ServerName www.example1.com
- DocumentRoot /www/example1
-
- NameVirtualHost 172.20.30.40
-
- <VirtualHost 172.20.30.40 172.20.30.50>
- DocumentRoot /www/example2
- ServerName www.example2.org
- # ...
- </VirtualHost>
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/example3
- ServerName www.example3.net
- ServerAlias *.example3.net
- # ...
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>The vhost can now be accessed through the new address (as an
- IP-based vhost) and through the old address (as a name-based
- vhost).</p>
- <hr />
-
- <h3><a id="serverpath" name="serverpath">Using the
- <code>ServerPath</code> directive</a></h3>
-
- <p><strong>Setup:</strong></p>
-
- <p>We have a server with two name-based vhosts. In order to match the
- correct virtual host a client must send the correct <code>Host:</code>
- header. Old HTTP/1.0 clients do not send such a header and Apache has
- no clue what vhost the client tried to reach (and serves the request
- from the primary vhost). To provide as much backward compatibility as
- possible we create a primary vhost which returns a single page
- containing links with an URL prefix to the name-based virtual
- hosts.</p>
-
- <p><strong>Server configuration:</strong></p>
-
- <blockquote>
- <table cellpadding="10">
- <tr>
- <td bgcolor="#eeeeee">
-<pre>
- NameVirtualHost 172.20.30.40
-
- <VirtualHost 172.20.30.40>
- # primary vhost
- DocumentRoot /www/subdomain
- RewriteEngine On
- RewriteRule ^/.* /www/subdomain/index.html
- # ...
- </VirtualHost>
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/subdomain/sub1
- ServerName www.sub1.domain.tld
- ServerPath /sub1/
- RewriteEngine On
- RewriteRule ^(/sub1/.*) /www/subdomain$1
- # ...
- </VirtualHost>
-
- <VirtualHost 172.20.30.40>
- DocumentRoot /www/subdomain/sub2
- ServerName www.sub2.domain.tld
- ServerPath /sub2/
- RewriteEngine On
- RewriteRule ^(/sub2/.*) /www/subdomain$1
- # ...
- </VirtualHost>
-</pre>
- </td>
- </tr>
- </table>
- </blockquote>
-
- <p>Due to the <a
- href="../mod/core.html#serverpath"><code>ServerPath</code></a>
- directive a request to the URL
- <samp>http://www.sub1.domain.tld/sub1/</samp> is <em>always</em> served
- from the sub1-vhost.<br />
- A request to the URL <samp>http://www.sub1.domain.tld/</samp> is only
- served from the sub1-vhost if the client sent a correct
- <code>Host:</code> header. If no <code>Host:</code> header is sent the
- client gets the information page from the primary host.<br />
- Please note that there is one oddity: A request to
- <samp>http://www.sub2.domain.tld/sub1/</samp> is also served from the
- sub1-vhost if the client sent no <code>Host:</code> header.<br />
- The <code>RewriteRule</code> directives are used to make sure that a
- client which sent a correct <code>Host:</code> header can use both URL
- variants, <em>i.e.</em>, with or without URL prefix.</p>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!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 IP-based Virtual Host Support</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Apache IP-based Virtual Host Support</h1>
- <strong>See also:</strong> <a href="name-based.html">Name-based
- Virtual Hosts Support</a>
- <hr />
-
- <h2>System requirements</h2>
- As the term <cite>IP-based</cite> indicates, the server
- <strong>must have a different IP address for each IP-based
- virtual host</strong>. This can be achieved by the machine
- having several physical network connections, or by use of
- virtual interfaces which are supported by most modern operating
- systems (see system documentation for details, these are
- frequently called "ip aliases", and the "ifconfig" command is
- most commonly used to set them up).
-
- <h2>How to set up Apache</h2>
- There are two ways of configuring apache to support multiple
- hosts. Either by running a separate httpd daemon for each
- hostname, or by running a single daemon which supports all the
- virtual hosts.
-
- <p>Use multiple daemons when:</p>
-
- <ul>
- <li>There are security partitioning issues, such as company1
- does not want anyone at company2 to be able to read their
- data except via the web. In this case you would need two
- daemons, each running with different <a
- href="../mod/mpm_common.html#user">User</a>, <a
- href="../mod/mpm_common.html#group">Group</a>, <a
- href="../mod/mpm_common.html#listen">Listen</a>, and <a
- href="../mod/core.html#serverroot">ServerRoot</a>
- settings.</li>
-
- <li>You can afford the memory and <a
- href="../misc/descriptors.html">file descriptor
- requirements</a> of listening to every IP alias on the
- machine. It's only possible to <a
- href="../mod/mpm_common.html#listen">Listen</a> to the "wildcard"
- address, or to specific addresses. So if you have a need to
- listen to a specific address for whatever reason, then you
- will need to listen to all specific addresses. (Although one
- httpd could listen to N-1 of the addresses, and another could
- listen to the remaining address.)</li>
- </ul>
- Use a single daemon when:
-
- <ul>
- <li>Sharing of the httpd configuration between virtual hosts
- is acceptable.</li>
-
- <li>The machine services a large number of requests, and so
- the performance loss in running separate daemons may be
- significant.</li>
- </ul>
-
- <h2>Setting up multiple daemons</h2>
- Create a separate httpd installation for each virtual host. For
- each installation, use the <a
- href="../mod/mpm_common.html#listen">Listen</a> directive in the
- configuration file to select which IP address (or virtual host)
- that daemon services. e.g.
-<pre>
- Listen www.smallco.com:80
-</pre>
- It is recommended that you use an IP address instead of a
- hostname (see <a href="../dns-caveats.html">DNS caveats</a>).
-
- <h2>Setting up a single daemon with virtual hosts</h2>
- For this case, a single httpd will service requests for the
- main server and all the virtual hosts. The <a
- href="../mod/core.html#virtualhost">VirtualHost</a> directive
- in the configuration file is used to set the values of <a
- href="../mod/core.html#serveradmin">ServerAdmin</a>, <a
- href="../mod/core.html#servername">ServerName</a>, <a
- href="../mod/core.html#documentroot">DocumentRoot</a>, <a
- href="../mod/core.html#errorlog">ErrorLog</a> and <a
- href="../mod/mod_log_config.html#transferlog">TransferLog</a>
- or <a href="../mod/mod_log_config.html#customlog">CustomLog</a>
- configuration directives to different values for each virtual
- host. e.g.
-<pre>
- <VirtualHost www.smallco.com>
- ServerAdmin webmaster@mail.smallco.com
- DocumentRoot /groups/smallco/www
- ServerName www.smallco.com
- ErrorLog /groups/smallco/logs/error_log
- TransferLog /groups/smallco/logs/access_log
- </VirtualHost>
-
- <VirtualHost www.baygroup.org>
- ServerAdmin webmaster@mail.baygroup.org
- DocumentRoot /groups/baygroup/www
- ServerName www.baygroup.org
- ErrorLog /groups/baygroup/logs/error_log
- TransferLog /groups/baygroup/logs/access_log
- </VirtualHost>
-</pre>
- It is recommended that you use an IP address instead of a
- hostname (see <a href="../dns-caveats.html">DNS caveats</a>).
-
- <p>Almost <strong>any</strong> configuration directive can be
- put in the VirtualHost directive, with the exception of
- directives that control process creation and a few other
- directives. To find out if a directive can be used in the
- VirtualHost directive, check the <a
- href="../mod/directive-dict.html#Context">Context</a> using the
- <a href="../mod/directives.html">directive index</a>.</p>
-
- <p><a href="../mod/mpm_common.html#user">User</a> and <a
- href="../mod/mpm_common.html#group">Group</a> may be used inside a
- VirtualHost directive if the <a href="../suexec.html">suEXEC
- wrapper</a> is used.</p>
-
- <p><em>SECURITY:</em> When specifying where to write log files,
- be aware of some security risks which are present if anyone
- other than the user that starts Apache has write access to the
- directory where they are written. See the <a
- href="../misc/security_tips.html">security tips</a> document
- for details.</p>
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-
+++ /dev/null
-<!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>Dynamically configured mass virtual hosting</title>
- </head>
- <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
-
- <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
- vlink="#000080" alink="#FF0000">
- <!--#include virtual="header.html" -->
-
- <h1 align="center">Dynamically configured mass virtual
- hosting</h1>
-
- <p>This document describes how to efficiently serve an
- arbitrary number of virtual hosts with Apache 1.3. <!--
-
- Written by Tony Finch (fanf@demon.net) (dot@dotat.at).
-
- Some examples were derived from Ralf S. Engleschall's document
- http://www.engelschall.com/pw/apache/rewriteguide/
-
- Some suggestions were made by Brian Behlendorf.
-
- -->
- </p>
-
- <h2><a id="contents" name="contents">Contents:</a></h2>
-
- <ul>
- <li><a href="#motivation">Motivation</a></li>
-
- <li><a href="#overview">Overview</a></li>
-
- <li><a href="#simple">Simple dynamic virtual hosts</a></li>
-
- <li><a href="#homepages">A virtually hosted homepages
- system</a></li>
-
- <li><a href="#combinations">Using more than one virtual
- hosting system on the same server</a></li>
-
- <li><a href="#ipbased">More efficient IP-based virtual
- hosting</a></li>
-
- <li><a href="#oldversion">Using older versions of
- Apache</a></li>
-
- <li><a href="#simple.rewrite">Simple dynamic virtual hosts
- using <code>mod_rewrite</code></a></li>
-
- <li><a href="#homepages.rewrite">A homepages system using
- <code>mod_rewrite</code></a></li>
-
- <li><a href="#xtra-conf">Using a separate virtual host
- configuration file</a></li>
- </ul>
- <hr />
-
- <h2><a id="motivation" name="motivation">Motivation</a></h2>
-
- <p>The techniques described here are of interest if your
- <code>httpd.conf</code> contains many
- <code><VirtualHost></code> sections that are
- substantially the same, for example:</p>
-<pre>
-NameVirtualHost 111.22.33.44
-<VirtualHost 111.22.33.44>
- ServerName www.customer-1.com
- DocumentRoot /www/hosts/www.customer-1.com/docs
- ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin
-</VirtualHost>
-<VirtualHost 111.22.33.44>
- ServerName www.customer-2.com
- DocumentRoot /www/hosts/www.customer-2.com/docs
- ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin
-</VirtualHost>
-# blah blah blah
-<VirtualHost 111.22.33.44>
- ServerName www.customer-N.com
- DocumentRoot /www/hosts/www.customer-N.com/docs
- ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin
-</VirtualHost>
-</pre>
- <br />
- <br />
-
-
- <p>The basic idea is to replace all of the static
- <code><VirtualHost></code> configuration with a mechanism
- that works it out dynamically. This has a number of
- advantages:</p>
-
- <ol>
- <li>Your configuration file is smaller so Apache starts
- faster and uses less memory.</li>
-
- <li>Adding virtual hosts is simply a matter of creating the
- appropriate directories in the filesystem and entries in the
- DNS - you don't need to reconfigure or restart Apache.</li>
- </ol>
- <br />
- <br />
-
-
- <p>The main disadvantage is that you cannot have a different
- log file for each virtual host; however if you have very many
- virtual hosts then doing this is dubious anyway because it eats
- file descriptors. It is better to log to a pipe or a fifo and
- arrange for the process at the other end to distribute the logs
- to the customers (it can also accumulate statistics, etc.).</p>
- <hr />
-
- <h2><a id="overview" name="overview">Overview</a></h2>
-
- <p>A virtual host is defined by two pieces of information: its
- IP address, and the contents of the <code>Host:</code> header
- in the HTTP request. The dynamic mass virtual hosting technique
- is based on automatically inserting this information into the
- pathname of the file that is used to satisfy the request. This
- is done most easily using <a
- href="../mod/mod_vhost_alias.html"><code>mod_vhost_alias</code></a>,
- but if you are using a version of Apache up to 1.3.6 then you
- must use <a
- href="../mod/mod_rewrite.html"><code>mod_rewrite</code></a>.
- Both of these modules are disabled by default; you must enable
- one of them when configuring and building Apache if you want to
- use this technique.</p>
-
- <p>A couple of things need to be `faked' to make the dynamic
- virtual host look like a normal one. The most important is the
- server name which is used by Apache to generate
- self-referential URLs, etc. It is configured with the
- <code>ServerName</code> directive, and it is available to CGIs
- via the <code>SERVER_NAME</code> environment variable. The
- actual value used at run time is controlled by the <a
- href="../mod/core.html#usecanonicalname"><code>UseCanonicalName</code></a>
- setting. With <code>UseCanonicalName Off</code> the server name
- comes from the contents of the <code>Host:</code> header in the
- request. With <code>UseCanonicalName DNS</code> it comes from a
- reverse DNS lookup of the virtual host's IP address. The former
- setting is used for name-based dynamic virtual hosting, and the
- latter is used for IP-based hosting. If Apache cannot work out
- the server name because there is no <code>Host:</code> header
- or the DNS lookup fails then the value configured with
- <code>ServerName</code> is used instead.</p>
-
- <p>The other thing to `fake' is the document root (configured
- with <code>DocumentRoot</code> and available to CGIs via the
- <code>DOCUMENT_ROOT</code> environment variable). In a normal
- configuration this setting is used by the core module when
- mapping URIs to filenames, but when the server is configured to
- do dynamic virtual hosting that job is taken over by another
- module (either <code>mod_vhost_alias</code> or
- <code>mod_rewrite</code>) which has a different way of doing
- the mapping. Neither of these modules is responsible for
- setting the <code>DOCUMENT_ROOT</code> environment variable so
- if any CGIs or SSI documents make use of it they will get a
- misleading value.</p>
- <hr />
-
- <h2><a id="simple" name="simple">Simple dynamic virtual
- hosts</a></h2>
-
- <p>This extract from <code>httpd.conf</code> implements the
- virtual host arrangement outlined in the <a
- href="#motivation">Motivation</a> section above, but in a
- generic fashion using <code>mod_vhost_alias</code>.</p>
-<pre>
-# get the server name from the Host: header
-UseCanonicalName Off
-
-# this log format can be split per-virtual-host based on the first field
-LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-# include the server name in the filenames used to satisfy requests
-VirtualDocumentRoot /www/hosts/%0/docs
-VirtualScriptAlias /www/hosts/%0/cgi-bin
-</pre>
-
- <p>This configuration can be changed into an IP-based virtual
- hosting solution by just turning <code>UseCanonicalName
- Off</code> into <code>UseCanonicalName DNS</code>. The server
- name that is inserted into the filename is then derived from
- the IP address of the virtual host.</p>
- <hr />
-
- <h2><a id="homepages" name="homepages">A virtually hosted
- homepages system</a></h2>
-
- <p>This is an adjustment of the above system tailored for an
- ISP's homepages server. Using a slightly more complicated
- configuration we can select substrings of the server name to
- use in the filename so that e.g. the documents for
- <samp>www.user.isp.com</samp> are found in
- <code>/home/user/</code>. It uses a single <code>cgi-bin</code>
- directory instead of one per virtual host.</p>
-<pre>
-# all the preliminary stuff is the same as above, then
-
-# include part of the server name in the filenames
-VirtualDocumentRoot /www/hosts/%2/docs
-
-# single cgi-bin directory
-ScriptAlias /cgi-bin/ /www/std-cgi/
-</pre>
-
- <p>There are examples of more complicated
- <code>VirtualDocumentRoot</code> settings in <a
- href="../mod/mod_vhost_alias.html">the
- <code>mod_vhost_alias</code> documentation</a>.</p>
- <hr />
-
- <h2><a id="combinations" name="combinations">Using more than
- one virtual hosting system on the same server</a></h2>
-
- <p>With more complicated setups you can use Apache's normal
- <code><VirtualHost></code> directives to control the
- scope of the various virtual hosting configurations. For
- example, you could have one IP address for homepages customers
- and another for commercial customers with the following setup.
- This can of course be combined with conventional
- <code><VirtualHost></code> configuration sections.</p>
-<pre>
-UseCanonicalName Off
-
-LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon
-
-<Directory /www/commercial>
- Options FollowSymLinks
- AllowOverride All
-</Directory>
-
-<Directory /www/homepages>
- Options FollowSymLinks
- AllowOverride None
-</Directory>
-
-<VirtualHost 111.22.33.44>
- ServerName www.commercial.isp.com
-
- CustomLog logs/access_log.commercial vcommon
-
- VirtualDocumentRoot /www/commercial/%0/docs
- VirtualScriptAlias /www/commercial/%0/cgi-bin
-</VirtualHost>
-
-<VirtualHost 111.22.33.45>
- ServerName www.homepages.isp.com
-
- CustomLog logs/access_log.homepages vcommon
-
- VirtualDocumentRoot /www/homepages/%0/docs
- ScriptAlias /cgi-bin/ /www/std-cgi/
-</VirtualHost>
-</pre>
- <hr />
-
- <h2><a id="ipbased" name="ipbased">More efficient IP-based
- virtual hosting</a></h2>
-
- <p>After <a href="#simple">the first example</a> I noted that
- it is easy to turn it into an IP-based virtual hosting setup.
- Unfortunately that configuration is not very efficient because
- it requires a DNS lookup for every request. This can be avoided
- by laying out the filesystem according to the IP addresses
- themselves rather than the corresponding names and changing the
- logging similarly. Apache will then usually not need to work
- out the server name and so incur a DNS lookup.</p>
-<pre>
-# get the server name from the reverse DNS of the IP address
-UseCanonicalName DNS
-
-# include the IP address in the logs so they may be split
-LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-# include the IP address in the filenames
-VirtualDocumentRootIP /www/hosts/%0/docs
-VirtualScriptAliasIP /www/hosts/%0/cgi-bin
-</pre>
- <hr />
-
- <h2><a id="oldversion" name="oldversion">Using older versions
- of Apache</a></h2>
-
- <p>The examples above rely on <code>mod_vhost_alias</code>
- which appeared after version 1.3.6. If you are using a version
- of Apache without <code>mod_vhost_alias</code> then you can
- implement this technique with <code>mod_rewrite</code> as
- illustrated below, but only for Host:-header-based virtual
- hosts.</p>
-
- <p>In addition there are some things to beware of with logging.
- Apache 1.3.6 is the first version to include the
- <code>%V</code> log format directive; in versions 1.3.0 - 1.3.3
- the <code>%v</code> option did what <code>%V</code> does;
- version 1.3.4 has no equivalent. In all these versions of
- Apache the <code>UseCanonicalName</code> directive can appear
- in <code>.htaccess</code> files which means that customers can
- cause the wrong thing to be logged. Therefore the best thing to
- do is use the <code>%{Host}i</code> directive which logs the
- <code>Host:</code> header directly; note that this may include
- <code>:port</code> on the end which is not the case for
- <code>%V</code>.</p>
- <hr />
-
- <h2><a id="simple.rewrite" name="simple.rewrite">Simple dynamic
- virtual hosts using <code>mod_rewrite</code></a></h2>
-
- <p>This extract from <code>httpd.conf</code> does the same
- thing as <a href="#simple">the first example</a>. The first
- half is very similar to the corresponding part above but with
- some changes for backward compatibility and to make the
- <code>mod_rewrite</code> part work properly; the second half
- configures <code>mod_rewrite</code> to do the actual work.</p>
-
- <p>There are a couple of especially tricky bits: By default,
- <code>mod_rewrite</code> runs before the other URI translation
- modules (<code>mod_alias</code> etc.) so if they are used then
- <code>mod_rewrite</code> must be configured to accommodate
- them. Also, mome magic must be performed to do a
- per-dynamic-virtual-host equivalent of
- <code>ScriptAlias</code>.</p>
-<pre>
-# get the server name from the Host: header
-UseCanonicalName Off
-
-# splittable logs
-LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon
-CustomLog logs/access_log vcommon
-
-<Directory /www/hosts>
- # ExecCGI is needed here because we can't force
- # CGI execution in the way that ScriptAlias does
- Options FollowSymLinks ExecCGI
-</Directory>
-
-# now for the hard bit
-
-RewriteEngine On
-
-# a ServerName derived from a Host: header may be any case at all
-RewriteMap lowercase int:tolower
-
-## deal with normal documents first:
-# allow Alias /icons/ to work - repeat for other aliases
-RewriteCond %{REQUEST_URI} !^/icons/
-# allow CGIs to work
-RewriteCond %{REQUEST_URI} !^/cgi-bin/
-# do the magic
-RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1
-
-## and now deal with CGIs - we have to force a MIME type
-RewriteCond %{REQUEST_URI} ^/cgi-bin/
-RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]
-
-# that's it!
-</pre>
- <hr />
-
- <h2><a id="homepages.rewrite" name="homepages.rewrite">A
- homepages system using <code>mod_rewrite</code></a></h2>
-
- <p>This does the same thing as <a href="#homepages">the second
- example</a>.</p>
-<pre>
-RewriteEngine on
-
-RewriteMap lowercase int:tolower
-
-# allow CGIs to work
-RewriteCond %{REQUEST_URI} !^/cgi-bin/
-
-# check the hostname is right so that the RewriteRule works
-RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$
-
-# concatenate the virtual host name onto the start of the URI
-# the [C] means do the next rewrite on the result of this one
-RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]
-
-# now create the real file name
-RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2
-
-# define the global CGI directory
-ScriptAlias /cgi-bin/ /www/std-cgi/
-</pre>
- <hr />
-
- <h2><a id="xtra-conf" name="xtra-conf">Using a separate virtual
- host configuration file</a></h2>
-
- <p>This arrangement uses more advanced <code>mod_rewrite</code>
- features to get the translation from virtual host to document
- root from a separate configuration file. This provides more
- flexibility but requires more complicated configuration.</p>
-
- <p>The <code>vhost.map</code> file contains something like
- this:</p>
-<pre>
-www.customer-1.com /www/customers/1
-www.customer-2.com /www/customers/2
-# ...
-www.customer-N.com /www/customers/N
-</pre>
- <br />
- <br />
-
-
- <p>The <code>http.conf</code> contains this:</p>
-<pre>
-RewriteEngine on
-
-RewriteMap lowercase int:tolower
-
-# define the map file
-RewriteMap vhost txt:/www/conf/vhost.map
-
-# deal with aliases as above
-RewriteCond %{REQUEST_URI} !^/icons/
-RewriteCond %{REQUEST_URI} !^/cgi-bin/
-RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
-# this does the file-based remap
-RewriteCond ${vhost:%1} ^(/.*)$
-RewriteRule ^/(.*)$ %1/docs/$1
-
-RewriteCond %{REQUEST_URI} ^/cgi-bin/
-RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$
-RewriteCond ${vhost:%1} ^(/.*)$
-RewriteRule ^/(.*)$ %1/cgi-bin/$1
-</pre>
- <br />
- <br />
- <!--#include virtual="footer.html" -->
- </body>
-</html>
-