From: Rich Bowen Date: Fri, 25 Mar 2011 13:47:58 +0000 (+0000) Subject: Links to more detailed rewrite flag doc. X-Git-Tag: 2.2.18~77 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=f5d14755ed4c1aa0612930db6b74dca1324cd8be;p=thirdparty%2Fapache%2Fhttpd.git Links to more detailed rewrite flag doc. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/branches/2.2.x@1085362 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 48f12ed7668..50cedaecb01 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -1303,316 +1303,137 @@ cannot use $N in the substitution string! [QSA] flag.

-

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

- -
-
'B' (escape backreferences)
-

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++. - But it will also map /C%2b%2b to - 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.

-

This escaping is particularly necessary in a proxy situation, - when the backend may break if presented with an unescaped URL.

-
- -
'chain|C' - (chained with next rule)
- This flag chains the current rule with the next rule - (which itself can be chained with the following rule, - and so on). This has the following effect: if a rule - matches, then processing continues as usual - - the flag has no effect. If the rule does - not match, then all following chained - rules are skipped. For instance, it can be used to remove the - ``.www'' part, inside a per-directory rule set, - when you let an external redirect happen (where the - ``.www'' part should not occur!).
- -
'cookie|CO=NAME:VAL:domain[:lifetime[:path[:secure[:httponly]]]]' - (set cookie)
- This sets a cookie in the client's browser. The cookie's name - is specified by NAME and the value is - VAL. The domain field is the domain of the - cookie, such as '.apache.org', the optional lifetime - is the lifetime of the cookie in minutes, and the optional - path is the path of the cookie. If secure - is set to 'secure', 'true' or '1', the cookie is only transmitted via secured - connections. If httponly is set to 'HttpOnly', 'true' or '1', the - HttpOnly flag is used, making the cookie not accessible - to JavaScript code on browsers that support this feature.
- -
'discardpathinfo|DPI' - (discard PATH_INFO)
-

In per-directory context, the URI each RewriteRule - compares against is the concatenation of the current values of the URI - and PATH_INFO.

- -

The current URI can be the initial URI as requested by the client, the - result of a previous round of mod_rewrite processing, or the result of - a prior rule in the current round of mod_rewrite processing.

- -

In contrast, the PATH_INFO that is appended to the URI before each - rule reflects only the value of PATH_INFO before this round of - mod_rewrite processing. As a consequence, if large portions - of the URI are matched and copied into a substitution in multiple - RewriteRule directives, without regard for - which parts of the URI came from the current PATH_INFO, the final - URI may have multiple copies of PATH_INFO appended to it.

- -

Use this flag on any substitution where the PATH_INFO that resulted - from the previous mapping of this request to the filesystem is not of - interest. This flag permanently forgets the PATH_INFO established - before this round of mod_rewrite processing began. PATH_INFO will - not be recalculated until the current round of mod_rewrite processing - completes. Subsequent rules during this round of processing will see - only the direct result of substitutions, without any PATH_INFO - appended.

- -
'env|E=!VAR[:VAL]' - (set environment variable)
- This forces an environment variable named VAR to - be set. The value will be VAL if provided, where VAL - can contain regexp backreferences ($N and - %N) which will be expanded. The form !VAR causes - the environment variable VAR to be unset and does not accept - any VAL. You can use this flag more than once, to set more - than one variable. The variables can later be dereferenced in many - situations, most commonly from within XSSI (via <!--#echo - var="VAR"-->) or CGI ($ENV{'VAR'}). - You can also dereference the variable in a later RewriteCond pattern, using - %{ENV:VAR}. Use this to strip - information from URLs, while maintaining a record of that information.
- -
'forbidden|F' (force URL - to be forbidden)
- This forces the current URL to be forbidden - 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 - it - immediately sends back a HTTP response of 410 (GONE). Use - this flag to mark pages which no longer exist as gone.
- -
- 'handler|H=Content-handler' - (force Content handler)
- Force the Content-handler of the target file to be - Content-handler. For instance, this can be used to - simulate the mod_alias directive - ScriptAlias, - which internally forces all files - inside the mapped directory to have a handler of - ``cgi-script''.
- -
'last|L' - (last rule)
Stop the rewriting process - here and don't apply any more rewrite rules. This corresponds - to the Perl last command or the - break command in C. Use this flag to prevent the - currently rewritten URL from being rewritten further by - following rules. Remember, however, that if the - RewriteRule generates an internal - redirect (which frequently occurs when rewriting in a - per-directory context), this will reinject the request and - will cause processing to be repeated starting from the first - RewriteRule.
- -
'next|N' - (next round)
- Re-run the rewriting process (starting again with the - first rewriting rule). This time, the URL to match is no longer - the original URL, but rather the URL returned by the last rewriting rule. - This corresponds to the Perl next command or - the continue command in C. Use - this flag to restart the rewriting process - - to immediately go to the top of the loop. - Be careful not to create an infinite - loop!
- -
'nocase|NC' - (no case)
- This makes the Pattern case-insensitive, - ignoring difference between 'A-Z' and - 'a-z' when Pattern is matched against the current - URL.
- -
- 'noescape|NE' - (no URI escaping of - output)
- This flag prevents mod_rewrite from applying the usual URI - escaping rules to the result of a rewrite. Ordinarily, - special characters (such as '%', '$', ';', and so on) - will be escaped into their hexcode equivalents ('%25', - '%24', and '%3B', respectively); this flag prevents this - from happening. This allows percent symbols to appear in - the output, as in - - RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] - - which would turn '/foo/zed' into a safe - request for '/bar?arg=P1=zed'. -
- -
- 'nosubreq|NS' - (not for internal - sub-requests)
-

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 - information about possible directory default files - (index.xxx files). On sub-requests it is not - always useful, and can even cause errors, if - the complete set of rules are applied. Use this flag to - exclude some rules.

