>
<!--#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
<h2>Summary</h2>
This module uses a rule-based rewriting engine (based on a
-regular-expression parser) to rewrite requested URLs on the fly.
+regular-expression parser) to rewrite requested URLs on the fly.
<p>
It supports an unlimited number of additional rule conditions (which can
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 © 1996,1997 <b>The Apache Group</b>, All rights reserved.<br>
-Copyright © 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>
- <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a>
+ <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a>
</blockquote>
<!--%hypertext -->
The <tt>RewriteEngine</tt> directive enables or disables the
runtime rewriting engine. If it is set to <code>off</code> this module does
no runtime processing at all. It does not even update the <tt>SCRIPT_URx</tt>
-environment variables.
+environment variables.
<p>
Use this directive to disable the module instead of commenting out
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>
server logs any rewriting actions it performs. If the name does not begin
with a slash ('<tt>/</tt>') then it is assumed to be relative to the
<em>Server Root</em>. The directive should occur only once per server
-config.
+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
#
-Ralf.S.Engelschall rse # Bastard Operator From Hell
+Ralf.S.Engelschall rse # Bastard Operator From Hell
Dr.Fred.Klabuster fred # Mr. DAU
</pre></td></tr>
</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;
while (<STDIN>) {
- # ...here any transformations
+ # ...here any transformations
# or lookups should occur...
print $_;
}
mapping-function use one <tt>RewriteMap</tt> directive to declare its
rewriting mapfile. While you cannot <b>declare</b> a map in per-directory
context it is of course possible to <b>use</b> this map in per-directory
-context.
+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
prefix is the corresponding filepath itself. <b>But at most websites URLs are
<b>NOT</b> directly related to physical filename paths, so this assumption
will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt>
-directive to specify the correct URL-prefix.
+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
RewriteEngine On
-# let the server know that we are reached via /xyz and not
+# let the server know that we are reached via /xyz and not
# via the physical path prefix /abc/def
RewriteBase /xyz
<p>
In the above example, a request to <tt>/xyz/oldstuff.html</tt> gets correctly
-rewritten to the physical file <tt>/abc/def/newstuff.html</tt>.
+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>
when it occurs the (rewritten) request has to be re-injected into the Apache
kernel! BUT: While this seems like a serious overhead, it really isn't, because
this re-injection happens fully internal to the Apache server and the same
-procedure is used by many other operations inside Apache. So, you can be
+procedure is used by many other operations inside Apache. So, you can be
sure the design and implementation is correct.
</font>
</td></tr>
<em>TestString</em> is a string which contains server-variables of the form
<blockquote><strong>
-<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt>
+<tt>%{</tt> <em>NAME_OF_VARIABLE</em> <tt>}</tt>
</strong></blockquote>
where <em>NAME_OF_VARIABLE</em> can be a string
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
<em>CondPattern</em> is the condition pattern, i.e. a regular expression
which gets applied to the current instance of the <em>TestString</em>, i.e.
<em>TestString</em> gets evaluated and then matched against
-<em>CondPattern</em>.
+<em>CondPattern</em>.
<p>
<b>Remember:</b> <em>CondPattern</em> is a standard
regular expression strings you can also use one of the following:
<p>
<ul>
+<li>'<b><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>>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.
<blockquote><pre>
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
-RewriteCond %{REMOTE_HOST} ^host3.*
+RewriteCond %{REMOTE_HOST} ^host3.*
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>
<strong><code>^</code></strong> Start of line
<strong><code>$</code></strong> End of line
<strong><code>.</code></strong> Any single character
-<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars
-<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars
+<strong><code>[</code></strong>chars<strong><code>]</code></strong> One of chars
+<strong><code>[^</code></strong>chars<strong><code>]</code></strong> None of chars
<strong><code>?</code></strong> 0 or 1 of the preceding char
<strong><code>*</code></strong> 0 or N of the preceding char
<strong><code>+</code></strong> 1 or N of the preceding char
-<strong><code>\</code></strong>char escape that specific char
+<strong><code>\</code></strong>char escape that specific char
(e.g. for specifying the chars "<code>.[]()</code>" etc.)
<strong><code>(</code></strong>string<strong><code>)</code></strong> Grouping of chars (the <b>N</b>th group can be used on the RHS with <code>$</code><b>N</b>)
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
<p>
<a name="rhs"><em>Substitution</em></a> of a rewriting rule is the string
which is substituted for (or replaces) the original URL for which
-<em>Pattern</em> matched. Beside plain text you can use
+<em>Pattern</em> matched. Beside plain text you can use
<ol>
<li>pattern-group back-references (<code>$N</code>)
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
<ul>
<li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br>
- Prefix <em>Substitution</em>
+ Prefix <em>Substitution</em>
with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to
force a external redirection. If no <i>code</i> is given a HTTP response
of 302 (MOVED TEMPORARILY) is used. If you want to use other response
codes in the range 300-400 just specify them as a number or use
one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>,
<tt>seeother</tt>.
- Use it for rules which should
+ Use it for rules which should
canonicalize the URL and gives it back to the client, e.g. translate
``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to
<code>/u/</code><em>user</em>, etc.<br>
from the last rewriting rule. This corresponds to the Perl
<code>next</code> command or the <code>continue</code> command from the C
language. Use this flag to restart the rewriting process, i.e. to
- immediately go to the top of the loop. <br>
+ immediately go to the top of the loop. <br>
<b>But be careful not to create a deadloop!</b>
<p>
<li>'<strong><code>chain|C</code></strong>' (<b>c</b>hained with next rule)<br>
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
with <tt>mod_alias</tt>:
<pre>
RewriteRule ^/abc(.*) /def$1 [PT]
- Alias /def /ghi
+ Alias /def /ghi
</pre>
If you omit the <tt>PT</tt> flag then <tt>mod_rewrite</tt>
will do its job fine, i.e. it rewrites <tt>uri=/abc/...</tt> to
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>
<tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>).
But additionally you can also dereference it in a following RewriteCond
pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember
- information from URLs.
+ information from URLs.
</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>
projects / thirdparty / apache / httpd.git / commitdiff
