name-based.html revision c114f15e6fa030dcc846aaf39fbebd845c44ca4a
280a8a0544b4aeb52414d20e8c6e6c5b1108562eTinderbox User<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
59602f2a7c4e4809941583bed3e94cd26e628f1aTinderbox User "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
969eaf7df8ac651946f76b6631ff5db568c11ef6Tinderbox User <!-- Background white, links blue (unvisited), navy (visited), red (active) -->
f4ee48be3994797a8332b86c101db4d7b54799ceTinderbox User <body bgcolor="#FFFFFF" text="#000000" link="#0000FF"
8de3f14f1c300c3e1ed99084cc03485b42c92bf1Tinderbox User <!--#include virtual="header.html" -->
950d203b64f512b85fcc093ee1e9e3e531a1aea3Tinderbox User <h1 align="CENTER">Name-based Virtual Host Support</h1>
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User<p>This document describes when and how to use name-based virtual hosts.</p>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<li><a href="#namevip">Name-based vs. IP-based Virtual Hosts</a></li>
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews<li><a href="#using">Using Name-based Virtual Hosts</a></li>
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox User<li><a href="#compat">Compatibility With Older Browsers</a></li>
3759f10fc543747668b1ca4b4671f35b0dea8445Francis Dupont<p>See also: <a href="examples.html">Virtual Host examples for common
d5637bdbb931ff79fced3d4858d83212ea58ed15Tinderbox Usersetups</a>, <a href="ip-based.html">IP-based Virtual Host Support</a>,
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<a href="details.html">An In-Depth Discussion of Virtual Host
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox UserMatching</a>, and <a href="mass.html">Dynamically configured mass
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<h2><a name="namevip">Name-based vs. IP-based Virtual Hosts</a></h2>
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews<p>IP-based virtual hosts use the IP address of the connection to
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsdetermine the correct virtual host to serve. Therefore you need to
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunthave a separate IP address for each host. With name-based virtual
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewshosting, the server relies on the client to report the hostname as
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userpart of the HTTP headers. Using this technique, many different hosts
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewscan share the same IP address.</p>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<p>Name-based virtual hosting is usually simpler, since you need
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Huntonly configure your DNS server to map each hostname to the correct
0eb371ca0dab50ae3462e98794a6126198c52f4bMark AndrewsIP address and then configure the Apache HTTP Server to recognize
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox Userthe different hostnames. Name-based virtual hosting also eases
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox Userthe demand for scarce IP addresses. Therefore you should use
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Huntname-based virtual hosting unless there is a specific reason to
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox Userchoose IP-based virtual hosting. Some reasons why you might consider
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrewsusing IP-based virtual hosting:</p>
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<li>Some ancient clients are not compatible with name-based virtual
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Hunthosting. For name-based virtual hosting to work, the client must send
dc238a06bffa79de141ee7655765e2df91498a8aTinderbox Userthe HTTP Host header. This is required by HTTP/1.1, and is
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrewsimplemented by all modern HTTP/1.0 browsers as an extension. If you
aa9c561961e9d877946ebaa8795fa2be054ab7bfEvan Huntneed to support obsolete clients and still use name-based virtual
710bce1a85c96e85ca1a90471382055acd29d51fTinderbox Userhosting, a possible technique is discussed at the end of this
9513a2a6670951f5cf5477fcfec9f933fcaff628Automatic Updater<li>Name-based virtual hosting cannot be used with SSL secure servers
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsbecause of the nature of the SSL protocol.</li>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<li>Some operating systems and network equipment implement bandwidth
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Huntmanagement techniques that cannot differentiate between hosts unless
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsthey are on separate IP addresses.</li>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<h2><a name="using">Using Name-based Virtual Hosts</a></h2>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<a href="mod/core.html#documentroot">DocumentRoot</a><br />
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews<a href="mod/core.html#namevirtualhost">NameVirtualHost</a><br />
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<a href="mod/core.html#serveralias">ServerAlias</a><br />
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<a href="mod/core.html#servername">ServerName</a><br />
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User<a href="mod/core.html#serverpath">ServerPath</a><br />
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox User<a href="mod/core.html#virtualhost">VirtualHost</a><br />
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrews<p>To use name-based virtual hosting, you must designate the IP
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewsaddress (and possibly port) on the server that will be accepting
2ae159b376dac23870d8005563c585acf85a4b5aEvan Huntrequests for the hosts. This is configured using the <a
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunthref="/mod/core.html#namevirtualhost">NameVirtualHost</a> directive.
2ae159b376dac23870d8005563c585acf85a4b5aEvan HuntIn the normal case where any and all IP addresses on the server should
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsbe used, you can use <code>*</code> as the argument to
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<code>NameVirtualHost</code>. Note that mentioning an IP address in a
2ae159b376dac23870d8005563c585acf85a4b5aEvan Hunt<code>NameVirtualHost</code> directive does not automatically make the
7cc0a5d21ef046bfd630c4769943d896a7d7472cTinderbox Userserver listen to that IP address. See <a href="/bind.html">Setting
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox Userwhich addresses and ports Apache uses</a> for more details.
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox Userhref="/mod/core.html#virtualhost"><VirtualHost></a> block for
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewseach different host that you would like to serve. The argument to the
549c517e2ecad52bb1d32f08920e29d4e8cda71eTinderbox User<code><VirtualHost></code> directive should be the same as the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsargument to the <code>NameVirtualHost</code> directive (ie, an IP
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Useraddress, or <code>*</code> for all addresses). Inside each
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrews<code><VirtualHost></code> block, you will need at minimum a <a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewshref="/mod/core.html#servername">ServerName</a> directive to
b91d11bfcc30b96f2c80f3a76d12e3dcc8597a68Mark Andrewsdesignate which host is served and a <a
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewshref="/mod/core.html#documentroot">DocumentRoot</a> directive to
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Usershow where in the filesystem the content for that host lives.</p>
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p>For example, suppose that both <samp>www.domain.tld</samp> and
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<samp>www.otherdomain.tld</samp> point at the IP address
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<samp>111.22.33.44</samp>. Then you simply add the following
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews NameVirtualHost 111.22.33.44
efb0e886f18894a1d2489f1ad74ad14b579e11c7Mark Andrews <VirtualHost 111.22.33.44>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews </VirtualHost>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson <VirtualHost 111.22.33.44>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt </VirtualHost>
91216cff91b34c9ff6e846dc23f248219cafe660Andreas Gustafsson<p>In the simplest case, the IP address <code>111.22.44.33</code> can be
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userreplaced by <code>*</code> to match all IP addresses for your server.</p>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<p>Many servers want to be accessible by more than one name. This is
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewspossible with the <a
28a5dd720187fddb16055a0f64b63a7b66f29f64Mark Andrewshref="/mod/core.html#serveralias"><code>ServerAlias</code></a>
03ebc228ee3725738b067b6bd7082a9a731822a1Tinderbox Userdirective, placed inside the <VirtualHost> section. For
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsexample if you add this to the first <VirtualHost> block
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrews<p>then requests for all hosts in the <code>domain.tld</code> domain
2a31bd531072824ef252c18303859d6af7451b00Francis Dupontwill be served by the <code>www.domain.tld</code> virtual host. The
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Userwildcard characters * and ? can be used to match names. Of course,
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrewsyou can't just make up names and place them in <code>ServerName</code>
2a31bd531072824ef252c18303859d6af7451b00Francis Dupontor <code>ServerAlias</code>. You must first have your DNS server
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewsproperly configured to map those names to the IP address in the
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p>Finally, you can fine-tune the configuration of the virtual hosts
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsby placing other directives inside the
a03cb08d0c4f1ca5fbc121d2f02bdffa7eb52286Mark Andrews<code><VirtualHost></code> containers. Most directives can be
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrewsplaced in these containers and will then change the configuration only
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsof the relevant virtual host. To find out if a particular directive
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewsis allowed, check the <a
7f9e2fff07b9c17e0d7a0ea7abc9304ce9d01b61Tinderbox Userhref="/mod/directive-dist.html#Context">Context</a> of the
5747235bf35e7398984fd6b4632743396895ea7aTinderbox Userdirective. Configuration directives set in the <em>main server
78f3ed4bc2fcd3d270bfd599804f3b27a1db4d91Mark Andrewscontext</em> (outside any <code><VirtualHost></code> container)
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrewswill be used only if they are not overriden by the virtual host
c651f15b30f1dae5cc2f00878fb5da5b3a35a468Mark Andrews<p>Now when a request arrives, the server will first check if it is
fec6e13f2d1e69fe1c2b8fac36f732f124cf5398Mark Andrewsusing an IP address that matches the <code>NameVirtualHost</code>. If
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Userit is, then it will look at each <code><VirtualHost></code>
827f8cccb5280f4da66c46186e792d1cb9d73503Mark Andrewssection with a matching IP address and try to find one where the
01a5c5503482fb3ba52088bf0178a7213273bf96Mark Andrews<code>ServerName</code> or <code>ServerAlias</code> matches the
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Userrequested hostname. If it finds one, then it uses the configuration
e40c4e4c17d4df338e2a7db0f84d8dbb3858964cTinderbox Userfor that server. If no matching virtual host is found, then
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<strong>the first listed virtual host</strong> that matches the IP
cdfc81e048bd34c1d628380247bda6b80a89e20eAutomatic Updateraddress will be used.</p>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<p>As a consequence, the first listed virtual host is the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews<em>default</em> virtual host. The <code>DocumentRoot</code> from the
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User<em>main server</em> will <strong>never</strong> be used when an IP
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updateraddress matches the <code>NameVirtualHost</code> directive. If you
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox Userwould like to have a special configuration for requests that do not
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrewsmatch any particular virtual host, simply put that configuration in a
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt<code><VirtualHost></code> container and list it first in the
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrewsconfiguration file.</p>
fa0326cc2cf428f67575b6ba3b97b528a31b0010Tinderbox User<h2><a name="compat">Compatibility with Older Browsers</a></h2>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <p>As mentioned earlier, there are some clients
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt who do not send the required data for the name-based virtual
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews hosts to work properly. These clients will always be sent the
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User pages from the first virtual host listed for that IP address
fe80a4909bf62b602feaf246866e9d29f7654194Automatic Updater (the <cite>primary</cite> name-based virtual host).</p>
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt href="/mod/core.html#serverpath"><code>ServerPath</code></a>
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews directive, albeit a slightly cumbersome one:</p>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews NameVirtualHost 111.22.33.44
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews <VirtualHost 111.22.33.44>
dd65eb1efb40b1c47d57963192bfc54873b219beAutomatic Updater ServerPath /domain
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews </VirtualHost>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <p>What does this mean? It means that a request for any URI
133e6d43fa82e80d3798be4de00f4540f485ec6cAutomatic Updater beginning with "<samp>/domain</samp>" will be served from the
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User virtual host <samp>www.domain.tld</samp> This means that the
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews pages can be accessed as
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <code>http://www.domain.tld/domain/</code> for all clients,
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews although clients sending a <samp>Host:</samp> header can also
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User access it as <code>http://www.domain.tld/</code>.</p>
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User <p>In order to make this work, put a link on your primary
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews virtual host's page to
30370d905e9be3be7d9b947fd432bacecbb13bb9Evan Hunt <samp>http://www.domain.tld/domain/</samp> Then, in the virtual
0eb371ca0dab50ae3462e98794a6126198c52f4bMark Andrews host's pages, be sure to use either purely relative links
5f7586ddbd3edd11272cdd30ed613d936129328bTinderbox User "<samp>/icons/image.gif</samp>" or links containing the
9ecb5d33470ebfb3719a1b8d56bcefdf4b27f7b2Tinderbox User prefacing <samp>/domain/</samp> (<em>e.g.</em>,
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews "<samp>http://www.domain.tld/domain/misc/file.html</samp>" or
015055b6e23f5c08f6a5b34726f90b62597e9e45Tinderbox User <p>This requires a bit of discipline, but adherence to these
ac2e2800b4ac9cbe4cb756d967f4583c611eb75eMark Andrews guidelines will, for the most part, ensure that your pages will
5affecff6e148a8e124d03f5dbac0da11e30dcc5Tinderbox User work with all browsers, new and old.</p>
e813f036c8251b6d9d2a72fa84f80c2c9d2795afMark Andrews <p>See also: <a href="examples.html#serverpath">ServerPath
bac4435d473c9a0281507524f084480c34aa942aTinderbox User <!--#include virtual="footer.html" -->