<table class="directive">
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
- <em>Pattern</em> <em>Substitution</em></code></td></tr>
+ <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
-<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
</table>
<p>The <code class="directive">RewriteRule</code> directive is the real
rewriting workhorse. The directive can occur more than once,
subsequent patterns are applied to the output of the last matched
RewriteRule.</p>
+<div class="note"><h3>What is matched?</h3>
+ <p>The <em>Pattern</em> will initially be matched against the part of the
+ URL after the hostname and port, and before the query string. If you wish
+ to match against the hostname, port, or query string, use a
+ <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
+ <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
+ <code>%{QUERY_STRING}</code> variables respectively.</p>
+</div>
+
+
+
<p>Some hints on the syntax of <a class="glossarylink" href="../glossary.html#regex" title="see glossary">regular
expressions</a>:</p>
</pre></div>
<p>For more information about regular expressions, have a look at the
- perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+ perl regular expression manpage ("<a href="http://www.perldoc.com/perlre.html">perldoc
perlre</a>"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:</p>
cannot use <code>$N</code> in the substitution string!
</div>
- <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
- rewrite rule is the string which is substituted for (or
- replaces) the original URL which <em>Pattern</em>
- matched. In addition to plain text, it can include</p>
+ <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+ rewrite rule is the string that replaces the original URL-path that
+ was matched by <em>Pattern</em>. The <em>Substitution</em> may
+ be a:</p>
+
+ <dl>
+
+ <dt>file-system path</dt>
+
+ <dd>Designates the location on the file-system of the resource
+ to be delivered to the client.</dd>
+
+ <dt>URL-path</dt>
+
+ <dd>A <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
+ resource to be served. Note that <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
+ tries to guess whether you have specified a file-system path
+ or a URL-path by checking to see if the first segement of the
+ path exists at the root of the file-system. For example, if
+ you specify a <em>Substitution</em> string of
+ <code>/www/file.html</code>, then this will be treated as a
+ URL-path <em>unless</em> a directory named <code>www</code>
+ exists at the root or your file-system, in which case it will
+ be treated as a file-system path. If you wish other
+ URL-mapping directives (such as <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
+ resulting URL-path, use the <code>[PT]</code> flag as
+ described below.</dd>
+
+ <dt>Absolute URL</dt>
+
+ <dd>If an absolute URL is specified,
+ <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
+ hostname matches the current host. If it does, the scheme and
+ hostname are stripped out and the resulting path is treated as
+ a URL-path. Otherwise, an external redirect is performed for
+ the given URL. To force an external redirect back to the
+ current host, see the <code>[R]</code> flag below.</dd>
+
+ <dt><code>-</code> (dash)</dt>
+
+ <dd>A dash indicates that no substitution should be performed
+ (the existing path is passed through untouched). This is used
+ when a flag (see below) needs to be applied without changing
+ the path.</dd>
+
+ </dl>
+
+ <p>In addition to plain text, the <em>Substition</em> string can include</p>
<ol>
<li>back-references (<code>$N</code>) to the RewriteRule
<li><a href="#mapfunc">mapping-function</a> calls
(<code>${mapname:key|default}</code>)</li>
</ol>
+
<p>Back-references are identifiers of the form
<code>$</code><strong>N</strong>
(<strong>N</strong>=0..9), which will be replaced
or it is explicitly terminated by a
<code><strong>L</strong></code> flag.</p>
- <p>There is a special substitution string named
- '<code>-</code>' which means: <strong>NO
- substitution</strong>! This is useful in providing
- rewriting rules which <strong>only</strong> match
- URLs but do not substitute anything for them. It is commonly used
- in conjunction with the <strong>C</strong> (chain) flag, in order
- to apply more than one pattern before substitution occurs.</p>
+ <div class="note"><h3>Modifying the Query String</h3>
+ <p>By default, the query string is passed through unchanged. You
+ can, however, create URLs in the substitution string containing
+ a query string part. Simply use a question mark inside the
+ substitution string to indicate that the following text should
+ be re-injected into the query string. When you want to erase an
+ existing query string, end the substitution string with just a
+ question mark. To combine new and old query strings, use the
+ <code>[QSA]</code> flag.</p>
+ </div>
- <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">flags</a> for <em>Substitution</em> by
+ <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
appending <strong><code>[</code><em>flags</em><code>]</code></strong>
as the third argument to the <code>RewriteRule</code>
- directive. <em>Flags</em> is a comma-separated list of any of the
- following flags: </p>
+ directive. <em>Flags</em> is a comma-separated list, surround by square
+ brackets, of any of the following flags: </p>
- <ul>
- <li>'<strong><code>chain|C</code></strong>'
- (<strong>c</strong>hained with next rule)<br />
+ <dl>
+ <dt>'<code>chain|C</code>'
+ (chained with next rule)</dt><dd>
This flag chains the current rule with the next rule
(which itself can be chained with the following rule,
and so on). This has the following effect: if a rule
rules are skipped. For instance, it can be used to remove the
``<code>.www</code>'' part, inside a per-directory rule set,
when you let an external redirect happen (where the
- ``<code>.www</code>'' part should not occur!).</li>
+ ``<code>.www</code>'' part should not occur!).</dd>
- <li>
- '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
- (set <strong>co</strong>okie)<br />
+ <dt>
+ '<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
+ (set cookie)</dt><dd>
This sets a cookie in the client's browser. The cookie's name
is specified by <em>NAME</em> and the value is
<em>VAL</em>. The <em>domain</em> field is the domain of the
cookie, such as '.apache.org', the optional <em>lifetime</em>
is the lifetime of the cookie in minutes, and the optional
- <em>path</em> is the path of the cookie</li>
+ <em>path</em> is the path of the cookie</dd>
- <li>
- '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
- (set <strong>e</strong>nvironment variable)<br />
+ <dt>
+ '<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
+ (set environment variable)</dt><dd>
This forces an environment variable named <em>VAR</em> to
be set to the value <em>VAL</em>, where <em>VAL</em> can
contain regexp backreferences (<code>$N</code> and
var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>).
You can also dereference the variable in a later RewriteCond pattern, using
<code>%{ENV:VAR}</code>. Use this to strip
- information from URLs, while maintaining a record of that information.</li>
+ information from URLs, while maintaining a record of that information.</dd>
- <li>'<strong><code>forbidden|F</code></strong>' (force URL
- to be <strong>f</strong>orbidden)<br />
+ <dt>'<code>forbidden|F</code>' (force URL
+ to be forbidden)</dt><dd>
This forces the current URL to be forbidden - it immediately
sends back a HTTP response of 403 (FORBIDDEN).
Use this flag in conjunction with
appropriate RewriteConds to conditionally block some
- URLs.</li>
+ URLs.</dd>
- <li>'<strong><code>gone|G</code></strong>' (force URL to be
- <strong>g</strong>one)<br />
+ <dt>'<code>gone|G</code>' (force URL to be
+ gone)</dt><dd>
This forces the current URL to be gone - it
immediately sends back a HTTP response of 410 (GONE). Use
- this flag to mark pages which no longer exist as gone.</li>
+ this flag to mark pages which no longer exist as gone.</dd>
- <li>
- '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'
- (force Content <strong>h</strong>andler)<br />
+ <dt>
+ '<code>handler|H</code>=<em>Content-handler</em>'
+ (force Content handler)</dt><dd>
Force the Content-handler of the target file to be
<em>Content-handler</em>. For instance, this can be used to
simulate the <code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> directive
<code class="directive"><a href="../mod/mod_alias.html#scriptalias">ScriptAlias</a></code>,
which internally forces all files
inside the mapped directory to have a handler of
- ``<code>cgi-script</code>''.</li>
-
- <li>'<strong><code>last|L</code></strong>'
- (<strong>l</strong>ast rule)<br />
- Stop the rewriting process here and don't apply any more
- rewrite rules. This corresponds to the Perl
- <code>last</code> command or the <code>break</code> command
- in C. Use this flag to prevent the currently
- rewritten URL from being rewritten further by following
- rules. For example, use it to rewrite the root-path URL
- ('<code>/</code>') to a real one, <em>e.g.</em>,
- '<code>/e/www/</code>'.</li>
-
- <li>'<strong><code>next|N</code></strong>'
- (<strong>n</strong>ext round)<br />
+ ``<code>cgi-script</code>''.</dd>
+
+ <dt>'<code>last|L</code>'
+ (last rule)</dt><dd> Stop the rewriting process
+ here and don't apply any more rewrite rules. This corresponds
+ to the Perl <code>last</code> command or the
+ <code>break</code> command in C. Use this flag to prevent the
+ currently rewritten URL from being rewritten further by
+ following rules. Remember, however, that if the
+ <code class="directive">RewriteRule</code> generates an internal
+ redirect (which frequently occurs when rewriting in a
+ per-directory context), this will reinject the request and
+ will cause processing to be repeated starting from the first
+ <code class="directive">RewriteRule</code>.</dd>
+
+ <dt>'<code>next|N</code>'
+ (next round)</dt><dd>
Re-run the rewriting process (starting again with the
first rewriting rule). This time, the URL to match is no longer
the original URL, but rather the URL returned by the last rewriting rule.
This corresponds to the Perl <code>next</code> command or
the <code>continue</code> command in C. Use
this flag to restart the rewriting process -
- to immediately go to the top of the loop.<br />
+ to immediately go to the top of the loop.
<strong>Be careful not to create an infinite
- loop!</strong></li>
+ loop!</strong></dd>
- <li>'<strong><code>nocase|NC</code></strong>'
- (<strong>n</strong>o <strong>c</strong>ase)<br />
+ <dt>'<code>nocase|NC</code>'
+ (no case)</dt><dd>
This makes the <em>Pattern</em> case-insensitive,
ignoring difference between 'A-Z' and
'a-z' when <em>Pattern</em> is matched against the current
- URL.</li>
+ URL.</dd>
- <li>
- '<strong><code>noescape|NE</code></strong>'
- (<strong>n</strong>o URI <strong>e</strong>scaping of
- output)<br />
+ <dt>
+ '<code>noescape|NE</code>'
+ (no URI escaping of
+ output)</dt><dd>
This flag prevents mod_rewrite from applying the usual URI
escaping rules to the result of a rewrite. Ordinarily,
special characters (such as '%', '$', ';', and so on)
</code></p></div>
which would turn '<code>/foo/zed</code>' into a safe
request for '<code>/bar?arg=P1=zed</code>'.
- </li>
+ </dd>
- <li>
- '<strong><code>nosubreq|NS</code></strong>'
- (<strong>n</strong>ot for internal
- <strong>s</strong>ub-requests)<br />
- This flag forces the rewriting engine to skip a
+ <dt>
+ '<code>nosubreq|NS</code>'
+ (not for internal
+ sub-requests)</dt><dd>
+ <p>This flag forces the rewriting engine to skip a
rewriting rule if the current request is an internal
sub-request. For instance, sub-requests occur internally
in Apache when <code class="module"><a href="../mod/mod_include.html">mod_include</a></code> tries to find out
(<code>index.xxx</code> files). On sub-requests it is not
always useful, and can even cause errors, if
the complete set of rules are applied. Use this flag to
- exclude some rules.<br />
- To decide whether or not to use this rule: if you
+ exclude some 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.
- </li>
+ sub-requests. In these cases, use this flag.</p>
+ </dd>
- <li>
- '<strong><code>proxy|P</code></strong>' (force
- <strong>p</strong>roxy)<br />
+ <dt>
+ '<code>proxy|P</code>' (force
+ proxy)</dt><dd>
This flag forces the substitution part to be internally
sent as a proxy request and immediately (rewrite
processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
<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>
- </li>
+ </dd>
- <li>
- '<strong><code>passthrough|PT</code></strong>'
- (<strong>p</strong>ass <strong>t</strong>hrough to next
- handler)<br />
+ <dt>
+ '<code>passthrough|PT</code>'
+ (pass through to next
+ handler)</dt><dd>
This flag forces the rewrite engine to set the
<code>uri</code> field of the internal
<code>request_rec</code> structure to the value of the
<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>
- </li>
+ </dd>
- <li>'<strong><code>qsappend|QSA</code></strong>'
- (<strong>q</strong>uery <strong>s</strong>tring
- <strong>a</strong>ppend)<br />
+ <dt>'<code>qsappend|QSA</code>'
+ (query string
+ append)</dt><dd>
This flag forces the rewrite engine to append a query
string part of the substitution string to the existing string,
instead of replacing it. Use this when you want to add more
- data to the query string via a rewrite rule.</li>
+ data to the query string via a rewrite rule.</dd>
- <li>'<strong><code>redirect|R</code>
- [=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
- Prefix <em>Substitution</em> with
+ <dt>'<code>redirect|R</code>
+ [=<em>code</em>]' (force <a id="redirect" name="redirect">redirect</a>)</dt><dd>
+ <p>Prefix <em>Substitution</em> with
<code>http://thishost[:thisport]/</code> (which makes the
new URL a URI) to force a external redirection. If no
<em>code</em> is given, a HTTP response of 302 (MOVED
- TEMPORARILY) will be returned. If you want to use other response
- codes in the range 300-400, simply specify the appropriate number
- or use one of the following symbolic names:
- <code>temp</code> (default), <code>permanent</code>,
- <code>seeother</code>. Use this for rules to
- canonicalize the URL and return it to the client - to
- translate ``<code>/~</code>'' into
- ``<code>/u/</code>'', or to always append a slash to
- <code>/u/</code><em>user</em>, etc.<br />
- <strong>Note:</strong> When you use this flag, make
- sure that the substitution field is a valid URL! Otherwise,
- you will be redirecting to an invalid location. Remember
- that this flag on its own will only prepend
- <code>http://thishost[:thisport]/</code> to the URL, and rewriting
- will continue. Usually, you will want to stop rewriting at this point,
- and redirect immediately. To stop rewriting, you should add
- the 'L' flag.
- </li>
-
- <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
- (<strong>s</strong>kip next rule(s))<br />
+ TEMPORARILY) will be returned. If you want to use other
+ response codes, simply specify the appropriate number or use
+ one of the following symbolic names: <code>temp</code>
+ (default), <code>permanent</code>,
+ <code>seeother</code>. Use this for rules to canonicalize
+ the URL and return it to the client - to translate
+ ``<code>/~</code>'' into ``<code>/u/</code>'', or to always
+ append a slash to <code>/u/</code><em>user</em>, etc.<br />
+ <strong>Note:</strong> When you use this flag, make sure
+ that the substitution field is a valid URL! Otherwise, you
+ will be redirecting to an invalid location. Remember that
+ this flag on its own will only prepend
+ <code>http://thishost[:thisport]/</code> to the URL, and
+ rewriting will continue. Usually, you will want to stop
+ rewriting at this point, and redirect immediately. To stop
+ rewriting, you should add the 'L' flag.</p>
+ <p>While this is typically used for redirects, any valid status
+ code can be given here. If the status code is outside the redirect
+ range (300-399), then the <em>Substitution</em> string is dropped
+ and rewriting is stopped as if the <code>L</code> flag was
+ used.</p>
+ </dd>
+
+ <dt>'<code>skip|S</code>=<em>num</em>'
+ (skip next rule(s))</dt><dd>
This flag forces the rewriting engine to skip the next
<em>num</em> rules in sequence, if the current rule
matches. 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. (This is <strong>not</strong> the same as the
- 'chain|C' flag!)</li>
+ 'chain|C' flag!)</dd>
- <li>
- '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
- (force MIME <strong>t</strong>ype)<br />
+ <dt>
+ '<code>type|T</code>=<em>MIME-type</em>'
+ (force MIME type)</dt><dd>
Force the <a class="glossarylink" href="../glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file to be
<em>MIME-type</em>. This can be used to
set up the content-type based on some conditions.
<div class="example"><p><code>
RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
</code></p></div>
- </li>
- </ul>
+ </dd>
+ </dl>
<div class="note"><h3>Per-directory Rewrites</h3>
<p>Although rewrite rules are syntactically permitted in <code class="directive"><a href="../mod/core.html#location"><Location></a></code> sections, this
should never be necessary and is unsupported.</p>
-</div>
-
-<div class="note"><h3>Note: Substitution of Absolute URLs</h3>
- <p>
- When you prefix a substitution field with
- <code>http://thishost[:thisport]</code>, <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> will automatically strip that
- out. This auto-reduction on URLs with an implicit
- external redirect is most useful in
- combination with a mapping-function which generates the
- hostname part.</p>
-
- <p><strong>Remember:</strong> An unconditional external
- redirect to your own server will not work with the prefix
- <code>http://thishost</code> because of this feature. To
- achieve such a self-redirect, you have to use the
- <strong>R</strong>-flag.</p>
-</div>
-
-<div class="note"><h3>What is matched?</h3>
- <p>The <em>Pattern</em> will initially be matched against the part of the
- URL after the hostname and port, and before the query string. If you wish
- to match against the hostname, port, or query string, use a
- <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
- <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
- <code>%{QUERY_STRING}</code> variables respectively.</p>
- <p>You can, however, create URLs in the substitution string containing a
- query string part. Simply use a question mark inside the substitution
- string, to indicate that the following text should be re-injected into the
- query string. When you want to erase an existing query string,
- end the substitution string with just a question mark. To
- combine new and old query strings, use the
- <code>[QSA]</code> flag.</p>
</div>
<p>Here are all possible substitution combinations and their
<name>RewriteRule</name>
<description>Defines rules for the rewriting engine</description>
<syntax>RewriteRule
- <em>Pattern</em> <em>Substitution</em></syntax>
+ <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</syntax>
<contextlist><context>server config</context><context>virtual host</context>
<context>directory</context><context>.htaccess</context></contextlist>
<override>FileInfo</override>
-<compatibility>The cookie-flag is available in Apache 2.0.40 and later.</compatibility>
<usage>
<p>The <directive>RewriteRule</directive> directive is the real
subsequent patterns are applied to the output of the last matched
RewriteRule.</p>
+<note><title>What is matched?</title>
+ <p>The <em>Pattern</em> will initially be matched against the part of the
+ URL after the hostname and port, and before the query string. If you wish
+ to match against the hostname, port, or query string, use a
+ <directive module="mod_rewrite">RewriteCond</directive> with the
+ <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
+ <code>%{QUERY_STRING}</code> variables respectively.</p>
+</note>
+
+
+
<p>Some hints on the syntax of <glossary ref="regex">regular
expressions</glossary>:</p>
<p>For more information about regular expressions, have a look at the
perl regular expression manpage ("<a
- href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
+ href="http://www.perldoc.com/perlre.html">perldoc
perlre</a>"). If you are interested in more detailed
information about regular expressions and their variants
(POSIX regex etc.) the following book is dedicated to this topic:</p>
cannot use <code>$N</code> in the substitution string!
</note>
- <p>The <a id="rhs" name="rhs"><em>substitution</em></a> of a
- rewrite rule is the string which is substituted for (or
- replaces) the original URL which <em>Pattern</em>
- matched. In addition to plain text, it can include</p>
+ <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
+ rewrite rule is the string that replaces the original URL-path that
+ was matched by <em>Pattern</em>. The <em>Substitution</em> may
+ be a:</p>
+
+ <dl>
+
+ <dt>file-system path</dt>
+
+ <dd>Designates the location on the file-system of the resource
+ to be delivered to the client.</dd>
+
+ <dt>URL-path</dt>
+
+ <dd>A <directive
+ module="core">DocumentRoot</directive>-relative path to the
+ resource to be served. Note that <module>mod_rewrite</module>
+ tries to guess whether you have specified a file-system path
+ or a URL-path by checking to see if the first segement of the
+ path exists at the root of the file-system. For example, if
+ you specify a <em>Substitution</em> string of
+ <code>/www/file.html</code>, then this will be treated as a
+ URL-path <em>unless</em> a directory named <code>www</code>
+ exists at the root or your file-system, in which case it will
+ be treated as a file-system path. If you wish other
+ URL-mapping directives (such as <directive
+ module="mod_alias">Alias</directive>) to be applied to the
+ resulting URL-path, use the <code>[PT]</code> flag as
+ described below.</dd>
+
+ <dt>Absolute URL</dt>
+
+ <dd>If an absolute URL is specified,
+ <module>mod_rewrite</module> checks to see whether the
+ hostname matches the current host. If it does, the scheme and
+ hostname are stripped out and the resulting path is treated as
+ a URL-path. Otherwise, an external redirect is performed for
+ the given URL. To force an external redirect back to the
+ current host, see the <code>[R]</code> flag below.</dd>
+
+ <dt><code>-</code> (dash)</dt>
+
+ <dd>A dash indicates that no substitution should be performed
+ (the existing path is passed through untouched). This is used
+ when a flag (see below) needs to be applied without changing
+ the path.</dd>
+
+ </dl>
+
+ <p>In addition to plain text, the <em>Substition</em> string can include</p>
<ol>
<li>back-references (<code>$N</code>) to the RewriteRule
<li><a href="#mapfunc">mapping-function</a> calls
(<code>${mapname:key|default}</code>)</li>
</ol>
+
<p>Back-references are identifiers of the form
<code>$</code><strong>N</strong>
(<strong>N</strong>=0..9), which will be replaced
or it is explicitly terminated by a
<code><strong>L</strong></code> flag.</p>
- <p>There is a special substitution string named
- '<code>-</code>' which means: <strong>NO
- substitution</strong>! This is useful in providing
- rewriting rules which <strong>only</strong> match
- URLs but do not substitute anything for them. It is commonly used
- in conjunction with the <strong>C</strong> (chain) flag, in order
- to apply more than one pattern before substitution occurs.</p>
+ <note><title>Modifying the Query String</title>
+ <p>By default, the query string is passed through unchanged. You
+ can, however, create URLs in the substitution string containing
+ a query string part. Simply use a question mark inside the
+ substitution string to indicate that the following text should
+ be re-injected into the query string. When you want to erase an
+ existing query string, end the substitution string with just a
+ question mark. To combine new and old query strings, use the
+ <code>[QSA]</code> flag.</p>
+ </note>
<p>Additionally you can set special <a name="rewriteflags"
- id="rewriteflags">flags</a> for <em>Substitution</em> by
+ id="rewriteflags">actions</a> to be performed by
appending <strong><code>[</code><em>flags</em><code>]</code></strong>
as the third argument to the <code>RewriteRule</code>
- directive. <em>Flags</em> is a comma-separated list of any of the
- following flags: </p>
+ directive. <em>Flags</em> is a comma-separated list, surround by square
+ brackets, of any of the following flags: </p>
- <ul>
- <li>'<strong><code>chain|C</code></strong>'
- (<strong>c</strong>hained with next rule)<br />
+ <dl>
+ <dt>'<code>chain|C</code>'
+ (chained with next rule)</dt><dd>
This flag chains the current rule with the next rule
(which itself can be chained with the following rule,
and so on). This has the following effect: if a rule
rules are skipped. For instance, it can be used to remove the
``<code>.www</code>'' part, inside a per-directory rule set,
when you let an external redirect happen (where the
- ``<code>.www</code>'' part should not occur!).</li>
+ ``<code>.www</code>'' part should not occur!).</dd>
- <li>
- '<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
- (set <strong>co</strong>okie)<br />
+ <dt>
+ '<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
+ (set cookie)</dt><dd>
This sets a cookie in the client's browser. The cookie's name
is specified by <em>NAME</em> and the value is
<em>VAL</em>. The <em>domain</em> field is the domain of the
cookie, such as '.apache.org', the optional <em>lifetime</em>
is the lifetime of the cookie in minutes, and the optional
- <em>path</em> is the path of the cookie</li>
+ <em>path</em> is the path of the cookie</dd>
- <li>
- '<strong><code>env|E=</code></strong><em>VAR</em>:<em>VAL</em>'
- (set <strong>e</strong>nvironment variable)<br />
+ <dt>
+ '<code>env|E=</code><em>VAR</em>:<em>VAL</em>'
+ (set environment variable)</dt><dd>
This forces an environment variable named <em>VAR</em> to
be set to the value <em>VAL</em>, where <em>VAL</em> can
contain regexp backreferences (<code>$N</code> and
var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>).
You can also dereference the variable in a later RewriteCond pattern, using
<code>%{ENV:VAR}</code>. Use this to strip
- information from URLs, while maintaining a record of that information.</li>
+ information from URLs, while maintaining a record of that information.</dd>
- <li>'<strong><code>forbidden|F</code></strong>' (force URL
- to be <strong>f</strong>orbidden)<br />
+ <dt>'<code>forbidden|F</code>' (force URL
+ to be forbidden)</dt><dd>
This forces the current URL to be forbidden - it immediately
sends back a HTTP response of 403 (FORBIDDEN).
Use this flag in conjunction with
appropriate RewriteConds to conditionally block some
- URLs.</li>
+ URLs.</dd>
- <li>'<strong><code>gone|G</code></strong>' (force URL to be
- <strong>g</strong>one)<br />
+ <dt>'<code>gone|G</code>' (force URL to be
+ gone)</dt><dd>
This forces the current URL to be gone - it
immediately sends back a HTTP response of 410 (GONE). Use
- this flag to mark pages which no longer exist as gone.</li>
+ this flag to mark pages which no longer exist as gone.</dd>
- <li>
- '<strong><code>handler|H</code></strong>=<em>Content-handler</em>'
- (force Content <strong>h</strong>andler)<br />
+ <dt>
+ '<code>handler|H</code>=<em>Content-handler</em>'
+ (force Content handler)</dt><dd>
Force the Content-handler of the target file to be
<em>Content-handler</em>. For instance, this can be used to
simulate the <module>mod_alias</module> directive
<directive module="mod_alias">ScriptAlias</directive>,
which internally forces all files
inside the mapped directory to have a handler of
- ``<code>cgi-script</code>''.</li>
-
- <li>'<strong><code>last|L</code></strong>'
- (<strong>l</strong>ast rule)<br />
- Stop the rewriting process here and don't apply any more
- rewrite rules. This corresponds to the Perl
- <code>last</code> command or the <code>break</code> command
- in C. Use this flag to prevent the currently
- rewritten URL from being rewritten further by following
- rules. For example, use it to rewrite the root-path URL
- ('<code>/</code>') to a real one, <em>e.g.</em>,
- '<code>/e/www/</code>'.</li>
-
- <li>'<strong><code>next|N</code></strong>'
- (<strong>n</strong>ext round)<br />
+ ``<code>cgi-script</code>''.</dd>
+
+ <dt>'<code>last|L</code>'
+ (last rule)</dt><dd> Stop the rewriting process
+ here and don't apply any more rewrite rules. This corresponds
+ to the Perl <code>last</code> command or the
+ <code>break</code> command in C. Use this flag to prevent the
+ currently rewritten URL from being rewritten further by
+ following rules. Remember, however, that if the
+ <directive>RewriteRule</directive> generates an internal
+ redirect (which frequently occurs when rewriting in a
+ per-directory context), this will reinject the request and
+ will cause processing to be repeated starting from the first
+ <directive>RewriteRule</directive>.</dd>
+
+ <dt>'<code>next|N</code>'
+ (next round)</dt><dd>
Re-run the rewriting process (starting again with the
first rewriting rule). This time, the URL to match is no longer
the original URL, but rather the URL returned by the last rewriting rule.
This corresponds to the Perl <code>next</code> command or
the <code>continue</code> command in C. Use
this flag to restart the rewriting process -
- to immediately go to the top of the loop.<br />
+ to immediately go to the top of the loop.
<strong>Be careful not to create an infinite
- loop!</strong></li>
+ loop!</strong></dd>
- <li>'<strong><code>nocase|NC</code></strong>'
- (<strong>n</strong>o <strong>c</strong>ase)<br />
+ <dt>'<code>nocase|NC</code>'
+ (no case)</dt><dd>
This makes the <em>Pattern</em> case-insensitive,
ignoring difference between 'A-Z' and
'a-z' when <em>Pattern</em> is matched against the current
- URL.</li>
+ URL.</dd>
- <li>
- '<strong><code>noescape|NE</code></strong>'
- (<strong>n</strong>o URI <strong>e</strong>scaping of
- output)<br />
+ <dt>
+ '<code>noescape|NE</code>'
+ (no URI escaping of
+ output)</dt><dd>
This flag prevents mod_rewrite from applying the usual URI
escaping rules to the result of a rewrite. Ordinarily,
special characters (such as '%', '$', ';', and so on)
</example>
which would turn '<code>/foo/zed</code>' into a safe
request for '<code>/bar?arg=P1=zed</code>'.
- </li>
+ </dd>
- <li>
- '<strong><code>nosubreq|NS</code></strong>'
- (<strong>n</strong>ot for internal
- <strong>s</strong>ub-requests)<br />
- This flag forces the rewriting engine to skip a
+ <dt>
+ '<code>nosubreq|NS</code>'
+ (not for internal
+ sub-requests)</dt><dd>
+ <p>This flag forces the rewriting engine to skip a
rewriting rule if the current request is an internal
sub-request. For instance, sub-requests occur internally
in Apache when <module>mod_include</module> tries to find out
(<code>index.xxx</code> files). On sub-requests it is not
always useful, and can even cause errors, if
the complete set of rules are applied. Use this flag to
- exclude some rules.<br />
- To decide whether or not to use this rule: if you
+ exclude some 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.
- </li>
+ sub-requests. In these cases, use this flag.</p>
+ </dd>
- <li>
- '<strong><code>proxy|P</code></strong>' (force
- <strong>p</strong>roxy)<br />
+ <dt>
+ '<code>proxy|P</code>' (force
+ proxy)</dt><dd>
This flag forces the substitution part to be internally
sent as a proxy request and immediately (rewrite
processing stops here) put through the <a
<p>Note: <module>mod_proxy</module> must be enabled in order
to use this flag.</p>
- </li>
+ </dd>
- <li>
- '<strong><code>passthrough|PT</code></strong>'
- (<strong>p</strong>ass <strong>t</strong>hrough to next
- handler)<br />
+ <dt>
+ '<code>passthrough|PT</code>'
+ (pass through to next
+ handler)</dt><dd>
This flag forces the rewrite engine to set the
<code>uri</code> field of the internal
<code>request_rec</code> structure to the value of the
<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>
- </li>
+ </dd>
- <li>'<strong><code>qsappend|QSA</code></strong>'
- (<strong>q</strong>uery <strong>s</strong>tring
- <strong>a</strong>ppend)<br />
+ <dt>'<code>qsappend|QSA</code>'
+ (query string
+ append)</dt><dd>
This flag forces the rewrite engine to append a query
string part of the substitution string to the existing string,
instead of replacing it. Use this when you want to add more
- data to the query string via a rewrite rule.</li>
+ data to the query string via a rewrite rule.</dd>
- <li>'<strong><code>redirect|R</code>
- [=<em>code</em>]
</strong>' (force <a id="redirect"
- name="redirect"><strong>r</strong>edirect</a>)<br />
- Prefix <em>Substitution</em> with
+ <dt>'<code>redirect|R</code>
+ [=<em>code</em>]' (force <a id="redirect"
+ name="redirect">redirect</a>)</dt><dd>
+ <p>Prefix <em>Substitution</em> with
<code>http://thishost[:thisport]/</code> (which makes the
new URL a URI) to force a external redirection. If no
<em>code</em> is given, a HTTP response of 302 (MOVED
- TEMPORARILY) will be returned. If you want to use other response
- codes in the range 300-400, simply specify the appropriate number
- or use one of the following symbolic names:
- <code>temp</code> (default), <code>permanent</code>,
- <code>seeother</code>. Use this for rules to
- canonicalize the URL and return it to the client - to
- translate ``<code>/~</code>'' into
- ``<code>/u/</code>'', or to always append a slash to
- <code>/u/</code><em>user</em>, etc.<br />
- <strong>Note:</strong> When you use this flag, make
- sure that the substitution field is a valid URL! Otherwise,
- you will be redirecting to an invalid location. Remember
- that this flag on its own will only prepend
- <code>http://thishost[:thisport]/</code> to the URL, and rewriting
- will continue. Usually, you will want to stop rewriting at this point,
- and redirect immediately. To stop rewriting, you should add
- the 'L' flag.
- </li>
-
- <li>'<strong><code>skip|S</code></strong>=<em>num</em>'
- (<strong>s</strong>kip next rule(s))<br />
+ TEMPORARILY) will be returned. If you want to use other
+ response codes, simply specify the appropriate number or use
+ one of the following symbolic names: <code>temp</code>
+ (default), <code>permanent</code>,
+ <code>seeother</code>. Use this for rules to canonicalize
+ the URL and return it to the client - to translate
+ ``<code>/~</code>'' into ``<code>/u/</code>'', or to always
+ append a slash to <code>/u/</code><em>user</em>, etc.<br />
+ <strong>Note:</strong> When you use this flag, make sure
+ that the substitution field is a valid URL! Otherwise, you
+ will be redirecting to an invalid location. Remember that
+ this flag on its own will only prepend
+ <code>http://thishost[:thisport]/</code> to the URL, and
+ rewriting will continue. Usually, you will want to stop
+ rewriting at this point, and redirect immediately. To stop
+ rewriting, you should add the 'L' flag.</p>
+ <p>While this is typically used for redirects, any valid status
+ code can be given here. If the status code is outside the redirect
+ range (300-399), then the <em>Substitution</em> string is dropped
+ and rewriting is stopped as if the <code>L</code> flag was
+ used.</p>
+ </dd>
+
+ <dt>'<code>skip|S</code>=<em>num</em>'
+ (skip next rule(s))</dt><dd>
This flag forces the rewriting engine to skip the next
<em>num</em> rules in sequence, if the current rule
matches. 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. (This is <strong>not</strong> the same as the
- 'chain|C' flag!)</li>
+ 'chain|C' flag!)</dd>
- <li>
- '<strong><code>type|T</code></strong>=<em>MIME-type</em>'
- (force MIME <strong>t</strong>ype)<br />
+ <dt>
+ '<code>type|T</code>=<em>MIME-type</em>'
+ (force MIME type)</dt><dd>
Force the <glossary>MIME-type</glossary> of the target file to be
<em>MIME-type</em>. This can be used to
set up the content-type based on some conditions.
<example>
RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
</example>
- </li>
- </ul>
+ </dd>
+ </dl>
<note><title>Per-directory Rewrites</title>
type="section" module="core">Location</directive> sections, this
should never be necessary and is unsupported.</p>
-</note>
-
-<note><title>Note: Substitution of Absolute URLs</title>
- <p>
- When you prefix a substitution field with
- <code>http://thishost[:thisport]</code>, <module
- >mod_rewrite</module> will automatically strip that
- out. This auto-reduction on URLs with an implicit
- external redirect is most useful in
- combination with a mapping-function which generates the
- hostname part.</p>
-
- <p><strong>Remember:</strong> An unconditional external
- redirect to your own server will not work with the prefix
- <code>http://thishost</code> because of this feature. To
- achieve such a self-redirect, you have to use the
- <strong>R</strong>-flag.</p>
-</note>
-
-<note><title>What is matched?</title>
- <p>The <em>Pattern</em> will initially be matched against the part of the
- URL after the hostname and port, and before the query string. If you wish
- to match against the hostname, port, or query string, use a
- <directive module="mod_rewrite">RewriteCond</directive> with the
- <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
- <code>%{QUERY_STRING}</code> variables respectively.</p>
- <p>You can, however, create URLs in the substitution string containing a
- query string part. Simply use a question mark inside the substitution
- string, to indicate that the following text should be re-injected into the
- query string. When you want to erase an existing query string,
- end the substitution string with just a question mark. To
- combine new and old query strings, use the
- <code>[QSA]</code> flag.</p>
</note>
<p>Here are all possible substitution combinations and their
projects / thirdparty / apache / httpd.git / commitdiff
