From: Noirin Plunkett Date: Wed, 4 Nov 2009 00:10:36 +0000 (+0000) Subject: Split RewriteCond into two sections, brought TestString section up to date. X-Git-Tag: 2.3.3~56 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=c42364520624dc9c60a635109bbb3eb8f84e6428;p=apache Split RewriteCond into two sections, brought TestString section up to date. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@832627 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index 11f543538f..971ae24393 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -90,10 +90,11 @@ URLs on the fly .htaccess file where you want to use RewriteRule directives.

The example below demonstrates how to map - http://example.com/foo/index.html to - /home/www/example/newsite.html, in a .htaccess file. This - assumes that the content available at - http://example.com/ is on disk at /home/www/example/

+ http://example.com/foo/index.html to + /home/www/example/newsite.html, in a .htaccess + file. This assumes that the content available at + http://example.com/ is on disk at + /home/www/example/.

 RewriteEngine On
 RewriteBase /foo/
@@ -114,47 +115,45 @@ RewriteRule ^index\.html$  newsite.html
 Status:Extension
 Module:mod_rewrite
 
-      
The RewriteCond directive defines a
-      rule condition. One or more RewriteCond
-      can precede a RewriteRule
-      directive. The following rule is then only used if both
-      the current state of the URI matches its pattern, and if these conditions are met.

-
-      
TestString is a string which can contain the
-      following expanded constructs in addition to plain text:

-
+      
The RewriteCond 
+      directive defines a rule condition. One or more RewriteCond
+      conditions can precede a RewriteRule directive. The following rewrite rule is then 
+      used only if these conditions are met, and if the URI matches the pattern
+      specified in the rule.

+
+      
top

+

+
TestString

+      
+      
TestString can contain plain text, any of the 
+      following expanded constructs, or both.

       
    
         
  • 
           RewriteRule backreferences: These are
           backreferences of the form $N
-          (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.
-        
    • 
+          (1 <= N <= 9). They provide access to the grouped
+          parts of the current RewriteRule pattern. The grouped
+	  parts of the pattern are those in parentheses.
         
  • 
           RewriteCond backreferences: These are
           backreferences of the form %N
-          (1 <= N <= 9), which provide access to the grouped
-          parts (again, in parentheses) of the pattern, from the last matched
-          RewriteCond in the current set
-          of conditions.
-        
    • 
+          (1 <= N <= 9). They provide access to the grouped
+	  parts of the last-matched RewriteCond pattern. The
+	  grouped parts of the pattern are those in parentheses.
         
  • 
           RewriteMap expansions: These are
           expansions of the form ${mapname:key|default}.
-          See the documentation for
-          RewriteMap for more details.
+          See the RewriteMap documentation 
+	  for more details.
         
    • 
         
  • 
-          Server-Variables: These are variables of
+          Server variables: These are variables of
           the form
-            %{ NAME_OF_VARIABLE
-            }
-          where NAME_OF_VARIABLE can be a string taken
-          from the following list:
-
-          
+            %{ NAME_OF_VARIABLE },
+          where NAME_OF_VARIABLE is one of the server variables from
+	  the table below:
+	  
+	  
    
           
             
    
               HTTP headers: connection & request: 
@@ -223,34 +222,23 @@ RewriteRule ^index\.html$  newsite.html
               
             
    
           
    
-
-                
    These variables all
-                correspond to the similarly named HTTP
-                MIME-headers, C variables of the Apache server or
-                struct tm fields of the Unix system.
-                Most are documented elsewhere in the Manual or in
-                the CGI specification. Those that are special to
-                mod_rewrite include those below.
    
-        
    
+	  

+	  
The following variables are specific to 
+	  mod_rewrite:

                 

                   
IS_SUBREQ

 
-                  
Will contain the text "true" if the request
-                  currently being processed is a sub-request,
+                  
Contains the text "true" if the request
+                  currently being processed is a sub-request, or
                   "false" otherwise. Sub-requests may be generated
                   by modules that need to resolve additional files
                   or URIs in order to complete their tasks.

 
                   
API_VERSION

 
-                  
This is the version of the Apache module API
-                  (the internal interface between server and
-                  module) in the current httpd build, as defined in
-                  include/ap_mmn.h. The module API version
-                  corresponds to the version of Apache in use (in
-                  the release version of Apache 1.3.14, for
-                  instance, it is 19990320:10), but is mainly of
-                  interest to module authors.

+                  
The version of the Apache module API contained in the
+                  current httpd build, as defined in
+		  include/ap_mmn.h.

 
                   
THE_REQUEST

 
@@ -263,108 +251,79 @@ RewriteRule ^index\.html$  newsite.html
                   
REQUEST_URI

 
                   
The resource requested in the HTTP request
-                  line. (In the example above, this would be
-                  "/index.html".)

+                  line.
 
                   
REQUEST_FILENAME

 
-                  
The full local filesystem path to the file or
+                  
The full local filesystem path of the file or
                   script matching the request.

 
                   
HTTPS

 
-                  
Will contain the text "on" if the connection is
-                  using SSL/TLS, or "off" otherwise.  (This variable
-                  can be safely used regardless of whether or not
-                  mod_ssl is loaded).

+                  
Contains the text "on" if the connection is
+                  using SSL/TLS, or "off" otherwise. This variable
+                  does not depend on mod_ssl being loaded.

 
                 

 

-        
-      
 
-      
Other things you should be aware of:

-
-      
    
-        
  1. 
-        
    The variables SCRIPT_FILENAME and REQUEST_FILENAME
-        contain the same value - the value of the
+      
    Note that the SCRIPT_FILENAME and 
+	      REQUEST_FILENAME
+        variables both contain 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).
    
