From: brian Date: Mon, 3 Feb 1997 22:23:27 +0000 (+0000) Subject: Reviewed by: Brian Behlendorf X-Git-Tag: APACHE_1_2b7~12 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=e05022297b450b8ed23c182e4d62f039430e42d4;p=apache Reviewed by: Brian Behlendorf Submitted by: "Ralf S. Engelschall" Updates to the documentation for mod_rewrite. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@77561 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html index dbe943c959..ed7f457758 100644 --- a/docs/manual/mod/mod_rewrite.html +++ b/docs/manual/mod/mod_rewrite.html @@ -8,14 +8,14 @@ -

Module mod_rewrite (Version 2.3)

- -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 URLs on the fly. -mod_rewrite is not compiled into the server by -default. To use mod_rewrite you have to enable the following -line in the server build Configuration file: + +

Module mod_rewrite (Version 3.0)

+ +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 +URLs on the fly. mod_rewrite is not compiled into the server by +default. To use mod_rewrite you have to enable the following line +in the server build Configuration file:

     Module  rewrite_module   mod_rewrite.o

@@ -45,13 +45,13 @@ The latest version can be found on

Written for The Apache Group by

Ralf S. Engelschall
rse@engelschall.com
- http://www.engelschall.com/~rse+ www.engelschall.com

