From 2bb655ccdfad14727d3a3bbe56713448a6e6635e Mon Sep 17 00:00:00 2001 From: "Ralf S. Engelschall" Date: Thu, 31 Jul 1997 21:27:03 +0000 Subject: [PATCH] Merge in documentation update from HEAD. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/APACHE_1_2_X@78839 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_rewrite.html | 178 +++++++++++++++++++++---------- 1 file changed, 120 insertions(+), 58 deletions(-) diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index 4cb6c83b85c..ce8731c2591 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -17,7 +17,7 @@ > -

Module mod_rewrite (Version 3.0)

+

Module mod_rewrite

This module is contained in the mod_rewrite.c file, with Apache 1.2 and later. It provides a rule-based rewriting engine to rewrite requested @@ -31,7 +31,7 @@ in the server build Configuration file:

Summary

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.

It supports an unlimited number of additional rule conditions (which can @@ -41,24 +41,19 @@ tables, DBM hash files or external processes) for advanced URL substitution.

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

-The latest version can be found on
- -http://www.engelschall.com/sw/mod_rewrite/ - -

-Copyright © 1996,1997 The Apache Group, All rights reserved.
-Copyright © 1996,1997 Ralf S. Engelschall, All rights reserved. +This module was originally written in April 1996 and +gifted exclusively to the The Apache Group in July 1997 by

-Written for The Apache Group by

Ralf S. Engelschall
rse@engelschall.com
- www.engelschall.com + www.engelschall.com
@@ -99,7 +94,7 @@ Written for The Apache Group by The RewriteEngine directive enables or disables the runtime rewriting engine. If it is set to off this module does no runtime processing at all. It does not even update the SCRIPT_URx -environment variables. +environment variables.

Use this directive to disable the module instead of commenting out @@ -126,7 +121,6 @@ strings can be one of the following: conditions and rules of the main server gets inherited. In per-directory context this means that conditions and rules of the parent directory's .htaccess configuration gets inherited. -

@@ -143,10 +137,10 @@ The RewriteLog directive sets the name of the file to which the server logs any rewriting actions it performs. If the name does not begin with a slash ('/') then it is assumed to be relative to the Server Root. The directive should occur only once per server -config. +config.

- +
To disable the logging of rewriting actions it is not recommended to set Filename @@ -160,7 +154,7 @@ To disable logging either remove or comment out the

- +
SECURITY: See the Apache Security @@ -197,7 +191,7 @@ To disable the logging of rewriting actions simply set Level to 0. This disables all rewrite action logs.

- +
Notice: Using a high value for Level will slow down your Apache server dramatically! Use the rewriting logfile only for debugging or at least @@ -266,19 +260,19 @@ of the following formats: string as in the following example:

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

- +
@@ -312,12 +306,12 @@ RewriteMap real-to-host txt:/path/to/file/map.real-to-user for the given key). A trivial program which will implement a 1:1 map (i.e. key == value) could be:

-

 RewriteMap real-to-host txt:/path/to/file/map.real-to-user
+
 #!/usr/bin/perl
 $| = 1;
 while (<STDIN>) {
-    # ...here any transformations 
+    # ...here any transformations
     # or lookups should occur...
     print $_;
 }
@@ -342,10 +336,10 @@ The RewriteMap directive can occur more than once. For each
 mapping-function use one RewriteMap directive to declare its
 rewriting mapfile. While you cannot declare a map in per-directory
 context it is of course possible to use this map in per-directory
-context.  
+context.
 
 

-
+

 

 For plain text and DBM format files the looked-up keys are cached in-core
 until the mtime of the mapfile changes or the server does a
@@ -380,10 +374,10 @@ to know what the corresponding URL-prefix or URL-base is. By default this
 prefix is the corresponding filepath itself. But at most websites URLs are
 NOT directly related to physical filename paths, so this assumption
 will be usually be wrong! There you have to use the RewriteBase
-directive to specify the correct URL-prefix. 
+directive to specify the correct URL-prefix.
 
 

-
+

 

 So, if your webserver's URLs are not directly
 related to physical file paths, you have to use RewriteBase in every
@@ -399,7 +393,7 @@ directives.
    Assume the following per-directory config file:
 
 

