diff options
| author | Jim Jagielski <jim@apache.org> | 1999-06-22 02:51:25 +0200 |
|---|---|---|
| committer | Jim Jagielski <jim@apache.org> | 1999-06-22 02:51:25 +0200 |
| commit | a4929c7ee928f423cfafb3dfd21078f1888e16d1 (patch) | |
| tree | 8021cbaf244b7d0067287380818c6f3ecb0e6a7b /docs | |
| parent | ap_mpm_graceful_stop -> ap_graceful_stop_signalled (diff) | |
| download | apache2-a4929c7ee928f423cfafb3dfd21078f1888e16d1.tar.xz apache2-a4929c7ee928f423cfafb3dfd21078f1888e16d1.zip | |
PR:
Submitted by: Tony Finch <fanf@demon.net>
Reviewed by: Dean, Randy, Jim, Lars, Martin
Obtained from:
Add the new mod_vhost_alias.c modules for better mass-hosting. This
has been used at Demon Internet with excellent results and basically
replaces the "old" method of using mod_rewrite. Big advantage is
that adding new vhosts can be done without restarting the server.
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@83357 13f79535-47bb-0310-9956-ffa450edef68
Diffstat (limited to 'docs')
| -rw-r--r-- | docs/manual/mod/core.html | 9 | ||||
| -rw-r--r-- | docs/manual/mod/index.html | 2 | ||||
| -rw-r--r-- | docs/manual/mod/mod_log_config.html | 1 | ||||
| -rw-r--r-- | docs/manual/mod/mod_rewrite.html | 1 | ||||
| -rw-r--r-- | docs/manual/mod/mod_vhost_alias.html | 311 | ||||
| -rw-r--r-- | docs/manual/vhosts/mass.html | 360 |
6 files changed, 543 insertions, 141 deletions
diff --git a/docs/manual/mod/core.html b/docs/manual/mod/core.html index 148eab5155..d6c99f4386 100644 --- a/docs/manual/mod/core.html +++ b/docs/manual/mod/core.html @@ -3109,8 +3109,7 @@ a packet is sent. <A HREF="directive-dict.html#Default" REL="Help"> <STRONG>Default:</STRONG></A> <CODE>UseCanonicalName on</CODE><BR> <A HREF="directive-dict.html#Context" REL="Help"> -<STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess -<BR> +<STRONG>Context:</STRONG></A> server config, virtual host<BR> <A HREF="directive-dict.html#Override" REL="Help"> <STRONG>Override:</STRONG></A> Options<BR> <A HREF="directive-dict.html#Compatibility" REL="Help"> @@ -3145,6 +3144,12 @@ for <CODE>www</CODE> and once again for <CODE>www.domain.com</CODE>). But if <CODE>UseCanonicalName</CODE> is set off, then Apache will redirect to <CODE>http://www/splat/</CODE>. +<P>There is a third option, <CODE>UseCanonicalName DNS</CODE>, which +is intended for use with mass IP-based virtual hosting to support +ancient clients that do not provide a <CODE>Host:</CODE> header. With +this option Apache does a reverse DNS lookup on the server IP address +that the client connected to in order to work out self-referential URLs. + <P><STRONG>Warning:</STRONG> if CGIs make assumptions about the values of <CODE>SERVER_NAME</CODE> they may be broken by this option. The client is essentially free to give whatever value they want as a hostname. diff --git a/docs/manual/mod/index.html b/docs/manual/mod/index.html index f003071e9f..4da36552fe 100644 --- a/docs/manual/mod/index.html +++ b/docs/manual/mod/index.html @@ -113,6 +113,8 @@ mod_log_config module in Apache 1.2 and up <DD>Generate unique request identifier for every request <DT><A HREF="mod_usertrack.html">mod_usertrack</A> Apache 1.2 and up <DD>User tracking using Cookies (replacement for mod_cookies.c) +<DT><A HREF="mod_vhost_alias.html">mod_vhost_alias</A> Apache 1.3.7 and up +<DD>Support for dynamically configured mass virtual hosting </DL> <!--#include virtual="footer.html" --> diff --git a/docs/manual/mod/mod_log_config.html b/docs/manual/mod/mod_log_config.html index e9bb199a42..dfa21e3f27 100644 --- a/docs/manual/mod/mod_log_config.html +++ b/docs/manual/mod/mod_log_config.html @@ -126,6 +126,7 @@ by the values as follows: %...{FOOBAR}e: The contents of the environment variable FOOBAR %...h: Remote host %...a: Remote IP-address +%...A: Local IP-address %...{Foobar}i: The contents of Foobar: header line(s) in the request sent to the server. %...l: Remote logname (from identd, if supplied) diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index ffd9088e0e..d68f1b8f30 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -1078,6 +1078,7 @@ AUTH_TYPE<BR> DOCUMENT_ROOT<BR> SERVER_ADMIN<BR> SERVER_NAME<BR> +SERVER_ADDR<BR> SERVER_PORT<BR> SERVER_PROTOCOL<BR> SERVER_SOFTWARE<BR> diff --git a/docs/manual/mod/mod_vhost_alias.html b/docs/manual/mod/mod_vhost_alias.html new file mode 100644 index 0000000000..9b86a07143 --- /dev/null +++ b/docs/manual/mod/mod_vhost_alias.html @@ -0,0 +1,311 @@ +<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> +<HTML> +<HEAD> +<TITLE>Apache module mod_vhost_alias</TITLE> +</HEAD> + +<!-- Background white, links blue (unvisited), navy (visited), red (active) --> +<BODY + BGCOLOR="#FFFFFF" + TEXT="#000000" + LINK="#0000FF" + VLINK="#000080" + ALINK="#FF0000" +> +<DIV ALIGN="CENTER"> + <IMG SRC="../images/sub.gif" ALT="[APACHE DOCUMENTATION]"> + <H3> + Apache HTTP Server Version 1.3 + </H3> +</DIV> + +<H1 ALIGN="CENTER">Module mod_vhost_alias</H1> + +<P> +This module is contained in the <CODE>mod_vhost_alias.c</CODE> file +and is not compiled in by default. It should be mentioned near the +start of the <CODE>Configuration</CODE> file so that it doesn't +override the behaviour of other modules that do filename translation, +e.g. <A HREF="mod_userdir.html"><CODE>mod_userdir</CODE></A> and +<A HREF="mod_alias.html"><CODE>mod_alias</CODE></A>. It provides +support for <A HREF="../vhost/mass.html">dynamically configured mass +virtual hosting</A>. +</P> + +<H2>Directory Name Interpolation</H2> + +<P> +All the directives in this module interpolate a string into a +pathname. The interpolated string (henceforth called the "name") may +be either the server name (see the +<A HREF="core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A> +directive for details on how this is determined) or the IP address of +the virtual host on the server in dotted-quad format. The +interpolation is controlled by specifiers inspired by +<CODE>printf</CODE> which have a number of formats: +<DL> + <DT><CODE>%%</CODE> + <DD>insert a <CODE>%</CODE> + <DT><CODE>%p</CODE> + <DD>insert the port number of the virtual host + <DT><CODE>%N.M</CODE> + <DD>insert (part of) the name +</DL> +</P> + +<P> +<CODE>N</CODE> and <CODE>M</CODE> are used to specify substrings of +the name. <CODE>N</CODE> selects from the dot-separated components of +the name, and <CODE>M</CODE> selects characters within whatever +<CODE>N</CODE> has selected. <CODE>M</CODE> is optional and defaults +to zero if it isn't present; the dot must be present if and only if +<CODE>M</CODE> is present. The interpretation is as follows: +<DL> + <DT><CODE>0</CODE> + <DD>the whole name + <DT><CODE>1</CODE> + <DD>the first part + <DT><CODE>2</CODE> + <DD>the second part + <DT><CODE>-1</CODE> + <DD>the last part + <DT><CODE>-2</CODE> + <DD>the penultimate part + <DT><CODE>2+</CODE> + <DD>the second and all subsequent parts + <DT><CODE>-2+</CODE> + <DD>the penultimate and all preceding parts + <DT><CODE>1+</CODE> and <CODE>-1+</CODE> + <DD>the same as <CODE>0</CODE> +</DL> +If <CODE>N</CODE> or <CODE>M</CODE> is greater than the number of +parts available a single underscore is interpolated. +</P> + +<H3>Examples</H3> + +<P> +For simple name-based virtual hosts you might use the following +directives in your server configuration file: +<PRE> + UseCanonicalName Off + VirtualDocumentRoot /usr/local/apache/vhosts/%0 +</PRE> +A request for <CODE>http://www.example.com/directory/file.html</CODE> +will be satisfied by the file +<CODE>/usr/local/apache/vhosts/www.example.com/directory/file.html</CODE>. +</P> + +<P> +For a very large number of virtual hosts it is a good idea to arrange +the files to reduce the size of the <CODE>vhosts</CODE> directory. To +do this you might use the following in your configuration file: +<PRE> + UseCanonicalName Off + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2 +</PRE> +A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> +will be satisfied by the file +<CODE>/usr/local/apache/isp.com/e/x/a/example/directory/file.html</CODE>. +A more even spread of files can be acheived by hashing from the end of +the name, for example: +<PRE> + VirtualDocumentRoot /u/%3+/%2.-1/%2.-2/%2.-3/%2 +</PRE> +The example request would come from +<CODE>/usr/local/apache/vhosts/isp.com/e/l/p/example/directory/file.html</CODE>. +Alternatively you might use: +<PRE> + VirtualDocumentRoot /usr/local/apache/vhosts/%3+/%2.1/%2.2/%2.3/%2.4+ +</PRE> +The example request would come from +<CODE>/usr/local/apache/vhosts/isp.com/e/x/a/mple/directory/file.html</CODE>. +</P> + +<P> +For IP-based virtual hosting you might use the following in your +configuration file: +<PRE> + UseCanonicalName DNS + VirtualDocumentRootIP /usr/local/apache/vhost/%1/%2/%3/%4/docs + VirtualScriptAliasIP /usr/local/apache/vhost/%1/%2/%3/%4/cgi-bin +</PRE> +A request for <CODE>http://www.example.isp.com/directory/file.html</CODE> +would be satisfied by the file +<CODE>/usr/local/apache/10/20/30/40/docs/directory/file.html</CODE> if +the IP address of <CODE>www.example.com</CODE> were 10.20.30.40. +A request for <CODE>http://www.example.isp.com/cgi-bin/script.pl</CODE> +would be satisfied by executing the program +<CODE>/usr/local/apache/10/20/30/40/cgi-bin/script.pl</CODE>. +</P> + +<P> +The <A HREF="mod_log_config.html#formats">LogFormat directives</A> +<CODE>%V</CODE> and <CODE>%A</CODE> are useful in conjunction with +this module. +</P> + +<HR> + +<H2>Directives</H2> +<UL> + <LI><A HREF="#VirtualDocumentRoot">VirtualDocumentRoot</A> + <LI><A HREF="#VirtualDocumentRootIP">VirtualDocumentRootIP</A> + <LI><A HREF="#VirtualScriptAlias">VirtualScriptAlias</A> + <LI><A HREF="#VirtualScriptAliasIP">VirtualScriptAliasIP</A> +</UL> +<HR> + +<H2><A NAME="VirtualDocumentRoot">VirtualDocumentRoot directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> VirtualDocumentRoot <EM>interpolated-directory</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> None<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> VirtualDocumentRoot is only available in 1.3.5 and later.</P> +<P> +The <CODE>VirtualDocumentRoot</CODE> directive allows you to determine +where Apache will find your documents based on the value of the server +name. The result of expanding <EM>interpolated-directory</EM> is used +as the root of the document tree in a similar manner to the +<A HREF="core.html#documentroot"><CODE>DocumentRoot</CODE></A> +directive's argument. If <EM>interpolated-directory</EM> is +<CODE>none</CODE> then <CODE>VirtaulDocumentRoot</CODE> is turned off. +This directive cannot be used in the same context as +<A HREF="#VirtualDocumentRootIP"><CODE>VirtualDocumentRootIP</CODE></A>. +</P> +<HR> + +<H2><A NAME="VirtualDocumentRootIP">VirtualDocumentRootIP directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> VirtualDocumentRootIP <EM>interpolated-directory</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> None<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> VirtualDocumentRootIP is only available in 1.3.5 and later.</P> +<P> +The <CODE>VirtualDocumentRootIP</CODE> directive is like the +<A HREF="#VirtualDocumentRoot"><CODE>VirtualDocumentRoot</CODE></A> directive, +except that it uses the IP address of the server end of the connection +instead of the server name. +</P> +<HR> + +<H2><A NAME="VirtualScriptAlias">VirtualScriptAlias directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> VirtualScriptAlias <EM>interpolated-directory</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> None<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> VirtualScriptAlias is only available in 1.3.5 and later.</P> +<P> +The <CODE>VirtualScriptAlias</CODE> directive allows you to determine +where Apache will find CGI scripts in a similar manner to +<A HREF="#VirtualDocumentRoot"><CODE>VirtualDocumentRoot</CODE></A> +does for other documents. It matches requests for URIs starting +<CODE>/cgi-bin/</CODE>, much like +<CODE><A HREF="mod_alias.html#scriptalias">ScriptAlias</A> /cgi-bin/</CODE> +would. +</P> +<HR> + +<H2><A NAME="VirtualScriptAlias">VirtualScriptAliasIP directive</A></H2> +<P> +<A + HREF="directive-dict.html#Syntax" + REL="Help" +><STRONG>Syntax:</STRONG></A> VirtualScriptAliasIP <EM>interpolated-directory</EM><BR> +<A + HREF="directive-dict.html#Default" + REL="Help" +><STRONG>Default:</STRONG></A> None<BR> +<A + HREF="directive-dict.html#Context" + REL="Help" +><STRONG>Context:</STRONG></A> server config, virtual host<BR> +<A + HREF="directive-dict.html#Status" + REL="Help" +><STRONG>Status:</STRONG></A> Extension<BR> +<A + HREF="directive-dict.html#Module" + REL="Help" +><STRONG>Module:</STRONG></A> mod_vhost_alias<BR> +<A + HREF="directive-dict.html#Compatibility" + REL="Help" +><STRONG>Compatibility:</STRONG></A> VirtualScriptAliasIP is only available in 1.3.5 and later.</P> +<P> +The <CODE>VirtualScriptAliasIP</CODE> directibe is like the +<A HREF="#VirtualScriptAlias"><CODE>VirtualScriptAlias</CODE></A> directive, +except that it uses the IP address of the server end of the connection +instead of the server name. +</P> +<HR> + +<H3 ALIGN="CENTER"> + Apache HTTP Server Version 1.3 +</H3> + +<A HREF="./"><IMG SRC="../images/index.gif" ALT="Index"></A> +<A HREF="../"><IMG SRC="../images/home.gif" ALT="Home"></A> + +</BODY> +</HTML> diff --git a/docs/manual/vhosts/mass.html b/docs/manual/vhosts/mass.html index 10b763f85a..2c1b8c6fdd 100644 --- a/docs/manual/vhosts/mass.html +++ b/docs/manual/vhosts/mass.html @@ -15,9 +15,7 @@ <H1 ALIGN="CENTER">Dynamically configured mass virtual hosting</H1> <P>This document describes how to efficiently serve an arbitrary number -of virtual hosts with Apache 1.3. Some familiarity with -<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A> is -useful.</P> +of virtual hosts with Apache 1.3. <!-- @@ -34,17 +32,21 @@ Some suggestions were made by Brian Behlendorf. <UL> <LI><A HREF="#motivation">Motivation</A> -<LI><A HREF="#overview">Overview of the technique</A> -<LI><A HREF="#simple">Simple name-based dynamic virtual hosts</A> +<LI><A HREF="#overview">Overview</A> +<LI><A HREF="#simple">Simple dynamic virtual hosts</A> <LI><A HREF="#homepages">A virtually hosted homepages system</A> -<LI><A HREF="#xtra-conf">Using a separate virtual host configuration file</A> <LI><A HREF="#combinations">Using more than one virtual hosting system on the same server</A> +<LI><A HREF="#ipbased">More efficient IP-based virtual hosting</A> +<LI><A HREF="#oldversion">Using older versions of Apache</A> +<LI><A HREF="#simple.rewrite">Simple dynamic virtual hosts using <CODE>mod_rewrite</CODE></A> +<LI><A HREF="#homepages.rewrite">A homepages system using <CODE>mod_rewrite</CODE></A> +<LI><A HREF="#xtra-conf">Using a separate virtual host configuration file</A> </UL> <HR><H2><A NAME="motivation">Motivation</A></H2> <P>The techniques described here are of interest if your -<CODE>httpd.conf</CODE> contains hundreds of +<CODE>httpd.conf</CODE> contains many <CODE><VirtualHost></CODE> sections that are substantially the same, for example: <PRE> @@ -81,82 +83,221 @@ works it out dynamically. This has a number of advantages: </P> <P>The main disadvantage is that you cannot have a different log file -for each server; however if you have very many virtual hosts then -doing this is dubious anyway because it eats file descriptors. It's -better to log to a pipe or a fifo and arrange for the process at the -other end to distribute the logs (and perhaps accumulate statistics, -etc.). A <CODE>LogFormat</CODE> directive that includes -<CODE>%{SERVER_NAME}e</CODE> for the virtual host makes it easy to do this.</P> - - -<HR><H2><A NAME="overview">Overview of the technique</A></H2> - -<P>All of the dynamic virtual hosts will either be configured as part -of the main server configuration, or within a -<CODE><VirtualHost></CODE> section. For a simple (very uniform) -setup, <CODE><VirtualHost></CODE> sections aren't needed at all.</P> +for each virtual host; however if you have very many virtual hosts +then doing this is dubious anyway because it eats file descriptors. It +is better to log to a pipe or a fifo and arrange for the process at +the other end to distribute the logs to the customers (it can also +accumulate statistics, etc.).</P> + + +<HR><H2><A NAME="overview">Overview</A></H2> + +<P>A virtual host is defined by two pieces of information: its IP +address, and the contents of the <CODE>Host:</CODE> header in the HTTP +request. The dynamic mass virtual hosting technique is based on +automatically inserting this information into the pathname of the file +that is used to satisfy the request. This is done most easily using +<A HREF="../mod/mod_vhost_alias.html"><CODE>mod_vhost_alias</CODE></A>, +but if you are using a version of Apache up to 1.3.6 then you must use +<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>. Both +of these modules are disabled by default; you must enable one of them +when configuring and building Apache if you want to use this technique.</P> <P>A couple of things need to be `faked' to make the dynamic virtual host look like a normal one. The most important is the server name -(configured with <CODE>ServerName</CODE> and available to CGIs via the -<CODE>SERVER_NAME</CODE> environment variable). The way it is -determined is controlled by the <CODE>UseCanonicalName</CODE> -directive: with <CODE>UseCanonicalName off</CODE> the server name +which is used by Apache to generate self-referential URLs, etc. It +is configured with the <CODE>ServerName</CODE> directive, and it is +available to CGIs via the <CODE>SERVER_NAME</CODE> environment +variable. The actual value used at run time is controlled by the +<A HREF="../mod/core.html#usecanonicalname"><CODE>UseCanonicalName</CODE></A> +setting. With <CODE>UseCanonicalName Off</CODE> the server name comes from the contents of the <CODE>Host:</CODE> header in the -request. If there is no <CODE>Host:</CODE> header then the value -configured with <CODE>ServerName</CODE> is used instead.</P> - -<P>The other one is the document root (configured with -<CODE>DocumentRoot</CODE> and available to CGIs via the -<CODE>DOCUMENT_ROOT</CODE> environment variable). This is used by the -core module when mapping URIs to filenames, but in the context of -dynamic virtual hosting its value only matters if any CGIs or SSI -documents make use of the <CODE>DOCUMENT_ROOT</CODE> environment -variable. This is an Apache extension to the CGI specification and as -such shouldn't really be relied upon, especially because this -technique breaks it: there isn't currently a way of setting -<CODE>DOCUMENT_ROOT</CODE> dynamically.</P> - -<P>The meat of the mechanism works via Apache's URI-to-filename -translation API phase. This is used by a number of modules: -<A HREF="../mod/mod_rewrite.html"><CODE>mod_rewrite</CODE></A>, -<A HREF="../mod/mod_alias.html"><CODE>mod_alias</CODE></A>, -<A HREF="../mod/mod_userdir.html"><CODE>mod_userdir</CODE></A>, -and <A HREF="../mod/core.html">the core module</A>. -In the default configuration these modules are called in that order -and given a chance to say that they know what the filename is. Most of -these modules do it in a fairly simple fashion (e.g. the core module -concatenates the document root and the URI) except for -<CODE>mod_rewrite</CODE>, which provides enough functionality to do -all sorts of sick and twisted things (like dynamic virtual hosting). -Note that because of the order in which the modules are called, using -a <CODE>mod_rewrite</CODE> configuration that matches any URI means -that the other modules (particularly <CODE>mod_alias</CODE>) will -cease to function. The examples below show how to deal with this.</P> - -<P><STRONG>The dynamic virtual hosting idea is very simple: use the -server name as well as the URI to determine the corresponding -filename.</STRONG></P> - - -<HR><H2><A NAME="simple">Simple name-based dynamic virtual hosts</A></H2> +request. With <CODE>UseCanonicalName DNS</CODE> it comes from a +reverse DNS lookup of the virtual host's IP address. The former +setting is used for name-based dynamic virtual hosting, and the latter +is used for IP-based hosting. If Apache cannot work out the server +name because there is no <CODE>Host:</CODE> header or the DNS lookup +fails then the value configured with <CODE>ServerName</CODE> is used +instead.</P> + +<P>The other thing to `fake' is the document root (configured +with <CODE>DocumentRoot</CODE> and available to CGIs via the +<CODE>DOCUMENT_ROOT</CODE> environment variable). This setting +is used by the core module when mapping URIs to filenames, but +when the server is configured to do dynamic virtual hosting that +job is taken over by another module. If any CGIs or SSI documents +make use of the <CODE>DOCUMENT_ROOT</CODE> environment variable +they will therefore get a misleading value; there isn't any way to +change <CODE>DOCUMENT_ROOT</CODE> dynamically.</P> + + +<HR><H2><A NAME="simple">Simple dynamic virtual hosts</A></H2> <P>This extract from <CODE>httpd.conf</CODE> implements the virtual host arrangement outlined in the <A HREF="#motivation">Motivation</A> -section above, but in a generic fashion.</P> +section above, but in a generic fashion using +<CODE>mod_vhost_alias</CODE>.</P> + +<PRE> +# get the server name from the Host: header +UseCanonicalName Off -<P>The first half shows some other configuration options that are -needed to make the <CODE>mod_rewrite</CODE> part work as expected; the -second half uses <CODE>mod_rewrite</CODE> to do the actual work. Some -care is taken to do a per-dynamic-virtual-host equivalent of -<CODE>ScriptAlias</CODE>.</P> +# this log format can be split per-virtual-host based on the first field +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon +CustomLog logs/access_log vcommon + +# include the server name in the filenames used to satisfy requests +VirtualDocumentRoot /www/hosts/%0/docs +VirtualScriptAlias /www/hosts/%0/cgi-bin +</PRE> + +<P>This configuration can be changed into an IP-based virtual hosting +solution by just turning <CODE>UseCanonicalName Off</CODE> into +<CODE>UseCanonicalName DNS</CODE>. The server name that is inserted +into the filename is then derived from the IP address of the virtual +host.</P> + + +<HR><H2><A NAME="homepages">A virtually hosted homepages system</A></H2> + +<P>This is an adjustment of the above system tailored for an ISP's +homepages server. Using a slightly more complicated configuration we +can select substrings of the server name to use in the filename so +that e.g. the documents for <SAMP>www.user.isp.com</SAMP> are found in +<CODE>/home/user/</CODE>. It uses a single <CODE>cgi-bin</CODE> +directory instead of one per virtual host.</P> + +<PRE> +# all the preliminary stuff is the same as above, then + +# include part of the server name in the filenames +VirtualDocumentRoot /www/hosts/%2/docs + +# single cgi-bin directory +ScriptAlias /cgi-bin/ /www/std-cgi/ +</PRE> + +<P>There are examples of more complicated +<CODE>VirtualDocumentRoot</CODE> settings in +<A HREF="../mod/mod_vhost_alias.html">the +<CODE>mod_vhost_alias</CODE> documentation</A>.</P> + + +<HR><H2><A NAME="combinations">Using more than one virtual hosting +system on the same server</A></H2> + +<P>With more complicated setups you can use Apache's normal +<CODE><VirtualHost></CODE> directives to control the scope of +the various virtual hosting configurations. For example, you could +have one IP address for homepages customers and another for commercial +customers with the following setup. This can of course be combined +with conventional <CODE><VirtualHost></CODE> configuration +sections.</P> <PRE> -# dynamic ServerName +UseCanonicalName Off + +LogFormat "%V %h %l %u %t \"%r\" %s %b" vcommon + +<Directory /www/commercial> + Options FollowSymLinks + AllowOverride All +</Directory> + +<Directory /www/homepages> + Options FollowSymLinks + AllowOverride None +</Directory> + +<VirtualHost 111.22.33.44> + ServerName www.commercial.isp.com + + CustomLog logs/access_log.commercial vcommon + + VirtualDocumentRoot /www/commercial/%0/docs + VirtualScriptAlias /www/commercial/%0/cgi-bin +</VirtualHost> + +<VirtualHost 111.22.33.45> + ServerName www.homepages.isp.com + + CustomLog logs/access_log.homepages vcommon + + VirtualDocumentRoot /www/homepages/%0/docs + ScriptAlias /cgi-bin/ /www/std-cgi/ +</VirtualHost> +</PRE> + + +<HR><H2><A NAME="ipbased">More efficient IP-based virtual hosting</A></H2> + +<P>After <A HREF="#simple">the first example</A> I noted that it is +easy to turn it into an IP-based virtual hosting setup. Unfortunately +that configuration is not very efficient because it requires a DNS +lookup for every request. This can be avoided by laying out the +filesystem according to the IP addresses themselves rather than the +corresponding names and changing the logging similarly. Apache will +then usually not need to work out the server name and so incur a DNS +lookup.</P> + +<PRE> +# get the server name from the reverse DNS of the IP address +UseCanonicalName DNS + +# include the IP address in the logs so they may be split +LogFormat "%A %h %l %u %t \"%r\" %s %b" vcommon +CustomLog logs/access_log vcommon + +# include the IP address in the filenames +VirtualDocumentRootIP /www/hosts/%0/docs +VirtualScriptAliasIP /www/hosts/%0/cgi-bin +</PRE> + + +<HR><H2><A NAME="oldversion">Using older versions of Apache</A></H2> + +<P>The examples above rely on <CODE>mod_vhost_alias</CODE> which +appeared after version 1.3.6. If you are using a version of Apache +without <CODE>mod_vhost_alias</CODE> then you can implement this +technique with <CODE>mod_rewrite</CODE> as illustrated below, but +only for Host:-header-based virtual hosts.</P> + +<P>In addition there are some things to beware of with logging. Apache +1.3.6 is the first version to include the <CODE>%V</CODE> log format +directive; in versions 1.3.0 - 1.3.3 the <CODE>%v</CODE> option did +what <CODE>%V</CODE> does; version 1.3.4 has no equivalent. In +all these versions of Apache the <CODE>UseCanonicalName</CODE> +directive can appear in <CODE>.htaccess</CODE> files which means that +customers can cause the wrong thing to be logged. Therefore the best +thing to do is use the <CODE>%{Host}i</CODE> directive which logs the +<CODE>Host:</CODE> header directly; note that this may include +<CODE>:port</CODE> on the end which is not the case for +<CODE>%V</CODE>.</P> + + +<HR><H2><A NAME="simple.rewrite">Simple dynamic virtual hosts +using <CODE>mod_rewrite</CODE></A></H2> + +<P>This extract from <CODE>httpd.conf</CODE> does the same thing as +<A HREF="#simple">the first example</A>. The first half is very +similar to the corresponding part above but with some changes for +backward compatibility and to make the <CODE>mod_rewrite</CODE> part +work properly; the second half configures <CODE>mod_rewrite</CODE> to +do the actual work.</P> + +<P>There are a couple of especially tricky bits: By default, +<CODE>mod_rewrite</CODE> runs before the other URI translation modules +(<CODE>mod_alias</CODE> etc.) so if they are used then +<CODE>mod_rewrite</CODE> must be configured to accommodate them. +Also, mome magic must be performed to do a per-dynamic-virtual-host +equivalent of <CODE>ScriptAlias</CODE>.</P> + +<PRE> +# get the server name from the Host: header UseCanonicalName Off # splittable logs -LogFormat "%{SERVER_NAME}e %h %l %u %t \"%r\" %s %b" vcommon +LogFormat "%{Host}i %h %l %u %t \"%r\" %s %b" vcommon CustomLog logs/access_log vcommon <Directory /www/hosts> @@ -188,14 +329,11 @@ RewriteRule ^/(.*)$ /www/hosts/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=appl </PRE> -<HR><H2><A NAME="homepages">A virtually hosted homepages system</A></H2> +<HR><H2><A NAME="homepages.rewrite">A homepages system +using <CODE>mod_rewrite</CODE></A></H2> -<P>This is an adjustment of the above system tailored for an ISP's -homepages server. Using slightly more complicated rewriting rules we -can select substrings of the server name to use in the filename so -that e.g. the documents for <SAMP>www.user.isp.com</SAMP> are found in -<CODE>/home/user/</CODE>. It uses a single <CODE>cgi-bin</CODE> -directory instead of one per virtual host.</P> +<P>This does the same thing as <A HREF="#homepages">the +second example</A>.</P> <PRE> RewriteEngine on @@ -206,11 +344,11 @@ RewriteMap lowercase int:tolower RewriteCond %{REQUEST_URI} !^/cgi-bin/ # check the hostname is right so that the RewriteRule works -RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$ +RewriteCond ${lowercase:%{SERVER_NAME}} ^www\.[a-z-]+\.isp\.com$ # concatenate the virtual host name onto the start of the URI # the [C] means do the next rewrite on the result of this one -RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C] +RewriteRule ^(.+) ${lowercase:%{SERVER_NAME}}$1 [C] # now create the real file name RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /home/$1/$2 @@ -222,9 +360,10 @@ ScriptAlias /cgi-bin/ /www/std-cgi/ <HR><H2><A NAME="xtra-conf">Using a separate virtual host configuration file</A></H2> -<P>This arrangement uses a separate configuration file to specify the -translation from virtual host to document root. This provides more -flexibility but requires more configuration.</P> +<P>This arrangement uses more advanced <CODE>mod_rewrite</CODE> +features to get the translation from virtual host to document root +from a separate configuration file. This provides more flexibility but +requires more complicated configuration.</P> <P>The <CODE>vhost.map</CODE> file contains something like this: <PRE> @@ -260,63 +399,6 @@ RewriteRule ^/(.*)$ %1/cgi-bin/$1 </P> -<HR><H2><A NAME="combinations">Using more than one virtual hosting system on the same server</A></H2> - -<P>With more complicated setups, you can use Apache's normal -<CODE><VirtualHost></CODE> directives to control the scope of -the various rewrite configurations. For example, you could have one IP -address for homepages customers and another for commercial customers -with the following setup. This can of course be combined with -convential <CODE><VirtualHost></CODE> configuration -sections.</P> - -<PRE> -UseCanonicalName Off - -LogFormat "%{SERVER_NAME}e %h %l %u %t \"%r\" %s %b" vcommon -CustomLog logs/access_log vcommon - -<Directory /www/commercial> - Options FollowSymLinks ExecCGI - AllowOverride All -</Directory> - -<Directory /www/homepages> - Options FollowSymLinks - AllowOverride None -</Directory> - -<VirtualHost 111.22.33.44> - ServerName www.commercial.isp.com - - RewriteEngine On - RewriteMap lowercase int:tolower - - RewriteCond %{REQUEST_URI} !^/icons/ - RewriteCond %{REQUEST_URI} !^/cgi-bin/ - RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/docs/$1 - - RewriteCond %{REQUEST_URI} ^/cgi-bin/ - RewriteRule ^/(.*)$ /www/commercial/${lowercase:%{SERVER_NAME}}/cgi-bin/$1 [T=application/x-httpd-cgi] -</VirtualHost> - -<VirtualHost 111.22.33.45> - ServerName www.homepages.isp.com - - RewriteEngine on - RewriteMap lowercase int:tolower - - RewriteCond %{REQUEST_URI} !^/cgi-bin/ - - RewriteCond ${lowercase:%{HTTP_HOST}} ^www\.[a-z-]+\.isp\.com$ - RewriteRule ^(.+) ${lowercase:%{HTTP_HOST}}$1 [C] - RewriteRule ^www\.([a-z-]+)\.isp\.com/(.*) /www/homepages/$1/$2 - - ScriptAlias /cgi-bin/ /www/std-cgi/ -</VirtualHost> -</PRE> - - <HR> <H3 ALIGN="CENTER"> |