From: Rich Bowen Date: Fri, 1 Jan 2010 20:02:30 +0000 (+0000) Subject: Removes duplication of the RewriteRule flags documentation. The module X-Git-Tag: 2.3.5~38 X-Git-Url: http://git.ipfire.org/?a=commitdiff_plain;h=5da48520eb2b7565dc2e43d014cb1ff34e9c4bde;p=thirdparty%2Fapache%2Fhttpd.git Removes duplication of the RewriteRule flags documentation. The module doc contains a table of definitions. The rewrite flag doc contains detailed explanations and examples. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@895060 13f79535-47bb-0310-9956-ffa450edef68 --- diff --git a/docs/manual/mod/mod_rewrite.html.en b/docs/manual/mod/mod_rewrite.html.en index ab1f2600ca4..60fc8b596e7 100644 --- a/docs/manual/mod/mod_rewrite.html.en +++ b/docs/manual/mod/mod_rewrite.html.en @@ -1107,327 +1107,127 @@ cannot use $N in the substitution string! [QSA] flag.

- -

Additionally you can set special 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 (0 means expires at end - of session), 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 inaccessible - to JavaScript code on browsers that support this feature.
- -
'discardpathinfo|DPI' - (discard PATH_INFO)
-

This flag is available from 2.2.12

-

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 to the value VAL, where VAL can - contain regexp backreferences ($N and - %N) which will be expanded. 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''.
- If used in per-directory context, there must not be a substitution - which changes the path. Use this flag in per-directory context only - with - (dash) as the substitution, otherwise the request - will fail.
- -
'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_dir 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 the query - string part of the substitution string to the existing query string, - instead of replacing it. Use this when you want to add more - data to the query string via a rewrite rule. This rule has no net effect - unless your substitution explicitly provides a new query string.
- -
'qsdiscard|QSD' - (query string discard)
- Discards any query string attached to the incoming URI. Without - this flag, the query string will be automatically copied from - the request URI to the rewritten URL. Note, however, that if you - provide a query string on your target URI, that one will be used - instead.
- -
'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. - If used in per-directory context, use only - (dash) - as the substitution, otherwise the MIME-type set with this flag - is lost due to an internal re-processing.
-
- + brackets, of any of the flags in the following table. More + details, ane examples, for each flag, are available in the Rewrite Flags document.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Flag and sytnaxFunction
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 ... +
discardpathinfo|DPICauses the PATH_INFO portion of the rewritten URI to be + discarded. details + ...
env|E=VAR:VALCauses an environment variable VAR to be set to the + value VAL. 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. 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 ...
qsdiscard|QSDDiscard any query string attached to the incoming URI. + 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 ...
tyle|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 diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index ce74347cb40..00dcbff557c 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -1121,331 +1121,142 @@ cannot use $N in the substitution string! [QSA] flag.

- -

Additionally you can set special 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 (0 means expires at end - of session), 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 inaccessible - to JavaScript code on browsers that support this feature.
- -
'discardpathinfo|DPI' - (discard PATH_INFO)
-

This flag is available from 2.2.12

-

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 to the value VAL, where VAL can - contain regexp backreferences ($N and - %N) which will be expanded. 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''.
- If used in per-directory context, there must not be a substitution - which changes the path. Use this flag in per-directory context only - with - (dash) as the substitution, otherwise the request - will fail.
- -
'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_dir 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 the query - string part of the substitution string to the existing query string, - instead of replacing it. Use this when you want to add more - data to the query string via a rewrite rule. This rule has no net effect - unless your substitution explicitly provides a new query string.
- -
'qsdiscard|QSD' - (query string discard)
- Discards any query string attached to the incoming URI. Without - this flag, the query string will be automatically copied from - the request URI to the rewritten URL. Note, however, that if you - provide a query string on your target URI, that one will be used - instead.
- -
'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. - If used in per-directory context, use only - (dash) - as the substitution, otherwise the MIME-type set with this flag - is lost due to an internal re-processing.
-
- + brackets, of any of the flags in the following table. More + details, ane examples, for each flag, are available in the Rewrite Flags document.

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Flag and sytnaxFunction
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 ... +
discardpathinfo|DPICauses the PATH_INFO portion of the rewritten URI to be + discarded. details + ...
env|E=VAR:VALCauses an environment variable VAR to be set to the + value VAL. 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. 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 ...
qsdiscard|QSDDiscard any query string attached to the incoming URI. + 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 ...
tyle|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 diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en index 4ba800ca16a..194af3fc651 100644 --- a/docs/manual/rewrite/flags.html.en +++ b/docs/manual/rewrite/flags.html.en @@ -346,7 +346,8 @@ RewriteRule ^(.*) index.php?req=$1 [L]

