diff options
Diffstat (limited to 'docs/manual/rewrite/flags.html.en')
| -rw-r--r-- | docs/manual/rewrite/flags.html.en | 130 |
1 files changed, 93 insertions, 37 deletions
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.</p> <div id="quickview"><a href="https://www.apache.org/foundation/contributing.html" class="badge"><img src="https://www.apache.org/images/SupportApache-small.png" alt="Support Apache!" /></a><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_b">B (escape backreferences)</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_bnp">BNP|backrefnoplus (don't escape space to +)</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#flag_bctls">BCTLS</a></li> +<li><img alt="" src="../images/down.gif" /> <a href="#flag_bne">BNE</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_c">C|chain</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_co">CO|cookie</a></li> <li><img alt="" src="../images/down.gif" /> <a href="#flag_dpi">DPI|discardpath</a></li> @@ -85,16 +87,16 @@ of how you might use them.</p> <h2><a name="flag_b" id="flag_b">B (escape backreferences)</a></h2> <p>The [B] flag instructs <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to escape non-alphanumeric characters before applying the transformation.</p> -<p>In 2.4.26 and later, you can limit the escaping to specific characters -in backreferences by listing them: <code>[B=#?;]</code>. Note: The space -character can be used in the list of characters to escape, but it cannot be -the last character in the list.</p> <p><code>mod_rewrite</code> 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:</p> +<p>For similar escaping of server-variables, see + the "escape" <a href="#mapfunc">mapping-function</a></p> + + <pre class="prettyprint lang-config">RewriteRule "^search/(.*)$" "/search.php?term=$1"</pre> @@ -120,6 +122,20 @@ when the backend may break if presented with an unescaped URL.</p> <p>An alternative to this flag is using a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> to capture against %{THE_REQUEST} which will capture strings in the encoded form.</p> + +<p>In 2.4.26 and later, you can limit the escaping to specific characters +in backreferences by listing them: <code>[B=#?;]</code>. Note: The space +character can be used in the list of characters to escape, but you must quote +the entire third argument of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> +and the space must not be the last character in the list.</p> + +<pre class="prettyprint lang-config"># 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= ?]"</pre> + + +<p>To limit the characters escaped this way, see <a href="#flag_bne">#flag_bne</a> + and <a href="#flag_bctls">#flag_bctls</a></p> </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="flag_bnp" id="flag_bnp">BNP|backrefnoplus (don't escape space to +)</a></h2> @@ -127,8 +143,40 @@ strings in the encoded form.</p> in a backreference to %20 rather than '+'. Useful when the backreference will be used in the path component rather than the query string.</p> +<pre class="prettyprint lang-config"># 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]"</pre> + + + <p>This flag is available in version 2.4.26 and later.</p> +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="flag_bctls" id="flag_bctls">BCTLS</a></h2> +<p>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. +</p> + +<pre class="prettyprint lang-config"># Escape control characters and spaces +RewriteRule "^search/(.*)$" "/search.php/$1" "[BCTLS]"</pre> + + +<p>This flag is available in version 2.4.57 and later.</p> + +</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> +<div class="section"> +<h2><a name="flag_bne" id="flag_bne">BNE</a></h2> +<p>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. +</p> + +<pre class="prettyprint lang-config"># Escape the default characters, but leave / +RewriteRule "^search/(.*)$" "/search.php?term=$1" "[B,BNE=/]"</pre> + +<p>This flag is available in version 2.4.57 and later.</p> </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> <h2><a name="flag_c" id="flag_c">C|chain</a></h2> @@ -210,7 +258,7 @@ attribute is set to the specified value. Typical values are <code>None</code>, <p>Consider this example:</p> <pre class="prettyprint lang-config">RewriteEngine On -RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]</pre> +RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]</pre> <p>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.</p> -<pre class="prettyprint lang-config">RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1] -CustomLog "logs/access_log" combined env=!image</pre> +<pre class="prettyprint lang-config">RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1] +CustomLog "logs/access_log" combined env=!image</pre> <p>Note that this same effect can be obtained using <code class="directive"><a href="../mod/mod_setenvif.html#setenvif">SetEnvIf</a></code>. This technique is offered as @@ -321,7 +369,7 @@ allows more flexibility in assigning a Forbidden status.</p> <p>The following rule will forbid <code>.exe</code> files from being downloaded from your server.</p> -<pre class="prettyprint lang-config">RewriteRule "\.exe" "-" [F]</pre> +<pre class="prettyprint lang-config">RewriteRule "\.exe" "-" [F]</pre> <p>This example uses the "-" syntax for the rewrite target, which means @@ -341,7 +389,7 @@ longer available.</p> <p>As with the [F] flag, you will typically use the "-" syntax for the rewrite target when using the [G] flag:</p> -<pre class="prettyprint lang-config">RewriteRule "oldproduct" "-" [G,NC]</pre> +<pre class="prettyprint lang-config">RewriteRule "oldproduct" "-" [G,NC]</pre> <p>When using [G], an [L] is implied - that is, the response is returned @@ -354,7 +402,7 @@ immediately, and no further rules are evaluated.</p> handler. For example, one might use this to force all files without a file extension to be parsed by the php handler:</p> -<pre class="prettyprint lang-config">RewriteRule "!\." "-" [H=application/x-httpd-php]</pre> +<pre class="prettyprint lang-config">RewriteRule "!\." "-" [H=application/x-httpd-php]</pre> <p> @@ -416,8 +464,8 @@ argument to <code>index.php</code>, however, the <code class="directive"><a href is already for <code>index.php</code>, the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> will be skipped.</p> <pre class="prettyprint lang-config">RewriteBase "/" -RewriteCond "%{REQUEST_URI}" "!=/index.php" -RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]</pre> +RewriteCond "%{REQUEST_URI}" !=/index.php +RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]</pre> </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> <div class="section"> @@ -440,11 +488,11 @@ pattern still matches (i.e., while the URI still contains an <code>A</code>), perform this substitution (i.e., replace the <code>A</code> with a <code>B</code>).</p> -<p>In 2.4.8 and later, this module returns an error after 32,000 iterations to +<p>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. </p> <pre class="prettyprint lang-config"># 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]</pre> @@ -540,11 +588,17 @@ client undue influence.</p> <div class="warning"> <h3>Performance warning</h3> -<p>Using this flag triggers the use of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, without handling of persistent connections. This -means the performance of your proxy will be better if you set it up with <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or -<code class="directive"><a href="../mod/mod_proxy.html#proxypassmatch">ProxyPassMatch</a></code></p> -<p>This is because this flag triggers the use of the default worker, which does not handle connection pooling/reuse.</p> -<p>Avoid using this flag and prefer those directives, whenever you can.</p> +<p>Using this flag triggers the use of <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, without +handling of persistent connections as the default worker is used in this case, +which does not handle connection pooling/reuse.</p> +<p>In order to use persistent connections you need to setup a +<code class="directive"><a href="../mod/mod_proxy.html#proxy">Proxy</a></code> block at least for the scheme +and host part of the target URL containing a +<code class="directive"><a href="../mod/mod_proxy.html#proxyset">ProxySet</a></code> directive where you e.g. set +a timeout.</p> +<p>If you set it up with <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> or +<code class="directive"><a href="../mod/mod_proxy.html#proxypassmatch">ProxyPassMatch</a></code> persistent connections +will be used automatically.</p> </div> <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order @@ -688,19 +742,21 @@ URI in request' warnings. <p>The [S] flag is used to skip rules that you don't want to run. The syntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies the number of rules to skip (provided the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule"> -RewriteRule</a></code> matches). This can be thought of as a <code>goto</code> -statement in your rewrite ruleset. In the following example, we only want -to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the -requested URI doesn't correspond with an actual file.</p> +RewriteRule</a></code> and any preceding <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond"> +RewriteCond</a></code> directives match). This can be thought of as a +<code>goto</code> statement in your rewrite ruleset. In the following +example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule"> +RewriteRule</a></code> if the requested URI doesn't correspond with an +actual file.</p> <pre class="prettyprint lang-config"># 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"</pre> +RewriteRule "(.*\.gif)" "images.php?$1" +RewriteRule "(.*\.html)" "docs.php?$1"</pre> <p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> 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 <code>skip=N</code>, where N is the number of rules in the else-clause:</p> <pre class="prettyprint lang-config"># 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</pre> @@ -740,7 +796,7 @@ sent. This has the same effect as the <code class="directive"><a href="../mod/mo source code as plain text, if requested in a particular way:</p> <pre class="prettyprint lang-config"># Serve .pl files as plain text -RewriteRule "\.pl$" "-" [T=text/plain]</pre> +RewriteRule "\.pl$" "-" [T=text/plain]</pre> <p>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:</p> <pre class="prettyprint lang-config"># Files with 'IMG' in the name are jpg images. -RewriteRule "IMG" "-" [T=image/jpg]</pre> +RewriteRule "IMG" "-" [T=image/jpg]</pre> <p>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); //--><!]]></script></div><div id="footer"> -<p class="apache">Copyright 2023 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> +<p class="apache">Copyright 2024 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p> <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!-- if (typeof(prettyPrint) !== 'undefined') { prettyPrint(); |