Mailing List Archive: cvs commit: apachen/htdocs/manual/vhosts details.html details_1_2.html examples.html fd-limits.html footer.html header.html index.html ip-based.html name-based.html

martin 97/11/11 15:47:22

Modified: htdocs/manual bind.html dns-caveats.html index.html
new_features_1_0.html new_features_1_1.html
new_features_1_3.html upgrading_to_1_3.html
htdocs/manual/misc FAQ.html known_bugs.html
htdocs/manual/mod core.html
Added: htdocs/manual/vhosts details.html details_1_2.html
examples.html fd-limits.html footer.html
header.html index.html ip-based.html
name-based.html
Log:
Citing Lars:
Hi,

the attachment includes a reworked Apache manual with the
new virtual host documentation.

As Dean suggested I created a new directory named 'vhosts' and moved the
updated vhosts-in-depth etc. documents into the new directory, renamed
them and updated all other documents which refered to the old docs
(at least I tried to find all documents...).

Submitted by: Lars Eilebrecht <sfx@unix-ag.org>
Reviewed by: Martin Kraemer

Revision Changes Path
1.9 +1 -2 apachen/htdocs/manual/bind.html

Index: bind.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/bind.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -u -r1.8 -r1.9
--- bind.html 1997/06/04 11:07:47 1.8
+++ bind.html 1997/11/11 23:46:47 1.9
@@ -95,8 +95,7 @@
<h2>See also</h2>

See also the documentation on
-<a href="virtual-host.html">Virtual Hosts</a>,
-<a href="host.html">Non-IP virtual hosts</a>,
+<a href="vhosts/index.html">Virtual Hosts</a>,
<a href="mod/core.html#bindaddress">BindAddress directive</a>,
<a href="mod/core.html#port">Port directive</a>,
<a href="dns-caveats.html">DNS Issues</a>

1.7 +2 -14 apachen/htdocs/manual/dns-caveats.html

Index: dns-caveats.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/dns-caveats.html,v
retrieving revision 1.6
retrieving revision 1.7
diff -u -u -r1.6 -r1.7
--- dns-caveats.html 1997/07/06 17:18:53 1.6
+++ dns-caveats.html 1997/11/11 23:46:48 1.7
@@ -113,11 +113,11 @@
served by the <code>def.com</code> virtual host. To better understand why
this happens requires a more in-depth discussion of how Apache matches
up incoming requests with the virtual host that will serve it. A rough
-document describing this <a href="vhosts-in-depth.html"> is available</a>.
+document describing this <a href="vhosts/details.html"> is available</a>.

<h3>The "main server" Address</h3>

-<p>The addition of <a href="host.html">non-IP-based virtual host
+<p>The addition of <a href="vhosts/name-based.html">name-based virtual host
support</a> in Apache 1.1 requires Apache to know the IP address(es) of
the host that httpd is running on. To get this address it uses either
the global <code>ServerName</code> (if present) or calls the C function
@@ -140,18 +140,6 @@
CGIs unless you use <a href="mod/mod_env.html"><code>mod_env</code></a>
to control the environment. It's best to consult the man pages or FAQs
for your OS.
-
-<h3>The _default_ Address</h3>
-
-<p>Any address that happens to go to your webserver which doesn't match
-the IP address of any of the webservers will be served from the "main" or
-"default" server configurations. The "main" server configuration consists
-of all those definitions appearing outside of any VirtualHost section.
-You may want instead to define a <code><VirtualHost _default_:*></code>
-which returns 403 or 404 for all hits. (The trailing <code>:*</code>
-makes it apply to all ports, which is just a safety measure should you
-begin using multiple <code><a href="mod/core.html#listen">Listen</a></code>
-directives.)

<h3><a name="tips">Tips to Avoid these problems</a></h3>

1.19 +2 -1 apachen/htdocs/manual/index.html

Index: index.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/index.html,v
retrieving revision 1.18
retrieving revision 1.19
diff -u -u -r1.18 -r1.19
--- index.html 1997/10/24 09:53:39 1.18
+++ index.html 1997/11/11 23:46:48 1.19
@@ -44,7 +44,8 @@
<li><A HREF="invoking.html">Starting Apache</A>
<li><A HREF="stopping.html">Stopping or Restarting Apache</A>
<li><A HREF="mod/directives.html">Apache run-time configuration directives</A>
-<li><A HREF="mod/">Apache modules</A>
+<li><A HREF="mod/index.html">Apache modules</A>
+<li><A HREF="vhosts/index.html">Apache Virtual Host documentation</A>
<li><A HREF="handler.html">Apache's handler use</A>
<li><A HREF="env.html">Special purpose environment variables</A>
<LI><A HREF="misc/API.html">Highly generalized API to server functionality</A>

1.8 +1 -1 apachen/htdocs/manual/new_features_1_0.html

Index: new_features_1_0.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/new_features_1_0.html,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -u -r1.7 -r1.8
--- new_features_1_0.html 1997/07/06 17:18:55 1.7
+++ new_features_1_0.html 1997/11/11 23:46:49 1.8
@@ -58,7 +58,7 @@

<P>

-<LI> <a href="virtual-host.html"><VirtualHost> (the configuration directive for
+<LI> <a href="vhosts/index.html"><VirtualHost> (the configuration directive for
multiple-homed servers)</a> is more general now. Just about any srm.conf or
httpd.conf command can go in a <Virtualhost> section, with the
following specific exceptions: ServerType, UserId, GroupId,

1.9 +1 -1 apachen/htdocs/manual/new_features_1_1.html

Index: new_features_1_1.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/new_features_1_1.html,v
retrieving revision 1.8
retrieving revision 1.9
diff -u -u -r1.8 -r1.9
--- new_features_1_1.html 1997/07/06 14:54:44 1.8
+++ new_features_1_1.html 1997/11/11 23:46:49 1.9
@@ -47,7 +47,7 @@
Netscape Navigator 2.0) has been shown to increase speed of document
transfer by up to 50% in certain cases.

-<li><b><a href="host.html">New non-IP Intensive VirtualHost
+<li><b><a href="vhosts/index.html">New non-IP Intensive VirtualHost
Support</a></b><br>
Apache's support for virtual hosts has been enhanced to be able to
use information sent by some new Web browsers to determine the server

1.31 +3 -1 apachen/htdocs/manual/new_features_1_3.html

