diff options
| -rw-r--r-- | docs/manual/vhosts/details.html.en | 404 | ||||
| -rw-r--r-- | docs/manual/vhosts/details.xml | 416 | ||||
| -rw-r--r-- | docs/manual/vhosts/examples.html.en | 574 | ||||
| -rw-r--r-- | docs/manual/vhosts/examples.xml | 592 | ||||
| -rw-r--r-- | docs/manual/vhosts/fd-limits.html.en | 77 | ||||
| -rw-r--r-- | docs/manual/vhosts/fd-limits.xml | 112 | ||||
| -rw-r--r-- | docs/manual/vhosts/index.html.en | 82 | ||||
| -rw-r--r-- | docs/manual/vhosts/index.xml | 83 | ||||
| -rw-r--r-- | docs/manual/vhosts/ip-based.html.en | 119 | ||||
| -rw-r--r-- | docs/manual/vhosts/ip-based.xml | 150 | ||||
| -rw-r--r-- | docs/manual/vhosts/mass.html.en | 389 | ||||
| -rw-r--r-- | docs/manual/vhosts/mass.xml | 420 | ||||
| -rw-r--r-- | docs/manual/vhosts/name-based.html.en | 367 | ||||
| -rw-r--r-- | docs/manual/vhosts/name-based.xml | 234 |
14 files changed, 3712 insertions, 307 deletions
diff --git a/docs/manual/vhosts/details.html.en b/docs/manual/vhosts/details.html.en new file mode 100644 index 0000000000..a5b21ecac9 --- /dev/null +++ b/docs/manual/vhosts/details.html.en @@ -0,0 +1,404 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>An In-Depth Discussion of Virtual Host Matching - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>An In-Depth Discussion of Virtual Host Matching</h1> + + <p>The virtual host code was completely rewritten in + <strong>Apache 1.3</strong>. This document attempts to explain + exactly what Apache does when deciding what virtual host to + serve a hit from. With the help of the new + <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> + directive virtual host configuration should be a lot easier and + safer than with versions prior to 1.3.</p> + + <p>If you just want to <cite>make it work</cite> without + understanding how, here are <a href="examples.html">some + examples</a>.</p> + +</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#configparsing">Config File Parsing</a></li><li><img alt="" src="../images/down.gif" /> <a href="#hostmatching">Virtual Host Matching</a></li><li><img alt="" src="../images/down.gif" /> <a href="#tips">Tips</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="configparsing" id="configparsing">Config File Parsing</a></h2> + + <p>There is a <em>main_server</em> which consists of all the + definitions appearing outside of + <code><VirtualHost></code> sections. There are virtual + servers, called <em>vhosts</em>, which are defined by + <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> + sections.</p> + + <p>The directives + <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>, + <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code>, + <code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code>, + and <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code> + can appear anywhere within the definition of a server. However, + each appearance overrides the previous appearance (within that + server).</p> + + <p>The default value of the <code>Listen</code> field for + main_server is 80. The main_server has no default + <code>ServerPath</code>, or <code>ServerAlias</code>. The + default <code>ServerName</code> is deduced from the servers IP + address.</p> + + <p>The main_server Listen directive has two functions. One + function is to determine the default network port Apache will + bind to. The second function is to specify the port number + which is used in absolute URIs during redirects.</p> + + <p>Unlike the main_server, vhost ports <em>do not</em> affect + what ports Apache listens for connections on.</p> + + <p>Each address appearing in the <code>VirtualHost</code> + directive can have an optional port. If the port is unspecified + it defaults to the value of the main_server's most recent + <code>Listen</code> statement. The special port <code>*</code> + indicates a wildcard that matches any port. Collectively the + entire set of addresses (including multiple <code>A</code> + record results from DNS lookups) are called the vhost's + <em>address set</em>.</p> + + <p>Unless a <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> + directive is used for a specific IP address the first vhost + with that address is treated as an IP-based vhost. The IP + address can also be the wildcard <code>*</code>.</p> + + <p>If name-based vhosts should be used a + <code>NameVirtualHost</code> directive <em>must</em> appear + with the IP address set to be used for the name-based vhosts. + In other words, you must specify the IP address that holds the + hostname aliases (CNAMEs) for your name-based vhosts via a + <code>NameVirtualHost</code> directive in your configuration + file.</p> + + <p>Multiple <code>NameVirtualHost</code> directives can be used + each with a set of <code>VirtualHost</code> directives but only + one <code>NameVirtualHost</code> directive should be used for + each specific IP:port pair.</p> + + <p>The ordering of <code>NameVirtualHost</code> and + <code>VirtualHost</code> directives is not important which + makes the following two examples identical (only the order of + the <code>VirtualHost</code> directives for <em>one</em> + address set is important, see below):</p> + +<table><tr> +<td><div class="example"><p><code> + NameVirtualHost 111.22.33.44<br /> + <VirtualHost 111.22.33.44><br /> + # server A<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.44><br /> + # server B<br /> + ...<br /> + </VirtualHost><br /> + <br /> + NameVirtualHost 111.22.33.55<br /> + <VirtualHost 111.22.33.55><br /> + # server C<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server D<br /> + ...<br /> + </VirtualHost> +</code></p></div></td> +<td><div class="example"><p><code> + <VirtualHost 111.22.33.44><br /> + # server A<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server C<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.44><br /> + # server B<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server D<br /> + ...<br /> + </VirtualHost><br /> + <br /> + NameVirtualHost 111.22.33.44<br /> + NameVirtualHost 111.22.33.55<br /> + <br /> +</code></p></div></td> +</tr></table> + + + <p>(To aid the readability of your configuration you should + prefer the left variant.)</p> + + <p>After parsing the <code>VirtualHost</code> directive, the + vhost server is given a default <code>Listen</code> equal to the + port assigned to the first name in its <code>VirtualHost</code> + directive.</p> + + <p>The complete list of names in the <code>VirtualHost</code> + directive are treated just like a <code>ServerAlias</code> (but + are not overridden by any <code>ServerAlias</code> statement) + if all names resolve to the same address set. Note that + subsequent <code>Listen</code> statements for this vhost will not + affect the ports assigned in the address set.</p> + + <p>During initialization a list for each IP address is + generated and inserted into an hash table. If the IP address is + used in a <code>NameVirtualHost</code> directive the list + contains all name-based vhosts for the given IP address. If + there are no vhosts defined for that address the + <code>NameVirtualHost</code> directive is ignored and an error + is logged. For an IP-based vhost the list in the hash table is + empty.</p> + + <p>Due to a fast hashing function the overhead of hashing an IP + address during a request is minimal and almost not existent. + Additionally the table is optimized for IP addresses which vary + in the last octet.</p> + + <p>For every vhost various default values are set. In + particular:</p> + + <ol> + <li>If a vhost has no <code class="directive"><a href="../mod/core.html#serveradmin">ServerAdmin</a></code>, + <code class="directive"><a href="../mod/core.html#resourceconfig">ResourceConfig</a></code>, + <code class="directive"><a href="../mod/core.html#accessconfig">AccessConfig</a></code>, + <code class="directive"><a href="../mod/core.html#timeout">Timeout</a></code>, + <code class="directive"><a href="../mod/core.html#keepalivetimeout">KeepAliveTimeout</a></code>, + <code class="directive"><a href="../mod/core.html#keepalive">KeepAlive</a></code>, + <code class="directive"><a href="../mod/core.html#maxkeepaliverequests">MaxKeepAliveRequests</a></code>, + or <code class="directive"><a href="../mod/core.html#sendbuffersize">SendBufferSize</a></code> + directive then the respective value is inherited from the + main_server. (That is, inherited from whatever the final + setting of that value is in the main_server.)</li> + + <li>The "lookup defaults" that define the default directory + permissions for a vhost are merged with those of the + main_server. This includes any per-directory configuration + information for any module.</li> + + <li>The per-server configs for each module from the + main_server are merged into the vhost server.</li> + </ol> + + <p>Essentially, the main_server is treated as "defaults" or a + "base" on which to build each vhost. But the positioning of + these main_server definitions in the config file is largely + irrelevant -- the entire config of the main_server has been + parsed when this final merging occurs. So even if a main_server + definition appears after a vhost definition it might affect the + vhost definition.</p> + + <p>If the main_server has no <code>ServerName</code> at this + point, then the hostname of the machine that httpd is running + on is used instead. We will call the <em>main_server address + set</em> those IP addresses returned by a DNS lookup on the + <code>ServerName</code> of the main_server.</p> + + <p>For any undefined <code>ServerName</code> fields, a + name-based vhost defaults to the address given first in the + <code>VirtualHost</code> statement defining the vhost.</p> + + <p>Any vhost that includes the magic <code>_default_</code> + wildcard is given the same <code>ServerName</code> as the + main_server.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="hostmatching" id="hostmatching">Virtual Host Matching</a></h2> + + <p>The server determines which vhost to use for a request as + follows:</p> + + <h3><a name="hashtable" id="hashtable">Hash table lookup</a></h3> + + <p>When the connection is first made by a client, the IP + address to which the client connected is looked up in the + internal IP hash table.</p> + + <p>If the lookup fails (the IP address wasn't found) the + request is served from the <code>_default_</code> vhost if + there is such a vhost for the port to which the client sent the + request. If there is no matching <code>_default_</code> vhost + the request is served from the main_server.</p> + + <p>If the IP address is not found in the hash table then the + match against the port number may also result in an entry + corresponding to a <code>NameVirtualHost *</code>, which is + subsequently handled like other name-based vhosts.</p> + + <p>If the lookup succeeded (a corresponding list for the IP + address was found) the next step is to decide if we have to + deal with an IP-based or a name-base vhost.</p> + + + + <h3><a name="ipbased" id="ipbased">IP-based vhost</a></h3> + + <p>If the entry we found has an empty name list then we have + found an IP-based vhost, no further actions are performed and + the request is served from that vhost.</p> + + + + <h3><a name="namebased" id="namebased">Name-based vhost</a></h3> + + <p>If the entry corresponds to a name-based vhost the name list + contains one or more vhost structures. This list contains the + vhosts in the same order as the <code>VirtualHost</code> + directives appear in the config file.</p> + + <p>The first vhost on this list (the first vhost in the config + file with the specified IP address) has the highest priority + and catches any request to an unknown server name or a request + without a <code>Host:</code> header field.</p> + + <p>If the client provided a <code>Host:</code> header field the + list is searched for a matching vhost and the first hit on a + <code>ServerName</code> or <code>ServerAlias</code> is taken + and the request is served from that vhost. A <code>Host:</code> + header field can contain a port number, but Apache always + matches against the real port to which the client sent the + request.</p> + + <p>If the client submitted a HTTP/1.0 request without + <code>Host:</code> header field we don't know to what server + the client tried to connect and any existing + <code>ServerPath</code> is matched against the URI from the + request. The first matching path on the list is used and the + request is served from that vhost.</p> + + <p>If no matching vhost could be found the request is served + from the first vhost with a matching port number that is on the + list for the IP to which the client connected (as already + mentioned before).</p> + + + + <h3><a name="persistent" id="persistent">Persistent connections</a></h3> + + <p>The IP lookup described above is only done <em>once</em> for a + particular TCP/IP session while the name lookup is done on + <em>every</em> request during a KeepAlive/persistent + connection. In other words a client may request pages from + different name-based vhosts during a single persistent + connection.</p> + + + + <h3><a name="absoluteURI" id="absoluteURI">Absolute URI</a></h3> + + <p>If the URI from the request is an absolute URI, and its + hostname and port match the main server or one of the + configured virtual hosts <em>and</em> match the address and + port to which the client sent the request, then the + scheme/hostname/port prefix is stripped off and the remaining + relative URI is served by the corresponding main server or + virtual host. If it does not match, then the URI remains + untouched and the request is taken to be a proxy request.</p> + + +<h3><a name="observations" id="observations">Observations</a></h3> + + <ul> + <li>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 + <code>NameVirtualHost</code> directive.</li> + + <li><code>ServerAlias</code> and <code>ServerPath</code> + checks are never performed for an IP-based vhost.</li> + + <li>The order of name-/IP-based, the <code>_default_</code> + vhost and the <code>NameVirtualHost</code> directive within + the config file is not important. 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 + corresponding address set.</li> + + <li>For security reasons the port number given in a + <code>Host:</code> header field is never used during the + matching process. Apache always uses the real port to which + the client sent the request.</li> + + <li>If a <code>ServerPath</code> directive exists which is a + prefix of another <code>ServerPath</code> directive that + appears later in the configuration file, then the former will + always be matched and the latter will never be matched. (That + is assuming that no <code>Host:</code> header field was + available to disambiguate the two.)</li> + + <li>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.</li> + + <li>A <code>_default_</code> vhost catches a request only if + there is no other vhost with a matching IP address + <em>and</em> 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 + <code>_default_</code> vhost which is your standard + <code>Listen</code> by default. A wildcard port can be + specified (<em>i.e.</em>, <code>_default_:*</code>) to catch + requests to any available port. This also applies to + <code>NameVirtualHost *</code> vhosts.</li> + + <li>The main_server is only used to serve a request if the IP + address and port number to which the client connected is + unspecified and does not match any other vhost (including a + <code>_default_</code> vhost). In other words the main_server + only catches a request for an unspecified address/port + combination (unless there is a <code>_default_</code> vhost + which matches that port).</li> + + <li>A <code>_default_</code> vhost or the main_server is + <em>never</em> matched for a request with an unknown or + missing <code>Host:</code> header field if the client + connected to an address (and port) which is used for + name-based vhosts, <em>e.g.</em>, in a + <code>NameVirtualHost</code> directive.</li> + + <li>You should never specify DNS names in + <code>VirtualHost</code> directives because it will force + your server to rely on DNS to boot. Furthermore it poses a + security threat if you do not control the DNS for all the + domains listed. There's <a href="../dns-caveats.html">more + information</a> available on this and the next two + topics.</li> + + <li><code>ServerName</code> should always be set for each + vhost. Otherwise A DNS lookup is required for each + vhost.</li> + </ul> + + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="tips" id="tips">Tips</a></h2> + + <p>In addition to the tips on the <a href="../dns-caveats.html#tips">DNS Issues</a> page, here are + some further tips:</p> + + <ul> + <li>Place all main_server definitions before any + <code>VirtualHost</code> definitions. (This is to aid the + 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.)</li> + + <li>Group corresponding <code>NameVirtualHost</code> and + <code>VirtualHost</code> definitions in your configuration to + ensure better readability.</li> + + <li>Avoid <code>ServerPaths</code> which are prefixes of + other <code>ServerPaths</code>. If you cannot avoid this then + you have to ensure that the longer (more specific) prefix + vhost appears earlier in the configuration file than the + shorter (less specific) prefix (<em>i.e.</em>, "ServerPath + /abc" should appear after "ServerPath /abc/def").</li> + </ul> + +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/details.xml b/docs/manual/vhosts/details.xml new file mode 100644 index 0000000000..8212402b6e --- /dev/null +++ b/docs/manual/vhosts/details.xml @@ -0,0 +1,416 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>An In-Depth Discussion of Virtual Host Matching</title> + +<summary> + + <p>The virtual host code was completely rewritten in + <strong>Apache 1.3</strong>. This document attempts to explain + exactly what Apache does when deciding what virtual host to + serve a hit from. With the help of the new + <directive module="core">NameVirtualHost</directive> + directive virtual host configuration should be a lot easier and + safer than with versions prior to 1.3.</p> + + <p>If you just want to <cite>make it work</cite> without + understanding how, here are <a href="examples.html">some + examples</a>.</p> + +</summary> + +<section id="configparsing"><title>Config File Parsing</title> + + <p>There is a <em>main_server</em> which consists of all the + definitions appearing outside of + <code><VirtualHost></code> sections. There are virtual + servers, called <em>vhosts</em>, which are defined by + <directive type="section" module="core">VirtualHost</directive> + sections.</p> + + <p>The directives + <directive module="mpm_common">Listen</directive>, + <directive module="core">ServerName</directive>, + <directive module="core">ServerPath</directive>, + and <directive module="core">ServerAlias</directive> + can appear anywhere within the definition of a server. However, + each appearance overrides the previous appearance (within that + server).</p> + + <p>The default value of the <code>Listen</code> field for + main_server is 80. The main_server has no default + <code>ServerPath</code>, or <code>ServerAlias</code>. The + default <code>ServerName</code> is deduced from the servers IP + address.</p> + + <p>The main_server Listen directive has two functions. One + function is to determine the default network port Apache will + bind to. The second function is to specify the port number + which is used in absolute URIs during redirects.</p> + + <p>Unlike the main_server, vhost ports <em>do not</em> affect + what ports Apache listens for connections on.</p> + + <p>Each address appearing in the <code>VirtualHost</code> + directive can have an optional port. If the port is unspecified + it defaults to the value of the main_server's most recent + <code>Listen</code> statement. The special port <code>*</code> + indicates a wildcard that matches any port. Collectively the + entire set of addresses (including multiple <code>A</code> + record results from DNS lookups) are called the vhost's + <em>address set</em>.</p> + + <p>Unless a <directive module="core">NameVirtualHost</directive> + directive is used for a specific IP address the first vhost + with that address is treated as an IP-based vhost. The IP + address can also be the wildcard <code>*</code>.</p> + + <p>If name-based vhosts should be used a + <code>NameVirtualHost</code> directive <em>must</em> appear + with the IP address set to be used for the name-based vhosts. + In other words, you must specify the IP address that holds the + hostname aliases (CNAMEs) for your name-based vhosts via a + <code>NameVirtualHost</code> directive in your configuration + file.</p> + + <p>Multiple <code>NameVirtualHost</code> directives can be used + each with a set of <code>VirtualHost</code> directives but only + one <code>NameVirtualHost</code> directive should be used for + each specific IP:port pair.</p> + + <p>The ordering of <code>NameVirtualHost</code> and + <code>VirtualHost</code> directives is not important which + makes the following two examples identical (only the order of + the <code>VirtualHost</code> directives for <em>one</em> + address set is important, see below):</p> + +<table><tr> +<td><example> + NameVirtualHost 111.22.33.44<br /> + <VirtualHost 111.22.33.44><br /> + # server A<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.44><br /> + # server B<br /> + ...<br /> + </VirtualHost><br /> + <br /> + NameVirtualHost 111.22.33.55<br /> + <VirtualHost 111.22.33.55><br /> + # server C<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server D<br /> + ...<br /> + </VirtualHost> +</example></td> +<td><example> + <VirtualHost 111.22.33.44><br /> + # server A<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server C<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.44><br /> + # server B<br /> + ...<br /> + </VirtualHost><br /> + <VirtualHost 111.22.33.55><br /> + # server D<br /> + ...<br /> + </VirtualHost><br /> + <br /> + NameVirtualHost 111.22.33.44<br /> + NameVirtualHost 111.22.33.55<br /> + <br /> +</example></td> +</tr></table> + + + <p>(To aid the readability of your configuration you should + prefer the left variant.)</p> + + <p>After parsing the <code>VirtualHost</code> directive, the + vhost server is given a default <code>Listen</code> equal to the + port assigned to the first name in its <code>VirtualHost</code> + directive.</p> + + <p>The complete list of names in the <code>VirtualHost</code> + directive are treated just like a <code>ServerAlias</code> (but + are not overridden by any <code>ServerAlias</code> statement) + if all names resolve to the same address set. Note that + subsequent <code>Listen</code> statements for this vhost will not + affect the ports assigned in the address set.</p> + + <p>During initialization a list for each IP address is + generated and inserted into an hash table. If the IP address is + used in a <code>NameVirtualHost</code> directive the list + contains all name-based vhosts for the given IP address. If + there are no vhosts defined for that address the + <code>NameVirtualHost</code> directive is ignored and an error + is logged. For an IP-based vhost the list in the hash table is + empty.</p> + + <p>Due to a fast hashing function the overhead of hashing an IP + address during a request is minimal and almost not existent. + Additionally the table is optimized for IP addresses which vary + in the last octet.</p> + + <p>For every vhost various default values are set. In + particular:</p> + + <ol> + <li>If a vhost has no <directive module="core">ServerAdmin</directive>, + <directive module="core">ResourceConfig</directive>, + <directive module="core">AccessConfig</directive>, + <directive module="core">Timeout</directive>, + <directive module="core">KeepAliveTimeout</directive>, + <directive module="core">KeepAlive</directive>, + <directive module="core">MaxKeepAliveRequests</directive>, + or <directive module="core">SendBufferSize</directive> + directive then the respective value is inherited from the + main_server. (That is, inherited from whatever the final + setting of that value is in the main_server.)</li> + + <li>The "lookup defaults" that define the default directory + permissions for a vhost are merged with those of the + main_server. This includes any per-directory configuration + information for any module.</li> + + <li>The per-server configs for each module from the + main_server are merged into the vhost server.</li> + </ol> + + <p>Essentially, the main_server is treated as "defaults" or a + "base" on which to build each vhost. But the positioning of + these main_server definitions in the config file is largely + irrelevant -- the entire config of the main_server has been + parsed when this final merging occurs. So even if a main_server + definition appears after a vhost definition it might affect the + vhost definition.</p> + + <p>If the main_server has no <code>ServerName</code> at this + point, then the hostname of the machine that httpd is running + on is used instead. We will call the <em>main_server address + set</em> those IP addresses returned by a DNS lookup on the + <code>ServerName</code> of the main_server.</p> + + <p>For any undefined <code>ServerName</code> fields, a + name-based vhost defaults to the address given first in the + <code>VirtualHost</code> statement defining the vhost.</p> + + <p>Any vhost that includes the magic <code>_default_</code> + wildcard is given the same <code>ServerName</code> as the + main_server.</p> + +</section> + +<section id="hostmatching"><title>Virtual Host Matching</title> + + <p>The server determines which vhost to use for a request as + follows:</p> + + <section id="hashtable"><title>Hash table lookup</title> + + <p>When the connection is first made by a client, the IP + address to which the client connected is looked up in the + internal IP hash table.</p> + + <p>If the lookup fails (the IP address wasn't found) the + request is served from the <code>_default_</code> vhost if + there is such a vhost for the port to which the client sent the + request. If there is no matching <code>_default_</code> vhost + the request is served from the main_server.</p> + + <p>If the IP address is not found in the hash table then the + match against the port number may also result in an entry + corresponding to a <code>NameVirtualHost *</code>, which is + subsequently handled like other name-based vhosts.</p> + + <p>If the lookup succeeded (a corresponding list for the IP + address was found) the next step is to decide if we have to + deal with an IP-based or a name-base vhost.</p> + + </section> + + <section id="ipbased"><title>IP-based vhost</title> + + <p>If the entry we found has an empty name list then we have + found an IP-based vhost, no further actions are performed and + the request is served from that vhost.</p> + + </section> + + <section id="namebased"><title>Name-based vhost</title> + + <p>If the entry corresponds to a name-based vhost the name list + contains one or more vhost structures. This list contains the + vhosts in the same order as the <code>VirtualHost</code> + directives appear in the config file.</p> + + <p>The first vhost on this list (the first vhost in the config + file with the specified IP address) has the highest priority + and catches any request to an unknown server name or a request + without a <code>Host:</code> header field.</p> + + <p>If the client provided a <code>Host:</code> header field the + list is searched for a matching vhost and the first hit on a + <code>ServerName</code> or <code>ServerAlias</code> is taken + and the request is served from that vhost. A <code>Host:</code> + header field can contain a port number, but Apache always + matches against the real port to which the client sent the + request.</p> + + <p>If the client submitted a HTTP/1.0 request without + <code>Host:</code> header field we don't know to what server + the client tried to connect and any existing + <code>ServerPath</code> is matched against the URI from the + request. The first matching path on the list is used and the + request is served from that vhost.</p> + + <p>If no matching vhost could be found the request is served + from the first vhost with a matching port number that is on the + list for the IP to which the client connected (as already + mentioned before).</p> + + </section> + + <section id="persistent"><title>Persistent connections</title> + + <p>The IP lookup described above is only done <em>once</em> for a + particular TCP/IP session while the name lookup is done on + <em>every</em> request during a KeepAlive/persistent + connection. In other words a client may request pages from + different name-based vhosts during a single persistent + connection.</p> + + </section> + + <section id="absoluteURI"><title>Absolute URI</title> + + <p>If the URI from the request is an absolute URI, and its + hostname and port match the main server or one of the + configured virtual hosts <em>and</em> match the address and + port to which the client sent the request, then the + scheme/hostname/port prefix is stripped off and the remaining + relative URI is served by the corresponding main server or + virtual host. If it does not match, then the URI remains + untouched and the request is taken to be a proxy request.</p> +</section> + +<section id="observations"><title>Observations</title> + + <ul> + <li>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 + <code>NameVirtualHost</code> directive.</li> + + <li><code>ServerAlias</code> and <code>ServerPath</code> + checks are never performed for an IP-based vhost.</li> + + <li>The order of name-/IP-based, the <code>_default_</code> + vhost and the <code>NameVirtualHost</code> directive within + the config file is not important. 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 + corresponding address set.</li> + + <li>For security reasons the port number given in a + <code>Host:</code> header field is never used during the + matching process. Apache always uses the real port to which + the client sent the request.</li> + + <li>If a <code>ServerPath</code> directive exists which is a + prefix of another <code>ServerPath</code> directive that + appears later in the configuration file, then the former will + always be matched and the latter will never be matched. (That + is assuming that no <code>Host:</code> header field was + available to disambiguate the two.)</li> + + <li>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.</li> + + <li>A <code>_default_</code> vhost catches a request only if + there is no other vhost with a matching IP address + <em>and</em> 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 + <code>_default_</code> vhost which is your standard + <code>Listen</code> by default. A wildcard port can be + specified (<em>i.e.</em>, <code>_default_:*</code>) to catch + requests to any available port. This also applies to + <code>NameVirtualHost *</code> vhosts.</li> + + <li>The main_server is only used to serve a request if the IP + address and port number to which the client connected is + unspecified and does not match any other vhost (including a + <code>_default_</code> vhost). In other words the main_server + only catches a request for an unspecified address/port + combination (unless there is a <code>_default_</code> vhost + which matches that port).</li> + + <li>A <code>_default_</code> vhost or the main_server is + <em>never</em> matched for a request with an unknown or + missing <code>Host:</code> header field if the client + connected to an address (and port) which is used for + name-based vhosts, <em>e.g.</em>, in a + <code>NameVirtualHost</code> directive.</li> + + <li>You should never specify DNS names in + <code>VirtualHost</code> directives because it will force + your server to rely on DNS to boot. Furthermore it poses a + security threat if you do not control the DNS for all the + domains listed. There's <a href="../dns-caveats.html">more + information</a> available on this and the next two + topics.</li> + + <li><code>ServerName</code> should always be set for each + vhost. Otherwise A DNS lookup is required for each + vhost.</li> + </ul> + </section> + +</section> + +<section id="tips"><title>Tips</title> + + <p>In addition to the tips on the <a + href="../dns-caveats.html#tips">DNS Issues</a> page, here are + some further tips:</p> + + <ul> + <li>Place all main_server definitions before any + <code>VirtualHost</code> definitions. (This is to aid the + 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.)</li> + + <li>Group corresponding <code>NameVirtualHost</code> and + <code>VirtualHost</code> definitions in your configuration to + ensure better readability.</li> + + <li>Avoid <code>ServerPaths</code> which are prefixes of + other <code>ServerPaths</code>. If you cannot avoid this then + you have to ensure that the longer (more specific) prefix + vhost appears earlier in the configuration file than the + shorter (less specific) prefix (<em>i.e.</em>, "ServerPath + /abc" should appear after "ServerPath /abc/def").</li> + </ul> + +</section> +</manualpage> + diff --git a/docs/manual/vhosts/examples.html.en b/docs/manual/vhosts/examples.html.en new file mode 100644 index 0000000000..05b81aec4e --- /dev/null +++ b/docs/manual/vhosts/examples.html.en @@ -0,0 +1,574 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>VirtualHost Examples - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>VirtualHost Examples</h1> + + <p>This document attempts to answer the commonly-asked questions about + setting up virtual hosts. These scenarios are those involving multiple + web sites running on a single server, via <a href="name-based.html">name-based</a> or <a href="ip-based.html">IP-based</a> virtual hosts. A document should be + coming soon about running sites on several servers behind a single + proxy server.</p> + +</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#purename">Running several name-based web + sites on a single IP address.</a></li><li><img alt="" src="../images/down.gif" /> <a href="#twoips">Name-based hosts on more than one + IP address.</a></li><li><img alt="" src="../images/down.gif" /> <a href="#intraextra">Serving the same content on + different IP addresses (such as an internal and external + address).</a></li><li><img alt="" src="../images/down.gif" /> <a href="#port">Running different sites on different + ports.</a></li><li><img alt="" src="../images/down.gif" /> <a href="#ip">IP-based virtual hosting</a></li><li><img alt="" src="../images/down.gif" /> <a href="#ipport">Mixed port-based and ip-based virtual + hosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#mixed">Mixed name-based and IP-based + vhosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#default">Using <code>_default_</code> + vhosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#migrate">Migrating a name-based vhost to an + IP-based vhost</a></li><li><img alt="" src="../images/down.gif" /> <a href="#serverpath">Using the <code>ServerPath</code> + directive</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="purename" id="purename">Running several name-based web + sites on a single IP address.</a></h2> + + <p>Your server has a single IP address, and multiple aliases (CNAMES) + point to this machine in DNS. You want to run a web server for + <code>www.example1.com</code> and <code>www.example2.org</code> on this + machine.</p> + + <div class="note"><h3>Note</h3><p>Creating virtual + host configurations on your Apache server does not magically + cause DNS entries to be created for those host names. You + <em>must</em> have the names in DNS, resolving to your IP + address, or nobody else will be able to see your web site. You + can put entries in your <code>hosts</code> file for local + testing, but that will work only from the machine with those + hosts entries.</p> + </div> + + <div class="example"><h3>Server configuration</h3><p><code> + + + # Ensure that Apache listens on port 80<br /> + Listen 80<br /> + <br /> + # Listen for virtual host requests on all IP addresses<br /> + NameVirtualHost *<br /> + <br /> + <VirtualHost *><br /> + <span class="indent"> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + <br /> + # Other directives here<br /> + <br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost *><br /> + <span class="indent"> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + <br /> + # Other directives here<br /> + <br /> + </span> + </VirtualHost> + </code></p></div> + + <p>The asterisks match all addresses, so the main server serves no + requests. Due to the fact that <code>www.example1.com</code> is first + in the configuration file, it has the highest priority and can be seen + as the <cite>default</cite> or <cite>primary</cite> server. That means + that if a request is received that does not match one of the specified + <code>ServerName</code> directives, it will be served by this first + <code>VirtualHost</code>.</p> + + <div class="note"> + <h3>Note</h3> + + <p>You can, if you wish, replace <code>*</code> with the actual + IP address of the system. In that case, the argument to + <code>VirtualHost</code> <em>must</em> match the argument to + <code>NameVirtualHost</code>:</p> + + <div class="example"><p><code> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + # etc ... + </code></p></div> + + <p>However, it is additionally useful to use <code>*</code> + on systems where the IP address is not predictable - for + example if you have a dynamic IP address with your ISP, and + you are using some variety of dynamic DNS solution. Since + <code>*</code> matches any IP address, this configuration + would work without changes whenever your IP address + changes.</p> + </div> + + <p>The above configuration is what you will want to use in almost + all name-based virtual hosting situations. The only think that this + configuration will not work for, in fact, is when you are serving + different content based on differing IP addresses or ports.</p> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="twoips" id="twoips">Name-based hosts on more than one + IP address.</a></h2> + + <div class="note"> + <h3>Note</h3><p>Any of the + techniques discussed here can be extended to any number of IP + addresses.</p> + </div> + + <p>The server has two IP addresses. On one (<code>172.20.30.40</code>), we + will serve the "main" server, <code>server.domain.com</code> and on the + other (<code>172.20.30.50</code>), we will serve two or more virtual hosts.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 80<br /> + <br /> + # This is the "main" server running on 172.20.30.40<br /> + ServerName server.domain.com<br /> + DocumentRoot /www/mainserver<br /> + <br /> + # This is the other address<br /> + NameVirtualHost 172.20.30.50<br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <span class="indent"> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + <br /> + # Other directives here ...<br /> + <br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <span class="indent"> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + <br /> + # Other directives here ...<br /> + <br /> + </span> + </VirtualHost> + </code></p></div> + + <p>Any request to an address other than <code>172.20.30.50</code> will be + served from the main server. A request to <code>172.20.30.50</code> with an + unknown hostname, or no <code>Host:</code> header, will be served from + <code>www.example1.com</code>.</p> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="intraextra" id="intraextra">Serving the same content on + different IP addresses (such as an internal and external + address).</a></h2> + + <p>The server machine has two IP addresses (<code>192.168.1.1</code> + and <code>172.20.30.40</code>). The machine is sitting between an + internal (intranet) network and an external (internet) network. Outside + of the network, the name <code>server.example.com</code> resolves to + the external address (<code>172.20.30.40</code>), but inside the + network, that same name resolves to the internal address + (<code>192.168.1.1</code>).</p> + + <p>The server can be made to respond to internal and external requests + with the same content, with just one <code>VirtualHost</code> + section.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + NameVirtualHost 192.168.1.1<br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 192.168.1.1 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/server1<br /> + ServerName server.example.com<br /> + ServerAlias server<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>Now requests from both networks will be served from the same + <code>VirtualHost</code>.</p> + + <div class="note"> + <h3>Note:</h3><p>On the internal + network, one can just use the name <code>server</code> rather + than the fully qualified host name + <code>server.example.com</code>.</p> + + <p>Note also that, in the above example, you can replace the list + of IP addresses with <code>*</code>, which will cause the server to + respond the same on all addresses.</p> + </div> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="port" id="port">Running different sites on different + ports.</a></h2> + + <p>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.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 80<br /> + Listen 8080<br /> + <br /> + NameVirtualHost 172.20.30.40:80<br /> + NameVirtualHost 172.20.30.40:8080<br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <span class="indent"> + ServerName www.example1.com<br /> + DocumentRoot /www/domain-80<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <span class="indent"> + ServerName www.example1.com<br /> + DocumentRoot /www/domain-8080<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <span class="indent"> + ServerName www.example2.org<br /> + DocumentRoot /www/otherdomain-80<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <span class="indent"> + ServerName www.example2.org<br /> + DocumentRoot /www/otherdomain-8080<br /> + </span> + </VirtualHost> + </code></p></div> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="ip" id="ip">IP-based virtual hosting</a></h2> + + <p>The server has two IP addresses (<code>172.20.30.40</code> and + <code>172.20.30.50</code>) which resolve to the names + <code>www.example1.com</code> and <code>www.example2.org</code> + respectively.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 80<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <span class="indent"> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>Requests for any address not specified in one of the + <code><VirtualHost></code> directives (such as + <code>localhost</code>, for example) will go to the main server, if + there is one.</p> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="ipport" id="ipport">Mixed port-based and ip-based virtual + hosts</a></h2> + + <p>The server machine has two IP addresses (<code>172.20.30.40</code> and + <code>172.20.30.50</code>) which resolve to the names + <code>www.example1.com</code> and <code>www.example2.org</code> + respectively. In each case, we want to run hosts on ports 80 and + 8080.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 172.20.30.40:80<br /> + Listen 172.20.30.40:8080<br /> + Listen 172.20.30.50:80<br /> + Listen 172.20.30.50:8080<br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <span class="indent"> + DocumentRoot /www/example1-80<br /> + ServerName www.example1.com<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <span class="indent"> + DocumentRoot /www/example1-8080<br /> + ServerName www.example1.com<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50:80><br /> + <span class="indent"> + DocumentRoot /www/example2-80<br /> + ServerName www.example1.org<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50:8080><br /> + <span class="indent"> + DocumentRoot /www/example2-8080<br /> + ServerName www.example2.org<br /> + </span> + </VirtualHost> + </code></p></div> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="mixed" id="mixed">Mixed name-based and IP-based + vhosts</a></h2> + + <p>On some of my addresses, I want to do name-based virtual hosts, and + on others, IP-based hosts.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 80<br /> + <br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/example3<br /> + ServerName www.example3.net<br /> + </span> + </VirtualHost><br /> + <br /> + # IP-based<br /> + <VirtualHost 172.20.30.50><br /> + <span class="indent"> + DocumentRoot /www/example4<br /> + ServerName www.example4.edu<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.60><br /> + <span class="indent"> + DocumentRoot /www/example5<br /> + ServerName www.example5.gov<br /> + </span> + </VirtualHost> + </code></p></div> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="default" id="default">Using <code>_default_</code> + vhosts</a></h2> + + <h3><a name="defaultallports" id="defaultallports"><code>_default_</code> vhosts + for all ports</a></h3> + + <p>Catching <em>every</em> request to any unspecified IP address and + port, <em>i.e.</em>, an address/port combination that is not used for + any other virtual host.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + <VirtualHost _default_:*><br /> + <span class="indent"> + DocumentRoot /www/default<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>Using such a default vhost with a wildcard port effectively prevents + any request going to the main server.</p> + + <p>A default vhost never serves a request that was sent to an + address/port that is used for name-based vhosts. If the request + contained an unknown or no <code>Host:</code> header it is always + served from the primary name-based vhost (the vhost for that + address/port appearing first in the configuration file).</p> + + <p>You can use <code class="directive"><a href="../mod/mod_alias.html#aliasmatch">AliasMatch</a></code> or + <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to rewrite any + request to a single information page (or script).</p> + + + <h3><a name="defaultdifferentports" id="defaultdifferentports"><code>_default_</code> vhosts + for different ports</a></h3> + + <p>Same as setup 1, but the server listens on several ports and we want + to use a second <code>_default_</code> vhost for port 80.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + <VirtualHost _default_:80><br /> + <span class="indent"> + DocumentRoot /www/default80<br /> + # ...<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost _default_:*><br /> + <span class="indent"> + DocumentRoot /www/default<br /> + # ...<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>The default vhost for port 80 (which <em>must</em> appear before any + default vhost with a wildcard port) catches all requests that were sent + to an unspecified IP address. The main server is never used to serve a + request.</p> + + + <h3><a name="defaultoneport" id="defaultoneport"><code>_default_</code> vhosts + for one port</a></h3> + + <p>We want to have a default vhost for port 80, but no other default + vhosts.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + <VirtualHost _default_:80><br /> + DocumentRoot /www/default<br /> + ...<br /> + </VirtualHost> + </code></p></div> + + <p>A request to an unspecified address on port 80 is served from the + default vhost any other request to an unspecified address and port is + served from the main server.</p> + + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="migrate" id="migrate">Migrating a name-based vhost to an + IP-based vhost</a></h2> + + <p>The name-based vhost with the hostname + <code>www.example2.org</code> (from our <a href="#name">name-based</a> example, setup 2) should get its own IP + address. To avoid problems with name servers or proxies who cached the + old IP address for the name-based vhost we want to provide both + variants during a migration phase.<br /> + The solution is easy, because we can simply add the new IP address + (<code>172.20.30.50</code>) to the <code>VirtualHost</code> + directive.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + Listen 80<br /> + ServerName www.example1.com<br /> + DocumentRoot /www/example1<br /> + <br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40 172.20.30.50><br /> + <span class="indent"> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + # ...<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/example3<br /> + ServerName www.example3.net<br /> + ServerAlias *.example3.net<br /> + # ...<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>The vhost can now be accessed through the new address (as an + IP-based vhost) and through the old address (as a name-based + vhost).</p> + + </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="serverpath" id="serverpath">Using the <code>ServerPath</code> + directive</a></h2> + + <p>We have a server with two name-based vhosts. In order to match the + correct virtual host a client must send the correct <code>Host:</code> + header. Old HTTP/1.0 clients do not send such a header and Apache has + no clue what vhost the client tried to reach (and serves the request + from the primary vhost). To provide as much backward compatibility as + possible we create a primary vhost which returns a single page + containing links with an URL prefix to the name-based virtual + hosts.</p> + + <div class="example"><h3>Server configuration</h3><p><code> + + + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + # primary vhost<br /> + DocumentRoot /www/subdomain<br /> + RewriteEngine On<br /> + RewriteRule ^/.* /www/subdomain/index.html<br /> + # ...<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + DocumentRoot /www/subdomain/sub1<br /> + <span class="indent"> + ServerName www.sub1.domain.tld<br /> + ServerPath /sub1/<br /> + RewriteEngine On<br /> + RewriteRule ^(/sub1/.*) /www/subdomain$1<br /> + # ...<br /> + </span> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <span class="indent"> + DocumentRoot /www/subdomain/sub2<br /> + ServerName www.sub2.domain.tld<br /> + ServerPath /sub2/<br /> + RewriteEngine On<br /> + RewriteRule ^(/sub2/.*) /www/subdomain$1<br /> + # ...<br /> + </span> + </VirtualHost> + </code></p></div> + + <p>Due to the <code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code> + directive a request to the URL + <code>http://www.sub1.domain.tld/sub1/</code> is <em>always</em> served + from the sub1-vhost.<br /> A request to the URL + <code>http://www.sub1.domain.tld/</code> is only + served from the sub1-vhost if the client sent a correct + <code>Host:</code> header. If no <code>Host:</code> header is sent the + client gets the information page from the primary host.<br /> + Please note that there is one oddity: A request to + <code>http://www.sub2.domain.tld/sub1/</code> is also served from the + sub1-vhost if the client sent no <code>Host:</code> header.<br /> + The <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives + are used to make sure that a client which sent a correct + <code>Host:</code> header can use both URL variants, <em>i.e.</em>, + with or without URL prefix.</p> + + </div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/examples.xml b/docs/manual/vhosts/examples.xml new file mode 100644 index 0000000000..f4a19da5f5 --- /dev/null +++ b/docs/manual/vhosts/examples.xml @@ -0,0 +1,592 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>VirtualHost Examples</title> + +<summary> + + <p>This document attempts to answer the commonly-asked questions about + setting up virtual hosts. These scenarios are those involving multiple + web sites running on a single server, via <a + href="name-based.html">name-based</a> or <a + href="ip-based.html">IP-based</a> virtual hosts. A document should be + coming soon about running sites on several servers behind a single + proxy server.</p> + +</summary> + + <section id="purename"><title>Running several name-based web + sites on a single IP address.</title> + + <p>Your server has a single IP address, and multiple aliases (CNAMES) + point to this machine in DNS. You want to run a web server for + <code>www.example1.com</code> and <code>www.example2.org</code> on this + machine.</p> + + <note><title>Note</title><p>Creating virtual + host configurations on your Apache server does not magically + cause DNS entries to be created for those host names. You + <em>must</em> have the names in DNS, resolving to your IP + address, or nobody else will be able to see your web site. You + can put entries in your <code>hosts</code> file for local + testing, but that will work only from the machine with those + hosts entries.</p> + </note> + + <example> + <title>Server configuration</title> + + # Ensure that Apache listens on port 80<br /> + Listen 80<br /> + <br /> + # Listen for virtual host requests on all IP addresses<br /> + NameVirtualHost *<br /> + <br /> + <VirtualHost *><br /> + <indent> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + <br /> + # Other directives here<br /> + <br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost *><br /> + <indent> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + <br /> + # Other directives here<br /> + <br /> + </indent> + </VirtualHost> + </example> + + <p>The asterisks match all addresses, so the main server serves no + requests. Due to the fact that <code>www.example1.com</code> is first + in the configuration file, it has the highest priority and can be seen + as the <cite>default</cite> or <cite>primary</cite> server. That means + that if a request is received that does not match one of the specified + <code>ServerName</code> directives, it will be served by this first + <code>VirtualHost</code>.</p> + + <note> + <title>Note</title> + + <p>You can, if you wish, replace <code>*</code> with the actual + IP address of the system. In that case, the argument to + <code>VirtualHost</code> <em>must</em> match the argument to + <code>NameVirtualHost</code>:</p> + + <example> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + # etc ... + </example> + + <p>However, it is additionally useful to use <code>*</code> + on systems where the IP address is not predictable - for + example if you have a dynamic IP address with your ISP, and + you are using some variety of dynamic DNS solution. Since + <code>*</code> matches any IP address, this configuration + would work without changes whenever your IP address + changes.</p> + </note> + + <p>The above configuration is what you will want to use in almost + all name-based virtual hosting situations. The only think that this + configuration will not work for, in fact, is when you are serving + different content based on differing IP addresses or ports.</p> + + </section> + + <section id="twoips"><title>Name-based hosts on more than one + IP address.</title> + + <note> + <title>Note</title><p>Any of the + techniques discussed here can be extended to any number of IP + addresses.</p> + </note> + + <p>The server has two IP addresses. On one (<code>172.20.30.40</code>), we + will serve the "main" server, <code>server.domain.com</code> and on the + other (<code>172.20.30.50</code>), we will serve two or more virtual hosts.</p> + + <example> + <title>Server configuration</title> + + Listen 80<br /> + <br /> + # This is the "main" server running on 172.20.30.40<br /> + ServerName server.domain.com<br /> + DocumentRoot /www/mainserver<br /> + <br /> + # This is the other address<br /> + NameVirtualHost 172.20.30.50<br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <indent> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + <br /> + # Other directives here ...<br /> + <br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <indent> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + <br /> + # Other directives here ...<br /> + <br /> + </indent> + </VirtualHost> + </example> + + <p>Any request to an address other than <code>172.20.30.50</code> will be + served from the main server. A request to <code>172.20.30.50</code> with an + unknown hostname, or no <code>Host:</code> header, will be served from + <code>www.example1.com</code>.</p> + + </section> + + <section id="intraextra"><title>Serving the same content on + different IP addresses (such as an internal and external + address).</title> + + <p>The server machine has two IP addresses (<code>192.168.1.1</code> + and <code>172.20.30.40</code>). The machine is sitting between an + internal (intranet) network and an external (internet) network. Outside + of the network, the name <code>server.example.com</code> resolves to + the external address (<code>172.20.30.40</code>), but inside the + network, that same name resolves to the internal address + (<code>192.168.1.1</code>).</p> + + <p>The server can be made to respond to internal and external requests + with the same content, with just one <code>VirtualHost</code> + section.</p> + + <example> + <title>Server configuration</title> + + NameVirtualHost 192.168.1.1<br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 192.168.1.1 172.20.30.40><br /> + <indent> + DocumentRoot /www/server1<br /> + ServerName server.example.com<br /> + ServerAlias server<br /> + </indent> + </VirtualHost> + </example> + + <p>Now requests from both networks will be served from the same + <code>VirtualHost</code>.</p> + + <note> + <title>Note:</title><p>On the internal + network, one can just use the name <code>server</code> rather + than the fully qualified host name + <code>server.example.com</code>.</p> + + <p>Note also that, in the above example, you can replace the list + of IP addresses with <code>*</code>, which will cause the server to + respond the same on all addresses.</p> + </note> + + </section> + + <section id="port"><title>Running different sites on different + ports.</title> + + <p>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.</p> + + <example> + <title>Server configuration</title> + + Listen 80<br /> + Listen 8080<br /> + <br /> + NameVirtualHost 172.20.30.40:80<br /> + NameVirtualHost 172.20.30.40:8080<br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <indent> + ServerName www.example1.com<br /> + DocumentRoot /www/domain-80<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <indent> + ServerName www.example1.com<br /> + DocumentRoot /www/domain-8080<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <indent> + ServerName www.example2.org<br /> + DocumentRoot /www/otherdomain-80<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <indent> + ServerName www.example2.org<br /> + DocumentRoot /www/otherdomain-8080<br /> + </indent> + </VirtualHost> + </example> + + </section> + + <section id="ip"><title>IP-based virtual hosting</title> + + <p>The server has two IP addresses (<code>172.20.30.40</code> and + <code>172.20.30.50</code>) which resolve to the names + <code>www.example1.com</code> and <code>www.example2.org</code> + respectively.</p> + + <example> + <title>Server configuration</title> + + Listen 80<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50><br /> + <indent> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + </indent> + </VirtualHost> + </example> + + <p>Requests for any address not specified in one of the + <code><VirtualHost></code> directives (such as + <code>localhost</code>, for example) will go to the main server, if + there is one.</p> + + </section> + + <section id="ipport"><title>Mixed port-based and ip-based virtual + hosts</title> + + <p>The server machine has two IP addresses (<code>172.20.30.40</code> and + <code>172.20.30.50</code>) which resolve to the names + <code>www.example1.com</code> and <code>www.example2.org</code> + respectively. In each case, we want to run hosts on ports 80 and + 8080.</p> + + <example> + <title>Server configuration</title> + + Listen 172.20.30.40:80<br /> + Listen 172.20.30.40:8080<br /> + Listen 172.20.30.50:80<br /> + Listen 172.20.30.50:8080<br /> + <br /> + <VirtualHost 172.20.30.40:80><br /> + <indent> + DocumentRoot /www/example1-80<br /> + ServerName www.example1.com<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40:8080><br /> + <indent> + DocumentRoot /www/example1-8080<br /> + ServerName www.example1.com<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50:80><br /> + <indent> + DocumentRoot /www/example2-80<br /> + ServerName www.example1.org<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.50:8080><br /> + <indent> + DocumentRoot /www/example2-8080<br /> + ServerName www.example2.org<br /> + </indent> + </VirtualHost> + </example> + + </section> + + <section id="mixed"><title>Mixed name-based and IP-based + vhosts</title> + + <p>On some of my addresses, I want to do name-based virtual hosts, and + on others, IP-based hosts.</p> + + <example> + <title>Server configuration</title> + + Listen 80<br /> + <br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/example1<br /> + ServerName www.example1.com<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/example3<br /> + ServerName www.example3.net<br /> + </indent> + </VirtualHost><br /> + <br /> + # IP-based<br /> + <VirtualHost 172.20.30.50><br /> + <indent> + DocumentRoot /www/example4<br /> + ServerName www.example4.edu<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.60><br /> + <indent> + DocumentRoot /www/example5<br /> + ServerName www.example5.gov<br /> + </indent> + </VirtualHost> + </example> + + </section> + + <section id="default"><title>Using <code>_default_</code> + vhosts</title> + + <section id="defaultallports"><title><code>_default_</code> vhosts + for all ports</title> + + <p>Catching <em>every</em> request to any unspecified IP address and + port, <em>i.e.</em>, an address/port combination that is not used for + any other virtual host.</p> + + <example> + <title>Server configuration</title> + + <VirtualHost _default_:*><br /> + <indent> + DocumentRoot /www/default<br /> + </indent> + </VirtualHost> + </example> + + <p>Using such a default vhost with a wildcard port effectively prevents + any request going to the main server.</p> + + <p>A default vhost never serves a request that was sent to an + address/port that is used for name-based vhosts. If the request + contained an unknown or no <code>Host:</code> header it is always + served from the primary name-based vhost (the vhost for that + address/port appearing first in the configuration file).</p> + + <p>You can use <directive module="mod_alias">AliasMatch</directive> or + <directive module="mod_rewrite">RewriteRule</directive> to rewrite any + request to a single information page (or script).</p> + </section> + + <section id="defaultdifferentports"><title><code>_default_</code> vhosts + for different ports</title> + + <p>Same as setup 1, but the server listens on several ports and we want + to use a second <code>_default_</code> vhost for port 80.</p> + + <example> + <title>Server configuration</title> + + <VirtualHost _default_:80><br /> + <indent> + DocumentRoot /www/default80<br /> + # ...<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost _default_:*><br /> + <indent> + DocumentRoot /www/default<br /> + # ...<br /> + </indent> + </VirtualHost> + </example> + + <p>The default vhost for port 80 (which <em>must</em> appear before any + default vhost with a wildcard port) catches all requests that were sent + to an unspecified IP address. The main server is never used to serve a + request.</p> + </section> + + <section id="defaultoneport"><title><code>_default_</code> vhosts + for one port</title> + + <p>We want to have a default vhost for port 80, but no other default + vhosts.</p> + + <example> + <title>Server configuration</title> + + <VirtualHost _default_:80><br /> + DocumentRoot /www/default<br /> + ...<br /> + </VirtualHost> + </example> + + <p>A request to an unspecified address on port 80 is served from the + default vhost any other request to an unspecified address and port is + served from the main server.</p> + </section> + + </section> + + <section id="migrate"><title>Migrating a name-based vhost to an + IP-based vhost</title> + + <p>The name-based vhost with the hostname + <code>www.example2.org</code> (from our <a + href="#name">name-based</a> example, setup 2) should get its own IP + address. To avoid problems with name servers or proxies who cached the + old IP address for the name-based vhost we want to provide both + variants during a migration phase.<br /> + The solution is easy, because we can simply add the new IP address + (<code>172.20.30.50</code>) to the <code>VirtualHost</code> + directive.</p> + + <example> + <title>Server configuration</title> + + Listen 80<br /> + ServerName www.example1.com<br /> + DocumentRoot /www/example1<br /> + <br /> + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40 172.20.30.50><br /> + <indent> + DocumentRoot /www/example2<br /> + ServerName www.example2.org<br /> + # ...<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/example3<br /> + ServerName www.example3.net<br /> + ServerAlias *.example3.net<br /> + # ...<br /> + </indent> + </VirtualHost> + </example> + + <p>The vhost can now be accessed through the new address (as an + IP-based vhost) and through the old address (as a name-based + vhost).</p> + + </section> + + <section id="serverpath"><title>Using the <code>ServerPath</code> + directive</title> + + <p>We have a server with two name-based vhosts. In order to match the + correct virtual host a client must send the correct <code>Host:</code> + header. Old HTTP/1.0 clients do not send such a header and Apache has + no clue what vhost the client tried to reach (and serves the request + from the primary vhost). To provide as much backward compatibility as + possible we create a primary vhost which returns a single page + containing links with an URL prefix to the name-based virtual + hosts.</p> + + <example> + <title>Server configuration</title> + + NameVirtualHost 172.20.30.40<br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + # primary vhost<br /> + DocumentRoot /www/subdomain<br /> + RewriteEngine On<br /> + RewriteRule ^/.* /www/subdomain/index.html<br /> + # ...<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + DocumentRoot /www/subdomain/sub1<br /> + <indent> + ServerName www.sub1.domain.tld<br /> + ServerPath /sub1/<br /> + RewriteEngine On<br /> + RewriteRule ^(/sub1/.*) /www/subdomain$1<br /> + # ...<br /> + </indent> + </VirtualHost><br /> + <br /> + <VirtualHost 172.20.30.40><br /> + <indent> + DocumentRoot /www/subdomain/sub2<br /> + ServerName www.sub2.domain.tld<br /> + ServerPath /sub2/<br /> + RewriteEngine On<br /> + RewriteRule ^(/sub2/.*) /www/subdomain$1<br /> + # ...<br /> + </indent> + </VirtualHost> + </example> + + <p>Due to the <directive module="core">ServerPath</directive> + directive a request to the URL + <code>http://www.sub1.domain.tld/sub1/</code> is <em>always</em> served + from the sub1-vhost.<br /> A request to the URL + <code>http://www.sub1.domain.tld/</code> is only + served from the sub1-vhost if the client sent a correct + <code>Host:</code> header. If no <code>Host:</code> header is sent the + client gets the information page from the primary host.<br /> + Please note that there is one oddity: A request to + <code>http://www.sub2.domain.tld/sub1/</code> is also served from the + sub1-vhost if the client sent no <code>Host:</code> header.<br /> + The <directive module="mod_rewrite">RewriteRule</directive> directives + are used to make sure that a client which sent a correct + <code>Host:</code> header can use both URL variants, <em>i.e.</em>, + with or without URL prefix.</p> + + </section> + +</manualpage> diff --git a/docs/manual/vhosts/fd-limits.html.en b/docs/manual/vhosts/fd-limits.html.en index c53aca9aac..5ab3435c9c 100644 --- a/docs/manual/vhosts/fd-limits.html.en +++ b/docs/manual/vhosts/fd-limits.html.en @@ -1,19 +1,10 @@ -<!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> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Apache Server Virtual Host Support</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">File Descriptor Limits</h1> +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>File Descriptor Limits - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>File Descriptor Limits</h1> <p>When using a large number of Virtual Hosts, Apache may run out of available file descriptors (sometimes called <cite>file @@ -32,46 +23,43 @@ <li>Your system does not provide the <code>setrlimit()</code> system call.</li> - <li>The <code>setrlimit(RLIMIT_NOFILE)</code> call does not + <li>The <code>setrlimit(RLIMIT_NOFILE)</code> call does not function on your system (such as Solaris 2.3)</li> <li>The number of file descriptors required exceeds the hard limit.</li> - + <li>Your system imposes other limits on file descriptors, such as a limit on stdio streams only using file descriptors below 256. (Solaris 2)</li> </ol> - In the event of problems you can: + In the event of problems you can: <ul> <li>Reduce the number of log files; don't specify log files - in the <code><a - href="../mod/core.html#virtualhost"><VirtualHost></a></code> - sections, but only log to the main log files. (See <a - href="#splitlogs">Splitting up your log files</a>, below, for more + in the <code class="directive"><a href="../mod/core.html#<virtualhost>"><VirtualHost></a></code> + sections, but only log to the main log files. (See <a href="#splitlogs">Splitting up your log files</a>, below, for more information on doing this.)</li> <li> If you system falls into 1 or 2 (above), then increase the file descriptor limit before starting Apache, using a - script like + script like - <blockquote> + <div class="example"><p><code> <code>#!/bin/sh<br /> ulimit -S -n 100<br /> exec httpd</code> - </blockquote> + </code></p></div> </li> </ul> - <p>Please see the <a - href="../misc/descriptors.html">Descriptors and Apache</a> + <p>Please see the <a href="../misc/descriptors.html">Descriptors and Apache</a> document containing further details about file descriptor problems and how they can be solved on your operating system.</p> -<h2><a name="splitlogs">Splitting up your log files</a></h2> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="splitlogs" id="splitlogs">Splitting up your log files</a></h2> <p>If you want to log multiple virtual hosts to the same log file, you may want to split up the log files afterwards in order to run @@ -79,40 +67,35 @@ statistical analysis of the various virtual hosts. This can be accomplished in the following manner.</p> <p>First, you will need to add the virtual host information to the log -entries. This can be done using the <code><a -href="../mod/mod_log_config.html#logformat">LogFormat</a></code> +entries. This can be done using the <code class="directive"><a href="../mod/mod_log_config.html# logformat"> +LogFormat</a></code> directive, and the <code>%v</code> variable. Add this to the beginning of your log format string:</p> -<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code> - LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost<br /> - CustomLog logs/multiple_vhost_log vhost -</code></td></tr></table></blockquote> +<div class="example"><p><code> +LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost<br /> +CustomLog logs/multiple_vhost_log vhost +</code></p></div> <p>This will create a log file in the common log format, but with the canonical virtual host (whatever appears in the -<a href="../mod/core.html#servername">ServerName</a> directive) prepended to -each line. (See <a -href="../mod/mod_log_config.html#formats">Custom Log Formats</a> for +<code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive) prepended to +each line. (See <code class="directive"><a href="../mod/mod_log_config.html#custom log formats">Custom Log Formats</a></code> for more about customizing your log files.)</p> <p>When you wish to split your log file into its component parts (one -file per virtual host) you can use the program <code><a -href="../programs/other.html">split-logfile</a></code> to accomplish +file per virtual host) you can use the program <code><a href="../programs/other.html">split-logfile</a></code> to accomplish this. You'll find this program in the <code>support</code> directory of the Apache disribution.</p> <p>Run this program with the command:</p> -<blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"> -<code>split-logfile < /logs/multiple_vhost_log</code> -</td></tr></table></blockquote> +<div class="example"><p><code> +split-logfile < /logs/multiple_vhost_log +</code></p></div> <p>This program, when run with the name of your vhost log file, will generate one file for each virtual host that appears in your log file. Each file will be called <code>hostname.log</code>.</p> - <!--#include virtual="footer.html" --> - </body> -</html> - +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/fd-limits.xml b/docs/manual/vhosts/fd-limits.xml new file mode 100644 index 0000000000..249f04fe5c --- /dev/null +++ b/docs/manual/vhosts/fd-limits.xml @@ -0,0 +1,112 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>File Descriptor Limits</title> + +<summary> + + <p>When using a large number of Virtual Hosts, Apache may run + out of available file descriptors (sometimes called <cite>file + handles</cite>) if each Virtual Host specifies different log + files. The total number of file descriptors used by Apache is + one for each distinct error log file, one for every other log + file directive, plus 10-20 for internal use. Unix operating + systems limit the number of file descriptors that may be used + by a process; the limit is typically 64, and may usually be + increased up to a large hard-limit.</p> + + <p>Although Apache attempts to increase the limit as required, + this may not work if:</p> + + <ol> + <li>Your system does not provide the <code>setrlimit()</code> + system call.</li> + + <li>The <code>setrlimit(RLIMIT_NOFILE)</code> call does not + function on your system (such as Solaris 2.3)</li> + + <li>The number of file descriptors required exceeds the hard + limit.</li> + + <li>Your system imposes other limits on file descriptors, + such as a limit on stdio streams only using file descriptors + below 256. (Solaris 2)</li> + </ol> + In the event of problems you can: + + <ul> + <li>Reduce the number of log files; don't specify log files + in the <directive module="core"><VirtualHost></directive> + sections, but only log to the main log files. (See <a + href="#splitlogs">Splitting up your log files</a>, below, for more + information on doing this.)</li> + + <li> + If you system falls into 1 or 2 (above), then increase the + file descriptor limit before starting Apache, using a + script like + + <example> + <code>#!/bin/sh<br /> + ulimit -S -n 100<br /> + exec httpd</code> + </example> + </li> + </ul> + + <p>Please see the <a + href="../misc/descriptors.html">Descriptors and Apache</a> + document containing further details about file descriptor + problems and how they can be solved on your operating + system.</p> + +</summary> + +<section id="splitlogs"><title>Splitting up your log files</title> + +<p>If you want to log multiple virtual hosts to the same log file, you +may want to split up the log files afterwards in order to run +statistical analysis of the various virtual hosts. This can be +accomplished in the following manner.</p> + +<p>First, you will need to add the virtual host information to the log +entries. This can be done using the <directive module="mod_log_config"> +LogFormat</directive> +directive, and the <code>%v</code> variable. Add this to the beginning +of your log format string:</p> + +<example> +LogFormat "%v %h %l %u %t \"%r\" %>s %b" vhost<br /> +CustomLog logs/multiple_vhost_log vhost +</example> + +<p>This will create a log file in the common log format, but with the +canonical virtual host (whatever appears in the +<directive module="core">ServerName</directive> directive) prepended to +each line. (See <directive +module="mod_log_config">Custom Log Formats</directive> for +more about customizing your log files.)</p> + +<p>When you wish to split your log file into its component parts (one +file per virtual host) you can use the program <code><a +href="../programs/other.html">split-logfile</a></code> to accomplish +this. You'll find this program in the <code>support</code> directory +of the Apache disribution.</p> + +<p>Run this program with the command:</p> + +<example> +split-logfile < /logs/multiple_vhost_log +</example> + +<p>This program, when run with the name of your vhost log file, will +generate one file for each virtual host that appears in your log file. +Each file will be called <code>hostname.log</code>.</p> + +</section> +</manualpage> + diff --git a/docs/manual/vhosts/index.html.en b/docs/manual/vhosts/index.html.en index 5d869dcda3..cd432e1f7d 100644 --- a/docs/manual/vhosts/index.html.en +++ b/docs/manual/vhosts/index.html.en @@ -1,27 +1,16 @@ -<!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> - <meta name="generator" content="HTML Tidy, see www.w3.org" /> - - <title>Apache Virtual Host documentation</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">Apache Virtual Host documentation</h1> +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Apache Virtual Host documentation - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Apache Virtual Host documentation</h1> <p>The term <cite>Virtual Host</cite> refers to the practice of running more than one web site (such as - <samp>www.company1.com</samp> and <samp>www.company2.com</samp>) - on a single machine. Virtual hosts can be "<a - href="ip-based.html">IP-based</a>," meaning that you have a - different IP address for every web site, or "<a - href="name-based.html">name-based</a>," meaning that you have + <code>www.company1.com</code> and <code>www.company2.com</code>) + on a single machine. Virtual hosts can be "<a href="ip-based.html">IP-based</a>," meaning that you have a + different IP address for every web site, or "<a href="name-based.html">name-based</a>," meaning that you have multiple names running on a single IP address. The fact that they are running on the same server is not apparent to the end user.</p> @@ -34,64 +23,47 @@ <p>Below is a list of documentation pages which explain all details of virtual host support in Apache version 1.3 and later.</p> - <hr /> - <h2>Virtual Host Support</h2> +</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#support">Virtual Host Support</a></li><li><img alt="" src="../images/down.gif" /> <a href="#directives">Configuration directives</a></li></ul><h3>See also</h3><ul class="seealso"><li> + <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> +</li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="support" id="support">Virtual Host Support</a></h2> <ul> <li><a href="name-based.html">Name-based Virtual Hosts</a> (One IP address, multiple web sites)</li> - <li><a href="ip-based.html">IP-based Virtual Hosts</a> (An IP address for each web site)</li> - - <li><a href="examples.html">Virtual Host examples for common + <li><a href="examples.html">Virtual Host examples for common setups</a></li> - <li><a href="fd-limits.html">File Descriptor Limits</a> (or, <em>Too many log files</em>)</li> - <li><a href="mass.html">Dynamically Configured Mass Virtual Hosting</a></li> - - <li><a href="details.html">In-Depth Discussion of Virtual Host + <li><a href="details.html">In-Depth Discussion of Virtual Host Matching</a></li> </ul> - <h2>Configuration directives</h2> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="directives" id="directives">Configuration directives</a></h2> <ul> - <li><a - href="../mod/core.html#virtualhost"><VirtualHost></a></li> - - <li><a - href="../mod/core.html#namevirtualhost">NameVirtualHost</a></li> - - <li><a href="../mod/core.html#servername">ServerName</a></li> - - <li><a href="../mod/core.html#serveralias">ServerAlias</a></li> - - <li><a href="../mod/core.html#serverpath">ServerPath</a></li> - - <li><b>See also</b> <a - href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></li> + <li><code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code></li> + <li><code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code></li> + <li><code class="directive"><a href="../mod/core.html#servername">ServerName</a></code></li> + <li><code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code></li> + <li><code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code></li> </ul> <p>If you are trying to debug your virtual host configuration, you - may find the Apache <code>-t -D DUMP_VHOSTS</code> command line switch + may find the Apache <code>-t -D DUMP_VHOSTS</code> command line switch useful. That is, type the following command:</p> - <blockquote><table cellpadding="10"><tr><td bgcolor="#eeeeee"><code> + <div class="example"><p><code> /usr/local/apache/bin/httpd -t -D DUMP_VHOSTS - </code></td></tr></table></blockquote> - + </code></p></div> + <p>This command will dump out a description of how Apache parsed the configuration file. Careful examination of the IP addresses and - server names may help uncover configuration mistakes. (See <a - href="../programs/httpd.html">the docs for the httpd program</a> for + server names may help uncover configuration mistakes. (See <a href="../programs/httpd.html">the docs for the httpd program</a> for other command line options)</p> - <!--#include virtual="footer.html" --> - </body> -</html> - +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/index.xml b/docs/manual/vhosts/index.xml new file mode 100644 index 0000000000..223aae4875 --- /dev/null +++ b/docs/manual/vhosts/index.xml @@ -0,0 +1,83 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>Apache Virtual Host documentation</title> + +<summary> + + <p>The term <cite>Virtual Host</cite> refers to the practice of + running more than one web site (such as + <code>www.company1.com</code> and <code>www.company2.com</code>) + on a single machine. Virtual hosts can be "<a + href="ip-based.html">IP-based</a>," meaning that you have a + different IP address for every web site, or "<a + href="name-based.html">name-based</a>," meaning that you have + multiple names running on a single IP address. The fact that they + are running on the same server is not apparent to the end user.</p> + + <p>Apache was one of the first servers to support IP-based + virtual hosts right out of the box. Versions 1.1 and later of + Apache support both IP-based and name-based virtual hosts + (vhosts). The latter variant of virtual hosts is sometimes also + called <em>host-based</em> or <em>non-IP virtual hosts</em>.</p> + + <p>Below is a list of documentation pages which explain all + details of virtual host support in Apache version 1.3 and + later.</p> + +</summary> + +<seealso> + <module>mod_vhost_alias</module> +</seealso> + +<section id="support"><title>Virtual Host Support</title> + + <ul> + <li><a href="name-based.html">Name-based Virtual Hosts</a> (One IP + address, multiple web sites)</li> + <li><a href="ip-based.html">IP-based Virtual Hosts</a> (An IP + address for each web site)</li> + <li><a href="examples.html">Virtual Host examples for common + setups</a></li> + <li><a href="fd-limits.html">File Descriptor Limits</a> (or, + <em>Too many log files</em>)</li> + <li><a href="mass.html">Dynamically Configured Mass Virtual + Hosting</a></li> + <li><a href="details.html">In-Depth Discussion of Virtual Host + Matching</a></li> + </ul> + +</section> + +<section id="directives"><title>Configuration directives</title> + + <ul> + <li><directive type="section" + module="core">VirtualHost</directive></li> + <li><directive module="core">NameVirtualHost</directive></li> + <li><directive module="core">ServerName</directive></li> + <li><directive module="core">ServerAlias</directive></li> + <li><directive module="core">ServerPath</directive></li> + </ul> + + <p>If you are trying to debug your virtual host configuration, you + may find the Apache <code>-t -D DUMP_VHOSTS</code> command line switch + useful. That is, type the following command:</p> + + <example> + /usr/local/apache/bin/httpd -t -D DUMP_VHOSTS + </example> + + <p>This command will dump out a description of how Apache parsed + the configuration file. Careful examination of the IP addresses and + server names may help uncover configuration mistakes. (See <a + href="../programs/httpd.html">the docs for the httpd program</a> for + other command line options)</p> + +</section> +</manualpage>
\ No newline at end of file diff --git a/docs/manual/vhosts/ip-based.html.en b/docs/manual/vhosts/ip-based.html.en new file mode 100644 index 0000000000..c743967ed2 --- /dev/null +++ b/docs/manual/vhosts/ip-based.html.en @@ -0,0 +1,119 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Apache IP-based Virtual Host Support - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Apache IP-based Virtual Host Support</h1></div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#requirements">System requirements</a></li><li><img alt="" src="../images/down.gif" /> <a href="#howto">How to set up Apache</a></li><li><img alt="" src="../images/down.gif" /> <a href="#multiple">Setting up multiple daemons</a></li><li><img alt="" src="../images/down.gif" /> <a href="#single">Setting up a single daemon + with virtual hosts</a></li></ul><h3>See also</h3><ul class="seealso"><li> +<a href="name-based.html">Name-based Virtual Hosts Support</a> +</li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="requirements" id="requirements">System requirements</a></h2> + + <p>As the term <cite>IP-based</cite> indicates, the server + <strong>must have a different IP address for each IP-based + virtual host</strong>. This can be achieved by the machine + having several physical network connections, or by use of + virtual interfaces which are supported by most modern operating + systems (see system documentation for details, these are + frequently called "ip aliases", and the "ifconfig" command is + most commonly used to set them up).</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="howto" id="howto">How to set up Apache</a></h2> + + <p>There are two ways of configuring apache to support multiple + hosts. Either by running a separate httpd daemon for each + hostname, or by running a single daemon which supports all the + virtual hosts.</p> + + <p>Use multiple daemons when:</p> + + <ul> + <li>There are security partitioning issues, such as company1 + does not want anyone at company2 to be able to read their + data except via the web. In this case you would need two + daemons, each running with different <code class="directive"><a href="../mod/mpm_common.html#user">User</a></code>, <code class="directive"><a href="../mod/mpm_common.html#group">Group</a></code>, <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code>, and <code class="directive"><a href="../mod/core.html#serverroot">ServerRoot</a></code> settings.</li> + + <li>You can afford the memory and <a href="../misc/descriptors.html">file descriptor + requirements</a> of listening to every IP alias on the + machine. It's only possible to <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code> to the "wildcard" + address, or to specific addresses. So if you have a need to + listen to a specific address for whatever reason, then you + will need to listen to all specific addresses. (Although one + httpd could listen to N-1 of the addresses, and another could + listen to the remaining address.)</li> + </ul> + + <p>Use a single daemon when:</p> + + <ul> + <li>Sharing of the httpd configuration between virtual hosts + is acceptable.</li> + + <li>The machine services a large number of requests, and so + the performance loss in running separate daemons may be + significant.</li> + </ul> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="multiple" id="multiple">Setting up multiple daemons</a></h2> + + <p>Create a separate httpd installation for each virtual host. For + each installation, use the <code class="directive"><a href="../mod/mpm_common.html#listen">Listen</a></code> directive in the + configuration file to select which IP address (or virtual host) + that daemon services. e.g.</p> + +<div class="example"><pre> + Listen www.smallco.com:80 +</pre></div> + + <p>It is recommended that you use an IP address instead of a + hostname (see <a href="../dns-caveats.html">DNS caveats</a>).</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="single" id="single">Setting up a single daemon + with virtual hosts</a></h2> + + <p>For this case, a single httpd will service requests for the + main server and all the virtual hosts. The <code class="directive"><a href="../mod/core.html#virtualhost">VirtualHost</a></code> directive + in the configuration file is used to set the values of <code class="directive"><a href="../mod/core.html#serveradmin">ServerAdmin</a></code>, <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code>, <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>, <code class="directive"><a href="../mod/core.html#errorlog">ErrorLog</a></code> and <code class="directive"><a href="../mod/mod_log_config.html#transferlog">TransferLog</a></code> + or <code class="directive"><a href="../mod/mod_log_config.html#customlog">CustomLog</a></code> + configuration directives to different values for each virtual + host. e.g.</p> + +<div class="example"><pre> + <VirtualHost www.smallco.com> + ServerAdmin webmaster@mail.smallco.com + DocumentRoot /groups/smallco/www + ServerName www.smallco.com + ErrorLog /groups/smallco/logs/error_log + TransferLog /groups/smallco/logs/access_log + </VirtualHost> + + <VirtualHost www.baygroup.org> + ServerAdmin webmaster@mail.baygroup.org + DocumentRoot /groups/baygroup/www + ServerName www.baygroup.org + ErrorLog /groups/baygroup/logs/error_log + TransferLog /groups/baygroup/logs/access_log + </VirtualHost> +</pre></div> + + <p>It is recommended that you use an IP address instead of a + hostname (see <a href="../dns-caveats.html">DNS caveats</a>).</p> + + <p>Almost <strong>any</strong> configuration directive can be + put in the VirtualHost directive, with the exception of + directives that control process creation and a few other + directives. To find out if a directive can be used in the + VirtualHost directive, check the <a href="../mod/directive-dict.html#Context">Context</a> using the + <a href="../mod/directives.html">directive index</a>.</p> + + <p><code class="directive"><a href="../mod/mpm_common.html#user">User</a></code> and <code class="directive"><a href="../mod/mpm_common.html#group">Group</a></code> may be used inside a + VirtualHost directive if the <a href="../suexec.html">suEXEC + wrapper</a> is used.</p> + + <p><em>SECURITY:</em> When specifying where to write log files, + be aware of some security risks which are present if anyone + other than the user that starts Apache has write access to the + directory where they are written. See the <a href="../misc/security_tips.html">security tips</a> document + for details.</p> + +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/ip-based.xml b/docs/manual/vhosts/ip-based.xml new file mode 100644 index 0000000000..a74ceead63 --- /dev/null +++ b/docs/manual/vhosts/ip-based.xml @@ -0,0 +1,150 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>Apache IP-based Virtual Host Support</title> + +<seealso> +<a href="name-based.html">Name-based Virtual Hosts Support</a> +</seealso> + +<section id="requirements"><title>System requirements</title> + + <p>As the term <cite>IP-based</cite> indicates, the server + <strong>must have a different IP address for each IP-based + virtual host</strong>. This can be achieved by the machine + having several physical network connections, or by use of + virtual interfaces which are supported by most modern operating + systems (see system documentation for details, these are + frequently called "ip aliases", and the "ifconfig" command is + most commonly used to set them up).</p> + +</section> + +<section id="howto"><title>How to set up Apache</title> + + <p>There are two ways of configuring apache to support multiple + hosts. Either by running a separate httpd daemon for each + hostname, or by running a single daemon which supports all the + virtual hosts.</p> + + <p>Use multiple daemons when:</p> + + <ul> + <li>There are security partitioning issues, such as company1 + does not want anyone at company2 to be able to read their + data except via the web. In this case you would need two + daemons, each running with different <directive + module="mpm_common">User</directive>, <directive + module="mpm_common">Group</directive>, <directive + module="mpm_common">Listen</directive>, and <directive + module="core">ServerRoot</directive> settings.</li> + + <li>You can afford the memory and <a + href="../misc/descriptors.html">file descriptor + requirements</a> of listening to every IP alias on the + machine. It's only possible to <directive + module="mpm_common">Listen</directive> to the "wildcard" + address, or to specific addresses. So if you have a need to + listen to a specific address for whatever reason, then you + will need to listen to all specific addresses. (Although one + httpd could listen to N-1 of the addresses, and another could + listen to the remaining address.)</li> + </ul> + + <p>Use a single daemon when:</p> + + <ul> + <li>Sharing of the httpd configuration between virtual hosts + is acceptable.</li> + + <li>The machine services a large number of requests, and so + the performance loss in running separate daemons may be + significant.</li> + </ul> + +</section> + +<section id="multiple"><title>Setting up multiple daemons</title> + + <p>Create a separate httpd installation for each virtual host. For + each installation, use the <directive + module="mpm_common">Listen</directive> directive in the + configuration file to select which IP address (or virtual host) + that daemon services. e.g.</p> + +<example> +<pre> + Listen www.smallco.com:80 +</pre> +</example> + + <p>It is recommended that you use an IP address instead of a + hostname (see <a href="../dns-caveats.html">DNS caveats</a>).</p> + +</section> + +<section id="single"><title>Setting up a single daemon + with virtual hosts</title> + + <p>For this case, a single httpd will service requests for the + main server and all the virtual hosts. The <directive + module="core">VirtualHost</directive> directive + in the configuration file is used to set the values of <directive + module="core">ServerAdmin</directive>, <directive + module="core">ServerName</directive>, <directive + module="core">DocumentRoot</directive>, <directive + module="core">ErrorLog</directive> and <directive + module="mod_log_config">TransferLog</directive> + or <directive module="mod_log_config">CustomLog</directive> + configuration directives to different values for each virtual + host. e.g.</p> + +<example> +<pre> + <VirtualHost www.smallco.com> + ServerAdmin webmaster@mail.smallco.com + DocumentRoot /groups/smallco/www + ServerName www.smallco.com + ErrorLog /groups/smallco/logs/error_log + TransferLog /groups/smallco/logs/access_log + </VirtualHost> + + <VirtualHost www.baygroup.org> + ServerAdmin webmaster@mail.baygroup.org + DocumentRoot /groups/baygroup/www + ServerName www.baygroup.org + ErrorLog /groups/baygroup/logs/error_log + TransferLog /groups/baygroup/logs/access_log + </VirtualHost> +</pre> +</example> + + <p>It is recommended that you use an IP address instead of a + hostname (see <a href="../dns-caveats.html">DNS caveats</a>).</p> + + <p>Almost <strong>any</strong> configuration directive can be + put in the VirtualHost directive, with the exception of + directives that control process creation and a few other + directives. To find out if a directive can be used in the + VirtualHost directive, check the <a + href="../mod/directive-dict.html#Context">Context</a> using the + <a href="../mod/directives.html">directive index</a>.</p> + + <p><directive module="mpm_common">User</directive> and <directive + module="mpm_common">Group</directive> may be used inside a + VirtualHost directive if the <a href="../suexec.html">suEXEC + wrapper</a> is used.</p> + + <p><em>SECURITY:</em> When specifying where to write log files, + be aware of some security risks which are present if anyone + other than the user that starts Apache has write access to the + directory where they are written. See the <a + href="../misc/security_tips.html">security tips</a> document + for details.</p> + +</section> +</manualpage> diff --git a/docs/manual/vhosts/mass.html.en b/docs/manual/vhosts/mass.html.en new file mode 100644 index 0000000000..8acd65017c --- /dev/null +++ b/docs/manual/vhosts/mass.html.en @@ -0,0 +1,389 @@ +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Dynamically configured mass virtual hosting - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Dynamically configured mass virtual hosting</h1> + + <p>This document describes how to efficiently serve an + arbitrary number of virtual hosts with Apache 1.3. + </p> + +</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#motivation">Motivation</a></li><li><img alt="" src="../images/down.gif" /> <a href="#overview">Overview</a></li><li><img alt="" src="../images/down.gif" /> <a href="#simple">Simple dynamic virtual hosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#homepages">A virtually hosted homepages system</a></li><li><img alt="" src="../images/down.gif" /> <a href="#combinations">Using more than + one virtual hosting system on the same server</a></li><li><img alt="" src="../images/down.gif" /> <a href="#ipbased">More efficient IP-based virtual hosting</a></li><li><img alt="" src="../images/down.gif" /> <a href="#oldversion">Using older versions of Apache</a></li><li><img alt="" src="../images/down.gif" /> <a href="#simple.rewrite">Simple dynamic + virtual hosts using <code>mod_rewrite</code></a></li><li><img alt="" src="../images/down.gif" /> <a href="#homepages.rewrite">A + homepages system using <code>mod_rewrite</code></a></li><li><img alt="" src="../images/down.gif" /> <a href="#xtra-conf">Using a separate virtual + host configuration file</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="motivation" id="motivation">Motivation</a></h2> + + <p>The techniques described here are of interest if your + <code>httpd.conf</code> contains many + <code><VirtualHost></code> sections that are + substantially the same, for example:</p> + +<div class="example"><p><code> +NameVirtualHost 111.22.33.44<br /> +<VirtualHost 111.22.33.44><br /> +<span class="indent"> + ServerName www.customer-1.com<br /> + DocumentRoot /www/hosts/www.customer-1.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin<br /> +</span> +</VirtualHost><br /> +<VirtualHost 111.22.33.44><br /> +<span class="indent"> + ServerName www.customer-2.com<br /> + DocumentRoot /www/hosts/www.customer-2.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin<br /> +</span> +</VirtualHost><br /> +# blah blah blah<br /> +<VirtualHost 111.22.33.44><br /> +<span class="indent"> + ServerName www.customer-N.com<br /> + DocumentRoot /www/hosts/www.customer-N.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin<br /> +</span> +</VirtualHost> +</code></p></div> + + <p>The basic idea is to replace all of the static + <code><VirtualHost></code> configuration with a mechanism + that works it out dynamically. This has a number of + advantages:</p> + + <ol> + <li>Your configuration file is smaller so Apache starts + faster and uses less memory.</li> + + <li>Adding virtual hosts is simply a matter of creating the + appropriate directories in the filesystem and entries in the + DNS - you don't need to reconfigure or restart Apache.</li> + </ol> + + <p>The main disadvantage is that you cannot have a different + log file for each virtual host; however if you have very many + virtual hosts then doing this is dubious anyway because it eats + file descriptors. It is better to log to a pipe or a fifo and + arrange for the process at the other end to distribute the logs + to the customers (it can also accumulate statistics, etc.).</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="overview" id="overview">Overview</a></h2> + + <p>A virtual host is defined by two pieces of information: its + IP address, and the contents of the <code>Host:</code> header + in the HTTP request. The dynamic mass virtual hosting technique + is based on automatically inserting this information into the + pathname of the file that is used to satisfy the request. This + is done most easily using <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code>, + but if you are using a version of Apache up to 1.3.6 then you + must use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. + Both of these modules are disabled by default; you must enable + one of them when configuring and building Apache if you want to + use this technique.</p> + + <p>A couple of things need to be `faked' to make the dynamic + virtual host look like a normal one. The most important is the + server name which is used by Apache to generate + self-referential URLs, etc. It is configured with the + <code>ServerName</code> directive, and it is available to CGIs + via the <code>SERVER_NAME</code> environment variable. The + actual value used at run time is controlled by the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code> + setting. With <code>UseCanonicalName Off</code> the server name + comes from the contents of the <code>Host:</code> header in the + request. With <code>UseCanonicalName DNS</code> it comes from a + reverse DNS lookup of the virtual host's IP address. The former + setting is used for name-based dynamic virtual hosting, and the + latter is used for IP-based hosting. If Apache cannot work out + the server name because there is no <code>Host:</code> header + or the DNS lookup fails then the value configured with + <code>ServerName</code> is used instead.</p> + + <p>The other thing to `fake' is the document root (configured + with <code>DocumentRoot</code> and available to CGIs via the + <code>DOCUMENT_ROOT</code> environment variable). In a normal + configuration this setting is used by the core module when + mapping URIs to filenames, but when the server is configured to + do dynamic virtual hosting that job is taken over by another + module (either <code>mod_vhost_alias</code> or + <code>mod_rewrite</code>) which has a different way of doing + the mapping. Neither of these modules is responsible for + setting the <code>DOCUMENT_ROOT</code> environment variable so + if any CGIs or SSI documents make use of it they will get a + misleading value.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="simple" id="simple">Simple dynamic virtual hosts</a></h2> + + <p>This extract from <code>httpd.conf</code> implements the + virtual host arrangement outlined in the <a href="#motivation">Motivation</a> section above, but in a + generic fashion using <code>mod_vhost_alias</code>.</p> + +<div class="example"><p><code> +# get the server name from the Host: header<br /> +UseCanonicalName Off<br /> +<br /> +# this log format can be split per-virtual-host based on the first field<br /> +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +# include the server name in the filenames used to satisfy requests<br /> +VirtualDocumentRoot /www/hosts/%0/docs<br /> +VirtualScriptAlias /www/hosts/%0/cgi-bin +</code></p></div> + + <p>This configuration can be changed into an IP-based virtual + hosting solution by just turning <code>UseCanonicalName + Off</code> into <code>UseCanonicalName DNS</code>. The server + name that is inserted into the filename is then derived from + the IP address of the virtual host.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="homepages" id="homepages">A virtually hosted homepages system</a></h2> + + <p>This is an adjustment of the above system tailored for an + ISP's homepages server. Using a slightly more complicated + configuration we can select substrings of the server name to + use in the filename so that e.g. the documents for + <samp>www.user.isp.com</samp> are found in + <code>/home/user/</code>. It uses a single <code>cgi-bin</code> + directory instead of one per virtual host.</p> + +<div class="example"><p><code> +# all the preliminary stuff is the same as above, then<br /> +<br /> +# include part of the server name in the filenames<br /> +VirtualDocumentRoot /www/hosts/%2/docs<br /> +<br /> +# single cgi-bin directory<br /> +ScriptAlias /cgi-bin/ /www/std-cgi/<br /> +</code></p></div> + + <p>There are examples of more complicated + <code>VirtualDocumentRoot</code> settings in the + <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> documentation.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="combinations" id="combinations">Using more than + one virtual hosting system on the same server</a></h2> + + <p>With more complicated setups you can use Apache's normal + <code><VirtualHost></code> directives to control the + scope of the various virtual hosting configurations. For + example, you could have one IP address for homepages customers + and another for commercial customers with the following setup. + This can of course be combined with conventional + <code><VirtualHost></code> configuration sections.</p> + +<div class="example"><p><code> +UseCanonicalName Off<br /> +<br /> +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br /> +<br /> +<Directory /www/commercial><br /> +<span class="indent"> + Options FollowSymLinks<br /> + AllowOverride All<br /> +</span> +</Directory><br /> +<br /> +<Directory /www/homepages><br /> +<span class="indent"> + Options FollowSymLinks<br /> + AllowOverride None<br /> +</span> +</Directory><br /> +<br /> +<VirtualHost 111.22.33.44><br /> +<span class="indent"> + ServerName www.commercial.isp.com<br /> + <br /> + CustomLog logs/access_log.commercial vcommon<br /> + <br /> + VirtualDocumentRoot /www/commercial/%0/docs<br /> + VirtualScriptAlias /www/commercial/%0/cgi-bin<br /> +</span> +</VirtualHost><br /> +<br /> +<VirtualHost 111.22.33.45><br /> +<span class="indent"> + ServerName www.homepages.isp.com<br /> + <br /> + CustomLog logs/access_log.homepages vcommon<br /> + <br /> + VirtualDocumentRoot /www/homepages/%0/docs<br /> + ScriptAlias /cgi-bin/ /www/std-cgi/<br /> +</span> +</VirtualHost> +</code></p></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="ipbased" id="ipbased">More efficient IP-based virtual hosting</a></h2> + + <p>After <a href="#simple">the first example</a> I noted that + it is easy to turn it into an IP-based virtual hosting setup. + Unfortunately that configuration is not very efficient because + it requires a DNS lookup for every request. This can be avoided + by laying out the filesystem according to the IP addresses + themselves rather than the corresponding names and changing the + logging similarly. Apache will then usually not need to work + out the server name and so incur a DNS lookup.</p> + +<div class="example"><p><code> +# get the server name from the reverse DNS of the IP address<br /> +UseCanonicalName DNS<br /> +<br /> +# include the IP address in the logs so they may be split<br /> +LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +# include the IP address in the filenames<br /> +VirtualDocumentRootIP /www/hosts/%0/docs<br /> +VirtualScriptAliasIP /www/hosts/%0/cgi-bin<br /> +</code></p></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="oldversion" id="oldversion">Using older versions of Apache</a></h2> + + <p>The examples above rely on <code>mod_vhost_alias</code> + which appeared after version 1.3.6. If you are using a version + of Apache without <code>mod_vhost_alias</code> then you can + implement this technique with <code>mod_rewrite</code> as + illustrated below, but only for Host:-header-based virtual + hosts.</p> + + <p>In addition there are some things to beware of with logging. + Apache 1.3.6 is the first version to include the + <code>%V</code> log format directive; in versions 1.3.0 - 1.3.3 + the <code>%v</code> option did what <code>%V</code> does; + version 1.3.4 has no equivalent. In all these versions of + Apache the <code>UseCanonicalName</code> directive can appear + in <code>.htaccess</code> files which means that customers can + cause the wrong thing to be logged. Therefore the best thing to + do is use the <code>%{Host}i</code> directive which logs the + <code>Host:</code> header directly; note that this may include + <code>:port</code> on the end which is not the case for + <code>%V</code>.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="simple.rewrite" id="simple.rewrite">Simple dynamic + virtual hosts using <code>mod_rewrite</code></a></h2> + + <p>This extract from <code>httpd.conf</code> does the same + thing as <a href="#simple">the first example</a>. The first + half is very similar to the corresponding part above but with + some changes for backward compatibility and to make the + <code>mod_rewrite</code> part work properly; the second half + configures <code>mod_rewrite</code> to do the actual work.</p> + + <p>There are a couple of especially tricky bits: By default, + <code>mod_rewrite</code> runs before the other URI translation + modules (<code>mod_alias</code> etc.) so if they are used then + <code>mod_rewrite</code> must be configured to accommodate + them. Also, mome magic must be performed to do a + per-dynamic-virtual-host equivalent of + <code>ScriptAlias</code>.</p> + +<div class="example"><p><code> +# get the server name from the Host: header<br /> +UseCanonicalName Off<br /> +<br /> +# splittable logs<br /> +LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +<Directory /www/hosts><br /> +<span class="indent"> + # ExecCGI is needed here because we can't force<br /> + # CGI execution in the way that ScriptAlias does<br /> + Options FollowSymLinks ExecCGI<br /> +</span> +</Directory><br /> +<br /> +# now for the hard bit<br /> +<br /> +RewriteEngine On<br /> +<br /> +# a ServerName derived from a Host: header may be any case at all<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +## deal with normal documents first:<br /> +# allow Alias /icons/ to work - repeat for other aliases<br /> +RewriteCond %{REQUEST_URI} !^/icons/<br /> +# allow CGIs to work<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +# do the magic<br /> +RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br /> +<br /> +## and now deal with CGIs - we have to force a MIME type<br /> +RewriteCond %{REQUEST_URI} ^/cgi-bin/<br /> +RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]<br /> +<br /> +# that's it! +</code></p></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="homepages.rewrite" id="homepages.rewrite">A + homepages system using <code>mod_rewrite</code></a></h2> + + <p>This does the same thing as <a href="#homepages">the second + example</a>.</p> + +<div class="example"><p><code> +RewriteEngine on<br /> +<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +# allow CGIs to work<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +<br /> +# check the hostname is right so that the RewriteRule works<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$<br /> +<br /> +# concatenate the virtual host name onto the start of the URI<br /> +# the [C] means do the next rewrite on the result of this one<br /> +RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]<br /> +<br /> +# now create the real file name<br /> +RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2<br /> +<br /> +# define the global CGI directory<br /> +ScriptAlias /cgi-bin/ /www/std-cgi/ +</code></p></div> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="xtra-conf" id="xtra-conf">Using a separate virtual + host configuration file</a></h2> + + <p>This arrangement uses more advanced <code>mod_rewrite</code> + features to get the translation from virtual host to document + root from a separate configuration file. This provides more + flexibility but requires more complicated configuration.</p> + + <p>The <code>vhost.map</code> file contains something like + this:</p> + +<div class="example"><p><code> +www.customer-1.com /www/customers/1<br /> +www.customer-2.com /www/customers/2<br /> +# ...<br /> +www.customer-N.com /www/customers/N<br /> +</code></p></div> + + <p>The <code>http.conf</code> contains this:</p> + +<div class="example"><p><code> +RewriteEngine on<br /> +<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +# define the map file<br /> +RewriteMap vhost txt:/www/conf/vhost.map<br /> +<br /> +# deal with aliases as above<br /> +RewriteCond %{REQUEST_URI} !^/icons/<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br /> +# this does the file-based remap<br /> +RewriteCond ${vhost:%1} ^(/.*)$<br /> +RewriteRule ^/(.*)$ %1/docs/$1<br /> +<br /> +RewriteCond %{REQUEST_URI} ^/cgi-bin/<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br /> +RewriteCond ${vhost:%1} ^(/.*)$<br /> +RewriteRule ^/(.*)$ %1/cgi-bin/$1 +</code></p></div> + +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/mass.xml b/docs/manual/vhosts/mass.xml new file mode 100644 index 0000000000..e2aaad9761 --- /dev/null +++ b/docs/manual/vhosts/mass.xml @@ -0,0 +1,420 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + + <title>Dynamically configured mass virtual hosting</title> + +<summary> + + <p>This document describes how to efficiently serve an + arbitrary number of virtual hosts with Apache 1.3. <!-- + + Written by Tony Finch (fanf@demon.net) (dot@dotat.at). + + Some examples were derived from Ralf S. Engleschall's document + http://www.engelschall.com/pw/apache/rewriteguide/ + + Some suggestions were made by Brian Behlendorf. + + --> + </p> + +</summary> + +<section id="motivation"><title>Motivation</title> + + <p>The techniques described here are of interest if your + <code>httpd.conf</code> contains many + <code><VirtualHost></code> sections that are + substantially the same, for example:</p> + +<example> +NameVirtualHost 111.22.33.44<br /> +<VirtualHost 111.22.33.44><br /> +<indent> + ServerName www.customer-1.com<br /> + DocumentRoot /www/hosts/www.customer-1.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin<br /> +</indent> +</VirtualHost><br /> +<VirtualHost 111.22.33.44><br /> +<indent> + ServerName www.customer-2.com<br /> + DocumentRoot /www/hosts/www.customer-2.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin<br /> +</indent> +</VirtualHost><br /> +# blah blah blah<br /> +<VirtualHost 111.22.33.44><br /> +<indent> + ServerName www.customer-N.com<br /> + DocumentRoot /www/hosts/www.customer-N.com/docs<br /> + ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin<br /> +</indent> +</VirtualHost> +</example> + + <p>The basic idea is to replace all of the static + <code><VirtualHost></code> configuration with a mechanism + that works it out dynamically. This has a number of + advantages:</p> + + <ol> + <li>Your configuration file is smaller so Apache starts + faster and uses less memory.</li> + + <li>Adding virtual hosts is simply a matter of creating the + appropriate directories in the filesystem and entries in the + DNS - you don't need to reconfigure or restart Apache.</li> + </ol> + + <p>The main disadvantage is that you cannot have a different + log file for each virtual host; however if you have very many + virtual hosts then doing this is dubious anyway because it eats + file descriptors. It is better to log to a pipe or a fifo and + arrange for the process at the other end to distribute the logs + to the customers (it can also accumulate statistics, etc.).</p> + +</section> + +<section id="overview"><title>Overview</title> + + <p>A virtual host is defined by two pieces of information: its + IP address, and the contents of the <code>Host:</code> header + in the HTTP request. The dynamic mass virtual hosting technique + is based on automatically inserting this information into the + pathname of the file that is used to satisfy the request. This + is done most easily using <module>mod_vhost_alias</module>, + but if you are using a version of Apache up to 1.3.6 then you + must use <module>mod_rewrite</module>. + Both of these modules are disabled by default; you must enable + one of them when configuring and building Apache if you want to + use this technique.</p> + + <p>A couple of things need to be `faked' to make the dynamic + virtual host look like a normal one. The most important is the + server name which is used by Apache to generate + self-referential URLs, etc. It is configured with the + <code>ServerName</code> directive, and it is available to CGIs + via the <code>SERVER_NAME</code> environment variable. The + actual value used at run time is controlled by the <directive + module="core">UseCanonicalName</directive> + setting. With <code>UseCanonicalName Off</code> the server name + comes from the contents of the <code>Host:</code> header in the + request. With <code>UseCanonicalName DNS</code> it comes from a + reverse DNS lookup of the virtual host's IP address. The former + setting is used for name-based dynamic virtual hosting, and the + latter is used for IP-based hosting. If Apache cannot work out + the server name because there is no <code>Host:</code> header + or the DNS lookup fails then the value configured with + <code>ServerName</code> is used instead.</p> + + <p>The other thing to `fake' is the document root (configured + with <code>DocumentRoot</code> and available to CGIs via the + <code>DOCUMENT_ROOT</code> environment variable). In a normal + configuration this setting is used by the core module when + mapping URIs to filenames, but when the server is configured to + do dynamic virtual hosting that job is taken over by another + module (either <code>mod_vhost_alias</code> or + <code>mod_rewrite</code>) which has a different way of doing + the mapping. Neither of these modules is responsible for + setting the <code>DOCUMENT_ROOT</code> environment variable so + if any CGIs or SSI documents make use of it they will get a + misleading value.</p> + +</section> + +<section id="simple"><title>Simple dynamic virtual hosts</title> + + <p>This extract from <code>httpd.conf</code> implements the + virtual host arrangement outlined in the <a + href="#motivation">Motivation</a> section above, but in a + generic fashion using <code>mod_vhost_alias</code>.</p> + +<example> +# get the server name from the Host: header<br /> +UseCanonicalName Off<br /> +<br /> +# this log format can be split per-virtual-host based on the first field<br /> +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +# include the server name in the filenames used to satisfy requests<br /> +VirtualDocumentRoot /www/hosts/%0/docs<br /> +VirtualScriptAlias /www/hosts/%0/cgi-bin +</example> + + <p>This configuration can be changed into an IP-based virtual + hosting solution by just turning <code>UseCanonicalName + Off</code> into <code>UseCanonicalName DNS</code>. The server + name that is inserted into the filename is then derived from + the IP address of the virtual host.</p> + +</section> + +<section id="homepages"><title>A virtually hosted homepages system</title> + + <p>This is an adjustment of the above system tailored for an + ISP's homepages server. Using a slightly more complicated + configuration we can select substrings of the server name to + use in the filename so that e.g. the documents for + <samp>www.user.isp.com</samp> are found in + <code>/home/user/</code>. It uses a single <code>cgi-bin</code> + directory instead of one per virtual host.</p> + +<example> +# all the preliminary stuff is the same as above, then<br /> +<br /> +# include part of the server name in the filenames<br /> +VirtualDocumentRoot /www/hosts/%2/docs<br /> +<br /> +# single cgi-bin directory<br /> +ScriptAlias /cgi-bin/ /www/std-cgi/<br /> +</example> + + <p>There are examples of more complicated + <code>VirtualDocumentRoot</code> settings in the + <module>mod_vhost_alias</module> documentation.</p> + +</section> + +<section id="combinations"><title>Using more than + one virtual hosting system on the same server</title> + + <p>With more complicated setups you can use Apache's normal + <code><VirtualHost></code> directives to control the + scope of the various virtual hosting configurations. For + example, you could have one IP address for homepages customers + and another for commercial customers with the following setup. + This can of course be combined with conventional + <code><VirtualHost></code> configuration sections.</p> + +<example> +UseCanonicalName Off<br /> +<br /> +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br /> +<br /> +<Directory /www/commercial><br /> +<indent> + Options FollowSymLinks<br /> + AllowOverride All<br /> +</indent> +</Directory><br /> +<br /> +<Directory /www/homepages><br /> +<indent> + Options FollowSymLinks<br /> + AllowOverride None<br /> +</indent> +</Directory><br /> +<br /> +<VirtualHost 111.22.33.44><br /> +<indent> + ServerName www.commercial.isp.com<br /> + <br /> + CustomLog logs/access_log.commercial vcommon<br /> + <br /> + VirtualDocumentRoot /www/commercial/%0/docs<br /> + VirtualScriptAlias /www/commercial/%0/cgi-bin<br /> +</indent> +</VirtualHost><br /> +<br /> +<VirtualHost 111.22.33.45><br /> +<indent> + ServerName www.homepages.isp.com<br /> + <br /> + CustomLog logs/access_log.homepages vcommon<br /> + <br /> + VirtualDocumentRoot /www/homepages/%0/docs<br /> + ScriptAlias /cgi-bin/ /www/std-cgi/<br /> +</indent> +</VirtualHost> +</example> + +</section> + +<section id="ipbased"><title>More efficient IP-based virtual hosting</title> + + <p>After <a href="#simple">the first example</a> I noted that + it is easy to turn it into an IP-based virtual hosting setup. + Unfortunately that configuration is not very efficient because + it requires a DNS lookup for every request. This can be avoided + by laying out the filesystem according to the IP addresses + themselves rather than the corresponding names and changing the + logging similarly. Apache will then usually not need to work + out the server name and so incur a DNS lookup.</p> + +<example> +# get the server name from the reverse DNS of the IP address<br /> +UseCanonicalName DNS<br /> +<br /> +# include the IP address in the logs so they may be split<br /> +LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +# include the IP address in the filenames<br /> +VirtualDocumentRootIP /www/hosts/%0/docs<br /> +VirtualScriptAliasIP /www/hosts/%0/cgi-bin<br /> +</example> + +</section> + +<section id="oldversion"><title>Using older versions of Apache</title> + + <p>The examples above rely on <code>mod_vhost_alias</code> + which appeared after version 1.3.6. If you are using a version + of Apache without <code>mod_vhost_alias</code> then you can + implement this technique with <code>mod_rewrite</code> as + illustrated below, but only for Host:-header-based virtual + hosts.</p> + + <p>In addition there are some things to beware of with logging. + Apache 1.3.6 is the first version to include the + <code>%V</code> log format directive; in versions 1.3.0 - 1.3.3 + the <code>%v</code> option did what <code>%V</code> does; + version 1.3.4 has no equivalent. In all these versions of + Apache the <code>UseCanonicalName</code> directive can appear + in <code>.htaccess</code> files which means that customers can + cause the wrong thing to be logged. Therefore the best thing to + do is use the <code>%{Host}i</code> directive which logs the + <code>Host:</code> header directly; note that this may include + <code>:port</code> on the end which is not the case for + <code>%V</code>.</p> + +</section> + +<section id="simple.rewrite"><title>Simple dynamic + virtual hosts using <code>mod_rewrite</code></title> + + <p>This extract from <code>httpd.conf</code> does the same + thing as <a href="#simple">the first example</a>. The first + half is very similar to the corresponding part above but with + some changes for backward compatibility and to make the + <code>mod_rewrite</code> part work properly; the second half + configures <code>mod_rewrite</code> to do the actual work.</p> + + <p>There are a couple of especially tricky bits: By default, + <code>mod_rewrite</code> runs before the other URI translation + modules (<code>mod_alias</code> etc.) so if they are used then + <code>mod_rewrite</code> must be configured to accommodate + them. Also, mome magic must be performed to do a + per-dynamic-virtual-host equivalent of + <code>ScriptAlias</code>.</p> + +<example> +# get the server name from the Host: header<br /> +UseCanonicalName Off<br /> +<br /> +# splittable logs<br /> +LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br /> +CustomLog logs/access_log vcommon<br /> +<br /> +<Directory /www/hosts><br /> +<indent> + # ExecCGI is needed here because we can't force<br /> + # CGI execution in the way that ScriptAlias does<br /> + Options FollowSymLinks ExecCGI<br /> +</indent> +</Directory><br /> +<br /> +# now for the hard bit<br /> +<br /> +RewriteEngine On<br /> +<br /> +# a ServerName derived from a Host: header may be any case at all<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +## deal with normal documents first:<br /> +# allow Alias /icons/ to work - repeat for other aliases<br /> +RewriteCond %{REQUEST_URI} !^/icons/<br /> +# allow CGIs to work<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +# do the magic<br /> +RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br /> +<br /> +## and now deal with CGIs - we have to force a MIME type<br /> +RewriteCond %{REQUEST_URI} ^/cgi-bin/<br /> +RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]<br /> +<br /> +# that's it! +</example> + +</section> + +<section id="homepages.rewrite"><title>A + homepages system using <code>mod_rewrite</code></title> + + <p>This does the same thing as <a href="#homepages">the second + example</a>.</p> + +<example> +RewriteEngine on<br /> +<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +# allow CGIs to work<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +<br /> +# check the hostname is right so that the RewriteRule works<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$<br /> +<br /> +# concatenate the virtual host name onto the start of the URI<br /> +# the [C] means do the next rewrite on the result of this one<br /> +RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]<br /> +<br /> +# now create the real file name<br /> +RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2<br /> +<br /> +# define the global CGI directory<br /> +ScriptAlias /cgi-bin/ /www/std-cgi/ +</example> + +</section> + +<section id="xtra-conf"><title>Using a separate virtual + host configuration file</title> + + <p>This arrangement uses more advanced <code>mod_rewrite</code> + features to get the translation from virtual host to document + root from a separate configuration file. This provides more + flexibility but requires more complicated configuration.</p> + + <p>The <code>vhost.map</code> file contains something like + this:</p> + +<example> +www.customer-1.com /www/customers/1<br /> +www.customer-2.com /www/customers/2<br /> +# ...<br /> +www.customer-N.com /www/customers/N<br /> +</example> + + <p>The <code>http.conf</code> contains this:</p> + +<example> +RewriteEngine on<br /> +<br /> +RewriteMap lowercase int:tolower<br /> +<br /> +# define the map file<br /> +RewriteMap vhost txt:/www/conf/vhost.map<br /> +<br /> +# deal with aliases as above<br /> +RewriteCond %{REQUEST_URI} !^/icons/<br /> +RewriteCond %{REQUEST_URI} !^/cgi-bin/<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br /> +# this does the file-based remap<br /> +RewriteCond ${vhost:%1} ^(/.*)$<br /> +RewriteRule ^/(.*)$ %1/docs/$1<br /> +<br /> +RewriteCond %{REQUEST_URI} ^/cgi-bin/<br /> +RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br /> +RewriteCond ${vhost:%1} ^(/.*)$<br /> +RewriteRule ^/(.*)$ %1/cgi-bin/$1 +</example> + +</section> +</manualpage> diff --git a/docs/manual/vhosts/name-based.html.en b/docs/manual/vhosts/name-based.html.en index effd7f78f2..bd622d0cba 100644 --- a/docs/manual/vhosts/name-based.html.en +++ b/docs/manual/vhosts/name-based.html.en @@ -1,124 +1,88 @@ -<!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> +<?xml version="1.0" encoding="ISO-8859-1"?> +<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> +<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!-- + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + This file is generated from xml source: DO NOT EDIT + XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX + --><title>Name-based Virtual Host Support - Apache HTTP Server</title><link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /><link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /><link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link href="../images/favicon.ico" rel="shortcut icon" /></head><body id="manual-page"><div id="page-header"><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p><p class="apache">Apache HTTP Server Version 2.0</p><img alt="" src="../images/feather.gif" /></div><div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div><div id="path"><a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.0</a></div><div id="page-content"><div id="preamble"><h1>Name-based Virtual Host Support</h1> + + <p>This document describes when and how to use name-based virtual hosts.</p> + +</div><div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#namevip">Name-based vs. IP-based Virtual Hosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#using">Using Name-based Virtual Hosts</a></li><li><img alt="" src="../images/down.gif" /> <a href="#">Compatibility with Older Browsers</a></li></ul><h3>See also</h3><ul class="seealso"><li><a href="ip-based.html">IP-based Virtual Host Support</a></li><li><a href="details.html">An In-Depth Discussion of Virtual Host Matching</a></li><li><a href="mass.html">Dynamically configured mass virtual hosting</a></li><li><a href="examples.html">Virtual Host examples for common setups</a></li><li><a href="examples.html#serverpath">ServerPath configuration example</a></li></ul></div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="namevip" id="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> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="using" id="using">Using Name-based Virtual Hosts</a></h2> + +<table class="related"><tr><th>Related Modules</th><th>Related Directives</th></tr><tr><td><ul><li><code class="module"><a href="../mod/core.html">core</a></code></li></ul></td><td><ul><li><code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code></li><li><code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code></li><li><code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code></li><li><code class="directive"><a href="../mod/core.html#servername">ServerName</a></code></li><li><code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code></li><li><code class="directive"><a href="../mod/core.html#virtualhost">VirtualHost</a></code></li></ul></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 <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> 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 <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code> 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 / + <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive to + designate which host is served and a <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> 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 + <code>www.domain.tld</code> and you wish to add the virtual host + <code>www.otherdomain.tld</code>, which points at the same IP address. + Then you simply add the following to <code>httpd.conf</code>:</p> + + <div class="example"><pre> NameVirtualHost * <VirtualHost *> @@ -130,110 +94,103 @@ Then you simply add the following to <code>httpd.conf</code>:</p> 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 +</pre></div> + + <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 <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code> + directive, placed inside the <VirtualHost> section. For + example if you add this to the first <VirtualHost> block + above</p> + + <div class="example"><p><code> + ServerAlias domain.tld *.domain.tld + </code></p></div> + + <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-dict.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> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div><div class="section"><h2><a name="" id="">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> + <p>There is a possible workaround with the <code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code> 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> + <div class="example"><p><code> + NameVirtualHost 111.22.33.44<br /> + <br /> + <VirtualHost 111.22.33.44><br /> + ServerName www.domain.tld<br /> + ServerPath /domain<br /> + DocumentRoot /web/domain<br /> + </VirtualHost><br /> + </code></p></div> <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 + beginning with "<code>/domain</code>" will be served from the + virtual host <code>www.domain.tld</code> 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 + although clients sending a <code>Host:</code> 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 + <code>http://www.domain.tld/domain/</code> 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> + (<em>e.g.</em>, "<code>file.html</code>" or + "<code>../icons/image.gif</code>" or links containing the + prefacing <code>/domain/</code> (<em>e.g.</em>, + "<code>http://www.domain.tld/domain/misc/file.html</code>" or + "<code>/domain/misc/file.html</code>").</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> - +</div></div><div id="footer"><p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p><p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div></body></html>
\ No newline at end of file diff --git a/docs/manual/vhosts/name-based.xml b/docs/manual/vhosts/name-based.xml new file mode 100644 index 0000000000..6cc9a1f7e5 --- /dev/null +++ b/docs/manual/vhosts/name-based.xml @@ -0,0 +1,234 @@ +<?xml version='1.0' encoding='UTF-8' ?> +<!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> +<?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> + +<manualpage> +<relativepath href=".."/> + +<title>Name-based Virtual Host Support</title> + +<summary> + + <p>This document describes when and how to use name-based virtual hosts.</p> + +</summary> + +<seealso><a href="ip-based.html">IP-based Virtual Host Support</a></seealso> +<seealso><a href="details.html">An In-Depth Discussion of Virtual Host Matching</a></seealso> +<seealso><a href="mass.html">Dynamically configured mass virtual hosting</a></seealso> +<seealso><a href="examples.html">Virtual Host examples for common setups</a></seealso> +<seealso><a href="examples.html#serverpath">ServerPath configuration example</a></seealso> + +<section id="namevip"><title>Name-based vs. IP-based Virtual Hosts</title> + + <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> + +</section> + +<section id="using"><title>Using Name-based Virtual Hosts</title> + +<related> + <modulelist> + <module>core</module> + </modulelist> + + <directivelist> + <directive module="core">DocumentRoot</directive> + <directive module="core">NameVirtualHost</directive> + <directive module="core">ServerAlias</directive> + <directive module="core">ServerName</directive> + <directive module="core">ServerPath</directive> + <directive module="core">VirtualHost</directive> + </directivelist> +</related> + + <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 <directive + module="core">NameVirtualHost</directive> 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 <directive type="section" + module="core">VirtualHost</directive> 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 / + <directive module="core">ServerName</directive> directive to + designate which host is served and a <directive + module="core">DocumentRoot</directive> 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 + <code>www.domain.tld</code> and you wish to add the virtual host + <code>www.otherdomain.tld</code>, which points at the same IP address. + Then you simply add the following to <code>httpd.conf</code>:</p> + + <example> +<pre> + NameVirtualHost * + + <VirtualHost *> + ServerName www.domain.tld + DocumentRoot /www/domain + </VirtualHost> + + <VirtualHost *> + ServerName www.otherdomain.tld + DocumentRoot /www/otherdomain + </VirtualHost> +</pre> + </example> + + <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 <directive module="core">ServerAlias</directive> + directive, placed inside the <VirtualHost> section. For + example if you add this to the first <VirtualHost> block + above</p> + + <example> + ServerAlias domain.tld *.domain.tld + </example> + + <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-dict.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> + +</section> + +<section id=""><title>Compatibility with Older Browsers</title> + + <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 <directive + module="core">ServerPath</directive> + directive, albeit a slightly cumbersome one:</p> + + <p>Example configuration:</p> + + <example> + NameVirtualHost 111.22.33.44<br /> + <br /> + <VirtualHost 111.22.33.44><br /> + ServerName www.domain.tld<br /> + ServerPath /domain<br /> + DocumentRoot /web/domain<br /> + </VirtualHost><br /> + </example> + + <p>What does this mean? It means that a request for any URI + beginning with "<code>/domain</code>" will be served from the + virtual host <code>www.domain.tld</code> This means that the + pages can be accessed as + <code>http://www.domain.tld/domain/</code> for all clients, + although clients sending a <code>Host:</code> 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 + <code>http://www.domain.tld/domain/</code> Then, in the virtual + host's pages, be sure to use either purely relative links + (<em>e.g.</em>, "<code>file.html</code>" or + "<code>../icons/image.gif</code>" or links containing the + prefacing <code>/domain/</code> (<em>e.g.</em>, + "<code>http://www.domain.tld/domain/misc/file.html</code>" or + "<code>/domain/misc/file.html</code>").</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> + +</section> +</manualpage> + + |