flags.xml revision 3d884698103201d426e73424aa6fa651df7af72f
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<!-- $LastChangedRevision$ -->
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon Licensed to the Apache Software Foundation (ASF) under one or more
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon contributor license agreements. See the NOTICE file distributed with
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon this work for additional information regarding copyright ownership.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon The ASF licenses this file to You under the Apache License, Version 2.0
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon (the "License"); you may not use this file except in compliance with
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon the License. You may obtain a copy of the License at
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon Unless required by applicable law or agreed to in writing, software
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon distributed under the License is distributed on an "AS IS" BASIS,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon See the License for the specific language governing permissions and
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon limitations under the License.
633fc3a6eed35d918db16925b7048d7a2e28064aSebastien Roy<parentdocument href="./">Rewrite</parentdocument>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This document discusses the flags which are available to the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive module="mod_rewrite">RewriteRule</directive> directive,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonproviding detailed explanations and examples.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="access.html">Controlling access</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="proxy.html">Proxying</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="advanced.html">Advanced techniques</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="introduction"><title>Introduction</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>A <directive module="mod_rewrite">RewriteRule</directive> can have
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonits behavior modified by one or more flags. Flags are included in
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsquare brackets at the end of the rule, and multiple flags are separated
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonby commas.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule pattern target [Flag1,Flag2,Flag3]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Each flag (with a few exceptions) has a short form, such as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>CO</code>, as well as a longer form, such as <code>cookie</code>.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonWhile it is most common to use
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe short form, it is recommended that you familiarize yourself with the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonlong form, so that you remember what each flag is supposed to do.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonSome flags take one or more arguments. Flags are not case sensitive.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Flags that alter metadata associated with the request (T=, H=, E=)
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonhave no affect in per-directory and htaccess context, when a substitution
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon(other than '-') is performed during the same round of rewrite processing.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Presented here are each of the available flags, along with an example
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonof how you might use them.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_b"><title>B (escape backreferences)</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> to escape non-alphanumeric
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncharacters before applying the transformation.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In 2.4.10 and later, you can limit the escaping to specific characters
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonin backreferences by listing them: <code>[B=#?;]</code> </p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p><code>mod_rewrite</code> has to unescape URLs before mapping them,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonso backreferences are unescaped at the time they are applied.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonUsing the B flag, non-alphanumeric characters in backreferences
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwill be escaped. For example, consider the rule:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule ^search/(.*)$ /search.php?term=$1</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Given a search term of 'x & y/z', a browser will encode it as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon'x%20%26%20y%2Fz', making the request 'search/x%20%26%20y%2Fz'. Without the B
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonflag, this rewrite rule will map to 'search.php?term=x & y/z', which
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonisn't a valid URL, and so would be encoded as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>search.php?term=x%20&y%2Fz=</code>, which is not what was intended.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>With the B flag set on this same rule, the parameters are re-encoded
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonbefore being passed on to the output URL, resulting in a correct mapping to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>/search.php?term=x%20%26%20y%2Fz</code>.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Note that you may also need to set <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="core">AllowEncodedSlashes</directive> to <code>On</code> to get this
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonparticular example to work, as httpd does not allow encoded slashes in URLs, and
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonreturns a 404 if it sees one.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This escaping is particularly necessary in a proxy situation,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwhen the backend may break if presented with an unescaped URL.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>An alternative to this flag is using a <directive module="mod_rewrite"
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon>RewriteCond</directive> to capture against %{THE_REQUEST} which will capture
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonstrings in the encoded form.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_bnp"><title>BNP|backrefnoplus (don't escape space to +)</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> to escape the space character
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonin a backreference to %20 rather than '+'. Useful when the backreference
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwill be used in the path component rather than the query string.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The [C] or [chain] flag indicates that the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> is chained to the next
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrule. That is, if the rule matches, then it is processed as usual and
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncontrol moves on to the next rule. However, if it does not match, then
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe next rule, and any other rules that are chained together, are
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The [CO], or [cookie] flag, allows you to set a cookie when a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonparticular <directive module="mod_rewrite">RewriteRule</directive>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmatches. The argument consists of three required fields and four optional
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The full syntax for the flag, including all attributes, is as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon[CO=NAME:VALUE:DOMAIN:lifetime:path:secure:httponly]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>You must declare a name, a value, and a domain for the cookie to be set.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>The domain for which you want the cookie to be valid. This may be a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonhostname, such as <code>www.example.com</code>, or it may be a domain,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsuch as <code>.example.com</code>. It must be at least two parts
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonseparated by a dot. That is, it may not be merely <code>.com</code> or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>.net</code>. Cookies of that kind are forbidden by the cookie
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsecurity model.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>You may optionally also set the following values:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>The time for which the cookie will persist, in minutes.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>A value of 0 indicates that the cookie will persist only for the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncurrent browser session. This is the default value if none is
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonspecified.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>The path, on the current website, for which the cookie is valid,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsuch as <code>/customers/</code> or <code>/files/download/</code>.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>By default, this is set to <code>/</code> - that is, the entire
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe cookie will only be permitted to be translated via secure (https)
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonconnections.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<dd>If set to <code>HttpOnly</code>, <code>true</code>, or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwhich means that the cookie is inaccessible to JavaScript code on
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonbrowsers that support this feature.</dd>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteEngine On
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule ^/index\.html - [CO=frontdoor:yes:.example.com:1440:/]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In the example give, the rule doesn't rewrite the request.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe "-" rewrite target tells mod_rewrite to pass the request
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthrough unchanged. Instead, it sets a cookie
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncalled 'frontdoor' to a value of 'yes'. The cookie is valid for any host
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonin the <code>.example.com</code> domain. It is set to expire in 1440
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonminutes (24 hours) and is returned for all URIs.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_dpi"><title>DPI|discardpath</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poondiscarded.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This flag is available in version 2.2.12 and later.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In per-directory context, the URI each <directive>RewriteRule</directive>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncompares against is the concatenation of the current values of the URI
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonand PATH_INFO.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The current URI can be the initial URI as requested by the client, the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonresult of a previous round of mod_rewrite processing, or the result of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poona prior rule in the current round of mod_rewrite processing.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In contrast, the PATH_INFO that is appended to the URI before each
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrule reflects only the value of PATH_INFO before this round of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmod_rewrite processing. As a consequence, if large portions
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonof the URI are matched and copied into a substitution in multiple
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive>RewriteRule</directive> directives, without regard for
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwhich parts of the URI came from the current PATH_INFO, the final
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonURI may have multiple copies of PATH_INFO appended to it.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Use this flag on any substitution where the PATH_INFO that resulted
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfrom the previous mapping of this request to the filesystem is not of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooninterest. This flag permanently forgets the PATH_INFO established
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonbefore this round of mod_rewrite processing began. PATH_INFO will
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonnot be recalculated until the current round of mod_rewrite processing
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncompletes. Subsequent rules during this round of processing will see
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poononly the direct result of substitutions, without any PATH_INFO
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>With the [E], or [env] flag, you can set the value of an environment
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonvariable. Note that some environment variables may be set after the rule
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonis run, thus unsetting what you have set. See <a href="/env.html">the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonEnvironment Variables document</a> for more details on how Environment
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonvariables work.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p><code>VAL</code> may contain backreferences (<code>$N</code> or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>you can set the environment variable named <code>VAR</code> to an
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonempty value.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>allows to unset a previously set environment variable named
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Environment variables can then be used in a variety of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncontexts, including CGI programs, other RewriteRule directives, or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonCustomLog directives.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The following example sets an environment variable called 'image' to a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonvalue of '1' if the requested URI is an image file. Then, that
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonenvironment variable is used to exclude those requests from the access
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule \.(png|gif|jpg)$ - [E=image:1]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Note that this same effect can be obtained using <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_setenvif">SetEnvIf</directive>. This technique is offered as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonan example, not as a recommendation.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Using the [END] flag terminates not only the current round of rewrite
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonprocessing (like [L]) but also prevents any subsequent rewrite
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonprocessing from occurring in per-directory (htaccess) context.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This does not apply to new requests resulting from external
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonredirects.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_f"><title>F|forbidden</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Using the [F] flag causes the server to return a 403 Forbidden status
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncode to the client. While the same behavior can be accomplished using
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe <directive module="mod_access_compat">Deny</directive> directive, this
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonallows more flexibility in assigning a Forbidden status.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The following rule will forbid <code>.exe</code> files from being
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poondownloaded from your server.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule \.exe - [F]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This example uses the "-" syntax for the rewrite target, which means
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthat the requested URI is not modified. There's no reason to rewrite to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonanother URI, if you're going to forbid the request.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>When using [F], an [L] is implied - that is, the response is returned
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonimmediately, and no further rules are evaluated.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The [G] flag forces the server to return a 410 Gone status with the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonresponse. This indicates that a resource used to be available, but is no
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonlonger available.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>As with the [F] flag, you will typically use the "-" syntax for the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrewrite target when using the [G] flag:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule oldproduct - [G,NC]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>When using [G], an [L] is implied - that is, the response is returned
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonimmediately, and no further rules are evaluated.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Forces the resulting request to be handled with the specified
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonhandler. For example, one might use this to force all files without a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfile extension to be parsed by the php handler:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule !\. - [H=application/x-httpd-php]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe regular expression above - <code>!\.</code> - will match any request
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthat does not contain the literal <code>.</code> character.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This can be also used to force the handler based on some conditions.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonFor example, the following snippet used in per-server context allows
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonif they are requested with the <code>.phps</code> extension:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmatch any request that starts with <code>/source/</code> followed by 1 or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonn characters followed by <code>.phps</code> literally. The backreference
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon$1 referrers to the captured match within parenthesis of the regular
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonexpression.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The [L] flag causes <module>mod_rewrite</module> to stop processing
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe rule set. In most contexts, this means that if the rule matches, no
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfurther rules will be processed. This corresponds to the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>last</code> command in Perl, or the <code>break</code> command in
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonC. Use this flag to indicate that the current rule should be applied
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonimmediately without considering further rules.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> in either
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive type="section" module="core">Directory</directive> sections,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonit is important to have some understanding of how the rules are
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonprocessed. The simplified form of this is that once the rules have been
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonprocessed, the rewritten request is handed back to the URL parsing
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonengine to do what it may with it. It is possible that as the rewritten
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrequest is handled, the <code>.htaccess</code> file or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive type="section" module="core">Directory</directive> section
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmay be encountered again, and thus the ruleset may be run again from the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonstart. Most commonly this will happen if one of the rules causes a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonredirect - either internal or external - causing the request process to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonstart over.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>It is therefore important, if you are using <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> directives in one of these
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncontexts, that you take explicit steps to avoid rules looping, and not
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncount solely on the [L] flag to terminate execution of a series of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrules, as shown below.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p> An alternative flag, [END], can be used to terminate not only the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncurrent round of rewrite processing but prevent any subsequent
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrewrite processing from occurring in per-directory (htaccess)
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncontext. This does not apply to new requests resulting from external
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonredirects.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The example given here will rewrite any request to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>index.php</code>, giving the original request as a query string
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonargument to <code>index.php</code>, however, the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteCond</directive> ensures that if the request
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonis already for <code>index.php</code>, the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> will be skipped.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond %{REQUEST_URI} !=/index.php
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule ^(.*) /index.php?req=$1 [L,PT]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe [N] flag causes the ruleset to start over again from the top, using
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe result of the ruleset so far as a starting point. Use
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwith extreme caution, as it may result in loop.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe [Next] flag could be used, for example, if you wished to replace a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncertain string or letter repeatedly in a request. The example shown here
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwill replace A with B everywhere in a request, and will continue doing
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonso until there are no more As to be replaced.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule (.*)A(.*) $1B$2 [N]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>You can think of this as a <code>while</code> loop: While this
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonpattern still matches (i.e., while the URI still contains an
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>A</code>), perform this substitution (i.e., replace the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In 2.5.0 and later, this module returns an error after 10,000 iterations to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonprotect against unintended looping. An alternative maximum number of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooniterations can be specified by adding to the N flag. </p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Be willing to replace 1 character in each pass of the loop
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule (.+)[><;]$ $1 [N=32000]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# ... or, give up if after 10 loops
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule (.+)[><;]$ $1 [N=10]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> to be matched in a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncase-insensitive manner. That is, it doesn't care whether letters appear
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonas upper-case or lower-case in the matched URI.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In the example below, any request for an image file will be proxied
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonto your dedicated image server. The match is case-insensitive, so that
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_ne"><title>NE|noescape</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>By default, special characters, such as <code>&</code> and
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>?</code>, for example, will be converted to their hexcode
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonequivalent. Using the [NE] flag prevents that from happening.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe above example will redirect <code>/anchor/xyz</code> to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonbeing converted to its hexcode equivalent, <code>%23</code>, which will
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthen result in a 404 Not Found error condition.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_ns"><title>NS|nosubreq</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Use of the [NS] flag prevents the rule from being used on
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsubrequests. For example, a page which is included using an SSI (Server
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonSide Include) is a subrequest, and you may want to avoid rewrites
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonhappening on those subrequests. Also, when <module>mod_dir</module>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poontries to find out information about possible directory default files
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon(such as <code>index.html</code> files), this is an internal
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsubrequest, and you often want to avoid rewrites on such subrequests.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonOn subrequests, it is not always useful, and can even cause errors, if
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe complete set of rules are applied. Use this flag to exclude
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonproblematic rules.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>To decide whether or not to use this rule: if you prefix URLs with
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonCGI-scripts, to force them to be processed by the CGI-script, it's
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonlikely that you will run into problems (or significant overhead)
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonon sub-requests. In these cases, use this flag.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonImages, javascript files, or css files, loaded as part of an HTML page,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonare not subrequests - the browser requests them as separate HTTP
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Use of the [P] flag causes the request to be handled by
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<module>mod_proxy</module>, and handled via a proxy request. For
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonexample, if you wanted all image requests to be handled by a back-end
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonimage server, you might do something like the following:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule /(.*)\.(jpg|gif|png)$ http://images.example.com/$1.$2 [P]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Use of the [P] flag implies [L] - that is, the request is immediately
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonpushed through the proxy, and any following rules will not be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonconsidered.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonYou must make sure that the substitution string is a valid URI
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon(typically starting with <code>http://</code><em>hostname</em>) which can be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonhandled by the <module>mod_proxy</module>. If not, you will get an
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonerror from the proxy module. Use this flag to achieve a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmore powerful implementation of the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_proxy">ProxyPass</directive> directive,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonto map remote content into the namespace of the local server.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Take care when constructing the target URL of the rule, considering
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe security impact from allowing the client influence over the set of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonURLs to which your server will act as a proxy. Ensure that the scheme
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonand hostname part of the URL is either fixed, or does not allow the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonclient undue influence.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Using this flag triggers the use of <module>mod_proxy</module>, without handling of persistent connections. This
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmeans the performance of your proxy will be better if you set it up with <directive module="mod_proxy">ProxyPass</directive> or
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive module="mod_proxy">ProxyPassMatch</directive></p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This is because this flag triggers the use of the default worker, which does not handle connection pooling.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Avoid using this flag and prefer those directives, whenever you can.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Note: <module>mod_proxy</module> must be enabled in order
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonto use this flag.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_pt"><title>PT|passthrough</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe target (or substitution string) in a RewriteRule is assumed to be a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfile path, by default. The use of the [PT] flag causes it to be treated
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonas a URI instead. That is to say, the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonuse of the [PT] flag causes the result of the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> to be passed back through
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonURL mapping, so that location-based mappings, such as <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_alias">Alias</directive>, <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_alias">Redirect</directive>, or <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_alias">ScriptAlias</directive>, for example, might have a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonchance to take effect.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonIf, for example, you have an
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive module="mod_alias">Alias</directive>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfor /icons, and have a <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> pointing there, you should
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonuse the [PT] flag to ensure that the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive module="mod_alias">Alias</directive> is evaluated.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule /pics/(.+)\.jpg$ /icons/$1.gif [PT]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonOmission of the [PT] flag in this case will cause the Alias to be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonignored, resulting in a 'File not found' error being returned.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The <code>PT</code> flag implies the <code>L</code> flag:
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonrewriting will be stopped in order to pass the request to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe next phase of processing.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Note that the <code>PT</code> flag is implied in per-directory
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncontexts such as
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive type="section" module="core">Directory</directive> sections
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonor in <code>.htaccess</code> files. The only way to circumvent that
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_qsa"><title>QSA|qsappend</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonWhen the replacement URI contains a query string, the default behavior
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonof <directive module="mod_rewrite">RewriteRule</directive> is to discard
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe existing query string, and replace it with the newly generated one.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonUsing the [QSA] flag causes the query strings to be combined.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<highlight language="config">RewriteRule /pages/(.+) /page.php?page=$1 [QSA]</highlight>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonflag, that same request will be mapped to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>/page.php?page=123</code> - that is, the existing query string
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwill be discarded.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<section id="flag_qsd"><title>QSD|qsdiscard</title>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonWhen the requested URI contains a query string, and the target URI does
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonnot, the default behavior of <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteRule</directive> is to copy that query
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonstring to the target URI. Using the [QSD] flag causes the query string
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonto be discarded.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This flag is available in version 2.4.0 and later.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonUsing [QSD] and [QSA] together will result in [QSD] taking precedence.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonIf the target URI has a query string, the default behavior will be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonobserved - that is, the original query string will be discarded and
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonreplaced with the query string in the <code>RewriteRule</code> target
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonUse of the [R] flag causes a HTTP redirect to be issued to the browser.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonIf a fully-qualified URL is specified (that is, including
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>http://servername/</code>) then a redirect will be issued to that
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonlocation. Otherwise, the current protocol, servername, and port number
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonwill be used to generate the URL sent with the redirect.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<em>Any</em> valid HTTP response status code may be specified,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonusing the syntax [R=305], with a 302 status code being used by
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poondefault if none is specified. The status code specified need not
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonnecessarily be a redirect (3xx) status code. However,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonif a status code is outside the redirect range (300-399) then the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsubstitution string is dropped entirely, and rewriting is stopped as if
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>In addition to response status codes, you may also specify redirect
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonstatus using their symbolic names: <code>temp</code> (default),
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>permanent</code>, or <code>seeother</code>.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonYou will almost always want to use [R] in conjunction with [L] (that is,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonuse [R,L]) because on its own, the [R] flag prepends
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>http://thishost[:thisport]</code> to the URI, but then passes this
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonon to the next rule in the ruleset, which can often result in 'Invalid
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonURI in request' warnings.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>The [S] flag is used to skip rules that you don't want to run. The
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsyntax of the skip flag is [S=<em>N</em>], where <em>N</em> signifies
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe number of rules to skip (provided the <directive module="mod_rewrite">
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule</directive> and any preceding <directive module="mod_rewrite">
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond</directive> directives match). This can be thought of as a
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<code>goto</code> statement in your rewrite ruleset. In the following
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonexample, we only want to run the <directive module="mod_rewrite">
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule</directive> if the requested URI doesn't correspond with an
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonactual file.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Is the request for a non-existent file?
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond %{REQUEST_FILENAME} !-f
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond %{REQUEST_FILENAME} !-d
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# If so, skip these two RewriteRules
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule .? - [S=2]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule (.*\.gif) images.php?$1
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule (.*\.html) docs.php?$1
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>This technique is useful because a <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_rewrite">RewriteCond</directive> only applies to the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<directive module="mod_rewrite">RewriteRule</directive> immediately
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfollowing it. Thus, if you want to make a <code>RewriteCond</code> apply
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonto several <code>RewriteRule</code>s, one possible technique is to
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonnegate those conditions and add a <code>RewriteRule</code> with a [Skip] flag. You can
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonuse this to make pseudo if-then-else constructs: The last rule of
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe then-clause becomes <code>skip=N</code>, where N is the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonnumber of rules in the else-clause:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Does the file exist?
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond %{REQUEST_FILENAME} !-f
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteCond %{REQUEST_FILENAME} !-d
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Create an if-then-else construct by skipping 3 lines if we meant to go to the "else" stanza.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonRewriteRule .? - [S=3]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# IF the file exists, then:
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon RewriteRule (.*\.gif) images.php?$1
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon RewriteRule (.*\.html) docs.php?$1
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon # Skip past the "else" stanza.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon RewriteRule .? - [S=1]
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon RewriteRule (.*) 404.php?file=$1
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>It is probably easier to accomplish this kind of configuration using
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonthe <directive type="section">If</directive>, <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poontype="section">ElseIf</directive>, and <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poontype="section">Else</directive> directives instead.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Sets the MIME type with which the resulting response will be
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsent. This has the same effect as the <directive
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonmodule="mod_mime">AddType</directive> directive.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>For example, you might use the following technique to serve Perl
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsource code as plain text, if requested in a particular way:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Serve .pl files as plain text
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Or, perhaps, if you have a camera that produces jpeg images without
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonfile extensions, you could force those images to be served with the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooncorrect MIME type by virtue of their file names:</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon# Files with 'IMG' in the name are jpg images.
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<p>Please note that this is a trivial example, and could be better done
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonusing <directive type="section" module="core">FilesMatch</directive>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooninstead. Always consider the alternate
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonsolutions to a problem before resorting to rewrite, which will
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Pooninvariably be a less efficient solution than the alternatives.</p>
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonIf used in per-directory context, use only <code>-</code> (dash)
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonas the substitution <em>for the entire round of mod_rewrite processing</em>,
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonotherwise the MIME-type set with this flag is lost due to an internal
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poonre-processing (including subsequent rounds of mod_rewrite processing).
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong PoonThe <code>L</code> flag can be useful in this context to end the
721fffe35d40e548a5a58dc53a2ec9c6762172d9Kacheong Poon<em>current</em> round of mod_rewrite processing.</p>