Conversion into XML

Submitted by: Luiz Rocha <lsdr@lsdr.net>

Additionally changed:
- changed <samp> to <code>
- removed <pre> from emaples
- restructured example.xml


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

1 files changed, 416 insertions, 0 deletions

diff --git a/docs/manual/vhosts/details.xml b/docs/manual/vhosts/details.xml
new file mode 100644
index 0000000000..8212402b6e
--- /dev/null
+++ b/docs/manual/vhosts/details.xml
@@ -0,0 +1,416 @@
+<?xml version='1.0' encoding='UTF-8' ?>
+<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
+<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
+
+<manualpage>
+<relativepath href=".."/>
+
+   <title>An In-Depth Discussion of Virtual Host Matching</title>
+
+<summary>
+
+    <p>The virtual host code was completely rewritten in
+    <strong>Apache 1.3</strong>. This document attempts to explain
+    exactly what Apache does when deciding what virtual host to
+    serve a hit from. With the help of the new
+    <directive module="core">NameVirtualHost</directive>
+    directive virtual host configuration should be a lot easier and
+    safer than with versions prior to 1.3.</p>
+
+    <p>If you just want to <cite>make it work</cite> without
+    understanding how, here are <a href="examples.html">some
+    examples</a>.</p>
+
+</summary>
+
+<section id="configparsing"><title>Config File Parsing</title>
+
+    <p>There is a <em>main_server</em> which consists of all the
+    definitions appearing outside of
+    <code>&lt;VirtualHost&gt;</code> sections. There are virtual
+    servers, called <em>vhosts</em>, which are defined by
+    <directive type="section" module="core">VirtualHost</directive>
+    sections.</p>
+
+    <p>The directives
+    <directive module="mpm_common">Listen</directive>,
+    <directive module="core">ServerName</directive>,
+    <directive module="core">ServerPath</directive>,
+    and <directive module="core">ServerAlias</directive>
+    can appear anywhere within the definition of a server. However,
+    each appearance overrides the previous appearance (within that
+    server).</p>
+
+    <p>The default value of the <code>Listen</code> field for
+    main_server is 80. The main_server has no default
+    <code>ServerPath</code>, or <code>ServerAlias</code>. The
+    default <code>ServerName</code> is deduced from the servers IP
+    address.</p>
+
+    <p>The main_server Listen directive has two functions.  One
+    function is to determine the default network port Apache will
+    bind to.  The second function is to specify the port number
+    which is used in absolute URIs during redirects.</p>
+
+    <p>Unlike the main_server, vhost ports <em>do not</em> affect
+    what ports Apache listens for connections on.</p>
+
+    <p>Each address appearing in the <code>VirtualHost</code>
+    directive can have an optional port. If the port is unspecified
+    it defaults to the value of the main_server's most recent
+    <code>Listen</code> statement. The special port <code>*</code>
+    indicates a wildcard that matches any port. Collectively the
+    entire set of addresses (including multiple <code>A</code>
+    record results from DNS lookups) are called the vhost's
+    <em>address set</em>.</p>
+
+    <p>Unless a <directive module="core">NameVirtualHost</directive>
+    directive is used for a specific IP address the first vhost
+    with that address is treated as an IP-based vhost. The IP
+    address can also be the wildcard <code>*</code>.</p>
+
+    <p>If name-based vhosts should be used a
+    <code>NameVirtualHost</code> directive <em>must</em> appear
+    with the IP address set to be used for the name-based vhosts.
+    In other words, you must specify the IP address that holds the
+    hostname aliases (CNAMEs) for your name-based vhosts via a
+    <code>NameVirtualHost</code> directive in your configuration
+    file.</p>
+
+    <p>Multiple <code>NameVirtualHost</code> directives can be used
+    each with a set of <code>VirtualHost</code> directives but only
+    one <code>NameVirtualHost</code> directive should be used for
+    each specific IP:port pair.</p>
+
+    <p>The ordering of <code>NameVirtualHost</code> and
+    <code>VirtualHost</code> directives is not important which
+    makes the following two examples identical (only the order of
+    the <code>VirtualHost</code> directives for <em>one</em>
+    address set is important, see below):</p>
+
+<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>After parsing the <code>VirtualHost</code> directive, the
+    vhost server is given a default <code>Listen</code> equal to the
+    port assigned to the first name in its <code>VirtualHost</code>
+    directive.</p>
+
+    <p>The complete list of names in the <code>VirtualHost</code>
+    directive are treated just like a <code>ServerAlias</code> (but
+    are not overridden by any <code>ServerAlias</code> statement)
+    if all names resolve to the same address set. Note that
+    subsequent <code>Listen</code> statements for this vhost will not
+    affect the ports assigned in the address set.</p>
+
+    <p>During initialization a list for each IP address is
+    generated and inserted into an hash table. If the IP address is
+    used in a <code>NameVirtualHost</code> directive the list
+    contains all name-based vhosts for the given IP address. If
+    there are no vhosts defined for that address the
+    <code>NameVirtualHost</code> directive is ignored and an error
+    is logged. For an IP-based vhost the list in the hash table is
+    empty.</p>
+
+    <p>Due to a fast hashing function the overhead of hashing an IP
+    address during a request is minimal and almost not existent.
+    Additionally the table is optimized for IP addresses which vary
+    in the last octet.</p>
+
+    <p>For every vhost various default values are set. In
+    particular:</p>
+
+    <ol>
+      <li>If a vhost has no <directive module="core">ServerAdmin</directive>,
+      <directive module="core">ResourceConfig</directive>,
+      <directive module="core">AccessConfig</directive>,
+      <directive module="core">Timeout</directive>,
+      <directive module="core">KeepAliveTimeout</directive>,
+      <directive module="core">KeepAlive</directive>,
+      <directive module="core">MaxKeepAliveRequests</directive>,
+      or <directive module="core">SendBufferSize</directive>
+      directive then the respective value is inherited from the
+      main_server. (That is, inherited from whatever the final
+      setting of that value is in the main_server.)</li>
+
+      <li>The "lookup defaults" that define the default directory
+      permissions for a vhost are merged with those of the
+      main_server. This includes any per-directory configuration
+      information for any module.</li>
+
+      <li>The per-server configs for each module from the
+      main_server are merged into the vhost server.</li>
+    </ol>
+
+    <p>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>
+
+    <p>If the main_server has no <code>ServerName</code> at this
+    point, then the hostname of the machine that httpd is running
+    on is used instead. We will call the <em>main_server address
+    set</em> those IP addresses returned by a DNS lookup on the
+    <code>ServerName</code> of the main_server.</p>
+
+    <p>For any undefined <code>ServerName</code> fields, a
+    name-based vhost defaults to the address given first in the
+    <code>VirtualHost</code> statement defining the vhost.</p>
+
+    <p>Any vhost that includes the magic <code>_default_</code>
+    wildcard is given the same <code>ServerName</code> as the
+    main_server.</p>
+
+</section>
+
+<section id="hostmatching"><title>Virtual Host Matching</title>
+
+    <p>The server determines which vhost to use for a request as
+    follows:</p>
+
+    <section id="hashtable"><title>Hash table lookup</title>
+
+    <p>When the connection is first made by a client, the IP
+    address to which the client connected is looked up in the
+    internal IP hash table.</p>
+
+    <p>If the lookup fails (the IP address wasn't found) the
+    request is served from the <code>_default_</code> vhost if
+    there is such a vhost for the port to which the client sent the
+    request. If there is no matching <code>_default_</code> vhost
+    the request is served from the main_server.</p>
+
+    <p>If the IP address is not found in the hash table then the
+    match against the port number may also result in an entry
+    corresponding to a <code>NameVirtualHost *</code>, which is
+    subsequently handled like other name-based vhosts.</p>
+
+    <p>If the lookup succeeded (a corresponding list for the IP
+    address was found) the next step is to decide if we have to
+    deal with an IP-based or a name-base vhost.</p>
+
+    </section>
+
+    <section id="ipbased"><title>IP-based vhost</title>
+
+    <p>If the entry we found has an empty name list then we have
+    found an IP-based vhost, no further actions are performed and
+    the request is served from that vhost.</p>
+
+    </section>
+
+    <section id="namebased"><title>Name-based vhost</title>
+
+    <p>If the entry corresponds to a name-based vhost the name list
+    contains one or more vhost structures. This list contains the
+    vhosts in the same order as the <code>VirtualHost</code>
+    directives appear in the config file.</p>
+
+    <p>The first vhost on this list (the first vhost in the config
+    file with the specified IP address) has the highest priority
+    and catches any request to an unknown server name or a request
+    without a <code>Host:</code> header field.</p>
+
+    <p>If the client provided a <code>Host:</code> header field the
+    list is searched for a matching vhost and the first hit on a
+    <code>ServerName</code> or <code>ServerAlias</code> is taken
+    and the request is served from that vhost. A <code>Host:</code>
+    header field can contain a port number, but Apache always
+    matches against the real port to which the client sent the
+    request.</p>
+
+    <p>If the client submitted a HTTP/1.0 request without
+    <code>Host:</code> header field we don't know to what server
+    the client tried to connect and any existing
+    <code>ServerPath</code> is matched against the URI from the
+    request. The first matching path on the list is used and the
+    request is served from that vhost.</p>
+
+    <p>If no matching vhost could be found the request is served
+    from the first vhost with a matching port number that is on the
+    list for the IP to which the client connected (as already
+    mentioned before).</p>
+
+    </section>
+
+    <section id="persistent"><title>Persistent connections</title>
+
+    <p>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.</p>
+
+    </section>
+
+    <section id="absoluteURI"><title>Absolute URI</title>
+
+    <p>If the URI from the request is an absolute URI, and its
+    hostname and port match the main server or one of the
+    configured virtual hosts <em>and</em> match the address and
+    port to which the client sent the request, then the
+    scheme/hostname/port prefix is stripped off and the remaining
+    relative URI is served by the corresponding main server or
+    virtual host. If it does not match, then the URI remains
+    untouched and the request is taken to be a proxy request.</p>
+</section>
+
+<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> and <code>ServerPath</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
+      name-based vhosts for a specific address set is significant.
+      The one name-based vhosts that comes first in the
+      configuration file has the highest priority for its
+      corresponding address set.</li>
+
+      <li>For security reasons the port number given in a
+      <code>Host:</code> header field is never used during the
+      matching process. Apache always uses the real port to which
+      the client sent the request.</li>
+
+      <li>If a <code>ServerPath</code> directive exists which is a
+      prefix of another <code>ServerPath</code> directive that
+      appears later in the configuration file, then the former will
+      always be matched and the latter will never be matched. (That
+      is assuming that no <code>Host:</code> header field was
+      available to disambiguate the two.)</li>
+
+      <li>If two IP-based vhosts have an address in common, the
+      vhost appearing first in the config file is always matched.
+      Such a thing might happen inadvertently. The server will give
+      a warning in the error logfile when it detects this.</li>
+
+      <li>A <code>_default_</code> vhost catches a request only if
+      there is no other vhost with a matching IP address
+      <em>and</em> a matching port number for the request. The
+      request is only caught if the port number to which the client
+      sent the request matches the port number of your
+      <code>_default_</code> vhost which is your standard
+      <code>Listen</code> by default. A wildcard port can be
+      specified (<em>i.e.</em>, <code>_default_:*</code>) to catch
+      requests to any available port. This also applies to
+      <code>NameVirtualHost *</code> vhosts.</li>
+
+      <li>The main_server is only used to serve a request if the IP
+      address and port number to which the client connected is
+      unspecified and does not match any other vhost (including a
+      <code>_default_</code> vhost). In other words the main_server
+      only catches a request for an unspecified address/port
+      combination (unless there is a <code>_default_</code> vhost
+      which matches that port).</li>
+
+      <li>A <code>_default_</code> vhost or the main_server is
+      <em>never</em> matched for a request with an unknown or
+      missing <code>Host:</code> header field if the client
+      connected to an address (and port) which is used for
+      name-based vhosts, <em>e.g.</em>, in a
+      <code>NameVirtualHost</code> directive.</li>
+
+      <li>You should never specify DNS names in
+      <code>VirtualHost</code> directives because it will force
+      your server to rely on DNS to boot. Furthermore it poses a
+      security threat if you do not control the DNS for all the
+      domains listed. There's <a href="../dns-caveats.html">more
+      information</a> available on this and the next two
+      topics.</li>
+
+      <li><code>ServerName</code> should always be set for each
+      vhost. Otherwise A DNS lookup is required for each
+      vhost.</li>
+      </ul>
+      </section>
+
+</section>
+
+<section id="tips"><title>Tips</title>
+
+    <p>In addition to the tips on the <a
+    href="../dns-caveats.html#tips">DNS Issues</a> page, here are
+    some further tips:</p>
+
+    <ul>
+      <li>Place all main_server definitions before any
+      <code>VirtualHost</code> definitions. (This is to aid the
+      readability of the configuration -- the post-config merging
+      process makes it non-obvious that definitions mixed in around
+      virtual hosts might affect all virtual hosts.)</li>
+
+      <li>Group corresponding <code>NameVirtualHost</code> and
+      <code>VirtualHost</code> definitions in your configuration to
+      ensure better readability.</li>
+
+      <li>Avoid <code>ServerPaths</code> which are prefixes of
+      other <code>ServerPaths</code>. If you cannot avoid this then
+      you have to ensure that the longer (more specific) prefix
+      vhost appears earlier in the configuration file than the
+      shorter (less specific) prefix (<em>i.e.</em>, "ServerPath
+      /abc" should appear after "ServerPath /abc/def").</li>
+    </ul>
+
+</section>
+</manualpage>
+