You are viewing a plain text version of this content. The canonical link for it is here.
Posted to cvs@httpd.apache.org by Brian Behlendorf <br...@hyperreal.com> on 1997/02/03 23:23:30 UTC
cvs commit: apache/htdocs/manual/mod mod_rewrite.html
brian 97/02/03 14:23:29
Modified: htdocs/manual/mod mod_rewrite.html
Log:
Reviewed by: Brian Behlendorf
Submitted by: "Ralf S. Engelschall" <rs...@engelschall.com>
Updates to the documentation for mod_rewrite.
Revision Changes Path
1.5 +102 -38 apache/htdocs/manual/mod/mod_rewrite.html
Index: mod_rewrite.html
===================================================================
RCS file: /export/home/cvs/apache/htdocs/manual/mod/mod_rewrite.html,v
retrieving revision 1.4
retrieving revision 1.5
diff -C3 -r1.4 -r1.5
*** mod_rewrite.html 1997/01/10 08:24:03 1.4
--- mod_rewrite.html 1997/02/03 22:23:27 1.5
***************
*** 8,21 ****
<body>
<!--#include virtual="header.html" -->
- <h1>Module mod_rewrite (Version 2.3)</h1>
! This module is contained in the <code>mod_rewrite.c</code> file, with
! Apache 1.2 and later. It provides
! a rule-based rewriting engine to rewrite requested URLs on the fly.
! <code>mod_rewrite</code> is not compiled into the server by
! default. To use <code>mod_rewrite</code> you have to enable the following
! line in the server build Configuration file:
<pre>
Module rewrite_module mod_rewrite.o
</pre>
--- 8,21 ----
<body>
<!--#include virtual="header.html" -->
! <h1>Module mod_rewrite (Version 3.0)</h1>
!
! This module is contained in the <code>mod_rewrite.c</code> file, with Apache
! 1.2 and later. It provides a rule-based rewriting engine to rewrite requested
! URLs on the fly. <code>mod_rewrite</code> is not compiled into the server by
! default. To use <code>mod_rewrite</code> you have to enable the following line
! in the server build Configuration file:
<pre>
Module rewrite_module mod_rewrite.o
</pre>
***************
*** 45,57 ****
<p>
Copyright © 1996,1997 <b>The Apache Group</b>, All rights reserved.<br>
! Copyright © 1996 <i>Ralf S. Engelschall</i>, All rights reserved.
<p>
Written for <b>The Apache Group</b> by
<blockquote>
<i>Ralf S. Engelschall</i><br>
<a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br>
! <a href="http://www.engelschall.com/~rse"><tt>http://www.engelschall.com/~rse</i></a>
</blockquote>
<!--%hypertext -->
--- 45,57 ----
<p>
Copyright © 1996,1997 <b>The Apache Group</b>, All rights reserved.<br>
! Copyright © 1996,1997 <i>Ralf S. Engelschall</i>, All rights reserved.
<p>
Written for <b>The Apache Group</b> by
<blockquote>
<i>Ralf S. Engelschall</i><br>
<a href="mailto:rse@engelschall.com"><tt>rse@engelschall.com</tt></a><br>
! <a href="http://www.engelschall.com/"><tt>www.engelschall.com</tt></a>
</blockquote>
<!--%hypertext -->
***************
*** 114,124 ****
<ul>
<li>'<strong><code>inherit</code></strong>'<br>
! This forces the current configuration to inherit the configuration of the
! parent. In per-virtual-server context this means that the maps,
! conditions and rules of the main server gets inherited. In per-directory
! context this means that conditions and rules of the parent directory's
! <tt>.htaccess</tt> configuration gets inherited.
<p>
</ul>
--- 114,124 ----
<ul>
<li>'<strong><code>inherit</code></strong>'<br>
! This forces the current configuration to inherit the configuration of the
! parent. In per-virtual-server context this means that the maps,
! conditions and rules of the main server gets inherited. In per-directory
! context this means that conditions and rules of the parent directory's
! <tt>.htaccess</tt> configuration gets inherited.
<p>
</ul>
***************
*** 151,162 ****
<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>!
</td></tr>
</table>
- <P>
! SECURITY: See the <A HREF="../misc/security_tips.html">security
! tips</A> document for details on why your security could be
! compromised if the directory where logfiles are stored is writable
! by anyone other than the user that starts the server. <P>
<p>
<b>Example:</b>
--- 151,167 ----
<tt>RewriteLog</tt> directive or use <tt>RewriteLogLevel 0</tt>!
</td></tr>
</table>
! <p>
! <table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
! <tr><td>
! SECURITY: See the <a
! href="http://www.apache.org/docs/misc/security_tips.html">Apache Security
! Tips</a> document for details on why your security could be compromised if the
! directory where logfiles are stored is writable by anyone other than the user
! that starts the server.
! </td></tr>
! </table>
<p>
<b>Example:</b>
***************
*** 365,371 ****
When a substitution occurs for a new URL, this module has to
re-inject the URL into the server processing. To be able to do this it needs
to know what the corresponding URL-prefix or URL-base is. By default this
! prefix is the corresponding filepath itself. <b>But at most web-sites URLs are
<b>NOT</b> directly related to physical filename paths, so this assumption
will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt>
directive to specify the correct URL-prefix.
--- 370,376 ----
When a substitution occurs for a new URL, this module has to
re-inject the URL into the server processing. To be able to do this it needs
to know what the corresponding URL-prefix or URL-base is. By default this
! prefix is the corresponding filepath itself. <b>But at most websites URLs are
<b>NOT</b> directly related to physical filename paths, so this assumption
will be usually be wrong!</b> There you have to use the <tt>RewriteBase</tt>
directive to specify the correct URL-prefix.
***************
*** 373,379 ****
<p>
<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
! So, if your web-server's URLs are <b>not</b> directly
related to physical file paths, you have to use <tt>RewriteBase</tt> in every
<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt>
directives.
--- 378,384 ----
<p>
<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
! So, if your webserver's URLs are <b>not</b> directly
related to physical file paths, you have to use <tt>RewriteBase</tt> in every
<tt>.htaccess</tt> files where you want to use <tt>RewriteRule</tt>
directives.
***************
*** 541,551 ****
--- 546,558 ----
THE_REQUEST<br>
REQUEST_URI<br>
REQUEST_FILENAME<br>
+ IS_SUBREQ<br>
</font>
</td>
</tr>
</table>
+
<p>
<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
***************
*** 566,582 ****
field of <tt>request_rec</tt>).
<p>
! <li>There is an additional format: <tt>%{ENV:variable}</tt> where
! <i>variable</i> can be any Unix environment variable. This is looked-up
! via <tt>getenv()</tt> from the Apache server process.
<p>
! <li>There is one more additional format: <tt>%{HTTP:header}</tt> where
<i>header</i> can be any HTTP MIME-header name. This is looked-up
from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt>
is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''.
- </ol>
<p>
<em>CondPattern</em> is the condition pattern, i.e. a regular expression
--- 573,599 ----
field of <tt>request_rec</tt>).
<p>
! <li>There is the special format: <tt>%{ENV:variable}</tt> where
! <i>variable</i> can be any environment variable. This is looked-up via
! internal Apache structures and (if not found there) via <tt>getenv()</tt> from
! the Apache server process.
<p>
! <li>There is the special format: <tt>%{HTTP:header}</tt> where
<i>header</i> can be any HTTP MIME-header name. This is looked-up
from the HTTP request. Example: <tt>%{HTTP:Proxy-Connection}</tt>
is the value of the HTTP header ``<tt>Proxy-Connection:</tt>''.
+ <p>
+ <li>There is the special format: <tt>%{LA-U:url}</tt>
+ for look-aheads like <tt>-U</tt>. This performans a internal sub-request to
+ look-ahead for the final value of <i>url</i>.
+
+ <p>
+ <li>There is the special format: <tt>%{LA-F:file}</tt>
+ for look-aheads like <tt>-F</tt>. This performans a internal sub-request to
+ look-ahead for the final value of <i>file</i>.
+ </ol>
<p>
<em>CondPattern</em> is the condition pattern, i.e. a regular expression
***************
*** 613,618 ****
--- 630,647 ----
<li>'<b>-l</b>' (is symbolic <b>l</b>ink)<br>
Treats the <i>TestString</i> as a pathname and
tests if it exists and is a symbolic link.
+ <p>
+ <li>'<b>-F</b>' (is existing file via subrequest)<br>
+ Checks if <i>TestString</i> is a valid file and accessible via all the
+ server's currently-configured access controls for that path. This uses an
+ internal subrequest to determine the check, so use it with care because it
+ decreases your servers performance!
+ <p>
+ <li>'<b>-U</b>' (is existing URL via subrequest)<br>
+ Checks if <i>TestString</i> is a valid URL and accessible via all the server's
+ currently-configured access controls for that path. This uses an internal
+ subrequest to determine the check, so use it with care because it decreases
+ your servers performance!
</ul>
<p>
Notice: All of these tests can also be prefixed by a not ('!') character
***************
*** 636,644 ****
<em>TestString</em> and the <em>CondPattern</em>.
<p>
<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br>
! Use this to combine rule conditions with a local OR instead of the
! implicit AND. Typical example:
! <p>
<blockquote><pre>
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
--- 665,673 ----
<em>TestString</em> and the <em>CondPattern</em>.
<p>
<li>'<strong><code>ornext|OR</code></strong>' (<b>or</b> next condition)<br>
! Use this to combine rule conditions with a local OR instead of the
! implicit AND. Typical example:
! <p>
<blockquote><pre>
RewriteCond %{REMOTE_HOST} ^host1.* [OR]
RewriteCond %{REMOTE_HOST} ^host2.* [OR]
***************
*** 653,659 ****
<b>Example:</b>
<blockquote>
! To rewrite the Home-page of a site according to the ``<tt>User-Agent:</tt>''
header of the request, you can use the following:
<blockquote><pre>
--- 682,688 ----
<b>Example:</b>
<blockquote>
! To rewrite the Homepage of a site according to the ``<tt>User-Agent:</tt>''
header of the request, you can use the following:
<blockquote><pre>
***************
*** 805,820 ****
comma-separated list of the following flags:
<ul>
! <li>'<strong><code>redirect|R</code></strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br>
Prefix <em>Substitution</em>
! with <code>http://thishost/</code> (which makes the new URL a URI) to
! force a external redirection. Use it for rules which should
! canonicalize the URL and gives it back to the client, e.g. translate
``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to
<code>/u/</code><em>user</em>, etc.<br>
<b>Notice:</b> When you use this flag, make sure that the
! substitution field is a valid URL! If not, you are redirecting to an invalid
! location!</b>
<p>
<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br>
This flag forces the substitution part to be internally forced as a proxy
--- 834,868 ----
comma-separated list of the following flags:
<ul>
! <li>'<strong><code>redirect|R</code>[=<i>code</i>]</strong>' (force <a name="redirect"><b>r</b>edirect</a>)<br>
Prefix <em>Substitution</em>
! with <code>http://thishost[:thisport]/</code> (which makes the new URL a URI) to
! force a external redirection. If no <i>code</i> is given a HTTP response
! of 302 (MOVED TEMPORARILY) is used. If you want to use other response
! codes in the range 300-400 just specify them as a number or use
! one of the following symbolic names: <tt>temp</tt> (default), <tt>permanent</tt>,
! <tt>seeother</tt>.
! Use it for rules which should
! canonicalize the URL and gives it back to the client, e.g. translate
``<code>/~</code>'' into ``<code>/u/</code>'' or always append a slash to
<code>/u/</code><em>user</em>, etc.<br>
+ <p>
<b>Notice:</b> When you use this flag, make sure that the
! substitution field is a valid URL! If not, you are redirecting to an
! invalid location! And remember that this flag itself only prefixes the
! URL with <code>http://thishost[:thisport]/</code>, but rewriting goes on.
! Usually you also want to stop and do the redirection immediately. To stop
! the rewriting you also have to provide the 'L' flag.
! <p>
! <li>'<strong><code>forbidden|F</code></strong>' (force URL to be <b>f</b>orbidden)<br>
! This forces the current URL to be forbidden, i.e. it immediately sends
! back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with
! appropriate RewriteConds to conditionally block some URLs.
! <p>
! <li>'<strong><code>gone|G</code></strong>' (force URL to be <b>g</b>one)<br>
! This forces the current URL to be gone, i.e. it immediately sends back a
! HTTP response of 410 (GONE). Use this flag to mark no longer existing
! pages as gone.
<p>
<li>'<strong><code>proxy|P</code></strong>' (force <b>p</b>roxy)<br>
This flag forces the substitution part to be internally forced as a proxy
***************
*** 824,830 ****
be handled by the Apache proxy module. If not you get an error from
the proxy module. Use this flag to achieve a more powerful implementation
of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map
! some remote stuff into the name-space of the local server.
<p>
<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br>
Stop the rewriting process here and
--- 872,884 ----
be handled by the Apache proxy module. If not you get an error from
the proxy module. Use this flag to achieve a more powerful implementation
of the <tt>mod_proxy</tt> directive <tt>ProxyPass</tt>, to map
! some remote stuff into the namespace of the local server.
! <p>
! Notice: <b>You really have to put <tt>ProxyRequests On</tt> into your
! server configuration to prevent proxy requests from leading to core-dumps
! inside the Apache kernel. If you have not compiled in the proxy module,
! then there is no core-dump problem, because mod_rewrite checks for
! existence of the proxy module and if lost forbids proxy URLs. </b>
<p>
<li>'<strong><code>last|L</code></strong>' (<b>l</b>ast rule)<br>
Stop the rewriting process here and
***************
*** 899,905 ****
of different modules which contain URL-to-filename translators</b>. The
typical example is the use of <tt>mod_alias</tt> and
<tt>mod_rewrite</tt>..
-
<p>
<table width=70% border=2 bgcolor="#c0c0e0" cellspacing=0 cellpadding=10>
<tr><td>
--- 953,958 ----
***************
*** 921,926 ****
--- 974,989 ----
a <tt>skip=N</tt> where N is the number of rules in the else-clause.
(This is <b>not</b> the same as the 'chain|C' flag!)
<p>
+ <li>'<strong><code>env|E=</code></strong><i>VAR</i>:<i>VAL</i>' (set <b>e</b>nvironment variable)<br>
+ This forces an environment variable named <i>VAR</i> to be set to the value
+ <i>VAL</i>, where <i>VAL</i> can contain regexp backreferences <tt>$N</tt>
+ which will be expanded. You can use this flag more than once to set more
+ than one variable. The variables can be later dereferenced at a lot of
+ situations, but the usual location will be from within XSSI (via
+ <tt><!--#echo var="VAR"--></tt>) or CGI (e.g. <tt>$ENV{'VAR'}</tt>).
+ But additionally you can also dereference it in a following RewriteCond
+ pattern via <tt>%{ENV:VAR}</tt>. Use this to strip but remember
+ information from URLs.
</ul>
<p>
***************
*** 1087,1089 ****
--- 1150,1153 ----
<!--#include virtual="footer.html" -->
</BODY>
</HTML>
+ <!--/%hypertext -->