<?xml version="1.0" encoding="UTF-8" ?>

<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">

<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>

<manualpage metafile="rewrite_guide.xml.meta">

<parentdocument href="./">Rewrite</parentdocument>

<title>URL Rewriting Guide</title>

<summary>

<p>This document supplements the <module>mod_rewrite</module>

<a href="/mod/mod_rewrite.html">reference documentation</a>.

It describes how one can use Apache's <module>mod_rewrite</module>

to solve typical URL-based problems with which webmasters are

commonly confronted. We give detailed descriptions on how to

solve each problem by configuring URL rewriting rulesets.</p>

<note type="warning">ATTENTION: Depending on your server configuration

it may be necessary to slightly change the examples for your

situation, e.g. adding the <code>[PT]</code> flag when

additionally using <module>mod_alias</module> and

<module>mod_userdir</module>, etc. Or rewriting a ruleset

to fit in <code>.htaccess</code> context instead

of per-server context. Always try to understand what a

particular ruleset really does before you use it. This

avoids many problems.</note>

</summary>

<seealso><a href="/mod/mod_rewrite.html">Module

documentation</a></seealso>

<seealso><a href="intro.html">mod_rewrite

introduction</a></seealso>

<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - advanced

useful examples</a></seealso>

<seealso><a href="tech.html">Technical details</a></seealso>

<section id="canonicalurl">

<title>Canonical URLs</title>

<dl>

<dt>Description:</dt>

<dd>

<p>On some webservers there are more than one URL for a

resource. Usually there are canonical URLs (which should be

actually used and distributed) and those which are just

shortcuts, internal ones, etc. Independent of which URL the

user supplied with the request he should finally see the

canonical one only.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We do an external HTTP redirect for all non-canonical

URLs to fix them in the location view of the Browser and

for all subsequent requests. In the example ruleset below

we replace <code>/~user</code> by the canonical

<code>/u/user</code> and fix a missing trailing slash for

<code>/u/user</code>.</p>

<example><pre>

RewriteRule ^/<strong>~</strong>([^/]+)/?(.*) /<strong>u</strong>/$1/$2 [<strong>R</strong>]

RewriteRule ^/u/(<strong>[^/]+</strong>)$ /$1/$2<strong>/</strong> [<strong>R</strong>]

</pre></example>

</dd>

</dl>

</section>

<section id="moveddocroot">

<title>Moved <code>DocumentRoot</code></title>

<dl>

<dt>Description:</dt>

<dd>

<p>Usually the <directive module="core">DocumentRoot</directive>

of the webserver directly relates to the URL "<code>/</code>".

But often this data is not really of top-level priority. For example,

you may wish for visitors, on first entering a site, to go to a

particular subdirectory <code>/about/</code>. This may be accomplished

using the following ruleset:</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We redirect the URL <code>/</code> to

<code>/about/</code>:

</p>

<example><pre>

RewriteEngine on

RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]

</pre></example>

<p>Note that this can also be handled using the <directive

module="mod_alias">RedirectMatch</directive> directive:</p>

<example>

RedirectMatch ^/$ http://example.com/about/

</example>

<p>Note also that the example rewrites only the root URL. That is, it

rewrites a request for <code>http://example.com/</code>, but not a

request for <code>http://example.com/page.html</code>. If you have in

fact changed your document root - that is, if <strong>all</strong> of

your content is in fact in that subdirectory, it is greatly preferable

to simply change your <directive module="core">DocumentRoot</directive>

directive, rather than rewriting URLs.</p>

</dd>

</dl>

</section>

<section id="trailingslash">

<title>Trailing Slash Problem</title>

<dl>

<dt>Description:</dt>

<dd><p>The vast majority of "trailing slash" problems can be dealt

with using the techniques discussed in the <a

href="http://httpd.apache.org/docs/misc/FAQ-E.html#set-servername">FAQ

entry</a>. However, occasionally, there is a need to use mod_rewrite

to handle a case where a missing trailing slash causes a URL to

fail. This can happen, for example, after a series of complex

rewrite rules.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>The solution to this subtle problem is to let the server

add the trailing slash automatically. To do this

correctly we have to use an external redirect, so the

browser correctly requests subsequent images etc. If we

only did a internal rewrite, this would only work for the

directory page, but would go wrong when any images are

included into this page with relative URLs, because the

browser would request an in-lined object. For instance, a

request for <code>image.gif</code> in

<code>/~quux/foo/index.html</code> would become

<code>/~quux/image.gif</code> without the external

redirect!</p>

<p>So, to do this trick we write:</p>

<example><pre>