Index: new_features_1_3.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/new_features_1_3.html,v
retrieving revision 1.30
retrieving revision 1.31
diff -u -u -r1.30 -r1.31
--- new_features_1_3.html 1997/11/09 20:40:28 1.30
+++ new_features_1_3.html 1997/11/11 23:46:50 1.31
@@ -341,7 +341,7 @@
it easier to start Apache via rsh or crontab.

<li><strong>Improved HTTP/1.1-style Virtual Hosts</strong><br>
- The new (undocumented)
+ The new
<a href="mod/core.html#namevirtualhost"><SAMP>NameVirtualHost</SAMP></a>
directive is used to list IP address:port
pairs on which HTTP/1.1-style virtual hosting occurs. This is
@@ -349,6 +349,8 @@
Previously this address was implicitly the same as the "main address"
of the machine, and this caused no end of problems for users, and
was not powerful enough.
+ Please see the <a href="vhosts/index.html">Apache Virtual Host
+ documentation</a> for further details on configuration.

<li><strong>API Additions</strong><br>

1.4 +3 -1 apachen/htdocs/manual/upgrading_to_1_3.html

Index: upgrading_to_1_3.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/upgrading_to_1_3.html,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -u -r1.3 -r1.4
--- upgrading_to_1_3.html 1997/10/07 23:01:35 1.3
+++ upgrading_to_1_3.html 1997/11/11 23:46:50 1.4
@@ -65,10 +65,12 @@
<ul>
<li>Folks using HTTP/1.1-style virtual hosting will need to list the
ip:port pairs that are supposed to have HTTP/1.1-style virtual hosting
- via the (undocumented) <a href="mod/core.html#namevirtualhost"><code>
+ via the <a href="mod/core.html#namevirtualhost"><code>
NameVirtualHost</code></a> directive. Previously this support was
given implicitly on the "main server address". Now it has to be
explicitly listed so as to avoid many problems that users had.
+ Please see the <a href="vhosts/index.html">Apache Virtual Host
+ documentation</a> for further details on configuration.

