vhosts.xml revision 369082e032313641ad20a7c588d0d0922db6aaa9
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<!-- $LastChangedRevision$ -->
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Licensed to the Apache Software Foundation (ASF) under one or more
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding contributor license agreements. See the NOTICE file distributed with
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding this work for additional information regarding copyright ownership.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding The ASF licenses this file to You under the Apache License, Version 2.0
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding (the "License"); you may not use this file except in compliance with
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding the License. You may obtain a copy of the License at
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Unless required by applicable law or agreed to in writing, software
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding distributed under the License is distributed on an "AS IS" BASIS,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding See the License for the specific language governing permissions and
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding limitations under the License.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<title>Dynamic mass virtual hosts with mod_rewrite</title>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<p>This document supplements the <module>mod_rewrite</module>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldinghow you can use <module>mod_rewrite</module> to create dynamically
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingconfigured virtual hosts.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<note type="warning">mod_rewrite is not the best way to configure
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingvirtual hosts. You should first consider the <a
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldinghref="/vhosts/mass.html">alternatives</a> before resorting to
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingmod_rewrite. See also the "<a href="avoid.html#vhosts">how to avoid
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="access.html">Controlling access</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<!--<seealso><a href="vhosts.html">Virtual hosts</a></seealso>-->
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="proxy.html">Proxying</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="rewritemap.html">RewriteMap</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <title>Virtual Hosts For Arbitrary Hostnames</title>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>We want to automatically create a virtual host for every hostname
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding which resolves in our domain, without having to create
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding new VirtualHost sections.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>In this recipe, we assume that we'll be using the hostname
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <code>www.<strong>SITE</strong>.example.com</code> for each
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding user, and serve their content out of
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteEngine on
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteMap lowercase int:tolower
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{lowercase:%{<strong>HTTP_HOST</strong>}} ^www\.<strong>([^.]+)</strong>\.example\.com$
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <note type="warning">You will need to take care of the DNS
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding resolution - Apache does
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding not handle name resolution. You'll need either to create CNAME
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding records for each hostname, or a DNS wildcard record. Creating DNS
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding records is beyond the scope of this document.</note>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<p>The internal <code>tolower</code> RewriteMap directive is used to
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingensure that the hostnames being used are all lowercase, so that there is
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingno ambiguity in the directory structure which must be created.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingmodule="mod_rewrite">RewriteCond</directive> are captured into the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingbackreferences <code>%1</code>, <code>%2</code>, etc, while parentheses
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingused in <directive module="mod_rewrite">RewriteRule</directive> are
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingcaptured into the backreferences <code>$1</code>, <code>$2</code>,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingAs with many techniques discussed in this document, mod_rewrite really
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingisn't the best way to accomplish this task. You should, instead,
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingconsider using <module>mod_vhost_alias</module> instead, as it will much
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingmore gracefully handle anything beyond serving static files, such as any
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingdynamic content, and Alias resolution.
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Virtual Hosts Using <module>mod_rewrite</module></title>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>This extract from <code>httpd.conf</code> does the same
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding thing as <a href="#simple">the first example</a>. The first
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding half is very similar to the corresponding part above, except for
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding some changes, required for backward compatibility and to make the
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <code>mod_rewrite</code> part work properly; the second half
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding configures <code>mod_rewrite</code> to do the actual work.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>Because <code>mod_rewrite</code> runs before other URI translation
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding modules (e.g., <code>mod_alias</code>), <code>mod_rewrite</code> must
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding be told to explicitly ignore any URLs that would have been handled
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding by those modules. And, because these rules would otherwise bypass
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding any <code>ScriptAlias</code> directives, we must have
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <code>mod_rewrite</code> explicitly enact those mappings.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# get the server name from the Host: header<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingUseCanonicalName Off<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# splittable logs<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingLogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding # ExecCGI is needed here because we can't force<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding # CGI execution in the way that ScriptAlias does<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding Options FollowSymLinks ExecCGI<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding</Directory><br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteEngine On<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# a ServerName derived from a Host: header may be any case at all<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteMap lowercase int:tolower<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding## deal with normal documents first:<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# allow Alias /icons/ to work - repeat for other aliases<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} !^/icons/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# allow CGIs to work<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# do the magic<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/docs/$1<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding## and now deal with CGIs - we have to force a handler<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [H=cgi-script]<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding<section id="xtra-conf"><title>Using a Separate Virtual Host Configuration File</title>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>This arrangement uses more advanced <module>mod_rewrite</module>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding features to work out the translation from virtual host to document
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding root, from a separate configuration file. This provides more
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding flexibility, but requires more complicated configuration.</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>The <code>vhost.map</code> file should look something like
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding <p>The <code>httpd.conf</code> should contain the following:</p>
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteEngine on<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteMap lowercase int:tolower<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# define the map file<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# deal with aliases as above<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} !^/icons/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} !^/cgi-bin/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding# this does the file-based remap<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond ${vhost:%1} ^(/.*)$<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond %{REQUEST_URI} ^/cgi-bin/<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond ${lowercase:%{SERVER_NAME}} ^(.+)$<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fieldingRewriteCond ${vhost:%1} ^(/.*)$<br />
09fe0b69d3d1e8c8041c9ce99ee77b8b44b5e3b1fielding</manualpage>