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