<li>The precedence of virtual hosts has been reversed (applies mainly to
vhosts using HTTP/1.1 Host: headers, and the

1.94 +12 -4 apachen/htdocs/manual/misc/FAQ.html

Index: FAQ.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/misc/FAQ.html,v
retrieving revision 1.93
retrieving revision 1.94
diff -u -u -r1.93 -r1.94
--- FAQ.html 1997/11/06 14:52:47 1.93
+++ FAQ.html 1997/11/11 23:47:15 1.94
@@ -15,7 +15,7 @@

<H1 ALIGN="CENTER">Apache Server Frequently Asked Questions</H1>
<P>
- $Revision: 1.93 $ ($Date: 1997/11/06 14:52:47 $)
+ $Revision: 1.94 $ ($Date: 1997/11/11 23:47:15 $)
</P>
<P>
The latest version of this FAQ is always available from the main
@@ -254,7 +254,7 @@
</LI>
<LI><A HREF="#year2000">Is Apache Year 2000 compliant?</A>
</LI>
- <LI><A HREF="#namevhost">I upgraded to Apache 1.3b2 and now my
+ <LI><A HREF="#namevhost">I upgraded to Apache 1.3b and now my
virtual hosts don't work!</A>
</LI>
</OL>
@@ -420,7 +420,10 @@
REL="Help"
><CITE>Apache Week</CITE></A>
available. Links to relevant <CITE>Apache Week</CITE> articles are
- included below where appropriate.
+ included below where appropriate. There are also some
+ <A
+ HREF="http://www.apache.org/info/apache_books.html"
+ >Apache-specific books</A> available.
</P>
<HR>
</LI>
@@ -2111,7 +2114,7 @@
<HR>
</LI>
<LI><A NAME="namevhost">
- <STRONG>I upgraded to Apache 1.3b2 and now my virtual hosts don't
+ <STRONG>I upgraded to Apache 1.3b and now my virtual hosts don't
work!</STRONG>
</A>
<P>
@@ -2149,6 +2152,11 @@
Make sure that your name-based <SAMP><VirtualHost></SAMP> blocks
contain <SAMP>ServerName</SAMP> and possibly <SAMP>ServerAlias</SAMP>
directives so Apache can be sure to tell them apart correctly.
+ </P>
+ <P>
+ Please see the
+ <A HREF="http://www.apache.org/docs/vhosts/index.html">Apache
+ Virtual Host documentation</A> for further details about configuration.
</P>
<HR>
</LI>

1.35 +1 -10 apachen/htdocs/manual/misc/known_bugs.html

Index: known_bugs.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/misc/known_bugs.html,v
retrieving revision 1.34
retrieving revision 1.35
diff -u -u -r1.34 -r1.35
--- known_bugs.html 1997/11/11 23:11:10 1.34
+++ known_bugs.html 1997/11/11 23:47:15 1.35
@@ -35,16 +35,7 @@
<HR>

<H2>Apache 1.3b2 Bugs</H2>
-<OL>
-<LI>There is no documentation for the <CODE>NameVirtualHost</CODE>
- directive. Name based virtual hosts (ie. those that do not have
- a separate IP) will not work unless you add a
- <CODE>NameVirtualHost x.x.x.x</CODE> directive to your config file
- for each IP address you want name based virtual hosts to be used
- on, where <CODE>x.x.x.x</CODE> is the IP address. This must appear
- before the related <A HREF="../mod/core.html#virtualhost">VirtualHost</A>
- directive. Documentation is being written for this.
-</OL>
+
<H3>Win32 only</H3>
<OL>
<LI>CGI scripts that are called with information appended to the script

1.83 +41 -14 apachen/htdocs/manual/mod/core.html

Index: core.html
===================================================================
RCS file: /home/cvs/apachen/htdocs/manual/mod/core.html,v
retrieving revision 1.82
retrieving revision 1.83
diff -u -u -r1.82 -r1.83
--- core.html 1997/11/11 23:11:11 1.82
+++ core.html 1997/11/11 23:47:17 1.83
@@ -57,6 +57,7 @@
<li><A HREF="#maxrequestsperchild">MaxRequestsPerChild</A>
<li><A HREF="#maxspareservers">MaxSpareServers</A>
<li><A HREF="#minspareservers">MinSpareServers</A>
+<li><A HREF="#namevirtualhost">NameVirtualHost</A>
<li><A HREF="#options">Options</A>
<li><A HREF="#pidfile">PidFile</A>
<li><A HREF="#port">Port</A>
@@ -252,7 +253,7 @@
<code>BindAddress</code>.<p>

<code>BindAddress</code> can be used as an alternative method for
-supporting <A HREF="../virtual-host.html">virtual hosts</A> using
+supporting <A HREF="../vhosts/index.html">virtual hosts</A> using
multiple independent servers, instead of using <code><A
HREF="#virtualhost"><VirtualHost></A></code> sections.

@@ -1111,6 +1112,34 @@
See also <A HREF="#maxspareservers">MaxSpareServers</A> and
<A HREF="#startservers">StartServers</A>.<p><hr>

+<h2><A name="namevirtualhost">NameVirtualHost directive</A></h2>
+
+<strong>Syntax:</strong> NameVirtualHost <em>addr</em>[:<em>port</em>]<br>
+<strong>Context:</strong> server config<br>
+<strong>Status:</strong> core<p>
+<strong>Compatibility:</strong> NameVirtualHost is only available in Apache 1.3 and later<p>
+
+The NameVirtualHost directive is a required directive if you want to configure
+<A HREF="../vhosts/index.html">name-based virtual hosts</A>.<p>
+
+Although <em>addr</em> can be hostname it is recommended that you always use
+an IP address, e.g.
+
+<blockquote><code>NameVirtualHost 111.22.33.44</code></blockquote>
+
+With the NameVirtualHost directive the address to which your name-based
+virtual host names resolve.
+If you have multiple name-based hosts on multiple addresses,
+repeat the directive for each address.<p>
+
+Optionally you can specify a port number on which the name-based
+virtual hosts should be used, e.g.
+
+<blockquote><code>NameVirtualHost 111.22.33.44:8080</code></blockquote>
+
+<strong>See also:</strong>
+<a href="../vhosts/index.html">Apache Virtual Host documentation</a>
+
<h2><A name="options">Options directive</A></h2>

<strong>Syntax:</strong> Options <em>[+|-]option [+|-]option ...</em><br>
@@ -1490,9 +1519,10 @@

The ServerAlias directive sets the alternate names for a host, for use
with
-<a href="../host.html">Host-header based virtual hosts</a>.
-<p><strong>See Also</strong>:
-<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p>
+<a href="../vhosts/name-based.html">name-based virtual hosts</a>.
+
+<p><strong>See also:</strong>
+<a href="../vhosts/index.html">Apache Virtual Host documentation</a>

<hr>

@@ -1522,9 +1552,11 @@
1.1 and later.<p>

The ServerPath directive sets the legacy URL pathname for a host, for
-use with <a href="../host.html">Host-header based virtual hosts</a>.
-<p><strong>See Also</strong>:
-<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a></p>
+use with <a href="../vhosts/index.html">name-based virtual hosts</a>.
+
+<p><strong>See also:</strong>
+<a href="../vhosts/index.html">Apache Virtual Host documentation</a>
+
<hr>

<h2><A name="serverroot">ServerRoot directive</A></h2>
@@ -1742,14 +1774,9 @@
href="#listen">Listen</a>.

<p><strong>See also:</strong>
-<A HREF="../dns-caveats.html">Warnings about DNS and Apache</a><br>
-<strong>See also:</strong>
-<A HREF="../virtual-host.html">Information on Virtual Hosts.
-(multihome)</A><br>
+<a href="../vhosts/index.html">Apache Virtual Host documentation</a><br>
<strong>See also:</strong>
-<a href="../host.html">Non-IP address-based Virtual Hosts</a><br>
-<strong>See also:</strong>
-<a href="../vhosts-in-depth.html">In-depth description of Virtual Host matching</a><br>
+<A HREF="../dns-caveats.html">Warnings about DNS and Apache</a><br>
<strong>See also:</strong>
<a href="../bind.html">Setting which addresses and ports Apache uses</a><br>
<strong>See also</strong>: <a href="../sections.html">How Directory,

1.1 apachen/htdocs/manual/vhosts/details.html

Index: details.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>An In-Depth Discussion of Virtual Host Matching</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<h1 ALIGN="CENTER">An In-Depth Discussion of Virtual Host Matching</h1>

<p>The virtual host code was completely rewritten in <B>Apache 1.3</B>.
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>If you just want to <cite>make it work</cite> without understanding
how, here are <a href="examples.html">some examples</a>.

<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>The directives
<A HREF="../mod/core.html#port"><SAMP>Port</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>The default value of the <code>Port</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>The main_server Port directive has two functions due to legacy
compatibility with NCSA configuration files. One function is
to determine the default network port Apache will bind to. This
default is overridden by the existence of any
<A HREF="../mod/core.html#listen"><code>Listen</code></A> directives.
The second function is to specify the port number which is used
in absolute URIs during redirects.

<p>Unlike the main_server, vhost ports <em>do not</em> affect what
ports Apache listens for connections on.

<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>Port</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>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.

<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>Multiple <code>NameVirtualHost</code> directives can be used each
with a set of <code>VirtualHost</code> directives.

<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):

<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> After parsing the <code>VirtualHost</code> directive, the vhost server
is given a default <code>Port</code> equal to the port assigned to the
first name in its <code>VirtualHost</code> directive.

<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>Port</code> statements for this vhost will not affect
the ports assigned in the address set.

<p>During initialization a list for each IP address
is generated an 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>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>For every vhost various default values are set. In particular:

<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>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>The per-server configs for each module from the main_server are
merged into the vhost server.
</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> 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>Any vhost that includes the magic <SAMP>_default_</SAMP> wildcard
is given the same <code>ServerName</code> as the main_server.

<h3>Virtual Host Matching</h3>

<p>The server determines which vhost to use for a request as follows:

<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>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>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.

<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.

<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>The first vhost on this list (the first vhost that appears after the
corresponding <code>NameVirtualHost</code> directive in the config file)
has the highest priority and catches any request to an unknown
server name or a request without a <code>Host:</code> header.

<p>If the client provided a <code>Host:</code> header 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 can contain a port number, but
Apache always matches against the real port to which the client sent
the request.

<p>If the client submitted a HTTP/1.0 request without <code>Host:</code>
header 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>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).

<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.

<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.
<p>

<li><code>ServerAlias</code> and <code>ServerPath</code> checks are never
performed for an IP-based vhost.
<p>

<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.
<p>

<li>For security reasons the port number given in a <code>Host:</code>
header is never used during the matching process. Apache always
uses the real port to which the client sent the request.
<p>

<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
Host header was available to disambiguate the two.)
<p>

<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.
<p>

<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 catched 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>Port</code>
by default. A wildcard port can be specified (i.e.
<code>_default_:*</code>) to catch requests to any available port.
<p>

<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).
<p>

