avoid.xml revision 860b4efe27e7c1c9a2bf5c872b29c90f76849b51
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
6896b3498e144d33f374efe93e6bab2669af535fnd<!-- $LastChangedRevision$ -->
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen Licensed to the Apache Software Foundation (ASF) under one or more
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen contributor license agreements. See the NOTICE file distributed with
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen this work for additional information regarding copyright ownership.
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen The ASF licenses this file to You under the Apache License, Version 2.0
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen (the "License"); you may not use this file except in compliance with
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen the License. You may obtain a copy of the License at
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen Unless required by applicable law or agreed to in writing, software
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen distributed under the License is distributed on an "AS IS" BASIS,
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen See the License for the specific language governing permissions and
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen limitations under the License.
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim<p>This document supplements the <module>mod_rewrite</module>
2bb0656f94af82b1ff5e3e77a99b4427c52e4953rbowen<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenperhaps one of the most important concepts about mod_rewrite - namely,
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenwhen to avoid using it.</p>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<p>mod_rewrite should be considered a last resort, when other
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenalternatives are found wanting. Using it when there are simpler
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenalternatives leads to configurations which are confusing, fragile, and
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenhard to maintain. Understanding what other alternatives are available is
4a1711ab536d965e63d7be80e29f912287fe70b2rbowena very important step towards mod_rewrite mastery.</p>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<p>Note that many of these examples won't work unchanged in your
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenparticular server configuration, so it's important that you understand
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenthem, rather than merely cutting and pasting the examples into your
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenconfiguration.</p>
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<p>The most common situation in which <module>mod_rewrite</module> is
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenthe right tool is when the very best solution requires access to the
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenserver configuration files, and you don't have that access. Some
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenconfiguration directives are only available in the server configuration
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenfile. So if you are in a hosting situation where you only have .htaccess
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenfiles to work with, you may need to resort to
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="access.html">Controlling access</a></seealso>
10705fbc225dcf590c9ba24a4f04de221358060arbowen<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
3723c5ef4beec0403b4daa6c64fc0a8f53541018rbowen<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
53abc235688d883cfa15cdfec354ba03128f357arbowen<seealso><a href="advanced.html">Advanced techniques</a></seealso>
10705fbc225dcf590c9ba24a4f04de221358060arbowen<!--<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>-->
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenmodule="mod_alias">Redirect</directive> and <directive
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenmodule="mod_alias">RedirectMatch</directive> directives, which provide a
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenmeans to redirect one URL to another. This kind of simple redirection of
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenone URL, or a class of URLs, to somewhere else, should be accomplished
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenusing these directives rather than <directive
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenmodule="mod_rewrite">RewriteRule</directive>. <code>RedirectMatch</code>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenallows you to include a regular expression in your redirection criteria,
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenproviding many of the benefits of using <code>RewriteRule</code>.</p>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<p>A common use for <code>RewriteRule</code> is to redirect an entire
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenclass of URLs. For example, all URLs in the <code>/one</code> directory
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenmust be redirected to <code>http://one.example.com/</code>, or perhaps
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<p>These situations are better handled by the <code>Redirect</code>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowendirective. Remember that <code>Redirect</code> preserves path
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrboweninformation. That is to say, a redirect for a URL <code>/one</code> will
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenalso redirect all URLs under that, such as <code>/one/two.html</code>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<code>http://one.example.com</code>, do the following:</p>
365711300b7310a1efed8aa9f01492086882ba7crbowen<p>To redirect <code>http</code> URLs to <code>https</code>, do the
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenfollowing:</p>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<VirtualHost *:80>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen</VirtualHost >
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<VirtualHost *:443>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen# ... SSL configuration goes here<br />
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen</VirtualHost >
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<p>The use of <code>RewriteRule</code> to perform this task may be
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenappropriate if there are other <code>RewriteRule</code> directives in
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenthe same scope. This is because, when there are <code>Redirect</code>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenand <code>RewriteRule</code> directives in the same scope, the
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<code>RewriteRule</code> directives will run first, regardless of the
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenorder of appearance in the configuration file.</p>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<p>In the case of the <em>http-to-https</em> redirection, the use of
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<code>RewriteRule</code> would be appropriate if you don't have access
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowento the main server configuration file, and are obliged to perform this
817e2217798a69597ab1da450376abac7b239814rbowen<p>The <directive module="mod_alias">Alias</directive> directive
817e2217798a69597ab1da450376abac7b239814rbowenprovides mapping from a URI to a directory - usually a directory outside
817e2217798a69597ab1da450376abac7b239814rbowenof your <directive module="core">DocumentRoot</directive>. Although it
cd16bb1940b0d07b466ac46b9be3f1bba7ce62ffrbowenis possible to perform this mapping with <code>mod_rewrite</code>,
817e2217798a69597ab1da450376abac7b239814rbowen<code>Alias</code> is the preferred method, for reasons of simplicity
817e2217798a69597ab1da450376abac7b239814rbowenand performance.</p>
817e2217798a69597ab1da450376abac7b239814rbowenThe use of <code>mod_rewrite</code> to perform this mapping may be
817e2217798a69597ab1da450376abac7b239814rbowenappropriate when you do not have access to the server configuration
817e2217798a69597ab1da450376abac7b239814rbowenfiles. Alias may only be used in server or virtualhost context, and not
817e2217798a69597ab1da450376abac7b239814rbowen<p>Symbolic links would be another way to accomplish the same thing, if
817e2217798a69597ab1da450376abac7b239814rbowenyou have <code>Options FollowSymLinks</code> enabled on your
365711300b7310a1efed8aa9f01492086882ba7crbowen<p>Although it is possible to handle <a href="vhosts.html">virtual hosts
1570744e45f66e479e87117f23048c44712a31bcrbowenwith mod_rewrite</a>, it is seldom the right way. Creating individual
1570744e45f66e479e87117f23048c44712a31bcrbowen<VirtualHost> blocks is almost always the right way to go. In the
1570744e45f66e479e87117f23048c44712a31bcrbowenevent that you have an enormous number of virtual hosts, consider using
d8be577d18fda0d6b74a6fe5a5e1c0f0b3bf246clgentis<module>mod_vhost_alias</module> to create these hosts automatically.</p>
2852e66e1a44feed2919689711060b8fe720a1fbrbowen<p>Third-party modules such as <a href="http://www.cri.ensmp.fr/~coelho/mod_macro/">mod_macro</a> are
d8be577d18fda0d6b74a6fe5a5e1c0f0b3bf246clgentisalso useful for creating a large number of virtual hosts dynamically.</p>
1570744e45f66e479e87117f23048c44712a31bcrbowen<p>Using <module>mod_rewrite</module> for vitualhost creation may be
1570744e45f66e479e87117f23048c44712a31bcrbowenappropriate if you are using a hosting service that does not provide
1570744e45f66e479e87117f23048c44712a31bcrbowenyou access to the server configuration files, and you are therefore
1570744e45f66e479e87117f23048c44712a31bcrbowenrestricted to configuration using <code>.htaccess</code> files.</p>
1570744e45f66e479e87117f23048c44712a31bcrbowen<p>See the <a href="vhosts.html">virtual hosts with mod_rewrite</a>
1570744e45f66e479e87117f23048c44712a31bcrbowendocument for more details on how you might accomplish this if it still
1570744e45f66e479e87117f23048c44712a31bcrbowenseems like the right approach.</p>
cd16bb1940b0d07b466ac46b9be3f1bba7ce62ffrbowenhref="flags.html#flag_p">[P]</a> flag to pass rewritten URIs through
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenRewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<p>However, in many cases, when there is no actual pattern matching
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenmeeded, as in the example shown above, the <directive
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenmodule="mod_proxy">ProxyPass</directive> directive is a better choice.
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenThe example here could be rendered as:</p>
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenmodule="mod_rewrite">RewriteRule</directive> or <directive
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenmodule="mod_proxy">ProxyPass</directive>, you'll still need to use the
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<directive module="mod_proxy">ProxyPassReverse</directive> directive to
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowencatch redirects issued from the back-end server:</p>
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenProxyPassReverse /images/ http://imageserver.local/images/
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<p>You may need to use <code>RewriteRule</code> instead when there are
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenother <code>RewriteRule</code>s in effect in the same scope, as a
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<code>RewriteRule</code> will usually take effect before a
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowen<code>ProxyPass</code>, and so may preempt what you're trying to
7ed90ff2ffacbd64549ed58890e0e44dbd2b2a49rbowenaccomplish.</p>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<section id="setenv"><title>Environment Variable Testing</title>
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<p><module>mod_rewrite</module> is frequently used to take a particular
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowenaction based on the presence or absense of a particular environment
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowenvariable or request header. This can be done more efficiently using the
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<directive module="core" type="section">If</directive>.</p>
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<p>Consider, for example, the common scenario where
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<directive>RewriteRule</directive> is used to enforce a canonical
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowenhostname, such as <code>www.example.com</code> instead of
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<code>example.com</code>. This can be done using the <directive
c7f365f090f1a2ddb14059d75e223ecfc4ae0eb4rbowenmodule="core" type="section">If</directive> directive, as shown here:</p>
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<p>This technique can be used to take actions based on any request
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowenheader, response header, or environment variable, replacing
da15e975ccc42c6c1f1d9a9b30d47fa1bd0b6a48rbowen<module>mod_rewrite</module> in many common scenarios.</p>
ee55237b797cb7b343048d38ffd77a7ac4da3f9erbowen<p>See especially the <a href="/expr.html">expression evaluation
ee55237b797cb7b343048d38ffd77a7ac4da3f9erbowendocumentation</a> for a overview of what types of expressions you can
ee55237b797cb7b343048d38ffd77a7ac4da3f9erbowenuse in <If> sections, and in certain other directives.</p>
860b4efe27e7c1c9a2bf5c872b29c90f76849b51jim</manualpage>