Doc for r1053230, NameVirtualHost is now unnecessary and other general NVH-vs-VH improvements.

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1053231 13f79535-47bb-0310-9956-ffa450edef68

6 files changed, 75 insertions, 215 deletions

diff --git a/docs/manual/vhosts/details.xml b/docs/manual/vhosts/details.xml
index 5702131a68..8fc83fd933 100644
--- a/docs/manual/vhosts/details.xml
+++ b/docs/manual/vhosts/details.xml
@@ -66,16 +66,10 @@
     resolutions fail, those virtual host definitions are ignored.
     This is, therefore, not recommended.</p>
 
-    <p>If using IP-based vhosts, the address can be specified
-    as <code>_default_</code>, which will match a request if no
-    other vhost has the explicit address on which the request was
-    received.</p>
-
-    <p>If using name-based vhosts, the address can be specified as
+    <p>The address can be specified as
     <code>*</code>, which will match a request if no
     other vhost has the explicit address on which the request was
-    received.  The corresponding <code>NameVirtualHost</code>
-    directive must also use <code>*</code>.</p>
+    received. </p> 
 
     <p>The address appearing in the <code>VirtualHost</code>
     directive can have an optional port. If the port is unspecified,
@@ -95,11 +89,10 @@
     results from DNS lookups) are called the vhost's
     <em>address set</em>.</p>
 
-    <p>If you want Apache to discriminate on the
-    basis of the HTTP <code>Host</code> header supplied by the client,
-    the <code>NameVirtualHost</code> directive <em>must</em> appear
-    with the exact IP address (or wildcard) and port pair used in a
-    corresponding set of <code>VirtualHost</code> directives.</p>
+    <p>Apache automatically discriminates on the
+    basis of the HTTP <code>Host</code> header supplied by the client
+    whenever the most specific match for an IP address and port combination
+    is listed in multiple virtual hosts.</p>
 
     <p>The 
     <directive module="core">ServerName</directive> directive
@@ -108,11 +101,6 @@
     server).  If no <code>ServerName</code> is specified, the server
     attempts to deduce it from the server's IP address.</p>
 
-    <p>Multiple <code>NameVirtualHost</code> directives can be used,
-    each with a set of <code>VirtualHost</code> directives, but only
-    one <code>NameVirtualHost</code> directive should be used for
-    each specific IP:port pair.</p>
-
     <p>The first name-based vhost in the configuration file for a
     given IP:port pair is significant because it is used for all
     requests received on that address and port for which no other
@@ -121,66 +109,6 @@
     server does not support <glossary
     ref="servernameindication">Server Name Indication</glossary>.</p>
 
-    <p>If there are no vhosts defined for an address in a
-    <code>NameVirtualHost</code> directive, the
-    <code>NameVirtualHost</code> directive is ignored at startup and an error is
-    logged.</p>
-
-    <p>The ordering of <code>NameVirtualHost</code> and
-    <code>VirtualHost</code> directives is not important, which
-    makes the following two examples identical (only the order of
-    the <code>VirtualHost</code> directives for <em>one</em>
-    address set is important, see below):</p>
-
-<table><tr>
-<td><example>
-  NameVirtualHost 111.22.33.44<br />
-  &lt;VirtualHost 111.22.33.44&gt;<br />
-  # server A<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  &lt;VirtualHost 111.22.33.44&gt;<br />
-  # server B<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  <br />
-  NameVirtualHost 111.22.33.55<br />
-  &lt;VirtualHost 111.22.33.55&gt;<br />
-  # server C<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  &lt;VirtualHost 111.22.33.55&gt;<br />
-  # server D<br />
-  ...<br />
-  &lt;/VirtualHost&gt;
-</example></td>
-<td><example>
-  &lt;VirtualHost 111.22.33.44&gt;<br />
-  # server A<br />
-  &lt;/VirtualHost&gt;<br />
-  &lt;VirtualHost 111.22.33.55&gt;<br />
-  # server C<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  &lt;VirtualHost 111.22.33.44&gt;<br />
-  # server B<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  &lt;VirtualHost 111.22.33.55&gt;<br />
-  # server D<br />
-  ...<br />
-  &lt;/VirtualHost&gt;<br />
-  <br />
-  NameVirtualHost 111.22.33.44<br />
-  NameVirtualHost 111.22.33.55<br />
-  <br />
-</example></td>
-</tr></table>
-
-
-    <p>(To aid the readability of your configuration you should
-    prefer the left variant.)</p>
-
     <p>For every vhost various default values are set. In
     particular:</p>
 
