You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by co...@apache.org on 2009/04/21 04:13:05 UTC
svn commit: r766945 - in /httpd/httpd/trunk/docs/manual/mod: core.html.en
core.xml
Author: covener
Date: Tue Apr 21 02:13:04 2009
New Revision: 766945
URL: http://svn.apache.org/viewvc?rev=766945&view=rev
Log:
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.
Modified:
httpd/httpd/trunk/docs/manual/mod/core.html.en
httpd/httpd/trunk/docs/manual/mod/core.xml
Modified: httpd/httpd/trunk/docs/manual/mod/core.html.en
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/core.html.en?rev=766945&r1=766944&r2=766945&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/core.html.en (original)
+++ httpd/httpd/trunk/docs/manual/mod/core.html.en Tue Apr 21 02:13:04 2009
@@ -2223,40 +2223,56 @@
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Core</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>core</td></tr>
</table>
- <p>The <code class="directive">NameVirtualHost</code> directive is a
- required directive if you want to configure <a href="../vhosts/">name-based virtual hosts</a>.</p>
- <p>Although <var>addr</var> can be hostname it is recommended
- that you always use an IP address, e.g.</p>
-
- <div class="example"><p><code>
- NameVirtualHost 111.22.33.44
- </code></p></div>
-
- <p>With the <code class="directive">NameVirtualHost</code> 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.</p>
-
- <div class="note"><h3>Note</h3>
- <p>Note, that the "main server" and any <code>_default_</code> servers
- will <strong>never</strong> be served for a request to a
- <code class="directive">NameVirtualHost</code> IP address (unless for some
- reason you specify <code class="directive">NameVirtualHost</code> but then
- don't define any <code class="directive">VirtualHost</code>s for that
- address).</p>
- </div>
-
- <p>Optionally you can specify a port number on which the
- name-based virtual hosts should be used, e.g.</p>
+<p>A single <code class="directive">NameVirtualHost</code> directive
+identifies a set of identical virtual hosts on which the server will
+further select from on the basis of the <em>hostname</em>
+requested by the client. The <code class="directive">NameVirtualHost</code>
+directive is a required directive if you want to configure
+<a href="../vhosts/">name-based virtual hosts</a>.</p>
+
+<p>This directive, and the corresponding <code class="directive">VirtualHost</code>,
+<em>must</em> be qualified with a port number if the server supports both HTTP
+and HTTPS connections.</p>
+
+<p>Although <var>addr</var> 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.</p>
+
+<p>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. </p>
+
+<p> 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.</p>
+
+ <div class="example"><p><code>
+ NameVirtualHost 192.0.2.1:80<br />
+ NameVirtualHost *:80<br /><br />
+
+ <VirtualHost 192.0.2.1:80><br />
+ ServerName namebased-a.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost 192.0.2.1:80><br />
+ Servername namebased-b.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-c.example.com <br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-d.example.com <br />
+ </VirtualHost><br />
+ <br />
- <div class="example"><p><code>
- NameVirtualHost 111.22.33.44:8080
</code></p></div>
<p>IPv6 addresses must be enclosed in square brackets, as shown
@@ -2266,21 +2282,14 @@
NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080
</code></p></div>
- <p>To receive requests on all interfaces, you can use an argument of
- <code>*</code></p>
-
- <div class="example"><p><code>
- NameVirtualHost *
- </code></p></div>
-
<div class="note"><h3>Argument to <code class="directive"><VirtualHost></code>
directive</h3>
<p>Note that the argument to the <code class="directive"><VirtualHost></code> directive must
exactly match the argument to the <code class="directive">NameVirtualHost</code> directive.</p>
<div class="example"><p><code>
- NameVirtualHost 1.2.3.4<br />
- <VirtualHost 1.2.3.4><br />
+ NameVirtualHost 192.0.2.2:80<br />
+ <VirtualHost 192.0.2.2:80><br />
# ...<br />
</VirtualHost><br />
</code></p></div>
@@ -3280,11 +3289,7 @@
not explicitly listed in another virtual host. In the absence
of any <code>_default_</code> 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 <code class="directive"><a href="#namevirtualhost">NameVirtualHost</a></code> directive will use neither
- the "main" server config nor the <code>_default_</code> virtual host.
- See the <a href="../vhosts/name-based.html">name-based virtual hosting</a>
- documentation for further details.)</p>
+ section, is used when no IP-match occurs.</p>
<p>You can specify a <code>:port</code> to change the port that is
matched. If unspecified then it defaults to the same port as the
Modified: httpd/httpd/trunk/docs/manual/mod/core.xml
URL: http://svn.apache.org/viewvc/httpd/httpd/trunk/docs/manual/mod/core.xml?rev=766945&r1=766944&r2=766945&view=diff
==============================================================================
--- httpd/httpd/trunk/docs/manual/mod/core.xml (original)
+++ httpd/httpd/trunk/docs/manual/mod/core.xml Tue Apr 21 02:13:04 2009
@@ -2207,41 +2207,56 @@
<contextlist><context>server config</context></contextlist>
<usage>
- <p>The <directive>NameVirtualHost</directive> directive is a
- required directive if you want to configure <a
- href="../vhosts/">name-based virtual hosts</a>.</p>
-
- <p>Although <var>addr</var> can be hostname it is recommended
- that you always use an IP address, e.g.</p>
-
- <example>
- NameVirtualHost 111.22.33.44
- </example>
- <p>With the <directive>NameVirtualHost</directive> 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.</p>
-
- <note><title>Note</title>
- <p>Note, that the "main server" and any <code>_default_</code> servers
- will <strong>never</strong> be served for a request to a
- <directive>NameVirtualHost</directive> IP address (unless for some
- reason you specify <directive>NameVirtualHost</directive> but then
- don't define any <directive>VirtualHost</directive>s for that
- address).</p>
- </note>
-
- <p>Optionally you can specify a port number on which the
- name-based virtual hosts should be used, e.g.</p>
+<p>A single <directive>NameVirtualHost</directive> directive
+identifies a set of identical virtual hosts on which the server will
+further select from on the basis of the <em>hostname</em>
+requested by the client. The <code class="directive">NameVirtualHost</code>
+directive is a required directive if you want to configure
+<a href="../vhosts/">name-based virtual hosts</a>.</p>
+
+<p>This directive, and the corresponding <directive >VirtualHost</directive>,
+<em>must</em> be qualified with a port number if the server supports both HTTP
+and HTTPS connections.</p>
+
+<p>Although <var>addr</var> 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.</p>
+
+<p>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. </p>
+
+<p> 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.</p>
+
+ <example>
+ NameVirtualHost 192.0.2.1:80<br />
+ NameVirtualHost *:80<br /><br />
+
+ <VirtualHost 192.0.2.1:80><br />
+ ServerName namebased-a.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost 192.0.2.1:80><br />
+ Servername namebased-b.example.com<br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-c.example.com <br />
+ </VirtualHost><br />
+ <br />
+ <VirtualHost *:80><br />
+ ServerName namebased-d.example.com <br />
+ </VirtualHost><br />
+ <br />
- <example>
- NameVirtualHost 111.22.33.44:8080
</example>
<p>IPv6 addresses must be enclosed in square brackets, as shown
@@ -2251,13 +2266,6 @@
NameVirtualHost [2001:db8::a00:20ff:fea7:ccea]:8080
</example>
- <p>To receive requests on all interfaces, you can use an argument of
- <code>*</code></p>
-
- <example>
- NameVirtualHost *
- </example>
-
<note><title>Argument to <directive type="section">VirtualHost</directive>
directive</title>
<p>Note that the argument to the <directive
@@ -2266,8 +2274,8 @@
>NameVirtualHost</directive> directive.</p>
<example>
- NameVirtualHost 1.2.3.4<br />
- <VirtualHost 1.2.3.4><br />
+ NameVirtualHost 192.0.2.2:80<br />
+ <VirtualHost 192.0.2.2:80><br />
# ...<br />
</VirtualHost><br />
</example>
@@ -3240,12 +3248,7 @@
not explicitly listed in another virtual host. In the absence
of any <code>_default_</code> 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 <directive
- module="core">NameVirtualHost</directive> directive will use neither
- the "main" server config nor the <code>_default_</code> virtual host.
- See the <a href="../vhosts/name-based.html">name-based virtual hosting</a>
- documentation for further details.)</p>
+ section, is used when no IP-match occurs.</p>
<p>You can specify a <code>:port</code> to change the port that is
matched. If unspecified then it defaults to the same port as the