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