From d91d8df242467facfaece42177164c966a67fd68 Mon Sep 17 00:00:00 2001 From: Eric Covener Date: Sun, 21 Dec 2008 08:04:29 +0000 Subject: [PATCH] Various cleanups and per-directory behavior differences Submitted By: Bob Ionescu Reviewed By: covener git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@728399 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_rewrite.html.en | 77 +++++++++++++++++++--------- docs/manual/mod/mod_rewrite.xml | 78 ++++++++++++++++++++--------- 2 files changed, 105 insertions(+), 50 deletions(-) diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index 08226e3f8e..256a141f01 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -103,7 +103,11 @@ URLs on the fly initially requested, that is, before any rewriting. This is important to note because the rewriting process is primarily used to rewrite logical URLs to physical - pathnames.

+ pathnames.
+ These variables are set in per-server context, which means + that they are available in per-directory context only, if + RewriteEngine is set to on in + per-server context.

Example

 SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
@@ -254,7 +258,7 @@ Result:
           (0 <= N <= 9), which provide access to the grouped
           parts (in parentheses) of the pattern, from the
           RewriteRule which is subject to the current 
-          set of RewriteCond conditions..
+          set of RewriteCond conditions.
         
         
  • 
           RewriteCond backreferences: These are
@@ -410,14 +414,26 @@ Result:
       
    Other things you should be aware of:
    
 
       
      
-        
    1. The variables SCRIPT_FILENAME and REQUEST_FILENAME
+        
    2. 
+        
      The variables SCRIPT_FILENAME and REQUEST_FILENAME
         contain the same value - the value of the
         filename field of the internal
         request_rec structure of the Apache server.
         The first name is the commonly known CGI variable name
         while the second is the appropriate counterpart of
         REQUEST_URI (which contains the value of the
-        uri field of request_rec).
      3. 
+        uri field of request_rec).
      
+        
      If a substitution occurred and the rewriting continues,
+        the value of both variables will be updated accordingly.
      
+        
      If used in per-server context (i.e., before the
+        request is mapped to the filesystem) SCRIPT_FILENAME and
+        REQUEST_FILENAME cannot contain the full local filesystem
+        path since the path is unknown at this stage of processing.
+        Both variables will initially contain the value of REQUEST_URI
+        in that case. In order to obtain the full local filesystem
+        path of the request in per-server context, use an URL-based
+        look-ahead %{LA-U:REQUEST_FILENAME} to determine
+        the final value of REQUEST_FILENAME.
      
 
         
    3. 
         %{ENV:variable}, where variable can be
@@ -963,13 +979,14 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map
           looked-up value as a newline-terminated string on
           stdout or the four-character string
           ``NULL'' if it fails (i.e., there
-          is no corresponding value for the given key). A trivial
-          program which will implement a 1:1 map (i.e.,
-          key == value) could be:
      
+          is no corresponding value for the given key).
      
 
           
      External rewriting programs are not started if they're defined in a
           context that does not have RewriteEngine set to
           on
      .
+          
+          
      A trivial program which will implement a 1:1 map (i.e.,
+          key == value) could be:
      
 
 
       #!/usr/bin/perl
@@ -1060,7 +1077,15 @@ later
       this means that the maps, conditions and rules of the main
       server are inherited. In per-directory context this means
       that conditions and rules of the parent directory's
-      .htaccess configuration are inherited.
+      .htaccess configuration or
+      <Directory>
+      sections are inherited. The inherited rules are virtually copied
+      to the section where this directive is being used. If used in
+      combination with local rules, the inherited rules are copied behind
+      the local rules. The position of this directive - below or above
+      of local rules - has no influence on this behavior. If local
+      rules forced the rewriting to stop, the inherited rules won't
+      be processed.
       
 
 
      
@@ -1083,7 +1108,7 @@ later
 
       
      Pattern is
       a perl compatible regular
-      expression. On the first RewriteRule it is applied to the
+      expression. On the first RewriteRule it is applied to the (%-encoded)
       URL-path of the request;
       subsequent patterns are applied to the output of the last matched
       RewriteRule.
      
@@ -1224,13 +1249,15 @@ cannot use $N in the substitution string!
         
      Apache has to unescape URLs before mapping them,
         so backreferences will be unescaped at the time they are applied.
         Using the B flag, non-alphanumeric characters in backreferences
-        will be escaped.  For example, consider the rule:
      
-        
       RewriteRule ^(.*)$ index.php?show=$1 
      
-        
      This will map /C++ to index.php?show=/C++.
+        will be escaped. For example, consider the rule:
+        
      
