rubbos/app/httpd-2.0.64/docs/manual/vhosts/details.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>An In-Depth Discussion of Virtual Host Matching - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  15 <p class="apache">Apache HTTP Server Version 2.0</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Virtual Hosts</a></div><div id="page-content"><div id="preamble"><h1>An In-Depth Discussion of Virtual Host Matching</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/vhosts/details.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="../ko/vhosts/details.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  23 <a href="../tr/vhosts/details.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  24 </div>
  25
  26
  27     <p>The virtual host code was completely rewritten in
  28     <strong>Apache 1.3</strong>. This document attempts to explain
  29     exactly what Apache does when deciding what virtual host to
  30     serve a hit from. With the help of the new
  31     <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code>
  32     directive virtual host configuration should be a lot easier and
  33     safer than with versions prior to 1.3.</p>
  34
  35     <p>If you just want to <cite>make it work</cite> without
  36     understanding how, here are <a href="examples.html">some
  37     examples</a>.</p>
  38
  39 </div>
  40 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configparsing">Config File Parsing</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#hostmatching">Virtual Host Matching</a></li>
  42 <li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
  43 </ul></div>
  44 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  45 <div class="section">
  46 <h2><a name="configparsing" id="configparsing">Config File Parsing</a></h2>
  47
  48     <p>There is a <em>main_server</em> which consists of all the
  49     definitions appearing outside of
  50     <code>&lt;VirtualHost&gt;</code> sections. There are virtual
  51     servers, called <em>vhosts</em>, which are defined by
  52     <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
  53     sections.</p>
  54
  55     <p>The directives
  56     <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>,
  57     <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code>,
  58     <code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code>,
  59     and <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code>
  60     can appear anywhere within the definition of a server. However,
  61     each appearance overrides the previous appearance (within that
  62     server).</p>
  63
  64     <p>The default value of the <code>Listen</code> field for
  65     main_server is 80. The main_server has no default
  66     <code>ServerPath</code>, or <code>ServerAlias</code>. The
  67     default <code>ServerName</code> is deduced from the server's IP
  68     address.</p>
  69
  70     <p>The main_server Listen directive has two functions.  One
  71     function is to determine the default network port Apache will
  72     bind to.  The second function is to specify the port number
  73     which is used in absolute URIs during redirects.</p>
  74
  75     <p>Unlike the main_server, vhost ports <em>do not</em> affect
  76     what ports Apache listens for connections on.</p>
  77
  78     <p>Each address appearing in the <code>VirtualHost</code>
  79     directive can have an optional port. If the port is unspecified
  80     it defaults to the value of the main_server's most recent
  81     <code>Listen</code> statement. The special port <code>*</code>
  82     indicates a wildcard that matches any port. Collectively the
  83     entire set of addresses (including multiple <code>A</code>
  84     record results from DNS lookups) are called the vhost's
  85     <em>address set</em>.</p>
  86
  87     <p>Unless a <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code>
  88     directive is used for a specific IP address the first vhost
  89     with that address is treated as an IP-based vhost. The IP
  90     address can also be the wildcard <code>*</code>.</p>
  91
  92     <p>If name-based vhosts should be used a
  93     <code>NameVirtualHost</code> directive <em>must</em> appear
  94     with the IP address set to be used for the name-based vhosts.
  95     In other words, you must specify the IP address that holds the
  96     hostname aliases (CNAMEs) for your name-based vhosts via a
  97     <code>NameVirtualHost</code> directive in your configuration
  98     file.</p>
  99
 100     <p>Multiple <code>NameVirtualHost</code> directives can be used
 101     each with a set of <code>VirtualHost</code> directives but only
 102     one <code>NameVirtualHost</code> directive should be used for
 103     each specific IP:port pair.</p>
 104
 105     <p>The ordering of <code>NameVirtualHost</code> and
 106     <code>VirtualHost</code> directives is not important which
 107     makes the following two examples identical (only the order of
 108     the <code>VirtualHost</code> directives for <em>one</em>
 109     address set is important, see below):</p>
 110
 111 <table><tr>
 112 <td><div class="example"><p><code>
 113   NameVirtualHost 111.22.33.44<br />
 114   &lt;VirtualHost 111.22.33.44&gt;<br />
 115   # server A<br />
 116   ...<br />
 117   &lt;/VirtualHost&gt;<br />
 118   &lt;VirtualHost 111.22.33.44&gt;<br />
 119   # server B<br />
 120   ...<br />
 121   &lt;/VirtualHost&gt;<br />
 122   <br />
 123   NameVirtualHost 111.22.33.55<br />
 124   &lt;VirtualHost 111.22.33.55&gt;<br />
 125   # server C<br />
 126   ...<br />
 127   &lt;/VirtualHost&gt;<br />
 128   &lt;VirtualHost 111.22.33.55&gt;<br />
 129   # server D<br />
 130   ...<br />
 131   &lt;/VirtualHost&gt;
 132 </code></p></div></td>
 133 <td><div class="example"><p><code>
 134   &lt;VirtualHost 111.22.33.44&gt;<br />
 135   # server A<br />
 136   &lt;/VirtualHost&gt;<br />
 137   &lt;VirtualHost 111.22.33.55&gt;<br />
 138   # server C<br />
 139   ...<br />
 140   &lt;/VirtualHost&gt;<br />
 141   &lt;VirtualHost 111.22.33.44&gt;<br />
 142   # server B<br />
 143   ...<br />
 144   &lt;/VirtualHost&gt;<br />
 145   &lt;VirtualHost 111.22.33.55&gt;<br />
 146   # server D<br />
 147   ...<br />
 148   &lt;/VirtualHost&gt;<br />
 149   <br />
 150   NameVirtualHost 111.22.33.44<br />
 151   NameVirtualHost 111.22.33.55<br />
 152   <br />
 153 </code></p></div></td>
 154 </tr></table>
 155
 156
 157     <p>(To aid the readability of your configuration you should
 158     prefer the left variant.)</p>
 159
 160     <p>After parsing the <code>VirtualHost</code> directive, the
 161     vhost server is given a default <code>Listen</code> equal to the
 162     port assigned to the first name in its <code>VirtualHost</code>
 163     directive.</p>
 164
 165     <p>The complete list of names in the <code>VirtualHost</code>
 166     directive are treated just like a <code>ServerAlias</code> (but
 167     are not overridden by any <code>ServerAlias</code> statement)
 168     if all names resolve to the same address set. Note that
 169     subsequent <code>Listen</code> statements for this vhost will not
 170     affect the ports assigned in the address set.</p>
 171
 172     <p>During initialization a list for each IP address is
 173     generated and inserted into an hash table. If the IP address is
 174     used in a <code>NameVirtualHost</code> directive the list
 175     contains all name-based vhosts for the given IP address. If
 176     there are no vhosts defined for that address the
 177     <code>NameVirtualHost</code> directive is ignored and an error
 178     is logged. For an IP-based vhost the list in the hash table is
 179     empty.</p>
 180
 181     <p>Due to a fast hashing function the overhead of hashing an IP
 182     address during a request is minimal and almost not existent.
 183     Additionally the table is optimized for IP addresses which vary
 184     in the last octet.</p>
 185
 186     <p>For every vhost various default values are set. In
 187     particular:</p>
 188
 189     <ol>
 190       <li>If a vhost has no <code class="directive"><a href="../mod/core.html#serveradmin">ServerAdmin</a></code>,
 191       <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code>,
 192       <code class="directive"><a href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a></code>,
 193       <code class="directive"><a href="../mod/core.html#keepalive">KeepAlive</a></code>,
 194       <code class="directive"><a href="../mod/core.html#maxkeepaliverequests">MaxKeepAliveRequests</a></code>,
 195       <code class="directive"><a href="../mod/core.html#receivebuffersize">ReceiveBufferSize</a></code>,
 196       or <code class="directive"><a href="../mod/core.html#sendbuffersize">SendBufferSize</a></code>
 197       directive then the respective value is inherited from the
 198       main_server. (That is, inherited from whatever the final
 199       setting of that value is in the main_server.)</li>
 200
 201       <li>The "lookup defaults" that define the default directory
 202       permissions for a vhost are merged with those of the
 203       main_server. This includes any per-directory configuration
 204       information for any module.</li>
 205
 206       <li>The per-server configs for each module from the
 207       main_server are merged into the vhost server.</li>
 208     </ol>
 209
 210     <p>Essentially, the main_server is treated as "defaults" or a
 211     "base" on which to build each vhost. But the positioning of
 212     these main_server definitions in the config file is largely
 213     irrelevant -- the entire config of the main_server has been
 214     parsed when this final merging occurs. So even if a main_server
 215     definition appears after a vhost definition it might affect the
 216     vhost definition.</p>
 217
 218     <p>If the main_server has no <code>ServerName</code> at this
 219     point, then the hostname of the machine that <code class="program"><a href="../programs/httpd.html">httpd</a></code>
 220     is running on is used instead. We will call the <em>main_server address
 221     set</em> those IP addresses returned by a DNS lookup on the
 222     <code>ServerName</code> of the main_server.</p>
 223
 224     <p>For any undefined <code>ServerName</code> fields, a
 225     name-based vhost defaults to the address given first in the
 226     <code>VirtualHost</code> statement defining the vhost.</p>
 227
 228     <p>Any vhost that includes the magic <code>_default_</code>
 229     wildcard is given the same <code>ServerName</code> as the
 230     main_server.</p>
 231
 232 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 233 <div class="section">
 234 <h2><a name="hostmatching" id="hostmatching">Virtual Host Matching</a></h2>
 235
 236     <p>The server determines which vhost to use for a request as
 237     follows:</p>
 238
 239     <h3><a name="hashtable" id="hashtable">Hash table lookup</a></h3>
 240
 241     <p>When the connection is first made by a client, the IP
 242     address to which the client connected is looked up in the
 243     internal IP hash table.</p>
 244
 245     <p>If the lookup fails (the IP address wasn't found) the
 246     request is served from the <code>_default_</code> vhost if
 247     there is such a vhost for the port to which the client sent the
 248     request. If there is no matching <code>_default_</code> vhost
 249     the request is served from the main_server.</p>
 250
 251     <p>If the IP address is not found in the hash table then the
 252     match against the port number may also result in an entry
 253     corresponding to a <code>NameVirtualHost *</code>, which is
 254     subsequently handled like other name-based vhosts.</p>
 255
 256     <p>If the lookup succeeded (a corresponding list for the IP
 257     address was found) the next step is to decide if we have to
 258     deal with an IP-based or a name-base vhost.</p>
 259
 260
 261
 262     <h3><a name="ipbased" id="ipbased">IP-based vhost</a></h3>
 263
 264     <p>If the entry we found has an empty name list then we have
 265     found an IP-based vhost, no further actions are performed and
 266     the request is served from that vhost.</p>
 267
 268
 269
 270     <h3><a name="namebased" id="namebased">Name-based vhost</a></h3>
 271
 272     <p>If the entry corresponds to a name-based vhost the name list
 273     contains one or more vhost structures. This list contains the
 274     vhosts in the same order as the <code>VirtualHost</code>
 275     directives appear in the config file.</p>
 276
 277     <p>The first vhost on this list (the first vhost in the config
 278     file with the specified IP address) has the highest priority
 279     and catches any request to an unknown server name or a request
 280     without a <code>Host:</code> header field.</p>
 281
 282     <p>If the client provided a <code>Host:</code> header field the
 283     list is searched for a matching vhost and the first hit on a
 284     <code>ServerName</code> or <code>ServerAlias</code> is taken
 285     and the request is served from that vhost. A <code>Host:</code>
 286     header field can contain a port number, but Apache always
 287     matches against the real port to which the client sent the
 288     request.</p>
 289
 290     <p>If the client submitted a HTTP/1.0 request without
 291     <code>Host:</code> header field we don't know to what server
 292     the client tried to connect and any existing
 293     <code>ServerPath</code> is matched against the URI from the
 294     request. The first matching path on the list is used and the
 295     request is served from that vhost.</p>
 296
 297     <p>If no matching vhost could be found the request is served
 298     from the first vhost with a matching port number that is on the
 299     list for the IP to which the client connected (as already
 300     mentioned before).</p>
 301
 302
 303
 304     <h3><a name="persistent" id="persistent">Persistent connections</a></h3>
 305
 306     <p>The IP lookup described above is only done <em>once</em> for a
 307     particular TCP/IP session while the name lookup is done on
 308     <em>every</em> request during a KeepAlive/persistent
 309     connection. In other words a client may request pages from
 310     different name-based vhosts during a single persistent
 311     connection.</p>
 312
 313
 314
 315     <h3><a name="absoluteURI" id="absoluteURI">Absolute URI</a></h3>
 316
 317     <p>If the URI from the request is an absolute URI, and its
 318     hostname and port match the main server or one of the
 319     configured virtual hosts <em>and</em> match the address and
 320     port to which the client sent the request, then the
 321     scheme/hostname/port prefix is stripped off and the remaining
 322     relative URI is served by the corresponding main server or
 323     virtual host. If it does not match, then the URI remains
 324     untouched and the request is taken to be a proxy request.</p>
 325
 326
 327 <h3><a name="observations" id="observations">Observations</a></h3>
 328
 329     <ul>
 330       <li>A name-based vhost can never interfere with an IP-base
 331       vhost and vice versa. IP-based vhosts can only be reached
 332       through an IP address of its own address set and never
 333       through any other address. The same applies to name-based
 334       vhosts, they can only be reached through an IP address of the
 335       corresponding address set which must be defined with a
 336       <code>NameVirtualHost</code> directive.</li>
 337
 338       <li><code>ServerAlias</code> and <code>ServerPath</code>
 339       checks are never performed for an IP-based vhost.</li>
 340
 341       <li>The order of name-/IP-based, the <code>_default_</code>
 342       vhost and the <code>NameVirtualHost</code> directive within
 343       the config file is not important. Only the ordering of
 344       name-based vhosts for a specific address set is significant.
 345       The one name-based vhosts that comes first in the
 346       configuration file has the highest priority for its
 347       corresponding address set.</li>
 348
 349       <li>For security reasons the port number given in a
 350       <code>Host:</code> header field is never used during the
 351       matching process. Apache always uses the real port to which
 352       the client sent the request.</li>
 353
 354       <li>If a <code>ServerPath</code> directive exists which is a
 355       prefix of another <code>ServerPath</code> directive that
 356       appears later in the configuration file, then the former will
 357       always be matched and the latter will never be matched. (That
 358       is assuming that no <code>Host:</code> header field was
 359       available to disambiguate the two.)</li>
 360
 361       <li>If two IP-based vhosts have an address in common, the
 362       vhost appearing first in the config file is always matched.
 363       Such a thing might happen inadvertently. The server will give
 364       a warning in the error logfile when it detects this.</li>
 365
 366       <li>A <code>_default_</code> vhost catches a request only if
 367       there is no other vhost with a matching IP address
 368       <em>and</em> a matching port number for the request. The
 369       request is only caught if the port number to which the client
 370       sent the request matches the port number of your
 371       <code>_default_</code> vhost which is your standard
 372       <code>Listen</code> by default. A wildcard port can be
 373       specified (<em>i.e.</em>, <code>_default_:*</code>) to catch
 374       requests to any available port. This also applies to
 375       <code>NameVirtualHost *</code> vhosts.</li>
 376
 377       <li>The main_server is only used to serve a request if the IP
 378       address and port number to which the client connected is
 379       unspecified and does not match any other vhost (including a
 380       <code>_default_</code> vhost). In other words the main_server
 381       only catches a request for an unspecified address/port
 382       combination (unless there is a <code>_default_</code> vhost
 383       which matches that port).</li>
 384
 385       <li>A <code>_default_</code> vhost or the main_server is
 386       <em>never</em> matched for a request with an unknown or
 387       missing <code>Host:</code> header field if the client
 388       connected to an address (and port) which is used for
 389       name-based vhosts, <em>e.g.</em>, in a
 390       <code>NameVirtualHost</code> directive.</li>
 391
 392       <li>You should never specify DNS names in
 393       <code>VirtualHost</code> directives because it will force
 394       your server to rely on DNS to boot. Furthermore it poses a
 395       security threat if you do not control the DNS for all the
 396       domains listed. There's <a href="../dns-caveats.html">more
 397       information</a> available on this and the next two
 398       topics.</li>
 399
 400       <li><code>ServerName</code> should always be set for each
 401       vhost. Otherwise A DNS lookup is required for each
 402       vhost.</li>
 403       </ul>
 404
 405
 406 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 407 <div class="section">
 408 <h2><a name="tips" id="tips">Tips</a></h2>
 409
 410     <p>In addition to the tips on the <a href="../dns-caveats.html#tips">DNS Issues</a> page, here are
 411     some further tips:</p>
 412
 413     <ul>
 414       <li>Place all main_server definitions before any
 415       <code>VirtualHost</code> definitions. (This is to aid the
 416       readability of the configuration -- the post-config merging
 417       process makes it non-obvious that definitions mixed in around
 418       virtual hosts might affect all virtual hosts.)</li>
 419
 420       <li>Group corresponding <code>NameVirtualHost</code> and
 421       <code>VirtualHost</code> definitions in your configuration to
 422       ensure better readability.</li>
 423
 424       <li>Avoid <code>ServerPaths</code> which are prefixes of
 425       other <code>ServerPaths</code>. If you cannot avoid this then
 426       you have to ensure that the longer (more specific) prefix
 427       vhost appears earlier in the configuration file than the
 428       shorter (less specific) prefix (<em>i.e.</em>, "ServerPath
 429       /abc" should appear after "ServerPath /abc/def").</li>
 430     </ul>
 431
 432 </div></div>
 433 <div class="bottomlang">
 434 <p><span>Available Languages: </span><a href="../en/vhosts/details.html" title="English">&nbsp;en&nbsp;</a> |
 435 <a href="../ko/vhosts/details.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 436 <a href="../tr/vhosts/details.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 437 </div><div id="footer">
 438 <p class="apache">Copyright 2009 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 439 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
 440 </body></html>