rse 97/07/31 14:27:04
Modified: htdocs/manual/mod Tag: APACHE_1_2_X mod_rewrite.html Log: Merge in documentation update from HEAD. Revision Changes Path No revision No revision 1.9.2.3 +120 -58 apache/htdocs/manual/mod/mod_rewrite.html Index: mod_rewrite.html =================================================================== RCS file: /export/home/cvs/apache/htdocs/manual/mod/mod_rewrite.html,v retrieving revision 1.9.2.2 retrieving revision 1.9.2.3 diff -u -r1.9.2.2 -r1.9.2.3 --- mod_rewrite.html 1997/07/03 06:01:21 1.9.2.2 +++ mod_rewrite.html 1997/07/31 21:27:03 1.9.2.3 @@ -17,7 +17,7 @@ > <!--#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 @@ -31,7 +31,7 @@ <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 @@ -41,24 +41,19 @@ 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:[EMAIL PROTECTED]"><tt>[EMAIL PROTECTED]</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 --> @@ -99,7 +94,7 @@ 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 @@ -126,7 +121,6 @@ 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> @@ -143,10 +137,10 @@ 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> @@ -160,7 +154,7 @@ </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 @@ -197,7 +191,7 @@ 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 @@ -266,19 +260,19 @@ 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> @@ -312,12 +306,12 @@ 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 $_; } @@ -342,10 +336,10 @@ 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 @@ -380,10 +374,10 @@ 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 @@ -399,7 +393,7 @@ 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 @@ -409,7 +403,7 @@ 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 @@ -420,10 +414,10 @@ <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> @@ -450,7 +444,7 @@ 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> @@ -480,14 +474,14 @@ <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> @@ -543,6 +537,7 @@ TIME_MIN<br> TIME_SEC<br> TIME_WDAY<br> +TIME<br> </font> </td> @@ -561,7 +556,7 @@ <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 @@ -606,7 +601,7 @@ <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 @@ -622,6 +617,22 @@ 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. @@ -678,11 +689,10 @@ <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> @@ -708,7 +718,6 @@ 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> @@ -738,21 +747,21 @@ 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>) @@ -769,7 +778,7 @@ 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 @@ -782,7 +791,7 @@ <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>) @@ -813,7 +822,14 @@ 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 @@ -842,14 +858,14 @@ <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> @@ -902,7 +918,7 @@ 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> @@ -935,6 +951,13 @@ 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 @@ -948,7 +971,7 @@ 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 @@ -961,7 +984,7 @@ 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> @@ -990,11 +1013,11 @@ <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 @@ -1011,7 +1034,7 @@ </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> @@ -1030,7 +1053,7 @@ 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> @@ -1077,7 +1100,7 @@ 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> @@ -1147,6 +1170,45 @@ RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 </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>
