<h3><a name="flag_ns" id="flag_ns">NS|nosubreq</a></h3>
-<p>No internal subrequest flag</p>
+<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.</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>
<h3><a name="flag_p" id="flag_p">P|proxy</a></h3>
-<p>Proxy flag</p>
+<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 immediatly
+pushed through the proxy, and any following rules will not be
+considered.</p>
+
<h3><a name="flag_pt" id="flag_pt">PT|passthrough</a></h3>
-<p>Passthrough flag</p>
+
+<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
+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
+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>
+
<h3><a name="flag_qsa" id="flag_qsa">QSA|qsappend</a></h3>
-<p>Query String Append flag</p>
+<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>
<h3><a name="flag_r" id="flag_r">R|redirect</a></h3>
-<p>Redirect flag</p>
+<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 servername will be used to generate the
+URL sent with the redirect.
+</p>
+
+<p>
+A status code may be specified, in the range 300-399, with a 302 status
+code being used by default if none is specified.
+</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>
+
<h3><a name="flag_s" id="flag_s">S|skip</a></h3>
</section>
<section id="flag_ns"><title>NS|nosubreq</title>
-<p>No internal subrequest flag</p>
+<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.</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>
</section>
<section id="flag_p"><title>P|proxy</title>
-<p>Proxy flag</p>
+<p>Use of the [P] flag causes the request to be handled by
+<module>mod_proxy</module>, 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>
+
+<example>
+RewriteRule (.*)\.(jpg|gif|png) http://images.example.com$1.$2 [P]
+</example>
+
+<p>Use of the [P] flag implies [L] - that is, the request is immediatly
+pushed through the proxy, and any following rules will not be
+considered.</p>
+
</section>
<section id="flag_pt"><title>PT|passthrough</title>
-<p>Passthrough flag</p>
+
+<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 <directive
+module="mod_rewrite">RewriteRule</directive> to be passed back through
+URL mapping, so that location-based mappings, such as <directive
+module="mod_alias">Alias</directive>, for example, might have a chance to take
+effect.
+</p>
+
+<p>
+If, for example, you have an
+<directive module="mod_alias">Alias</directive>
+for /icons, and have a <directive
+module="mod_rewrite">RewriteRule</directive> pointing there, you should
+use the [PT] flag to ensure that the
+<directive module="mod_alias">Alias</directive> is evaluated.
+</p>
+
+<example>
+Alias /icons /usr/local/apache/icons
+RewriteRule /pics/(.+)\.jpg /icons/$1.gif [PT]
+</example>
+
+<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>
+
</section>
<section id="flag_qsa"><title>QSA|qsappend</title>
-<p>Query String Append flag</p>
+<p>
+When the replacement URI contains a query string, the default behavior
+of <directive module="mod_rewrite">RewriteRule</directive> 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>
+
+<example>
+RewriteRule /pages/(.+) /page.php?page=$1 [QSA]
+</example>
+
+<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>
</section>
<section id="flag_r"><title>R|redirect</title>
-<p>Redirect flag</p>
+<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 servername will be used to generate the
+URL sent with the redirect.
+</p>
+
+<p>
+A status code may be specified, in the range 300-399, with a 302 status
+code being used by default if none is specified.
+</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>
+
</section>
<section id="flag_s"><title>S|skip</title>
projects / thirdparty / apache / httpd.git / commitdiff
