From ef81d4ba83ce827f331ef1df8d67415dd03787a9 Mon Sep 17 00:00:00 2001 From: Eric Covener Date: Tue, 28 Dec 2010 00:53:56 +0000 Subject: Doc for r1053230, NameVirtualHost is now unnecessary and other general NVH-vs-VH improvements. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1053231 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/vhosts/details.xml | 157 +++++++------------------------------- docs/manual/vhosts/examples.xml | 42 ++-------- docs/manual/vhosts/index.xml | 1 - docs/manual/vhosts/ip-based.xml | 24 ++++-- docs/manual/vhosts/mass.xml | 1 - docs/manual/vhosts/name-based.xml | 65 +++++----------- 6 files changed, 75 insertions(+), 215 deletions(-) (limited to 'docs/manual/vhosts') diff --git a/docs/manual/vhosts/details.xml b/docs/manual/vhosts/details.xml index 5702131a68..8fc83fd933 100644 --- a/docs/manual/vhosts/details.xml +++ b/docs/manual/vhosts/details.xml @@ -66,16 +66,10 @@ resolutions fail, those virtual host definitions are ignored. This is, therefore, not recommended.

-

If using IP-based vhosts, the address can be specified - as _default_, which will match a request if no - other vhost has the explicit address on which the request was - received.

- -

If using name-based vhosts, the address can be specified as +

The address can be specified as *, which will match a request if no other vhost has the explicit address on which the request was - received. The corresponding NameVirtualHost - directive must also use *.

+ received.

The address appearing in the VirtualHost directive can have an optional port. If the port is unspecified, @@ -95,11 +89,10 @@ results from DNS lookups) are called the vhost's address set.

-

If you want Apache to discriminate on the - basis of the HTTP Host header supplied by the client, - the NameVirtualHost directive must appear - with the exact IP address (or wildcard) and port pair used in a - corresponding set of VirtualHost directives.

+

Apache automatically discriminates on the + basis of the HTTP Host header supplied by the client + whenever the most specific match for an IP address and port combination + is listed in multiple virtual hosts.

The ServerName directive @@ -108,11 +101,6 @@ server). If no ServerName is specified, the server attempts to deduce it from the server's IP address.

-

Multiple NameVirtualHost directives can be used, - each with a set of VirtualHost directives, but only - one NameVirtualHost directive should be used for - each specific IP:port pair.

-

The first name-based vhost in the configuration file for a given IP:port pair is significant because it is used for all requests received on that address and port for which no other @@ -121,66 +109,6 @@ server does not support Server Name Indication.

-

If there are no vhosts defined for an address in a - NameVirtualHost directive, the - NameVirtualHost directive is ignored at startup and an error is - logged.

- -

The ordering of NameVirtualHost and - VirtualHost directives is not important, which - makes the following two examples identical (only the order of - the VirtualHost directives for one - address set is important, see below):

- - - - -
- NameVirtualHost 111.22.33.44
- <VirtualHost 111.22.33.44>
- # server A
- ...
- </VirtualHost>
- <VirtualHost 111.22.33.44>
- # server B
- ...
- </VirtualHost>
-
- NameVirtualHost 111.22.33.55
- <VirtualHost 111.22.33.55>
- # server C
- ...
- </VirtualHost>
- <VirtualHost 111.22.33.55>
- # server D
- ...
- </VirtualHost> -		 - <VirtualHost 111.22.33.44>
- # server A
- </VirtualHost>
- <VirtualHost 111.22.33.55>
- # server C
- ...
- </VirtualHost>
- <VirtualHost 111.22.33.44>
- # server B
- ...
- </VirtualHost>
- <VirtualHost 111.22.33.55>
- # server D
- ...
- </VirtualHost>
-
- NameVirtualHost 111.22.33.44
- NameVirtualHost 111.22.33.55
-
-
- - -

(To aid the readability of your configuration you should - prefer the left variant.)

-

For every vhost various default values are set. In particular:

@@ -245,10 +173,6 @@