-        
    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
+        request_rec structure.
+	If a substitution occurs and rewriting continues,
+        the value of both variables will be updated accordingly.
+	In a per-server context, before the
+        request is mapped to the filesystem, these variables contain the value
+	of REQUEST_URI, because the full filesystem path is not
+	yet known. To obtain the full filesystem
+        path of a request in a per-server context, use a URL-based
         look-ahead %{LA-U:REQUEST_FILENAME} to determine
-        the final value of REQUEST_FILENAME.
    2. 
+	the final value of REQUEST_FILENAME.
    
 
-        
  2. 
-        %{ENV:variable}, where variable can be
-        any environment variable, is also available.
-        This is looked-up via internal
-        Apache structures and (if not found there) via
-        getenv() from the Apache server process.
    3. 
+	
    Other available variables include the following:
    
+	
    • 
+	%{ENV:variable}, where variable can be
+	any environment variable.
      • 
 
         
    • 
-        %{SSL:variable}, where variable is the
+	%{SSL:variable}, where variable is the
         name of an SSL environment
-        variable, can be used whether or not
-        mod_ssl is loaded, but will always expand to
-        the empty string if it is not.  Example:
-        %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
-        128.
      • 
-
-        
    • 
-        %{HTTP:header}, where header can be
-        any HTTP MIME-header name, can always be used to obtain the
-        value of a header sent in the HTTP request.
-        Example: %{HTTP:Proxy-Connection} is
-        the value of the HTTP header
-        ``Proxy-Connection:''.
-        
      If a HTTP header is used in a condition this header is added to
-        the Vary header of the response in case the condition evaluates to
-        to true for the request. It is not added if the
-        condition evaluates to false for the request. Adding the HTTP header
-        to the Vary header of the response is needed for proper caching.
      
-        
      It has to be kept in mind that conditions follow a short circuit
-        logic in the case of the 'ornext|OR' flag
-        so that certain conditions might not be evaluated at all.
      • 
-
+	variable. If mod_ssl is not loaded, this
+	will always expand to the empty string.
         
    • 
-        %{LA-U:variable} can be used for look-aheads which perform
-        an internal (URL-based) sub-request to determine the final
-        value of variable. This can be used to access
-        variable for rewriting which is not available at the current
-        stage, but will be set in a later phase.
-        
      For instance, to rewrite according to the