@@ -114,11 +114,11 @@ strings can be one of the following: 'inherit' - This forces the current configuration to inherit the configuration of the - parent. In per-virtual-server context this means that the maps, - 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. + This forces the current configuration to inherit the configuration of the + parent. In per-virtual-server context this means that the maps, + 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. @@ -151,12 +151,17 @@ To disable logging either remove or comment out the RewriteLog directive or use RewriteLogLevel 0! - -SECURITY: See the security -tips document for details on why your security could be -compromised if the directory where logfiles are stored is writable -by anyone other than the user that starts the server. + + + + +SECURITY: See the Apache Security +Tips document for details on why your security could be compromised if the +directory where logfiles are stored is writable by anyone other than the user +that starts the server. + Example: @@ -365,7 +370,7 @@ it is automatically added. When a substitution occurs for a new URL, this module has to re-inject the URL into the server processing. To be able to do this it needs to know what the corresponding URL-prefix or URL-base is. By default this -prefix is the corresponding filepath itself. But at most web-sites URLs are +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. @@ -373,7 +378,7 @@ directive to specify the correct URL-prefix. -So, if your web-server's URLs are not directly +So, if your webserver's URLs are not directly related to physical file paths, you have to use RewriteBase in every .htaccess files where you want to use RewriteRule directives. @@ -541,11 +546,13 @@ API_VERSION THE_REQUEST REQUEST_URI REQUEST_FILENAME +IS_SUBREQ + @@ -566,17 +573,27 @@ counterpart to REQUEST_URI (which contains the value of the uri field of request_rec). - There is an additional format: %{ENV:variable} where -variable can be any Unix environment variable. This is looked-up -via getenv() from the Apache server process. + There is the special format: %{ENV:variable} where +variable can be any environment variable. This is looked-up via +internal Apache structures and (if not found there) via getenv() from +the Apache server process. - There is one more additional format: %{HTTP:header} where + There is the special format: %{HTTP:header} where header can be any HTTP MIME-header name. This is looked-up from the HTTP request. Example: %{HTTP:Proxy-Connection} is the value of the HTTP header ``Proxy-Connection:''. - + + There is the special format: %{LA-U:url} +for look-aheads like -U. This performans a internal sub-request to +look-ahead for the final value of url. + + + There is the special format: %{LA-F:file} +for look-aheads like -F. This performans a internal sub-request to +look-ahead for the final value of file. + CondPattern is the condition pattern, i.e. a regular expression @@ -613,6 +630,18 @@ tests if it exists and is a regular file with size greater then zero. '-l' (is symbolic link) Treats the TestString as a pathname and tests if it exists and is a symbolic link. + + '-F' (is existing file via subrequest) +Checks if TestString is a valid file and accessible via all the +server's currently-configured access controls for that path. This uses an +internal subrequest to determine the check, so use it with care because it +decreases your servers performance! + + '-U' (is existing URL via subrequest) +Checks if TestString is a valid URL and accessible via all the server's +currently-configured access controls for that path. This uses an internal +subrequest to determine the check, so use it with care because it decreases +your servers performance! Notice: All of these tests can also be prefixed by a not ('!') character @@ -636,9 +665,9 @@ is a comma-separated list of the following flags: TestString and the CondPattern. 'ornext|OR' (or next condition) - Use this to combine rule conditions with a local OR instead of the - implicit AND. Typical example: - + Use this to combine rule conditions with a local OR instead of the + implicit AND. Typical example: + RewriteCond %{REMOTE_HOST} ^host1.* [OR] RewriteCond %{REMOTE_HOST} ^host2.* [OR] @@ -653,7 +682,7 @@ RewriteRule ...some special stuff for any of these hosts... Example: -To rewrite the Home-page of a site according to the ``User-Agent:'' +To rewrite the Homepage of a site according to the ``User-Agent:'' header of the request, you can use the following: @@ -805,16 +834,35 @@ as the third argument to the RewriteRule directive. Flags is a comma-separated list of the following flags: -'redirect|R' (force redirect) + 'redirect|R[=code]' (force redirect) Prefix Substitution - with http://thishost/ (which makes the new URL a URI) to - force a external redirection. Use it for rules which should - canonicalize the URL and gives it back to the client, e.g. translate + 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 + canonicalize the URL and gives it back to the client, e.g. translate ``/~'' into ``/u/'' or always append a slash to /u/user, etc. + Notice: When you use this flag, make sure that the - substitution field is a valid URL! If not, you are redirecting to an invalid - location! + substitution field is a valid URL! If not, you are redirecting to an + invalid location! And remember that this flag itself only prefixes the + URL with http://thishost[:thisport]/, but rewriting goes on. + Usually you also want to stop and do the redirection immediately. To stop + the rewriting you also have to provide the 'L' flag. + + 'forbidden|F' (force URL to be forbidden) + This forces the current URL to be forbidden, i.e. it immediately sends + back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with + appropriate RewriteConds to conditionally block some URLs. + + 'gone|G' (force URL to be gone) + This forces the current URL to be gone, i.e. it immediately sends back a + HTTP response of 410 (GONE). Use this flag to mark no longer existing + pages as gone. 'proxy|P' (force proxy) This flag forces the substitution part to be internally forced as a proxy @@ -824,7 +872,13 @@ comma-separated list of the following flags: be handled by the Apache proxy module. If not you get an error from the proxy module. Use this flag to achieve a more powerful implementation of the mod_proxy directive ProxyPass, to map - some remote stuff into the name-space of the local server. + some remote stuff into the namespace of the local server. + + Notice: You really have to put ProxyRequests On into your + server configuration to prevent proxy requests from leading to core-dumps + inside the Apache kernel. If you have not compiled in the proxy module, + then there is no core-dump problem, because mod_rewrite checks for + existence of the proxy module and if lost forbids proxy URLs. 'last|L' (last rule) Stop the rewriting process here and @@ -899,7 +953,6 @@ comma-separated list of the following flags: of different modules which contain URL-to-filename translators. The typical example is the use of mod_alias and mod_rewrite.. - @@ -921,6 +974,16 @@ comma-separated list of the following flags: a skip=N where N is the number of rules in the else-clause. (This is not the same as the 'chain|C' flag!) + 'env|E=VAR:VAL' (set environment variable) + This forces an environment variable named VAR to be set to the value + VAL, where VAL can contain regexp backreferences $N + which will be expanded. You can use this flag more than once to set more + than one variable. The variables can be later dereferenced at a lot of + situations, but the usual location will be from within XSSI (via + ) 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. @@ -1087,3 +1150,4 @@ RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 +