RewriteEngine on

RewriteBase /~quux/

RewriteRule ^foo<strong>$</strong> foo<strong>/</strong> [<strong>R</strong>]

</pre></example>

<p>Alternately, you can put the following in a

top-level <code>.htaccess</code> file in the content directory.

But note that this creates some processing overhead.</p>

<example><pre>

RewriteEngine on

RewriteBase /~quux/

RewriteCond %{REQUEST_FILENAME} <strong>-d</strong>

RewriteRule ^(.+<strong>[^/]</strong>)$ $1<strong>/</strong> [R]

</pre></example>

</dd>

</dl>

</section>

<section id="setenvvars">

<title>Set Environment Variables According To URL Parts</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Perhaps you want to keep status information between

requests and use the URL to encode it. But you don't want

to use a CGI wrapper for all pages just to strip out this

information.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We use a rewrite rule to strip out the status information

and remember it via an environment variable which can be

later dereferenced from within XSSI or CGI. This way a

URL <code>/foo/S=java/bar/</code> gets translated to

<code>/foo/bar/</code> and the environment variable named

<code>STATUS</code> is set to the value "java".</p>

<example><pre>

RewriteEngine on

RewriteRule ^(.*)/<strong>S=([^/]+)</strong>/(.*) $1/$3 [E=<strong>STATUS:$2</strong>]

</pre></example>

</dd>

</dl>

</section>

<section id="uservhosts">

<title>Virtual Hosts Per User</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Assume that you want to provide

<code>www.<strong>username</strong>.host.domain.com</code>

for the homepage of username via just DNS A records to the

same machine and without any virtualhosts on this

machine.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>For HTTP/1.0 requests there is no solution, but for

HTTP/1.1 requests which contain a Host: HTTP header we

can use the following ruleset to rewrite

<code>http://www.username.host.com/anypath</code>

internally to <code>/home/username/anypath</code>:</p>

<example><pre>

RewriteEngine on

RewriteCond %{<strong>HTTP_HOST</strong>} ^www\.<strong>([^.]+)</strong>\.host\.com$

RewriteRule ^(.*) /home/<strong>%1</strong>$1

</pre></example>

<p>Parentheses used in a <directive

module="mod_rewrite">RewriteCond</directive> are captured into the

backreferences <code>%1</code>, <code>%2</code>, etc, while parentheses

used in <directive module="mod_rewrite">RewriteRule</directive> are

captured into the backreferences <code>$1</code>, <code>$2</code>,

etc.</p>

</dd>

</dl>

</section>

<section id="redirecthome">

<title>Redirect Homedirs For Foreigners</title>

<dl>

<dt>Description:</dt>

<dd>

<p>We want to redirect homedir URLs to another webserver

<code>www.somewhere.com</code> when the requesting user

does not stay in the local domain

<code>ourdomain.com</code>. This is sometimes used in

virtual host contexts.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>Just a rewrite condition:</p>

<example><pre>

RewriteEngine on

RewriteCond %{REMOTE_HOST} <strong>!^.+\.ourdomain\.com$</strong>

RewriteRule ^(/~.+) http://www.somewhere.com/$1 [R,L]

</pre></example>

</dd>

</dl>

</section>

<section id="redirectanchors">

<title>Redirecting Anchors</title>

<dl>

<dt>Description:</dt>

<dd>

<p>By default, redirecting to an HTML anchor doesn't work,

because mod_rewrite escapes the <code>#</code> character,

turning it into <code>%23</code>. This, in turn, breaks the

redirection.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>Use the <code>[NE]</code> flag on the

<code>RewriteRule</code>. NE stands for No Escape.

</p>

</dd>

</dl>

</section>

<section id="time-dependent">

<title>Time-Dependent Rewriting</title>

<dl>

<dt>Description:</dt>

<dd>

<p>When tricks like time-dependent content should happen a

lot of webmasters still use CGI scripts which do for

instance redirects to specialized pages. How can it be done

via <module>mod_rewrite</module>?</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>There are a lot of variables named <code>TIME_xxx</code>

for rewrite conditions. In conjunction with the special

lexicographic comparison patterns <code>&lt;STRING</code>,

<code>&gt;STRING</code> and <code>=STRING</code> we can

do time-dependent redirects:</p>

<example><pre>

RewriteEngine on

RewriteCond %{TIME_HOUR}%{TIME_MIN} &gt;0700

RewriteCond %{TIME_HOUR}%{TIME_MIN} &lt;1900

RewriteRule ^foo\.html$ foo.day.html

RewriteRule ^foo\.html$ foo.night.html

