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.2</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.2</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></p>
26
<p>This document describes how to efficiently serve an
27
arbitrary number of virtual hosts with Apache.
31
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#motivation">Motivation</a></li>
32
<li><img alt="" src="../images/down.gif" /> <a href="#overview">Overview</a></li>
33
<li><img alt="" src="../images/down.gif" /> <a href="#simple">Simple dynamic virtual hosts</a></li>
34
<li><img alt="" src="../images/down.gif" /> <a href="#homepages">A virtually hosted homepages system</a></li>
35
<li><img alt="" src="../images/down.gif" /> <a href="#combinations">Using more than
36
one virtual hosting system on the same server</a></li>
37
<li><img alt="" src="../images/down.gif" /> <a href="#ipbased">More efficient IP-based virtual hosting</a></li>
38
<li><img alt="" src="../images/down.gif" /> <a href="#oldversion">Using older versions of Apache</a></li>
39
<li><img alt="" src="../images/down.gif" /> <a href="#simple.rewrite">Simple dynamic
40
virtual hosts using <code>mod_rewrite</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> configuration with a mechanism
83
that works it out dynamically. This has a number of
87
<li>Your configuration file is smaller so Apache starts
88
faster 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
96
log file for each virtual host; however if you have very many
97
virtual hosts then doing this is dubious anyway because it eats
98
file descriptors. It is better to log to a pipe or a fifo and
99
arrange for the process at the other end to distribute the logs
100
to the customers (it can also 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
is based on automatically inserting this information into the
110
pathname of the file that is used to satisfy the request. This
111
is done most easily using <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code>,
112
but if you are using a version of Apache up to 1.3.6 then you
113
must use <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.
114
Both of these modules are disabled by default; you must enable
115
one of them when configuring and building Apache if you want to
116
use this technique.</p>
118
<p>A couple of things need to be `faked' to make the dynamic
119
virtual host look like a normal one. The most important is the
120
server name which is used by Apache to generate
121
self-referential URLs, etc. It is configured with the
122
<code>ServerName</code> directive, and it is available to CGIs
123
via the <code>SERVER_NAME</code> environment variable. The
124
actual value used at run time is controlled by the <code class="directive"><a href="../mod/core.html#usecanonicalname">UseCanonicalName</a></code>
125
setting. With <code>UseCanonicalName Off</code> the server name
126
comes from the contents of the <code>Host:</code> header in the
127
request. With <code>UseCanonicalName DNS</code> it comes from a
128
reverse DNS lookup of the virtual host's IP address. The former
129
setting is used for name-based dynamic virtual hosting, and the
130
latter is used for IP-based hosting. If Apache cannot work out
131
the server name because there is no <code>Host:</code> header
132
or the DNS lookup fails then the value configured with
133
<code>ServerName</code> is used instead.</p>
135
<p>The other thing to `fake' is the document root (configured
136
with <code>DocumentRoot</code> and available to CGIs via the
137
<code>DOCUMENT_ROOT</code> environment variable). In a normal
138
configuration this setting is used by the core module when
139
mapping URIs to filenames, but when the server is configured to
140
do dynamic virtual hosting that job is taken over by another
141
module (either <code>mod_vhost_alias</code> or
142
<code>mod_rewrite</code>) which has a different way of doing
143
the mapping. Neither of these modules is responsible for
144
setting the <code>DOCUMENT_ROOT</code> environment variable so
145
if any CGIs or SSI documents make use of it they will get a
146
misleading value.</p>
148
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
149
<div class="section">
150
<h2><a name="simple" id="simple">Simple dynamic virtual hosts</a></h2>
152
<p>This extract from <code>httpd.conf</code> implements the
153
virtual host arrangement outlined in the <a href="#motivation">Motivation</a> section above, but in a
154
generic fashion using <code>mod_vhost_alias</code>.</p>
156
<div class="example"><p><code>
157
# get the server name from the Host: header<br />
158
UseCanonicalName Off<br />
160
# this log format can be split per-virtual-host based on the first field<br />
161
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br />
162
CustomLog logs/access_log vcommon<br />
164
# include the server name in the filenames used to satisfy requests<br />
165
VirtualDocumentRoot /www/hosts/%0/docs<br />
166
VirtualScriptAlias /www/hosts/%0/cgi-bin
169
<p>This configuration can be changed into an IP-based virtual
170
hosting solution by just turning <code>UseCanonicalName
171
Off</code> into <code>UseCanonicalName DNS</code>. The server
172
name that is inserted into the filename is then derived from
173
the IP address of the virtual host.</p>
175
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
176
<div class="section">
177
<h2><a name="homepages" id="homepages">A virtually hosted homepages system</a></h2>
179
<p>This is an adjustment of the above system tailored for an
180
ISP's homepages server. Using a slightly more complicated
181
configuration we can select substrings of the server name to
182
use in the filename so that e.g. the documents for
183
<code>www.user.isp.com</code> are found in
184
<code>/home/user/</code>. It uses a single <code>cgi-bin</code>
185
directory instead of one per virtual host.</p>
187
<div class="example"><p><code>
188
# all the preliminary stuff is the same as above, then<br />
190
# include part of the server name in the filenames<br />
191
VirtualDocumentRoot /www/hosts/%2/docs<br />
193
# single cgi-bin directory<br />
194
ScriptAlias /cgi-bin/ /www/std-cgi/<br />
197
<p>There are examples of more complicated
198
<code>VirtualDocumentRoot</code> settings in the
199
<code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> documentation.</p>
201
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
202
<div class="section">
203
<h2><a name="combinations" id="combinations">Using more than
204
one virtual hosting system on the same server</a></h2>
206
<p>With more complicated setups you can use Apache's normal
207
<code><VirtualHost></code> directives to control the
208
scope of the various virtual hosting configurations. For
209
example, you could have one IP address for homepages customers
210
and another for commercial customers with the following setup.
211
This can of course be combined with conventional
212
<code><VirtualHost></code> configuration sections.</p>
214
<div class="example"><p><code>
215
UseCanonicalName Off<br />
217
LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br />
219
<Directory /www/commercial><br />
220
<span class="indent">
221
Options FollowSymLinks<br />
222
AllowOverride All<br />
224
</Directory><br />
226
<Directory /www/homepages><br />
227
<span class="indent">
228
Options FollowSymLinks<br />
229
AllowOverride None<br />
231
</Directory><br />
233
<VirtualHost 111.22.33.44><br />
234
<span class="indent">
235
ServerName www.commercial.isp.com<br />
237
CustomLog logs/access_log.commercial vcommon<br />
239
VirtualDocumentRoot /www/commercial/%0/docs<br />
240
VirtualScriptAlias /www/commercial/%0/cgi-bin<br />
242
</VirtualHost><br />
244
<VirtualHost 111.22.33.45><br />
245
<span class="indent">
246
ServerName www.homepages.isp.com<br />
248
CustomLog logs/access_log.homepages vcommon<br />
250
VirtualDocumentRoot /www/homepages/%0/docs<br />
251
ScriptAlias /cgi-bin/ /www/std-cgi/<br />
256
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
257
<div class="section">
258
<h2><a name="ipbased" id="ipbased">More efficient IP-based virtual hosting</a></h2>
260
<p>After <a href="#simple">the first example</a> I noted that
261
it is easy to turn it into an IP-based virtual hosting setup.
262
Unfortunately that configuration is not very efficient because
263
it requires a DNS lookup for every request. This can be avoided
264
by laying out the filesystem according to the IP addresses
265
themselves rather than the corresponding names and changing the
266
logging similarly. Apache will then usually not need to work
267
out the server name and so incur a DNS lookup.</p>
269
<div class="example"><p><code>
270
# get the server name from the reverse DNS of the IP address<br />
271
UseCanonicalName DNS<br />
273
# include the IP address in the logs so they may be split<br />
274
LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon<br />
275
CustomLog logs/access_log vcommon<br />
277
# include the IP address in the filenames<br />
278
VirtualDocumentRootIP /www/hosts/%0/docs<br />
279
VirtualScriptAliasIP /www/hosts/%0/cgi-bin<br />
282
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
283
<div class="section">
284
<h2><a name="oldversion" id="oldversion">Using older versions of Apache</a></h2>
286
<p>The examples above rely on <code>mod_vhost_alias</code>
287
which appeared after version 1.3.6. If you are using a version
288
of Apache without <code>mod_vhost_alias</code> then you can
289
implement this technique with <code>mod_rewrite</code> as
290
illustrated below, but only for Host:-header-based virtual
293
<p>In addition there are some things to beware of with logging.
294
Apache 1.3.6 is the first version to include the
295
<code>%V</code> log format directive; in versions 1.3.0 - 1.3.3
296
the <code>%v</code> option did what <code>%V</code> does;
297
version 1.3.4 has no equivalent. In all these versions of
298
Apache the <code>UseCanonicalName</code> directive can appear
299
in <code>.htaccess</code> files which means that customers can
300
cause the wrong thing to be logged. Therefore the best thing to
301
do is use the <code>%{Host}i</code> directive which logs the
302
<code>Host:</code> header directly; note that this may include
303
<code>:port</code> on the end which is not the case for
306
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
307
<div class="section">
308
<h2><a name="simple.rewrite" id="simple.rewrite">Simple dynamic
309
virtual hosts using <code>mod_rewrite</code></a></h2>
311
<p>This extract from <code>httpd.conf</code> does the same
312
thing as <a href="#simple">the first example</a>. The first
313
half is very similar to the corresponding part above but with
314
some changes for backward compatibility and to make the
315
<code>mod_rewrite</code> part work properly; the second half
316
configures <code>mod_rewrite</code> to do the actual work.</p>
318
<p>There are a couple of especially tricky bits: By default,
319
<code>mod_rewrite</code> runs before the other URI translation
320
modules (<code>mod_alias</code> etc.) so if they are used then
321
<code>mod_rewrite</code> must be configured to accommodate
322
them. Also, some magic must be performed to do a
323
per-dynamic-virtual-host equivalent of
324
<code>ScriptAlias</code>.</p>
326
<div class="example"><p><code>
327
# get the server name from the Host: header<br />
328
UseCanonicalName Off<br />
330
# splittable logs<br />
331
LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
332
CustomLog logs/access_log vcommon<br />
334
<Directory /www/hosts><br />
335
<span class="indent">
336
# ExecCGI is needed here because we can't force<br />
337
# CGI execution in the way that ScriptAlias does<br />
338
Options FollowSymLinks ExecCGI<br />
340
</Directory><br />
342
# now for the hard bit<br />
344
RewriteEngine On<br />
346
# a ServerName derived from a Host: header may be any case at all<br />
347
RewriteMap lowercase int:tolower<br />
349
## deal with normal documents first:<br />
350
# allow Alias /icons/ to work - repeat for other aliases<br />
351
RewriteCond %{REQUEST_URI} !^/icons/<br />
352
# allow CGIs to work<br />
353
RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
355
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
357
## and now deal with CGIs - we have to force a MIME type<br />
358
RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
359
RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi]<br />
364
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
365
<div class="section">
366
<h2><a name="homepages.rewrite" id="homepages.rewrite">A
367
homepages system using <code>mod_rewrite</code></a></h2>
369
<p>This does the same thing as <a href="#homepages">the second
372
<div class="example"><p><code>
373
RewriteEngine on<br />
375
RewriteMap lowercase int:tolower<br />
377
# allow CGIs to work<br />
378
RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
380
# check the hostname is right so that the RewriteRule works<br />
381
RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$<br />
383
# concatenate the virtual host name onto the start of the URI<br />
384
# the [C] means do the next rewrite on the result of this one<br />
385
RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C]<br />
387
# now create the real file name<br />
388
RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2<br />
390
# define the global CGI directory<br />
391
ScriptAlias /cgi-bin/ /www/std-cgi/
394
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
395
<div class="section">
396
<h2><a name="xtra-conf" id="xtra-conf">Using a separate virtual
397
host configuration file</a></h2>
399
<p>This arrangement uses more advanced <code>mod_rewrite</code>
400
features to get the translation from virtual host to document
401
root from a separate configuration file. This provides more
402
flexibility but requires more complicated configuration.</p>
404
<p>The <code>vhost.map</code> file contains something like
407
<div class="example"><p><code>
408
www.customer-1.com /www/customers/1<br />
409
www.customer-2.com /www/customers/2<br />
411
www.customer-N.com /www/customers/N<br />
414
<p>The <code>http.conf</code> contains this:</p>
416
<div class="example"><p><code>
417
RewriteEngine on<br />
419
RewriteMap lowercase int:tolower<br />
421
# define the map file<br />
422
RewriteMap vhost txt:/www/conf/vhost.map<br />
424
# deal with aliases as above<br />
425
RewriteCond %{REQUEST_URI} !^/icons/<br />
426
RewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
427
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
428
# this does the file-based remap<br />
429
RewriteCond ${vhost:%1} ^(/.*)$<br />
430
RewriteRule ^/(.*)$ %1/docs/$1<br />
432
RewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
433
RewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
434
RewriteCond ${vhost:%1} ^(/.*)$<br />
435
RewriteRule ^/(.*)$ %1/cgi-bin/$1
439
<div class="bottomlang">
440
<p><span>Available Languages: </span><a href="../en/vhosts/mass.html" title="English"> en </a> |
441
<a href="../ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean"> ko </a></p>
442
</div><div id="footer">
443
<p class="apache">Copyright 2006 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>
444
<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>
b'\\ No newline at end of file'
added
removed
docs/manual/vhosts/mass.html.en
