rubbos/app/apache2/manual/vhosts/mass.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>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="&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/">Documentation</a> &gt; <a href="../">Version 2.0</a> &gt; <a href="./">Virtual Hosts</a></div><div id="page-content"><div id="preamble"><h1>Dynamically Configured Mass Virtual Hosting</h1>
  20 <div class="toplang">
  21 <p><span>Available Languages: </span><a href="../en/vhosts/mass.html" title="English">&nbsp;en&nbsp;</a> |
  22 <a href="../ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
  23 <a href="../tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</a></p>
  24 </div>
  25
  26
  27     <p>This document describes how to efficiently serve an
  28     arbitrary number of virtual hosts with the Apache httpd webserver.
  29     </p>
  30
  31 </div>
  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>
  45 </ul></div>
  46 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  47 <div class="section">
  48 <h2><a name="motivation" id="motivation">Motivation</a></h2>
  49
  50     <p>The techniques described here are of interest if your
  51     <code>httpd.conf</code> contains many
  52     <code>&lt;VirtualHost&gt;</code> sections that are
  53     substantially the same, for example:</p>
  54
  55 <div class="example"><p><code>
  56 NameVirtualHost 111.22.33.44<br />
  57 &lt;VirtualHost 111.22.33.44&gt;<br />
  58 <span class="indent">
  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 />
  62 </span>
  63 &lt;/VirtualHost&gt;<br />
  64 &lt;VirtualHost 111.22.33.44&gt;<br />
  65 <span class="indent">
  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 />
  69 </span>
  70 &lt;/VirtualHost&gt;<br />
  71 # blah blah blah<br />
  72 &lt;VirtualHost 111.22.33.44&gt;<br />
  73 <span class="indent">
  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 />
  77 </span>
  78 &lt;/VirtualHost&gt;
  79 </code></p></div>
  80
  81     <p>The basic idea is to replace all of the static
  82     <code>&lt;VirtualHost&gt;</code> configurations with a mechanism
  83     that works them out dynamically. This has a number of
  84     advantages:</p>
  85
  86     <ol>
  87       <li>Your configuration file is smaller, so Apache starts
  88       more quickly and uses less memory.</li>
  89
  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>
  93     </ol>
  94
  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>
 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 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>
 116
 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>
 133
 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>
 146
 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>
 150
 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>
 154
 155 <div class="example"><p><code>
 156 # get the server name from the Host: header<br />
 157 UseCanonicalName Off<br />
 158 <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 />
 162 <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
 166 </code></p></div>
 167
 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>
 173
 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>
 177
 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>
 185
 186 <div class="example"><p><code>
 187 # all the preliminary stuff is the same as above, then<br />
 188 <br />
 189 # include part of the server name in the filenames<br />
 190 VirtualDocumentRoot /www/hosts/%2/docs<br />
 191 <br />
 192 # single cgi-bin directory<br />
 193 ScriptAlias  /cgi-bin/  /www/std-cgi/<br />
 194 </code></p></div>
 195
 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>
 199
 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>
 204
 205     <p>With more complicated setups, you can use Apache's normal
 206     <code>&lt;VirtualHost&gt;</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>&lt;VirtualHost&gt;</code> configuration sections.</p>
 212
 213 <div class="example"><p><code>
 214 UseCanonicalName Off<br />
 215 <br />
 216 LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon<br />
 217 <br />
 218 &lt;Directory /www/commercial&gt;<br />
 219 <span class="indent">
 220     Options FollowSymLinks<br />
 221     AllowOverride All<br />
 222 </span>
 223 &lt;/Directory&gt;<br />
 224 <br />
 225 &lt;Directory /www/homepages&gt;<br />
 226 <span class="indent">
 227     Options FollowSymLinks<br />
 228     AllowOverride None<br />
 229 </span>
 230 &lt;/Directory&gt;<br />
 231 <br />
 232 &lt;VirtualHost 111.22.33.44&gt;<br />
 233 <span class="indent">
 234     ServerName www.commercial.isp.com<br />
 235     <br />
 236     CustomLog logs/access_log.commercial vcommon<br />
 237     <br />
 238     VirtualDocumentRoot /www/commercial/%0/docs<br />
 239     VirtualScriptAlias  /www/commercial/%0/cgi-bin<br />
 240 </span>
 241 &lt;/VirtualHost&gt;<br />
 242 <br />
 243 &lt;VirtualHost 111.22.33.45&gt;<br />
 244 <span class="indent">
 245     ServerName www.homepages.isp.com<br />
 246     <br />
 247     CustomLog logs/access_log.homepages vcommon<br />
 248     <br />
 249     VirtualDocumentRoot /www/homepages/%0/docs<br />
 250     ScriptAlias         /cgi-bin/ /www/std-cgi/<br />
 251 </span>
 252 &lt;/VirtualHost&gt;
 253 </code></p></div>
 254
 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>
 258
 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>
 266
 267 <div class="example"><p><code>
 268 # get the server name from the reverse DNS of the IP address<br />
 269 UseCanonicalName DNS<br />
 270 <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 />
 274 <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 />
 278 </code></p></div>
 279
 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>
 284
 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>
 291
 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>
 298
 299 <div class="example"><p><code>
 300 # get the server name from the Host: header<br />
 301 UseCanonicalName Off<br />
 302 <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 />
 306 <br />
 307 &lt;Directory /www/hosts&gt;<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 />
 312 </span>
 313 &lt;/Directory&gt;<br />
 314 <br />
 315 # now for the hard bit<br />
 316 <br />
 317 RewriteEngine On<br />
 318 <br />
 319 # a ServerName derived from a Host: header may be any case at all<br />
 320 RewriteMap  lowercase  int:tolower<br />
 321 <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 />
 327 # do the magic<br />
 328 RewriteRule  ^/(.*)$  /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
 329 <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 />
 333 <br />
 334 # that's it!
 335 </code></p></div>
 336
 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>
 341
 342     <p>This does the same thing as <a href="#homepages">the second
 343     example</a>.</p>
 344
 345 <div class="example"><p><code>
 346 RewriteEngine on<br />
 347 <br />
 348 RewriteMap   lowercase  int:tolower<br />
 349 <br />
 350 # allow CGIs to work<br />
 351 RewriteCond  %{REQUEST_URI}  !^/cgi-bin/<br />
 352 <br />
 353 # check the hostname is right so that the RewriteRule works<br />
 354 RewriteCond  ${lowercase:%{SERVER_NAME}}  ^www\.[a-z-]+\.isp\.com$<br />
 355 <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 />
 359 <br />
 360 # now create the real file name<br />
 361 RewriteRule  ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2<br />
 362 <br />
 363 # define the global CGI directory<br />
 364 ScriptAlias  /cgi-bin/  /www/std-cgi/
 365 </code></p></div>
 366
 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>
 371
 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>
 376
 377     <p>The <code>vhost.map</code> file should look something like
 378     this:</p>
 379
 380 <div class="example"><p><code>
 381 www.customer-1.com  /www/customers/1<br />
 382 www.customer-2.com  /www/customers/2<br />
 383 # ...<br />
 384 www.customer-N.com  /www/customers/N<br />
 385 </code></p></div>
 386
 387     <p>The <code>httpd.conf</code> should contain the following:</p>
 388
 389 <div class="example"><p><code>
 390 RewriteEngine on<br />
 391 <br />
 392 RewriteMap   lowercase  int:tolower<br />
 393 <br />
 394 # define the map file<br />
 395 RewriteMap   vhost      txt:/www/conf/vhost.map<br />
 396 <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 />
 404 <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]
 409 </code></p></div>
 410
 411 </div></div>
 412 <div class="bottomlang">
 413 <p><span>Available Languages: </span><a href="../en/vhosts/mass.html" title="English">&nbsp;en&nbsp;</a> |
 414 <a href="../ko/vhosts/mass.html" hreflang="ko" rel="alternate" title="Korean">&nbsp;ko&nbsp;</a> |
 415 <a href="../tr/vhosts/mass.html" hreflang="tr" rel="alternate" title="Türkçe">&nbsp;tr&nbsp;</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>
 419 </body></html>