</pre></example>

<p>This provides the content of <code>foo.day.html</code>

under the URL <code>foo.html</code> from

<code>07:01-18:59</code> and at the remaining time the

contents of <code>foo.night.html</code>. Just a nice

feature for a homepage...</p>

<note type="warning"><module>mod_cache</module>, intermediate proxies

and browsers may each cache responses and cause the either page to be

shown outside of the time-window configured.

<module>mod_expires</module> may be used to control this

effect.</note>

</dd>

</dl>

</section>

<section id="external-rewriting">

<title>External Rewriting Engine</title>

<dl>

<dt>Description:</dt>

<dd>

<p>A FAQ: How can we solve the FOO/BAR/QUUX/etc.

problem? There seems no solution by the use of

<module>mod_rewrite</module>...</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>Use an external <directive module="mod_rewrite"

>RewriteMap</directive>, i.e. a program which acts

like a <directive module="mod_rewrite"

>RewriteMap</directive>. It is run once on startup of Apache

receives the requested URLs on <code>STDIN</code> and has

to put the resulting (usually rewritten) URL on

<code>STDOUT</code> (same order!).</p>

<example><pre>

RewriteEngine on

RewriteMap quux-map <strong>prg:</strong>/path/to/map.quux.pl

RewriteRule ^/~quux/(.*)$ /~quux/<strong>${quux-map:$1}</strong>

</pre></example>

<example><pre>

#!/path/to/perl

# disable buffered I/O which would lead

# to deadloops for the Apache server

$| = 1;

# read URLs one per line from stdin and

# generate substitution URL on stdout

while (&lt;&gt;) {

s|^foo/|bar/|;

print $_;

}

</pre></example>

<p>This is a demonstration-only example and just rewrites

all URLs <code>/~quux/foo/...</code> to

<code>/~quux/bar/...</code>. Actually you can program

whatever you like. But notice that while such maps can be

<strong>used</strong> also by an average user, only the

system administrator can <strong>define</strong> it.</p>

</dd>

</dl>

</section>

<section id="cluster">

<title>URL-based sharding accross multiple backends</title>

<dl>

<dt>Description:</dt>

<dd>

<p>A common technique for distributing the burden of

server load or storage space is called "sharding".

When using this method, a front-end server will use the

url to consistently "shard" users or objects to seperate

backend servers.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>A mapping is maintained, from users to target servers, in

external map files. They look like:</p>

<example><pre>

user1 physical_host_of_user1

user2 physical_host_of_user2

: :

</pre></example>

<p>We put this into a <code>map.users-to-hosts</code> file. The

aim is to map;</p>

<example><pre>

/u/user1/anypath

</pre></example>

<p>to</p>

<example><pre>

</pre></example>

<p>thus every URL path need not be valid on every backend physical

host. The following ruleset does this for us with the help of the map

files assuming that server0 is a default server which will be used if

a user has no entry in the map):</p>

<example><pre>

RewriteEngine on

RewriteMap users-to-hosts txt:/path/to/map.users-to-hosts

RewriteRule ^/u/<strong>([^/]+)</strong>/?(.*) http://<strong>${users-to-hosts:$1|server0}</strong>/u/$1/$2

</pre></example>

</dd>

</dl>

</section>

<section id="structuredhomedirs">

<title>Structured Homedirs</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Some sites with thousands of users use a

structured homedir layout, <em>i.e.</em> each homedir is in a

subdirectory which begins (for instance) with the first

character of the username. So, <code>/~foo/anypath</code>

is <code>/home/<strong>f</strong>/foo/.www/anypath</code>

while <code>/~bar/anypath</code> is

<code>/home/<strong>b</strong>/bar/.www/anypath</code>.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We use the following ruleset to expand the tilde URLs

into the above layout.</p>

<example><pre>

RewriteEngine on

RewriteRule ^/~(<strong>([a-z])</strong>[a-z0-9]+)(.*) /home/<strong>$2</strong>/$1/.www$3

</pre></example>

</dd>

</dl>

</section>

<section id="browser-dependent-content">

<title>Browser Dependent Content</title>

<dl>

<dt>Description:</dt>

<dd>

<p>At least for important top-level pages it is sometimes

necessary to provide the optimum of browser dependent

content, i.e., one has to provide one version for

current browsers, a different version for the Lynx and text-mode

browsers, and another for other browsers.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We cannot use content negotiation because the browsers do

not provide their type in that form. Instead we have to

act on the HTTP header "User-Agent". The following config

does the following: If the HTTP header "User-Agent"

begins with "Mozilla/3", the page <code>foo.html</code>