<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
if the client connected to an address (and port) which is used
for name-based vhosts, e.g. in a <code>NameVirtualHost</code> directive.
<p>

<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.
<p>

<li><code>ServerName</code> should always be set for each vhost. Otherwise
A DNS lookup is required for each vhost.
<p>

</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:

<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.)
<p>

<li>Group corresponding <code>NameVirtualHost</code> and
<code>VirtualHost</code> definitions in your configuration to ensure
better readability.
<p>

<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").
<p>

</ul>


</BODY>
</HTML>

1.1 apachen/htdocs/manual/vhosts/details_1_2.html

Index: details_1_2.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>An In-Depth Discussion of VirtualHost Matching</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<h1 ALIGN="CENTER">An In-Depth Discussion of VirtualHost Matching</h1>

<p>This is a very rough document that was probably out of date the moment
it was written. It attempts to explain exactly what the code does when
deciding what virtual host to serve a hit from. It's provided on the
assumption that something is better than nothing. The server version
under discussion is Apache 1.2.

<p>If you just want to "make it work" without understanding
how, there's a <a href="#whatworks">What Works</a> section at the bottom.

<h3>Config File Parsing</h3>

<p>There is a main_server 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>The directives
<A
HREF="mod/core.html#port"
><SAMP>Port</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>The default value of the <code>Port</code> field for main_server
is 80. The main_server has no default <code>ServerName</code>,
<code>ServerPath</code>, or <code>ServerAlias</code>.

<p>In the absence of any
<A
HREF="mod/core.html#listen"
><SAMP>Listen</SAMP></A>
directives, the (final if there
are multiple) <code>Port</code> directive in the main_server indicates
which port httpd will listen on.

<p> The <code>Port</code> and <code>ServerName</code> directives for
any server main or virtual are used when generating URLs such as during
redirects.

<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>Port</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> The magic <code>_default_</code> address has significance during
the matching algorithm. It essentially matches any unspecified address.

<p> After parsing the <code>VirtualHost</code> directive, the vhost server
is given a default <code>Port</code> equal to the port assigned to the
first name in its <code>VirtualHost</code> directive. 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). Note that subsequent <code>Port</code>
statements for this vhost will not affect the ports assigned in the
address set.

<p>
All vhosts are stored in a list which is in the reverse order that
they appeared in the config file. For example, if the config file is:

<blockquote><pre>
<VirtualHost A>
...
</VirtualHost>

<VirtualHost B>
...
</VirtualHost>

<VirtualHost C>
...
</VirtualHost>
</pre></blockquote>

Then the list will be ordered: main_server, C, B, A. Keep this in mind.

<p>
After parsing has completed, the list of servers is scanned, and various
merges and default values are set. In particular:

<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>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>The per-server configs for each module from the main_server are
merged into the vhost server.
</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> Now a pass is made through the vhosts to fill in any missing
<code>ServerName</code> fields and to classify the vhost as either
an <EM>IP-based</EM> vhost or a <EM>name-based</EM> vhost. A vhost is
considered a name-based vhost if any of its address set overlaps the
main_server (the port associated with each address must match the
main_server's <code>Port</code>). Otherwise it is considered an IP-based
vhost.

<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. Any vhost that includes the magic
<SAMP>_default_</SAMP> wildcard is given the same <code>ServerName</code> as
the main_server. Otherwise the vhost (which is necessarily an IP-based
vhost) is given a <code>ServerName</code> based on the result of a reverse
DNS lookup on the first address given in the <code>VirtualHost</code>
statement.

<p>

<h3>Vhost Matching</h3>

<p><strong>Apache 1.3 differs from what is documented
here, and documentation still has to be written.</strong>

<p>
The server determines which vhost to use for a request as follows:

<p> <code>find_virtual_server</code>: When the connection is first made
by the client, the local IP address (the IP address to which the client
connected) is looked up in the server list. A vhost is matched if it
is an IP-based vhost, the IP address matches and the port matches
(taking into account wildcards).

<p> If no vhosts are matched then the last occurrence, if it appears,
of a <SAMP>_default_</SAMP> address (which if you recall the ordering of the
server list mentioned above means that this would be the first occurrence
of <SAMP>_default_</SAMP> in the config file) is matched.

<p> In any event, if nothing above has matched, then the main_server is
matched.

<p> The vhost resulting from the above search is stored with data
about the connection. We'll call this the <EM>connection vhost</EM>.
The connection vhost is constant over all requests in a particular TCP/IP
session -- that is, over all requests in a KeepAlive/persistent session.

<p> For each request made on the connection the following sequence of
events further determines the actual vhost that will be used to serve
the request.

<p> <code>check_fulluri</code>: If the requestURI is an absoluteURI, that
is it includes <code>http://hostname/</code>, then an attempt is made to
determine if the hostname's address (and optional port) match that of
the connection vhost. If it does then the hostname portion of the URI
is saved as the <EM>request_hostname</EM>. If it does not match, then the
URI remains untouched. <STRONG>Note</STRONG>: to achieve this address
comparison,
the hostname supplied goes through a DNS lookup unless it matches the
<code>ServerName</code> or the local IP address of the client's socket.

<p> <code>parse_uri</code>: If the URI begins with a protocol
(<EM>i.e.</EM>, <code>http:</code>, <code>ftp:</code>) then the request is
considered a proxy request. Note that even though we may have stripped
an <code>http://hostname/</code> in the previous step, this could still
be a proxy request.

<p> <code>read_request</code>: If the request does not have a hostname
from the earlier step, then any <code>Host:</code> header sent by the
client is used as the request hostname.

<p> <code>check_hostalias</code>: If the request now has a hostname,
then an attempt is made to match for this hostname. The first step
of this match is to compare any port, if one was given in the request,
against the <code>Port</code> field of the connection vhost. If there's
a mismatch then the vhost used for the request is the connection vhost.
(This is a bug, see observations.)

<p>
If the port matches, then httpd scans the list of vhosts starting with
the next server <STRONG>after</STRONG> the connection vhost. This scan does not
stop if there are any matches, it goes through all possible vhosts,
and in the end uses the last match it found. The comparisons performed
are as follows:

<ul>
<li>Compare the request hostname:port with the vhost
<code>ServerName</code> and <code>Port</code>.

<li>Compare the request hostname against any and all addresses given in
the <code>VirtualHost</code> directive for this vhost.

<li>Compare the request hostname against the <code>ServerAlias</code>
given for the vhost.
</ul>

<p>
<code>check_serverpath</code>: If the request has no hostname
(back up a few paragraphs) then a scan similar to the one
in <code>check_hostalias</code> is performed to match any
<code>ServerPath</code> directives given in the vhosts. Note that the
<STRONG>last match</STRONG> is used regardless (again consider the ordering of
the virtual hosts).

<h3>Observations</h3>

<ul>

<li>It is difficult to define an IP-based vhost for the machine's
"main IP address". You essentially have to create a bogus
<code>ServerName</code> for the main_server that does not match the
machine's IPs.
<P>

<li>During the scans in both <code>check_hostalias</code> and
<code>check_serverpath</code> no check is made that the vhost being
scanned is actually a name-based vhost. This means, for example, that
it's possible to match an IP-based vhost through another address. But
because the scan starts in the vhost list at the first vhost that
matched the local IP address of the connection, not all IP-based vhosts
can be matched.
<p>
Consider the config file above with three vhosts A, B, C. Suppose
that B is a named-based vhost, and A and C are IP-based vhosts. If
a request comes in on B or C's address containing a header
"<SAMP>Host: A</SAMP>" then
it will be served from A's config. If a request comes in on A's
address then it will always be served from A's config regardless of
any Host: header.
</p>

<li>Unless you have a <SAMP>_default_</SAMP> vhost,
it doesn't matter if you mix name-based vhosts in amongst IP-based
vhosts. During the <code>find_virtual_server</code> phase above no
named-based vhost will be matched, so the main_server will remain the
connection vhost. Then scans will cover all vhosts in the vhost list.
<p>
If you do have a <SAMP>_default_</SAMP> vhost, then you cannot place
named-based vhosts after it in the config. This is because on any
connection to the main server IPs the connection vhost will always be
the <SAMP>_default_</SAMP> vhost since none of the name-based are
considered during <code>find_virtual_server</code>.
</p>

<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.
<a href="dns-caveats.html">There's more information
available on this and the next two topics</a>.
<p>

<li><code>ServerName</code> should always be set for each vhost. Otherwise
A DNS lookup is required for each vhost.
<p>

<li>A DNS lookup is always required for the main_server's
<code>ServerName</code> (or to generate that if it isn't specified
in the config).
<p>

<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
Host header was available to disambiguate the two.)
<p>

