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 <[EMAIL PROTECTED]> 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 @@ <!--#include virtual="header.html" --> <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> +<!--%plaintext <?INDEX {\tt NameVirtualHost} directive> --> +<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> <!--%plaintext <?INDEX {\tt Options} directive> --> <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> <!-- 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 <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> <!--#include virtual="footer.html" --> </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> <!-- 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 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> <!--#include virtual="footer.html" --> </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> <!-- 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> <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> <!--#include virtual="footer.html" --> </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> <!-- 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">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> <!--#include virtual="footer.html" --> </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> <!-- 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 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> <!--#include virtual="footer.html" --> </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> <!-- 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). <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 [EMAIL PROTECTED] 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 [EMAIL PROTECTED] 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> <!--#include virtual="footer.html" --> </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> <!-- 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 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> <!--#include virtual="footer.html" --> </BODY> </HTML>