is rewritten to <code>foo.NS.html</code> and the

rewriting stops. If the browser is "Lynx" or "Mozilla" of

version 1 or 2, the URL becomes <code>foo.20.html</code>.

All other browsers receive page <code>foo.32.html</code>.

This is done with the following ruleset:</p>

<example><pre>

RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*

RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]

RewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]

RewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*

RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]

RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]

</pre></example>

</dd>

</dl>

</section>

<section id="dynamic-mirror">

<title>Dynamic Mirror</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Assume there are nice web pages on remote hosts we want

to bring into our namespace. For FTP servers we would use

the <code>mirror</code> program which actually maintains an

explicit up-to-date copy of the remote data on the local

machine. For a web server we could use the program

<code>webcopy</code> which runs via HTTP. But both

techniques have a major drawback: The local copy is

always only as up-to-date as the last time we ran the program. It

would be much better if the mirror was not a static one we

have to establish explicitly. Instead we want a dynamic

mirror with data which gets updated automatically

as needed on the remote host(s).</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>To provide this feature we map the remote web page or even

the complete remote web area to our namespace by the use

of the <dfn>Proxy Throughput</dfn> feature

(flag <code>[P]</code>):</p>

<example><pre>

RewriteEngine on

RewriteBase /~quux/

RewriteRule ^<strong>hotsheet/</strong>(.*)$ <strong>http://www.tstimpreso.com/hotsheet/</strong>$1 [<strong>P</strong>]

</pre></example>

<example><pre>

RewriteEngine on

RewriteBase /~quux/

RewriteRule ^<strong>usa-news\.html</strong>$ <strong>http://www.quux-corp.com/news/index.html</strong> [<strong>P</strong>]

</pre></example>

</dd>

</dl>

</section>

<section id="reverse-dynamic-mirror">

<title>Reverse Dynamic Mirror</title>

<dl>

<dt>Description:</dt>

<dd>...</dd>

<dt>Solution:</dt>

<dd>

<example><pre>

RewriteEngine on

RewriteCond /mirror/of/remotesite/$1 -U

RewriteRule ^http://www\.remotesite\.com/(.*)$ /mirror/of/remotesite/$1

</pre></example>

</dd>

</dl>

</section>

<section id="retrieve-missing-data">

<title>Retrieve Missing Data from Intranet</title>

<dl>

<dt>Description:</dt>

<dd>

<p>This is a tricky way of virtually running a corporate

(external) Internet web server

(<code>www.quux-corp.dom</code>), while actually keeping

and maintaining its data on an (internal) Intranet web server

(<code>www2.quux-corp.dom</code>) which is protected by a

firewall. The trick is that the external web server retrieves

the requested data on-the-fly from the internal

one.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>First, we must make sure that our firewall still

protects the internal web server and only the

external web server is allowed to retrieve data from it.

On a packet-filtering firewall, for instance, we could

configure a firewall ruleset like the following:</p>

<example><pre>

<strong>ALLOW</strong> Host www.quux-corp.dom Port &gt;1024 --&gt; Host www2.quux-corp.dom Port <strong>80</strong>

<strong>DENY</strong> Host * Port * --&gt; Host www2.quux-corp.dom Port <strong>80</strong>

</pre></example>

<p>Just adjust it to your actual configuration syntax.

Now we can establish the <module>mod_rewrite</module>

rules which request the missing data in the background

through the proxy throughput feature:</p>

<example><pre>

RewriteRule ^/~([^/]+)/?(.*) /home/$1/.www/$2 [C]

# REQUEST_FILENAME usage below is correct in this per-server context example

# because the rule that references REQUEST_FILENAME is chained to a rule that

# sets REQUEST_FILENAME.

RewriteCond %{REQUEST_FILENAME} <strong>!-f</strong>

RewriteCond %{REQUEST_FILENAME} <strong>!-d</strong>

RewriteRule ^/home/([^/]+)/.www/?(.*) http://<strong>www2</strong>.quux-corp.dom/~$1/pub/$2 [<strong>P</strong>]

</pre></example>

</dd>

</dl>

</section>

<section id="load-balancing">

<title>Load Balancing</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Suppose we want to load balance the traffic to

<code>www.example.com</code> over <code>www[0-5].example.com</code>

(a total of 6 servers). How can this be done?</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>There are many possible solutions for this problem.

We will first discuss a common DNS-based method,

and then one based on <module>mod_rewrite</module>:</p>

<ol>

<li>

<strong>DNS Round-Robin</strong>

<p>The simplest method for load-balancing is to use