N|next

-The [N] flag causes the ruleset to start over again from the top. Use +The [N] flag causes the ruleset to start over again from the top, using +the result of the ruleset so far as a starting point. Use with extreme caution, as it may result in loop.

@@ -405,7 +406,18 @@ then result in a 404 Not Found error condition.

Use of the [NS] flag prevents the rule from being used on subrequests. For example, a page which is included using an SSI (Server Side Include) is a subrequest, and you may want to avoid rewrites -happening on those subrequests.

+happening on those subrequests. Also, when mod_dir +tries to find out information about possible directory default files +(such as index.html files), this is an internal +subrequest, and you often want to avoid rewrites on such subrequests. +On subrequests, it is not always useful, and can even cause errors, if +the complete set of rules are applied. Use this flag to exclude +problematic 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.

Images, javascript files, or css files, loaded as part of an HTML page, @@ -424,10 +436,21 @@ image server, you might do something like the following:

RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]

-

Use of the [P] flag implies [L] - that is, the request is immediatly +

Use of the [P] flag implies [L] - that is, the request is immediately pushed through the proxy, and any following rules will not be considered.

+

+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.

+
top

PT|passthrough

@@ -437,8 +460,8 @@ The target (or substitution string) in a RewriteRule is assumed to be a file path, by default. The use of the [PT] flag causes it to be treated as a URI instead. That is to say, the use of the [PT] flag causes the result of the RewriteRule to be passed back through -URL mapping, so that location-based mappings, such as Alias, for example, might have a chance to take -effect. +URL mapping, so that location-based mappings, such as Alias, Redirect, or ScriptAlias, for example, might have a +chance to take effect.

@@ -459,6 +482,10 @@ Omission of the [PT] flag in this case will cause the Alias to be ignored, resulting in a 'File not found' error being returned.

+

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

+
top

QSA|qsappend