<li>If a vhost that would otherwise be a name-vhost includes a
<code>Port</code> statement that doesn't match the main_server
<code>Port</code> then it will be considered an IP-based vhost.
Then <code>find_virtual_server</code> will match it (because
the ports associated with each address in the address set default
to the port of the main_server) as the connection vhost. Then
<code>check_hostalias</code> will refuse to check any other name-based
vhost because of the port mismatch. The result is that the vhost
will steal all hits going to the main_server address.
<p>

<li>If two IP-based vhosts have an address in common, the vhost appearing
later in the file is always matched. Such a thing might happen
inadvertently. If the config has name-based vhosts and for some reason
the main_server <code>ServerName</code> resolves to the wrong address
then all the name-based vhosts will be parsed as ip-based vhosts.
Then the last of them will steal all the hits.
<P>

<li>The last name-based vhost in the config is always matched for any hit
which doesn't match one of the other name-based vhosts.

</ul>

<h3><a name="whatworks">What Works</a></h3>

<p>In addition to the tips on the <a href="dns-caveats.html#tips">DNS
Issues</a> page, here are some further tips:

<ul>

<li>Place all main_server definitions before any VirtualHost definitions.
(This is to aid the readability of the configuration -- the post-config
merging process makes it non-obvious that definitions mixed in around
virtualhosts might affect all virtualhosts.)
<p>

<li>Arrange your VirtualHosts such
that all name-based virtual hosts come first, followed by IP-based
virtual hosts, followed by any <SAMP>_default_</SAMP> virtual host
<p>

<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 /abcdef").
<p>

<li>Do not use <EM>port-based</EM> vhosts in the same server as
name-based vhosts. A loose definition for port-based is a vhost which
is determined by the port on the server (<em>i.e.</em>, one server with
ports 8000, 8080, and 80 - all of which have different configurations).
<p>

</ul>


</BODY>
</HTML>

1.1 apachen/htdocs/manual/vhosts/examples.html

Index: examples.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>VirtualHost Examples</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<h1 ALIGN="CENTER">Virtual Host examples for common setups</h1>

<h2>Base configuration</h2>

<ul>
<li><A HREF="#ip">IP-based vhosts only</A>
<li><A HREF="#name">Name-based vhosts only</A>
<li><A HREF="#mixed">Mixed name-/IP-based vhosts</A>
<li><A HREF="#port">Port-based vhosts</A>
</ul>

<h2>Additional features</h2>

<ul>
<li><A HREF="#default">Using <code>_default_</code> vhosts</A>
<li><A HREF="#migrate">Migrating a named-based vhost to an IP-based vhost</A>
<li><A HREF="#serverpath">Using the <code>ServerPath</code> directive</A>
</ul>

<HR>

<h3><A NAME="ip">IP-based vhosts only</A></h3>

<ul>

<li><b>Setup 1:</b>
The server machine has two IP addresses (<samp>111.22.33.44</samp>
and <samp>111.22.33.55</samp>)
which resolve to the names <samp>server.domain.tld</samp> and
<samp>www.otherdomain.tld</samp> respectively.
The hostname <samp>www.domain.tld</samp> is an alias (CNAME)
for <samp>server.domain.tld</samp> and will represent the
main server.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
DocumentRoot /www/domain
ServerName www.domain.tld

<VirtualHost 111.22.33.55>
DocumentRoot /www/otherdomain
ServerName www.otherdomain.tld
...
</VirtualHost>
</pre>
<samp>www.otherdomain.tld</samp> can only be reached through the
address <samp>111.22.33.55</samp>, while <samp>www.domain.tld</samp>
can only be reached through <samp>111.22.33.44</samp>
(which represents our main server).
</blockquote>
<p>

<li><b>Setup 2:</b>
Same as setup 1, but we don't want to have a dedicated main server.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
ServerName server.domain.tld

<VirtualHost 111.22.33.44>
DocumentRoot /www/domain
ServerName www.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.55>
DocumentRoot /www/otherdomain
ServerName www.otherdomain.tld
...
</VirtualHost>
</pre>
The main server can never catch a request, because all IP address
of our machine are in use for IP-based virtual hosts
(only <samp>localhost</samp> requests can hit the main server).
</blockquote>
<p>

