From 299688e2b1e4ece056dde95aec74b90956a11d28 Mon Sep 17 00:00:00 2001 From: Vincent Deffontaines Date: Sun, 25 Oct 2009 10:03:25 +0000 Subject: [PATCH] Add a note about the DPI rewrite flag, available from 2.2.12 only. git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@829520 13f79535-47bb-0310-9956-ffa450edef68 --- docs/manual/mod/mod_rewrite.xml | 141 ++++++++++++++++---------------- 1 file changed, 71 insertions(+), 70 deletions(-) diff --git a/docs/manual/mod/mod_rewrite.xml b/docs/manual/mod/mod_rewrite.xml index 3518fd5a9d..38f2e04dfb 100644 --- a/docs/manual/mod/mod_rewrite.xml +++ b/docs/manual/mod/mod_rewrite.xml @@ -22,7 +22,7 @@ -mod_rewrite +mod_rewrite Provides a rule-based rewriting engine to rewrite requested URLs on the fly @@ -134,7 +134,7 @@ SCRIPT_URI=http://en1.engelschall.com/u/rse/ directory.htaccess FileInfo - +

The RewriteEngine directive enables or disables the runtime rewriting engine. If it is set to @@ -172,7 +172,7 @@ later

The RewriteOptions directive sets some special options for the current per-server or per-directory - configuration. The Option string can currently + configuration. The Option string can currently only be one of the following:

