Merge in documentation update from HEAD.

>

<!--#include virtual="header.html" -->

<h1 ALIGN="CENTER">Module mod_rewrite (Version 3.0)</h1>

<h1 ALIGN="CENTER">Module mod_rewrite</h1>

This module is contained in the <code>mod_rewrite.c</code> file, with Apache

1.2 and later.  It provides a rule-based rewriting engine to rewrite requested

substitution.

<p>

It operates on the full URLs (including the PATH_INFO part) both in

per-server context (httpd.conf) and per-dir context (.htaccess) and even

can generate QUERY_STRING parts on result.   The rewritten result can lead to internal sub-processing, external request redirection or to internal proxy throughput.

It operates on the full URLs (including the PATH_INFO part) both in per-server

context (httpd.conf) and per-dir context (.htaccess) and even can generate

QUERY_STRING parts on result.   The rewritten result can lead to internal

sub-processing, external request redirection or to internal proxy throughput.

<p>

The latest version can be found on<br>

<a href="http://www.engelschall.com/sw/mod_rewrite/">

<code><b>http://www.engelschall.com/sw/mod_rewrite/</b></code></a>

<p>

Copyright &copy; 1996,1997 <b>The Apache Group</b>, All rights reserved.<br>

Copyright &copy; 1996,1997 <i>Ralf S. Engelschall</i>, All rights reserved.

This module was originally written in April 1996 and 

gifted exclusively to the The Apache Group in July 1997 by

<p>

Written for <b>The Apache Group</b> by

<blockquote>

    <i>Ralf S. Engelschall</i><br>

    <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br>

    conditions and rules of the main server gets inherited. In per-directory

    context this means that conditions and rules of the parent directory's

    <tt>.htaccess</tt> configuration gets inherited.

<p>

</ul>

<p>

config.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10>

<tr><td>

To disable the logging of rewriting actions it is not recommended

to set <em>Filename</em>

</table>

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

SECURITY: See the <a

href="../misc/security_tips.html">Apache Security

This disables all rewrite action logs.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10>

<tr><td>

<b>Notice:</b> Using a high value for <i>Level</i> will slow down your Apache

server dramatically! Use the rewriting logfile only for debugging or at least

    string as in the following example:

<p>

<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">

<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0">

<tr><td><pre>

#

#   map.real-to-user -- maps realnames to usernames

</table>

<p>

<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">

<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0">

<tr><td><pre>

RewriteMap real-to-host txt:/path/to/file/map.real-to-user

</pre></td></tr>

    for the given key). A trivial program which will implement a 1:1 map

    (i.e. key == value) could be:

    <p>

<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">

<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0">

<tr><td><pre>

#!/usr/bin/perl

$| = 1;

context.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10>

<tr><td>

For plain text and DBM format files the looked-up keys are cached in-core

until the <tt>mtime</tt> of the mapfile changes or the server does a

directive to specify the correct URL-prefix.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

So, if your webserver's URLs are <b>not</b> directly

related to physical file paths, you have to use <tt>RewriteBase</tt> in every

   Assume the following per-directory config file:

<p>

<table border=2 cellspacing=1 cellpadding=5 bgcolor="#d0d0d0">

<table border=0 cellspacing=1 cellpadding=5 bgcolor="#f0f0f0">

<tr><td><pre>

#

#  /abc/def/.htaccess -- per-dir config file for directory /abc/def

rewritten to the physical file <tt>/abc/def/newstuff.html</tt>.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

<font size=-1>

<b>For the Apache hackers:</b><br>

of the following list:

<p>

<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>

<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5>

<tr>

<td valign=top>

<b>HTTP headers:</b><p>

TIME_MIN<br>

TIME_SEC<br>

TIME_WDAY<br>

TIME<br>

</font>

</td>

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#f0f0f0" cellspacing=0 cellpadding=10>

<tr><td>

These variables all correspond to the similar named HTTP MIME-headers, C

variables of the Apache server or <tt>struct tm</tt> fields of the Unix

regular expression strings you can also use one of the following:

<p>

<ul>

<li>'<b>&lt;CondPattern</b>' (is lexicographically lower)<br>

Treats the <i>CondPattern</i> as a plain string and compares it

lexicographically to <i>TestString</i> and results in a true expression if

<i>TestString</i> is lexicographically lower then <i>CondPattern</i>.

<p>

<li>'<b>&gt;CondPattern</b>' (is lexicographically greater)<br>

Treats the <i>CondPattern</i> as a plain string and compares it

lexicographically to <i>TestString</i> and results in a true expression if

<i>TestString</i> is lexicographically greater then <i>CondPattern</i>.

<p>