DNS round-robin.

Here you just configure <code>www[0-9].example.com</code>

as usual in your DNS with A (address) records, e.g.,</p>

<example><pre>

www0 IN A 1.2.3.1

www1 IN A 1.2.3.2

www2 IN A 1.2.3.3

www3 IN A 1.2.3.4

www4 IN A 1.2.3.5

www5 IN A 1.2.3.6

</pre></example>

<p>Then you additionally add the following entries:</p>

<example><pre>

www IN A 1.2.3.1

www IN A 1.2.3.2

www IN A 1.2.3.3

www IN A 1.2.3.4

www IN A 1.2.3.5

</pre></example>

<p>Now when <code>www.example.com</code> gets

resolved, <code>BIND</code> gives out <code>www0-www5</code>

- but in a permutated (rotated) order every time.

This way the clients are spread over the various

servers. But notice that this is not a perfect load

balancing scheme, because DNS resolutions are

cached by clients and other nameservers, so

once a client has resolved <code>www.example.com</code>

to a particular <code>wwwN.example.com</code>, all its

subsequent requests will continue to go to the same

IP (and thus a single server), rather than being

distributed across the other available servers. But the

overall result is

okay because the requests are collectively

spread over the various web servers.</p>

</li>

<li>

<strong>DNS Load-Balancing</strong>

<p>A sophisticated DNS-based method for

load-balancing is to use the program

<code>lbnamed</code> which can be found at <a

href="http://www.stanford.edu/~riepel/lbnamed/">

http://www.stanford.edu/~riepel/lbnamed/</a>.

It is a Perl 5 program which, in conjunction with auxiliary

tools, provides real load-balancing via

DNS.</p>

</li>

<li>

<strong>Proxy Throughput Round-Robin</strong>

<p>In this variant we use <module>mod_rewrite</module>

and its proxy throughput feature. First we dedicate

<code>www0.example.com</code> to be actually

<code>www.example.com</code> by using a single</p>

<example><pre>

www IN CNAME www0.example.com.

</pre></example>

<p>entry in the DNS. Then we convert

<code>www0.example.com</code> to a proxy-only server,

i.e., we configure this machine so all arriving URLs

are simply passed through its internal proxy to one of

the 5 other servers (<code>www1-www5</code>). To

accomplish this we first establish a ruleset which

contacts a load balancing script <code>lb.pl</code>

for all URLs.</p>

<example><pre>

RewriteEngine on

RewriteMap lb prg:/path/to/lb.pl

RewriteRule ^/(.+)$ ${lb:$1} [P,L]

</pre></example>

<p>Then we write <code>lb.pl</code>:</p>

<example><pre>

#!/path/to/perl

##

## lb.pl -- load balancing script

##

$| = 1;

$name = "www"; # the hostname base

$first = 1; # the first server (not 0 here, because 0 is myself)

$last = 5; # the last server in the round-robin

$domain = "foo.dom"; # the domainname

$cnt = 0;

while (&lt;STDIN&gt;) {

$cnt = (($cnt+1) % ($last+1-$first));

$server = sprintf("%s%d.%s", $name, $cnt+$first, $domain);

print "http://$server/$_";

}

##EOF##

</pre></example>

<note>A last notice: Why is this useful? Seems like

<code>www0.example.com</code> still is overloaded? The

answer is yes, it is overloaded, but with plain proxy

throughput requests, only! All SSI, CGI, ePerl, etc.

processing is handled done on the other machines.

For a complicated site, this may work well. The biggest

risk here is that www0 is now a single point of failure --

if it crashes, the other servers are inaccessible.</note>

</li>

<li>

<strong>Dedicated Load Balancers</strong>

<p>There are more sophisticated solutions, as well. Cisco,

F5, and several other companies sell hardware load

balancers (typically used in pairs for redundancy), which

offer sophisticated load balancing and auto-failover

features. There are software packages which offer similar

features on commodity hardware, as well. If you have

enough money or need, check these out. The <a

href="http://vegan.net/lb/">lb-l mailing list</a> is a

good place to research.</p>

</li>

</ol>

</dd>

</dl>

</section>

<section id="new-mime-type">

<title>New MIME-type, New Service</title>

<dl>

<dt>Description:</dt>

<dd>

<p>On the net there are many nifty CGI programs. But

their usage is usually boring, so a lot of webmasters

don't use them. Even Apache's Action handler feature for

MIME-types is only appropriate when the CGI programs

don't need special URLs (actually <code>PATH_INFO</code>

and <code>QUERY_STRINGS</code>) as their input. First,

let us configure a new file type with extension