@@ -350,7 +350,7 @@ Apache 2.0.41 and later
  • Standard Plain Text
    MapType: txt, MapSource: Unix filesystem - path to valid regular file + path to valid regular file

    This is the standard rewriting map feature where the MapSource is a plain ASCII file containing @@ -382,7 +382,7 @@ RewriteMap real-to-user txt:/path/to/file/map.txt

  • Randomized Plain Text
    MapType: rnd, MapSource: Unix filesystem - path to valid regular file + path to valid regular file

    This is identical to the Standard Plain Text variant above but with a special post-processing feature: After @@ -441,7 +441,7 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map

  • Internal Function
    MapType: int, MapSource: Internal Apache - function + function

    Here, the source is an internal Apache function. Currently you cannot create your own, but the following @@ -467,7 +467,7 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map

  • External Rewriting Program
    MapType: prg, MapSource: Unix filesystem - path to valid regular file + path to valid regular file

    Here the source is a program, not a map file. To create it you can use a language of your choice, but @@ -490,7 +490,7 @@ $ httxt2dbm -i mapfile.txt -o mapfile.map

    External rewriting programs are not started if they're defined in a context that does not have RewriteEngine set to on

    . - +

    A trivial program which will implement a 1:1 map (i.e., key == value) could be:

    @@ -509,7 +509,7 @@ while (<STDIN>) {
    1. ``Keep it simple, stupid'' (KISS). - If this program hangs, it will cause Apache to hang + If this program hangs, it will cause Apache to hang when trying to use the relevant rewrite rule.
    2. A common mistake is to use buffered I/O on @@ -517,8 +517,8 @@ while (<STDIN>) { ``$|=1'' is used above, to prevent this.
    3. The RewriteLock directive can - be used to define a lockfile which mod_rewrite can use to synchronize + module="mod_rewrite">RewriteLock directive can + be used to define a lockfile which mod_rewrite can use to synchronize communication with the mapping program. By default no such synchronization takes place.
    @@ -578,7 +578,7 @@ once! can be used in per-directory config files (.htaccess). In such a case, it will act locally, stripping the local directory prefix before processing, and applying - rewrite rules only to the remainder. When processing is complete, the + rewrite rules only to the remainder. When processing is complete, the prefix is automatically added back to the path. The default setting is; RewriteBase physical-directory-path

    @@ -588,7 +588,7 @@ once! or URL-base is. By default this prefix is the corresponding filepath itself. However, for most websites, URLs are NOT directly related to physical filename paths, so this - assumption will often be wrong! Therefore, you can + assumption will often be wrong! Therefore, you can use the RewriteBase directive to specify the correct URL-prefix.

    @@ -648,10 +648,10 @@ Result: were a new request. (See mod_rewrite technical details.) - This is not the serious overhead it may seem to be - - this re-injection is completely internal to the - Apache server (and the same procedure is used by - many other operations within Apache).

    + This is not the serious overhead it may seem to be - + this re-injection is completely internal to the + Apache server (and the same procedure is used by + many other operations within Apache).

    @@ -671,7 +671,7 @@ Result:

    The RewriteCond directive defines a rule condition. One or more RewriteCond - can precede a RewriteRule + can precede a RewriteRule directive. The following rule is then only used if both the current state of the URI matches its pattern, and if these conditions are met.

    @@ -685,7 +685,7 @@ Result: backreferences of the form $N (0 <= N <= 9), which provide access to the grouped parts (in parentheses) of the pattern, from the - RewriteRule which is subject to the current + RewriteRule which is subject to the current set of RewriteCond conditions.
  • @@ -705,11 +705,11 @@ Result:
  • Server-Variables: These are variables of - the form + the form %{ NAME_OF_VARIABLE } where NAME_OF_VARIABLE can be a string taken - from the following list: + from the following list: @@ -867,7 +867,7 @@ Result:
  • %{ENV:variable}, where variable can be - any environment variable, is also available. + any environment variable, is also available. This is looked-up via internal Apache structures and (if not found there) via getenv() from the Apache server process.
    • @@ -901,7 +901,7 @@ Result: %{LA-U:variable} can be used for look-aheads which perform an internal (URL-based) sub-request to determine the final value of variable. This can be used to access - variable for rewriting which is not available at the current + variable for rewriting which is not available at the current stage, but will be set in a later phase.

    For instance, to rewrite according to the REMOTE_USER variable from within the @@ -941,10 +941,10 @@ Result:

  • There are some special variants of CondPatterns. Instead of real regular expression strings you can also - use one of the following: + use one of the following:
      -
    • '<CondPattern' (lexicographically +
    • '<CondPattern' (lexicographically precedes)
      Treats the CondPattern as a plain string and compares it lexicographically to TestString. True if @@ -992,8 +992,8 @@ Result:
    • '-x' (has executable permissions)
      Treats the TestString as a pathname and tests - whether or not it exists, and has executable permissions. - These permissions are determined according to + whether or not it exists, and has executable permissions. + These permissions are determined according to the underlying OS.
    • '-F' (is existing file, via @@ -1009,7 +1009,7 @@ Result: Checks whether or not TestString is a valid URL, accessible via all the server's currently-configured access controls for that path. This uses an internal - subrequest to do the check, so use it with care - + subrequest to do the check, so use it with care - it can impact your server's performance!
    @@ -1030,7 +1030,7 @@ Result:
    • 'nocase|NC' (no case)
      - This makes the test case-insensitive - differences + This makes the test case-insensitive - differences between 'A-Z' and 'a-z' are ignored, both in the expanded TestString and the CondPattern. This flag is effective only for comparisons between @@ -1041,7 +1041,7 @@ Result: 'ornext|OR' (or next condition)
      Use this to combine rule conditions with a local OR - instead of the implicit AND. Typical example: + instead of the implicit AND. Typical example: 
      @@ -1087,12 +1087,12 @@ RewriteRule  ^/$                 /homepage.std.html  [L]
      -

      Explanation: If you use a browser which identifies itself +

      Explanation: If you use a browser which identifies itself as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you get the max homepage (which could include frames, or other special features). If you use the Lynx browser (which is terminal-based), then - you get the min homepage (which could be a version designed for + you get the min homepage (which could be a version designed for easy, text-only browsing). If neither of these conditions apply (you use any other browser, or your browser identifies itself as something non-standard), you get @@ -1113,7 +1113,7 @@ 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.

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

      In mod_rewrite, the NOT character - ('!') is also available as a possible pattern + ('!') 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 @@ -1148,9 +1148,9 @@ RewriteRule ^/$ /homepage.std.html [L] 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 -pattern does NOT match (ie, the negation matches), there are no +When using the NOT character to negate a pattern, you cannot include +grouped wildcard parts in that pattern. This is because, when the +pattern does NOT match (ie, the negation matches), there are no contents for the groups. Thus, if negated patterns are used, you cannot use $N in the substitution string! @@ -1167,7 +1167,7 @@ cannot use $N in the substitution string!
      Designates the location on the file-system of the resource to be delivered to the client.
      -
      URL-path
      +
      URL-path
      A DocumentRoot-relative path to the @@ -1220,7 +1220,7 @@ cannot use $N in the substitution string! (${mapname:key|default})
      • -

      Back-references are identifiers of the form +

      Back-references are identifiers of the form $N (N=0..9), which will be replaced by the contents of the Nth group of the @@ -1231,7 +1231,7 @@ cannot use $N in the substitution string! These three types of variables are expanded in the order above.

      As already mentioned, all rewrite rules are - applied to the Substitution (in the order in which + applied to the Substitution (in the order in which they are defined in the config file). The URL is completely replaced by the Substitution and the @@ -1247,16 +1247,16 @@ cannot use $N in the substitution string! 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.

      + [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 + directive. Flags is a comma-separated list, surround by square brackets, of any of the following flags:

      @@ -1282,7 +1282,7 @@ cannot use $N in the substitution string! 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 - + 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 @@ -1306,29 +1306,30 @@ cannot use $N in the substitution string!
      '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.

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

      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 + 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 + 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 + completes. Subsequent rules during this round of processing will see + only the direct result of substitutions, without any PATH_INFO appended.

      @@ -1341,15 +1342,15 @@ cannot use $N in the substitution string! 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'}). + var="VAR"-->) or CGI ($ENV{'VAR'}). You can also dereference the variable in a later RewriteCond pattern, using - %{ENV:VAR}. Use this to strip + %{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). + 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.
      @@ -1366,7 +1367,7 @@ cannot use $N in the substitution string! 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, + ScriptAlias, which internally forces all files inside the mapped directory to have a handler of ``cgi-script''.
      @@ -1417,12 +1418,12 @@ cannot use $N in the substitution string! 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 + 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'. + request for '/bar?arg=P1=zed'.
      @@ -1440,7 +1441,7 @@ cannot use $N in the substitution string! 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 + 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.

      @@ -1449,7 +1450,7 @@ cannot use $N in the substitution string! 'proxy|P' (force proxy)
      This flag forces the substitution part to be internally - sent as a proxy request and immediately (rewrite + 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 @@ -1460,7 +1461,7 @@ cannot use $N in the substitution string! more powerful implementation of the ProxyPass directive, to map remote content into the namespace of the local - server. + server.

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

      @@ -1482,18 +1483,18 @@ cannot use $N in the substitution string! /abc to /def using mod_rewrite, and then /def to /ghi using - mod_alias: + mod_alias: RewriteRule ^/abc(.*) /def$1 [PT]
      Alias /def /ghi       If you omit the PT flag, - mod_rewrite will rewrite + 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. + URI-to-filename transition, which will fail.

      Note: You must use this flag if you want to mix directives from different modules which allow @@ -1569,7 +1570,7 @@ cannot use $N in the substitution string! Home directory expansion

      When the substitution string begins with a string resembling "/~user" (via explicit text or backreferences), mod_rewrite performs -home directory expansion independent of the presence or configuration +home directory expansion independent of the presence or configuration of mod_userdir.

      This expansion does not occur when the PT @@ -1578,7 +1579,7 @@ 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 @@ -1664,7 +1665,7 @@ should never be necessary and is unsupported.

      (/physical/path/to/somepath/.htacccess, with RewriteBase /somepath)
      for request ``GET - /somepath/localpath/pathinfo'':
      + /somepath/localpath/pathinfo'':

      -- 
2.40.0