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