<li>'<b>=CondPattern</b>' (is lexicographically equal)<br>

Treats the <i>CondPattern</i> as a plain string and compares it

lexicographically to <i>TestString</i> and results in a true expression if

<i>TestString</i> is lexicographically equal to <i>CondPattern</i>, i.e the

two strings are exactly equal (character by character).

<p>

<li>'<b>-d</b>' (is <b>d</b>irectory)<br>

Treats the <i>TestString</i> as a pathname and

tests if it exists and is a directory.

RewriteRule ...some special stuff for any of these hosts...

</pre></blockquote>

    Without this flag you had to write down the cond/rule three times.

<p>

</ul>

<p>

get the min homepage, which contains no images, no tables, etc.  If you

use any other browser you get the standard homepage.

</blockquote>

<p>

<p>

<hr noshade size=1>

Some hints about the syntax of regular expressions:

<p>

<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>

<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5>

<tr>

<td valign=top>

<pre>

last default rule.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

<b>Notice!</b> When using the NOT character to negate a pattern you cannot

have grouped wildcard parts in the pattern. This is impossible because when

pattern to be applied before a substitution occurs.

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

One more note: You can even create URLs in the substitution string containing

a query string part. Just use a question mark inside the substitution string

to indicate that the following stuff should be re-injected into the

QUERY_STRING.  When you want to erase an existing query string, end the

substitution string with just the question mark.

<p>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

<b>Notice</b>: There is a special feature. When you prefix a substitution

field with <tt>http://</tt><em>thishost</em>[<em>:thisport</em>] then

    chance is high that you will run into problems (or even overhead) on sub-requests.

    In these cases, use this flag.

<p>

<li>'<strong><code>qsappend|QSA</code></strong>' (<b>q</b>uery <b>s</b>tring

    <b>a</b>ppend)<br> 

    This flag forces the rewriting engine to append a query

    string part in the substitution string to the existing one instead of

    replacing it.  Use this when you want to add more data to the query string

    via a rewrite rule.

<p>

<li>'<strong><code>passthrough|PT</code></strong>' (<b>p</b>ass <b>t</b>hrough to next handler)<br>

    This flag forces the rewriting engine to set the <code>uri</code> field

    of the internal <code>request_rec</code> structure to the value

    typical example is the use of <tt>mod_alias</tt> and

    <tt>mod_rewrite</tt>..

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

<font size=-1>

    <b>For the Apache hackers:</b><br>

</ul>

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

Remember: Never forget that <em>Pattern</em> gets applied to a complete URL

in per-server configuration files. <b>But in per-directory configuration

</table>

<p>

<table width="70%" border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>

<table width="70%" border=0 bgcolor="#fff0f0" cellspacing=0 cellpadding=10>

<tr><td>

Notice!  To enable the rewriting engine for per-directory configuration files

you need to set ``<tt>RewriteEngine On</tt>'' in these files <b>and</b>

for request ``<tt>GET /somepath/pathinfo</tt>'':</b><br>

<p>

<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>

<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5>

<tr>

<td>

<pre>

request ``<tt>GET /somepath/localpath/pathinfo</tt>'':</b><br>

<p>

<table bgcolor="#d0d0d0" cellspacing=0 cellpadding=5>

<table bgcolor="#f0f0f0" cellspacing=0 cellpadding=5>

<tr>

<td>

<pre>

</blockquote>

<!--%hypertext -->

<hr>

<!--/%hypertext -->

<center>

<a name="Additional">

<h1>Additional Features</h1>

</a>

</center>

<a name="EnvVar">

<h2>Environment Variables</h2>

</a>

This module keeps track of two additional (non-standard) CGI/SSI environment

variables named <tt>SCRIPT_URL</tt> and <tt>SCRIPT_URI</tt>. These contain

the <em>logical</em> Web-view to the current resource, while the standard CGI/SSI

variables <tt>SCRIPT_NAME</tt> and <tt>SCRIPT_FILENAME</tt> contain the

<em>physical</em> System-view. 

<p>

Notice: These variables hold the URI/URL <em>as they were initially

requested</em>, i.e. in a state <em>before</em> any rewriting. This is

important because the rewriting process is primarily used to rewrite logical

URLs to physical pathnames.

<p>

<b>Example:</b>

<blockquote>

<pre>

SCRIPT_NAME=/v/sw/free/lib/apache/global/u/rse/.www/index.html

SCRIPT_FILENAME=/u/rse/.www/index.html

SCRIPT_URL=/u/rse/

SCRIPT_URI=http://en2.en.sdm.de/u/rse/

</pre>

</blockquote>

<!--#include virtual="footer.html" -->

</BODY>

</HTML>