@@ -245,10 +173,6 @@
     <p>If there are no exact matches for the address and port, then
     wildcard (<code>*</code>) matches are considered.</p>
 
-    <p>If there are still no matches, then vhosts with IP
-    address specified as <code>_default_</code> that match the
-    port are considered.</p>
-
     <p>If no matches are found, the request is served by the
     main server.</p>
 
@@ -260,17 +184,19 @@
 
     <section id="ipbased"><title>IP-based vhost</title>
 
-    <p>If there is no <code>NameVirtualHost</code> directive
-    matching the vhost, no further actions are performed and
-    the request is served from the first matching vhost.</p>
+    <p>If there is exactly one <code>VirtualHost</code> directive
+    listing the IP address and port combibation that was determined
+    to be the best match, no further actions are performed and
+    the request is served from the matching vhost.</p>
 
     </section>
 
     <section id="namebased"><title>Name-based vhost</title>
 
-    <p>If the entry corresponds to a name-based vhost, the "list" in
-    the remaining steps refers to the list of vhosts that matched, in
-    the order they were in the configuration file.</p>
+    <p>If there are multiple <code>VirtalHost</code> directives listing
+    the IP address and port combination that was determined to be the
+    best match, the "list" in the remaining steps refers to the list of vhosts 
+    that matched, in the order they were in the configuration file.</p>
 
     <p>If the connection is using SSL, the server supports <glossary
     ref="servernameindication">Server Name Indication</glossary>, and
@@ -324,20 +250,18 @@
 <section id="observations"><title>Observations</title>
 
     <ul>
-      <li>A name-based vhost can never interfere with an IP-base
-      vhost and vice versa. IP-based vhosts can only be reached
-      through an IP address of its own address set and never
-      through any other address. The same applies to name-based
-      vhosts, they can only be reached through an IP address of the
-      corresponding address set which must be defined with a
-      <code>NameVirtualHost</code> directive.</li>
-
-      <li><code>ServerAlias</code>
+      <li>Name-based virtual hosting is a process applied after
+      the server has selected the best matching IP-based virtual
+      host.</li>
+
+      <li>If you don't care what IP address the client has connected to, use a
+      "*" as the address of every virtual host, and name-based virtual hosting
+      is applied across all configured virtual hosts.</li>
+
+      <li><code>ServerName</code> and <code>ServerAlias</code>
       checks are never performed for an IP-based vhost.</li>
 
-      <li>The order of name-/IP-based, the <code>_default_</code>
-      vhost and the <code>NameVirtualHost</code> directive within
-      the config file is not important. Only the ordering of
+      <li>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
@@ -347,39 +271,18 @@
       matching process. Apache always uses the real port to which
       the client sent the request.</li>
 
-      <li>If two IP-based vhosts have an address in common, the
-      vhost appearing first in the config file is always matched.
-      Such a thing might happen inadvertently. The server will give
-      a warning in the error logfile when it detects this.</li>
-
-      <li>A <code>_default_</code> vhost catches a request only if
-      there is no other vhost with a matching IP address
-      <em>and</em> a matching port number for the request. The
-      request is only caught if the port number to which the client
-      sent the request matches the port number of your
-      <code>_default_</code> vhost which is your standard
-      <code>Listen</code> by default. A wildcard port can be
-      specified (<em>i.e.</em>, <code>_default_:*</code>) to catch
-      requests to any available port. This also applies to
-      <code>NameVirtualHost *</code> vhosts.  Note that this is simply an
-      extension of the "best match" principle, as a specific and exact match
-      is favored over a wildcard.</li>
+      <li>If two vhosts have an address in common, those common addresses
+      act as name-based virtual hosts implicitly.  This is new behavior as of 
+      2.3.11.</li>
 
       <li>The main server is only used to serve a request if the IP
       address and port number to which the client connected 
       does not match any vhost (including a
-      <code>_default_</code> vhost). In other words, the main server
+      <code>*</code> vhost). In other words, the main server
       only catches a request for an unspecified address/port
       combination (unless there is a <code>_default_</code> vhost
       which matches that port).</li>
 
-      <li>A <code>_default_</code> vhost or the main server is
-      <em>never</em> matched for a request with an unknown or
-      missing <code>Host:</code> header field if the client
-      connected to an address (and port) which is used for
-      name-based vhosts, <em>e.g.</em>, in a
-      <code>NameVirtualHost</code> directive.</li>
-
       <li>You should never specify DNS names in
       <code>VirtualHost</code> directives because it will force
       your server to rely on DNS to boot. Furthermore it poses a