-        REMOTE_USER variable from within the
-        per-server context (httpd.conf file) you must
-        use %{LA-U:REMOTE_USER} - this
-        variable is set by the authorization phases, which come
-        after the URL translation phase (during which mod_rewrite
-        operates).
      
-        
      On the other hand, because mod_rewrite implements
-        its per-directory context (.htaccess file) via
-        the Fixup phase of the API and because the authorization
-        phases come before this phase, you just can use
-        %{REMOTE_USER} in that context.
      • 
-
+	%{HTTP:header}, where header can be
+	any HTTP MIME-header name. For example, 
+	%{HTTP:Proxy-Connection} is the value of the HTTP header
+        ``Proxy-Connection:''. If a HTTP header is used in a 
+	condition, and the condition evaluates to true, then that 
+	header is added to the Vary header of the response. This is used to 
+	ensure proper caching. 
+	If a previous condition has evaluated to true and the 
+	'ornext|OR' flag is in use, later
+	conditions are not evaluated, and therefore headers are not added to the
+	Vary header.
         
    • 
-        %{LA-F:variable} can be used to perform an internal
-        (filename-based) sub-request, to determine the final value
-        of variable. Most of the time, this is the same as
-        LA-U above.
      • 
-      

+	%{LA-U:variable}, which is used to perform 
+        an internal URL-based sub-request, to determine the final
+        value of variable. This can be used to access the value of
+	a variable which is to be set in a later phase. For example, the
+	REMOTE_USER variable is set in the authorization phase of
+	processing. This comes after the URL translation phase, where rewrite
+	rules in httpd.conf are applied, but before the fixup
+	phase, where rewrite rules in a .htaccess file are applied.
+	Therefore, to obtain the value of the REMOTE_USER variable 
+	within httpd.conf, you must use %{LA-U:REMOTE_USER}. To obtain the value of the
+	REMOTE_USER variable within a .htaccess file,
+	simply use %{REMOTE_USER}
+      
+      

 
+      
top

+

+
CondPattern

+      
       
CondPattern is the condition pattern,
        a regular expression which is applied to the
       current instance of the TestString.
@@ -536,6 +495,7 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
         or your browser identifies itself as something non-standard), you get
         the std (standard) homepage.

 
+
top
diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 362d0d920d..f4bd3b7ebe 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -516,10 +516,11 @@ once! module="mod_rewrite">RewriteRule directives.

The example below demonstrates how to map - http://example.com/foo/index.html to - /home/www/example/newsite.html, in a .htaccess file. This - assumes that the content available at - http://example.com/ is on disk at /home/www/example/

+ http://example.com/foo/index.html to + /home/www/example/newsite.html, in a .htaccess + file. This assumes that the content available at + http://example.com/ is on disk at + /home/www/example/.

 RewriteEngine On
@@ -543,49 +544,46 @@ RewriteRule ^index\.html$  newsite.html
 FileInfo
 
 
-      
The RewriteCond directive defines a
-      rule condition. One or more RewriteCond
-      can precede a RewriteRule
-      directive. The following rule is then only used if both
-      the current state of the URI matches its pattern, and if these conditions are met.

-
-      
TestString is a string which can contain the
-      following expanded constructs in addition to plain text:

-
+      
The RewriteCond 
+      directive defines a rule condition. One or more RewriteCond
+      conditions can precede a RewriteRule directive. The following rewrite rule is then 
+      used only if these conditions are met, and if the URI matches the pattern
+      specified in the rule.

+
+      

+      TestString
+      
TestString can contain plain text, any of the 
+      following expanded constructs, or both.

       
    
         
  • 
           RewriteRule backreferences: These are
           backreferences of the form $N