<code>.scgi</code> (for secure CGI) which will be processed

by the popular <code>cgiwrap</code> program. The problem

here is that for instance if we use a Homogeneous URL Layout

(see above) a file inside the user homedirs might have a URL

like <code>/u/user/foo/bar.scgi</code>, but

<code>cgiwrap</code> needs URLs in the form

<code>/~user/foo/bar.scgi/</code>. The following rule

solves the problem:</p>

<example><pre>

RewriteRule ^/[uge]/<strong>([^/]+)</strong>/\.www/(.+)\.scgi(.*) ...

... /internal/cgi/user/cgiwrap/~<strong>$1</strong>/$2.scgi$3 [NS,<strong>T=application/x-http-cgi</strong>]

</pre></example>

<p>Or assume we have some more nifty programs:

<code>wwwlog</code> (which displays the

<code>access.log</code> for a URL subtree) and

<code>wwwidx</code> (which runs Glimpse on a URL

subtree). We have to provide the URL area to these

programs so they know which area they are really working with.

But usually this is complicated, because they may still be

requested by the alternate URL form, i.e., typically we would

run the <code>swwidx</code> program from within

<code>/u/user/foo/</code> via hyperlink to</p>

<example><pre>

/internal/cgi/user/swwidx?i=/u/user/foo/

</pre></example>

<p>which is ugly, because we have to hard-code

<strong>both</strong> the location of the area

<strong>and</strong> the location of the CGI inside the

hyperlink. When we have to reorganize, we spend a

lot of time changing the various hyperlinks.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>The solution here is to provide a special new URL format

which automatically leads to the proper CGI invocation.

We configure the following:</p>

<example><pre>

RewriteRule ^/([uge])/([^/]+)(/?.*)/\* /internal/cgi/user/wwwidx?i=/$1/$2$3/

RewriteRule ^/([uge])/([^/]+)(/?.*):log /internal/cgi/user/wwwlog?f=/$1/$2$3

</pre></example>

<p>Now the hyperlink to search at

<code>/u/user/foo/</code> reads only</p>

<example><pre>

HREF="*"

</pre></example>

<p>which internally gets automatically transformed to</p>

<example><pre>

/internal/cgi/user/wwwidx?i=/u/user/foo/

</pre></example>

<p>The same approach leads to an invocation for the

access log CGI program when the hyperlink

<code>:log</code> gets used.</p>

</dd>

</dl>

</section>

<section id="on-the-fly-content">

<title>On-the-fly Content-Regeneration</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Here comes a really esoteric feature: Dynamically

generated but statically served pages, i.e., pages should be

delivered as pure static pages (read from the filesystem

and just passed through), but they have to be generated

dynamically by the web server if missing. This way you can

have CGI-generated pages which are statically served unless an

admin (or a <code>cron</code> job) removes the static contents. Then the

contents gets refreshed.</p>

</dd>

<dt>Solution:</dt>

<dd>

This is done via the following ruleset:

<example><pre>

# This example is valid in per-directory context only

RewriteCond %{REQUEST_FILENAME} <strong>!-s</strong>

RewriteRule ^page\.<strong>html</strong>$ page.<strong>cgi</strong> [T=application/x-httpd-cgi,L]

</pre></example>

<p>Here a request for <code>page.html</code> leads to an

internal run of a corresponding <code>page.cgi</code> if

<code>page.html</code> is missing or has filesize

null. The trick here is that <code>page.cgi</code> is a

CGI script which (additionally to its <code>STDOUT</code>)

writes its output to the file <code>page.html</code>.

Once it has completed, the server sends out

<code>page.html</code>. When the webmaster wants to force

a refresh of the contents, he just removes

<code>page.html</code> (typically from <code>cron</code>).</p>

</dd>

</dl>

</section>

<section id="autorefresh">

<title>Document With Autorefresh</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Wouldn't it be nice, while creating a complex web page, if

the web browser would automatically refresh the page every

time we save a new version from within our editor?

Impossible?</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>No! We just combine the MIME multipart feature, the

web server NPH feature, and the URL manipulation power of

<module>mod_rewrite</module>. First, we establish a new

URL feature: Adding just <code>:refresh</code> to any

URL causes the 'page' to be refreshed every time it is

updated on the filesystem.</p>

<example><pre>

RewriteRule ^(/[uge]/[^/]+/?.*):refresh /internal/cgi/apache/nph-refresh?f=$1

</pre></example>

<p>Now when we reference the URL</p>

<example><pre>

/u/foo/bar/page.html:refresh

</pre></example>

