Merge in documentation update from HEAD.

>

>

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

<!--#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

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

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

substitution.

substitution.

<p>

<p>

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

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

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

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

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

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

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

<p>

<p>

The latest version can be found on<br>

This module was originally written in April 1996 and 

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

gifted exclusively to the The Apache Group in July 1997 by

<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.

<p>

<p>

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

<blockquote>

<blockquote>

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

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

    <a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><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

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

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

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

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

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

<p>

</ul>

</ul>

<p>

<p>

config.

config.

<p>

<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>

<tr><td>

To disable the logging of rewriting actions it is not recommended

To disable the logging of rewriting actions it is not recommended

to set <em>Filename</em>

to set <em>Filename</em>

</table>

</table>

<p>

<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>

<tr><td>

SECURITY: See the <a

SECURITY: See the <a

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

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

This disables all rewrite action logs.

This disables all rewrite action logs.

<p>

<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>

<tr><td>

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

<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

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

    string as in the following example:

    string as in the following example:

<p>

<p>

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

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

<tr><td><pre>

<tr><td><pre>

#

#

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

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

</table>

</table>

<p>

<p>

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

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

<tr><td><pre>

<tr><td><pre>

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

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

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

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

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

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

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

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

    <p>

    <p>

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

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

<tr><td><pre>

<tr><td><pre>

#!/usr/bin/perl

#!/usr/bin/perl

$| = 1;

$| = 1;

context.

context.

<p>

<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>

<tr><td>

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

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

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

directive to specify the correct URL-prefix.

directive to specify the correct URL-prefix.

<p>

<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>

<tr><td>

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

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

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

   Assume the following per-directory config file:

   Assume the following per-directory config file:

<p>

<p>

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

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

<tr><td><pre>

<tr><td><pre>

#

#

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

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

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

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

<p>

<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>

<tr><td>

<font size=-1>

<font size=-1>

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

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

of the following list:

of the following list:

<p>

<p>

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

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

<tr>

<tr>

<td valign=top>

<td valign=top>

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

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

TIME_MIN<br>

TIME_MIN<br>

TIME_SEC<br>

TIME_SEC<br>

TIME_WDAY<br>

TIME_WDAY<br>

TIME<br>

</font>

</font>

</td>

</td>

<p>

<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>

<tr><td>

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

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

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:

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

<p>

<p>

<ul>

<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>

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

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

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

tests if it exists and is a directory.

tests if it exists and is a directory.

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

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

</pre></blockquote>

</pre></blockquote>

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

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

<p>

</ul>

</ul>

<p>

<p>

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

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

use any other browser you get the standard homepage.

use any other browser you get the standard homepage.

</blockquote>

</blockquote>

<p>

<p>

<p>

<hr noshade size=1>

<hr noshade size=1>

Some hints about the syntax of regular expressions:

Some hints about the syntax of regular expressions:

<p>

<p>

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

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

<tr>

<tr>

<td valign=top>

<td valign=top>

<pre>

<pre>

last default rule.

last default rule.

<p>

<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>

<tr><td>

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

<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

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

pattern to be applied before a substitution occurs.

pattern to be applied before a substitution occurs.

<p>

<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>

<tr><td>

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

<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

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.

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

    In these cases, use this flag.

    In these cases, use this flag.

<p>

<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>

<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

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

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

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

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

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

    <tt>mod_rewrite</tt>..

    <tt>mod_rewrite</tt>..

<p>

<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>

<tr><td>

<font size=-1>

<font size=-1>

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

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

</ul>

</ul>

<p>

<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>

<tr><td>

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

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

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

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

</table>

</table>

<p>

<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>

<tr><td>

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

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>

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

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

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

<p>

<p>

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

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

<tr>

<tr>

<td>

<td>

<pre>

<pre>

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

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

<p>

<p>

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

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

<tr>

<tr>

<td>

<td>

<pre>

<pre>

</blockquote>

</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" -->

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

</BODY>

</BODY>

</HTML>

</HTML>