-          (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.
-        
    • 
+          (1 <= N <= 9). They provide access to the grouped
+          parts of the current RewriteRule pattern. The grouped
+	  parts of the pattern are those in parentheses.
         
  • 
           RewriteCond backreferences: These are
           backreferences of the form %N
-          (1 <= N <= 9), which provide access to the grouped
-          parts (again, in parentheses) of the pattern, from the last matched
-          RewriteCond in the current set
-          of conditions.
-        
    • 
+          (1 <= N <= 9). They provide access to the grouped
+	  parts of the last-matched RewriteCond pattern. The
+	  grouped parts of the pattern are those in parentheses.
         
  • 
           RewriteMap expansions: These are
           expansions of the form ${mapname:key|default}.
-          See the documentation for
-          RewriteMap for more details.
+          See the RewriteMap documentation 
+	  for more details.
         
    • 
         
  • 
-          Server-Variables: These are variables of
+          Server variables: These are variables of
           the form
-            %{ NAME_OF_VARIABLE
-            }
-          where NAME_OF_VARIABLE can be a string taken
-          from the following list:
-
-          
+            %{ NAME_OF_VARIABLE },
+          where NAME_OF_VARIABLE is one of the server variables from
+	  the table below:
+	  
+	  
    
            
@@ -655,34 +653,23 @@ RewriteRule ^index\.html$  newsite.html
               
    
           
             
    
             
    
           
    
-
-                
    These variables all
-                correspond to the similarly named HTTP
-                MIME-headers, C variables of the Apache server or
-                struct tm fields of the Unix system.
-                Most are documented elsewhere in the Manual or in
-                the CGI specification. Those that are special to
-                mod_rewrite include those below.
    
-        
+	  

+	  
The following variables are specific to 
+	  mod_rewrite:

                 

                   
IS_SUBREQ

 
-                  
Will contain the text "true" if the request
-                  currently being processed is a sub-request,
+                  
Contains the text "true" if the request
+                  currently being processed is a sub-request, or
                   "false" otherwise. Sub-requests may be generated
                   by modules that need to resolve additional files
                   or URIs in order to complete their tasks.

 
                   
API_VERSION

 
-                  
This is the version of the Apache module API
-                  (the internal interface between server and
-                  module) in the current httpd build, as defined in
-                  include/ap_mmn.h. The module API version
-                  corresponds to the version of Apache in use (in
-                  the release version of Apache 1.3.14, for
-                  instance, it is 19990320:10), but is mainly of
-                  interest to module authors.

+                  
The version of the Apache module API contained in the
+                  current httpd build, as defined in
+		  include/ap_mmn.h.

 
                   
THE_REQUEST

 
@@ -695,108 +682,78 @@ RewriteRule ^index\.html$  newsite.html
                   
REQUEST_URI

 
                   
The resource requested in the HTTP request
-                  line. (In the example above, this would be
-                  "/index.html".)

+                  line.
 
                   
REQUEST_FILENAME

 
-                  
The full local filesystem path to the file or
+                  
The full local filesystem path of the file or
                   script matching the request.

 
                   
HTTPS

 
-                  
Will contain the text "on" if the connection is
-                  using SSL/TLS, or "off" otherwise.  (This variable
-                  can be safely used regardless of whether or not
-                  mod_ssl is loaded).

+                  
Contains the text "on" if the connection is
+                  using SSL/TLS, or "off" otherwise. This variable
+                  does not depend on mod_ssl being loaded.

 
                 

 
-        
-      
-
-      
Other things you should be aware of:

 
-      
    
-        
  1. 
-        
    The variables SCRIPT_FILENAME and REQUEST_FILENAME
-        contain the same value - the value of the
+      
    Note that the SCRIPT_FILENAME and 
+	      REQUEST_FILENAME
+        variables both contain 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).
    
-        
    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
+        request_rec structure.
+	If a substitution occurs and rewriting continues,
+        the value of both variables will be updated accordingly.
+	In a per-server context, before the
+        request is mapped to the filesystem, these variables contain the value
+	of REQUEST_URI, because the full filesystem path is not
+	yet known. To obtain the full filesystem
+        path of a request in a per-server context, use a URL-based
         look-ahead %{LA-U:REQUEST_FILENAME} to determine
-        the final value of REQUEST_FILENAME.
    2. 