<li><b>Setup 3:</b>
The server machine has two IP addresses (<samp>111.22.33.44</samp>
and <samp>111.22.33.55</samp>)
which resolve to the names <samp>server.domain.tld</samp> and
<samp>www-cache.domain.tld</samp> respectively.
The hostname <samp>www.domain.tld</samp> is an alias (CNAME)
for <samp>server.domain.tld</samp> and will represent the
main server.
<samp>www-cache.domain.tld</samp> will become our proxy-cache
listening on port 8080, while the web server itself uses the default
port 80.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
Listen 111.22.33.44:80
Listen 111.22.33.55:8080
ServerName server.domain.tld

<VirtualHost 111.22.33.44:80>
DocumentRoot /www/domain
ServerName www.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.55:8080>
ServerName www-cache.domain.tld
...
<Directory proxy:>
order deny,allow
deny from all
allow from 111.22.33
</Directory>
</VirtualHost>
</pre>
The main server can never catch a request, because all IP addresss
(apart from <samp>localhost</samp>) of our machine are in use for IP-based
virtual hosts. The web server can only be reached on the first address
through port 80 and the proxy only on the second address through port 8080.
</blockquote>
</ul>
<HR>

<h3><A NAME="name">Name-based vhosts only</A></h3>

<ul>

<li><b>Setup 1:</b>
The server machine has one IP address (<samp>111.22.33.44</samp>)
which resolves to the name <samp>server.domain.tld</samp>.
There are two aliases (CNAMEs) <samp>www.domain.tld</samp> and
<samp>www.sub.domain.tld</samp> for the address <samp>111.22.33.44</samp>.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
ServerName server.domain.tld

NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
DocumentRoot /www/domain
ServerName www.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.44>
DocumentRoot /www/subdomain
ServerName www.sub.domain.tld
...
</VirtualHost>
</pre>
Apart from <samp>localhost</samp> there are no unspecified
addresses/ports, therefore the main server only serves
<samp>localhost</samp> requests. Due to the fact
that <samp>www.domain.tld</samp> has the highest priority
it can be seen as the <cite>default</cite> or
<cite>primary</cite> server.
</blockquote>
<p>

<li><b>Setup 2:</b>
The server machine has two IP addresses (<samp>111.22.33.44</samp>
and <samp>111.22.33.55</samp>)
which resolve to the names <samp>server1.domain.tld</samp> and
<samp>server2.domain.tld</samp> respectively.
The alias <samp>www.domain.tld</samp> should be used for the
main server which should also catch any unspecified addresses.
We want to use a virtual host for the alias
<samp>www.otherdomain.tld</samp> and one virtual host should
catch any request to hostnames of the form
<samp>*.sub.domain.tld</samp> with <samp>www.sub.domain.tld</samp>
as its server name. The address <samp>111.22.33.55</samp> should be
used for the virtual hosts.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
ServerName www.domain.tld
DocumentRoot /www/domain

NameVirtualHost 111.22.33.55

<VirtualHost 111.22.33.55>
DocumentRoot /www/otherdomain
ServerName www.otherdomain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.55>
DocumentRoot /www/subdomain
ServerName www.sub.domain.tld
ServerAlias *.sub.domain.tld
...
</VirtualHost>
</pre>
Any request to an address other than <samp>111.22.33.55</samp>
will be served from the main server. A request to
<samp>111.22.33.55</samp> with an unknown or no <code>Host:</code>
header will be served from <samp>www.otherdomain.tld</samp>.
</blockquote>
</ul>

<HR>

<h3><A NAME="mixed">Mixed name-/IP-based vhosts</A></h3>

<Ul>

<li><b>Setup:</b>
The server machine has three IP addresses (<samp>111.22.33.44</samp>,
<samp>111.22.33.55</samp> and <samp>111.22.33.66</samp>)
which resolve to the names <samp>server.domain.tld</samp>,
<samp>www.otherdomain1.tld</samp> and <samp>www.otherdomain2.tld</samp>
respectively.
The address <samp>111.22.33.44</samp> should we used for a couple
of name-based vhosts and the other addresses for IP-based vhosts.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
ServerName server.domain.tld

NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
DocumentRoot /www/domain
ServerName www.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.44>
DocumentRoot /www/subdomain1
ServerName www.sub1.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.44>
DocumentRoot /www/subdomain2
ServerName www.sub2.domain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.55>
DocumentRoot /www/otherdomain1
ServerName www.otherdomain1.tld
...
</VirtualHost>

<VirtualHost 111.22.33.66>
DocumentRoot /www/otherdomain2
ServerName www.otherdomain2.tld
...
</VirtualHost>
</pre></blockquote>

</ul>

<HR>

<h3><A NAME="port">Port-based vhosts</A></h3>

<ul>

<li><b>Setup:</b>
The server machine has one IP address (<samp>111.22.33.44</samp>)
which resolves to the name <samp>www.domain.tld</samp>.
If we don't have the option to get another address or alias
for our server we can use port-based vhosts if we need
a virtual host with a different configuration.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Listen 80
Listen 8080
ServerName www.domain.tld
DocumentRoot /www/domain

<VirtualHost 111.22.33.44:8080>
DocumentRoot /www/domain2
...
</VirtualHost>
</pre>
A request to <samp>www.domain.tld</samp> on port 80 is served
from the main server and a request to port 8080 is served from
the virtual host.
</blockquote>
</ul>

<HR>

<h3><A NAME="default">Using <code>_default_</code> vhosts</A></h3>

<ul>

<li><b>Setup 1:</b>
Catching <em>every</em> request to any unspecified IP address and port,
i.e. an address/port combination that is not used for any other
virtual host.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
<VirtualHost _default_:*>
DocumentRoot /www/default
...
</VirtualHost>
</pre>
Using such a default vhost with a wildcard port effectively
prevents any request going to the main server.<br>
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).<br>
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).
</blockquote>
<p>

<li><b>Setup 2:</b>
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>
<b>Server configuration:</b>

<blockquote><pre>
...
<VirtualHost _default_:80>
DocumentRoot /www/default80
...
</VirtualHost>

<VirtualHost _default_:*>
DocumentRoot /www/default
...
</VirtualHost>
</pre>
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.
</blockquote>
<p>

<li><b>Setup 3:</b>
We want to have a default vhost for port 80, but no other default vhosts.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
<VirtualHost _default_:80>
DocumentRoot /www/default
...
</VirtualHost>
</pre>
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.
</blockquote>

</ul>

<HR>

<h3><A NAME="migrate">Migrating a name-based vhost to an IP-based vhost</A></h3>

<ul>

