diff options
Diffstat (limited to 'docs/manual/rewrite/flags.html.en')
| -rw-r--r-- | docs/manual/rewrite/flags.html.en | 159 |
1 files changed, 111 insertions, 48 deletions
diff --git a/docs/manual/rewrite/flags.html.en b/docs/manual/rewrite/flags.html.en index 1984882..bfb5656 100644 --- a/docs/manual/rewrite/flags.html.en +++ b/docs/manual/rewrite/flags.html.en @@ -1,7 +1,7 @@ -<?xml version="1.0" encoding="ISO-8859-1"?> +<?xml version="1.0" encoding="UTF-8"?> <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head> -<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" /> +<meta content="text/html; charset=UTF-8" http-equiv="Content-Type" /> <!-- XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX This file is generated from xml source: DO NOT EDIT @@ -24,7 +24,7 @@ <a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.4</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>RewriteRule Flags</h1> <div class="toplang"> <p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> | -<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> +<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> </div> <p>This document discusses the flags which are available to the @@ -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> @@ -67,7 +69,7 @@ by commas.</p> <p>Each flag (with a few exceptions) has a short form, such as -<code>CO</code>, as well as a longer form, such as <code>cookie</code>. +<code>CO</code>, as well as a longer form, such as <code>cookie</code>. While it is most common to use the short form, it is recommended that you familiarize yourself with the long form, so that you remember what each flag is supposed to do. @@ -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,10 +143,42 @@ 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> <p>The [C] or [chain] flag indicates that the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is chained to the next rule. That is, if the rule matches, then it is processed as usual and @@ -143,14 +191,14 @@ skipped.</p> <h2><a name="flag_co" id="flag_co">CO|cookie</a></h2> <p>The [CO], or [cookie] flag, allows you to set a cookie when a particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> -matches. The argument consists of three required fields and four optional +matches. The argument consists of three required fields and five optional fields.</p> <p>The full syntax for the flag, including all attributes, is as follows:</p> <div class="example"><p><code> -[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly] +[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly:samesite] </code></p></div> <p>If a literal ':' character is needed in any of the cookie fields, an @@ -159,7 +207,7 @@ alternate syntax is available. To opt-in to the alternate syntax, the cookie specified as ';'.</p> <div class="example"><p><code> -[CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly] +[CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly;samesite] </code></p></div> <p>You must declare a name, a value, and a domain for the cookie to be set.</p> @@ -199,12 +247,18 @@ connections.</dd> <code>1</code>, the cookie will have the <code>HttpOnly</code> flag set, which means that the cookie is inaccessible to JavaScript code on browsers that support this feature.</dd> + +<dt>samesite</dt> +<dd>If set to anything other than <code>false</code> or <code>0</code>, the <code>SameSite</code> +attribute is set to the specified value. Typical values are <code>None</code>, +<code>Lax</code>, and <code>Strict</code>. Available in 2.4.47 and later.</dd> </dl> + <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. @@ -289,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 @@ -315,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 @@ -335,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 @@ -348,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> @@ -410,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"> @@ -434,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 -protect against unintended looping. An alternative maximum number of +<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> @@ -462,7 +516,8 @@ example.</p> <h2><a name="flag_ne" id="flag_ne">NE|noescape</a></h2> <p>By default, special characters, such as <code>&</code> and <code>?</code>, for example, will be converted to their hexcode -equivalent. Using the [NE] flag prevents that from happening. +equivalent for rules that result in external redirects. +Using the [NE] flag prevents that from happening. </p> <pre class="prettyprint lang-config">RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]</pre> @@ -533,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 @@ -681,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 @@ -705,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> @@ -733,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 @@ -741,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 @@ -761,8 +824,8 @@ The <code>L</code> flag can be useful in this context to end the </div></div> <div class="bottomlang"> <p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> | -<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> -</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed again by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Freenode, or sent to our <a href="http://httpd.apache.org/lists.html">mailing lists</a>.</div> +<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p> +</div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>Notice:</strong><br />This is not a Q&A section. Comments placed here should be pointed towards suggestions on improving the documentation or server, and may be removed by our moderators if they are either implemented or considered invalid/off-topic. Questions on how to manage the Apache HTTP Server should be directed at either our IRC channel, #httpd, on Libera.chat, or sent to our <a href="https://httpd.apache.org/lists.html">mailing lists</a>.</div> <script type="text/javascript"><!--//--><![CDATA[//><!-- var comments_shortname = 'httpd'; var comments_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/flags.html'; @@ -780,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 2019 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(); |