entire module in just one day.</p>
</div>
-<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></li><li><a href="rewrite_intro.html">Introduction</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></li></ul></div>
+<div id="quickview"><h3>See also</h3><ul class="seealso"><li><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></li><li><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></li><li><a href="../glossary.html">Glossary</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="documentation" id="documentation">Documentation</a></h2>
<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
documentation</a></li>
<li><a href="rewrite_intro.html">Introduction</a></li>
+<li><a href="rewrite_flags.html">Flags</a></li>
<li><a href="rewrite_tech.html">Technical details</a></li>
<li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
<li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
useful examples</a></li>
-<li><a href="../glossary.html">Glossary</a></li>
</ul>
</div></div>
<div class="bottomlang">
</summary>
-<seealso><a href="../mod/mod_rewrite.html">mod_rewrite reference
-documentation</a></seealso>
-<seealso><a href="rewrite_intro.html">Introduction</a></seealso>
-<seealso><a href="rewrite_tech.html">Technical details</a></seealso>
-<seealso><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></seealso>
-<seealso><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
-advanced useful examples</a></seealso>
+<seealso><a href="../urlmapping.html">Mapping URLs to the Filesystem</a></seealso>
+<seealso><a href="http://wiki.apache.org/httpd/Rewrite">mod_rewrite
+wiki</a></seealso>
+<seealso><a href="../glossary.html">Glossary</a></seealso>
<section id="documentation"><title>Documentation</title>
<ul>
<li><a href="../mod/mod_rewrite.html">mod_rewrite reference
documentation</a></li>
<li><a href="rewrite_intro.html">Introduction</a></li>
+<li><a href="rewrite_flags.html">Flags</a></li>
<li><a href="rewrite_tech.html">Technical details</a></li>
<li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li>
<li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide - more
useful examples</a></li>
-<li><a href="../glossary.html">Glossary</a></li>
</ul>
</section>
-URI: flags.html.en
+URI: rewrite_flags.html.en
Content-Language: en
Content-type: text/html; charset=ISO-8859-1
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-->
<title>Apache mod_rewrite 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>
+<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="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="./index.html"><img title="<-" alt="<-" src="../images/left.gif" /></a></div>
+<img alt="" src="/images/feather.gif" /></div>
+<div class="up"><a href="./index.html"><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></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Flags</h1>
+<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></div><div id="page-content"><div id="preamble"><h1>Apache mod_rewrite Flags</h1>
<div class="toplang">
-<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a></p>
+<p><span>Available Languages: </span></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 more detailed explanations and examples of each.</p>
+<code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> directive,
+providing detailed explanations and examples. This is not necessarily
+a comprehensive list of all flags available, so be sure to also
+consult the reference documentation.</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="#flags">The flags</a></li>
+<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="#flags">The flags</a></li>
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Rewrite Guide - useful examples</a></li><li><a href="rewrite_guide_advanced.html">Advanced Rewrite Guide -
advanced useful examples</a></li></ul></div>
-<div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></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><code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
+<p><code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>s can have
their 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>
a longer form, such as <code>cookie</code>. Some flags take one or more
arguments. Flags are not case sensitive.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
+</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
<div class="section">
<h2><a name="flags" id="flags">The flags</a></h2>
of how you might use them.</p>
<h3><a name="flag_c" id="flag_c">C|chain</a></h3>
-<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
+<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
<h3><a name="flag_co" id="flag_co">CO|cookie</a></h3>
<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>
+particular <code class="directive"><a href="/mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>
matches. The argument consists of three required fields and two optional
fields.</p>
<p>You must declare a name and value for the cookie to be set, and the
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
+<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>
<h3><a name="flag_f" id="flag_f">F|forbidden</a></h3>
<p>Using the [F] flag causes Apache 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
+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
<h3><a name="flag_l" id="flag_l">L|last</a></h3>
-<p>The [L] flag causes <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> to stop processing
+<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.</p>
-<p>If you are using <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> in either
+<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,
+<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
+<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
+<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
context 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>
<h3><a name="flag_nc" id="flag_nc">NC|nocase</a></h3>
-<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
+<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>
<h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
<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
+<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>
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 trated
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>, for example, might have a chance to take
+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>, 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
+<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.
+<code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code> is evaluated.
</p>
<div class="example"><p><code>
<h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
<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
+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>
<h3><a name="flag_s" id="flag_s">S|skip</a></h3>
<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
+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>
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
+<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.</p>
<h3><a name="flag_t" id="flag_t">T|type</a></h3>
<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>
+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>
</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>
+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>
</div></div>
<div class="bottomlang">
-<p><span>Available Languages: </span><a href="../en/rewrite/flags.html" title="English"> en </a></p>
+<p><span>Available Languages: </span></p>
</div><div id="footer">
<p class="apache">Copyright 2008 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>
+<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>
\ No newline at end of file
<summary>
<p>This document discusses the flags which are available to the
<directive module="mod_rewrite">RewriteRule</directive> directive,
-providing more detailed explanations and examples of each.</p>
+providing detailed explanations and examples. This is not necessarily
+a comprehensive list of all flags available, so be sure to also
+consult the reference documentation.</p>
</summary>
<seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
<?xml version="1.0" encoding="UTF-8" ?>
<metafile>
- <basename>flags</basename>
+ <basename>rewrite_flags</basename>
<path>/rewrite/</path>
<relpath>..</relpath>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritecond">Rewrite conditions</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#rewritemap">Rewrite maps</a></li>
<li><img alt="" src="../images/down.gif" /> <a href="#htaccess">.htaccess files</a></li>
-<li><img alt="" src="../images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
</ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module
documentation</a></li><li><a href="rewrite_tech.html">Technical details</a></li><li><a href="rewrite_guide.html">Practical solutions to common
problems</a></li><li><a href="rewrite_guide_advanced.html">Practical solutions to
<p>This document attempts to give sufficient background so that what
follows is understood, rather than just copied blindly.
</p>
+
+<p>Remember that many common URL-manipulation tasks don't require the
+full power and complexity of <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>. For simple
+tasks, see <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> and the documentation
+on <a href="../urlmapping.html">mapping URLs to the
+filesystem</a>.</p>
+
+<p>Finally, before proceding, be sure to configure
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewritelog">RewriteLog</a></code>. Although
+this log file can give an overwhelming amount of information, it is
+indispensable in debugging problems with <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+configuration, since it will tell you exactly how each rule is
+processed.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="regex" id="regex">Regular Expressions</a></h2>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewriterule" id="rewriterule">RewriteRule basics</a></h2>
-<p>
-Basic anatomy of a RewriteRule, with exhaustively annotated simple
-examples.
-</p>
+<p>A <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> consists
+of three arguments separated by spaces. The arguments are</p>
+<ol>
+<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
+<li><var>Substitution</var>: where should the matching requests be sent;</li>
+<li><var>[flags]</var>: options affecting the rewritten request.</li>
+</ol>
+
+<p>The <var>Pattern</var> is always a <a href="#regex">regular
+expression</a> matched against the URL-Path of the incoming request
+(the part after the hostname but before any question mark indicating
+the beginning of a query string).</p>
+
+<p>The <var>Substitution</var> can itself be one of three things:</p>
+
+<dl>
+<dt>A full filesystem path to a resource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/games.* /usr/local/games/web
+</code></p></div>
+<p>This maps a request to an arbitrary location on your filesystem, much
+like the <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive.</p>
+</dd>
+
+<dt>A web-path to a resource</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/foo$ /bar
+</code></p></div>
+<p>If <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code> is set
+to <code>/usr/local/apache2/htdocs</code>, then this directive would
+map requests for <code>http://example.com/foo</code> to the
+path <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>An absolute URL</dt>
+<dd>
+<div class="example"><p><code>
+RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]
+</code></p></div>
+<p>This tells the client to make a new request for the specified URL.</p>
+</dd>
+</dl>
+
+<p>The <var>Substitution</var> can also
+contain <em>back-references</em> to parts of the incoming URL-path
+matched by the <var>Pattern</var>. Consider the following:</p>
+<div class="example"><p><code>
+RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1
+</code></p></div>
+<p>The variable <code>$1</code> will be replaced with whatever text
+was matched by the expression inside the parenthesis in
+the <var>Pattern</var>. For example, a request
+for <code>http://example.com/product/r14df/view</code> will be mapped
+to the path <code>/var/web/productdbr14df</code>.</p>
+
+<p>If there is more than one expression in parenthesis, they are
+available in order in the
+variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
+on.</p>
+
+
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="flags" id="flags">Rewrite Flags</a></h2>
</code></p></div>
<p>For more details on the available flags, their meanings, and
-examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
<div class="section">
<h2><a name="rewritecond" id="rewritecond">Rewrite conditions</a></h2>
-<p>The <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> directive
-allows a condition to be applied to a <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>.
-</p>
+<p>One or more <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>
+directives can be used to restrict the types of requests that will be
+subject to the
+following <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. The
+first argument is a variable describing a characteristic of the
+request, the second argument is a <a href="#regex">regular
+expression</a> that must match the variable, and a third optional
+argument is a list of flags that modify how the match is evaluated.</p>
+
+<p>For example, to send all requests from a particular IP range to a
+different server, you could use:</p>
+<div class="example"><p><code>
+RewriteCond %{REMOTE_ADDR} ^10\2.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</code></p></div>
+
+<p>When more than
+one <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code> is
+specified, they must all match for
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> to be
+applied. For example, to deny requests that contain the word "hack" in
+their query string, except if they also contain a cookie containing
+the word "go", you could use:</p>
+<div class="example"><p><code>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</code></p></div>
+<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
+
+<p>Matches in the regular expressions contained in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewritecond">RewriteCond</a></code>s can be
+used as part of the <var>Substitution</var> in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> using the
+variables <code>%1</code>, <code>%2</code>, etc. For example, this
+will direct the request to a different directory depending on the
+hostname used to access the site:</p>
+<div class="example"><p><code>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</code></p></div>
+<p>If the request was for <code>http://example.com/foo/bar</code>,
+then <code>%1</code> would contain <code>example.com</code>
+and <code>$1</code> would contain <code>foo/bar</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="rewritemap" id="rewritemap">Rewrite maps</a></h2>
-<p>Discussion of RewriteMap, including simple, but heavily annotated,
-examples.</p>
+<p>See <code class="directive"><a href="../mod/mod_rewrite.html#rewritemap">RewriteMap</a></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="htaccess" id="htaccess">.htaccess files</a></h2>
-<p>Discussion of the differences between rewrite rules in httpd.conf and
-in .htaccess files.</p>
-</div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
-<div class="section">
-<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
-
-<p>This module keeps track of two additional (non-standard)
-CGI/SSI environment variables named <code>SCRIPT_URL</code>
-and <code>SCRIPT_URI</code>. These contain the
-<em>logical</em> Web-view to the current resource, while the
-standard CGI/SSI variables <code>SCRIPT_NAME</code> and
-<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
-System-view. </p>
-
-<p>Notice: These variables hold the URI/URL <em>as they were
-initially requested</em>, <em>i.e.</em>, <em>before</em> any
-rewriting. This is important because the rewriting process is
-primarily used to rewrite logical URLs to physical
-pathnames.</p>
-
-<div class="example"><h3>Example</h3><pre>
-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-</pre></div>
+
+<p>Rewriting is typically configured in the main server configuration
+setting (outside any <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code> section) or
+inside <code class="directive"><a href="../mod/core.html#virtualhost"><VirtualHost></a></code>
+containers. This is the easiest way to do rewriting and is
+recommended. It is possible, however, to do rewriting
+inside <code class="directive"><a href="../mod/core.html#directory"><Directory></a></code>
+sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
+files</a> at the expense of some additional complexity. This technique
+is called per-directory rewrites.</p>
+
+<p>The main difference with per-directory rewrites is that the path
+prefix of the directory containing the <code>.htaccess</code> file is
+stripped before matching in
+the <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. In addition, the <code class="directive"><a href="../mod/mod_rewrite.html#rewritebase">RewriteBase</a></code> should be used to assure the request is properly mapped.</p>
</div></div>
<div class="bottomlang">
<p>This document attempts to give sufficient background so that what
follows is understood, rather than just copied blindly.
</p>
+
+<p>Remember that many common URL-manipulation tasks don't require the
+full power and complexity of <module>mod_rewrite</module>. For simple
+tasks, see <module>mod_alias</module> and the documentation
+on <a href="../urlmapping.html">mapping URLs to the
+filesystem</a>.</p>
+
+<p>Finally, before proceding, be sure to configure
+the <directive module="mod_rewrite">RewriteLog</directive>. Although
+this log file can give an overwhelming amount of information, it is
+indispensable in debugging problems with <module>mod_rewrite</module>
+configuration, since it will tell you exactly how each rule is
+processed.</p>
</section>
<section id="regex"><title>Regular Expressions</title>
</section>
<section id="rewriterule"><title>RewriteRule basics</title>
-<p>
-Basic anatomy of a RewriteRule, with exhaustively annotated simple
-examples.
-</p>
+<p>A <directive module="mod_rewrite">RewriteRule</directive> consists
+of three arguments separated by spaces. The arguments are</p>
+<ol>
+<li><var>Pattern</var>: which incoming URLs should be affected by the rule;</li>
+<li><var>Substitution</var>: where should the matching requests be sent;</li>
+<li><var>[flags]</var>: options affecting the rewritten request.</li>
+</ol>
+
+<p>The <var>Pattern</var> is always a <a href="#regex">regular
+expression</a> matched against the URL-Path of the incoming request
+(the part after the hostname but before any question mark indicating
+the beginning of a query string).</p>
+
+<p>The <var>Substitution</var> can itself be one of three things:</p>
+
+<dl>
+<dt>A full filesystem path to a resource</dt>
+<dd>
+<example>
+RewriteRule ^/games.* /usr/local/games/web
+</example>
+<p>This maps a request to an arbitrary location on your filesystem, much
+like the <directive module="mod_alias">Alias</directive> directive.</p>
+</dd>
+
+<dt>A web-path to a resource</dt>
+<dd>
+<example>
+RewriteRule ^/foo$ /bar
+</example>
+<p>If <directive module="core">DocumentRoot</directive> is set
+to <code>/usr/local/apache2/htdocs</code>, then this directive would
+map requests for <code>http://example.com/foo</code> to the
+path <code>/usr/local/apache2/htdocs/bar</code>.</p>
+</dd>
+
+<dt>An absolute URL</dt>
+<dd>
+<example>
+RewriteRule ^/product/view$ http://site2.example.com/seeproduct.html [R]
+</example>
+<p>This tells the client to make a new request for the specified URL.</p>
+</dd>
+</dl>
+
+<p>The <var>Substitution</var> can also
+contain <em>back-references</em> to parts of the incoming URL-path
+matched by the <var>Pattern</var>. Consider the following:</p>
+<example>
+RewriteRule ^/product/(.*)/view$ /var/web/productdb/$1
+</example>
+<p>The variable <code>$1</code> will be replaced with whatever text
+was matched by the expression inside the parenthesis in
+the <var>Pattern</var>. For example, a request
+for <code>http://example.com/product/r14df/view</code> will be mapped
+to the path <code>/var/web/productdbr14df</code>.</p>
+
+<p>If there is more than one expression in parenthesis, they are
+available in order in the
+variables <code>$1</code>, <code>$2</code>, <code>$3</code>, and so
+on.</p>
+
+
</section>
<section id="flags"><title>Rewrite Flags</title>
</example>
<p>For more details on the available flags, their meanings, and
-examples, see the <a href="flags.html">Rewrite Flags</a> document.</p>
+examples, see the <a href="rewrite_flags.html">Rewrite Flags</a> document.</p>
</section>
<section id="rewritecond"><title>Rewrite conditions</title>
-<p>The <directive module="mod_rewrite">RewriteCond</directive> directive
-allows a condition to be applied to a <directive
-module="mod_rewrite">RewriteRule</directive>.
-</p>
+<p>One or more <directive module="mod_rewrite">RewriteCond</directive>
+directives can be used to restrict the types of requests that will be
+subject to the
+following <directive module="mod_rewrite">RewriteRule</directive>. The
+first argument is a variable describing a characteristic of the
+request, the second argument is a <a href="#regex">regular
+expression</a> that must match the variable, and a third optional
+argument is a list of flags that modify how the match is evaluated.</p>
+
+<p>For example, to send all requests from a particular IP range to a
+different server, you could use:</p>
+<example>
+RewriteCond %{REMOTE_ADDR} ^10\2.<br />
+RewriteRule (.*) http://intranet.example.com$1
+</example>
+
+<p>When more than
+one <directive module="mod_rewrite">RewriteCond</directive> is
+specified, they must all match for
+the <directive module="mod_rewrite">RewriteRule</directive> to be
+applied. For example, to deny requests that contain the word "hack" in
+their query string, except if they also contain a cookie containing
+the word "go", you could use:</p>
+<example>
+RewriteCond %{QUERY_STRING} hack<br />
+RewriteCond %{HTTP_COOKIE} !go<br />
+RewriteRule .* - [F]
+</example>
+<p>Notice that the exclamation mark specifies a negative match, so the rule is only applied if the cookie does not contain "go".</p>
+
+<p>Matches in the regular expressions contained in
+the <directive module="mod_rewrite">RewriteCond</directive>s can be
+used as part of the <var>Substitution</var> in
+the <directive module="mod_rewrite">RewriteRule</directive> using the
+variables <code>%1</code>, <code>%2</code>, etc. For example, this
+will direct the request to a different directory depending on the
+hostname used to access the site:</p>
+<example>
+RewriteCond %{HTTP_HOST} (.*)<br />
+RewriteRule ^/(.*) /sites/%1/$1
+</example>
+<p>If the request was for <code>http://example.com/foo/bar</code>,
+then <code>%1</code> would contain <code>example.com</code>
+and <code>$1</code> would contain <code>foo/bar</code>.</p>
+
+
</section>
<section id="rewritemap"><title>Rewrite maps</title>
-<p>Discussion of RewriteMap, including simple, but heavily annotated,
-examples.</p>
+<p>See <directive module="mod_rewrite">RewriteMap</directive>.</p>
</section>
<section id="htaccess"><title>.htaccess files</title>
-<p>Discussion of the differences between rewrite rules in httpd.conf and
-in .htaccess files.</p>
-</section>
-<section id="EnvVar"><title>Environment Variables</title>
-
-<p>This module keeps track of two additional (non-standard)
-CGI/SSI environment variables named <code>SCRIPT_URL</code>
-and <code>SCRIPT_URI</code>. These contain the
-<em>logical</em> Web-view to the current resource, while the
-standard CGI/SSI variables <code>SCRIPT_NAME</code> and
-<code>SCRIPT_FILENAME</code> contain the <em>physical</em>
-System-view. </p>
-
-<p>Notice: These variables hold the URI/URL <em>as they were
-initially requested</em>, <em>i.e.</em>, <em>before</em> any
-rewriting. This is important because the rewriting process is
-primarily used to rewrite logical URLs to physical
-pathnames.</p>
-
-<example><title>Example</title>
-<pre>
-SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
-SCRIPT_FILENAME=/u/rse/.www/index.html
-SCRIPT_URL=/u/rse/
-SCRIPT_URI=http://en1.engelschall.com/u/rse/
-</pre>
-</example>
+<p>Rewriting is typically configured in the main server configuration
+setting (outside any <directive type="section"
+module="core">Directory</directive> section) or
+inside <directive type="section" module="core">VirtualHost</directive>
+containers. This is the easiest way to do rewriting and is
+recommended. It is possible, however, to do rewriting
+inside <directive type="section" module="core">Directory</directive>
+sections or <a href="../howto/htaccess.html"><code>.htaccess</code>
+files</a> at the expense of some additional complexity. This technique
+is called per-directory rewrites.</p>
+
+<p>The main difference with per-directory rewrites is that the path
+prefix of the directory containing the <code>.htaccess</code> file is
+stripped before matching in
+the <directive module="mod_rewrite">RewriteRule</directive>. In addition, the <directive module="mod_rewrite">RewriteBase</directive> should be used to assure the request is properly mapped.</p>
</section>
projects / thirdparty / apache / httpd.git / commitdiff
