granicus.if.org Git - apache/blob - docs/manual/rewrite/flags.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>RewriteRule Flags - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <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" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <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>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>RewriteRule Flags</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English">&nbsp;en&nbsp;</a> |
  25 <a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
  26 </div>
  27
  28 <p>This document discusses the flags which are available to the
  29 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
  30 providing detailed explanations and examples.</p>
  31 </div>
  32 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
  33 <li><img alt="" src="../images/down.gif" /> <a href="#flag_b">B (escape backreferences)</a></li>
  34 <li><img alt="" src="../images/down.gif" /> <a href="#flag_c">C|chain</a></li>
  35 <li><img alt="" src="../images/down.gif" /> <a href="#flag_co">CO|cookie</a></li>
  36 <li><img alt="" src="../images/down.gif" /> <a href="#flag_dpi">DPI|discardpath</a></li>
  37 <li><img alt="" src="../images/down.gif" /> <a href="#flag_e">E|env</a></li>
  38 <li><img alt="" src="../images/down.gif" /> <a href="#flag_end">END</a></li>
  39 <li><img alt="" src="../images/down.gif" /> <a href="#flag_f">F|forbidden</a></li>
  40 <li><img alt="" src="../images/down.gif" /> <a href="#flag_g">G|gone</a></li>
  41 <li><img alt="" src="../images/down.gif" /> <a href="#flag_h">H|handler</a></li>
  42 <li><img alt="" src="../images/down.gif" /> <a href="#flag_l">L|last</a></li>
  43 <li><img alt="" src="../images/down.gif" /> <a href="#flag_n">N|next</a></li>
  44 <li><img alt="" src="../images/down.gif" /> <a href="#flag_nc">NC|nocase</a></li>
  45 <li><img alt="" src="../images/down.gif" /> <a href="#flag_ne">NE|noescape</a></li>
  46 <li><img alt="" src="../images/down.gif" /> <a href="#flag_ns">NS|nosubreq</a></li>
  47 <li><img alt="" src="../images/down.gif" /> <a href="#flag_p">P|proxy</a></li>
  48 <li><img alt="" src="../images/down.gif" /> <a href="#flag_pt">PT|passthrough</a></li>
  49 <li><img alt="" src="../images/down.gif" /> <a href="#flag_qsa">QSA|qsappend</a></li>
  50 <li><img alt="" src="../images/down.gif" /> <a href="#flag_qsd">QSD|qsdiscard</a></li>
  51 <li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li>
  52 <li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li>
  53 <li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</a></li>
  54 </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></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  55 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  56 <div class="section">
  57 <h2><a name="introduction" id="introduction">Introduction</a></h2>
  58 <p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can have
  59 its behavior modified by one or more flags. Flags are included in
  60 square brackets at the end of the rule, and multiple flags are separated
  61 by commas.</p>
  62 <pre class="prettyprint lang-config">RewriteRule pattern target [Flag1,Flag2,Flag3]</pre>
  63
  64
  65 <p>The flags all have a short form, such as <code>CO</code>, as well as
  66 a longer form, such as <code>cookie</code>. Some flags take one or more
  67 arguments. Flags are not case sensitive.</p>
  68
  69 <p>Each flag (with a few exceptions)
  70 has a long and short form. While it is most common to use
  71 the short form, it is recommended that you familiarize yourself with the
  72 long form, so that you remember what each flag is supposed to do.</p>
  73
  74 <p>Flags that alter metadata associated with the request (T=, H=, E=)
  75 have no affect in per-directory and htaccess context, when a substitution
  76 (other than '-') is performed during the same round of rewrite processing.
  77 </p>
  78
  79 <p>Presented here are each of the available flags, along with an example
  80 of how you might use them.</p>
  81 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  82 <div class="section">
  83 <h2><a name="flag_b" id="flag_b">B (escape backreferences)</a></h2>
  84 <p>The [B] flag instructs <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to escape non-alphanumeric
  85 characters before applying the transformation.
  86 </p>
  87
  88 <p><code>mod_rewrite</code> has to unescape URLs before mapping them,
  89 so backreferences will be unescaped at the time they are applied.
  90 Using the B flag, non-alphanumeric characters in backreferences
  91 will be escaped. For example, consider the rule:</p>
  92
  93 <pre class="prettyprint lang-config">RewriteRule ^search/(.*)$ /search.php?term=$1</pre>
  94
  95
  96 <p>Given a search term of 'x &amp; y/z', a browser will encode it as
  97 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B
  98 flag, this rewrite rule will map to 'search.php?term=x &amp; y/z', which
  99 isn't a valid URL, and so would be encoded as
 100 <code>search.php?term=x%20&amp;y%2Fz=</code>, which is not what was intended.</p>
 101
 102 <p>With the B flag set on this same rule, the parameters are re-encoded
 103 before being passed on to the output URL, resulting in a correct mapping to
 104 <code>/search.php?term=x%20%26%20y%2Fz</code>.</p>
 105
 106 <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
 107 particular example to work, as httpd does not allow encoded slashes in URLs, and
 108 returns a 404 if it sees one.</p>
 109
 110 <p>This escaping is particularly necessary in a proxy situation,
 111 when the backend may break if presented with an unescaped URL.</p>
 112
 113 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 114 <div class="section">
 115 <h2><a name="flag_c" id="flag_c">C|chain</a></h2>
 116 <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
 117 rule. That is, if the rule matches, then it is processed as usual and
 118 control moves on to the next rule. However, if it does not match, then
 119 the next rule, and any other rules that are chained together, will be
 120 skipped.</p>
 121
 122 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 123 <div class="section">
 124 <h2><a name="flag_co" id="flag_co">CO|cookie</a></h2>
 125 <p>The [CO], or [cookie] flag, allows you to set a cookie when a
 126 particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
 127 matches. The argument consists of three required fields and four optional
 128 fields.</p>
 129
 130 <p>The full syntax for the flag, including all attributes, is as
 131 follows:</p>
 132
 133 <div class="example"><p><code>
 134 [CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]
 135 </code></p></div>
 136
 137 <p>You must declare a name, a value, and a domain for the cookie to be set.</p>
 138
 139 <dl>
 140 <dt>Domain</dt>
 141 <dd>The domain for which you want the cookie to be valid. This may be a
 142 hostname, such as <code>www.example.com</code>, or it may be a domain,
 143 such as <code>.example.com</code>. It must be at least two parts
 144 separated by a dot. That is, it may not be merely <code>.com</code> or
 145 <code>.net</code>. Cookies of that kind are forbidden by the cookie
 146 security model.</dd>
 147 </dl>
 148
 149 <p>You may optionally also set the following values:</p>
 150
 151 <dl>
 152 <dt>Lifetime</dt>
 153 <dd>The time for which the cookie will persist, in minutes.</dd>
 154 <dd>A value of 0 indicates that the cookie will persist only for the
 155 current browser session. This is the default value if none is
 156 specified.</dd>
 157
 158 <dt>Path</dt>
 159 <dd>The path, on the current website, for which the cookie is valid,
 160 such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
 161 <dd>By default, this is set to <code>/</code> - that is, the entire
 162 website.</dd>
 163
 164 <dt>Secure</dt>
 165 <dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
 166 the cookie will only be permitted to be translated via secure (https)
 167 connections.</dd>
 168
 169 <dt>httponly</dt>
 170 <dd>If set to <code>HttpOnly</code>, <code>true</code>, or
 171 <code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
 172 which means that the cookie will be inaccessible to JavaScript code on
 173 browsers that support this feature.</dd>
 174 </dl>
 175
 176 <p>Several examples are offered here:</p>
 177
 178 <pre class="prettyprint lang-config">
 179 RewriteEngine On
 180 RewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]
 181 </pre>
 182
 183
 184 <p>In the example give, the rule doesn't rewrite the request.
 185 The "-" rewrite target tells mod_rewrite to pass the request
 186 through unchanged. Instead, it sets a cookie
 187 called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
 188 in the <code>.example.com</code> domain. It will be set to expire in 1440
 189 minutes (24 hours) and will be returned for all URIs.</p>
 190
 191 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 192 <div class="section">
 193 <h2><a name="flag_dpi" id="flag_dpi">DPI|discardpath</a></h2>
 194 <p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
 195 discarded.</p>
 196 <p>This flag is available in version 2.2.12 and later.</p>
 197 <p>In per-directory context, the URI each <code class="directive">RewriteRule</code>
 198 compares against is the concatenation of the current values of the URI
 199 and PATH_INFO.</p>
 200
 201 <p>The current URI can be the initial URI as requested by the client, the
 202 result of a previous round of mod_rewrite processing, or the result of
 203 a prior rule in the current round of mod_rewrite processing.</p>
 204
 205 <p>In contrast, the PATH_INFO that is appended to the URI before each
 206 rule reflects only the value of PATH_INFO before this round of
 207 mod_rewrite processing. As a consequence, if large portions
 208 of the URI are matched and copied into a substitution in multiple
 209 <code class="directive">RewriteRule</code> directives, without regard for
 210 which parts of the URI came from the current PATH_INFO, the final
 211 URI may have multiple copies of PATH_INFO appended to it.</p>
 212
 213 <p>Use this flag on any substitution where the PATH_INFO that resulted
 214 from the previous mapping of this request to the filesystem is not of
 215 interest.  This flag permanently forgets the PATH_INFO established
 216 before this round of mod_rewrite processing began. PATH_INFO will
 217 not be recalculated until the current round of mod_rewrite processing
 218 completes.  Subsequent rules during this round of processing will see
 219 only the direct result of substitutions, without any PATH_INFO
 220 appended.</p>
 221 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 222 <div class="section">
 223 <h2><a name="flag_e" id="flag_e">E|env</a></h2>
 224 <p>With the [E], or [env] flag, you can set the value of an environment
 225 variable. Note that some environment variables may be set after the rule
 226 is run, thus unsetting what you have set. See <a href="../env.html">the
 227 Environment Variables document</a> for more details on how Environment
 228 variables work.</p>
 229
 230 <p>The full syntax for this flag is:</p>
 231
 232 <div class="example"><p><code>
 233 [E=VAR:VAL]
 234 [E=!VAR]
 235 </code></p></div>
 236
 237 <p><code>VAL</code> may contain backreferences (<code>$N</code> or
 238 <code>%N</code>) which will be expanded.</p>
 239
 240 <p>Using the short form</p>
 241
 242 <div class="example"><p><code>
 243 [E=VAR]
 244 </code></p></div>
 245
 246 <p>you can set the environment variable named <code>VAR</code> to an
 247 empty value.</p>
 248
 249 <p>The form</p>
 250
 251 <div class="example"><p><code>
 252 [E=!VAR]
 253 </code></p></div>
 254
 255 <p>allows to unset a previously set environment variable named
 256 <code>VAR</code>.</p>
 257
 258 <p>Environment variables can then be used in a variety of
 259 contexts, including CGI programs, other RewriteRule directives, or
 260 CustomLog directives.</p>
 261
 262 <p>The following example sets an environment variable called 'image' to a
 263 value of '1' if the requested URI is an image file. Then, that
 264 environment variable is used to exclude those requests from the access
 265 log.</p>
 266
 267 <pre class="prettyprint lang-config">
 268 RewriteRule \.(png|gif|jpg)$ - [E=image:1]
 269 CustomLog logs/access_log combined env=!image
 270 </pre>
 271
 272
 273 <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
 274 an example, not as a recommendation.</p>
 275 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 276 <div class="section">
 277 <h2><a name="flag_end" id="flag_end">END</a></h2>
 278 <p>Using the [END] flag terminates not only the current round of rewrite
 279 processing (like [L]) but also prevents any subsequent rewrite
 280 processing from occurring in per-directory (htaccess) context.</p>
 281
 282 <p>This does not apply to new requests resulting from external
 283 redirects.</p>
 284 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 285 <div class="section">
 286 <h2><a name="flag_f" id="flag_f">F|forbidden</a></h2>
 287 <p>Using the [F] flag causes the server to return a 403 Forbidden status
 288 code to the client. While the same behavior can be accomplished using
 289 the <code class="directive"><a href="../mod/mod_access_compat.html#deny">Deny</a></code> directive, this
 290 allows more flexibility in assigning a Forbidden status.</p>
 291
 292 <p>The following rule will forbid <code>.exe</code> files from being
 293 downloaded from your server.</p>
 294
 295 <pre class="prettyprint lang-config">RewriteRule \.exe - [F]</pre>
 296
 297
 298 <p>This example uses the "-" syntax for the rewrite target, which means
 299 that the requested URI is not modified. There's no reason to rewrite to
 300 another URI, if you're going to forbid the request.</p>
 301
 302 <p>When using [F], an [L] is implied - that is, the response is returned
 303 immediately, and no further rules are evaluated.</p>
 304
 305 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 306 <div class="section">
 307 <h2><a name="flag_g" id="flag_g">G|gone</a></h2>
 308 <p>The [G] flag forces the server to return a 410 Gone status with the
 309 response. This indicates that a resource used to be available, but is no
 310 longer available.</p>
 311
 312 <p>As with the [F] flag, you will typically use the "-" syntax for the
 313 rewrite target when using the [G] flag:</p>
 314
 315 <pre class="prettyprint lang-config">RewriteRule oldproduct - [G,NC]</pre>
 316
 317
 318 <p>When using [G], an [L] is implied - that is, the response is returned
 319 immediately, and no further rules are evaluated.</p>
 320
 321 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 322 <div class="section">
 323 <h2><a name="flag_h" id="flag_h">H|handler</a></h2>
 324 <p>Forces the resulting request to be handled with the specified
 325 handler. For example, one might use this to force all files without a
 326 file extension to be parsed by the php handler:</p>
 327
 328 <pre class="prettyprint lang-config">RewriteRule !\. - [H=application/x-httpd-php]</pre>
 329
 330
 331 <p>
 332 The regular expression above - <code>!\.</code> - will match any request
 333 that does not contain the literal <code>.</code> character.
 334 </p>
 335
 336 <p>This can be also used to force the handler based on some conditions.
 337 For example, the following snippet used in per-server context allows
 338 <code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
 339 if they are requested with the <code>.phps</code> extension:</p>
 340
 341 <pre class="prettyprint lang-config">
 342 RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
 343 </pre>
 344
 345
 346 <p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
 347 match any request that starts with <code>/source/</code> followed by 1 or
 348 n characters followed by <code>.phps</code> literally. The backreference
 349 $1 referrers to the captured match within parenthesis of the regular
 350 expression.</p>
 351 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 352 <div class="section">
 353 <h2><a name="flag_l" id="flag_l">L|last</a></h2>
 354 <p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
 355 the rule set. In most contexts, this means that if the rule matches, no
 356 further rules will be processed. This corresponds to the
 357 <code>last</code> command in Perl, or the <code>break</code> command in
 358 C. Use this flag to indicate that the current rule should be applied
 359 immediately without considering further rules.</p>
 360
 361 <p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
 362 <code>.htaccess</code> files or in
 363 <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections,
 364 it is important to have some understanding of how the rules are
 365 processed.  The simplified form of this is that once the rules have been
 366 processed, the rewritten request is handed back to the URL parsing
 367 engine to do what it may with it. It is possible that as the rewritten
 368 request is handled, the <code>.htaccess</code> file or
 369 <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> section
 370 may be encountered again, and thus the ruleset may be run again from the
 371 start. Most commonly this will happen if one of the rules causes a
 372 redirect - either internal or external - causing the request process to
 373 start over.</p>
 374
 375 <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
 376 contexts, that you take explicit steps to avoid rules looping, and not
 377 count solely on the [L] flag to terminate execution of a series of
 378 rules, as shown below.</p>
 379
 380 <p> An alternative flag, [END], can be used to terminate not only the
 381 current round of rewrite processing but prevent any subsequent
 382 rewrite processing from occuring in per-directory (htaccess)
 383 context. This does not apply to new requests resulting from external
 384 redirects.</p>
 385
 386 <p>The example given here will rewrite any request to
 387 <code>index.php</code>, giving the original request as a query string
 388 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
 389 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>
 390
 391 <pre class="prettyprint lang-config">
 392 RewriteBase /
 393 RewriteCond %{REQUEST_URI} !=/index.php
 394 RewriteRule ^(.*) /index.php?req=$1 [L,PT]
 395 </pre>
 396
 397 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 398 <div class="section">
 399 <h2><a name="flag_n" id="flag_n">N|next</a></h2>
 400 <p>
 401 The [N] flag causes the ruleset to start over again from the top, using
 402 the result of the ruleset so far as a starting point. Use
 403 with extreme caution, as it may result in loop.
 404 </p>
 405 <p>
 406 The [Next] flag could be used, for example, if you wished to replace a
 407 certain string or letter repeatedly in a request. The example shown here
 408 will replace A with B everywhere in a request, and will continue doing
 409 so until there are no more As to be replaced.
 410 </p>
 411
 412 <pre class="prettyprint lang-config">RewriteRule (.*)A(.*) $1B$2 [N]</pre>
 413
 414
 415 <p>You can think of this as a <code>while</code> loop: While this
 416 pattern still matches (i.e., while the URI still contains an
 417 <code>A</code>), perform this substitution (i.e., replace the
 418 <code>A</code> with a <code>B</code>).</p>
 419
 420 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 421 <div class="section">
 422 <h2><a name="flag_nc" id="flag_nc">NC|nocase</a></h2>
 423 <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
 424 case-insensitive manner. That is, it doesn't care whether letters appear
 425 as upper-case or lower-case in the matched URI.</p>
 426
 427 <p>In the example below, any request for an image file will be proxied
 428 to your dedicated image server. The match is case-insensitive, so that
 429 <code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
 430 example.</p>
 431
 432 <pre class="prettyprint lang-config">RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]</pre>
 433
 434 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 435 <div class="section">
 436 <h2><a name="flag_ne" id="flag_ne">NE|noescape</a></h2>
 437 <p>By default, special characters, such as <code>&amp;</code> and
 438 <code>?</code>, for example, will be converted to their hexcode
 439 equivalent. Using the [NE] flag prevents that from happening.
 440 </p>
 441
 442 <pre class="prettyprint lang-config">RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]</pre>
 443
 444
 445 <p>
 446 The above example will redirect <code>/anchor/xyz</code> to
 447 <code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
 448 being converted to its hexcode equivalent, <code>%23</code>, which will
 449 then result in a 404 Not Found error condition.
 450 </p>
 451
 452 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 453 <div class="section">
 454 <h2><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h2>
 455 <p>Use of the [NS] flag prevents the rule from being used on
 456 subrequests. For example, a page which is included using an SSI (Server
 457 Side Include) is a subrequest, and you may want to avoid rewrites
 458 happening on those subrequests. Also, when <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code>
 459 tries to find out information about possible directory default files
 460 (such as <code>index.html</code> files), this is an internal
 461 subrequest, and you often want to avoid rewrites on such subrequests.
 462 On subrequests, it is not always useful, and can even cause errors, if
 463 the complete set of rules are applied. Use this flag to exclude
 464 problematic rules.</p>
 465
 466 <p>To decide whether or not to use this rule: if you prefix URLs with
 467 CGI-scripts, to force them to be processed by the CGI-script, it's
 468 likely that you will run into problems (or significant overhead)
 469 on sub-requests. In these cases, use this flag.</p>
 470
 471 <p>
 472 Images, javascript files, or css files, loaded as part of an HTML page,
 473 are not subrequests - the browser requests them as separate HTTP
 474 requests.
 475 </p>
 476 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 477 <div class="section">
 478 <h2><a name="flag_p" id="flag_p">P|proxy</a></h2>
 479 <p>Use of the [P] flag causes the request to be handled by
 480 <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For
 481 example, if you wanted all image requests to be handled by a back-end
 482 image server, you might do something like the following:</p>
 483
 484 <pre class="prettyprint lang-config">RewriteRule /(.*)\.(jpg|gif|png)$ http://images.example.com/$1.$2 [P]</pre>
 485
 486
 487 <p>Use of the [P] flag implies [L] - that is, the request is immediately
 488 pushed through the proxy, and any following rules will not be
 489 considered.</p>
 490
 491 <p>
 492 You must make sure that the substitution string is a valid URI
 493 (typically starting with <code>http://</code><em>hostname</em>) which can be
 494 handled by the <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. If not, you will get an
 495 error from the proxy module. Use this flag to achieve a
 496 more powerful implementation of the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive,
 497 to map remote content into the namespace of the local server.</p>
 498
 499 <div class="warning">
 500 <h3>Security Warning</h3>
 501 <p>Take care when constructing the target URL of the rule, considering
 502 the security impact from allowing the client influence over the set of
 503 URLs to which your server will act as a proxy.  Ensure that the scheme
 504 and hostname part of the URL is either fixed, or does not allow the
 505 client undue influence.</p>
 506 </div>
 507
 508 <p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
 509 to use this flag.</p>
 510
 511 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 512 <div class="section">
 513 <h2><a name="flag_pt" id="flag_pt">PT|passthrough</a></h2>
 514
 515 <p>
 516 The target (or substitution string) in a RewriteRule is assumed to be a
 517 file path, by default. The use of the [PT] flag causes it to be treated
 518 as a URI instead. That is to say, the
 519 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
 520 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
 521 chance to take effect.
 522 </p>
 523
 524 <p>
 525 If, for example, you have an
 526 <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
 527 for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should
 528 use the [PT] flag to ensure that the
 529 <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated.
 530 </p>
 531
 532 <pre class="prettyprint lang-config">
 533 Alias /icons /usr/local/apache/icons
 534 RewriteRule /pics/(.+)\.jpg$ /icons/$1.gif [PT]
 535 </pre>
 536
 537
 538 <p>
 539 Omission of the [PT] flag in this case will cause the Alias to be
 540 ignored, resulting in a 'File not found' error being returned.
 541 </p>
 542
 543 <p>The <code>PT</code> flag implies the <code>L</code> flag:
 544 rewriting will be stopped in order to pass the request to
 545 the next phase of processing.</p>
 546
 547 <p>Note that the <code>PT</code> flag is implied in per-directory
 548 contexts such as
 549 <code class="directive"><a href="../mod/core.html#directory">&lt;Directory&gt;</a></code> sections
 550 or in <code>.htaccess</code> files. The only way to circumvent that
 551 is to rewrite to <code>-</code>.</p>
 552
 553 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 554 <div class="section">
 555 <h2><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h2>
 556 <p>
 557 When the replacement URI contains a query string, the default behavior
 558 of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard
 559 the existing query string, and replace it with the newly generated one.
 560 Using the [QSA] flag causes the query strings to be combined.
 561 </p>
 562
 563 <p>Consider the following rule:</p>
 564
 565 <pre class="prettyprint lang-config">RewriteRule /pages/(.+) /page.php?page=$1 [QSA]</pre>
 566
 567
 568 <p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
 569 mapped to <code>/page.php?page=123&amp;one=two</code>. Without the [QSA]
 570 flag, that same request will be mapped to
 571 <code>/page.php?page=123</code> - that is, the existing query string
 572 will be discarded.
 573 </p>
 574 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 575 <div class="section">
 576 <h2><a name="flag_qsd" id="flag_qsd">QSD|qsdiscard</a></h2>
 577 <p>
 578 When the requested URI contains a query string, and the target URI does
 579 not, the default behavior of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to copy that query
 580 string to the target URI. Using the [QSD] flag causes the query string
 581 to be discarded.
 582 </p>
 583
 584 <p>This flag is available in version 2.4.0 and later.</p>
 585
 586 <p>
 587 Using [QSD] and [QSA] together will result in [QSD] taking precedence.
 588 </p>
 589
 590 <p>
 591 If the target URI has a query string, the default behavior will be
 592 observed - that is, the original query string will be discarded and
 593 replaced with the query string in the <code>RewriteRule</code> target
 594 URI.
 595 </p>
 596
 597 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 598 <div class="section">
 599 <h2><a name="flag_r" id="flag_r">R|redirect</a></h2>
 600 <p>
 601 Use of the [R] flag causes a HTTP redirect to be issued to the browser.
 602 If a fully-qualified URL is specified (that is, including
 603 <code>http://servername/</code>) then a redirect will be issued to that
 604 location. Otherwise, the current protocol, servername, and port number
 605 will be used to generate the URL sent with the redirect.
 606 </p>
 607
 608 <p>
 609 <em>Any</em> valid HTTP response  status code may be specified,
 610 using the syntax [R=305], with a 302 status code being used by
 611 default if none is specified. The status code specified need not
 612 necessarily be a redirect (3xx) status code.
 613 </p>
 614
 615 <p>If a status code is outside the redirect range (300-399) then the
 616 substitution string is dropped entirely, and rewriting is stopped as if
 617 the <code>L</code> were used.</p>
 618
 619 <p>In addition to response status codes, you may also specify redirect
 620 status using their symbolic names: <code>temp</code> (default),
 621 <code>permanent</code>, or <code>seeother</code>.</p>
 622
 623 <p>
 624 You will almost always want to use [R] in conjunction with [L] (that is,
 625 use [R,L]) because on its own, the [R] flag prepends
 626 <code>http://thishost[:thisport]</code> to the URI, but then passes this
 627 on to the next rule in the ruleset, which can often result in 'Invalid
 628 URI in request' warnings.
 629 </p>
 630
 631 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 632 <div class="section">
 633 <h2><a name="flag_s" id="flag_s">S|skip</a></h2>
 634 <p>The [S] flag is used to skip rules that you don't want to run. The
 635 syntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies
 636 the number of rules to skip. This can be thought of as a <code>goto</code>
 637 statement in your rewrite ruleset. In the following example, we only want
 638 to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the
 639 requested URI doesn't correspond with an actual file.</p>
 640
 641 <pre class="prettyprint lang-config">
 642 # Is the request for a non-existent file?
 643 RewriteCond %{REQUEST_FILENAME} !-f
 644 RewriteCond %{REQUEST_FILENAME} !-d
 645 # If so, skip these two RewriteRules
 646 RewriteRule .? - [S=2]
 647
 648 RewriteRule (.*\.gif) images.php?$1
 649 RewriteRule (.*\.html) docs.php?$1
 650 </pre>
 651
 652
 653 <p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
 654 <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
 655 following it. Thus, if you want to make a <code>RewriteCond</code> apply
 656 to several <code>RewriteRule</code>s, one possible technique is to
 657 negate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. You can
 658 use this to make pseudo if-then-else constructs: The last rule of
 659 the then-clause becomes <code>skip=N</code>, where N is the
 660 number of rules in the else-clause:</p>
 661 <pre class="prettyprint lang-config">
 662 # Does the file exist?
 663 RewriteCond %{REQUEST_FILENAME} !-f
 664 RewriteCond %{REQUEST_FILENAME} !-d
 665 # Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
 666 RewriteRule .? - [S=3]
 667
 668 # IF the file exists, then:
 669     RewriteRule (.*\.gif) images.php?$1
 670     RewriteRule (.*\.html) docs.php?$1
 671     # Skip past the "else" stanza.
 672     RewriteRule .? - [S=1]
 673 # ELSE...
 674     RewriteRule (.*) 404.php?file=$1
 675 # END
 676 </pre>
 677
 678
 679 <p>It is probably easier to accomplish this kind of configuration using
 680 the <code class="directive">&lt;If&gt;</code>, <code class="directive">&lt;ElseIf&gt;</code>, and <code class="directive">&lt;Else&gt;</code> directives instead.</p>
 681
 682 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 683 <div class="section">
 684 <h2><a name="flag_t" id="flag_t">T|type</a></h2>
 685 <p>Sets the MIME type with which the resulting response will be
 686 sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
 687
 688 <p>For example, you might use the following technique to serve Perl
 689 source code as plain text, if requested in a particular way:</p>
 690
 691 <pre class="prettyprint lang-config">
 692 # Serve .pl files as plain text
 693 RewriteRule \.pl$ - [T=text/plain]
 694 </pre>
 695
 696
 697 <p>Or, perhaps, if you have a camera that produces jpeg images without
 698 file extensions, you could force those images to be served with the
 699 correct MIME type by virtue of their file names:</p>
 700
 701 <pre class="prettyprint lang-config">
 702 # Files with 'IMG' in the name are jpg images.
 703 RewriteRule IMG - [T=image/jpg]
 704 </pre>
 705
 706
 707 <p>Please note that this is a trivial example, and could be better done
 708 using <code class="directive"><a href="../mod/core.html#filesmatch">&lt;FilesMatch&gt;</a></code>
 709 instead. Always consider the alternate
 710 solutions to a problem before resorting to rewrite, which will
 711 invariably be a less efficient solution than the alternatives.</p>
 712
 713 <p>
 714 If used in per-directory context, use only <code>-</code> (dash)
 715 as the substitution <em>for the entire round of mod_rewrite processing</em>,
 716 otherwise the MIME-type set with this flag is lost due to an internal
 717 re-processing (including subsequent rounds of mod_rewrite processing).
 718 The <code>L</code> flag can be useful in this context to end the
 719 <em>current</em> round of mod_rewrite processing.</p>
 720
 721 </div></div>
 722 <div class="bottomlang">
 723 <p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English">&nbsp;en&nbsp;</a> |
 724 <a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français">&nbsp;fr&nbsp;</a></p>
 725 </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>This section is experimental!</strong><br />Comments placed here should not be expected
 726 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div>
 727 <script type="text/javascript"><!--//--><![CDATA[//><!--
 728 var disqus_shortname = 'httpd';
 729 var disqus_identifier = 'http://httpd.apache.org/docs/2.4/rewrite/flags.html.en';
 730 (function(w, d) {
 731     var disabled = true;
 732     if (w.location.hostname.toLowerCase() == "httpd.apache.org" && disabled !== true) {
 733         d.write('<div id="disqus_thread"><\/div>');
 734         var s = d.createElement('script');
 735         s.type = 'text/javascript';
 736         s.async = true;
 737         s.src = 'http' + '://' + disqus_shortname + '.disqus.com/embed.js';
 738         (d.getElementsByTagName('head')[0] || d.getElementsByTagName('body')[0]).appendChild(s);
 739     }
 740     else {
 741         d.write('<div id="disqus_thread">Comments are disabled for this page at the moment.<\/div>');
 742     }
 743 })(window, document);
 744 //--><!]]></script></div><div id="footer">
 745 <p class="apache">Copyright 2012 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>
 746 <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[//><!--
 747 if (typeof(prettyPrint) !== 'undefined') {
 748     prettyPrint();
 749 }
 750 //--><!]]></script>
 751 </body></html>