avoid.xml revision 3723c5ef4beec0403b4daa6c64fc0a8f53541018
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
817e2217798a69597ab1da450376abac7b239814rbowenis possible to perform this mappint 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
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>