httpd-cvs mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From r..@apache.org (Ralf S. Engelschall)
Subject cvs commit: apache/htdocs/manual/mod mod_rewrite.html
Date Thu, 31 Jul 1997 21:27:05 GMT
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 &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>
  -    <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 (&lt;STDIN&gt;) {
  -    # ...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>&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.
  @@ -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>&lt;!--#echo var="VAR"--&gt;</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>
   
   
  
  
  

Mime
View raw message