| <?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=UTF-8" http-equiv="Content-Type" /> |
| <!-- |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| This file is generated from xml source: DO NOT EDIT |
| XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX |
| --> |
| <title>RewriteRule Flags - Apache HTTP Server Version 2.4</title> |
| <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" /> |
| <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" /> |
| <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" /> |
| <script src="../style/scripts/prettify.min.js" type="text/javascript"> |
| </script> |
| |
| <link href="../images/favicon.ico" rel="shortcut icon" /></head> |
| <body id="manual-page"><div id="page-header"> |
| <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> |
| <p class="apache">Apache HTTP Server Version 2.4</p> |
| <img alt="" src="../images/feather.png" /></div> |
| <div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div> |
| <div id="path"> |
| <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> |
| </div> |
| |
| <p>This document discusses the flags which are available to the |
| <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive, |
| providing detailed explanations and examples.</p> |
| </div> |
| <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_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> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_e">E|env</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_end">END</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_f">F|forbidden</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_g">G|gone</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_h">H|handler</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_l">L|last</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_n">N|next</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_nc">NC|nocase</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_ne">NE|noescape</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_ns">NS|nosubreq</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_p">P|proxy</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_pt">PT|passthrough</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_qsa">QSA|qsappend</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_qsd">QSD|qsdiscard</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_qsl">QSL|qslast</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li> |
| <li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</a></li> |
| </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li><li><a href="avoid.html">When not to use mod_rewrite</a></li><li><a href="#comments_section">Comments</a></li></ul></div> |
| <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> |
| <div class="section"> |
| <h2><a name="introduction" id="introduction">Introduction</a></h2> |
| <p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can have |
| its behavior modified by one or more flags. Flags are included in |
| square brackets at the end of the rule, and multiple flags are separated |
| by commas.</p> |
| <pre class="prettyprint lang-config">RewriteRule pattern target [Flag1,Flag2,Flag3]</pre> |
| |
| |
| <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>. |
| 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. |
| Some flags take one or more arguments. Flags are not case sensitive.</p> |
| |
| <p>Flags that alter metadata associated with the request (T=, H=, E=) |
| have no affect in per-directory and htaccess context, when a substitution |
| (other than '-') is performed during the same round of rewrite processing. |
| </p> |
| |
| <p>Presented here are each of the available flags, along with an example |
| of how you might use them.</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_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> |
| |
| <pre class="prettyprint lang-config">RewriteRule "^search/(.*)$" "/search.php?term=$1"</pre> |
| |
| |
| <p>Given a search term of 'x & y/z', a browser will encode it as |
| 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B |
| flag, this rewrite rule will map to 'search.php?term=x & y/z', which |
| isn't a valid URL, and so would be encoded as |
| <code>search.php?term=x%20&y%2Fz=</code>, which is not what was intended.</p> |
| |
| <p>With the B flag set on this same rule, the parameters are re-encoded |
| before being passed on to the output URL, resulting in a correct mapping to |
| <code>/search.php?term=x%20%26%20y%2Fz</code>.</p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "^search/(.*)$" "/search.php?term=$1" [B,PT]</pre> |
| |
| |
| <p>Note that you may also need to set <code class="directive"><a href="../mod/core.html#allowencodedslashes">AllowEncodedSlashes</a></code> to <code>On</code> to get this |
| particular example to work, as httpd does not allow encoded slashes in URLs, and |
| returns a 404 if it sees one.</p> |
| |
| <p>This escaping is particularly necessary in a proxy situation, |
| 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> |
| </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> |
| <p>The [BNP] flag instructs <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to escape the space character |
| in a backreference to %20 rather than '+'. Useful when the backreference |
| will be used in the path component rather than the query string.</p> |
| |
| <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_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 |
| control moves on to the next rule. However, if it does not match, then |
| the next rule, and any other rules that are chained together, are |
| skipped.</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_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 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:samesite] |
| </code></p></div> |
| |
| <p>If a literal ':' character is needed in any of the cookie fields, an |
| alternate syntax is available. To opt-in to the alternate syntax, the cookie |
| "Name" should be preceded with a ';' character, and field separators should be |
| specified as ';'.</p> |
| |
| <div class="example"><p><code> |
| [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> |
| |
| <dl> |
| <dt>Domain</dt> |
| <dd>The domain for which you want the cookie to be valid. This may be a |
| hostname, such as <code>www.example.com</code>, or it may be a domain, |
| such as <code>.example.com</code>. It must be at least two parts |
| separated by a dot. That is, it may not be merely <code>.com</code> or |
| <code>.net</code>. Cookies of that kind are forbidden by the cookie |
| security model.</dd> |
| </dl> |
| |
| <p>You may optionally also set the following values:</p> |
| |
| <dl> |
| <dt>Lifetime</dt> |
| <dd>The time for which the cookie will persist, in minutes.</dd> |
| <dd>A value of 0 indicates that the cookie will persist only for the |
| current browser session. This is the default value if none is |
| specified.</dd> |
| |
| <dt>Path</dt> |
| <dd>The path, on the current website, for which the cookie is valid, |
| such as <code>/customers/</code> or <code>/files/download/</code>.</dd> |
| <dd>By default, this is set to <code>/</code> - that is, the entire |
| website.</dd> |
| |
| <dt>Secure</dt> |
| <dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>, |
| the cookie will only be permitted to be translated via secure (https) |
| connections.</dd> |
| |
| <dt>httponly</dt> |
| <dd>If set to <code>HttpOnly</code>, <code>true</code>, or |
| <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> |
| |
| |
| <p>In the example give, the rule doesn't rewrite the request. |
| The "-" rewrite target tells mod_rewrite to pass the request |
| through unchanged. Instead, it sets a cookie |
| called 'frontdoor' to a value of 'yes'. The cookie is valid for any host |
| in the <code>.example.com</code> domain. It is set to expire in 1440 |
| minutes (24 hours) and is returned for all URIs.</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_dpi" id="flag_dpi">DPI|discardpath</a></h2> |
| <p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be |
| discarded.</p> |
| <p>This flag is available in version 2.2.12 and later.</p> |
| <p>In per-directory context, the URI each <code class="directive">RewriteRule</code> |
| compares against is the concatenation of the current values of the URI |
| and PATH_INFO.</p> |
| |
| <p>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.</p> |
| |
| <p>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 |
| <code class="directive">RewriteRule</code> 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.</p> |
| |
| <p>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.</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_e" id="flag_e">E|env</a></h2> |
| <p>With the [E], or [env] flag, you can set the value of an environment |
| variable. Note that some environment variables may be set after the rule |
| is run, thus unsetting what you have set. See <a href="../env.html">the |
| Environment Variables document</a> for more details on how Environment |
| variables work.</p> |
| |
| <p>The full syntax for this flag is:</p> |
| |
| <pre class="prettyprint lang-config">[E=VAR:VAL] |
| [E=!VAR]</pre> |
| |
| |
| <p><code>VAL</code> may contain backreferences (<code>$N</code> or |
| <code>%N</code>) which are expanded.</p> |
| |
| <p>Using the short form</p> |
| |
| <div class="example"><p><code> |
| [E=VAR] |
| </code></p></div> |
| |
| <p>you can set the environment variable named <code>VAR</code> to an |
| empty value.</p> |
| |
| <p>The form</p> |
| |
| <div class="example"><p><code> |
| [E=!VAR] |
| </code></p></div> |
| |
| <p>allows to unset a previously set environment variable named |
| <code>VAR</code>.</p> |
| |
| <p>Environment variables can then be used in a variety of |
| contexts, including CGI programs, other RewriteRule directives, or |
| CustomLog directives.</p> |
| |
| <p>The following example sets an environment variable called 'image' to a |
| 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> |
| |
| |
| <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 |
| an example, not as a recommendation.</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_end" id="flag_end">END</a></h2> |
| <p>Using the [END] flag terminates not only the current round of rewrite |
| processing (like [L]) but also prevents any subsequent rewrite |
| processing from occurring in per-directory (htaccess) context.</p> |
| |
| <p>This does not apply to new requests resulting from external |
| redirects.</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_f" id="flag_f">F|forbidden</a></h2> |
| <p>Using the [F] flag causes the server to return a 403 Forbidden status |
| code to the client. While the same behavior can be accomplished using |
| the <code class="directive"><a href="../mod/mod_access_compat.html#deny">Deny</a></code> directive, this |
| 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> |
| |
| |
| <p>This example uses the "-" syntax for the rewrite target, which means |
| that the requested URI is not modified. There's no reason to rewrite to |
| another URI, if you're going to forbid the request.</p> |
| |
| <p>When using [F], an [L] is implied - that is, the response is returned |
| immediately, and no further rules are evaluated.</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_g" id="flag_g">G|gone</a></h2> |
| <p>The [G] flag forces the server to return a 410 Gone status with the |
| response. This indicates that a resource used to be available, but is no |
| 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> |
| |
| |
| <p>When using [G], an [L] is implied - that is, the response is returned |
| immediately, and no further rules are evaluated.</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_h" id="flag_h">H|handler</a></h2> |
| <p>Forces the resulting request to be handled with the specified |
| 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> |
| |
| |
| <p> |
| The regular expression above - <code>!\.</code> - will match any request |
| that does not contain the literal <code>.</code> character. |
| </p> |
| |
| <p>This can be also used to force the handler based on some conditions. |
| For example, the following snippet used in per-server context allows |
| <code>.php</code> files to be <em>displayed</em> by <code>mod_php</code> |
| if they are requested with the <code>.phps</code> extension:</p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]</pre> |
| |
| |
| <p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will |
| match any request that starts with <code>/source/</code> followed by 1 or |
| n characters followed by <code>.phps</code> literally. The backreference |
| $1 referrers to the captured match within parenthesis of the regular |
| expression.</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_l" id="flag_l">L|last</a></h2> |
| <p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing |
| the rule set. In most contexts, this means that if the rule matches, no |
| further rules will be processed. This corresponds to the |
| <code>last</code> command in Perl, or the <code>break</code> command in |
| C. Use this flag to indicate that the current rule should be applied |
| immediately without considering further rules.</p> |
| |
| <p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either |
| <code>.htaccess</code> files or in |
| <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections, |
| it is important to have some understanding of how the rules are |
| processed. The simplified form of this is that once the rules have been |
| processed, the rewritten request is handed back to the URL parsing |
| engine to do what it may with it. It is possible that as the rewritten |
| request is handled, the <code>.htaccess</code> file or |
| <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section |
| may be encountered again, and thus the ruleset may be run again from the |
| start. Most commonly this will happen if one of the rules causes a |
| redirect - either internal or external - causing the request process to |
| start over.</p> |
| |
| <p>It is therefore important, if you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directives in one of these |
| contexts, that you take explicit steps to avoid rules looping, and not |
| count solely on the [L] flag to terminate execution of a series of |
| rules, as shown below.</p> |
| |
| <p> An alternative flag, [END], can be used to terminate not only the |
| current round of rewrite processing but prevent any subsequent |
| rewrite processing from occurring in per-directory (htaccess) |
| context. This does not apply to new requests resulting from external |
| redirects.</p> |
| |
| <p>The example given here will rewrite any request to |
| <code>index.php</code>, giving the original request as a query string |
| argument to <code>index.php</code>, however, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> ensures that if the request |
| 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> |
| |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> |
| <div class="section"> |
| <h2><a name="flag_n" id="flag_n">N|next</a></h2> |
| <p> |
| 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. |
| </p> |
| <p> |
| The [Next] flag could be used, for example, if you wished to replace a |
| certain string or letter repeatedly in a request. The example shown here |
| will replace A with B everywhere in a request, and will continue doing |
| so until there are no more As to be replaced. |
| </p> |
| <pre class="prettyprint lang-config">RewriteRule "(.*)A(.*)" "$1B$2" [N]</pre> |
| |
| <p>You can think of this as a <code>while</code> loop: While this |
| 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 |
| 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] |
| # ... or, give up if after 10 loops |
| RewriteRule "(.+)[><;]$" "$1" [N=10]</pre> |
| |
| |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> |
| <div class="section"> |
| <h2><a name="flag_nc" id="flag_nc">NC|nocase</a></h2> |
| <p>Use of the [NC] flag causes the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be matched in a |
| case-insensitive manner. That is, it doesn't care whether letters appear |
| as upper-case or lower-case in the matched URI.</p> |
| |
| <p>In the example below, any request for an image file will be proxied |
| to your dedicated image server. The match is case-insensitive, so that |
| <code>.jpg</code> and <code>.JPG</code> files are both acceptable, for |
| example.</p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]</pre> |
| |
| </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div> |
| <div class="section"> |
| <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. |
| </p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]</pre> |
| |
| |
| <p> |
| The above example will redirect <code>/anchor/xyz</code> to |
| <code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the # |
| being converted to its hexcode equivalent, <code>%23</code>, which will |
| then result in a 404 Not Found error condition. |
| </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_ns" id="flag_ns">NS|nosubreq</a></h2> |
| <p>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. Also, when <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code> |
| tries to find out information about possible directory default files |
| (such as <code>index.html</code> 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.</p> |
| |
| <p>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.</p> |
| |
| <p> |
| Images, javascript files, or css files, loaded as part of an HTML page, |
| are not subrequests - the browser requests them as separate HTTP |
| requests. |
| </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_p" id="flag_p">P|proxy</a></h2> |
| <p>Use of the [P] flag causes the request to be handled by |
| <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For |
| example, if you wanted all image requests to be handled by a back-end |
| image server, you might do something like the following:</p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]</pre> |
| |
| |
| <p>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.</p> |
| |
| <p> |
| You must make sure that the substitution string is a valid URI |
| (typically starting with <code>http://</code><em>hostname</em>) which can be |
| handled by the <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. If not, you will get an |
| error from the proxy module. Use this flag to achieve a |
| more powerful implementation of the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive, |
| to map remote content into the namespace of the local server.</p> |
| |
| <div class="warning"> |
| <h3>Security Warning</h3> |
| <p>Take care when constructing the target URL of the rule, considering |
| the security impact from allowing the client influence over the set of |
| URLs to which your server will act as a proxy. Ensure that the scheme |
| and hostname part of the URL is either fixed, or does not allow the |
| client undue influence.</p> |
| </div> |
| |
| <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> |
| </div> |
| |
| <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order |
| to use this flag.</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_pt" id="flag_pt">PT|passthrough</a></h2> |
| |
| <p> |
| 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 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be passed back through |
| URL mapping, so that location-based mappings, such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, <code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code>, or <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, for example, might have a |
| chance to take effect. |
| </p> |
| |
| <p> |
| If, for example, you have an |
| <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> |
| for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should |
| use the [PT] flag to ensure that the |
| <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated. |
| </p> |
| |
| <pre class="prettyprint lang-config">Alias "/icons" "/usr/local/apache/icons" |
| RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]</pre> |
| |
| |
| <p> |
| Omission of the [PT] flag in this case will cause the Alias to be |
| ignored, resulting in a 'File not found' error being returned. |
| </p> |
| |
| <p>The <code>PT</code> flag implies the <code>L</code> flag: |
| rewriting will be stopped in order to pass the request to |
| the next phase of processing.</p> |
| |
| <p>Note that the <code>PT</code> flag is implied in per-directory |
| contexts such as |
| <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections |
| or in <code>.htaccess</code> files. The only way to circumvent that |
| is to rewrite to <code>-</code>.</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_qsa" id="flag_qsa">QSA|qsappend</a></h2> |
| <p> |
| When the replacement URI contains a query string, the default behavior |
| of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard |
| the existing query string, and replace it with the newly generated one. |
| Using the [QSA] flag causes the query strings to be combined. |
| </p> |
| |
| <p>Consider the following rule:</p> |
| |
| <pre class="prettyprint lang-config">RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]</pre> |
| |
| |
| <p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be |
| mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA] |
| flag, that same request will be mapped to |
| <code>/page.php?page=123</code> - that is, the existing query string |
| will be discarded. |
| </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_qsd" id="flag_qsd">QSD|qsdiscard</a></h2> |
| <p> |
| When the requested URI contains a query string, and the target URI does |
| not, the default behavior of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to copy that query |
| string to the target URI. Using the [QSD] flag causes the query string |
| to be discarded. |
| </p> |
| |
| <p>This flag is available in version 2.4.0 and later.</p> |
| |
| <p> |
| Using [QSD] and [QSA] together will result in [QSD] taking precedence. |
| </p> |
| |
| <p> |
| If the target URI has a query string, the default behavior will be |
| observed - that is, the original query string will be discarded and |
| replaced with the query string in the <code>RewriteRule</code> target |
| URI. |
| </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_qsl" id="flag_qsl">QSL|qslast</a></h2> |
| <p> |
| By default, the first (left-most) question mark in the substitution |
| delimits the path from the query string. Using the [QSL] flag instructs |
| <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to instead split |
| the two components using the last (right-most) question mark. </p> |
| |
| <p> |
| This is useful when mapping to files that have literal question marks in |
| their filename. If no query string is used in the substitution, |
| a question mark can be appended to it in combination with this flag. </p> |
| |
| <p> This flag is available in version 2.4.19 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_r" id="flag_r">R|redirect</a></h2> |
| <p> |
| 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 |
| <code>http://servername/</code>) then a redirect will be issued to that |
| location. Otherwise, the current protocol, servername, and port number |
| will be used to generate the URL sent with the redirect. |
| </p> |
| |
| <p> |
| <em>Any</em> 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. However, |
| 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 <code>L</code> were used.</p> |
| |
| <p>In addition to response status codes, you may also specify redirect |
| status using their symbolic names: <code>temp</code> (default), |
| <code>permanent</code>, or <code>seeother</code>.</p> |
| |
| <p> |
| 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 |
| <code>http://thishost[:thisport]</code> to the URI, but then passes this |
| on to the next rule in the ruleset, which can often result in 'Invalid |
| URI in request' warnings. |
| </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_s" id="flag_s">S|skip</a></h2> |
| <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> |
| |
| <pre class="prettyprint lang-config"># Is the request for a non-existent file? |
| RewriteCond "%{REQUEST_FILENAME}" "!-f" |
| RewriteCond "%{REQUEST_FILENAME}" "!-d" |
| # If so, skip these two RewriteRules |
| RewriteRule ".?" "-" [S=2] |
| |
| 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 |
| <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately |
| following it. Thus, if you want to make a <code>RewriteCond</code> apply |
| to several <code>RewriteRule</code>s, one possible technique is to |
| negate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. You can |
| 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" |
| # Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza. |
| RewriteRule ".?" "-" [S=3] |
| |
| # IF the file exists, then: |
| RewriteRule "(.*\.gif)" "images.php?$1" |
| RewriteRule "(.*\.html)" "docs.php?$1" |
| # Skip past the "else" stanza. |
| RewriteRule ".?" "-" [S=1] |
| # ELSE... |
| RewriteRule "(.*)" "404.php?file=$1" |
| # END</pre> |
| |
| |
| <p>It is probably easier to accomplish this kind of configuration using |
| the <code class="directive"><If></code>, <code class="directive"><ElseIf></code>, and <code class="directive"><Else></code> directives instead.</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_t" id="flag_t">T|type</a></h2> |
| <p>Sets the MIME type with which the resulting response will be |
| sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p> |
| |
| <p>For example, you might use the following technique to serve Perl |
| 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> |
| |
| |
| <p>Or, perhaps, if you have a camera that produces jpeg images without |
| 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> |
| |
| |
| <p>Please note that this is a trivial example, and could be better done |
| using <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code> |
| instead. Always consider the alternate |
| solutions to a problem before resorting to rewrite, which will |
| invariably be a less efficient solution than the alternatives.</p> |
| |
| <p> |
| If used in per-directory context, use only <code>-</code> (dash) |
| as the substitution <em>for the entire round of mod_rewrite processing</em>, |
| otherwise the MIME-type set with this flag is lost due to an internal |
| re-processing (including subsequent rounds of mod_rewrite processing). |
| The <code>L</code> flag can be useful in this context to end the |
| <em>current</em> round of mod_rewrite processing.</p> |
| |
| </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 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'; |
| (function(w, d) { |
| if (w.location.hostname.toLowerCase() == "httpd.apache.org") { |
| d.write('<div id="comments_thread"><\/div>'); |
| var s = d.createElement('script'); |
| s.type = 'text/javascript'; |
| s.async = true; |
| s.src = 'https://comments.apache.org/show_comments.lua?site=' + comments_shortname + '&page=' + comments_identifier; |
| (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s); |
| } |
| else { |
| d.write('<div id="comments_thread">Comments are disabled for this page at the moment.<\/div>'); |
| } |
| })(window, document); |
| //--><!]]></script></div><div id="footer"> |
| <p class="apache">Copyright 2022 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(); |
| } |
| //--><!]]></script> |
| </body></html> |