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>Dynamically Configured Mass Virtual Hosting - 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" /><link rel="stylesheet" type="text/css" href="/style/css/prettify.css" /> 12<script src="/style/scripts/prettify.min.js" type="text/javascript"> 13</script> 14 15<link href="/images/favicon.ico" rel="shortcut icon" /></head> 16<body id="manual-page"><div id="page-header"> 17<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p> 18<p class="apache">Apache HTTP Server Version 2.4</p> 19<img alt="" src="/images/feather.gif" /></div> 20<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div> 21<div id="path"> 22<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Virtual Hosts</a></div><div id="page-content"><div id="preamble"><h1>Dynamically Configured Mass Virtual Hosting</h1> 23<div class="toplang"> 24<p><span>Available Languages: </span><a href="/en/vhosts/mass.html" title="English"> en </a> | 25<a href="/fr/vhosts/mass.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 26<a href="/ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 27<a href="/tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 28</div> 29 30 31 <p>This document describes how to efficiently serve an 32 arbitrary number of virtual hosts with the Apache HTTP Server. A 33 <a href="/rewrite/vhosts.html">separate document</a> discusses using 34 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> to create dynamic mass virtual hosts. 35 </p> 36 37</div> 38<div id="quickview"><ul id="toc"><li><img alt="" src="/images/down.gif" /> <a href="#motivation">Motivation</a></li> 39<li><img alt="" src="/images/down.gif" /> <a href="#overview">Overview</a></li> 40<li><img alt="" src="/images/down.gif" /> <a href="#simple">Dynamic Virtual Hosts with 41mod_vhost_alias</a></li> 42<li><img alt="" src="/images/down.gif" /> <a href="#homepages">Simplified Dynamic Virtual Hosts</a></li> 43<li><img alt="" src="/images/down.gif" /> <a href="#combinations">Using Multiple Virtual 44 Hosting Systems on the Same Server</a></li> 45<li><img alt="" src="/images/down.gif" /> <a href="#ipbased">More Efficient IP-Based Virtual Hosting</a></li> 46<li><img alt="" src="/images/down.gif" /> <a href="#rewrite">Mass virtual hosts with 47mod_rewrite</a></li> 48</ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div> 49<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 50<div class="section"> 51<h2><a name="motivation" id="motivation">Motivation</a></h2> 52 53 <p>The techniques described here are of interest if your 54 <code>httpd.conf</code> contains many 55 <code><VirtualHost></code> sections that are 56 substantially the same, for example:</p> 57 58<pre class="prettyprint lang-config"><VirtualHost 111.22.33.44> 59 ServerName customer-1.example.com 60 DocumentRoot /www/hosts/customer-1.example.com/docs 61 ScriptAlias /cgi-bin/ /www/hosts/customer-1.example.com/cgi-bin 62</VirtualHost> 63 64<VirtualHost 111.22.33.44> 65 ServerName customer-2.example.com 66 DocumentRoot /www/hosts/customer-2.example.com/docs 67 ScriptAlias /cgi-bin/ /www/hosts/customer-2.example.com/cgi-bin 68</VirtualHost> 69 70<VirtualHost 111.22.33.44> 71 ServerName customer-N.example.com 72 DocumentRoot /www/hosts/customer-N.example.com/docs 73 ScriptAlias /cgi-bin/ /www/hosts/customer-N.example.com/cgi-bin 74</VirtualHost></pre> 75 76 77 <p>We wish to replace these multiple 78 <code><VirtualHost></code> blocks with a mechanism 79 that works them out dynamically. This has a number of 80 advantages:</p> 81 82 <ol> 83 <li>Your configuration file is smaller, so Apache starts 84 more quickly and uses less memory. Perhaps more importantly, the 85 smaller configuration is easier to maintain, and leaves less room 86 for errors.</li> 87 88 <li>Adding virtual hosts is simply a matter of creating the 89 appropriate directories in the filesystem and entries in the 90 DNS - you don't need to reconfigure or restart Apache.</li> 91 </ol> 92 93 <p>The main disadvantage is that you cannot have a different log file for 94 each virtual host; however, if you have many virtual hosts, doing 95 this can be a bad idea anyway, because of the <a href="fd-limits.html">number of file descriptors needed</a>. 96 It is better to <a href="/logs.html#piped">log to a pipe or a fifo</a>, 97 and arrange for the process at the other end to split up the log 98 files into one per virtual host. One example of such a process can 99 be found in the <a href="/programs/other.html#split-logfile">split-logfile</a> 100 utility.</p> 101 102</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 103<div class="section"> 104<h2><a name="overview" id="overview">Overview</a></h2> 105 106 <p>A virtual host is defined by two pieces of information: its 107 IP address, and the contents of the <code>Host:</code> header 108 in the HTTP request. The dynamic mass virtual hosting technique 109 used here is based on automatically inserting this information into the 110 pathname of the file that is used to satisfy the request. This 111 can be most easily done by using <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> 112 with Apache httpd. Alternatively, 113 <a href="/rewrite/vhosts.html">mod_rewrite can 114 be used</a>.</p> 115 <p>Both of these modules are disabled by default; you must enable 116 one of them when configuring and building Apache httpd if you want to 117 use this technique.</p> 118 119 <p>A couple of things need to be determined from the request in 120 order to make the dynamic 121 virtual host look like a normal one. The most important is the 122 server name, which is used by the server to generate 123 self-referential URLs etc. It is configured with the 124 <code>ServerName</code> directive, and it is available to CGIs 125 via the <code>SERVER_NAME</code> environment variable. The 126 actual value used at run time is controlled by the <code class="directive"><a href="/mod/core.html#usecanonicalname">UseCanonicalName</a></code> 127 setting. With <code>UseCanonicalName Off</code>, the server name 128 is taken from the contents of the <code>Host:</code> header in the 129 request. With <code>UseCanonicalName DNS</code>, it is taken from a 130 reverse DNS lookup of the virtual host's IP address. The former 131 setting is used for name-based dynamic virtual hosting, and the 132 latter is used for IP-based hosting. If httpd cannot work out 133 the server name because there is no <code>Host:</code> header, 134 or the DNS lookup fails, then the value configured with 135 <code>ServerName</code> is used instead.</p> 136 137 <p>The other thing to determine is the document root (configured 138 with <code>DocumentRoot</code> and available to CGI scripts via the 139 <code>DOCUMENT_ROOT</code> environment variable). In a normal 140 configuration, this is used by the core module when 141 mapping URIs to filenames, but when the server is configured to 142 do dynamic virtual hosting, that job must be taken over by another 143 module (either <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> or 144 <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>), which has a different way of doing 145 the mapping. Neither of these modules is responsible for 146 setting the <code>DOCUMENT_ROOT</code> environment variable so 147 if any CGIs or SSI documents make use of it, they will get a 148 misleading value.</p> 149 150</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 151<div class="section"> 152<h2><a name="simple" id="simple">Dynamic Virtual Hosts with 153mod_vhost_alias</a></h2> 154 155 <p>This extract from <code>httpd.conf</code> implements the 156 virtual host arrangement outlined in the <a href="#motivation">Motivation</a> section above 157 using <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code>.</p> 158 159<pre class="prettyprint lang-config"># get the server name from the Host: header 160UseCanonicalName Off 161 162# this log format can be split per-virtual-host based on the first field 163# using the split-logfile utility. 164LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon 165CustomLog logs/access_log vcommon 166 167# include the server name in the filenames used to satisfy requests 168VirtualDocumentRoot /www/hosts/%0/docs 169VirtualScriptAlias /www/hosts/%0/cgi-bin</pre> 170 171 172 <p>This configuration can be changed into an IP-based virtual 173 hosting solution by just turning <code>UseCanonicalName 174 Off</code> into <code>UseCanonicalName DNS</code>. The server 175 name that is inserted into the filename is then derived from 176 the IP address of the virtual host. The variable <code>%0</code> 177 references the requested servername, as indicated in the 178 <code>Host:</code> header.</p> 179 180<p>See the <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> documentation for more usage 181examples.</p> 182 183</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 184<div class="section"> 185<h2><a name="homepages" id="homepages">Simplified Dynamic Virtual Hosts</a></h2> 186 187 <p>This is an adjustment of the above system, tailored for an 188 ISP's web hosting server. Using <code>%2</code>, 189 we can select substrings of the server name to 190 use in the filename so that, for example, the documents for 191 <code>www.user.example.com</code> are found in 192 <code>/home/user/www</code>. It uses a single <code>cgi-bin</code> 193 directory instead of one per virtual host.</p> 194 195<pre class="prettyprint lang-config">UseCanonicalName Off 196 197LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon 198CustomLog logs/access_log vcommon 199 200# include part of the server name in the filenames 201VirtualDocumentRoot /home/%2/www 202 203# single cgi-bin directory 204ScriptAlias /cgi-bin/ /www/std-cgi/</pre> 205 206 207 <p>There are examples of more complicated 208 <code>VirtualDocumentRoot</code> settings in the 209 <code class="module"><a href="/mod/mod_vhost_alias.html">mod_vhost_alias</a></code> documentation.</p> 210 211</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 212<div class="section"> 213<h2><a name="combinations" id="combinations">Using Multiple Virtual 214 Hosting Systems on the Same Server</a></h2> 215 216 <p>With more complicated setups, you can use httpd's normal 217 <code><VirtualHost></code> directives to control the 218 scope of the various virtual hosting configurations. For 219 example, you could have one IP address for general customers' homepages, 220 and another for commercial customers, with the following setup. 221 This can be combined with conventional 222 <code><VirtualHost></code> configuration sections, as shown 223 below.</p> 224 225<pre class="prettyprint lang-config">UseCanonicalName Off 226 227LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon 228 229<Directory /www/commercial> 230 Options FollowSymLinks 231 AllowOverride All 232</Directory> 233 234<Directory /www/homepages> 235 Options FollowSymLinks 236 AllowOverride None 237</Directory> 238 239<VirtualHost 111.22.33.44> 240 ServerName www.commercial.example.com 241 242 CustomLog logs/access_log.commercial vcommon 243 244 VirtualDocumentRoot /www/commercial/%0/docs 245 VirtualScriptAlias /www/commercial/%0/cgi-bin 246</VirtualHost> 247 248<VirtualHost 111.22.33.45> 249 ServerName www.homepages.example.com 250 251 CustomLog logs/access_log.homepages vcommon 252 253 VirtualDocumentRoot /www/homepages/%0/docs 254 ScriptAlias /cgi-bin/ /www/std-cgi/ 255</VirtualHost></pre> 256 257 258<div class="note"> 259 <h3>Note</h3> 260 <p>If the first VirtualHost block does <em>not</em> include a 261 <code class="directive"><a href="/mod/core.html#servername">ServerName</a></code> directive, the reverse 262 DNS of the relevant IP will be used instead. 263 If this is not the server name you 264 wish to use, a bogus entry (eg. <code>ServerName 265 none.example.com</code>) can be added to get around this 266 behaviour.</p> 267</div> 268 269</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 270<div class="section"> 271<h2><a name="ipbased" id="ipbased">More Efficient IP-Based Virtual Hosting</a></h2> 272 273 <p>The configuration changes suggested to turn <a href="#simple">the first 274 example</a> into an IP-based virtual hosting setup result in 275 a rather inefficient setup. A new DNS lookup is required for every 276 request. To avoid this overhead, the filesystem can be arranged to 277 correspond to the IP addresses, instead of to the host names, thereby 278 negating the need for a DNS lookup. Logging will also have to be adjusted 279 to fit this system.</p> 280 281<pre class="prettyprint lang-config"># get the server name from the reverse DNS of the IP address 282UseCanonicalName DNS 283 284# include the IP address in the logs so they may be split 285LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon 286CustomLog logs/access_log vcommon 287 288# include the IP address in the filenames 289VirtualDocumentRootIP /www/hosts/%0/docs 290VirtualScriptAliasIP /www/hosts/%0/cgi-bin</pre> 291 292 293</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div> 294<div class="section"> 295<h2><a name="rewrite" id="rewrite">Mass virtual hosts with 296mod_rewrite</a></h2> 297 298<p> 299Mass virtual hosting may also be accomplished using 300<code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>, either using simple <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives, or using more 301complicated techniques such as storing the vhost definitions externally 302and accessing them via <code class="directive"><a href="/mod/mod_rewrite.html#rewritemap">RewriteMap</a></code>. These techniques are 303discussed in the <a href="/rewrite/vhosts.html">rewrite 304documentation</a>.</p> 305</div></div> 306<div class="bottomlang"> 307<p><span>Available Languages: </span><a href="/en/vhosts/mass.html" title="English"> en </a> | 308<a href="/fr/vhosts/mass.html" hreflang="fr" rel="alternate" title="Fran�ais"> fr </a> | 309<a href="/ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> | 310<a href="/tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="T�rk�e"> tr </a></p> 311</div><div class="top"><a href="#page-header"><img src="/images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> 312<script type="text/javascript"><!--//--><![CDATA[//><!-- 313var comments_shortname = 'httpd'; 314var comments_identifier = 'http://httpd.apache.org/docs/2.4/vhosts/mass.html'; 315(function(w, d) { 316 if (w.location.hostname.toLowerCase() == "httpd.apache.org") { 317 d.write('<div id="comments_thread"><\/div>'); 318 var s = d.createElement('script'); 319 s.type = 'text/javascript'; 320 s.async = true; 321 s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; 322 (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); 323 } 324 else { 325 d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); 326 } 327})(window, document); 328//--><!]]></script></div><div id="footer"> 329<p class="apache">Copyright 2014 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> 330<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- 331if (typeof(prettyPrint) !== 'undefined') { 332 prettyPrint(); 333} 334//--><!]]></script> 335</body></html>
