1 <?xml version='1.0' encoding='UTF-8' ?>
2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
4 <!-- $LastChangedRevision$ -->
7 Licensed to the Apache Software Foundation (ASF) under one or more
8 contributor license agreements. See the NOTICE file distributed with
9 this work for additional information regarding copyright ownership.
10 The ASF licenses this file to You under the Apache License, Version 2.0
11 (the "License"); you may not use this file except in compliance with
12 the License. You may obtain a copy of the License at
14 http://www.apache.org/licenses/LICENSE-2.0
16 Unless required by applicable law or agreed to in writing, software
17 distributed under the License is distributed on an "AS IS" BASIS,
18 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
19 See the License for the specific language governing permissions and
20 limitations under the License.
23 <manualpage metafile="flags.xml.meta">
24 <parentdocument href="./">Rewrite</parentdocument>
26 <title>RewriteRule Flags</title>
29 <p>This document discusses the flags which are available to the
30 <directive module="mod_rewrite">RewriteRule</directive> directive,
31 providing detailed explanations and examples.</p>
34 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
35 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
36 <seealso><a href="remapping.html">Redirection and remapping</a></seealso>
37 <seealso><a href="access.html">Controlling access</a></seealso>
38 <seealso><a href="vhosts.html">Virtual hosts</a></seealso>
39 <seealso><a href="proxy.html">Proxying</a></seealso>
40 <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
41 <seealso><a href="advanced.html">Advanced techniques</a></seealso>
42 <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
44 <section id="introduction"><title>Introduction</title>
45 <p>A <directive module="mod_rewrite">RewriteRule</directive> can have
46 its behavior modified by one or more flags. Flags are included in
47 square brackets at the end of the rule, and multiple flags are separated
49 <highlight language="config">
50 RewriteRule pattern target [Flag1,Flag2,Flag3]
53 <p>Each flag (with a few exceptions) has a short form, such as
54 <code>CO</code>, as well as a longer form, such as <code>cookie</code>.
55 While it is most common to use
56 the short form, it is recommended that you familiarize yourself with the
57 long form, so that you remember what each flag is supposed to do.
58 Some flags take one or more arguments. Flags are not case sensitive.</p>
60 <p>Flags that alter metadata associated with the request (T=, H=, E=)
61 have no affect in per-directory and htaccess context, when a substitution
62 (other than '-') is performed during the same round of rewrite processing.
65 <p>Presented here are each of the available flags, along with an example
66 of how you might use them.</p>
69 <section id="flag_b"><title>B (escape backreferences)</title>
70 <p>The [B] flag instructs <directive
71 module="mod_rewrite">RewriteRule</directive> to escape non-alphanumeric
72 characters before applying the transformation.</p>
73 <p>In 2.4.10 and later, you can limit the escaping to specific characters
74 in backreferences by listing them: <code>[B=#?;]</code>. Note: The space
75 character can be used in the list of characters to escape, but it cannot be
76 the last character in the list.</p>
78 <p><code>mod_rewrite</code> has to unescape URLs before mapping them,
79 so backreferences are unescaped at the time they are applied.
80 Using the B flag, non-alphanumeric characters in backreferences
81 will be escaped. For example, consider the rule:</p>
83 <highlight language="config">
84 RewriteRule "^search/(.*)$" "/search.php?term=$1"
87 <p>Given a search term of 'x & y/z', a browser will encode it as
88 'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B
89 flag, this rewrite rule will map to 'search.php?term=x & y/z', which
90 isn't a valid URL, and so would be encoded as
91 <code>search.php?term=x%20&y%2Fz=</code>, which is not what was intended.</p>
93 <p>With the B flag set on this same rule, the parameters are re-encoded
94 before being passed on to the output URL, resulting in a correct mapping to
95 <code>/search.php?term=x%20%26%20y%2Fz</code>.</p>
97 <highlight language="config">
98 RewriteRule "^search/(.*)$" "/search.php?term=$1" [B,PT]
101 <p>Note that you may also need to set <directive
102 module="core">AllowEncodedSlashes</directive> to <code>On</code> to get this
103 particular example to work, as httpd does not allow encoded slashes in URLs, and
104 returns a 404 if it sees one.</p>
106 <p>This escaping is particularly necessary in a proxy situation,
107 when the backend may break if presented with an unescaped URL.</p>
109 <p>An alternative to this flag is using a <directive module="mod_rewrite"
110 >RewriteCond</directive> to capture against %{THE_REQUEST} which will capture
111 strings in the encoded form.</p>
114 <section id="flag_bnp"><title>BNP|backrefnoplus (don't escape space to +)</title>
115 <p>The [BNP] flag instructs <directive
116 module="mod_rewrite">RewriteRule</directive> to escape the space character
117 in a backreference to %20 rather than '+'. Useful when the backreference
118 will be used in the path component rather than the query string.</p>
121 <section id="flag_c"><title>C|chain</title>
122 <p>The [C] or [chain] flag indicates that the <directive
123 module="mod_rewrite">RewriteRule</directive> is chained to the next
124 rule. That is, if the rule matches, then it is processed as usual and
125 control moves on to the next rule. However, if it does not match, then
126 the next rule, and any other rules that are chained together, are
131 <section id="flag_co"><title>CO|cookie</title>
132 <p>The [CO], or [cookie] flag, allows you to set a cookie when a
133 particular <directive module="mod_rewrite">RewriteRule</directive>
134 matches. The argument consists of three required fields and four optional
137 <p>The full syntax for the flag, including all attributes, is as
141 [CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]
144 <p>If a literal ':' character is needed in any of the cookie fields, an
145 alternate syntax is available. To opt-in to the alternate syntax, the cookie
146 "Name" should be preceded with a ';' character, and field separators should be
147 specified as ';'.</p>
150 [CO=;NAME;VALUE:MOREVALUE;DOMAIN;lifetime;path;secure;httponly]
153 <p>You must declare a name, a value, and a domain for the cookie to be set.</p>
157 <dd>The domain for which you want the cookie to be valid. This may be a
158 hostname, such as <code>www.example.com</code>, or it may be a domain,
159 such as <code>.example.com</code>. It must be at least two parts
160 separated by a dot. That is, it may not be merely <code>.com</code> or
161 <code>.net</code>. Cookies of that kind are forbidden by the cookie
165 <p>You may optionally also set the following values:</p>
169 <dd>The time for which the cookie will persist, in minutes.</dd>
170 <dd>A value of 0 indicates that the cookie will persist only for the
171 current browser session. This is the default value if none is
175 <dd>The path, on the current website, for which the cookie is valid,
176 such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
177 <dd>By default, this is set to <code>/</code> - that is, the entire
181 <dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
182 the cookie will only be permitted to be translated via secure (https)
186 <dd>If set to <code>HttpOnly</code>, <code>true</code>, or
187 <code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
188 which means that the cookie is inaccessible to JavaScript code on
189 browsers that support this feature.</dd>
192 <p>Consider this example:</p>
194 <highlight language="config">
196 RewriteRule "^/index\.html" "-" [CO=frontdoor:yes:.example.com:1440:/]
199 <p>In the example give, the rule doesn't rewrite the request.
200 The "-" rewrite target tells mod_rewrite to pass the request
201 through unchanged. Instead, it sets a cookie
202 called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
203 in the <code>.example.com</code> domain. It is set to expire in 1440
204 minutes (24 hours) and is returned for all URIs.</p>
208 <section id="flag_dpi"><title>DPI|discardpath</title>
209 <p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
211 <p>This flag is available in version 2.2.12 and later.</p>
212 <p>In per-directory context, the URI each <directive>RewriteRule</directive>
213 compares against is the concatenation of the current values of the URI
216 <p>The current URI can be the initial URI as requested by the client, the
217 result of a previous round of mod_rewrite processing, or the result of
218 a prior rule in the current round of mod_rewrite processing.</p>
220 <p>In contrast, the PATH_INFO that is appended to the URI before each
221 rule reflects only the value of PATH_INFO before this round of
222 mod_rewrite processing. As a consequence, if large portions
223 of the URI are matched and copied into a substitution in multiple
224 <directive>RewriteRule</directive> directives, without regard for
225 which parts of the URI came from the current PATH_INFO, the final
226 URI may have multiple copies of PATH_INFO appended to it.</p>
228 <p>Use this flag on any substitution where the PATH_INFO that resulted
229 from the previous mapping of this request to the filesystem is not of
230 interest. This flag permanently forgets the PATH_INFO established
231 before this round of mod_rewrite processing began. PATH_INFO will
232 not be recalculated until the current round of mod_rewrite processing
233 completes. Subsequent rules during this round of processing will see
234 only the direct result of substitutions, without any PATH_INFO
238 <section id="flag_e"><title>E|env</title>
239 <p>With the [E], or [env] flag, you can set the value of an environment
240 variable. Note that some environment variables may be set after the rule
241 is run, thus unsetting what you have set. See <a href="../env.html">the
242 Environment Variables document</a> for more details on how Environment
245 <p>The full syntax for this flag is:</p>
247 <highlight language="config">
252 <p><code>VAL</code> may contain backreferences (<code>$N</code> or
253 <code>%N</code>) which are expanded.</p>
255 <p>Using the short form</p>
261 <p>you can set the environment variable named <code>VAR</code> to an
270 <p>allows to unset a previously set environment variable named
271 <code>VAR</code>.</p>
273 <p>Environment variables can then be used in a variety of
274 contexts, including CGI programs, other RewriteRule directives, or
275 CustomLog directives.</p>
277 <p>The following example sets an environment variable called 'image' to a
278 value of '1' if the requested URI is an image file. Then, that
279 environment variable is used to exclude those requests from the access
282 <highlight language="config">
283 RewriteRule "\.(png|gif|jpg)$" "-" [E=image:1]
284 CustomLog "logs/access_log" combined env=!image
287 <p>Note that this same effect can be obtained using <directive
288 module="mod_setenvif">SetEnvIf</directive>. This technique is offered as
289 an example, not as a recommendation.</p>
292 <section id="flag_end"><title>END</title>
293 <p>Using the [END] flag terminates not only the current round of rewrite
294 processing (like [L]) but also prevents any subsequent rewrite
295 processing from occurring in per-directory (htaccess) context.</p>
297 <p>This does not apply to new requests resulting from external
301 <section id="flag_f"><title>F|forbidden</title>
302 <p>Using the [F] flag causes the server to return a 403 Forbidden status
303 code to the client. While the same behavior can be accomplished using
304 the <directive module="mod_access_compat">Deny</directive> directive, this
305 allows more flexibility in assigning a Forbidden status.</p>
307 <p>The following rule will forbid <code>.exe</code> files from being
308 downloaded from your server.</p>
310 <highlight language="config">
311 RewriteRule "\.exe" "-" [F]
314 <p>This example uses the "-" syntax for the rewrite target, which means
315 that the requested URI is not modified. There's no reason to rewrite to
316 another URI, if you're going to forbid the request.</p>
318 <p>When using [F], an [L] is implied - that is, the response is returned
319 immediately, and no further rules are evaluated.</p>
323 <section id="flag_g"><title>G|gone</title>
324 <p>The [G] flag forces the server to return a 410 Gone status with the
325 response. This indicates that a resource used to be available, but is no
326 longer available.</p>
328 <p>As with the [F] flag, you will typically use the "-" syntax for the
329 rewrite target when using the [G] flag:</p>
331 <highlight language="config">
332 RewriteRule "oldproduct" "-" [G,NC]
335 <p>When using [G], an [L] is implied - that is, the response is returned
336 immediately, and no further rules are evaluated.</p>
340 <section id="flag_h"><title>H|handler</title>
341 <p>Forces the resulting request to be handled with the specified
342 handler. For example, one might use this to force all files without a
343 file extension to be parsed by the php handler:</p>
345 <highlight language="config">
346 RewriteRule "!\." "-" [H=application/x-httpd-php]
350 The regular expression above - <code>!\.</code> - will match any request
351 that does not contain the literal <code>.</code> character.
354 <p>This can be also used to force the handler based on some conditions.
355 For example, the following snippet used in per-server context allows
356 <code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
357 if they are requested with the <code>.phps</code> extension:</p>
359 <highlight language="config">
360 RewriteRule "^(/source/.+\.php)s$" "$1" [H=application/x-httpd-php-source]
363 <p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
364 match any request that starts with <code>/source/</code> followed by 1 or
365 n characters followed by <code>.phps</code> literally. The backreference
366 $1 referrers to the captured match within parenthesis of the regular
370 <section id="flag_l"><title>L|last</title>
371 <p>The [L] flag causes <module>mod_rewrite</module> to stop processing
372 the rule set. In most contexts, this means that if the rule matches, no
373 further rules will be processed. This corresponds to the
374 <code>last</code> command in Perl, or the <code>break</code> command in
375 C. Use this flag to indicate that the current rule should be applied
376 immediately without considering further rules.</p>
378 <p>If you are using <directive
379 module="mod_rewrite">RewriteRule</directive> in either
380 <code>.htaccess</code> files or in
381 <directive type="section" module="core">Directory</directive> sections,
382 it is important to have some understanding of how the rules are
383 processed. The simplified form of this is that once the rules have been
384 processed, the rewritten request is handed back to the URL parsing
385 engine to do what it may with it. It is possible that as the rewritten
386 request is handled, the <code>.htaccess</code> file or
387 <directive type="section" module="core">Directory</directive> section
388 may be encountered again, and thus the ruleset may be run again from the
389 start. Most commonly this will happen if one of the rules causes a
390 redirect - either internal or external - causing the request process to
393 <p>It is therefore important, if you are using <directive
394 module="mod_rewrite">RewriteRule</directive> directives in one of these
395 contexts, that you take explicit steps to avoid rules looping, and not
396 count solely on the [L] flag to terminate execution of a series of
397 rules, as shown below.</p>
399 <p> An alternative flag, [END], can be used to terminate not only the
400 current round of rewrite processing but prevent any subsequent
401 rewrite processing from occurring in per-directory (htaccess)
402 context. This does not apply to new requests resulting from external
405 <p>The example given here will rewrite any request to
406 <code>index.php</code>, giving the original request as a query string
407 argument to <code>index.php</code>, however, the <directive
408 module="mod_rewrite">RewriteCond</directive> ensures that if the request
409 is already for <code>index.php</code>, the <directive
410 module="mod_rewrite">RewriteRule</directive> will be skipped.</p>
412 <highlight language="config">
414 RewriteCond "%{REQUEST_URI}" !=/index.php
415 RewriteRule "^(.*)" "/index.php?req=$1" [L,PT]
419 <section id="flag_n"><title>N|next</title>
421 The [N] flag causes the ruleset to start over again from the top, using
422 the result of the ruleset so far as a starting point. Use
423 with extreme caution, as it may result in loop.
426 The [Next] flag could be used, for example, if you wished to replace a
427 certain string or letter repeatedly in a request. The example shown here
428 will replace A with B everywhere in a request, and will continue doing
429 so until there are no more As to be replaced.
431 <highlight language="config">
432 RewriteRule "(.*)A(.*)" "$1B$2" [N]
434 <p>You can think of this as a <code>while</code> loop: While this
435 pattern still matches (i.e., while the URI still contains an
436 <code>A</code>), perform this substitution (i.e., replace the
437 <code>A</code> with a <code>B</code>).</p>
439 <p>In 2.5.0 and later, this module returns an error after 10,000 iterations to
440 protect against unintended looping. An alternative maximum number of
441 iterations can be specified by adding to the N flag. </p>
442 <highlight language="config">
443 # Be willing to replace 1 character in each pass of the loop
444 RewriteRule "(.+)[><;]$" "$1" [N=32000]
445 # ... or, give up if after 10 loops
446 RewriteRule "(.+)[><;]$" "$1" [N=10]
451 <section id="flag_nc"><title>NC|nocase</title>
452 <p>Use of the [NC] flag causes the <directive
453 module="mod_rewrite">RewriteRule</directive> to be matched in a
454 case-insensitive manner. That is, it doesn't care whether letters appear
455 as upper-case or lower-case in the matched URI.</p>
457 <p>In the example below, any request for an image file will be proxied
458 to your dedicated image server. The match is case-insensitive, so that
459 <code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
462 <highlight language="config">
463 RewriteRule "(.*\.(jpg|gif|png))$" "http://images.example.com$1" [P,NC]
467 <section id="flag_ne"><title>NE|noescape</title>
468 <p>By default, special characters, such as <code>&</code> and
469 <code>?</code>, for example, will be converted to their hexcode
470 equivalent. Using the [NE] flag prevents that from happening.
473 <highlight language="config">
474 RewriteRule "^/anchor/(.+)" "/bigpage.html#$1" [NE,R]
478 The above example will redirect <code>/anchor/xyz</code> to
479 <code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
480 being converted to its hexcode equivalent, <code>%23</code>, which will
481 then result in a 404 Not Found error condition.
486 <section id="flag_ns"><title>NS|nosubreq</title>
487 <p>Use of the [NS] flag prevents the rule from being used on
488 subrequests. For example, a page which is included using an SSI (Server
489 Side Include) is a subrequest, and you may want to avoid rewrites
490 happening on those subrequests. Also, when <module>mod_dir</module>
491 tries to find out information about possible directory default files
492 (such as <code>index.html</code> files), this is an internal
493 subrequest, and you often want to avoid rewrites on such subrequests.
494 On subrequests, it is not always useful, and can even cause errors, if
495 the complete set of rules are applied. Use this flag to exclude
496 problematic rules.</p>
498 <p>To decide whether or not to use this rule: if you prefix URLs with
499 CGI-scripts, to force them to be processed by the CGI-script, it's
500 likely that you will run into problems (or significant overhead)
501 on sub-requests. In these cases, use this flag.</p>
504 Images, javascript files, or css files, loaded as part of an HTML page,
505 are not subrequests - the browser requests them as separate HTTP
510 <section id="flag_p"><title>P|proxy</title>
511 <p>Use of the [P] flag causes the request to be handled by
512 <module>mod_proxy</module>, and handled via a proxy request. For
513 example, if you wanted all image requests to be handled by a back-end
514 image server, you might do something like the following:</p>
516 <highlight language="config">
517 RewriteRule "/(.*)\.(jpg|gif|png)$" "http://images.example.com/$1.$2" [P]
520 <p>Use of the [P] flag implies [L] - that is, the request is immediately
521 pushed through the proxy, and any following rules will not be
525 You must make sure that the substitution string is a valid URI
526 (typically starting with <code>http://</code><em>hostname</em>) which can be
527 handled by the <module>mod_proxy</module>. If not, you will get an
528 error from the proxy module. Use this flag to achieve a
529 more powerful implementation of the <directive
530 module="mod_proxy">ProxyPass</directive> directive,
531 to map remote content into the namespace of the local server.</p>
533 <note type="warning">
534 <title>Security Warning</title>
535 <p>Take care when constructing the target URL of the rule, considering
536 the security impact from allowing the client influence over the set of
537 URLs to which your server will act as a proxy. Ensure that the scheme
538 and hostname part of the URL is either fixed, or does not allow the
539 client undue influence.</p>
542 <note type="warning">
543 <title>Performance warning</title>
544 <p>Using this flag triggers the use of <module>mod_proxy</module>, without handling of persistent connections. This
545 means the performance of your proxy will be better if you set it up with <directive module="mod_proxy">ProxyPass</directive> or
546 <directive module="mod_proxy">ProxyPassMatch</directive></p>
547 <p>This is because this flag triggers the use of the default worker, which does not handle connection pooling.</p>
548 <p>Avoid using this flag and prefer those directives, whenever you can.</p>
551 <p>Note: <module>mod_proxy</module> must be enabled in order
552 to use this flag.</p>
556 <section id="flag_pt"><title>PT|passthrough</title>
559 The target (or substitution string) in a RewriteRule is assumed to be a
560 file path, by default. The use of the [PT] flag causes it to be treated
561 as a URI instead. That is to say, the
562 use of the [PT] flag causes the result of the <directive
563 module="mod_rewrite">RewriteRule</directive> to be passed back through
564 URL mapping, so that location-based mappings, such as <directive
565 module="mod_alias">Alias</directive>, <directive
566 module="mod_alias">Redirect</directive>, or <directive
567 module="mod_alias">ScriptAlias</directive>, for example, might have a
568 chance to take effect.
572 If, for example, you have an
573 <directive module="mod_alias">Alias</directive>
574 for /icons, and have a <directive
575 module="mod_rewrite">RewriteRule</directive> pointing there, you should
576 use the [PT] flag to ensure that the
577 <directive module="mod_alias">Alias</directive> is evaluated.
580 <highlight language="config">
581 Alias "/icons" "/usr/local/apache/icons"
582 RewriteRule "/pics/(.+)\.jpg$" "/icons/$1.gif" [PT]
586 Omission of the [PT] flag in this case will cause the Alias to be
587 ignored, resulting in a 'File not found' error being returned.
590 <p>The <code>PT</code> flag implies the <code>L</code> flag:
591 rewriting will be stopped in order to pass the request to
592 the next phase of processing.</p>
594 <p>Note that the <code>PT</code> flag is implied in per-directory
596 <directive type="section" module="core">Directory</directive> sections
597 or in <code>.htaccess</code> files. The only way to circumvent that
598 is to rewrite to <code>-</code>.</p>
602 <section id="flag_qsa"><title>QSA|qsappend</title>
604 When the replacement URI contains a query string, the default behavior
605 of <directive module="mod_rewrite">RewriteRule</directive> is to discard
606 the existing query string, and replace it with the newly generated one.
607 Using the [QSA] flag causes the query strings to be combined.
610 <p>Consider the following rule:</p>
612 <highlight language="config">
613 RewriteRule "/pages/(.+)" "/page.php?page=$1" [QSA]
616 <p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
617 mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
618 flag, that same request will be mapped to
619 <code>/page.php?page=123</code> - that is, the existing query string
624 <section id="flag_qsd"><title>QSD|qsdiscard</title>
626 When the requested URI contains a query string, and the target URI does
627 not, the default behavior of <directive
628 module="mod_rewrite">RewriteRule</directive> is to copy that query
629 string to the target URI. Using the [QSD] flag causes the query string
633 <p>This flag is available in version 2.4.0 and later.</p>
636 Using [QSD] and [QSA] together will result in [QSD] taking precedence.
640 If the target URI has a query string, the default behavior will be
641 observed - that is, the original query string will be discarded and
642 replaced with the query string in the <code>RewriteRule</code> target
648 <section id="flag_qsl"><title>QSL|qslast</title>
650 By default, the first (left-most) question mark in the substitution
651 delimits the path from the query string. Using the [QSL] flag instructs
652 <directive module="mod_rewrite">RewriteRule</directive> to instead split
653 the two components using the last (right-most) question mark. </p>
656 This is useful when mapping to files that have literal question marks in
657 their filename. If no query string is used in the substitution,
658 a question mark can be appended to it in combination with this flag. </p>
660 <p> This flag is available in version 2.4.19 and later.</p>
665 <section id="flag_r"><title>R|redirect</title>
667 Use of the [R] flag causes a HTTP redirect to be issued to the browser.
668 If a fully-qualified URL is specified (that is, including
669 <code>http://servername/</code>) then a redirect will be issued to that
670 location. Otherwise, the current protocol, servername, and port number
671 will be used to generate the URL sent with the redirect.
675 <em>Any</em> valid HTTP response status code may be specified,
676 using the syntax [R=305], with a 302 status code being used by
677 default if none is specified. The status code specified need not
678 necessarily be a redirect (3xx) status code. However,
679 if a status code is outside the redirect range (300-399) then the
680 substitution string is dropped entirely, and rewriting is stopped as if
681 the <code>L</code> were used.</p>
683 <p>In addition to response status codes, you may also specify redirect
684 status using their symbolic names: <code>temp</code> (default),
685 <code>permanent</code>, or <code>seeother</code>.</p>
688 You will almost always want to use [R] in conjunction with [L] (that is,
689 use [R,L]) because on its own, the [R] flag prepends
690 <code>http://thishost[:thisport]</code> to the URI, but then passes this
691 on to the next rule in the ruleset, which can often result in 'Invalid
692 URI in request' warnings.
697 <section id="flag_s"><title>S|skip</title>
698 <p>The [S] flag is used to skip rules that you don't want to run. The
699 syntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies
700 the number of rules to skip (provided the <directive module="mod_rewrite">
701 RewriteRule</directive> and any preceding <directive module="mod_rewrite">
702 RewriteCond</directive> directives match). This can be thought of as a
703 <code>goto</code> statement in your rewrite ruleset. In the following
704 example, we only want to run the <directive module="mod_rewrite">
705 RewriteRule</directive> if the requested URI doesn't correspond with an
708 <highlight language="config">
709 # Is the request for a non-existent file?
710 RewriteCond "%{REQUEST_FILENAME}" !-f
711 RewriteCond "%{REQUEST_FILENAME}" !-d
712 # If so, skip these two RewriteRules
713 RewriteRule ".?" "-" [S=2]
715 RewriteRule "(.*\.gif)" "images.php?$1"
716 RewriteRule "(.*\.html)" "docs.php?$1"
719 <p>This technique is useful because a <directive
720 module="mod_rewrite">RewriteCond</directive> only applies to the
721 <directive module="mod_rewrite">RewriteRule</directive> immediately
722 following it. Thus, if you want to make a <code>RewriteCond</code> apply
723 to several <code>RewriteRule</code>s, one possible technique is to
724 negate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. You can
725 use this to make pseudo if-then-else constructs: The last rule of
726 the then-clause becomes <code>skip=N</code>, where N is the
727 number of rules in the else-clause:</p>
728 <highlight language="config">
729 # Does the file exist?
730 RewriteCond "%{REQUEST_FILENAME}" !-f
731 RewriteCond "%{REQUEST_FILENAME}" !-d
732 # Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
733 RewriteRule ".?" "-" [S=3]
735 # IF the file exists, then:
736 RewriteRule "(.*\.gif)" "images.php?$1"
737 RewriteRule "(.*\.html)" "docs.php?$1"
738 # Skip past the "else" stanza.
739 RewriteRule ".?" "-" [S=1]
741 RewriteRule "(.*)" "404.php?file=$1"
745 <p>It is probably easier to accomplish this kind of configuration using
746 the <directive type="section">If</directive>, <directive
747 type="section">ElseIf</directive>, and <directive
748 type="section">Else</directive> directives instead.</p>
752 <section id="flag_t"><title>T|type</title>
753 <p>Sets the MIME type with which the resulting response will be
754 sent. This has the same effect as the <directive
755 module="mod_mime">AddType</directive> directive.</p>
757 <p>For example, you might use the following technique to serve Perl
758 source code as plain text, if requested in a particular way:</p>
760 <highlight language="config">
761 # Serve .pl files as plain text
762 RewriteRule "\.pl$" "-" [T=text/plain]
765 <p>Or, perhaps, if you have a camera that produces jpeg images without
766 file extensions, you could force those images to be served with the
767 correct MIME type by virtue of their file names:</p>
769 <highlight language="config">
770 # Files with 'IMG' in the name are jpg images.
771 RewriteRule "IMG" "-" [T=image/jpg]
774 <p>Please note that this is a trivial example, and could be better done
775 using <directive type="section" module="core">FilesMatch</directive>
776 instead. Always consider the alternate
777 solutions to a problem before resorting to rewrite, which will
778 invariably be a less efficient solution than the alternatives.</p>
781 If used in per-directory context, use only <code>-</code> (dash)
782 as the substitution <em>for the entire round of mod_rewrite processing</em>,
783 otherwise the MIME-type set with this flag is lost due to an internal
784 re-processing (including subsequent rounds of mod_rewrite processing).
785 The <code>L</code> flag can be useful in this context to end the
786 <em>current</em> round of mod_rewrite processing.</p>