<p>this leads to the internal invocation of the URL</p>

<example><pre>

/internal/cgi/apache/nph-refresh?f=/u/foo/bar/page.html

</pre></example>

<p>The only missing part is the NPH-CGI script. Although

one would usually say "left as an exercise to the reader"

;-) I will provide this, too.</p>

<example><pre>

#!/sw/bin/perl

##

## nph-refresh -- NPH/CGI script for auto refreshing pages

## Copyright (c) 1997 Ralf S. Engelschall, All Rights Reserved.

##

$| = 1;

# split the QUERY_STRING variable

@pairs = split(/&amp;/, $ENV{'QUERY_STRING'});

foreach $pair (@pairs) {

($name, $value) = split(/=/, $pair);

$name =~ tr/A-Z/a-z/;

$name = 'QS_' . $name;

$value =~ s/%([a-fA-F0-9][a-fA-F0-9])/pack("C", hex($1))/eg;

eval "\$$name = \"$value\"";

}

$QS_s = 1 if ($QS_s eq '');

$QS_n = 3600 if ($QS_n eq '');

if ($QS_f eq '') {

print "HTTP/1.0 200 OK\n";

print "Content-type: text/html\n\n";

print "&amp;lt;b&amp;gt;ERROR&amp;lt;/b&amp;gt;: No file given\n";

exit(0);

}

if (! -f $QS_f) {

print "HTTP/1.0 200 OK\n";

print "Content-type: text/html\n\n";

print "&amp;lt;b&amp;gt;ERROR&amp;lt;/b&amp;gt;: File $QS_f not found\n";

exit(0);

}

sub print_http_headers_multipart_begin {

print "HTTP/1.0 200 OK\n";

$bound = "ThisRandomString12345";

print "Content-type: multipart/x-mixed-replace;boundary=$bound\n";

&amp;print_http_headers_multipart_next;

}

sub print_http_headers_multipart_next {

print "\n--$bound\n";

}

sub print_http_headers_multipart_end {

print "\n--$bound--\n";

}

sub displayhtml {

local($buffer) = @_;

$len = length($buffer);

print "Content-type: text/html\n";

print "Content-length: $len\n\n";

print $buffer;

}

sub readfile {

local($file) = @_;

local(*FP, $size, $buffer, $bytes);

($x, $x, $x, $x, $x, $x, $x, $size) = stat($file);

$size = sprintf("%d", $size);

open(FP, "&amp;lt;$file");

$bytes = sysread(FP, $buffer, $size);

close(FP);

return $buffer;

}

$buffer = &amp;readfile($QS_f);

&amp;print_http_headers_multipart_begin;

&amp;displayhtml($buffer);

sub mystat {

local($file) = $_[0];

local($time);

($x, $x, $x, $x, $x, $x, $x, $x, $x, $mtime) = stat($file);

return $mtime;

}

$mtimeL = &amp;mystat($QS_f);

$mtime = $mtime;

for ($n = 0; $n &amp;lt; $QS_n; $n++) {

while (1) {

$mtime = &amp;mystat($QS_f);

if ($mtime ne $mtimeL) {

$mtimeL = $mtime;

sleep(2);

$buffer = &amp;readfile($QS_f);

&amp;print_http_headers_multipart_next;

&amp;displayhtml($buffer);

sleep(5);

$mtimeL = &amp;mystat($QS_f);

last;

}

sleep($QS_s);

}

}

&amp;print_http_headers_multipart_end;

exit(0);

##EOF##

</pre></example>

</dd>

</dl>

</section>

<section id="mass-virtual-hosting">

<title>Mass Virtual Hosting</title>

<dl>

<dt>Description:</dt>

<dd>

<p>The <directive type="section" module="core"

>VirtualHost</directive> feature of Apache is nice

and works great when you just have a few dozen

virtual hosts. But when you are an ISP and have hundreds of

virtual hosts, this feature is suboptimal.</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>To provide this feature we map the remote web page or even

the complete remote web area to our namespace using the

<dfn>Proxy Throughput</dfn> feature (flag <code>[P]</code>):</p>

<example><pre>

##

## vhost.map

##

www.vhost1.dom:80 /path/to/docroot/vhost1

www.vhost2.dom:80 /path/to/docroot/vhost2

:

www.vhostN.dom:80 /path/to/docroot/vhostN

</pre></example>

<example><pre>

##

## httpd.conf

##

:

# use the canonical hostname on redirects, etc.

UseCanonicalName on

:

# add the virtual host in front of the CLF-format

CustomLog /path/to/access_log "%{VHOST}e %h %l %u %t \"%r\" %&gt;s %b"