-
+

 
 #
 #  /abc/def/.htaccess -- per-dir config file for directory /abc/def
@@ -409,7 +403,7 @@ directives.
 
 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 @@ RewriteRule   ^oldstuff\.html$  newstuff.html
 
 

 In the above example, a request to /xyz/oldstuff.html gets correctly
-rewritten to the physical file /abc/def/newstuff.html. 
+rewritten to the physical file /abc/def/newstuff.html.
 
 

-
+

@@ -480,14 +474,14 @@ state of the URI AND if these additional conditions apply, too.
 TestString is a string which contains server-variables of the form
 
 

-%{ NAME_OF_VARIABLE } 
+%{ NAME_OF_VARIABLE }
 

 
 where NAME_OF_VARIABLE can be a string
 of the following list:
 
 

-

 

 
 For the Apache hackers:

@@ -450,7 +444,7 @@ because the per-directory rewriting comes too late in the process.  So,
 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.
 
 

+

 
@@ -561,7 +556,7 @@ IS_SUBREQ

-

 

 
 HTTP headers:

@@ -543,6 +537,7 @@ TIME_HOUR

 TIME_MIN

 TIME_SEC

 TIME_WDAY

+TIME

 
 

 
 
 

+

 

 These variables all correspond to the similar named HTTP MIME-headers, C
 variables of the Apache server or struct tm fields of the Unix
@@ -606,7 +601,7 @@ look-ahead for the final value of file.
 CondPattern is the condition pattern, i.e. a regular expression
 which gets applied to the current instance of the TestString, i.e.
 TestString gets evaluated and then matched against
-CondPattern. 
+CondPattern.
 
 

 Remember: CondPattern is a standard
@@ -622,6 +617,22 @@ There are some special variants of CondPatterns. Instead of real
 regular expression strings you can also use one of the following:
 

 
    
+
  • '<CondPattern' (is lexicographically lower)
    
+Treats the CondPattern as a plain string and compares it
+lexicographically to TestString and results in a true expression if
+TestString is lexicographically lower then CondPattern.
+
    
+
  • '>CondPattern' (is lexicographically greater)
    
+Treats the CondPattern as a plain string and compares it
+lexicographically to TestString and results in a true expression if
+TestString is lexicographically greater then CondPattern.
+
    
+
  • '=CondPattern' (is lexicographically equal)
    
+Treats the CondPattern as a plain string and compares it
+lexicographically to TestString and results in a true expression if
+TestString is lexicographically equal to CondPattern, i.e the
+two strings are exactly equal (character by character).
+
    
 
  • '-d' (is directory)
    
 Treats the TestString as a pathname and
 tests if it exists and is a directory.
@@ -678,11 +689,10 @@ is a comma-separated list of the following flags:
 
     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...
 
    
     Without this flag you had to write down the cond/rule three times.
-
    
 

 
 

@@ -708,7 +718,6 @@ Frames, etc. If you use the Lynx browser (which is Terminal-based), then you
 get the min homepage, which contains no images, no tables, etc.  If you
 use any other browser you get the standard homepage.
 
-

 
 

 

@@ -738,21 +747,21 @@ and made alterations to it.
 Some hints about the syntax of regular expressions:
 
 

-
+

 

 
 
 ^           Start of line
 $           End of line
 .           Any single character
-[chars]     One of chars 
-[^chars]    None of chars 
+[chars]     One of chars
+[^chars]    None of chars
 
 ?           0 or 1 of the preceding char
 *           0 or N of the preceding char
 +           1 or N of the preceding char
 
-\char       escape that specific char 
+\char       escape that specific char
             (e.g. for specifying the chars ".[]()" etc.)
 
 (string)    Grouping of chars (the Nth group can be used on the RHS with $N)
@@ -769,7 +778,7 @@ for special cases where it is better to match the negative pattern or as a
 last default rule.
 
 

-
+

 

 Notice! 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 @@ substitution string!
 

 Substitution of a rewriting rule is the string
 which is substituted for (or replaces) the original URL for which
-Pattern matched.  Beside plain text you can use 
+Pattern matched.  Beside plain text you can use
 
 
    
 
  1. pattern-group back-references ($N)
@@ -813,7 +822,14 @@ conjunction with the C (chain) flag to be able to have more than one
 pattern to be applied before a substitution occurs.
 
 
    
