mirror of
https://github.com/apache/httpd.git
synced 2025-10-24 10:53:08 +03:00
1051b18e72
<virtualhost> section with name-virtual-hosts. This is already clearly documented a few paragraphs below, but judging by questions on the newsgroup/mailing list, people don't read past the example. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@96416 13f79535-47bb-0310-9956-ffa450edef68
240 lines
10 KiB
Plaintext
240 lines
10 KiB
Plaintext
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
|
|
|
|
<html xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>Name-based Virtual Hosts</title>
|
|
</head>
|
|
<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
|
|
|
|
<body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
|
|
vlink="#000080" alink="#FF0000">
|
|
<!--#include virtual="header.html" -->
|
|
|
|
<h1 align="center">Name-based Virtual Host Support</h1>
|
|
|
|
<p>This document describes when and how to use name-based virtual hosts.</p>
|
|
|
|
<ul>
|
|
<li><a href="#namevip">Name-based vs. IP-based Virtual Hosts</a></li>
|
|
<li><a href="#using">Using Name-based Virtual Hosts</a></li>
|
|
<li><a href="#compat">Compatibility With Older Browsers</a></li>
|
|
</ul>
|
|
|
|
<p>See also: <a href="examples.html">Virtual Host examples for common
|
|
setups</a>, <a href="ip-based.html">IP-based Virtual Host Support</a>,
|
|
<a href="details.html">An In-Depth Discussion of Virtual Host
|
|
Matching</a>, and <a href="mass.html">Dynamically configured mass
|
|
virtual hosting</a>.</p>
|
|
|
|
<hr />
|
|
|
|
<h2><a name="namevip">Name-based vs. IP-based Virtual Hosts</a></h2>
|
|
|
|
<p>IP-based virtual hosts use the IP address of the connection to
|
|
determine the correct virtual host to serve. Therefore you need to
|
|
have a separate IP address for each host. With name-based virtual
|
|
hosting, the server relies on the client to report the hostname as
|
|
part of the HTTP headers. Using this technique, many different hosts
|
|
can share the same IP address.</p>
|
|
|
|
<p>Name-based virtual hosting is usually simpler, since you need
|
|
only configure your DNS server to map each hostname to the correct
|
|
IP address and then configure the Apache HTTP Server to recognize
|
|
the different hostnames. Name-based virtual hosting also eases
|
|
the demand for scarce IP addresses. Therefore you should use
|
|
name-based virtual hosting unless there is a specific reason to
|
|
choose IP-based virtual hosting. Some reasons why you might consider
|
|
using IP-based virtual hosting:</p>
|
|
|
|
<ul>
|
|
|
|
<li>Some ancient clients are not compatible with name-based virtual
|
|
hosting. For name-based virtual hosting to work, the client must send
|
|
the HTTP Host header. This is required by HTTP/1.1, and is
|
|
implemented by all modern HTTP/1.0 browsers as an extension. If you
|
|
need to support obsolete clients and still use name-based virtual
|
|
hosting, a possible technique is discussed at the end of this
|
|
document.</li>
|
|
|
|
<li>Name-based virtual hosting cannot be used with SSL secure servers
|
|
because of the nature of the SSL protocol.</li>
|
|
|
|
<li>Some operating systems and network equipment implement bandwidth
|
|
management techniques that cannot differentiate between hosts unless
|
|
they are on separate IP addresses.</li>
|
|
|
|
</ul>
|
|
|
|
<h2><a name="using">Using Name-based Virtual Hosts</a></h2>
|
|
|
|
<table border="1">
|
|
<tr><td valign="top">
|
|
<strong>Related Directives</strong><br /><br />
|
|
|
|
<a href="../mod/core.html#documentroot">DocumentRoot</a><br />
|
|
<a href="../mod/core.html#namevirtualhost">NameVirtualHost</a><br />
|
|
<a href="../mod/core.html#serveralias">ServerAlias</a><br />
|
|
<a href="../mod/core.html#servername">ServerName</a><br />
|
|
<a href="../mod/core.html#serverpath">ServerPath</a><br />
|
|
<a href="../mod/core.html#virtualhost">VirtualHost</a><br />
|
|
</td></tr></table>
|
|
|
|
<p>To use name-based virtual hosting, you must designate the IP
|
|
address (and possibly port) on the server that will be accepting
|
|
requests for the hosts. This is configured using the <a
|
|
href="../mod/core.html#namevirtualhost">NameVirtualHost</a> directive.
|
|
In the normal case where any and all IP addresses on the server should
|
|
be used, you can use <code>*</code> as the argument to
|
|
<code>NameVirtualHost</code>. Note that mentioning an IP address in a
|
|
<code>NameVirtualHost</code> directive does not automatically make the
|
|
server listen to that IP address. See <a href="../bind.html">Setting
|
|
which addresses and ports Apache uses</a> for more details. In addition,
|
|
any IP address specified here must be associated with a network interface
|
|
on the server.</p>
|
|
|
|
<p>The next step is to create a <a
|
|
href="../mod/core.html#virtualhost"><VirtualHost></a> block for
|
|
each different host that you would like to serve. The argument to the
|
|
<code><VirtualHost></code> directive should be the same as the
|
|
argument to the <code>NameVirtualHost</code> directive (ie, an IP
|
|
address, or <code>*</code> for all addresses). Inside each
|
|
<code><VirtualHost></code> block, you will need at minimum a <a
|
|
href="../mod/core.html#servername">ServerName</a> directive to
|
|
designate which host is served and a <a
|
|
href="../mod/core.html#documentroot">DocumentRoot</a> directive to
|
|
show where in the filesystem the content for that host lives.</p>
|
|
|
|
<p>If you are adding virtual hosts to an existing web server, you
|
|
must also create a <VirtualHost> block for the existing host.
|
|
The <code>ServerName</code> and <code>DocumentRoot</code> included in
|
|
this virtual host should be the same as the global
|
|
<code>ServerName</code> and <code>DocumentRoot</code>. List this
|
|
virtual host first in the configuration file so that it will act as
|
|
the default host.</p>
|
|
|
|
<p>For example, suppose that you are serving the domain
|
|
<samp>www.domain.tld</samp> and you wish to add the virtual host
|
|
<samp>www.otherdomain.tld</samp>, which points at the same IP address.
|
|
Then you simply add the following to <code>httpd.conf</code>:</p>
|
|
|
|
<pre>
|
|
NameVirtualHost *
|
|
|
|
<VirtualHost *>
|
|
ServerName www.domain.tld
|
|
DocumentRoot /www/domain
|
|
</VirtualHost>
|
|
|
|
<VirtualHost *>
|
|
ServerName www.otherdomain.tld
|
|
DocumentRoot /www/otherdomain
|
|
</VirtualHost>
|
|
</pre>
|
|
|
|
<p>You can alternatively specify an explicit IP address in place of
|
|
the * in both the <code>NameVirtualHost</code> and
|
|
<code><VirtualHost></code> directives.</p>
|
|
|
|
<p>Many servers want to be accessible by more than one name. This is
|
|
possible with the <a
|
|
href="../mod/core.html#serveralias"><code>ServerAlias</code></a>
|
|
directive, placed inside the <VirtualHost> section. For
|
|
example if you add this to the first <VirtualHost> block
|
|
above</p>
|
|
|
|
<blockquote><code>
|
|
ServerAlias domain.tld *.domain.tld
|
|
</code></blockquote>
|
|
|
|
<p>then requests for all hosts in the <code>domain.tld</code> domain
|
|
will be served by the <code>www.domain.tld</code> virtual host. The
|
|
wildcard characters * and ? can be used to match names. Of course,
|
|
you can't just make up names and place them in <code>ServerName</code>
|
|
or <code>ServerAlias</code>. You must first have your DNS server
|
|
properly configured to map those names to an IP address associated
|
|
with your server.</p>
|
|
|
|
<p>Finally, you can fine-tune the configuration of the virtual hosts
|
|
by placing other directives inside the
|
|
<code><VirtualHost></code> containers. Most directives can be
|
|
placed in these containers and will then change the configuration only
|
|
of the relevant virtual host. To find out if a particular directive
|
|
is allowed, check the <a
|
|
href="../mod/directive-dist.html#Context">Context</a> of the
|
|
directive. Configuration directives set in the <em>main server
|
|
context</em> (outside any <code><VirtualHost></code> container)
|
|
will be used only if they are not overriden by the virtual host
|
|
settings.</p>
|
|
|
|
<p>Now when a request arrives, the server will first check if it is
|
|
using an IP address that matches the <code>NameVirtualHost</code>. If
|
|
it is, then it will look at each <code><VirtualHost></code>
|
|
section with a matching IP address and try to find one where the
|
|
<code>ServerName</code> or <code>ServerAlias</code> matches the
|
|
requested hostname. If it finds one, then it uses the configuration
|
|
for that server. If no matching virtual host is found, then
|
|
<strong>the first listed virtual host</strong> that matches the IP
|
|
address will be used.</p>
|
|
|
|
<p>As a consequence, the first listed virtual host is the
|
|
<em>default</em> virtual host. The <code>DocumentRoot</code> from the
|
|
<em>main server</em> will <strong>never</strong> be used when an IP
|
|
address matches the <code>NameVirtualHost</code> directive. If you
|
|
would like to have a special configuration for requests that do not
|
|
match any particular virtual host, simply put that configuration in a
|
|
<code><VirtualHost></code> container and list it first in the
|
|
configuration file.</p>
|
|
|
|
<h2><a name="compat">Compatibility with Older Browsers</a></h2>
|
|
|
|
<p>As mentioned earlier, there are some clients
|
|
who do not send the required data for the name-based virtual
|
|
hosts to work properly. These clients will always be sent the
|
|
pages from the first virtual host listed for that IP address
|
|
(the <cite>primary</cite> name-based virtual host).</p>
|
|
|
|
<p>There is a possible workaround with the <a
|
|
href="../mod/core.html#serverpath"><code>ServerPath</code></a>
|
|
directive, albeit a slightly cumbersome one:</p>
|
|
|
|
<p>Example configuration:</p>
|
|
<pre>
|
|
NameVirtualHost 111.22.33.44
|
|
|
|
<VirtualHost 111.22.33.44>
|
|
ServerName www.domain.tld
|
|
ServerPath /domain
|
|
DocumentRoot /web/domain
|
|
</VirtualHost>
|
|
</pre>
|
|
|
|
<p>What does this mean? It means that a request for any URI
|
|
beginning with "<samp>/domain</samp>" will be served from the
|
|
virtual host <samp>www.domain.tld</samp> This means that the
|
|
pages can be accessed as
|
|
<code>http://www.domain.tld/domain/</code> for all clients,
|
|
although clients sending a <samp>Host:</samp> header can also
|
|
access it as <code>http://www.domain.tld/</code>.</p>
|
|
|
|
<p>In order to make this work, put a link on your primary
|
|
virtual host's page to
|
|
<samp>http://www.domain.tld/domain/</samp> Then, in the virtual
|
|
host's pages, be sure to use either purely relative links
|
|
(<em>e.g.</em>, "<samp>file.html</samp>" or
|
|
"<samp>../icons/image.gif</samp>" or links containing the
|
|
prefacing <samp>/domain/</samp> (<em>e.g.</em>,
|
|
"<samp>http://www.domain.tld/domain/misc/file.html</samp>" or
|
|
"<samp>/domain/misc/file.html</samp>").</p>
|
|
|
|
<p>This requires a bit of discipline, but adherence to these
|
|
guidelines will, for the most part, ensure that your pages will
|
|
work with all browsers, new and old.</p>
|
|
|
|
<p>See also: <a href="examples.html#serverpath">ServerPath
|
|
configuration example</a></p>
|
|
<!--#include virtual="footer.html" -->
|
|
</body>
|
|
</html>
|
|
|