From: Joshua Slive Date: Thu, 2 Aug 2007 13:42:07 +0000 (+0000) Subject: Merge r561840, r561902, r561906, r561918 from trunk: X-Git-Tag: 2.2.5~66 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6a7fff89b0798f60d86c12660e378378fbc1c830;p=thirdparty%2Fapache%2Fhttpd.git Merge r561840, r561902, r561906, r561918 from trunk: Some updates to the RewriteRule docs, mostly focusing on clearly describing what can be in the substitution string. Included is a description of how mod_rewrite decides whether to treat the substitution as a file-system or URL-path. PR: 22529 R flag to mod_rewrite can set any status code PR: 25917 Note the L doesn't necessarily mean no more rewriting. PR: 40004 Change the flag list to a
instead of

Per-directory Rewrites

@@ -1454,38 +1518,6 @@ virtual host context, rather than in a <Location> sections, this should never be necessary and is unsupported.

-
- -

Note: Substitution of Absolute URLs

-

- When you prefix a substitution field with - http://thishost[:thisport], mod_rewrite will automatically strip that - out. This auto-reduction on URLs with an implicit - external redirect is most useful in - combination with a mapping-function which generates the - hostname part.

- -

Remember: An unconditional external - redirect to your own server will not work with the prefix - http://thishost because of this feature. To - achieve such a self-redirect, you have to use the - R-flag.

-
- -

What is matched?

-

The Pattern will initially be matched against the part of the - URL after the hostname and port, and before the query string. If you wish - to match against the hostname, port, or query string, use a - RewriteCond with the - %{HTTP_HOST}, %{SERVER_PORT}, or - %{QUERY_STRING} variables respectively.

-

You can, however, create URLs in the substitution string containing a - query string part. Simply use a question mark inside the substitution - string, to indicate that the following text should be re-injected into the - query string. When you want to erase an existing query string, - end the substitution string with just a question mark. To - combine new and old query strings, use the - [QSA] flag.

Here are all possible substitution combinations and their diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 017b9237a0b..d818c8935b6 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -1055,11 +1055,10 @@ RewriteRule ^/$ /homepage.std.html [L] RewriteRule Defines rules for the rewriting engine RewriteRule - Pattern Substitution + Pattern Substitution [flags] server configvirtual host directory.htaccess FileInfo -The cookie-flag is available in Apache 2.0.40 and later.

The RewriteRule directive is the real @@ -1075,6 +1074,17 @@ RewriteRule ^/$ /homepage.std.html [L] subsequent patterns are applied to the output of the last matched RewriteRule.

+What is matched? +

The Pattern will initially be matched against the part of the + URL after the hostname and port, and before the query string. If you wish + to match against the hostname, port, or query string, use a + RewriteCond with the + %{HTTP_HOST}, %{SERVER_PORT}, or + %{QUERY_STRING} variables respectively.

+ + + +

Some hints on the syntax of regular expressions:

@@ -1107,7 +1117,7 @@ RewriteRule ^/$ /homepage.std.html [L]

For more information about regular expressions, have a look at the perl regular expression manpage ("perldoc + href="http://www.perldoc.com/perlre.html">perldoc perlre"). If you are interested in more detailed information about regular expressions and their variants (POSIX regex etc.) the following book is dedicated to this topic:

@@ -1135,10 +1145,56 @@ contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string! -

The substitution of a - rewrite rule is the string which is substituted for (or - replaces) the original URL which Pattern - matched. In addition to plain text, it can include

+

The Substitution of a + rewrite rule is the string that replaces the original URL-path that + was matched by Pattern. The Substitution may + be a:

+ +
+ +
file-system path
+ +
Designates the location on the file-system of the resource + to be delivered to the client.
+ +
URL-path
+ +
A DocumentRoot-relative path to the + resource to be served. Note that mod_rewrite + tries to guess whether you have specified a file-system path + or a URL-path by checking to see if the first segement of the + path exists at the root of the file-system. For example, if + you specify a Substitution string of + /www/file.html, then this will be treated as a + URL-path unless a directory named www + exists at the root or your file-system, in which case it will + be treated as a file-system path. If you wish other + URL-mapping directives (such as Alias) to be applied to the + resulting URL-path, use the [PT] flag as + described below.
+ +
Absolute URL
+ +
If an absolute URL is specified, + mod_rewrite checks to see whether the + hostname matches the current host. If it does, the scheme and + hostname are stripped out and the resulting path is treated as + a URL-path. Otherwise, an external redirect is performed for + the given URL. To force an external redirect back to the + current host, see the [R] flag below.
+ +
- (dash)
+ +
A dash indicates that no substitution should be performed + (the existing path is passed through untouched). This is used + when a flag (see below) needs to be applied without changing + the path.
+ +
+ +

In addition to plain text, the Substition string can include

  1. back-references ($N) to the RewriteRule @@ -1153,6 +1209,7 @@ cannot use $N in the substitution string!
  2. mapping-function calls (${mapname:key|default})
+

Back-references are identifiers of the form $N (N=0..9), which will be replaced @@ -1172,25 +1229,28 @@ cannot use $N in the substitution string! or it is explicitly terminated by a L flag.

-

There is a special substitution string named - '-' which means: NO - substitution! This is useful in providing - rewriting rules which only match - URLs but do not substitute anything for them. It is commonly used - in conjunction with the C (chain) flag, in order - to apply more than one pattern before substitution occurs.

+ Modifying the Query String +

By default, the query string is passed through unchanged. You + can, however, create URLs in the substitution string containing + a query string part. Simply use a question mark inside the + substitution string to indicate that the following text should + be re-injected into the query string. When you want to erase an + existing query string, end the substitution string with just a + question mark. To combine new and old query strings, use the + [QSA] flag.

+

Additionally you can set special flags for Substitution by + id="rewriteflags">actions to be performed by appending [flags] as the third argument to the RewriteRule - directive. Flags is a comma-separated list of any of the - following flags:

+ directive. Flags is a comma-separated list, surround by square + brackets, of any of the following flags:

- + + Per-directory Rewrites @@ -1476,39 +1542,6 @@ module="core">Directory section.

type="section" module="core">Location sections, this should never be necessary and is unsupported.

- - -Note: Substitution of Absolute URLs -

- When you prefix a substitution field with - http://thishost[:thisport], mod_rewrite will automatically strip that - out. This auto-reduction on URLs with an implicit - external redirect is most useful in - combination with a mapping-function which generates the - hostname part.

- -

Remember: An unconditional external - redirect to your own server will not work with the prefix - http://thishost because of this feature. To - achieve such a self-redirect, you have to use the - R-flag.

- - -What is matched? -

The Pattern will initially be matched against the part of the - URL after the hostname and port, and before the query string. If you wish - to match against the hostname, port, or query string, use a - RewriteCond with the - %{HTTP_HOST}, %{SERVER_PORT}, or - %{QUERY_STRING} variables respectively.

-

You can, however, create URLs in the substitution string containing a - query string part. Simply use a question mark inside the substitution - string, to indicate that the following text should be re-injected into the - query string. When you want to erase an existing query string, - end the substitution string with just a question mark. To - combine new and old query strings, use the - [QSA] flag.

Here are all possible substitution combinations and their