+	the final value of REQUEST_FILENAME.
    
 
-        
  2. 
-        %{ENV:variable}, where variable can be
-        any environment variable, is also available.
-        This is looked-up via internal
-        Apache structures and (if not found there) via
-        getenv() from the Apache server process.
    3. 
+	
    Other available variables include the following:
    
+	
    • 
+	%{ENV:variable}, where variable can be
+	any environment variable.
      • 
 
         
    • 
-        %{SSL:variable}, where variable is the
+	%{SSL:variable}, where variable is the
         name of an SSL environment
-        variable, can be used whether or not
-        mod_ssl is loaded, but will always expand to
-        the empty string if it is not.  Example:
-        %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to
-        128.
      • 
-
+	variable. If mod_ssl is not loaded, this
+	will always expand to the empty string.
         
    • 
-        %{HTTP:header}, where header can be
-        any HTTP MIME-header name, can always be used to obtain the
-        value of a header sent in the HTTP request.
-        Example: %{HTTP:Proxy-Connection} is
-        the value of the HTTP header
-        ``Proxy-Connection:''.
-        
      If a HTTP header is used in a condition this header is added to
-        the Vary header of the response in case the condition evaluates to
-        to true for the request. It is not added if the
-        condition evaluates to false for the request. Adding the HTTP header
-        to the Vary header of the response is needed for proper caching.
      
-        
      It has to be kept in mind that conditions follow a short circuit
-        logic in the case of the 'ornext|OR' flag
-        so that certain conditions might not be evaluated at all.
      • 
-
+	%{HTTP:header}, where header can be
+	any HTTP MIME-header name. For example, 
+	%{HTTP:Proxy-Connection} is the value of the HTTP header
+        ``Proxy-Connection:''. If a HTTP header is used in a 
+	condition, and the condition evaluates to true, then that 
+	header is added to the Vary header of the response. This is used to 
+	ensure proper caching. 
+	If a previous condition has evaluated to true and the 
+	'ornext|OR' flag is in use, later
+	conditions are not evaluated, and therefore headers are not added to the
+	Vary header.
         
    • 
-        %{LA-U:variable} can be used for look-aheads which perform
-        an internal (URL-based) sub-request to determine the final
-        value of variable. This can be used to access
-        variable for rewriting which is not available at the current
-        stage, but will be set in a later phase.
-        
      For instance, to rewrite according to the
-        REMOTE_USER variable from within the
-        per-server context (httpd.conf file) you must
-        use %{LA-U:REMOTE_USER} - this
-        variable is set by the authorization phases, which come
-        after the URL translation phase (during which mod_rewrite
-        operates).
      
-        
      On the other hand, because mod_rewrite implements
-        its per-directory context (.htaccess file) via
-        the Fixup phase of the API and because the authorization
-        phases come before this phase, you just can use
-        %{REMOTE_USER} in that context.
      • 
-
-        
    • 
-        %{LA-F:variable} can be used to perform an internal
-        (filename-based) sub-request, to determine the final value
-        of variable. Most of the time, this is the same as
-        LA-U above.
      • 
-      

+	%{LA-U:variable}, which is used to perform 
+        an internal URL-based sub-request, to determine the final
+        value of variable. This can be used to access the value of
+	a variable which is to be set in a later phase. For example, the
+	REMOTE_USER variable is set in the authorization phase of
+	processing. This comes after the URL translation phase, where rewrite
+	rules in httpd.conf are applied, but before the fixup
+	phase, where rewrite rules in a .htaccess file are applied.
+	Therefore, to obtain the value of the REMOTE_USER variable 
+	within httpd.conf, you must use %{LA-U:REMOTE_USER}. To obtain the value of the
+	REMOTE_USER variable within a .htaccess file,
+	simply use %{REMOTE_USER}
+      
+      

 
+      

+      CondPattern
       
CondPattern is the condition pattern,
        a regular expression which is applied to the
       current instance of the TestString.
@@ -972,6 +929,7 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
         or your browser identifies itself as something non-standard), you get
         the std (standard) homepage.

 
+