From: Eric Covener Date: Tue, 21 Apr 2009 02:13:04 +0000 (+0000) Subject: rework the NameVirtualHost documentation to hopefully be a little X-Git-Tag: 2.3.3~707 X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=9e08f2669d81ae45170631d95f65ad2aba0abf5e;p=thirdparty%2Fapache%2Fhttpd.git rework the NameVirtualHost documentation to hopefully be a little less confusing and match the conventional wisdom of the various support fora. Provide a longer example that demonstrates the 1:n nature, relation to IP-based vhosts, and always uses a port. Avoid phrasing that makes NVH look like Listen. Remove the over-complicated hints about NVH impact on _default_ and base server configs, which boils down to the basic ip-based vhost mapping algorithm. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@766945 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/core.html.en b/docs/manual/mod/core.html.en index 76c984cdeec..aa6874fd053 100644 --- a/docs/manual/mod/core.html.en +++ b/docs/manual/mod/core.html.en @@ -2223,40 +2223,56 @@ hosting Status:Core Module:core -

The NameVirtualHost directive is a - required directive if you want to configure name-based virtual hosts.

-

Although addr can be hostname it is recommended - that you always use an IP address, e.g.

- -

- NameVirtualHost 111.22.33.44 -

- -

With the NameVirtualHost directive you - specify the IP address on which the server will receive requests - for the name-based virtual hosts. This will usually be the address - to which your name-based virtual host names resolve. In cases - where a firewall or other proxy receives the requests and forwards - them on a different IP address to the server, you must specify the - IP address of the physical interface on the machine which will be - servicing the requests. If you have multiple name-based hosts on - multiple addresses, repeat the directive for each address.

- -

Note

-

