From f184c05ccf6ecf41f44be04d867598c3b5dc2c91 Mon Sep 17 00:00:00 2001 From: Daniel Baumann Date: Sun, 28 Apr 2024 01:56:18 +0200 Subject: Adding upstream version 2.4.59. Signed-off-by: Daniel Baumann --- docs/manual/rewrite/flags.html.en | 130 +++++++++++++++++++++++++++----------- 1 file changed, 93 insertions(+), 37 deletions(-) (limited to 'docs/manual/rewrite/flags.html.en') diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en index 5ffd1b2..bfb5656 100644 --- a/docs/manual/rewrite/flags.html.en +++ b/docs/manual/rewrite/flags.html.en @@ -34,6 +34,8 @@ providing detailed explanations and examples.

Support Apache!
  • Introduction
  • B (escape backreferences)
  • BNP|backrefnoplus (don't escape space to +)
    • +
  • BCTLS
    • +
  • BNE
  • C|chain
  • CO|cookie
  • DPI|discardpath
    • @@ -85,16 +87,16 @@ of how you might use them.

    B (escape backreferences)

    The [B] flag instructs RewriteRule to escape non-alphanumeric characters before applying the transformation.

    -

    In 2.4.26 and later, you can limit the escaping to specific characters -in backreferences by listing them: [B=#?;]. Note: The space -character can be used in the list of characters to escape, but it cannot be -the last character in the list.

    mod_rewrite has to unescape URLs before mapping them, so backreferences are unescaped at the time they are applied. Using the B flag, non-alphanumeric characters in backreferences will be escaped. For example, consider the rule:

    +

    For similar escaping of server-variables, see + the "escape" mapping-function

    + + 
    RewriteRule "^search/(.*)$" "/search.php?term=$1"
    @@ -120,6 +122,20 @@ when the backend may break if presented with an unescaped URL.

    An alternative to this flag is using a RewriteCond to capture against %{THE_REQUEST} which will capture strings in the encoded form.

    + +

    In 2.4.26 and later, you can limit the escaping to specific characters +in backreferences by listing them: [B=#?;]. Note: The space +character can be used in the list of characters to escape, but you must quote +the entire third argument of RewriteRule +and the space must not be the last character in the list.

    + +
    # Escape spaces and question marks.  The quotes around the final argument 
+# are required when a space is included.
+RewriteRule "^search/(.*)$" "/search.php?term=$1" "[B= ?]"
    + + +

    To limit the characters escaped this way, see #flag_bne + and #flag_bctls

top

BNP|backrefnoplus (don't escape space to +)

@@ -127,8 +143,40 @@ strings in the encoded form.

in a backreference to %20 rather than '+'. Useful when the backreference will be used in the path component rather than the query string.

+
# Escape spaces to %20 in the path instead of + as used in form submission via
+# the query string
+RewriteRule "^search/(.*)$" "/search.php/$1" "[B,BNP]"
+ + +

This flag is available in version 2.4.26 and later.

+
top
+
+

BCTLS

+

The [BCTLS] flag is similar to the [B] flag, but only escapes +control characters and the space character. This is the same set of +characters rejected when they are copied into the query string unencoded. +

+ +
# Escape control characters and spaces
+RewriteRule "^search/(.*)$" "/search.php/$1" "[BCTLS]"
+ + +

This flag is available in version 2.4.57 and later.

+ +
top
+
+

BNE

+

The list of characters in [BNE=...] are treated as exclusions to the +characters of the [B] or [BCTLS] flags. The listed characters will not be +escaped. +

+ +
# Escape the default characters, but leave /
+RewriteRule "^search/(.*)$" "/search.php?term=$1" "[B,BNE=/]"
+ +

This flag is available in version 2.4.57 and later.

top

C|chain

@@ -210,7 +258,7 @@ attribute is set to the specified value. Typical values are None,

Consider this example:

RewriteEngine On
-RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]
+RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]

In the example give, the rule doesn't rewrite the request. @@ -295,8 +343,8 @@ value of '1' if the requested URI is an image file. Then, that environment variable is used to exclude those requests from the access log.

-
RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1]
-CustomLog "logs/access_log" combined env=!image
+
RewriteRule "\.(png|gif|jpg)$"   "-" [E=image:1]
+CustomLog   "logs/access_log"    combined env=!image

Note that this same effect can be obtained using SetEnvIf. This technique is offered as @@ -321,7 +369,7 @@ allows more flexibility in assigning a Forbidden status.

The following rule will forbid .exe files from being downloaded from your server.

-
RewriteRule "\.exe" "-" [F]
+
RewriteRule "\.exe"   "-" [F]

This example uses the "-" syntax for the rewrite target, which means @@ -341,7 +389,7 @@ longer available.

As with the [F] flag, you will typically use the "-" syntax for the rewrite target when using the [G] flag:

-
RewriteRule "oldproduct" "-" [G,NC]
+
RewriteRule "oldproduct"   "-" [G,NC]

When using [G], an [L] is implied - that is, the response is returned @@ -354,7 +402,7 @@ immediately, and no further rules are evaluated.

handler. For example, one might use this to force all files without a file extension to be parsed by the php handler:

-
RewriteRule "!\." "-" [H=application/x-httpd-php]
+
RewriteRule "!\."  "-" [H=application/x-httpd-php]

@@ -416,8 +464,8 @@ argument to index.php, however, the index.php, the RewriteRule will be skipped.

RewriteBase "/"
-RewriteCond "%{REQUEST_URI}" "!=/index.php"
-RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]
+RewriteCond "%{REQUEST_URI}" !=/index.php +RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]
top
@@ -440,11 +488,11 @@ pattern still matches (i.e., while the URI still contains an A), perform this substitution (i.e., replace the A with a B).

