mirror of
https://github.com/apache/httpd.git
synced 2025-09-08 11:12:11 +03:00
585e0c73cc
git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@934398 13f79535-47bb-0310-9956-ffa450edef68
639 lines
31 KiB
XML
639 lines
31 KiB
XML
<?xml version="1.0" encoding="ISO-8859-1"?>
|
|
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
This file is generated from xml source: DO NOT EDIT
|
|
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
|
|
-->
|
|
<title>RewriteRule Flags - Apache HTTP Server</title>
|
|
<link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
|
|
<link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
|
|
<link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
|
|
<link href="../images/favicon.ico" rel="shortcut icon" /></head>
|
|
<body id="manual-page"><div id="page-header">
|
|
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
|
|
<p class="apache">Apache HTTP Server Version 2.3</p>
|
|
<img alt="" src="../images/feather.gif" /></div>
|
|
<div class="up"><a href="./"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
|
|
<div id="path">
|
|
<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.3</a> > <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>RewriteRule Flags</h1>
|
|
<div class="toplang">
|
|
<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> |
|
|
<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
|
|
</div>
|
|
|
|
<p>This document discusses the flags which are available to the
|
|
<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
|
|
providing detailed explanations and examples.</p>
|
|
</div>
|
|
<div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#introduction">Introduction</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_b">B (escape backreferences)</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_c">C|chain</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_co">CO|cookie</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_dpi">DPI|discardpathinfo</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_e">E|env</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_f">F|forbidden</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_g">G|gone</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_h">H|handler</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_l">L|last</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_n">N|next</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_nc">NC|nocase</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_ne">NE|noescape</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_ns">NS|nosubreq</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_p">P|proxy</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_pt">PT|passthrough</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsa">QSA|qsappend</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_qsd">QSD|qsdiscard</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_r">R|redirect</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_s">S|skip</a></li>
|
|
<li><img alt="" src="../images/down.gif" /> <a href="#flag_t">T|type</a></li>
|
|
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="tech.html">Technical details</a></li></ul></div>
|
|
<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="introduction" id="introduction">Introduction</a></h2>
|
|
<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> can have
|
|
its behavior modified by one or more flags. Flags are included in
|
|
square brackets at the end of the rule, and multiple flags are separated
|
|
by commas.</p>
|
|
<div class="example"><p><code>
|
|
RewriteRule pattern target [Flag1,Flag2,Flag3]
|
|
</code></p></div>
|
|
|
|
<p>The flags all have a short form, such as <code>CO</code>, as well as
|
|
a longer form, such as <code>cookie</code>. Some flags take one or more
|
|
arguments. Flags are not case sensitive.</p>
|
|
|
|
<p>Each flag (with a few exceptions)
|
|
has a long and short form. While it is most common to use
|
|
the short form, it is recommended that you familiarize yourself with the
|
|
long form, so that you remember what each flag is supposed to do.</p>
|
|
|
|
<p>Presented here are each of the available flags, along with an example
|
|
of how you might use them.</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_b" id="flag_b">B (escape backreferences)</a></h2>
|
|
<p>The [B] flag instructs <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to escape non-alphanumeric
|
|
characters before applying the transformation.
|
|
</p>
|
|
|
|
<p><code>mod_rewrite</code> has to unescape URLs before mapping them,
|
|
so backreferences will be unescaped at the time they are applied.
|
|
Using the B flag, non-alphanumeric characters in backreferences
|
|
will be escaped. For example, consider the rule:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule ^(/.*)$ /index.php?show=$1
|
|
</code></p></div>
|
|
|
|
<p>This will map <code>/C++</code> to
|
|
<code>/index.php?show=/C++</code>. But it will also map
|
|
<code>/C%2b%2b</code> to <code>/index.php?show=/C++</code>, because
|
|
the <code>%2b</code> has been unescaped. With the B flag, it will
|
|
instead map to <code>/index.php?show=/C%2b%2b</code>.</p>
|
|
|
|
<p>This escaping is particularly necessary in a proxy situation,
|
|
when the backend may break if presented with an unescaped URL.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_c" id="flag_c">C|chain</a></h2>
|
|
<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
|
|
rule. That is, if the rule matches, then it is processed as usual and
|
|
control moves on to the next rule. However, if it does not match, then
|
|
the next rule, and any other rules that are chained together, will be
|
|
skipped.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_co" id="flag_co">CO|cookie</a></h2>
|
|
<p>The [CO], or [cookie] flag, allows you to set a cookie when a
|
|
particular <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
|
|
matches. The argument consists of three required fields and five optional
|
|
fields.</p>
|
|
|
|
<p>The full syntax for the flag, including all attributes, is as
|
|
follows:</p>
|
|
|
|
<div class="example"><p><code>
|
|
[CO=NAME:VALUE:domain:lifetime:path:secure:httponly]
|
|
</code></p></div>
|
|
|
|
<p>You must declare a name and value for the cookie to be set.</p>
|
|
|
|
<p>You may optionally also set the following values:</p>
|
|
|
|
<dl>
|
|
<dt>Domain</dt>
|
|
<dd>The domain for which you want the cookie to be valid. This may be a
|
|
hostname, such as <code>www.example.com</code>, or it may be a domain,
|
|
such as <code>.example.com</code>. It must be at least two parts
|
|
separated by a dot. That is, it may not be merely <code>.com</code> or
|
|
<code>.net</code>. Cookies of that kind are forbidden by the cookie
|
|
security model.</dd>
|
|
<dd>The default value for the domain is the current domain.</dd>
|
|
|
|
<dt>Lifetime</dt>
|
|
<dd>The time for which the cookie will persist, in minutes.</dd>
|
|
<dd>A value of 0 indicates that the cookie will persist only for the
|
|
current browser session. This is the default value if none is
|
|
specified.</dd>
|
|
|
|
<dt>Path</dt>
|
|
<dd>The path, on the current website, for which the cookie is valid,
|
|
such as <code>/customers/</code> or <code>/files/download/</code>.</dd>
|
|
<dd>By default, this is set to <code>/</code> - that is, the entire
|
|
website.</dd>
|
|
|
|
<dt>Secure</dt>
|
|
<dd>If set to <code>secure</code>, <code>true</code>, or <code>1</code>,
|
|
the cookie will only be permitted to be translated via secure (https)
|
|
connections.</dd>
|
|
|
|
<dt>httponly</dt>
|
|
<dd>If set to <code>HttpOnly</code>, <code>true</code>, or
|
|
<code>1</code>, the cookie will have the <code>HttpOnly</code> flag set,
|
|
which means that the cookie will be inaccessible to JavaScript code on
|
|
browsers that support this feature.</dd>
|
|
</dl>
|
|
|
|
<p>Several examples are offered here:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteEngine On<br />
|
|
RewriteRule ^/index\.html - [CO=frontdoor:yes:.apache.org:1440:/]
|
|
</code></p></div>
|
|
|
|
<p>In the example give, the rule doesn't rewrite the request.
|
|
The "-" rewrite target tells mod_rewrite to pass the request
|
|
through unchanged. Instead, it sets a cookie
|
|
called 'frontdoor' to a value of 'yes'. The cookie is valid for any host
|
|
in the <code>.apache.org</code> domain. It will be set to expire in 1440
|
|
minutes (24 hours) and will be returned for all URIs.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_dpi" id="flag_dpi">DPI|discardpathinfo</a></h2>
|
|
<p>The DPI flag causes the PATH_INFO portion of the rewritten URI to be
|
|
discarded.</p>
|
|
<p>This flag is available in version 2.2.12 and later.</p>
|
|
<p>In per-directory context, the URI each <code class="directive">RewriteRule</code>
|
|
compares against is the concatenation of the current values of the URI
|
|
and PATH_INFO.</p>
|
|
|
|
<p>The current URI can be the initial URI as requested by the client, the
|
|
result of a previous round of mod_rewrite processing, or the result of
|
|
a prior rule in the current round of mod_rewrite processing.</p>
|
|
|
|
<p>In contrast, the PATH_INFO that is appended to the URI before each
|
|
rule reflects only the value of PATH_INFO before this round of
|
|
mod_rewrite processing. As a consequence, if large portions
|
|
of the URI are matched and copied into a substitution in multiple
|
|
<code class="directive">RewriteRule</code> directives, without regard for
|
|
which parts of the URI came from the current PATH_INFO, the final
|
|
URI may have multiple copies of PATH_INFO appended to it.</p>
|
|
|
|
<p>Use this flag on any substitution where the PATH_INFO that resulted
|
|
from the previous mapping of this request to the filesystem is not of
|
|
interest. This flag permanently forgets the PATH_INFO established
|
|
before this round of mod_rewrite processing began. PATH_INFO will
|
|
not be recalculated until the current round of mod_rewrite processing
|
|
completes. Subsequent rules during this round of processing will see
|
|
only the direct result of substitutions, without any PATH_INFO
|
|
appended.</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_e" id="flag_e">E|env</a></h2>
|
|
<p>With the [E], or [env] flag, you can set the value of an environment
|
|
variable. Note that some environment variables may be set after the rule
|
|
is run, thus unsetting what you have set. See <a href="../env.html">the
|
|
Environment Variables document</a> for more details on how Environment
|
|
variables work.</p>
|
|
|
|
<p>The syntax for this flag is:</p>
|
|
|
|
<div class="example"><p><code>
|
|
[E:VAR=VAL]
|
|
</code></p></div>
|
|
|
|
<p><code>VAL</code> may contain backreferences (<code>$N</code> or
|
|
<code>%N</code>) which will be expanded.</p>
|
|
|
|
<p>These environment variables can then be used in a variety of
|
|
contexts, including CGI programs, other RewriteRule directives, or
|
|
CustomLog directives.</p>
|
|
|
|
<p>The following example sets an evironment variable called 'image' to a
|
|
value of '1' if the requested URI is an image file. Then, that
|
|
environment variable is used to exclude those requests from the access
|
|
log.</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule \.(png|gif|jpg) - [E=image:1]<br />
|
|
CustomLog logs/access_log combined env=!image
|
|
</code></p></div>
|
|
|
|
<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
|
|
an example, not as a recommendation.</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_f" id="flag_f">F|forbidden</a></h2>
|
|
<p>Using the [F] flag causes the server to return a 403 Forbidden status
|
|
code to the client. While the same behavior can be accomplished using
|
|
the <code class="directive"><a href="../mod/mod_access.html#deny">Deny</a></code> directive, this
|
|
allows more flexibility in assigning a Forbidden status.</p>
|
|
|
|
<p>The following rule will forbid <code>.exe</code> files from being
|
|
downloaded from your server.</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule \.exe - [F]
|
|
</code></p></div>
|
|
|
|
<p>This example uses the "-" syntax for the rewrite target, which means
|
|
that the requested URI is not modified. There's no reason to rewrite to
|
|
another URI, if you're going to forbid the request.</p>
|
|
|
|
<p>When using [F], an [L] is implied - that is, the response is returned
|
|
immediately, and no further rules are evaluated.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_g" id="flag_g">G|gone</a></h2>
|
|
<p>The [G] flag forces the server to return a 410 Gone status with the
|
|
response. This indicates that a resource used to be available, but is no
|
|
longer available.</p>
|
|
|
|
<p>As with the [F] flag, you will typically use the "-" syntax for the
|
|
rewrite target when using the [G] flag:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule oldproduct - [G,NC]
|
|
</code></p></div>
|
|
|
|
<p>When using [F], an [L] is implied - that is, the response is returned
|
|
immediately, and no further rules are evaluated.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_h" id="flag_h">H|handler</a></h2>
|
|
<p>Forces the resulting request to be handled with the specified
|
|
handler. For example, one might use this to force all files without a
|
|
file extension to be parsed by the php handler:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule !\. - [H=application/x-httpd-php]
|
|
</code></p></div>
|
|
|
|
<p>
|
|
The regular expression above - <code>!\.</code> - will match any request
|
|
that does not contain the literal <code>.</code> character.
|
|
</p>
|
|
|
|
<p>This can be also used to force the handler based on some conditions.
|
|
For example, the following snippet used in per-server context allows
|
|
<code>.php</code> files to be <em>displayed</em> by <code>mod_php</code>
|
|
if they are requested with the <code>.phps</code> extension:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule ^(/source/.+\.php)s$ $1 [H=application/x-httpd-php-source]
|
|
</code></p></div>
|
|
|
|
<p>The regular expression above - <code>^(/source/.+\.php)s$</code> - will
|
|
match any request that starts with <code>/source/</code> followed by 1 or
|
|
n characters followed by <code>.phps</code> literally. The backreference
|
|
$1 referrers to the captured match within parenthesis of the regular
|
|
expression.</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_l" id="flag_l">L|last</a></h2>
|
|
<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
|
|
the rule set. In most contexts, this means that if the rule matches, no
|
|
further rules will be processed. This corresponds to the
|
|
<code>last</code> command in Perl, or the <code>break</code> command in
|
|
C. Use this flag to indicate that the current rule should be applied
|
|
immediately without considering further rules.</p>
|
|
|
|
<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
|
|
<code>.htaccess</code> files or in
|
|
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> sections,
|
|
it is important to have some understanding of how the rules are
|
|
processed. The simplified form of this is that once the rules have been
|
|
processed, the rewritten request is handed back to the URL parsing
|
|
engine to do what it may with it. It is possible that as the rewritten
|
|
request is handled, the <code>.htaccess</code> file or
|
|
<code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section
|
|
may be encountered again, and thus the ruleset may be run again from the
|
|
start. Most commonly this will happen if one of the rules causes a
|
|
redirect - either internal or external - causing the request process to
|
|
start over.</p>
|
|
|
|
<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
|
|
contexts, that you take explicit steps to avoid rules looping, and not
|
|
count solely on the [L] flag to terminate execution of a series of
|
|
rules, as shown below.</p>
|
|
|
|
<p>The example given here will rewrite any request to
|
|
<code>index.php</code>, giving the original request as a query string
|
|
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
|
|
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>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteCond %{REQUEST_URI} !=index.php<br />
|
|
RewriteRule ^(.*) index.php?req=$1 [L]
|
|
</code></p></div>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_n" id="flag_n">N|next</a></h2>
|
|
<p>
|
|
The [N] flag causes the ruleset to start over again from the top, using
|
|
the result of the ruleset so far as a starting point. Use
|
|
with extreme caution, as it may result in loop.
|
|
</p>
|
|
<p>
|
|
The [Next] flag could be used, for example, if you wished to replace a
|
|
certain string or letter repeatedly in a request. The example shown here
|
|
will replace A with B everywhere in a request, and will continue doing
|
|
so until there are no more As to be replaced.
|
|
</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule (.*)A(.*) $1B$2 [N]
|
|
</code></p></div>
|
|
|
|
<p>You can think of this as a <code>while</code> loop: While this
|
|
pattern still matches (i.e., while the URI still contains an
|
|
<code>A</code>), perform this substitution (i.e., replace the
|
|
<code>A</code> with a <code>B</code>).</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_nc" id="flag_nc">NC|nocase</a></h2>
|
|
<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
|
|
case-insensitive manner. That is, it doesn't care whether letters appear
|
|
as upper-case or lower-case in the matched URI.</p>
|
|
|
|
<p>In the example below, any request for an image file will be proxied
|
|
to your dedicated image server. The match is case-insensitive, so that
|
|
<code>.jpg</code> and <code>.JPG</code> files are both acceptable, for
|
|
example.</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule (.*\.(jpg|gif|png))$ http://images.example.com$1 [P,NC]
|
|
</code></p></div>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_ne" id="flag_ne">NE|noescape</a></h2>
|
|
<p>By default, special characters, such as <code>&</code> and
|
|
<code>?</code>, for example, will be converted to their hexcode
|
|
equivalent. Using the [NE] flag prevents that from happening.
|
|
</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule ^/anchor/(.+) /bigpage.html#$1 [NE,R]
|
|
</code></p></div>
|
|
|
|
<p>
|
|
The above example will redirect <code>/anchor/xyz</code> to
|
|
<code>/bigpage.html#xyz</code>. Omitting the [NE] will result in the #
|
|
being converted to its hexcode equivalent, <code>%23</code>, which will
|
|
then result in a 404 Not Found error condition.
|
|
</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h2>
|
|
<p>Use of the [NS] flag prevents the rule from being used on
|
|
subrequests. For example, a page which is included using an SSI (Server
|
|
Side Include) is a subrequest, and you may want to avoid rewrites
|
|
happening on those subrequests. Also, when <code class="module"><a href="../mod/mod_dir.html">mod_dir</a></code>
|
|
tries to find out information about possible directory default files
|
|
(such as <code>index.html</code> files), this is an internal
|
|
subrequest, and you often want to avoid rewrites on such subrequests.
|
|
On subrequests, it is not always useful, and can even cause errors, if
|
|
the complete set of rules are applied. Use this flag to exclude
|
|
problematic rules.</p>
|
|
|
|
<p>To decide whether or not to use this rule: if you prefix URLs with
|
|
CGI-scripts, to force them to be processed by the CGI-script, it's
|
|
likely that you will run into problems (or significant overhead)
|
|
on sub-requests. In these cases, use this flag.</p>
|
|
|
|
<p>
|
|
Images, javascript files, or css files, loaded as part of an HTML page,
|
|
are not subrequests - the browser requests them as separate HTTP
|
|
requests.
|
|
</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_p" id="flag_p">P|proxy</a></h2>
|
|
<p>Use of the [P] flag causes the request to be handled by
|
|
<code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>, and handled via a proxy request. For
|
|
example, if you wanted all image requests to be handled by a back-end
|
|
image server, you might do something like the following:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
|
|
</code></p></div>
|
|
|
|
<p>Use of the [P] flag implies [L] - that is, the request is immediately
|
|
pushed through the proxy, and any following rules will not be
|
|
considered.</p>
|
|
|
|
<p>
|
|
You must make sure that the substitution string is a valid URI
|
|
(typically starting with <code>http://</code><em>hostname</em>) which can be
|
|
handled by the <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>. If not, you will get an
|
|
error from the proxy module. Use this flag to achieve a
|
|
more powerful implementation of the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive,
|
|
to map remote content into the namespace of the local server.</p>
|
|
|
|
<p>Note: <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
|
|
to use this flag.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_pt" id="flag_pt">PT|passthrough</a></h2>
|
|
|
|
<p>
|
|
The target (or substitution string) in a RewriteRule is assumed to be a
|
|
file path, by default. The use of the [PT] flag causes it to be treated
|
|
as a URI instead. That is to say, the
|
|
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
|
|
URL mapping, so that location-based mappings, such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>, <code class="directive"><a href="../mod/core.html#redirect">Redirect</a></code>, or <code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>, for example, might have a
|
|
chance to take effect.
|
|
</p>
|
|
|
|
<p>
|
|
If, for example, you have an
|
|
<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>
|
|
for /icons, and have a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> pointing there, you should
|
|
use the [PT] flag to ensure that the
|
|
<code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> is evaluated.
|
|
</p>
|
|
|
|
<div class="example"><p><code>
|
|
Alias /icons /usr/local/apache/icons<br />
|
|
RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
|
|
</code></p></div>
|
|
|
|
<p>
|
|
Omission of the [PT] flag in this case will cause the Alias to be
|
|
ignored, resulting in a 'File not found' error being returned.
|
|
</p>
|
|
|
|
<p>The <code>PT</code> flag implies the <code>L</code> flag:
|
|
rewriting will be stopped in order to pass the request to
|
|
the next phase of processing.</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h2>
|
|
<p>
|
|
When the replacement URI contains a query string, the default behavior
|
|
of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to discard
|
|
the existing query string, and replace it with the newly generated one.
|
|
Using the [QSA] flag causes the query strings to be combined.
|
|
</p>
|
|
|
|
<p>Consider the following rule:</p>
|
|
|
|
<div class="example"><p><code>
|
|
RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
|
|
</code></p></div>
|
|
|
|
<p>With the [QSA] flag, a request for <code>/pages/123?one=two</code> will be
|
|
mapped to <code>/page.php?page=123&one=two</code>. Without the [QSA]
|
|
flag, that same request will be mapped to
|
|
<code>/page.php?page=123</code> - that is, the existing query string
|
|
will be discarded.
|
|
</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_qsd" id="flag_qsd">QSD|qsdiscard</a></h2>
|
|
<p>
|
|
When the requested URI contains a query string, and the target URI does
|
|
not, the default behavior of <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> is to copy that query
|
|
string to the target URI. Using the [QSD] flag causes the query string
|
|
to be discarded.
|
|
</p>
|
|
|
|
<p>This flag is available in version 2.4.0 and later.</p>
|
|
|
|
<p>
|
|
Using [QSD] and [QSA] together will result in [QSD] taking precedence.
|
|
</p>
|
|
|
|
<p>
|
|
If the target URI has a query string, the default behavior will be
|
|
observed - that is, the original query string will be discarded and
|
|
replaced with the query string in the <code>RewriteRule</code> target
|
|
URI.
|
|
</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_r" id="flag_r">R|redirect</a></h2>
|
|
<p>
|
|
Use of the [R] flag causes a HTTP redirect to be issued to the browser.
|
|
If a fully-qualified URL is specified (that is, including
|
|
<code>http://servername/</code>) then a redirect will be issued to that
|
|
location. Otherwise, the current protocol, servername, and port number
|
|
will be used to generate the URL sent with the redirect.
|
|
</p>
|
|
|
|
<p>
|
|
<em>Any</em> valid HTTP response status code may be specified,
|
|
using the syntax [R=305], with a 302 status code being used by
|
|
default if none is specified. The status code specified need not
|
|
necessarily be a redirect (3xx) status code.
|
|
</p>
|
|
|
|
<p>If a status code is outside the redirect range (300-399) then the
|
|
substitution string is dropped entirely, and rewriting is stopped as if
|
|
the <code>L</code> were used.</p>
|
|
|
|
<p>In addition to response status codes, you may also specify redirect
|
|
status using their symbolic names: <code>temp</code> (default),
|
|
<code>permanent</code>, or <code>seeother</code>.</p>
|
|
|
|
<p>
|
|
You will almost always want to use [R] in conjunction with [L] (that is,
|
|
use [R,L]) because on its own, the [R] flag prepends
|
|
<code>http://thishost[:thisport]</code> to the URI, but then passes this
|
|
on to the next rule in the ruleset, which can often result in 'Invalid
|
|
URI in request' warnings.
|
|
</p>
|
|
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_s" id="flag_s">S|skip</a></h2>
|
|
<p>The [S] flag is used to skip rules that you don't want to run. This
|
|
can be thought of as a <code>goto</code> statement in your rewrite
|
|
ruleset. In the following example, we only want to run the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> if the requested URI
|
|
doesn't correspond with an actual file.</p>
|
|
|
|
<div class="example"><p><code>
|
|
# Is the request for a non-existent file?<br />
|
|
RewriteCond %{REQUEST_FILENAME} !-f<br />
|
|
RewriteCond %{REQUEST_FILENAME} !-d<br />
|
|
# If so, skip these two RewriteRules<br />
|
|
RewriteRule .? - [S=2]<br />
|
|
<br />
|
|
RewriteRule (.*\.gif) images.php?$1<br />
|
|
RewriteRule (.*\.html) docs.php?$1
|
|
</code></p></div>
|
|
|
|
<p>This technique is useful because a <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> only applies to the
|
|
<code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> immediately
|
|
following it. Thus, if you want to make a <code>RewriteCond</code> apply
|
|
to several <code>RewriteRule</code>s, one possible technique is to
|
|
negate those conditions and use a [Skip] flag. So, you can
|
|
use this to make pseudo if-then-else constructs: The last rule of
|
|
the then-clause becomes <code>skip=N</code>, where N is the
|
|
number of rules in the else-clause.</p>
|
|
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
|
|
<div class="section">
|
|
<h2><a name="flag_t" id="flag_t">T|type</a></h2>
|
|
<p>Sets the MIME type with which the resulting response will be
|
|
sent. This has the same effect as the <code class="directive"><a href="../mod/mod_mime.html#addtype">AddType</a></code> directive.</p>
|
|
|
|
<p>For example, you might use the following technique to serve Perl
|
|
source code as plain text, if requested in a particular way:</p>
|
|
|
|
<div class="example"><p><code>
|
|
# Serve .pl files as plain text<br />
|
|
RewriteRule \.pl$ - [T=text/plain]
|
|
</code></p></div>
|
|
|
|
<p>Or, perhaps, if you have a camera that produces jpeg images without
|
|
file extensions, you could force those images to be served with the
|
|
correct MIME type by virtue of their file names:</p>
|
|
|
|
<div class="example"><p><code>
|
|
# Files with 'IMG' in the name are jpg images.<br />
|
|
RewriteRule IMG - [T=image/jpg]
|
|
</code></p></div>
|
|
|
|
<p>Please note that this is a trivial example, and could be better done
|
|
using <code class="directive"><a href="../mod/core.html#filesmatch"><FilesMatch></a></code>
|
|
instead. Always consider the alternate
|
|
solutions to a problem before resorting to rewrite, which will
|
|
invariably be a less efficient solution than the alternatives.</p>
|
|
|
|
<p>
|
|
If used in per-directory context, use only <code>-</code> (dash)
|
|
as the substitution <em>for the entire round of mod_rewrite processing</em>,
|
|
otherwise the MIME-type set with this flag is lost due to an internal
|
|
re-processing (including subsequent rounds of mod_rewrite processing).
|
|
The <code>L</code> flag can be useful in this context to end the
|
|
<em>current</em> round of mod_rewrite processing.</p>
|
|
|
|
</div></div>
|
|
<div class="bottomlang">
|
|
<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a> |
|
|
<a href="../fr/rewrite/flags.html" hreflang="fr" rel="alternate" title="Français"> fr </a></p>
|
|
</div><div id="footer">
|
|
<p class="apache">Copyright 2010 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>
|
|
<p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="../faq/">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div>
|
|
</body></html> |