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