granicus.if.org Git - apache/blob - docs/manual/vhosts/name-based.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>Name-based Virtual Host Support - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
  12 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  13 <body id="manual-page"><div id="page-header">
  14 <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>
  15 <p class="apache">Apache HTTP Server Version 2.1</p>
  16 <img alt="" src="../images/feather.gif" /></div>
  17 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  18 <div id="path">
  19 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs-project/">Documentation</a> &gt; <a href="../">Version 2.1</a> &gt; <a href="./">Virtual Hosts</a></div><div id="page-content"><div id="preamble"><h1>Name-based Virtual Host Support</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/vhosts/name-based.html" hreflang="en" title="English">&nbsp;en&nbsp;</a> | <a href="../ja/vhosts/name-based.html" hreflang="ja" title="Japanese">&nbsp;ja&nbsp;</a> | <a href="../ko/vhosts/name-based.html" hreflang="ko" title="Korean">&nbsp;ko&nbsp;</a></p>
  22 </div>
  23
  24
  25         <p>This document describes when and how to use name-based virtual hosts.</p>
  26
  27 </div>
  28 <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>
  29 <li><img alt="" src="../images/down.gif" /> <a href="#using">Using Name-based Virtual Hosts</a></li>
  30 <li><img alt="" src="../images/down.gif" /> <a href="#compat">Compatibility with Older Browsers</a></li>
  31 </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>
  32 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  33 <div class="section">
  34 <h2><a name="namevip" id="namevip">Name-based vs. IP-based Virtual Hosts</a></h2>
  35
  36         <p>IP-based virtual hosts use the IP address of the connection to
  37         determine the correct virtual host to serve.  Therefore you need to
  38         have a separate IP address for each host.  With name-based virtual
  39         hosting, the server relies on the client to report the hostname as
  40         part of the HTTP headers.  Using this technique, many different hosts
  41         can share the same IP address.</p>
  42
  43         <p>Name-based virtual hosting is usually simpler, since you need
  44         only configure your DNS server to map each hostname to the correct
  45         IP address and then configure the Apache HTTP Server to recognize
  46         the different hostnames.  Name-based virtual hosting also eases
  47         the demand for scarce IP addresses.  Therefore you should use
  48         name-based virtual hosting unless there is a specific reason to
  49         choose IP-based virtual hosting.  Some reasons why you might consider
  50         using IP-based virtual hosting:</p>
  51
  52         <ul>
  53                 <li>Some ancient clients are not compatible with name-based virtual
  54                 hosting.  For name-based virtual hosting to work, the client must send
  55                 the HTTP Host header.  This is required by HTTP/1.1, and is
  56                 implemented by all modern HTTP/1.0 browsers as an extension.  If you
  57                 need to support obsolete clients and still use name-based virtual
  58                 hosting, a possible technique is discussed at the end of this
  59                 document.</li>
  60
  61                 <li>Name-based virtual hosting cannot be used with SSL secure servers
  62                 because of the nature of the SSL protocol.</li>
  63
  64                 <li>Some operating systems and network equipment implement bandwidth
  65                 management techniques that cannot differentiate between hosts unless
  66                 they are on separate IP addresses.</li>
  67         </ul>
  68
  69 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  70 <div class="section">
  71 <h2><a name="using" id="using">Using Name-based Virtual Hosts</a></h2>
  72
  73 <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>
  74
  75         <p>To use name-based virtual hosting, you must designate the IP
  76         address (and possibly port) on the server that will be accepting
  77         requests for the hosts.  This is configured using the <code class="directive"><a href="../mod/core.html#namevirtualhost">NameVirtualHost</a></code> directive.
  78         In the normal case where any and all IP addresses on the server should
  79         be used, you can use <code>*</code> as the argument to
  80         <code>NameVirtualHost</code>.  Note that mentioning an IP address in a
  81         <code>NameVirtualHost</code> directive does not automatically make the
  82         server listen to that IP address.  See <a href="../bind.html">Setting
  83         which addresses and ports Apache uses</a> for more details.  In addition,
  84         any IP address specified here must be associated with a network interface
  85         on the server.</p>
  86
  87         <p>The next step is to create a <code class="directive"><a href="../mod/core.html#virtualhost">&lt;VirtualHost&gt;</a></code> block for
  88         each different host that you would like to serve.  The argument to the
  89         <code>&lt;VirtualHost&gt;</code> directive should be the same as the
  90         argument to the <code>NameVirtualHost</code> directive (ie, an IP
  91         address, or <code>*</code> for all addresses).  Inside each
  92         <code>&lt;VirtualHost&gt;</code> block, you will need at minimum a
  93         <code class="directive"><a href="../mod/core.html#servername">ServerName</a></code> directive to
  94         designate which host is served and a <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> directive to
  95         show where in the filesystem the content for that host lives.</p>
  96
  97     <div class="note"><h3>Main host goes away</h3>
  98         If you are adding virtual hosts to an existing web server, you
  99         must also create a &lt;VirtualHost&gt; block for the existing host.
 100         The <code>ServerName</code> and <code>DocumentRoot</code> included in
 101         this virtual host should be the same as the global
 102         <code>ServerName</code> and <code>DocumentRoot</code>.  List this
 103         virtual host first in the configuration file so that it will act as
 104         the default host.
 105     </div>
 106
 107         <p>For example, suppose that you are serving the domain
 108         <code>www.domain.tld</code> and you wish to add the virtual host
 109         <code>www.otherdomain.tld</code>, which points at the same IP address.
 110         Then you simply add the following to <code>httpd.conf</code>:</p>
 111
 112         <div class="example"><p><code>
 113     NameVirtualHost *<br />
 114     <br />
 115     &lt;VirtualHost *&gt;<br />
 116     <span class="indent">
 117     ServerName www.domain.tld<br />
 118     ServerAlias domain.tld *.domain.tld<br />
 119     DocumentRoot /www/domain<br />
 120     </span>
 121     &lt;/VirtualHost&gt;<br />
 122     <br />
 123     &lt;VirtualHost *&gt;<br />
 124     <span class="indent">ServerName www.otherdomain.tld<br />
 125     DocumentRoot /www/otherdomain<br />
 126     </span>
 127     &lt;/VirtualHost&gt;<br />
 128         </code></p></div>
 129
 130         <p>You can alternatively specify an explicit IP address in place of
 131         the * in both the <code>NameVirtualHost</code> and
 132         <code>&lt;VirtualHost&gt;</code> directives. For example, you might
 133     want to do this in order to run some name-based virtual hosts on one
 134     IP address, and either IP-based, or another set of name-based
 135     virtual hosts on another address.</p>
 136
 137         <p>Many servers want to be accessible by more than one name.  This is
 138         possible with the <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code>
 139         directive, placed inside the &lt;VirtualHost&gt; section. For
 140         example in the first &lt;VirtualHost&gt; block above, the <code class="directive"><a href="../mod/core.html#serveralias">ServerAlias</a></code> directive indicates that the
 141     listed names are other names which people can use to see that same
 142     web site:</p>
 143
 144         <div class="example"><p><code>
 145     ServerAlias domain.tld *.domain.tld
 146         </code></p></div>
 147
 148         <p>then requests for all hosts in the <code>domain.tld</code> domain
 149         will be served by the <code>www.domain.tld</code> virtual host.  The
 150         wildcard characters * and ? can be used to match names.  Of course,
 151         you can't just make up names and place them in <code>ServerName</code>
 152         or <code>ServerAlias</code>.  You must first have your DNS server
 153         properly configured to map those names to an IP address associated
 154         with your server.</p>
 155
 156         <p>Finally, you can fine-tune the configuration of the virtual hosts
 157         by placing other directives inside the
 158         <code>&lt;VirtualHost&gt;</code> containers.  Most directives can be
 159         placed in these containers and will then change the configuration only
 160         of the relevant virtual host.  To find out if a particular directive
 161         is allowed, check the <a href="../mod/directive-dict.html#Context">Context</a> of the
 162         directive.  Configuration directives set in the <em>main server
 163         context</em> (outside any <code>&lt;VirtualHost&gt;</code> container)
 164         will be used only if they are not overridden by the virtual host
 165         settings.</p>
 166
 167         <p>Now when a request arrives, the server will first check if it is
 168         using an IP address that matches the <code>NameVirtualHost</code>.  If
 169         it is, then it will look at each <code>&lt;VirtualHost&gt;</code>
 170         section with a matching IP address and try to find one where the
 171         <code>ServerName</code> or <code>ServerAlias</code> matches the
 172         requested hostname.  If it finds one, then it uses the configuration
 173         for that server.  If no matching virtual host is found, then
 174         <strong>the first listed virtual host</strong> that matches the IP
 175         address will be used.</p>
 176
 177         <p>As a consequence, the first listed virtual host is the
 178         <em>default</em> virtual host.  The <code>DocumentRoot</code> from the
 179         <em>main server</em> will <strong>never</strong> be used when an IP
 180         address matches the <code>NameVirtualHost</code> directive.  If you
 181         would like to have a special configuration for requests that do not
 182         match any particular virtual host, simply put that configuration in a
 183         <code>&lt;VirtualHost&gt;</code> container and list it first in the
 184         configuration file.</p>
 185
 186 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 187 <div class="section">
 188 <h2><a name="compat" id="compat">Compatibility with Older Browsers</a></h2>
 189
 190     <p>As mentioned earlier, there are some clients
 191     who do not send the required data for the name-based virtual
 192     hosts to work properly. These clients will always be sent the
 193     pages from the first virtual host listed for that IP address
 194     (the <cite>primary</cite> name-based virtual host).</p>
 195
 196     <div class="note"><h3>How much older?</h3>
 197     Please note that when we say older, we really do mean older. You are
 198     very unlikely to encounter one of these browsers in use today. All
 199     current versions of any browser send the <code>Host</code> header as
 200     required for name-based virtual hosts.
 201     </div>
 202
 203     <p>There is a possible workaround with the <code class="directive"><a href="../mod/core.html#serverpath">ServerPath</a></code>
 204     directive, albeit a slightly cumbersome one:</p>
 205
 206     <p>Example configuration:</p>
 207
 208     <div class="example"><p><code>
 209     NameVirtualHost 111.22.33.44<br />
 210     <br />
 211     &lt;VirtualHost 111.22.33.44&gt;<br />
 212     <span class="indent">
 213     ServerName www.domain.tld<br />
 214     ServerPath /domain<br />
 215     DocumentRoot /web/domain<br />
 216     </span>
 217     &lt;/VirtualHost&gt;<br />
 218           </code></p></div>
 219
 220     <p>What does this mean? It means that a request for any URI
 221     beginning with "<code>/domain</code>" will be served from the
 222     virtual host <code>www.domain.tld</code> This means that the
 223     pages can be accessed as
 224     <code>http://www.domain.tld/domain/</code> for all clients,
 225     although clients sending a <code>Host:</code> header can also
 226     access it as <code>http://www.domain.tld/</code>.</p>
 227
 228     <p>In order to make this work, put a link on your primary
 229     virtual host's page to
 230     <code>http://www.domain.tld/domain/</code> Then, in the virtual
 231     host's pages, be sure to use either purely relative links
 232     (<em>e.g.</em>, "<code>file.html</code>" or
 233     "<code>../icons/image.gif</code>" or links containing the
 234     prefacing <code>/domain/</code> (<em>e.g.</em>,
 235     "<code>http://www.domain.tld/domain/misc/file.html</code>" or
 236     "<code>/domain/misc/file.html</code>").</p>
 237
 238     <p>This requires a bit of discipline, but adherence to these
 239     guidelines will, for the most part, ensure that your pages will
 240     work with all browsers, new and old.</p>
 241
 242 </div></div>
 243 <div class="bottomlang">
 244 <p><span>Available Languages: </span><a href="../en/vhosts/name-based.html" hreflang="en" title="English">&nbsp;en&nbsp;</a> | <a href="../ja/vhosts/name-based.html" hreflang="ja" title="Japanese">&nbsp;ja&nbsp;</a> | <a href="../ko/vhosts/name-based.html" hreflang="ko" title="Korean">&nbsp;ko&nbsp;</a></p>
 245 </div><div id="footer">
 246 <p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
 247 <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>
 248 </body></html>