-
+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.
+
+
    
+
    
 
    
 Notice: There is a special feature. When you prefix a substitution
 field with http://thishost[:thisport] then
@@ -842,14 +858,14 @@ comma-separated list of the following flags:
 
 
      
 
    • 'redirect|R[=code]' (force redirect)
      
-    Prefix Substitution 
+    Prefix Substitution
     with http://thishost[:thisport]/ (which makes the new URL a URI) to
     force a external redirection. If no code 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: temp (default), permanent,
     seeother.
-    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
     ``/~'' into ``/u/'' or always append a slash to
     /u/user, etc.
      
@@ -902,7 +918,7 @@ comma-separated list of the following flags:
     from the last rewriting rule.  This corresponds to the Perl
     next command or the continue command from the C
     language. Use this flag to restart the rewriting process, i.e.  to
-    immediately go to the top of the loop. 
       
+    immediately go to the top of the loop. 
      
     But be careful not to create a deadloop!
 
      
 
    • 'chain|C' (chained with next rule)
      
@@ -935,6 +951,13 @@ comma-separated list of the following flags:
     chance is high that you will run into problems (or even overhead) on sub-requests.
     In these cases, use this flag.
 
      
+
    • 'qsappend|QSA' (query string
+    append)
       
+    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.
+
      
 
    • 'passthrough|PT' (pass through to next handler)
      
     This flag forces the rewriting engine to set the uri field
     of the internal request_rec structure to the value
@@ -948,7 +971,7 @@ comma-separated list of the following flags:
     with mod_alias:
     
           RewriteRule ^/abc(.*)  /def$1 [PT]
-    Alias       /def       /ghi   
+    Alias       /def       /ghi
     
      
     If you omit the PT flag then mod_rewrite
     will do its job fine, i.e. it rewrites uri=/abc/... to
@@ -961,7 +984,7 @@ comma-separated list of the following flags:
     typical example is the use of mod_alias and
     mod_rewrite..
 
      
-
+
      
 
      
 
     For the Apache hackers:
      
@@ -990,11 +1013,11 @@ comma-separated list of the following flags:
         <!--#echo var="VAR"-->) or CGI (e.g. $ENV{'VAR'}).
         But additionally you can also dereference it in a following RewriteCond
         pattern via %{ENV:VAR}. Use this to strip but remember
-        information from URLs. 
+        information from URLs.
 
 
 
      
-
+
      
 
      
 Remember: Never forget that Pattern gets applied to a complete URL
 in per-server configuration files. But in per-directory configuration
@@ -1011,7 +1034,7 @@ external redirect or proxy throughput (if flag P is used!) is forced!
 
      
 
 
      
-
+
      
 
      
 Notice!  To enable the rewriting engine for per-directory configuration files
 you need to set ``RewriteEngine On'' in these files and
@@ -1030,7 +1053,7 @@ Here are all possible substitution combinations and their meanings:
 for request ``GET /somepath/pathinfo'':
      
 
 
      
-
+
      
 
      
 
 
      @@ -1077,7 +1100,7 @@ for request ``GET /somepath/pathinfo'':
      
 request ``GET /somepath/localpath/pathinfo'':
      
 
 
      
-
+
      
 
      
 
 
      @@ -1150,6 +1173,45 @@ RewriteRule  ^/([^/]+)/~([^/]+)/(.*)$   /u/${real-to-user:$2|nobody}/$3.$1
 
 
 
+
+
      
+
+
+
      
+
+
      Additional Features
      
+      
+
      
+
+
+
      Environment Variables
      
+      
+
+This module keeps track of two additional (non-standard) CGI/SSI environment
+variables named SCRIPT_URL and SCRIPT_URI. These contain
+the logical Web-view to the current resource, while the standard CGI/SSI
+variables SCRIPT_NAME and SCRIPT_FILENAME contain the
+physical System-view. 
+
+
      
+Notice: These variables hold the URI/URL as they were initially
+requested, i.e. in a state before any rewriting. This is
+important because the rewriting process is primarily used to rewrite logical
+URLs to physical pathnames.
+
+
      
+Example:
+
+
      
+
      +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/
+
      
+
      
+
+
 
 
 
-- 
2.47.2