@@ -509,15 +536,25 @@ URI. Use of the [R] flag causes a HTTP redirect to be issued to the browser. If a fully-qualified URL is specified (that is, including http://servername/) then a redirect will be issued to that -location. Otherwise, the current servername will be used to generate the -URL sent with the redirect. +location. Otherwise, the current protocol, servername, and port number +will be used to generate the URL sent with the redirect.

-Any status code may be specified, that is a valid HTTP Response, -with a 302 status code being used by default if none is specified. +Any valid HTTP response status code may be specified, +using the syntax [R=305], with a 302 status code being used by +default if none is specified. The status code specified need not +necessarily be a redirect (3xx) status code.

+

If a status code is outside the redirect range (300-399) then the +substitution string is dropped entirely, and rewriting is stopped as if +the L were used.

+ +

In addition to response status codes, you may also specify redirect +status using their symbolic names: temp (default), +permanent, or seeother.

+

You will almost always want to use [R] in conjunction with [L] (that is, use [R,L]) because on its own, the [R] flag prepends @@ -549,8 +586,10 @@ RewriteRule (.*\.html) docs.php?$1 RewriteRule immediately following it. Thus, if you want to make a RewriteCond apply to several RewriteRules, one possible technique is to -negate those conditions and use a [Skip] flag.

- +negate those conditions and use a [Skip] flag. So, you can +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.

top

T|type

@@ -579,6 +618,12 @@ using <FilesMat instead. Always consider the alternate solutions to a problem before resorting to rewrite, which will invariably be a less efficient solution than the alternatives.

+ +

+If used in per-directory context, use only - (dash) +as the substitution, otherwise the MIME-type set with this flag +is lost due to an internal re-processing.

+

Available Languages:  en  | diff --git a/docs/manual/rewrite/flags.xml b/docs/manual/rewrite/flags.xml index 5d368fab832..02ef3473890 100644 --- a/docs/manual/rewrite/flags.xml +++ b/docs/manual/rewrite/flags.xml @@ -337,7 +337,8 @@ RewriteRule ^(.*) index.php?req=$1 [L]

N|next

-The [N] flag causes the ruleset to start over again from the top. Use +The [N] flag causes the ruleset to start over again from the top, using +the result of the ruleset so far as a starting point. Use with extreme caution, as it may result in loop.

@@ -397,7 +398,18 @@ then result in a 404 Not Found error condition.

Use of the [NS] flag prevents the rule from being used on subrequests. For example, a page which is included using an SSI (Server Side Include) is a subrequest, and you may want to avoid rewrites -happening on those subrequests.

+happening on those subrequests. Also, when mod_dir +tries to find out information about possible directory default files +(such as index.html files), this is an internal +subrequest, and you often want to avoid rewrites on such subrequests. +On subrequests, it is not always useful, and can even cause errors, if +the complete set of rules are applied. Use this flag to exclude +problematic 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.

Images, javascript files, or css files, loaded as part of an HTML page, @@ -416,10 +428,22 @@ image server, you might do something like the following:

RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P] -

Use of the [P] flag implies [L] - that is, the request is immediatly +

Use of the [P] flag implies [L] - that is, the request is immediately pushed through the proxy, and any following rules will not be considered.

+

+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.

+
PT|passthrough @@ -431,8 +455,10 @@ as a URI instead. That is to say, the use of the [PT] flag causes the result of the RewriteRule to be passed back through URL mapping, so that location-based mappings, such as Alias, for example, might have a chance to take -effect. +module="mod_alias">Alias, Redirect, or ScriptAlias, for example, might have a +chance to take effect.

@@ -454,6 +480,10 @@ Omission of the [PT] flag in this case will cause the Alias to be ignored, resulting in a 'File not found' error being returned.

+

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

+
QSA|qsappend @@ -505,15 +535,25 @@ URI. Use of the [R] flag causes a HTTP redirect to be issued to the browser. If a fully-qualified URL is specified (that is, including http://servername/) then a redirect will be issued to that -location. Otherwise, the current servername will be used to generate the -URL sent with the redirect. +location. Otherwise, the current protocol, servername, and port number +will be used to generate the URL sent with the redirect.

-Any status code may be specified, that is a valid HTTP Response, -with a 302 status code being used by default if none is specified. +Any valid HTTP response status code may be specified, +using the syntax [R=305], with a 302 status code being used by +default if none is specified. The status code specified need not +necessarily be a redirect (3xx) status code.

+

If a status code is outside the redirect range (300-399) then the +substitution string is dropped entirely, and rewriting is stopped as if +the L were used.

+ +

In addition to response status codes, you may also specify redirect +status using their symbolic names: temp (default), +permanent, or seeother.

+

You will almost always want to use [R] in conjunction with [L] (that is, use [R,L]) because on its own, the [R] flag prepends @@ -547,8 +587,10 @@ module="mod_rewrite">RewriteCond only applies to the RewriteRule immediately following it. Thus, if you want to make a RewriteCond apply to several RewriteRules, one possible technique is to -negate those conditions and use a [Skip] flag.

- +negate those conditions and use a [Skip] flag. So, you can +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.

T|type @@ -578,6 +620,12 @@ using FilesMatch instead. Always consider the alternate solutions to a problem before resorting to rewrite, which will invariably be a less efficient solution than the alternatives.

+ +

+If used in per-directory context, use only - (dash) +as the substitution, otherwise the MIME-type set with this flag +is lost due to an internal re-processing.

+