If there are no exact matches for the address and port, then wildcard (*) matches are considered.

-

If there are still no matches, then vhosts with IP - address specified as _default_ that match the - port are considered.

-

If no matches are found, the request is served by the main server.

@@ -260,17 +184,19 @@
IP-based vhost -

If there is no NameVirtualHost directive - matching the vhost, no further actions are performed and - the request is served from the first matching vhost.

+

If there is exactly one VirtualHost directive + listing the IP address and port combibation that was determined + to be the best match, no further actions are performed and + the request is served from the matching vhost.

Name-based vhost -

If the entry corresponds to a name-based vhost, the "list" in - the remaining steps refers to the list of vhosts that matched, in - the order they were in the configuration file.

+

If there are multiple VirtalHost directives listing + the IP address and port combination that was determined to be the + best match, the "list" in the remaining steps refers to the list of vhosts + that matched, in the order they were in the configuration file.

If the connection is using SSL, the server supports Server Name Indication, and @@ -324,20 +250,18 @@

Observations
    -
  • A name-based vhost can never interfere with an IP-base - vhost and vice versa. IP-based vhosts can only be reached - through an IP address of its own address set and never - through any other address. The same applies to name-based - vhosts, they can only be reached through an IP address of the - corresponding address set which must be defined with a - NameVirtualHost directive.
    • - -
  • ServerAlias +
  • Name-based virtual hosting is a process applied after + the server has selected the best matching IP-based virtual + host.
    • + +
  • If you don't care what IP address the client has connected to, use a + "*" as the address of every virtual host, and name-based virtual hosting + is applied across all configured virtual hosts.
    • + +
  • ServerName and ServerAlias checks are never performed for an IP-based vhost.
    • -
  • The order of name-/IP-based, the _default_ - vhost and the NameVirtualHost directive within - the config file is not important. Only the ordering of +
  • Only the ordering of name-based vhosts for a specific address set is significant. The one name-based vhosts that comes first in the configuration file has the highest priority for its @@ -347,39 +271,18 @@ matching process. Apache always uses the real port to which the client sent the request.
    • -
  • If two IP-based vhosts have an address in common, the - vhost appearing first in the config file is always matched. - Such a thing might happen inadvertently. The server will give - a warning in the error logfile when it detects this.
    • - -
  • A _default_ vhost catches a request only if - there is no other vhost with a matching IP address - and a matching port number for the request. The - request is only caught if the port number to which the client - sent the request matches the port number of your - _default_ vhost which is your standard - Listen by default. A wildcard port can be - specified (i.e., _default_:*) to catch - requests to any available port. This also applies to - NameVirtualHost * vhosts. Note that this is simply an - extension of the "best match" principle, as a specific and exact match - is favored over a wildcard.
    • +
  • If two vhosts have an address in common, those common addresses + act as name-based virtual hosts implicitly. This is new behavior as of + 2.3.11.
  • The main server is only used to serve a request if the IP address and port number to which the client connected does not match any vhost (including a - _default_ vhost). In other words, the main server + * vhost). In other words, the main server only catches a request for an unspecified address/port combination (unless there is a _default_ vhost which matches that port).
    • -
  • A _default_ vhost or the main server is - never matched for a request with an unknown or - missing Host: header field if the client - connected to an address (and port) which is used for - name-based vhosts, e.g., in a - NameVirtualHost directive.
    • -
  • You should never specify DNS names in VirtualHost directives because it will force your server to rely on DNS to boot. Furthermore it poses a @@ -408,10 +311,6 @@ readability of the configuration -- the post-config merging process makes it non-obvious that definitions mixed in around virtual hosts might affect all virtual hosts.)
    • - -
  • Group corresponding NameVirtualHost and - VirtualHost definitions in your configuration to - ensure better readability.
diff --git a/docs/manual/vhosts/examples.xml b/docs/manual/vhosts/examples.xml index ef6ec3010f..4a70b5a979 100644 --- a/docs/manual/vhosts/examples.xml +++ b/docs/manual/vhosts/examples.xml @@ -59,8 +59,6 @@ # Ensure that Apache listens on port 80
Listen 80