<li><b>Setup:</b>
The name-based vhost with the hostname
<samp>www.otherdomain.tld</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>111.22.33.66</samp>) to the <code>VirtualHost</code> directive.
<p>
<b>Server configuration:</b>

<blockquote><pre>
...
Port 80
ServerName www.domain.tld
DocumentRoot /www/domain

NameVirtualHost 111.22.33.55

<VirtualHost 111.22.33.55 111.22.33.66>
DocumentRoot /www/otherdomain
ServerName www.otherdomain.tld
...
</VirtualHost>

<VirtualHost 111.22.33.55>
DocumentRoot /www/subdomain
ServerName www.sub.domain.tld
ServerAlias *.sub.domain.tld
...
</VirtualHost>
</pre>
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).
</blockquote>

</ul>

<HR>

<h3><A NAME="serverpath">Using the <code>ServerPath</code> directive</A></h3>

<ul>

<li><b>Setup:</b>
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>
<b>Server configuration:</b>

<blockquote><pre>
...
NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
# primary vhost
DocumentRoot /www/subdomain
RewriteEngine On
RewriteRule ^/.* /www/subdomain/index.html
...
</VirtualHost>

<VirtualHost 111.22.33.44>
DocumentRoot /www/subdomain/sub1
ServerName www.sub1.domain.tld
ServerPath /sub1/
RewriteEngine On
RewriteRule ^(/sub1/.*) /www/subdomain$1
...
</VirtualHost>

<VirtualHost 111.22.33.44>
DocumentRoot /www/subdomain/sub2
ServerName www.sub2.domain.tld
ServerPath /sub2/
RewriteEngine On
RewriteRule ^(/sub2/.*) /www/subdomain$1
...
</VirtualHost>
</pre>
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, i.e. with or without URL prefix.
</blockquote>

</ul>


</BODY>
</HTML>

1.1 apachen/htdocs/manual/vhosts/fd-limits.html

Index: fd-limits.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Apache Server Virtual Host Support</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<h1 ALIGN="CENTER">File Descriptor Limits</h1>

<P>
When using a large number of Virtual Hosts, Apache may run out of available
file descriptors (sometimes called <cite>file handles</cite> if each Virtual
Host specifies different log files.
The total number of file descriptors used by Apache is one for each distinct
error log file, one for every other log file directive, plus 10-20 for
internal use. Unix operating systems limit the number of file descriptors that
may be used by a process; the limit is typically 64, and may usually be
increased up to a large hard-limit.
<p>
Although Apache attempts to increase the limit as required, this
may not work if:
<ol>
<li>Your system does not provide the setrlimit() system call.
<li>The setrlimit(RLIMIT_NOFILE) call does not function on your system
(such as Solaris 2.3)
<li>The number of file descriptors required exceeds the hard limit.
<li>Your system imposes other limits on file descriptors, such as a limit
on stdio streams only using file descriptors below 256. (Solaris 2)
</ol>

In the event of problems you can:
<ul>
<li>Reduce the number of log files; don't specify log files in the VirtualHost
sections, but only log to the main log files.
<li>If you system falls into 1 or 2 (above), then increase the file descriptor
limit before starting Apache, using a script like
<blockquote><code>
#!/bin/sh <br>
ulimit -S -n 100 <br>
exec httpd</code></blockquote>
</ul>
<P>
Please see the
<A HREF="../misc/descriptors.html">Descriptors and Apache</A>
document containing further details about file descriptor problems and how
they can be solved on your operating system.
</P>


</body></html>

1.1 apachen/htdocs/manual/vhosts/footer.html

Index: footer.html
===================================================================
<HR>
<H3 ALIGN="CENTER">
Apache HTTP Server Version 1.3
</H3>

<A HREF="./"><IMG SRC="images/index.gif" ALT="Index"></A>

1.1 apachen/htdocs/manual/vhosts/header.html

Index: header.html
===================================================================
<DIV ALIGN="CENTER">
<IMG SRC="images/sub.gif" ALT="[APACHE DOCUMENTATION]">
<H3>
Apache HTTP Server Version 1.3
</H3>
</DIV>

1.1 apachen/htdocs/manual/vhosts/index.html

Index: index.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<HTML>
<HEAD>
<TITLE>Apache Virtual Host documentation</TITLE>
</HEAD>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<H1 ALIGN="CENTER">Apache Virtual Host documentation</h1>

<p>The term <cite>Virtual Host</cite> refers to the practice of maintaining
more than one server on one machine, as differentiated by their apparent
hostname. For example, it is often desirable for companies sharing a
web server to have their own domains, with web servers accessible as
<samp>www.company1.com</samp> and <samp>www.company2.com</samp>,
without requiring the user to know any extra path information.</p>

<p>Apache was one of the first servers to support IP-based
virtual hosts right out of the box. Versions 1.1 and later of
Apache support both, IP-based and name-based virtual hosts (vhosts).
The latter variant of virtual hosts is sometimes also called host-based or
non-IP virtual hosts.</P>

<P>Below is a list of documentation pages which explain all details
of virtual host support in Apache version 1.3 and later.</P>

<HR>

<H2>Virtual Host Support</H2>

<UL>
<LI><A HREF="ip-based.html">IP-based Virtual Hosts</A>
<LI><A HREF="name-based.html">Name-based Virtual Hosts</A>
<LI><A HREF="examples.html">Virtual Host examples for common setups</A>
<LI><A HREF="details.html">In-Depth Discussion of Virtual Host Matching</A>
<LI><A HREF="fd-limits.html">File Descriptor Limits</A>
</UL>

<H2>Configuration directives</H2>

<UL>
<LI><A HREF="../mod/core.html#virtualhost"><VirtualHost></A>
<LI><A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>
<LI><A HREF="../mod/core.html#servername">ServerName</A>
<LI><A HREF="../mod/core.html#serveralias">ServerAlias</A>
<LI><A HREF="../mod/core.html#serverpath">ServerPath</A>
</UL>


</BODY>
</HTML>

1.1 apachen/htdocs/manual/vhosts/ip-based.html

Index: ip-based.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html>
<head>
<title>Apache IP-based Virtual Host Support</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<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).

<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:
<ul>
<li>The different virtual hosts need very different httpd configurations, such
as different values for: <A HREF="../mod/core.html#servertype">ServerType</A>,
<A HREF="../mod/core.html#user">User</A>,
<A HREF="../mod/core.html#group">Group</A>,
<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A> or
<A HREF="../mod/core.html#serverroot">ServerRoot</A>.
<li>The machine does not process a very high request rate.
</ul>
Use a single daemon when:
<ul>
<li>Sharing of the httpd configuration between virtual hosts is acceptable.
<li>The machine services a large number of requests, and so the performance
loss in running separate daemons may be significant.
</ul>

