From: Eric Covener Date: Wed, 8 Dec 2010 16:52:34 +0000 (+0000) Subject: Move the description of how a name-based vhost is picked to the top X-Git-Tag: 2.3.10~49 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=70fb157dfe349c84380cb022fbe90750f4e03b2e;p=apache Move the description of how a name-based vhost is picked to the top instead of burying it. Reword some other "default vhost" references. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1043516 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/vhosts/name-based.xml b/docs/manual/vhosts/name-based.xml index 3d1b40a66a..54bea219ab 100644 --- a/docs/manual/vhosts/name-based.xml +++ b/docs/manual/vhosts/name-based.xml @@ -39,10 +39,9 @@ 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.

+

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.

Name-based virtual hosting is usually simpler, since you need only configure your DNS server to map each hostname to the correct @@ -63,6 +62,30 @@ they are on separate IP addresses. + + + +

How the server selects the proper name-based virtual host + +

It is important to recognize that the first step in name-based virtual + host resolution is IP-based resolution. Name-based virtual host + resolution only chooses the most appropriate name-based virtual host + after narrowing down the candidates to the best IP-based match. Using a wildcard (*) + for the IP address in all of the NameVirtualHost and VirtualHost directives makes this + IP-based mapping irrelevant.

+ +

When a request arrives, the server will first check if it is using + an IP address that matches exactly any NameVirtualHost. If it is, then it will look at each VirtualHost section with a (literal) matching + IP address and try to find one where the ServerName or ServerAlias matches the requested + hostname. If it finds one, then it uses the configuration for that server.

+ +

If no matching ServerName or ServerAlias is found in the + set of virtual hosts matching the NameVirtualHost directive, then + the first listed virtual host that matches the IP + address will be used.

Using Name-based Virtual Hosts @@ -113,20 +136,23 @@ lives.

Main host goes away -

If you are adding virtual hosts to an existing web server, you - must also create a VirtualHost block for the existing host. The ServerName and DocumentRoot included in this virtual host should be the - same as the global ServerName and - DocumentRoot. List this virtual - host first in the configuration file so that it will act as the default - host.

+

Any request that doesn't match an existing VirtualHost is handled by the global + server configuration, regardless of the hostname or ServerName.

+ +

When you add a name-based virtual host to an existing server, and + the virtual host arguments match preexisting IP and port combinations, + requests will now be handled by an explicit virtual host. In this case, + it's usually wise to create a default virtual host + with a ServerName matching that of + the base server. New domains on the same interface and port, but + requiring separate configurations, can then be added as subsequent (non-default) + virtual hosts.

For example, suppose that you are serving the domain - www.domain.tld and you wish to add the virtual host - www.otherdomain.tld, which points at the same IP address. + www.example.com and you wish to add the virtual host + other.example.com, which points at the same IP address. Then you simply add the following to httpd.conf:

@@ -134,14 +160,15 @@
<VirtualHost *:80>
- ServerName www.domain.tld
- ServerAlias domain.tld *.domain.tld
+ # This first-listed virtual host is also the default for *:80 + ServerName www.example.com
+ ServerAlias example.com *.example.com
DocumentRoot /www/domain
 </VirtualHost>

<VirtualHost *:80>
- ServerName www.otherdomain.tld
+ ServerName other.example.com
DocumentRoot /www/otherdomain
 </VirtualHost>
@@ -164,11 +191,11 @@ web site:

- ServerAlias domain.tld *.domain.tld + ServerAlias example.com *.example.com -

then requests for all hosts in the domain.tld domain will - be served by the www.domain.tld virtual host. The wildcard +

then requests for all hosts in the example.com domain will + be served by the www.example.com 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 ServerName or ServerAlias. You must @@ -186,25 +213,6 @@ container) will be used only if they are not overridden by the virtual host settings.

-

Now when a request arrives, the server will first check if it is using - an IP address that matches the NameVirtualHost. If it is, then it will look at each VirtualHost section with a matching - IP address and try to find one where the ServerName or ServerAlias matches the requested - hostname. If it finds one, then it uses the configuration for that server. - If no matching virtual host is found, then the first listed virtual - host that matches the IP address will be used.

- -

As a consequence, the first listed virtual host is the default - virtual host. The DocumentRoot from - the main server will never be used when an IP - address matches the NameVirtualHost - 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 VirtualHost - container and list it first in the configuration file.

-