- # Listen for virtual host requests on all IP addresses
- NameVirtualHost *:80

<VirtualHost *:80>
@@ -95,17 +93,9 @@ Note -

You can, if you wish, replace * with the actual - IP address of the system. In that case, the argument to - VirtualHost must match the argument to - NameVirtualHost:

- - - NameVirtualHost 172.20.30.40
-
- <VirtualHost 172.20.30.40>
- # etc ... - +

You can, if you wish, replace * with the actual + IP address of the system, when you don't care to discriminate based + on the IP address or port.

However, it is additionally useful to use * on systems where the IP address is not predictable - for @@ -145,9 +135,6 @@ ServerName server.example.com
DocumentRoot /www/mainserver

- # This is the other address
- NameVirtualHost 172.20.30.50
-
<VirtualHost 172.20.30.50>
DocumentRoot /www/example1
@@ -195,8 +182,6 @@ Server configuration - NameVirtualHost 192.168.1.1
- NameVirtualHost 172.20.30.40

<VirtualHost 192.168.1.1 172.20.30.40>
@@ -227,10 +212,9 @@ ports.

You have multiple domains going to the same IP and also want to - serve multiple ports. By defining the ports in the "NameVirtualHost" - tag, you can allow this to work. If you try using <VirtualHost - name:port> without the NameVirtualHost name:port or you try to use - the Listen directive, your configuration will not work.

+ serve multiple ports. The example below illustrates that the name-matching + takes place after the best matching IP address and port combination + is determined.

Server configuration @@ -238,9 +222,6 @@ Listen 80
Listen 8080

- NameVirtualHost 172.20.30.40:80
- NameVirtualHost 172.20.30.40:8080
-
<VirtualHost 172.20.30.40:80>
ServerName www.example.com
@@ -357,16 +338,13 @@
Mixed name-based and IP-based vhosts -

On some of my addresses, I want to do name-based virtual hosts, and - on others, IP-based hosts.

+

Any address mentioned in the argument to a virtualhost that never + appears in another virtual host is a strictly IP-based virtual host.

Server configuration Listen 80
-
- NameVirtualHost 172.20.30.40
-
<VirtualHost 172.20.30.40>
DocumentRoot /www/example1
@@ -540,8 +518,6 @@ ServerName www.example.com
DocumentRoot /www/example1

- NameVirtualHost 172.20.30.40
-
<VirtualHost 172.20.30.40 172.20.30.50>
DocumentRoot /www/example2
@@ -581,8 +557,6 @@ Server configuration - NameVirtualHost 172.20.30.40
-
<VirtualHost 172.20.30.40>
# primary vhost
diff --git a/docs/manual/vhosts/index.xml b/docs/manual/vhosts/index.xml index fbb2c247fe..055a404fa4 100644 --- a/docs/manual/vhosts/index.xml +++ b/docs/manual/vhosts/index.xml @@ -82,7 +82,6 @@ hosts
  • VirtualHost
    • -
  • NameVirtualHost
  • ServerName
  • ServerAlias
  • ServerPath
    • diff --git a/docs/manual/vhosts/ip-based.xml b/docs/manual/vhosts/ip-based.xml index 24196c0e4d..9fde89fe51 100644 --- a/docs/manual/vhosts/ip-based.xml +++ b/docs/manual/vhosts/ip-based.xml @@ -28,6 +28,18 @@ Name-based Virtual Hosts Support +
    What is IP-based virtual hosting +

    IP-based virtual hosting is a method to apply different directives +based on the IP address and port a request is received on. Most commonly, +this is used to serve different websites on different ports or interfaces.

    + +

    In many cases, name-based +virtual hosts are more convenient, because they allow +many virtual hosts to share a single address/port. +See Name-based vs. IP-based +Virtual Hosts to help you decide.

    +
    +
    System requirements

    As the term IP-based indicates, the server @@ -40,12 +52,8 @@ most commonly used to set them up), and/or using multiple port numbers.

    -

    In many cases, name-based - virtual hosts are more convenient, because they allow - many virtual hosts to share a single address/port. - See Name-based vs. IP-based - Virtual Hosts to help you decide. -

    +

    In the terminology of Apache HTTP Servr, using a single IP address + but multiple TCP ports, is also IP-based virtual hosting.

    @@ -147,6 +155,10 @@ hostname in the <VirtualHost> directive (see DNS caveats).

    +

    Specific IP addresses or ports have precedence over their wildcard + equivalents, and any virtual host that matches has precedence over + the servers base configuration.

    +

    Almost any configuration directive can be put in the VirtualHost directive, with the exception of directives that control process creation and a few other diff --git a/docs/manual/vhosts/mass.xml b/docs/manual/vhosts/mass.xml index 4755130667..227e95fb50 100644 --- a/docs/manual/vhosts/mass.xml +++ b/docs/manual/vhosts/mass.xml @@ -43,7 +43,6 @@ 

    -NameVirtualHost 111.22.33.44
 <VirtualHost 111.22.33.44>
     ServerName                 customer-1.example.com
     DocumentRoot        /www/hosts/customer-1.example.com/docs
