details.xml revision 18ee8bb3db5cc3b04291f89301bd5d14dc271066
6ae232055d4d8a97267517c5e50074c2c819941and<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
6ae232055d4d8a97267517c5e50074c2c819941and<!-- $LastChangedRevision$ -->
6ae232055d4d8a97267517c5e50074c2c819941and Licensed to the Apache Software Foundation (ASF) under one or more
6ae232055d4d8a97267517c5e50074c2c819941and contributor license agreements. See the NOTICE file distributed with
6ae232055d4d8a97267517c5e50074c2c819941and this work for additional information regarding copyright ownership.
6ae232055d4d8a97267517c5e50074c2c819941and The ASF licenses this file to You under the Apache License, Version 2.0
6ae232055d4d8a97267517c5e50074c2c819941and (the "License"); you may not use this file except in compliance with
6ae232055d4d8a97267517c5e50074c2c819941and the License. You may obtain a copy of the License at
6ae232055d4d8a97267517c5e50074c2c819941and Unless required by applicable law or agreed to in writing, software
6ae232055d4d8a97267517c5e50074c2c819941and distributed under the License is distributed on an "AS IS" BASIS,
6ae232055d4d8a97267517c5e50074c2c819941and WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
6ae232055d4d8a97267517c5e50074c2c819941and See the License for the specific language governing permissions and
6ae232055d4d8a97267517c5e50074c2c819941and limitations under the License.
6ae232055d4d8a97267517c5e50074c2c819941and <title>An In-Depth Discussion of Virtual Host Matching</title>
6ae232055d4d8a97267517c5e50074c2c819941and <p>This document attempts to explain
6ae232055d4d8a97267517c5e50074c2c819941and exactly what Apache HTTP Server does when deciding what virtual host to
6ae232055d4d8a97267517c5e50074c2c819941and serve a request from.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>Most users should read about <a href="name-based.html#namevip">
6ae232055d4d8a97267517c5e50074c2c819941and Name-based vs. IP-based Virtual Hosts</a> to decide which type they
6ae232055d4d8a97267517c5e50074c2c819941and want to use, then read more about <a href="name-based.html">name-based</a>
6ae232055d4d8a97267517c5e50074c2c819941and or <a href="ip-based.html">IP-based</a> virtualhosts, and then see
6ae232055d4d8a97267517c5e50074c2c819941and <p>If you want to understand all the details, then you can
6ae232055d4d8a97267517c5e50074c2c819941and come back to this page.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<seealso><a href="ip-based.html">IP-based Virtual Host Support</a></seealso>
6ae232055d4d8a97267517c5e50074c2c819941and<seealso><a href="name-based.html">Name-based Virtual Hosts Support</a></seealso>
6ae232055d4d8a97267517c5e50074c2c819941and<seealso><a href="examples.html">Virtual Host examples for common setups</a></seealso>
6ae232055d4d8a97267517c5e50074c2c819941and<seealso><a href="mass.html">Dynamically configured mass virtual hosting</a></seealso>
6ae232055d4d8a97267517c5e50074c2c819941and<section id="configparsing"><title>Configuration File</title>
6ae232055d4d8a97267517c5e50074c2c819941and <p>There is a <em>main server</em> which consists of all the
6ae232055d4d8a97267517c5e50074c2c819941and definitions appearing outside of
6ae232055d4d8a97267517c5e50074c2c819941and <p>There are virtual
6ae232055d4d8a97267517c5e50074c2c819941and <directive type="section" module="core">VirtualHost</directive>
6ae232055d4d8a97267517c5e50074c2c819941and sections.</p>
6ae232055d4d8a97267517c5e50074c2c819941and or more addresses and optional ports.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>Hostnames can be used in place of IP addresses in a virtual
6ae232055d4d8a97267517c5e50074c2c819941and host definition, but they are resolved at startup and if any name
6ae232055d4d8a97267517c5e50074c2c819941and resolutions fail, those virtual host definitions are ignored.
6ae232055d4d8a97267517c5e50074c2c819941and This is, therefore, not recommended.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>The address can be specified as
6ae232055d4d8a97267517c5e50074c2c819941and other vhost has the explicit address on which the request was
6ae232055d4d8a97267517c5e50074c2c819941and received. </p>
6ae232055d4d8a97267517c5e50074c2c819941and directive can have an optional port. If the port is unspecified,
6ae232055d4d8a97267517c5e50074c2c819941and it is treated as a wildcard port, which can also be indicated
6ae232055d4d8a97267517c5e50074c2c819941and The wildcard port matches any port.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>(Port numbers specified in the <code>VirtualHost</code> directive do
6ae232055d4d8a97267517c5e50074c2c819941and not influence what port numbers Apache will listen on, they only control
6ae232055d4d8a97267517c5e50074c2c819941and which <code>VirtualHost</code> will be selected to handle a request.
6ae232055d4d8a97267517c5e50074c2c819941and Use the <directive module="core">Listen</directive> directive to
6ae232055d4d8a97267517c5e50074c2c819941and control the addresses and ports on which the server listens.)
6ae232055d4d8a97267517c5e50074c2c819941and <p>Collectively the
6ae232055d4d8a97267517c5e50074c2c819941and entire set of addresses (including multiple
6ae232055d4d8a97267517c5e50074c2c819941and results from DNS lookups) are called the vhost's
6ae232055d4d8a97267517c5e50074c2c819941and <p>Apache automatically discriminates on the
6ae232055d4d8a97267517c5e50074c2c819941and basis of the HTTP <code>Host</code> header supplied by the client
6ae232055d4d8a97267517c5e50074c2c819941and whenever the most specific match for an IP address and port combination
6ae232055d4d8a97267517c5e50074c2c819941and is listed in multiple virtual hosts.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <directive module="core">ServerName</directive> directive
6ae232055d4d8a97267517c5e50074c2c819941and may appear anywhere within the definition of a server. However,
6ae232055d4d8a97267517c5e50074c2c819941and each appearance overrides the previous appearance (within that
6ae232055d4d8a97267517c5e50074c2c819941and server). If no <code>ServerName</code> is specified, the server
6ae232055d4d8a97267517c5e50074c2c819941and attempts to deduce it from the server's IP address.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>The first name-based vhost in the configuration file for a
6ae232055d4d8a97267517c5e50074c2c819941and given IP:port pair is significant because it is used for all
6ae232055d4d8a97267517c5e50074c2c819941and requests received on that address and port for which no other
6ae232055d4d8a97267517c5e50074c2c819941and vhost for that IP:port pair has a matching ServerName or
6ae232055d4d8a97267517c5e50074c2c819941and ServerAlias. It is also used for all SSL connections if the
6ae232055d4d8a97267517c5e50074c2c819941and server does not support <glossary
6ae232055d4d8a97267517c5e50074c2c819941and ref="servernameindication">Server Name Indication</glossary>.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>For every vhost various default values are set. In
6ae232055d4d8a97267517c5e50074c2c819941and particular:</p>
6ae232055d4d8a97267517c5e50074c2c819941and <li>If a vhost has no <directive module="core">ServerAdmin</directive>,
6ae232055d4d8a97267517c5e50074c2c819941and <directive module="core">MaxKeepAliveRequests</directive>,
6ae232055d4d8a97267517c5e50074c2c819941and directive then the respective value is inherited from the
6ae232055d4d8a97267517c5e50074c2c819941and main server. (That is, inherited from whatever the final
6ae232055d4d8a97267517c5e50074c2c819941and setting of that value is in the main server.)</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>The "lookup defaults" that define the default directory
6ae232055d4d8a97267517c5e50074c2c819941and permissions for a vhost are merged with those of the
6ae232055d4d8a97267517c5e50074c2c819941and main server. This includes any per-directory configuration
6ae232055d4d8a97267517c5e50074c2c819941and information for any module.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>The per-server configs for each module from the
6ae232055d4d8a97267517c5e50074c2c819941and main server are merged into the vhost server.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <p>Essentially, the main server is treated as "defaults" or a
6ae232055d4d8a97267517c5e50074c2c819941and "base" on which to build each vhost. But the positioning of
6ae232055d4d8a97267517c5e50074c2c819941and these main server definitions in the config file is largely
6ae232055d4d8a97267517c5e50074c2c819941and irrelevant -- the entire config of the main server has been
6ae232055d4d8a97267517c5e50074c2c819941and parsed when this final merging occurs. So even if a main server
6ae232055d4d8a97267517c5e50074c2c819941and definition appears after a vhost definition it might affect the
6ae232055d4d8a97267517c5e50074c2c819941and vhost definition.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If the main server has no <code>ServerName</code> at this
6ae232055d4d8a97267517c5e50074c2c819941and point, then the hostname of the machine that <program>httpd</program>
6ae232055d4d8a97267517c5e50074c2c819941and is running on is used instead. We will call the <em>main server address
6ae232055d4d8a97267517c5e50074c2c819941and set</em> those IP addresses returned by a DNS lookup on the
6ae232055d4d8a97267517c5e50074c2c819941and name-based vhost defaults to the address given first in the
6ae232055d4d8a97267517c5e50074c2c819941and <code>VirtualHost</code> statement defining the vhost.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>Any vhost that includes the magic <code>_default_</code>
6ae232055d4d8a97267517c5e50074c2c819941and wildcard is given the same <code>ServerName</code> as the
6ae232055d4d8a97267517c5e50074c2c819941and main server.</p>
6ae232055d4d8a97267517c5e50074c2c819941and<section id="hostmatching"><title>Virtual Host Matching</title>
6ae232055d4d8a97267517c5e50074c2c819941and <p>The server determines which vhost to use for a request as
6ae232055d4d8a97267517c5e50074c2c819941and follows:</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>When the connection is first received on some address and port,
6ae232055d4d8a97267517c5e50074c2c819941and the server looks for all the <code>VirtualHost</code> definitions
6ae232055d4d8a97267517c5e50074c2c819941and that have the same IP address and port.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If there are no exact matches for the address and port, then
6ae232055d4d8a97267517c5e50074c2c819941and <p>If no matches are found, the request is served by the
6ae232055d4d8a97267517c5e50074c2c819941and main server.</p>
6ae232055d4d8a97267517c5e50074c2c819941and the IP address, the next step is to decide if we have to
6ae232055d4d8a97267517c5e50074c2c819941and deal with an IP-based or a name-based vhost.</p>
6ae232055d4d8a97267517c5e50074c2c819941and </section>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If there is exactly one <code>VirtualHost</code> directive
6ae232055d4d8a97267517c5e50074c2c819941and listing the IP address and port combination that was determined
6ae232055d4d8a97267517c5e50074c2c819941and to be the best match, no further actions are performed and
6ae232055d4d8a97267517c5e50074c2c819941and the request is served from the matching vhost.</p>
6ae232055d4d8a97267517c5e50074c2c819941and </section>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If there are multiple <code>VirtualHost</code> directives listing
6ae232055d4d8a97267517c5e50074c2c819941and the IP address and port combination that was determined to be the
6ae232055d4d8a97267517c5e50074c2c819941and best match, the "list" in the remaining steps refers to the list of vhosts
6ae232055d4d8a97267517c5e50074c2c819941and that matched, in the order they were in the configuration file.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If the connection is using SSL, the server supports <glossary
6ae232055d4d8a97267517c5e50074c2c819941and ref="servernameindication">Server Name Indication</glossary>, and
6ae232055d4d8a97267517c5e50074c2c819941and the SSL client handshake includes the TLS extension with the
6ae232055d4d8a97267517c5e50074c2c819941and requested hostname, then that hostname is used below just like the
6ae232055d4d8a97267517c5e50074c2c819941and <code>Host:</code> header would be used on a non-SSL connection.
6ae232055d4d8a97267517c5e50074c2c819941and Otherwise, the first name-based vhost whose address matched is
6ae232055d4d8a97267517c5e50074c2c819941and used for SSL connections. This is significant because the
6ae232055d4d8a97267517c5e50074c2c819941and vhost determines which certificate the server will use for the
6ae232055d4d8a97267517c5e50074c2c819941and connection.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If the request contains a <code>Host:</code> header field, the
6ae232055d4d8a97267517c5e50074c2c819941and list is searched for the first vhost with a matching
6ae232055d4d8a97267517c5e50074c2c819941and <code>ServerName</code> or <code>ServerAlias</code>, and the
6ae232055d4d8a97267517c5e50074c2c819941and request is served from that vhost. A <code>Host:</code> header
6ae232055d4d8a97267517c5e50074c2c819941and field can contain a port number, but Apache always ignores it and
6ae232055d4d8a97267517c5e50074c2c819941and matches against the real port to which the client sent the
6ae232055d4d8a97267517c5e50074c2c819941and request.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <p>The first vhost in the config
6ae232055d4d8a97267517c5e50074c2c819941and file with the specified IP address has the highest priority
6ae232055d4d8a97267517c5e50074c2c819941and and catches any request to an unknown server name, or a request
6ae232055d4d8a97267517c5e50074c2c819941and without a <code>Host:</code> header field (such as a HTTP/1.0
6ae232055d4d8a97267517c5e50074c2c819941and request).</p>
6ae232055d4d8a97267517c5e50074c2c819941and </section>
6ae232055d4d8a97267517c5e50074c2c819941and <section id="persistent"><title>Persistent connections</title>
6ae232055d4d8a97267517c5e50074c2c819941and <p>The <em>IP lookup</em> described above is only done <em>once</em> for a
6ae232055d4d8a97267517c5e50074c2c819941and particular TCP/IP session while the <em>name lookup</em> is done on
6ae232055d4d8a97267517c5e50074c2c819941and connection. In other words, a client may request pages from
6ae232055d4d8a97267517c5e50074c2c819941and different name-based vhosts during a single persistent
6ae232055d4d8a97267517c5e50074c2c819941and connection.</p>
6ae232055d4d8a97267517c5e50074c2c819941and </section>
6ae232055d4d8a97267517c5e50074c2c819941and <p>If the URI from the request is an absolute URI, and its
6ae232055d4d8a97267517c5e50074c2c819941and hostname and port match the main server or one of the
6ae232055d4d8a97267517c5e50074c2c819941and configured virtual hosts <em>and</em> match the address and
6ae232055d4d8a97267517c5e50074c2c819941and port to which the client sent the request, then the
6ae232055d4d8a97267517c5e50074c2c819941and scheme/hostname/port prefix is stripped off and the remaining
6ae232055d4d8a97267517c5e50074c2c819941and relative URI is served by the corresponding main server or
6ae232055d4d8a97267517c5e50074c2c819941and virtual host. If it does not match, then the URI remains
6ae232055d4d8a97267517c5e50074c2c819941and untouched and the request is taken to be a proxy request.</p>
6ae232055d4d8a97267517c5e50074c2c819941and <li>Name-based virtual hosting is a process applied after
6ae232055d4d8a97267517c5e50074c2c819941and the server has selected the best matching IP-based virtual
6ae232055d4d8a97267517c5e50074c2c819941and host.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>If you don't care what IP address the client has connected to, use a
6ae232055d4d8a97267517c5e50074c2c819941and "*" as the address of every virtual host, and name-based virtual hosting
6ae232055d4d8a97267517c5e50074c2c819941and is applied across all configured virtual hosts.</li>
6ae232055d4d8a97267517c5e50074c2c819941and checks are never performed for an IP-based vhost.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>Only the ordering of
6ae232055d4d8a97267517c5e50074c2c819941and name-based vhosts for a specific address set is significant.
6ae232055d4d8a97267517c5e50074c2c819941and The one name-based vhosts that comes first in the
6ae232055d4d8a97267517c5e50074c2c819941and configuration file has the highest priority for its
6ae232055d4d8a97267517c5e50074c2c819941and corresponding address set.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>Any port in the <code>Host:</code> header field is never used during the
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi matching process. Apache always uses the real port to which
ecc5150d35c0dc5ee5119c2717e6660fa331abbftakashi the client sent the request.</li>
6ae232055d4d8a97267517c5e50074c2c819941and <li>If two vhosts have an address in common, those common addresses
6ae232055d4d8a97267517c5e50074c2c819941and act as name-based virtual hosts implicitly. This is new behavior as of
6ae232055d4d8a97267517c5e50074c2c819941and 2.3.11.</li>