:

# enable the rewriting engine in the main server

RewriteEngine on

# define two maps: one for fixing the URL and one which defines

# the available virtual hosts with their corresponding

# DocumentRoot.

RewriteMap lowercase int:tolower

RewriteMap vhost txt:/path/to/vhost.map

# Now do the actual virtual host mapping

# via a huge and complicated single rule:

#

# 1. make sure we don't map for common locations

RewriteCond %{REQUEST_URI} !^/commonurl1/.*

RewriteCond %{REQUEST_URI} !^/commonurl2/.*

:

RewriteCond %{REQUEST_URI} !^/commonurlN/.*

#

# 2. make sure we have a Host header, because

# currently our approach only supports

# virtual hosting through this header

RewriteCond %{HTTP_HOST} !^$

#

# 3. lowercase the hostname

RewriteCond ${lowercase:%{HTTP_HOST}|NONE} ^(.+)$

#

# 4. lookup this hostname in vhost.map and

# remember it only when it is a path

# (and not "NONE" from above)

RewriteCond ${vhost:%1} ^(/.*)$

#

# 5. finally we can map the URL to its docroot location

# and remember the virtual host for logging purposes

RewriteRule ^/(.*)$ %1/$1 [E=VHOST:${lowercase:%{HTTP_HOST}}]

:

</pre></example>

</dd>

</dl>

</section>

<section id="proxy-deny">

<title>Proxy Deny</title>

<dl>

<dt>Description:</dt>

<dd>

<p>How can we forbid a certain host or even a user of a

special host from using the Apache proxy?</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We first have to make sure <module>mod_rewrite</module>

is below(!) <module>mod_proxy</module> in the Configuration

file when compiling the Apache web server. This way it gets

called <em>before</em> <module>mod_proxy</module>. Then we

configure the following for a host-dependent deny...</p>

<example><pre>

RewriteCond %{REMOTE_HOST} <strong>^badhost\.mydomain\.com$</strong>

RewriteRule !^http://[^/.]\.mydomain.com.* - [F]

</pre></example>

<p>...and this one for a user@host-dependent deny:</p>

<example><pre>

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>^badguy@badhost\.mydomain\.com$</strong>

RewriteRule !^http://[^/.]\.mydomain.com.* - [F]

</pre></example>

</dd>

</dl>

</section>

<section id="special-authentication">

<title>Special Authentication Variant</title>

<dl>

<dt>Description:</dt>

<dd>

<p>Sometimes very special authentication is needed, for

instance authentication which checks for a set of

explicitly configured users. Only these should receive

access and without explicit prompting (which would occur

when using Basic Auth via <module>mod_auth_basic</module>).</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>We use a list of rewrite conditions to exclude all except

our friends:</p>

<example><pre>

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend1@client1.quux-corp\.com$</strong>

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend2</strong>@client2.quux-corp\.com$

RewriteCond %{REMOTE_IDENT}@%{REMOTE_HOST} <strong>!^friend3</strong>@client3.quux-corp\.com$

RewriteRule ^/~quux/only-for-friends/ - [F]

</pre></example>

</dd>

</dl>

</section>

<section id="referer-deflector">

<title>Referer-based Deflector</title>

<dl>

<dt>Description:</dt>

<dd>

<p>How can we program a flexible URL Deflector which acts

on the "Referer" HTTP header and can be configured with as

many referring pages as we like?</p>

</dd>

<dt>Solution:</dt>

<dd>

<p>Use the following really tricky ruleset...</p>

<example><pre>

RewriteMap deflector txt:/path/to/deflector.map

RewriteCond %{HTTP_REFERER} !=""

RewriteCond ${deflector:%{HTTP_REFERER}} ^-$

RewriteRule ^.* %{HTTP_REFERER} [R,L]

RewriteCond %{HTTP_REFERER} !=""

RewriteCond ${deflector:%{HTTP_REFERER}|NOT-FOUND} !=NOT-FOUND

RewriteRule ^.* ${deflector:%{HTTP_REFERER}} [R,L]

</pre></example>

<p>... in conjunction with a corresponding rewrite

map:</p>

<example><pre>

##

## deflector.map

##

http://www.badguys.com/bad/index.html -

http://www.badguys.com/bad/index2.html -

http://www.badguys.com/bad/index3.html http://somewhere.com/

</pre></example>

<p>This automatically redirects the request back to the

referring page (when "<code>-</code>" is used as the value

in the map) or to a specific URL (when an URL is specified

in the map as the second argument).</p>

</dd>

</dl>

</section>

</manualpage>