avoid.xml revision cd16bb1940b0d07b466ac46b9be3f1bba7ce62ff
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.
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<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>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<note type="warning">This document is a work in progress.</note>
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>
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="advanced.html">Advanced techniques and tricks</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>
d8be577d18fda0d6b74a6fe5a5e1c0f0b3bf246clgentis<p>Third-party modules such as <a href="link_needed">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
cd16bb1940b0d07b466ac46b9be3f1bba7ce62ffrbowen<module>mod_proxy</module>. As with any use of <code>mod_rewrite</code>,
cd16bb1940b0d07b466ac46b9be3f1bba7ce62ffrbowenyou want to ask yourself whether it's really the best solution.</p>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<section id="setenv"><title>Environment Variable Testing</title>
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowen<note type="note">Parts of this section are applicable only to Apache HTTP
9e4fd920b1e57cb1a7113cde0959b9ff1689d1dfrbowenServer 2.3 and later.</note>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen</manualpage>