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