<?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="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="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="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="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="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="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="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>

</manualpage>