-

In 2.4.8 and later, this module returns an error after 32,000 iterations to +

In 2.4.8 and later, this module returns an error after 10,000 iterations to protect against unintended looping. An alternative maximum number of iterations can be specified by adding to the N flag. 

# Be willing to replace 1 character in each pass of the loop
-RewriteRule "(.+)[><;]$" "$1" [N=64000]
+RewriteRule "(.+)[><;]$" "$1" [N=32000]
 # ... or, give up if after 10 loops
 RewriteRule "(.+)[><;]$" "$1" [N=10]
@@ -540,11 +588,17 @@ client undue influence.

Performance warning

-

Using this flag triggers the use of mod_proxy, without handling of persistent connections. This -means the performance of your proxy will be better if you set it up with ProxyPass or -ProxyPassMatch

-

This is because this flag triggers the use of the default worker, which does not handle connection pooling/reuse.

-

Avoid using this flag and prefer those directives, whenever you can.

+

Using this flag triggers the use of mod_proxy, without +handling of persistent connections as the default worker is used in this case, +which does not handle connection pooling/reuse.

+

In order to use persistent connections you need to setup a +Proxy block at least for the scheme +and host part of the target URL containing a +ProxySet directive where you e.g. set +a timeout.

+

If you set it up with ProxyPass or +ProxyPassMatch persistent connections +will be used automatically.

Note: mod_proxy must be enabled in order @@ -688,19 +742,21 @@ URI in request' warnings.

The [S] flag is used to skip rules that you don't want to run. The syntax of the skip flag is [S=N], where N signifies the number of rules to skip (provided the -RewriteRule matches). This can be thought of as a goto -statement in your rewrite ruleset. In the following example, we only want -to run the RewriteRule if the -requested URI doesn't correspond with an actual file.

+RewriteRule and any preceding +RewriteCond directives match). This can be thought of as a +goto statement in your rewrite ruleset. In the following +example, we only want to run the +RewriteRule if the requested URI doesn't correspond with an +actual file.

# Is the request for a non-existent file?
-RewriteCond "%{REQUEST_FILENAME}" "!-f"
-RewriteCond "%{REQUEST_FILENAME}" "!-d"
+RewriteCond "%{REQUEST_FILENAME}" !-f
+RewriteCond "%{REQUEST_FILENAME}" !-d
 # If so, skip these two RewriteRules
-RewriteRule ".?" "-" [S=2]
+RewriteRule ".?"                  "-" [S=2]
 
-RewriteRule "(.*\.gif)" "images.php?$1"
-RewriteRule "(.*\.html)" "docs.php?$1"
+RewriteRule "(.*\.gif)" "images.php?$1" +RewriteRule "(.*\.html)" "docs.php?$1"

This technique is useful because a RewriteCond only applies to the @@ -712,18 +768,18 @@ 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:

# Does the file exist?
-RewriteCond "%{REQUEST_FILENAME}" "!-f"
-RewriteCond "%{REQUEST_FILENAME}" "!-d"
+RewriteCond "%{REQUEST_FILENAME}" !-f
+RewriteCond "%{REQUEST_FILENAME}" !-d
 # Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
-RewriteRule ".?" "-" [S=3]
+RewriteRule ".?"                  "-" [S=3]
 
 # IF the file exists, then:
-    RewriteRule "(.*\.gif)" "images.php?$1"
+    RewriteRule "(.*\.gif)"  "images.php?$1"
     RewriteRule "(.*\.html)" "docs.php?$1"
     # Skip past the "else" stanza.
-    RewriteRule ".?" "-" [S=1]
+    RewriteRule ".?"         "-" [S=1]
 # ELSE...
-    RewriteRule "(.*)" "404.php?file=$1"
+    RewriteRule "(.*)"       "404.php?file=$1"
 # END
@@ -740,7 +796,7 @@ sent. This has the same effect as the # Serve .pl files as plain text -RewriteRule "\.pl$" "-" [T=text/plain] +RewriteRule "\.pl$" "-" [T=text/plain]

Or, perhaps, if you have a camera that produces jpeg images without @@ -748,7 +804,7 @@ file extensions, you could force those images to be served with the correct MIME type by virtue of their file names:

# Files with 'IMG' in the name are jpg images.
-RewriteRule "IMG" "-" [T=image/jpg]
+RewriteRule "IMG" "-" [T=image/jpg]

Please note that this is a trivial example, and could be better done @@ -787,7 +843,7 @@ var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/flags.html'; } })(window, document); //-->