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