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
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" />
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.0</p>
16 <img alt="" src="../images/feather.gif" /></div>
17 <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
19 <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.0</a> > <a href="./">Virtual Hosts</a></div><div id="page-content"><div id="preamble"><h1>Dynamically Configured Mass Virtual Hosting</h1>
21 <p><span>Available Languages: </span><a href="../en/vhosts/mass.html" title="English"> en </a> |
22 <a href="../ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
23 <a href="../tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
27 <p>This document describes how to efficiently serve an
28 arbitrary number of virtual hosts with the Apache httpd webserver.
32 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#motivation">Motivation</a></li>
33 <li><img alt="" src="../images/down.gif" /> <a href="#overview">Overview</a></li>
34 <li><img alt="" src="../images/down.gif" /> <a href="#simple">Simple Dynamic Virtual Hosts</a></li>
35 <li><img alt="" src="../images/down.gif" /> <a href="#homepages">A Virtually Hosted Homepages System</a></li>
36 <li><img alt="" src="../images/down.gif" /> <a href="#combinations">Using Multiple Virtual
37 Hosting Systems on the Same Server</a></li>
38 <li><img alt="" src="../images/down.gif" /> <a href="#ipbased">More Efficient IP-Based Virtual Hosting</a></li>
39 <li><img alt="" src="../images/down.gif" /> <a href="#simple.rewrite">Simple Dynamic
40 Virtual Hosts Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></a></li>
41 <li><img alt="" src="../images/down.gif" /> <a href="#homepages.rewrite">A
42 Homepages System Using <code>mod_rewrite</code></a></li>
43 <li><img alt="" src="../images/down.gif" /> <a href="#xtra-conf">Using a Separate Virtual
44 Host Configuration File</a></li>
46 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
48 <h2><a name="motivation" id="motivation">Motivation</a></h2>
50 <p>The techniques described here are of interest if your
51 <code>httpd.conf</code> contains many
52 <code><VirtualHost></code> sections that are
53 substantially the same, for example:</p>
55 <div class="example"><p><code>
56 NameVirtualHost 111.22.33.44<br />
57 <VirtualHost 111.22.33.44><br />
59 ServerName www.customer-1.com<br />
60 DocumentRoot /www/hosts/www.customer-1.com/docs<br />
61 ScriptAlias /cgi-bin/ /www/hosts/www.customer-1.com/cgi-bin<br />
63 </VirtualHost><br />
64 <VirtualHost 111.22.33.44><br />
66 ServerName www.customer-2.com<br />
67 DocumentRoot /www/hosts/www.customer-2.com/docs<br />
68 ScriptAlias /cgi-bin/ /www/hosts/www.customer-2.com/cgi-bin<br />
70 </VirtualHost><br />
71 # blah blah blah<br />
72 <VirtualHost 111.22.33.44><br />
74 ServerName www.customer-N.com<br />
75 DocumentRoot /www/hosts/www.customer-N.com/docs<br />
76 ScriptAlias /cgi-bin/ /www/hosts/www.customer-N.com/cgi-bin<br />
81 <p>The basic idea is to replace all of the static
82 <code><VirtualHost></code> configurations with a mechanism
83 that works them out dynamically. This has a number of
87 <li>Your configuration file is smaller, so Apache starts
88 more quickly and uses less memory.</li>
90 <li>Adding virtual hosts is simply a matter of creating the
91 appropriate directories in the filesystem and entries in the
92 DNS - you don't need to reconfigure or restart Apache.</li>
95 <p>The main disadvantage is that you cannot have a different log file for
96 each virtual host; however, if you have many virtual hosts, doing
97 this can be a bad idea anyway, because of the number of file
98 descriptors needed. It is better to log to a pipe or a fifo, and arrange for
99 the process at the other end to distribute the logs to the customers.
100 (This can also be used to accumulate statistics, etc.).</p>
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>
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 2.0. Alternatively, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> can be used.
113 Both of these modules are disabled by default; you must enable
114 one of them when configuring and building Apache if you want to
115 use this technique.</p>
117 <p>A couple of things need to be `faked' to make the dynamic
118 virtual host look like a normal one. The most important is the
119 server name, which is used by Apache to generate
120 self-referential URLs etc. It is configured with the
121 <code>ServerName</code> directive, and it is available to CGIs
122 via the <code>SERVER_NAME</code> environment variable. The
123 actual value used at run time is controlled by the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code>
124 setting. With <code>UseCanonicalName Off</code>, the server name
125 is taken from the contents of the <code>Host:</code> header in the
126 request. With <code>UseCanonicalName DNS</code>, it is taken from a
127 reverse DNS lookup of the virtual host's IP address. The former
128 setting is used for name-based dynamic virtual hosting, and the
129 latter is used for IP-based hosting. If Apache cannot work out
130 the server name because there is no <code>Host:</code> header,
131 or the DNS lookup fails, then the value configured with
132 <code>ServerName</code> is used instead.</p>
134 <p>The other thing to `fake' is the document root (configured
135 with <code>DocumentRoot</code> and available to CGIs via the
136 <code>DOCUMENT_ROOT</code> environment variable). In a normal
137 configuration, this is used by the core module when
138 mapping URIs to filenames, but when the server is configured to
139 do dynamic virtual hosting, that job must be taken over by another
140 module (either <code>mod_vhost_alias</code> or
141 <code>mod_rewrite</code>), which has a different way of doing
142 the mapping. Neither of these modules is responsible for
143 setting the <code>DOCUMENT_ROOT</code> environment variable so
144 if any CGIs or SSI documents make use of it, they will get a
145 misleading value.</p>
147 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
148 <div class="section">
149 <h2><a name="simple" id="simple">Simple Dynamic Virtual Hosts</a></h2>
151 <p>This extract from <code>httpd.conf</code> implements the
152 virtual host arrangement outlined in the <a href="#motivation">Motivation</a> section above, but in a
153 generic fashion using <code>mod_vhost_alias</code>.</p>
155 <div class="example"><p><code>
156 # get the server name from the Host: header<br />
157 UseCanonicalName Off<br />
159 # this log format can be split per-virtual-host based on the first field<br />
160 LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br />
161 CustomLog logs/access_log vcommon<br />
163 # include the server name in the filenames used to satisfy requests<br />
164 VirtualDocumentRoot /www/hosts/%0/docs<br />
165 VirtualScriptAlias /www/hosts/%0/cgi-bin
168 <p>This configuration can be changed into an IP-based virtual
169 hosting solution by just turning <code>UseCanonicalName
170 Off</code> into <code>UseCanonicalName DNS</code>. The server
171 name that is inserted into the filename is then derived from
172 the IP address of the virtual host.</p>
174 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
175 <div class="section">
176 <h2><a name="homepages" id="homepages">A Virtually Hosted Homepages System</a></h2>
178 <p>This is an adjustment of the above system, tailored for an
179 ISP's homepages server. Using a slightly more complicated
180 configuration, we can select substrings of the server name to
181 use in the filename so that, for example, the documents for
182 <code>www.user.isp.com</code> are found in
183 <code>/home/user/</code>. It uses a single <code>cgi-bin</code>
184 directory instead of one per virtual host.</p>
186 <div class="example"><p><code>
187 # all the preliminary stuff is the same as above, then<br />
189 # include part of the server name in the filenames<br />
190 VirtualDocumentRoot /www/hosts/%2/docs<br />
192 # single cgi-bin directory<br />
193 ScriptAlias /cgi-bin/ /www/std-cgi/<br />
196 <p>There are examples of more complicated
197 <code>VirtualDocumentRoot</code> settings in the
198 <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> documentation.</p>
200 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
201 <div class="section">
202 <h2><a name="combinations" id="combinations">Using Multiple Virtual
203 Hosting Systems on the Same Server</a></h2>
205 <p>With more complicated setups, you can use Apache's normal
206 <code><VirtualHost></code> directives to control the
207 scope of the various virtual hosting configurations. For
208 example, you could have one IP address for general customers' homepages,
209 and another for commercial customers, with the following setup.
210 This can, of course, be combined with conventional
211 <code><VirtualHost></code> configuration sections.</p>
213 <div class="example"><p><code>
214 UseCanonicalName Off<br />
216 LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br />
218 <Directory /www/commercial><br />
219 <span class="indent">
220 Options FollowSymLinks<br />
221 AllowOverride All<br />
223 </Directory><br />
225 <Directory /www/homepages><br />
226 <span class="indent">
227 Options FollowSymLinks<br />
228 AllowOverride None<br />
230 </Directory><br />
232 <VirtualHost 111.22.33.44><br />
233 <span class="indent">
234 ServerName www.commercial.isp.com<br />
236 CustomLog logs/access_log.commercial vcommon<br />
238 VirtualDocumentRoot /www/commercial/%0/docs<br />
239 VirtualScriptAlias /www/commercial/%0/cgi-bin<br />
241 </VirtualHost><br />
243 <VirtualHost 111.22.33.45><br />
244 <span class="indent">
245 ServerName www.homepages.isp.com<br />
247 CustomLog logs/access_log.homepages vcommon<br />
249 VirtualDocumentRoot /www/homepages/%0/docs<br />
250 ScriptAlias /cgi-bin/ /www/std-cgi/<br />
255 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
256 <div class="section">
257 <h2><a name="ipbased" id="ipbased">More Efficient IP-Based Virtual Hosting</a></h2>
259 <p>The configuration changes suggested to turn <a href="#simple">the first
260 example</a> into an IP-based virtual hosting setup result in
261 a rather inefficient setup. A new DNS lookup is required for every
262 request. To avoid this overhead, the filesystem can be arranged to
263 correspond to the IP addresses, instead of to the host names, thereby
264 negating the need for a DNS lookup. Logging will also have to be adjusted
265 to fit this system.</p>
267 <div class="example"><p><code>
268 # get the server name from the reverse DNS of the IP address<br />
269 UseCanonicalName DNS<br />
271 # include the IP address in the logs so they may be split<br />
272 LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon<br />
273 CustomLog logs/access_log vcommon<br />
275 # include the IP address in the filenames<br />
276 VirtualDocumentRootIP /www/hosts/%0/docs<br />
277 VirtualScriptAliasIP /www/hosts/%0/cgi-bin<br />
280 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
281 <div class="section">
282 <h2><a name="simple.rewrite" id="simple.rewrite">Simple Dynamic
283 Virtual Hosts Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code></a></h2>
285 <p>This extract from <code>httpd.conf</code> does the same
286 thing as <a href="#simple">the first example</a>. The first
287 half is very similar to the corresponding part above, except for
288 some changes, required for backward compatibility and to make the
289 <code>mod_rewrite</code> part work properly; the second half
290 configures <code>mod_rewrite</code> to do the actual work.</p>
292 <p>There are a couple of especially tricky bits: by default,
293 <code>mod_rewrite</code> runs before other URI translation
294 modules (<code>mod_alias</code> etc.) - so if you wish to use these modules, <code>mod_rewrite</code> must be configured to accommodate
295 them. Also, some magic is required to do a
296 per-dynamic-virtual-host equivalent of
297 <code>ScriptAlias</code>.</p>
299 <div class="example"><p><code>
300 # get the server name from the Host: header<br />
301 UseCanonicalName Off<br />
303 # splittable logs<br />
304 LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
305 CustomLog logs/access_log vcommon<br />
307 <Directory /www/hosts><br />
308 <span class="indent">
309 # ExecCGI is needed here because we can't force<br />
310 # CGI execution in the way that ScriptAlias does<br />
311 Options FollowSymLinks ExecCGI<br />
313 </Directory><br />
315 # now for the hard bit<br />
317 RewriteEngine On<br />
319 # a ServerName derived from a Host: header may be any case at all<br />
320 RewriteMap lowercase int:tolower<br />
322 ## deal with normal documents first:<br />
323 # allow Alias /icons/ to work - repeat for other aliases<br />
324 RewriteCond %{REQUEST_URI} !^/icons/<br />
325 # allow CGIs to work<br />
326 RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
328 RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
330 ## and now deal with CGIs - we have to force a MIME type<br />
331 RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
332 RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]<br />
337 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
338 <div class="section">
339 <h2><a name="homepages.rewrite" id="homepages.rewrite">A
340 Homepages System Using <code>mod_rewrite</code></a></h2>
342 <p>This does the same thing as <a href="#homepages">the second
345 <div class="example"><p><code>
346 RewriteEngine on<br />
348 RewriteMap lowercase int:tolower<br />
350 # allow CGIs to work<br />
351 RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
353 # check the hostname is right so that the RewriteRule works<br />
354 RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$<br />
356 # concatenate the virtual host name onto the start of the URI<br />
357 # the [C] means do the next rewrite on the result of this one<br />
358 RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]<br />
360 # now create the real file name<br />
361 RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2<br />
363 # define the global CGI directory<br />
364 ScriptAlias /cgi-bin/ /www/std-cgi/
367 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
368 <div class="section">
369 <h2><a name="xtra-conf" id="xtra-conf">Using a Separate Virtual
370 Host Configuration File</a></h2>
372 <p>This arrangement uses more advanced <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
373 features to work out the translation from virtual host to document
374 root, from a separate configuration file. This provides more
375 flexibility, but requires more complicated configuration.</p>
377 <p>The <code>vhost.map</code> file should look something like
380 <div class="example"><p><code>
381 www.customer-1.com /www/customers/1<br />
382 www.customer-2.com /www/customers/2<br />
384 www.customer-N.com /www/customers/N<br />
387 <p>The <code>httpd.conf</code> should contain the following:</p>
389 <div class="example"><p><code>
390 RewriteEngine on<br />
392 RewriteMap lowercase int:tolower<br />
394 # define the map file<br />
395 RewriteMap vhost txt:/www/conf/vhost.map<br />
397 # deal with aliases as above<br />
398 RewriteCond %{REQUEST_URI} !^/icons/<br />
399 RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
400 RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
401 # this does the file-based remap<br />
402 RewriteCond ${vhost:%1} ^(/.*)$<br />
403 RewriteRule ^/(.*)$ %1/docs/$1<br />
405 RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
406 RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
407 RewriteCond ${vhost:%1} ^(/.*)$<br />
408 RewriteRule ^/(.*)$ %1/cgi-bin/$1 [T=application/x-httpd-cgi]
412 <div class="bottomlang">
413 <p><span>Available Languages: </span><a href="../en/vhosts/mass.html" title="English"> en </a> |
414 <a href="../ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean"> ko </a> |
415 <a href="../tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="Türkçe"> tr </a></p>
416 </div><div id="footer">
417 <p class="apache">Copyright 2009 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>
418 <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>