diff --git a/docs/manual/vhosts/name-based.xml b/docs/manual/vhosts/name-based.xml
index 476547d355..1ff58e0875 100644
--- a/docs/manual/vhosts/name-based.xml
+++ b/docs/manual/vhosts/name-based.xml
@@ -62,6 +62,10 @@
         they are on separate IP addresses.
+

Name-based virtual hosting builds off of the IP-based virtual host + selection algoirthm, meaning that searches for the proper server name + occur only between virtual hosts that have the best IP-based address.

+
@@ -71,23 +75,22 @@ 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 + for the IP address in all of the 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.

- -
The default name-based vhost for a NameVirtualHost -

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.

+

When a request arrives, the server will find the best (most specific) matching + VirtualHost argument based on + the IP address and port used by the request. If there is more than one virtual host + contanin this best-match address and port combination, Apache will further + compare the ServerName and ServerAlias directives to the server name + present in the request.

+ +
The default name-based vhost for an IP and port combination +

If no matching ServerName or ServerAlias is found in the set of + virtual hosts containing the most specific matching IP address and port + combination, then the first listed virtual host that + matches the will be used.

Using Name-based Virtual Hosts @@ -99,38 +102,15 @@ DocumentRoot - NameVirtualHost ServerAlias ServerName VirtualHost -

To use name-based virtual hosting, you must designate the IP - address (and possibly port) on the server that will be accepting - requests that need to be distinguished by hostname. - This is configured using the NameVirtualHost directive. - In the normal case where any and all IP addresses on the server should - be used, you can use * as the argument to NameVirtualHost. If you're planning to use - multiple ports (e.g. running SSL) you should add a Port to the argument, - such as *:80.

- -

Note that mentioning an IP address in a - NameVirtualHost directive does not - automatically make the server listen to that IP address. See - Setting which addresses and ports Apache uses - for more details. In addition, any IP address specified here must be - associated with a network interface on the server.

 - -

The next step is to create a The first step is to create a VirtualHost block for - each different host that you would like to serve. The argument to the - VirtualHost directive - must match a defined NameVirtualHost directive. (In this usual case, - this will be "*:80"). Inside each VirtualHost block, you will need at minimum a ServerName directive to designate which host is served and a DocumentRoot @@ -158,8 +138,6 @@ Then you simply add the following to httpd.conf:

- NameVirtualHost *:80
-
<VirtualHost *:80>
# This first-listed virtual host is also the default for *:80 @@ -177,8 +155,7 @@

You can alternatively specify an explicit IP address in place of the - * in both the NameVirtualHost and * in VirtualHost directives. For example, you might want to do this in order to run some name-based virtual hosts on one IP address, and either IP-based, or another set of name-based virtual hosts on another address.

-- cgit v1.2.3