<h2>Setting up multiple daemons</h2>
Create a separate httpd installation for each virtual host.
For each installation, use the
<A HREF="../mod/core.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 page</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 page</A>).

<P>

Almost <strong>any</strong> configuration directive can be put
in the VirtualHost directive, with the exception of
<A HREF="../mod/core.html#servertype">ServerType</A>,
<A HREF="../mod/core.html#startservers">StartServers</A>,
<A HREF="../mod/core.html#maxspareservers">MaxSpareServers</A>,
<A HREF="../mod/core.html#minspareservers">MinSpareServers</A>,
<A HREF="../mod/core.html#maxrequestsperchild">MaxRequestsPerChild</A>,
<A HREF="../mod/core.html#bindaddress">BindAddress</A>,
<A HREF="../mod/core.html#listen">Listen</A>,
<A HREF="../mod/core.html#pidfile">PidFile</A>,
<A HREF="../mod/mod_mime.html#typesconfig">TypesConfig</A>,
<A HREF="../mod/core.html#serverroot">ServerRoot</A> and
<A HREF="../mod/core.html#namevirtualhost">NameVirtualHost</A>.
<P>
<A HREF="../mod/core.html#user">User</A> and
<A HREF="../mod/core.html#group">Group</A> maybe used inside a VirtualHost
directive if the <A HREF="../suexec.html">suEXEC wrapper</A> is used.
<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>


</body>
</html>

1.1 apachen/htdocs/manual/vhosts/name-based.html

Index: name-based.html
===================================================================
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
<html><head>
<title>Apache name-based Virtual Hosts</title>
</head>


<BODY
BGCOLOR="#FFFFFF"
TEXT="#000000"
LINK="#0000FF"
VLINK="#000080"
ALINK="#FF0000"
>

<h1 ALIGN="CENTER">Apache name-based Virtual Host Support</h1>

<strong>See Also:</strong>
<a href="ip-based.html">IP-based Virtual Host Support</a>

<hr>

<h2>Name-based vs. IP-based virtual hosts</h2>

<p>While the approach with IP-based virtual hosts works still very well,
it is not the most elegant solution, because a dedicated IP address
is needed for every virtual host and it is hard to implement on some
machines. The <code>HTTP/1.1</code> protocol contains a method for the
server to identify what name it is being addressed as. Apache 1.1 and
later support this approach as well as the traditional
IP-address-per-hostname method.</p>

<p>The benefits of using the new name-based virtual host support is a
practically unlimited number of servers, ease of configuration and use, and
requires no additional hardware or software.
The main disadvantage is that the client must support this part of the
protocol. The latest versions of most browsers do, but there are still
old browsers in use who do not. This can cause problems, although a possible
solution is addressed below.</p>

<h2>Using non-IP Virtual Hosts</h2>

<p>Using the new virtual hosts is quite easy, and superficially looks
like the old method. You simply add to one of the Apache configuration
files (most likely <code>httpd.conf</code> or <code>srm.conf</code>)
code similar to the following:</p>
<pre>
NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
ServerName www.domain.tld
DocumentRoot /web/domain
</VirtualHost>
</pre>

<p>The notable difference between IP-based and name-based virtual host
configuration is the
<A HREF="../mod/core.html#namevirtualhost"><code>NameVirtualHost</code></A>
directive which specifies any IP address that should be used as a target for
name-based virtual hosts.

<p>Of course, any additional directives can (and should) be placed
into the <code><VirtualHost></code> section. To make this work,
all that is needed is to make sure that the name
<samp>www.domain.tld</samp> is an alias (CNAME) pointing to the IP address
<samp>111.22.33.44</samp></p>

<p>Additionally, many servers may wish to be accessible by more than
one name. For example, the example server might want to be accessible
as <code>domain.tld</code>, or <code>www2.domain.tld</code>, assuming
the IP addresses pointed to the same server. In fact, one might want it
so that all addresses at <code>domain.tld</code> were picked up by the
server. This is possible with the
<A HREF="../mod/core.html#serveralias"><code>ServerAlias</code></A>
directive, placed inside the <VirtualHost> section. For
example:</p>

<pre>
ServerAlias domain.tld *.domain.tld
</pre>

<p>Note that you can use <code>*</code> and <code>?</code> as wild-card
characters.</p>

<p>You also might need <code>ServerAlias</code> if you are
serving local users who do not always include the domain name.
For example, if local users are
familiar with typing "www" or "www.foobar" then you will need to add
<code>ServerAlias www www.foobar</code>. It isn't possible for the
server to know what domain the client uses for their name resolution
because the client doesn't provide that information in the request.</p>

<h2>Compatibility with Older Browsers</h2>

<p>As mentioned earlier, there are still some clients in use who
do not send the required data for the name-based virtual hosts to work
properly. These clients will always be sent the pages from the
<cite>primary</cite> name-based virtual host (the first virtual host
appearing in the configuration file for a specific IP address).</p>

<p>There is a possible workaround with the
<A HREF="../mod/core.html#serverpath"><code>ServerPath</code></A>
directive, albeit a slightly cumbersome one:</p>

<p>Example configuration:

<pre>
NameVirtualHost 111.22.33.44

<VirtualHost 111.22.33.44>
ServerName www.domain.tld
ServerPath /domain
DocumentRoot /web/domain
</VirtualHost>
</pre>

<p>What does this mean? It means that a request for any URI beginning
with "<samp>/domain</samp>" will be served from the virtual host
<samp>www.domain.tld</samp> This means that the pages can be accessed as
<code>http://www.domain.tld/domain/</code> for all clients, although
clients sending a <samp>Host:</samp> header can also access it as
<code>http://www.domain.tld/</code>.</p>

<p>In order to make this work, put a link on your primary virtual host's page
to <samp>http://www.domain.tld/domain/</samp>
Then, in the virtual host's pages, be sure to use either purely
relative links (e.g. "<samp>file.html</samp>" or
"<samp>../icons/image.gif</samp>" or links containing the prefacing
<samp>/domain/</samp>
(e.g. "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or
"<samp>/domain/misc/file.html</samp>").</p>

<p>This requires a bit of
discipline, but adherence to these guidelines will, for the most part,
ensure that your pages will work with all browsers, new and old.</p>

<p>See also: <A HREF="examples.html#serverpath">ServerPath configuration
example</A></p>


</BODY>
</HTML>