@@ -408,10 +311,6 @@
       readability of the configuration -- the post-config merging
       process makes it non-obvious that definitions mixed in around
       virtual hosts might affect all virtual hosts.)</li>
-
-      <li>Group corresponding <code>NameVirtualHost</code> and
-      <code>VirtualHost</code> definitions in your configuration to
-      ensure better readability.</li>
     </ul>
 
 </section>
diff --git a/docs/manual/vhosts/examples.xml b/docs/manual/vhosts/examples.xml
index ef6ec3010f..4a70b5a979 100644
--- a/docs/manual/vhosts/examples.xml
+++ b/docs/manual/vhosts/examples.xml
@@ -59,8 +59,6 @@
     # Ensure that Apache listens on port 80<br />
     Listen 80<br />
     <br />
-    # Listen for virtual host requests on all IP addresses<br />
-    NameVirtualHost *:80<br />
     <br />
     &lt;VirtualHost *:80&gt;<br />
     <indent>
@@ -95,17 +93,9 @@
     <note>
             <title>Note</title>
 
-            <p>You can, if you wish, replace <code>*</code> with the actual
-            IP address of the system. In that case, the argument to
-            <code>VirtualHost</code> <em>must</em> match the argument to
-            <code>NameVirtualHost</code>:</p>
-
-            <example>
-            NameVirtualHost 172.20.30.40<br />
-            <br />
-            &lt;VirtualHost 172.20.30.40&gt;<br />
-             # etc ...
-            </example>
+           <p>You can, if you wish, replace <code>*</code> with the actual
+           IP address of the system, when you don't care to discriminate based
+           on the IP address or port.</p>
 
            <p>However, it is additionally useful to use <code>*</code>
            on systems where the IP address is not predictable - for
@@ -145,9 +135,6 @@
     ServerName server.example.com<br />
     DocumentRoot /www/mainserver<br />
     <br />
-    # This is the other address<br />
-    NameVirtualHost 172.20.30.50<br />
-    <br />
     &lt;VirtualHost 172.20.30.50&gt;<br />
     <indent>
         DocumentRoot /www/example1<br />
@@ -195,8 +182,6 @@
     <example>
     <title>Server configuration</title>
 
-    NameVirtualHost 192.168.1.1<br />
-    NameVirtualHost 172.20.30.40<br />
     <br />
     &lt;VirtualHost 192.168.1.1 172.20.30.40&gt;<br />
     <indent>
@@ -227,10 +212,9 @@
     ports.</title>
 
     <p>You have multiple domains going to the same IP and also want to
-    serve multiple ports. By defining the ports in the "NameVirtualHost"
-    tag, you can allow this to work. If you try using &lt;VirtualHost
-    name:port&gt; without the NameVirtualHost name:port or you try to use
-    the Listen directive, your configuration will not work.</p>
+    serve multiple ports.  The example below illustrates that the name-matching
+    takes place after the best matching IP address and port combination
+    is determined.</p>
 
     <example>
     <title>Server configuration</title>
@@ -238,9 +222,6 @@
     Listen 80<br />
     Listen 8080<br />
     <br />
-    NameVirtualHost 172.20.30.40:80<br />
-    NameVirtualHost 172.20.30.40:8080<br />
-    <br />
     &lt;VirtualHost 172.20.30.40:80&gt;<br />
     <indent>
         ServerName www.example.com<br />
@@ -357,16 +338,13 @@
   <section id="mixed"><title>Mixed name-based and IP-based
     vhosts</title>
 
-    <p>On some of my addresses, I want to do name-based virtual hosts, and
-    on others, IP-based hosts.</p>
+    <p>Any address mentioned in the argument to a virtualhost that never
+    appears in another virtual host is a strictly IP-based virtual host.</p>
 
     <example>
     <title>Server configuration</title>
 
     Listen 80<br />
-    <br />
-    NameVirtualHost 172.20.30.40<br />
-    <br />
     &lt;VirtualHost 172.20.30.40&gt;<br />
     <indent>
         DocumentRoot /www/example1<br />
@@ -540,8 +518,6 @@
     ServerName www.example.com<br />
     DocumentRoot /www/example1<br />
     <br />
-    NameVirtualHost 172.20.30.40<br />
-    <br />
     &lt;VirtualHost 172.20.30.40 172.20.30.50&gt;<br />
     <indent>
         DocumentRoot /www/example2<br />