+        RewriteRule ^(/.*)$ /index.php?show=$1
+        
      
+        This will map /C++ to /index.php?show=/C++.
         But it will also map /C%2b%2b to
-        index.php?show=/C++, because the %2b
+        /index.php?show=/C++, because the %2b
         has been unescaped.  With the B flag, it will instead map to
-        index.php?show=/C%2b%2b.
      
+        /index.php?show=/C%2b%2b.
      
         
      This escaping is particularly necessary in a proxy situation,
         when the backend may break if presented with an unescaped URL.
      
         
      
@@ -1327,7 +1354,11 @@ cannot use $N in the substitution string!
         ScriptAlias, 
         which internally forces all files
         inside the mapped directory to have a handler of
-        ``cgi-script''.
+        ``cgi-script''.
      
+        If used in per-directory context, there must not be a substitution
+        which changes the path. Use this flag in per-directory context only
+        with - (dash) as the substitution, otherwise the request
+        will fail.
 
         
      'last|L'
         (last rule)
       Stop the rewriting process
@@ -1373,7 +1404,7 @@ cannot use $N in the substitution string!
           from happening. This allows percent symbols to appear in
           the output, as in 
 
      
-    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
+    RewriteRule ^/foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
 
      
           which would turn '/foo/zed' into a safe
           request for '/bar?arg=P1=zed'. 
@@ -1386,7 +1417,7 @@ cannot use $N in the substitution string!
           
      This flag forces the rewriting engine to skip a
           rewriting rule if the current request is an internal
           sub-request. For instance, sub-requests occur internally
-          in Apache when mod_include tries to find out
+          in Apache when mod_dir tries to find out
           information about possible directory default files
           (index.xxx files). On sub-requests it is not
           always useful, and can even cause errors, if
@@ -1511,13 +1542,9 @@ cannot use $N in the substitution string!
          Force the MIME-type of the target file to be
         MIME-type. This can be used to
         set up the content-type based on some conditions.
-        For example, the following snippet allows .php files to
-        be displayed by mod_php if they are called with
-        the .phps extension:
-        
      
-            RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
-        
      
-        
      
+        If used in per-directory context, use only - (dash)
+        as the substitution, otherwise the MIME-type set with this flag
+        is lost due to an internal re-processing.
       
 
 
@@ -1561,7 +1588,7 @@ files.  It is usually simpler, however, to avoid the prefix substitution
 complication by putting the rewrite rules in the main server or
 virtual host context, rather than in a <Directory> section.
      
 
-
      Although rewrite rules are syntactically permitted in <Location> sections, this
+
      Although rewrite rules are syntactically permitted in <Location> and <Files> sections, this
 should never be necessary and is unsupported.
    • diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 0de8014d78..525b5ed767 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -84,7 +84,11 @@ URLs on the fly initially requested, that is, before any rewriting. This is important to note because the rewriting process is primarily used to rewrite logical URLs to physical - pathnames.

    + pathnames.
    + These variables are set in per-server context, which means + that they are available in per-directory context only, if + RewriteEngine is set to on in + per-server context.

    Example 
    @@ -178,7 +182,15 @@ later
       this means that the maps, conditions and rules of the main
       server are inherited. In per-directory context this means
       that conditions and rules of the parent directory's
-      .htaccess configuration are inherited.
+      .htaccess configuration or
+      Directory
+      sections are inherited. The inherited rules are virtually copied
+      to the section where this directive is being used. If used in
+      combination with local rules, the inherited rules are copied behind
+      the local rules. The position of this directive - below or above
+      of local rules - has no influence on this behavior. If local
+      rules forced the rewriting to stop, the inherited rules won't
+      be processed.
       
 
 
@@ -473,13 +485,14 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map
           looked-up value as a newline-terminated string on
           stdout or the four-character string
           ``NULL'' if it fails (i.e., there
-          is no corresponding value for the given key). A trivial
-          program which will implement a 1:1 map (i.e.,
-          key == value) could be:
    
+          is no corresponding value for the given key).
    
 
           
    External rewriting programs are not started if they're defined in a
           context that does not have RewriteEngine set to
           on
    .
+          
+          
    A trivial program which will implement a 1:1 map (i.e.,
+          key == value) could be:
    
 
 
 
    @@ -673,7 +686,7 @@ Result:
           (0 <= N <= 9), which provide access to the grouped
           parts (in parentheses) of the pattern, from the
           RewriteRule which is subject to the current 
-          set of RewriteCond conditions..
+          set of RewriteCond conditions.
         
         
  • 
           RewriteCond backreferences: These are
