From: Eric Covener Date: Wed, 5 Jan 2011 22:42:07 +0000 (+0000) Subject: synch up with trunk for the first half of RewriteRule: X-Git-Tag: 2.2.18~197 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=0a29833203d4fda4bffa6a26e3d3809b61170612;p=thirdparty%2Fapache%2Fhttpd.git synch up with trunk for the first half of RewriteRule: PR#44838: be more up front with how the per-dir RewriteRule comparison is the filesystem path minus the Directory the rules were listed in. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1055672 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 83039f27e15..59dc4b22f14 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -1113,40 +1113,88 @@ RewriteRule ^/$ /homepage.std.html [L]

The RewriteRule directive is the real - rewriting workhorse. The directive can occur more than once, + rewriting workhorse. The directive can occur more than once, with each instance defining a single rewrite rule. The order in which these rules are defined is important - this is the order in which they will be applied at run-time.

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.

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 +

In VirtualHost context, + The Pattern will initially be matched against the part of the + URL after the hostname and port, and before the query string (e.g. "/app1/index.html").

+ +

In Directory and htaccess context, + the Pattern will initially be matched against the + filesystem path, after removing the prefix that lead the server + to the current RewriteRule (e.g. "app1/index.html" + or "index.html" depending on where the directives are defined).

+ +

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.

+ + + +Per-directory Rewrites +
    +
  • The rewrite engine may be used in .htaccess files in Directory sections, with some additional +complexity.
    • + +
  • To enable the rewrite engine in this context, you need to set +"RewriteEngine On" and +"Options FollowSymLinks" must be enabled. If your +administrator has disabled override of FollowSymLinks for +a user's directory, then you cannot use the rewrite engine. This +restriction is required for security reasons.
    • + +
  • When using the rewrite engine in .htaccess files the +per-directory prefix (which always is the same for a specific +directory) is automatically removed for the RewriteRule pattern matching +and automatically added after any relative (not starting with a +slash or protocol name) substitution encounters the end of a rule set. +See the RewriteBase +directive for more information regarding what prefix will be added back to +relative substutions.
    • + +
  • If you wish to match against the full URL-path in a per-directory +(htaccess) RewriteRule, use the %{REQUEST_URI} variable in +a RewriteCond.
    • + +
  • The removed prefix always ends with a slash, meaning the matching occurs against a string which +never has a leading slash. Therefore, A Pattern with ^/ never +matches in per-directory context.
    • + +
  • Although rewrite rules are syntactically permitted in Location and Files sections, this +should never be necessary and is unsupported.
    • +

For some hints on regular expressions, see - the mod_rewrite + the mod_rewrite Introduction.

-

In mod_rewrite, the NOT character - ('!') is also available as a possible pattern +

In mod_rewrite, the NOT character + ('!') is also available as a possible pattern prefix. This enables you to negate a pattern; to say, for instance: ``if the current URL does NOT match this pattern''. This can be used for exceptional cases, where it is easier to match the negative pattern, or as a last default rule.

+ Note When using the NOT character to negate a pattern, you cannot include grouped wildcard parts in that pattern. This is because, when the @@ -1570,44 +1618,6 @@ of mod_userdir.

This expansion does not occur when the PT flag is used on the RewriteRule directive.

- - -Per-directory Rewrites - -

The rewrite engine may be used in .htaccess files. To enable the -rewrite engine for these files you need to set -"RewriteEngine On" and -"Options FollowSymLinks" must be enabled. If your -administrator has disabled override of FollowSymLinks for -a user's directory, then you cannot use the rewrite engine. This -restriction is required for security reasons.

- -

When using the rewrite engine in .htaccess files the -per-directory prefix (which always is the same for a specific -directory) is automatically removed for the pattern matching -and automatically added after the substitution has been -done. This feature is essential for many sorts of rewriting; without -this, you would always have to match the parent directory, which is -not always possible. There is one exception: If a substitution string -starts with http://, then the directory prefix will -not be added, and an external redirect (or proxy -throughput, if using flag P) is forced. See the -RewriteBase directive for -more information.

- -

The rewrite engine may also be used in Directory sections with the same -prefix-matching rules as would be applied to .htaccess -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 -should never be necessary and is unsupported.

-

Here are all possible substitution combinations and their