@@ -581,8 +557,6 @@
     <example>
     <title>Server configuration</title>
 
-    NameVirtualHost 172.20.30.40<br />
-    <br />
     &lt;VirtualHost 172.20.30.40&gt;<br />
     <indent>
         # primary vhost<br />
diff --git a/docs/manual/vhosts/index.xml b/docs/manual/vhosts/index.xml
index fbb2c247fe..055a404fa4 100644
--- a/docs/manual/vhosts/index.xml
+++ b/docs/manual/vhosts/index.xml
@@ -82,7 +82,6 @@ hosts</a></seealso>
     <ul>
       <li><directive type="section"
            module="core">VirtualHost</directive></li>
-      <li><directive module="core">NameVirtualHost</directive></li>
       <li><directive module="core">ServerName</directive></li>
       <li><directive module="core">ServerAlias</directive></li>
       <li><directive module="core">ServerPath</directive></li>
diff --git a/docs/manual/vhosts/ip-based.xml b/docs/manual/vhosts/ip-based.xml
index 24196c0e4d..9fde89fe51 100644
--- a/docs/manual/vhosts/ip-based.xml
+++ b/docs/manual/vhosts/ip-based.xml
@@ -28,6 +28,18 @@
 <a href="name-based.html">Name-based Virtual Hosts Support</a>
 </seealso>
 
+<section id="explanation"><title>What is IP-based virtual hosting</title>
+<p>IP-based virtual hosting is a method to apply different directives
+based on the IP address and port a request is received on.  Most commonly,
+this is used to serve different websites on different ports or interfaces.</p>
+
+<p>In many cases, <a href="name-based.html">name-based
+virtual hosts</a> are more convenient, because they allow
+many virtual hosts to share a single address/port.
+See <a href="name-based.html#namevip">Name-based vs. IP-based
+Virtual Hosts</a> to help you decide.  </p>
+</section>
+
 <section id="requirements"><title>System requirements</title>
 
     <p>As the term <cite>IP-based</cite> indicates, the server
@@ -40,12 +52,8 @@
     most commonly used to set them up), and/or using multiple
     port numbers.</p>
 
-    <p>In many cases, <a href="name-based.html">name-based
-    virtual hosts</a> are more convenient, because they allow
-    many virtual hosts to share a single address/port.
-    See <a href="name-based.html#namevip">Name-based vs. IP-based
-    Virtual Hosts</a> to help you decide.
-    </p>
+    <p> In the terminology of Apache HTTP Servr, using a single IP address 
+    but multiple TCP ports, is also IP-based virtual hosting.</p>
 
 </section>
 
@@ -147,6 +155,10 @@
     hostname in the &lt;VirtualHost&gt; directive
     (see <a href="../dns-caveats.html">DNS caveats</a>).</p>
 
+    <p> Specific IP addresses or ports have precedence over their wildcard
+    equivalents, and any virtual host that matches has precedence over
+    the servers base configuration.</p> 
+
     <p>Almost <strong>any</strong> configuration directive can be
     put in the VirtualHost directive, with the exception of
     directives that control process creation and a few other
diff --git a/docs/manual/vhosts/mass.xml b/docs/manual/vhosts/mass.xml
index 4755130667..227e95fb50 100644
--- a/docs/manual/vhosts/mass.xml
+++ b/docs/manual/vhosts/mass.xml
@@ -43,7 +43,6 @@
 
 <example>
 <pre>
-NameVirtualHost 111.22.33.44
 &lt;VirtualHost 111.22.33.44&gt;
     ServerName                 customer-1.example.com
     DocumentRoot        /www/hosts/customer-1.example.com/docs
diff --git a/docs/manual/vhosts/name-based.xml b/docs/manual/vhosts/name-based.xml
index 476547d355..1ff58e0875 100644
--- a/docs/manual/vhosts/name-based.xml
+++ b/docs/manual/vhosts/name-based.xml
@@ -62,6 +62,10 @@
         they are on separate IP addresses.</li>
     </ul>
 
+    <p> Name-based virtual hosting builds off of the IP-based virtual host
+    selection algoirthm, meaning that searches for the proper server name
+    occur only between virtual hosts that have the best IP-based address.</p>
+
 
 </section>
 
@@ -71,23 +75,22 @@
     host resolution is IP-based resolution.  Name-based virtual host
     resolution only chooses the most appropriate name-based virtual host
     after narrowing down the candidates to the best IP-based match.  Using a wildcard (*)
