granicus.if.org Git - apache/blob - 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.3</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.3</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="../fr/vhosts/details.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
  23 <a href="../ko/vhosts/details.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  24 <a href="../tr/vhosts/details.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  25 </div>
  26
  27
  28     <p>This document attempts to explain
  29     exactly what Apache HTTP Server does when deciding what virtual host to
  30     serve a request from.</p>
  31
  32     <p>Most users should read about <a href="name-based.html#namevip">
  33     Name-based vs. IP-based Virtual Hosts</a> to decide which type they
  34     want to use, then read more about <a href="name-based.html">name-based</a>
  35     or <a href="ip-based.html">IP-based</a> virtualhosts, and then see
  36     <a href="examples.html">some examples</a>.</p>
  37
  38     <p>If you want to understand all the details, then you can
  39     come back to this page.</p>
  40
  41 </div>
  42 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configparsing">Configuration File</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#hostmatching">Virtual Host Matching</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li>
  45 </ul><h3>See also</h3><ul class="seealso"><li><a href="ip-based.html">IP-based Virtual Host Support</a></li><li><a href="name-based.html">Name-based Virtual Hosts Support</a></li><li><a href="examples.html">Virtual Host examples for common setups</a></li><li><a href="mass.html">Dynamically configured mass virtual hosting</a></li></ul></div>
  46 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  47 <div class="section">
  48 <h2><a name="configparsing" id="configparsing">Configuration File</a></h2>
  49
  50     <p>There is a <em>main server</em> which consists of all the
  51     definitions appearing outside of
  52     <code>&lt;VirtualHost&gt;</code> sections.</p>
  53
  54     <p>There are virtual
  55     servers, called <em>vhosts</em>, which are defined by
  56     <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code>
  57     sections.</p>
  58
  59     <p>Each <code>VirtualHost</code> directive includes one
  60     or more addresses and optional ports.</p>
  61
  62     <p>Hostnames can be used in place of IP addresses in a virtual
  63     host definition, but they are resolved at startup and if any name
  64     resolutions fail, those virtual host definitions are ignored.
  65     This is, therefore, not recommended.</p>
  66
  67     <p>The address can be specified as
  68     <code>*</code>, which will match a request if no
  69     other vhost has the explicit address on which the request was
  70     received. </p>
  71
  72     <p>The address appearing in the <code>VirtualHost</code>
  73     directive can have an optional port. If the port is unspecified,
  74     it is treated as a wildcard port, which can also be indicated
  75     explicitly using <code>*</code>.
  76     The wildcard port matches any port.</p>
  77
  78     <p>(Port numbers specified in the <code>VirtualHost</code> directive do
  79     not influence what port numbers Apache will listen on, they only control
  80     which <code>VirtualHost</code> will be selected to handle a request.
  81     Use the <code class="directive"><a href="../mod/core.html#listen">Listen</a></code> directive to
  82     control the addresses and ports on which the server listens.)
  83     </p>
  84
  85     <p>Collectively the
  86     entire set of addresses (including multiple
  87     results from DNS lookups) are called the vhost's
  88     <em>address set</em>.</p>
  89
  90     <p>Apache automatically discriminates on the
  91     basis of the HTTP <code>Host</code> header supplied by the client
  92     whenever the most specific match for an IP address and port combination
  93     is listed in multiple virtual hosts.</p>
  94
  95     <p>The
  96     <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive
  97     may appear anywhere within the definition of a server. However,
  98     each appearance overrides the previous appearance (within that
  99     server).  If no <code>ServerName</code> is specified, the server
 100     attempts to deduce it from the server's IP address.</p>
 101
 102     <p>The first name-based vhost in the configuration file for a
 103     given IP:port pair is significant because it is used for all
 104     requests received on that address and port for which no other
 105     vhost for that IP:port pair has a matching ServerName or
 106     ServerAlias.  It is also used for all SSL connections if the
 107     server does not support <a class="glossarylink" href="../glossary.html#servernameindication" title="see glossary">Server Name Indication</a>.</p>
 108
 109     <p>For every vhost various default values are set. In
 110     particular:</p>
 111
 112     <ol>
 113       <li>If a vhost has no <code class="directive"><a href="../mod/core.html#serveradmin">ServerAdmin</a></code>,
 114       <code class="directive"><a href="../mod/core.html#resourceconfig">ResourceConfig</a></code>,
 115       <code class="directive"><a href="../mod/core.html#accessconfig">AccessConfig</a></code>,
 116       <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code>,
 117       <code class="directive"><a href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a></code>,
 118       <code class="directive"><a href="../mod/core.html#keepalive">KeepAlive</a></code>,
 119       <code class="directive"><a href="../mod/core.html#maxkeepaliverequests">MaxKeepAliveRequests</a></code>,
 120       <code class="directive"><a href="../mod/core.html#receivebuffersize">ReceiveBufferSize</a></code>,
 121       or <code class="directive"><a href="../mod/core.html#sendbuffersize">SendBufferSize</a></code>
 122       directive then the respective value is inherited from the
 123       main server. (That is, inherited from whatever the final
 124       setting of that value is in the main server.)</li>
 125
 126       <li>The "lookup defaults" that define the default directory
 127       permissions for a vhost are merged with those of the
 128       main server. This includes any per-directory configuration
 129       information for any module.</li>
 130
 131       <li>The per-server configs for each module from the
 132       main server are merged into the vhost server.</li>
 133     </ol>
 134
 135     <p>Essentially, the main server is treated as "defaults" or a
 136     "base" on which to build each vhost. But the positioning of
 137     these main server definitions in the config file is largely
 138     irrelevant -- the entire config of the main server has been
 139     parsed when this final merging occurs. So even if a main server
 140     definition appears after a vhost definition it might affect the
 141     vhost definition.</p>
 142
 143     <p>If the main server has no <code>ServerName</code> at this
 144     point, then the hostname of the machine that <code class="program"><a href="../programs/httpd.html">httpd</a></code>
 145     is running on is used instead. We will call the <em>main server address
 146     set</em> those IP addresses returned by a DNS lookup on the
 147     <code>ServerName</code> of the main server.</p>
 148
 149     <p>For any undefined <code>ServerName</code> fields, a
 150     name-based vhost defaults to the address given first in the
 151     <code>VirtualHost</code> statement defining the vhost.</p>
 152
 153     <p>Any vhost that includes the magic <code>_default_</code>
 154     wildcard is given the same <code>ServerName</code> as the
 155     main server.</p>
 156
 157 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 158 <div class="section">
 159 <h2><a name="hostmatching" id="hostmatching">Virtual Host Matching</a></h2>
 160
 161     <p>The server determines which vhost to use for a request as
 162     follows:</p>
 163
 164     <h3><a name="hashtable" id="hashtable">IP address lookup</a></h3>
 165
 166     <p>When the connection is first received on some address and port,
 167     the server looks for all the <code>VirtualHost</code> definitions
 168     that have the same IP address and port.</p>
 169
 170     <p>If there are no exact matches for the address and port, then
 171     wildcard (<code>*</code>) matches are considered.</p>
 172
 173     <p>If no matches are found, the request is served by the
 174     main server.</p>
 175
 176     <p>If there are <code>VirtualHost</code> definitions for
 177     the IP address, the next step is to decide if we have to
 178     deal with an IP-based or a name-based vhost.</p>
 179
 180
 181
 182     <h3><a name="ipbased" id="ipbased">IP-based vhost</a></h3>
 183
 184     <p>If there is exactly one <code>VirtualHost</code> directive
 185     listing the IP address and port combination that was determined
 186     to be the best match, no further actions are performed and
 187     the request is served from the matching vhost.</p>
 188
 189
 190
 191     <h3><a name="namebased" id="namebased">Name-based vhost</a></h3>
 192
 193     <p>If there are multiple <code>VirtualHost</code> directives listing
 194     the IP address and port combination that was determined to be the
 195     best match, the "list" in the remaining steps refers to the list of vhosts
 196     that matched, in the order they were in the configuration file.</p>
 197
 198     <p>If the connection is using SSL, the server supports <a class="glossarylink" href="../glossary.html#servernameindication" title="see glossary">Server Name Indication</a>, and
 199     the SSL client handshake includes the TLS extension with the
 200     requested hostname, then that hostname is used below just like the
 201     <code>Host:</code> header would be used on a non-SSL connection.
 202     Otherwise, the first name-based vhost whose address matched is
 203     used for SSL connections.  This is significant because the
 204     vhost determines which certificate the server will use for the
 205     connection.</p>
 206
 207     <p>If the request contains a <code>Host:</code> header field, the
 208     list is searched for the first vhost with a matching
 209     <code>ServerName</code> or <code>ServerAlias</code>, and the
 210     request is served from that vhost. A <code>Host:</code> header
 211     field can contain a port number, but Apache always ignores it and
 212     matches against the real port to which the client sent the
 213     request.</p>
 214
 215     <p>The first vhost in the config
 216     file with the specified IP address has the highest priority
 217     and catches any request to an unknown server name, or a request
 218     without a <code>Host:</code> header field (such as a HTTP/1.0
 219     request).</p>
 220
 221
 222
 223     <h3><a name="persistent" id="persistent">Persistent connections</a></h3>
 224
 225     <p>The <em>IP lookup</em> described above is only done <em>once</em> for a
 226     particular TCP/IP session while the <em>name lookup</em> is done on
 227     <em>every</em> request during a KeepAlive/persistent
 228     connection. In other words, a client may request pages from
 229     different name-based vhosts during a single persistent
 230     connection.</p>
 231
 232
 233
 234     <h3><a name="absoluteURI" id="absoluteURI">Absolute URI</a></h3>
 235
 236     <p>If the URI from the request is an absolute URI, and its
 237     hostname and port match the main server or one of the
 238     configured virtual hosts <em>and</em> match the address and
 239     port to which the client sent the request, then the
 240     scheme/hostname/port prefix is stripped off and the remaining
 241     relative URI is served by the corresponding main server or
 242     virtual host. If it does not match, then the URI remains
 243     untouched and the request is taken to be a proxy request.</p>
 244
 245
 246 <h3><a name="observations" id="observations">Observations</a></h3>
 247
 248     <ul>
 249       <li>Name-based virtual hosting is a process applied after
 250       the server has selected the best matching IP-based virtual
 251       host.</li>
 252
 253       <li>If you don't care what IP address the client has connected to, use a
 254       "*" as the address of every virtual host, and name-based virtual hosting
 255       is applied across all configured virtual hosts.</li>
 256
 257       <li><code>ServerName</code> and <code>ServerAlias</code>
 258       checks are never performed for an IP-based vhost.</li>
 259
 260       <li>Only the ordering of
 261       name-based vhosts for a specific address set is significant.
 262       The one name-based vhosts that comes first in the
 263       configuration file has the highest priority for its
 264       corresponding address set.</li>
 265
 266       <li>Any port in the <code>Host:</code> header field is never used during the
 267       matching process. Apache always uses the real port to which
 268       the client sent the request.</li>
 269
 270       <li>If two vhosts have an address in common, those common addresses
 271       act as name-based virtual hosts implicitly.  This is new behavior as of
 272       2.3.11.</li>
 273
 274       <li>The main server is only used to serve a request if the IP
 275       address and port number to which the client connected
 276       does not match any vhost (including a
 277       <code>*</code> vhost). In other words, the main server
 278       only catches a request for an unspecified address/port
 279       combination (unless there is a <code>_default_</code> vhost
 280       which matches that port).</li>
 281
 282       <li>You should never specify DNS names in
 283       <code>VirtualHost</code> directives because it will force
 284       your server to rely on DNS to boot. Furthermore it poses a
 285       security threat if you do not control the DNS for all the
 286       domains listed. There's <a href="../dns-caveats.html">more
 287       information</a> available on this and the next two
 288       topics.</li>
 289
 290       <li><code>ServerName</code> should always be set for each
 291       vhost. Otherwise A DNS lookup is required for each
 292       vhost.</li>
 293       </ul>
 294
 295
 296 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 297 <div class="section">
 298 <h2><a name="tips" id="tips">Tips</a></h2>
 299
 300     <p>In addition to the tips on the <a href="../dns-caveats.html#tips">DNS Issues</a> page, here are
 301     some further tips:</p>
 302
 303     <ul>
 304       <li>Place all main server definitions before any
 305       <code>VirtualHost</code> definitions. (This is to aid the
 306       readability of the configuration -- the post-config merging
 307       process makes it non-obvious that definitions mixed in around
 308       virtual hosts might affect all virtual hosts.)</li>
 309     </ul>
 310
 311 </div></div>
 312 <div class="bottomlang">
 313 <p><span>Available Languages: </span><a href="../en/vhosts/details.html" title="English">&nbsp;en&nbsp;</a> |
 314 <a href="../fr/vhosts/details.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a> |
 315 <a href="../ko/vhosts/details.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 316 <a href="../tr/vhosts/details.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
 317 </div><div id="footer">
 318 <p class="apache">Copyright 2011 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>
 319 <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>
 320 </body></html>