-

To decide whether or not to use this rule: if you - prefix URLs with CGI-scripts, to force them to be - processed by the CGI-script, it's likely that you - will run into problems (or significant overhead) on - sub-requests. In these cases, use this flag.

-
- -
- 'proxy|P' (force - proxy)
- This flag forces the substitution part to be internally - sent as a proxy request and immediately (rewrite - processing stops here) put through the proxy module. You must make - sure that the substitution string is a valid URI - (typically starting with - http://hostname) which can be - handled by the Apache proxy module. If not, you will get an - error from the proxy module. Use this flag to achieve a - more powerful implementation of the ProxyPass directive, - to map remote content into the namespace of the local - server. - -

Note: mod_proxy must be enabled in order - to use this flag.

-
- -
- 'passthrough|PT' - (pass through to next - handler)
- This flag forces the rewrite engine to set the - uri field of the internal - request_rec structure to the value of the - filename field. This flag is just a hack to - enable post-processing of the output of - RewriteRule directives, using - Alias, ScriptAlias, - Redirect, and other directives from - various URI-to-filename translators. For example, to rewrite - /abc to /def using - mod_rewrite, and then - /def to /ghi using - mod_alias: - - RewriteRule ^/abc(.*) /def$1 [PT]
- Alias /def /ghi - - If you omit the PT flag, - mod_rewrite will rewrite - uri=/abc/... to - filename=/def/... as a full API-compliant - URI-to-filename translator should do. Then - mod_alias will try to do a - URI-to-filename transition, which will fail. - -

Note: You must use this flag if you want to - mix directives from different modules which allow - URL-to-filename translators. The typical example - is the use of mod_alias and - mod_rewrite.

- -

The PT flag implies the L flag: - rewriting will be stopped in order to pass the request to - the next phase of processing.

-
- -
'qsappend|QSA' - (query string - append)
- This flag forces the rewrite engine to append a query - string part of the substitution string to the existing string, - instead of replacing it. Use this when you want to add more - data to the query string via a rewrite rule.
- -
'redirect|R - [=code]' (force redirect)
-

Prefix Substitution 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) will be returned. If you want to use other - response codes, simply specify the appropriate number or use - one of the following symbolic names: temp - (default), permanent, - seeother. Use this for rules to canonicalize - the URL and return it to the client - to translate - ``/~'' into ``/u/'', or to always - append a slash to /u/user, etc.
- Note: When you use this flag, make sure - that the substitution field is a valid URL! Otherwise, you - will be redirecting to an invalid location. Remember that - this flag on its own will only prepend - http://thishost[:thisport]/ to the URL, and - rewriting will continue. Usually, you will want to stop - rewriting at this point, and redirect immediately. To stop - rewriting, you should add the 'L' flag.

-

While this is typically used for redirects, any valid status - code can be given here. If the status code is outside the redirect - range (300-399), then the Substitution string is dropped - and rewriting is stopped as if the L flag was - used.

-
- -
'skip|S=num' - (skip next rule(s))
- This flag forces the rewriting engine to skip the next - num rules in sequence, if the current rule - matches. Use this to make pseudo if-then-else constructs: - The last rule of the then-clause becomes - skip=N, where N is the number of rules in the - else-clause. (This is not the same as the - 'chain|C' flag!)
- -
- 'type|T=MIME-type' - (force MIME type)
- 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] - -
-
+ directive. Flags is a comma-separated list, surround by square + brackets, of any of the flags in the following table. More + details, and examples, for each flag, are available in the Rewrite Flags document.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Flag and syntaxFunction
BEscape non-alphanumeric characters before applying + the transformation. details ...
chain|CRule is chained to the following rule. If the rule fails, + the rule(s) chained to it will be skipped. details ...
cookie|CO=NAME:VALSets a cookie in the client browser. Full syntax is: + CO=NAME:VAL[:domain[:lifetime[:path[:secure[:httponly]]]]] details ... +
discardpath|DPICauses the PATH_INFO portion of the rewritten URI to be + discarded. details + ...
env|E=[!]VAR[:VAL]Causes an environment variable VAR to be set (to the + value VAL if provided). The form !VAR causes + the environment variable VAR to be unset.details ...
forbidden|FReturns a 403 FORBIDDEN response to the client browser. + details ...
gone|GReturns a 410 GONE response to the client browser. details ...
Handler|H=Content-handlerCauses the resulting URI to be sent to the specified + Content-handler for processing. details ...
last|LStop the rewriting process immediately and don't apply any + more rules. Especially note caveats for per-directory and + .htaccess context (see also the END flag). details ...
next|NRe-run the rewriting process, starting again with the first + rule, using the result of the ruleset so far as a starting + point. details + ...
nocase|NCMakes the pattern pattern comparison case-insensitive. + details ...
noescape|NEPrevent mod_rewrite from applying hexcode escaping of + special characters in the result of the rewrite. details ...
nosubreq|NSCauses a rule to be skipped if the current request is an + internal sub-request. details ...
proxy|PForce the substitution URL to be internally sent as a proxy + request. details + ...
passthrough|PTForces the resulting URI to be passed back to the URL + mapping engine for processing of other URI-to-filename + translators, such as Alias or + Redirect. details ...
qsappend|QSAAppends any query string created in the rewrite target to + any query string that was in the original request URL. details ...
redirect|R[=code]Forces an external redirect, optionally with the specified + HTTP status code. details ... +
skip|S=numTells the rewriting engine to skip the next num + rules if the current rule matches. details ...
type|T=MIME-typeForce the MIME-type of the target file + to be the specified type. details ...
Home directory expansion

When the substitution string begins with a string