@@ -831,14 +844,26 @@ Result:
       
    Other things you should be aware of:
    
 
       
      
-        
    1. The variables SCRIPT_FILENAME and REQUEST_FILENAME
+        
    2. 
+        
      The variables SCRIPT_FILENAME and REQUEST_FILENAME
         contain the same value - the value of the
         filename field of the internal
         request_rec structure of the Apache server.
         The first name is the commonly known CGI variable name
         while the second is the appropriate counterpart of
         REQUEST_URI (which contains the value of the
-        uri field of request_rec).
      3. 
+        uri field of request_rec).
      
+        
      If a substitution occurred and the rewriting continues,
+        the value of both variables will be updated accordingly.
      
+        
      If used in per-server context (i.e., before the
+        request is mapped to the filesystem) SCRIPT_FILENAME and
+        REQUEST_FILENAME cannot contain the full local filesystem
+        path since the path is unknown at this stage of processing.
+        Both variables will initially contain the value of REQUEST_URI
+        in that case. In order to obtain the full local filesystem
+        path of the request in per-server context, use an URL-based
+        look-ahead %{LA-U:REQUEST_FILENAME} to determine
+        the final value of REQUEST_FILENAME.
      
 
         
    3. 
         %{ENV:variable}, where variable can be
@@ -1095,7 +1120,7 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
 
       
      Pattern is
       a perl compatible regular
-      expression. On the first RewriteRule it is applied to the
+      expression. On the first RewriteRule it is applied to the (%-encoded)
       URL-path of the request;
       subsequent patterns are applied to the output of the last matched
       RewriteRule.
      
@@ -1239,13 +1264,15 @@ cannot use $N in the substitution string!
         
      Apache has to unescape URLs before mapping them,
         so backreferences will be unescaped at the time they are applied.
         Using the B flag, non-alphanumeric characters in backreferences
-        will be escaped.  For example, consider the rule:
      
-        
       RewriteRule ^(.*)$ index.php?show=$1 
      
-        
      This will map /C++ to index.php?show=/C++.
+        will be escaped. For example, consider the rule:
+        
+        RewriteRule ^(/.*)$ /index.php?show=$1
+        
+        This will map /C++ to /index.php?show=/C++.
         But it will also map /C%2b%2b to
-        index.php?show=/C++, because the %2b
+        /index.php?show=/C++, because the %2b
         has been unescaped.  With the B flag, it will instead map to
-        index.php?show=/C%2b%2b.
      
+        /index.php?show=/C%2b%2b.
      
         
      This escaping is particularly necessary in a proxy situation,
         when the backend may break if presented with an unescaped URL.
      
         
      
@@ -1342,7 +1369,11 @@ cannot use $N in the substitution string!
         ScriptAlias, 
         which internally forces all files
         inside the mapped directory to have a handler of
-        ``cgi-script''.
+        ``cgi-script''.
      
+        If used in per-directory context, there must not be a substitution
+        which changes the path. Use this flag in per-directory context only
+        with - (dash) as the substitution, otherwise the request
+        will fail.
 
         
      'last|L'
         (last rule)
       Stop the rewriting process
@@ -1388,7 +1419,7 @@ cannot use $N in the substitution string!
           from happening. This allows percent symbols to appear in
           the output, as in 
 
-    RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
+    RewriteRule ^/foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
 
           which would turn '/foo/zed' into a safe
           request for '/bar?arg=P1=zed'. 
@@ -1401,7 +1432,7 @@ cannot use $N in the substitution string!
           
      This flag forces the rewriting engine to skip a
           rewriting rule if the current request is an internal
           sub-request. For instance, sub-requests occur internally
-          in Apache when mod_include tries to find out
+          in Apache when mod_dir tries to find out
           information about possible directory default files
           (index.xxx files). On sub-requests it is not
           always useful, and can even cause errors, if
@@ -1529,13 +1560,9 @@ cannot use $N in the substitution string!
          Force the MIME-type of the target file to be
         MIME-type. This can be used to
         set up the content-type based on some conditions.
-        For example, the following snippet allows .php files to
-        be displayed by mod_php if they are called with
-        the .phps extension:
-        
-            RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
-        
-        
      
+        If used in per-directory context, use only - (dash)
+        as the substitution, otherwise the MIME-type set with this flag
+        is lost due to an internal re-processing.
       
 
 
@@ -1583,7 +1610,8 @@ virtual host context, rather than in a Directory section.
      
 
 
      Although rewrite rules are syntactically permitted in Location sections, this
+type="section" module="core">Location and Files sections, this
 should never be necessary and is unsupported.
      
 
 
-- 
2.50.1