-    for the IP address in all of the NameVirtualHost and VirtualHost directives makes this
+    for the IP address in all of the VirtualHost directives makes this
     IP-based mapping irrelevant.</p>
     
-    <p>When a request arrives, the server will first check if it is using
-    an IP address that matches exactly any <directive module="core"
-    >NameVirtualHost</directive>. If it is, then it will look at each <directive
-    type="section" module="core">VirtualHost</directive> section with a (literal) matching
-    IP address and try to find one where the <directive module="core"
-    >ServerName</directive> or <directive module="core" >ServerAlias</directive> 
-    matches the requested hostname. If it finds one, then it uses the configuration 
-    for that server.</p>
-
-    <section id="defaultvhost"><title>The default name-based vhost for a NameVirtualHost</title>
-    <p> If no matching ServerName or ServerAlias is found in the
-    set of virtual hosts matching the NameVirtualHost directive, then 
-    <strong>the first listed virtual host</strong> that matches the IP 
-    address will be used.</p></section>
+    <p>When a request arrives, the server will find the best (most specific) matching  
+    <directive type="section" module="core">VirtualHost</directive> argument based on
+    the IP address and port used by the request.  If there is more than one virtual host
+    contanin this best-match address and port combination,  Apache will further
+    compare the <directive module="core" >ServerName</directive> and <directive 
+    module="core">ServerAlias</directive>  directives to the server name
+    present in the request.</p>
+
+    <section id="defaultvhost"><title>The default name-based vhost for an IP and port combination </title>
+    <p> If no matching ServerName or ServerAlias is found in the set of 
+    virtual hosts containing the most specific matching IP address and port 
+    combination, then <strong>the first listed virtual host</strong> that 
+    matches the will be used.</p></section>
 </section>
 
 <section id="using"><title>Using Name-based Virtual Hosts</title>
@@ -99,38 +102,15 @@
 
     <directivelist>
         <directive module="core">DocumentRoot</directive>
-        <directive module="core">NameVirtualHost</directive>
         <directive module="core">ServerAlias</directive>
         <directive module="core">ServerName</directive>
         <directive module="core" type="section">VirtualHost</directive>
     </directivelist>
 </related>
 
-    <p>To use name-based virtual hosting, you must designate the IP
-    address (and possibly port) on the server that will be accepting
-    requests that need to be distinguished by hostname.
-    This is configured using the <directive
-    module="core">NameVirtualHost</directive> directive.
-    In the normal case where any and all IP addresses on the server should
-    be used, you can use <code>*</code> as the argument to <directive
-    module="core">NameVirtualHost</directive>. If you're planning to use
-    multiple ports (e.g. running SSL) you should add a Port to the argument,
-    such as <code>*:80</code>.</p>
-
-    <note><p>Note that mentioning an IP address in a
-    <directive module="core">NameVirtualHost</directive> directive does not
-    automatically make the server <em>listen</em> to that IP address. See
-    <a href="../bind.html">Setting which addresses and ports Apache uses</a>
-    for more details. In addition, any IP address specified here must be
-    associated with a network interface on the server.</p></note>
-
-    <p>The next step is to create a <directive type="section"
+    <p>The first step is to create a <directive type="section"
     module="core">VirtualHost</directive> block for
-    each different host that you would like to serve. The argument to the
-    <directive type="section" module="core">VirtualHost</directive> directive
-    must match a defined <directive
-    module="core">NameVirtualHost</directive> directive. (In this usual case,
-    this will be "*:80").  Inside each <directive type="section"
+    each different host that you would like to serve.  Inside each <directive type="section"
     module="core">VirtualHost</directive> block, you will need at minimum a
     <directive module="core">ServerName</directive> directive to designate
     which host is served and a <directive module="core">DocumentRoot</directive>
@@ -158,8 +138,6 @@
     Then you simply add the following to <code>httpd.conf</code>:</p>
 
     <example>
-        NameVirtualHost *:80<br />
-        <br />
         &lt;VirtualHost *:80&gt;<br />
         <indent>
             # This first-listed virtual host is also the default for *:80
@@ -177,8 +155,7 @@
     </example>
 
     <p>You can alternatively specify an explicit IP address in place of the
-    <code>*</code> in both the <directive module="core"
-    >NameVirtualHost</directive> and <directive type="section" module="core"
+    <code>*</code> in <directive type="section" module="core"
     >VirtualHost</directive> directives. For example, you might want to do this
     in order to run some name-based virtual hosts on one IP address, and either
     IP-based, or another set of name-based virtual hosts on another address.</p>