Note, that the "main server" and any _default_ servers - will never be served for a request to a - NameVirtualHost IP address (unless for some - reason you specify NameVirtualHost but then - don't define any VirtualHosts for that - address).

-
- -

Optionally you can specify a port number on which the - name-based virtual hosts should be used, e.g.

+

A single NameVirtualHost directive +identifies a set of identical virtual hosts on which the server will +further select from on the basis of the hostname +requested by the client. The NameVirtualHost +directive is a required directive if you want to configure +name-based virtual hosts.

+ +

This directive, and the corresponding VirtualHost, +must be qualified with a port number if the server supports both HTTP +and HTTPS connections.

+ +

Although addr can be a hostname, it is recommended +that you always use an IP address or a wildcard. A wildcard +NameVirtualHost matches only virtualhosts that also have a literal wildcard +as their argument.

+ +

In cases where a firewall or other proxy receives the requests and +forwards them on a different IP address to the server, you must specify the +IP address of the physical interface on the machine which will be +servicing the requests.

+ +

In the example below, requests received on interface 192.0.2.1 and port 80 +will only select among the first two virtual hosts. Requests received on +port 80 on any other interface will only select among the third and fourth +virtual hosts. In the common case where the interface isn't important +to the mapping, only the "*:80" NameVirtualHost and VirtualHost directives +are necessary.

+ +

+ NameVirtualHost 192.0.2.1:80
+ NameVirtualHost *:80

+ + <VirtualHost 192.0.2.1:80>
+   ServerName namebased-a.example.com
+ </VirtualHost>
+
+ <VirtualHost 192.0.2.1:80>
+   Servername namebased-b.example.com
+ </VirtualHost>
+
+ <VirtualHost *:80>
+   ServerName namebased-c.example.com
+ </VirtualHost>
+
+ <VirtualHost *:80>
+   ServerName namebased-d.example.com
+ </VirtualHost>
+
-

- NameVirtualHost 111.22.33.44:8080

IPv6 addresses must be enclosed in square brackets, as shown @@ -2266,21 +2282,14 @@ hosting NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080

-

To receive requests on all interfaces, you can use an argument of - *

- -

- NameVirtualHost * -

-

Argument to <VirtualHost> directive

Note that the argument to the <VirtualHost> directive must exactly match the argument to the NameVirtualHost directive.

- NameVirtualHost 1.2.3.4
- <VirtualHost 1.2.3.4>
+ NameVirtualHost 192.0.2.2:80
+ <VirtualHost 192.0.2.2:80>
# ...
</VirtualHost>

@@ -3280,11 +3289,7 @@ hostname or IP address not explicitly listed in another virtual host. In the absence of any _default_ virtual host the "main" server config, consisting of all those definitions outside any VirtualHost - section, is used when no IP-match occurs. (But note that any IP - address that matches a NameVirtualHost directive will use neither - the "main" server config nor the _default_ virtual host. - See the name-based virtual hosting - documentation for further details.)

+ section, is used when no IP-match occurs.

You can specify a :port to change the port that is matched. If unspecified then it defaults to the same port as the diff --git a/docs/manual/mod/core.xml b/docs/manual/mod/core.xml index 9e182f142ad..6119f867e00 100644 --- a/docs/manual/mod/core.xml +++ b/docs/manual/mod/core.xml @@ -2207,41 +2207,56 @@ hosting server config -

The NameVirtualHost directive is a - required directive if you want to configure name-based virtual hosts.

- -

Although addr can be hostname it is recommended - that you always use an IP address, e.g.

- - - NameVirtualHost 111.22.33.44 - -

With the NameVirtualHost directive you - specify the IP address on which the server will receive requests - for the name-based virtual hosts. This will usually be the address - to which your name-based virtual host names resolve. In cases - where a firewall or other proxy receives the requests and forwards - them on a different IP address to the server, you must specify the - IP address of the physical interface on the machine which will be - servicing the requests. If you have multiple name-based hosts on - multiple addresses, repeat the directive for each address.

- - Note -

Note, that the "main server" and any _default_ servers - will never be served for a request to a - NameVirtualHost IP address (unless for some - reason you specify NameVirtualHost but then - don't define any VirtualHosts for that - address).

- - -

Optionally you can specify a port number on which the - name-based virtual hosts should be used, e.g.

+

A single NameVirtualHost directive +identifies a set of identical virtual hosts on which the server will +further select from on the basis of the hostname +requested by the client. The NameVirtualHost +directive is a required directive if you want to configure +name-based virtual hosts.

+ +

This directive, and the corresponding VirtualHost, +must be qualified with a port number if the server supports both HTTP +and HTTPS connections.

+ +

Although addr can be a hostname, it is recommended +that you always use an IP address or a wildcard. A wildcard +NameVirtualHost matches only virtualhosts that also have a literal wildcard +as their argument.

+ +

In cases where a firewall or other proxy receives the requests and +forwards them on a different IP address to the server, you must specify the +IP address of the physical interface on the machine which will be +servicing the requests.

+ +

In the example below, requests received on interface 192.0.2.1 and port 80 +will only select among the first two virtual hosts. Requests received on +port 80 on any other interface will only select among the third and fourth +virtual hosts. In the common case where the interface isn't important +to the mapping, only the "*:80" NameVirtualHost and VirtualHost directives +are necessary.

+ + + NameVirtualHost 192.0.2.1:80
+ NameVirtualHost *:80

+ + <VirtualHost 192.0.2.1:80>
+   ServerName namebased-a.example.com
+ </VirtualHost>
+
+ <VirtualHost 192.0.2.1:80>
+   Servername namebased-b.example.com
+ </VirtualHost>
+
+ <VirtualHost *:80>
+   ServerName namebased-c.example.com
+ </VirtualHost>
+
+ <VirtualHost *:80>
+   ServerName namebased-d.example.com
+ </VirtualHost>
+
- - NameVirtualHost 111.22.33.44:8080

IPv6 addresses must be enclosed in square brackets, as shown @@ -2251,13 +2266,6 @@ hosting NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080 -

To receive requests on all interfaces, you can use an argument of - *

- - - NameVirtualHost * - - Argument to <directive type="section">VirtualHost</directive> directive

Note that the argument to the >NameVirtualHost directive.

- NameVirtualHost 1.2.3.4
- <VirtualHost 1.2.3.4>
+ NameVirtualHost 192.0.2.2:80
+ <VirtualHost 192.0.2.2:80>
# ...
</VirtualHost>
 @@ -3240,12 +3248,7 @@ hostname or IP address not explicitly listed in another virtual host. In the absence of any _default_ virtual host the "main" server config, consisting of all those definitions outside any VirtualHost - section, is used when no IP-match occurs. (But note that any IP - address that matches a NameVirtualHost directive will use neither - the "main" server config nor the _default_ virtual host. - See the name-based virtual hosting - documentation for further details.)

+ section, is used when no IP-match occurs.

You can specify a :port to change the port that is matched. If unspecified then it defaults to the same port as the