avoid.xml revision 3723c5ef4beec0403b4daa6c64fc0a8f53541018
97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE manualpage SYSTEM "/style/manualpage.dtd">
97a9a944b5887e91042b019776c41d5dd74557aferikabele<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
a945f35eff8b6a88009ce73de6d4c862ce58de3cslive<!-- $LastChangedRevision$ -->
fe64b2ba25510d8c9dba5560a2d537763566cf40nd Licensed to the Apache Software Foundation (ASF) under one or more
fe64b2ba25510d8c9dba5560a2d537763566cf40nd contributor license agreements. See the NOTICE file distributed with
fe64b2ba25510d8c9dba5560a2d537763566cf40nd this work for additional information regarding copyright ownership.
fe64b2ba25510d8c9dba5560a2d537763566cf40nd The ASF licenses this file to You under the Apache License, Version 2.0
d29d9ab4614ff992b0e8de6e2b88d52b6f1f153erbowen (the "License"); you may not use this file except in compliance with
2e545ce2450a9953665f701bb05350f0d3f26275nd the License. You may obtain a copy of the License at
fe64b2ba25510d8c9dba5560a2d537763566cf40nd Unless required by applicable law or agreed to in writing, software
fe64b2ba25510d8c9dba5560a2d537763566cf40nd distributed under the License is distributed on an "AS IS" BASIS,
af33a4994ae2ff15bc67d19ff1a7feb906745bf8rbowen WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
3f08db06526d6901aa08c110b5bc7dde6bc39905nd See the License for the specific language governing permissions and
fe64b2ba25510d8c9dba5560a2d537763566cf40nd limitations under the License.
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd<p>This document supplements the <module>mod_rewrite</module>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<a href="/mod/mod_rewrite.html">reference documentation</a>. It describes
fe64b2ba25510d8c9dba5560a2d537763566cf40ndperhaps one of the most important concepts about mod_rewrite - namely,
fe64b2ba25510d8c9dba5560a2d537763566cf40ndwhen to avoid using it.</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p>mod_rewrite should be considered a last resort, when other
fe64b2ba25510d8c9dba5560a2d537763566cf40ndalternatives are found wanting. Using it when there are simpler
06ba4a61654b3763ad65f52283832ebf058fdf1cslivealternatives leads to configurations which are confusing, fragile, and
06ba4a61654b3763ad65f52283832ebf058fdf1cslivehard to maintain. Understanding what other alternatives are available is
06ba4a61654b3763ad65f52283832ebf058fdf1cslivea very important step towards mod_rewrite mastery.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>Note that many of these examples won't work unchanged in your
06ba4a61654b3763ad65f52283832ebf058fdf1csliveparticular server configuration, so it's important that you understand
06ba4a61654b3763ad65f52283832ebf058fdf1cslivethem, rather than merely cutting and pasting the examples into your
06ba4a61654b3763ad65f52283832ebf058fdf1csliveconfiguration.</p>
26556019355f6e007335c2d5d57013ac24ebf651nd<note type="warning">This document is a work in progress.</note>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<seealso><a href="remapping.html">Redirection and remapping</a></seealso>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<seealso><a href="access.html">Controlling access</a></seealso>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<seealso><a href="rewritemap.html">Using RewriteMap</a></seealso>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<!--<seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso>-->
fe64b2ba25510d8c9dba5560a2d537763566cf40ndmodule="mod_alias">RedirectMatch</directive> directives, which provide a
fe64b2ba25510d8c9dba5560a2d537763566cf40ndmeans to redirect one URL to another. This kind of simple redirection of
fe64b2ba25510d8c9dba5560a2d537763566cf40ndone URL, or a class of URLs, to somewhere else, should be accomplished
fe64b2ba25510d8c9dba5560a2d537763566cf40ndusing these directives rather than <directive
fe64b2ba25510d8c9dba5560a2d537763566cf40ndmodule="mod_rewrite">RewriteRule</directive>. <code>RedirectMatch</code>
fe64b2ba25510d8c9dba5560a2d537763566cf40ndallows you to include a regular expression in your redirection criteria,
fe64b2ba25510d8c9dba5560a2d537763566cf40ndproviding many of the benefits of using <code>RewriteRule</code>.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>A common use for <code>RewriteRule</code> is to redirect an entire
06ba4a61654b3763ad65f52283832ebf058fdf1csliveclass of URLs. For example, all URLs in the <code>/one</code> directory
06ba4a61654b3763ad65f52283832ebf058fdf1cslivemust be redirected to <code>http://one.example.com/</code>, or perhaps
23255b04d466bf2621c4dd4ae1b025a9c5639e1ahumbedooh<p>These situations are better handled by the <code>Redirect</code>
23255b04d466bf2621c4dd4ae1b025a9c5639e1ahumbedoohdirective. Remember that <code>Redirect</code> preserves path
d43535d2b691837e9c1e2f01e42b76aa0a1ab98frboweninformation. That is to say, a redirect for a URL <code>/one</code> will
d43535d2b691837e9c1e2f01e42b76aa0a1ab98frbowenalso redirect all URLs under that, such as <code>/one/two.html</code>
23255b04d466bf2621c4dd4ae1b025a9c5639e1ahumbedooh<code>http://one.example.com</code>, do the following:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p>To redirect <code>http</code> URLs to <code>https</code>, do the
fe64b2ba25510d8c9dba5560a2d537763566cf40ndfollowing:</p>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<VirtualHost *:80>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd</VirtualHost >
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<VirtualHost *:443>
fe64b2ba25510d8c9dba5560a2d537763566cf40nd# ... SSL configuration goes here<br />
fe64b2ba25510d8c9dba5560a2d537763566cf40nd</VirtualHost >
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<p>The use of <code>RewriteRule</code> to perform this task may be
fe64b2ba25510d8c9dba5560a2d537763566cf40ndappropriate if there are other <code>RewriteRule</code> directives in
fe64b2ba25510d8c9dba5560a2d537763566cf40ndthe same scope. This is because, when there are <code>Redirect</code>
fe64b2ba25510d8c9dba5560a2d537763566cf40ndand <code>RewriteRule</code> directives in the same scope, the
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<code>RewriteRule</code> directives will run first, regardless of the
fe64b2ba25510d8c9dba5560a2d537763566cf40ndorder of appearance in the configuration file.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>In the case of the <em>http-to-https</em> redirection, the use of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<code>RewriteRule</code> would be appropriate if you don't have access
06ba4a61654b3763ad65f52283832ebf058fdf1csliveto the main server configuration file, and are obliged to perform this
20f499565e77defe9dab24dd85c02f38a1175855nd<p>The <directive module="mod_alias">Alias</directive> directive
888e1c11ac3d57919ad538235846188bfbe4fcb1humbedoohprovides mapping from a URI to a directory - usually a directory outside
fe64b2ba25510d8c9dba5560a2d537763566cf40ndof your <directive module="core">DocumentRoot</directive>. Although it
fe64b2ba25510d8c9dba5560a2d537763566cf40ndis possible to perform this mappint with <code>mod_rewrite</code>,
fe64b2ba25510d8c9dba5560a2d537763566cf40nd<code>Alias</code> is the preferred method, for reasons of simplicity
3b3b7fc78d1f5bfc2769903375050048ff41ff26ndand performance.</p>
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohThe use of <code>mod_rewrite</code> to perform this mapping may be
0d0ba3a410038e179b695446bb149cce6264e0abndappropriate when you do not have access to the server configuration
cc7e1025de9ac63bd4db6fe7f71c158b2cf09fe4humbedoohfiles. Alias may only be used in server or virtualhost context, and not
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>Symbolic links would be another way to accomplish the same thing, if
ac082aefa89416cbdc9a1836eaf3bed9698201c8humbedoohyou have <code>Options FollowSymLinks</code> enabled on your
0d0ba3a410038e179b695446bb149cce6264e0abndserver.</p>
727872d18412fc021f03969b8641810d8896820bhumbedooh<section id="vhosts"><title>Virtual Hosting</title>
0d0ba3a410038e179b695446bb149cce6264e0abnd<p>Although it is possible to handle <a href="vhosts.html">virtual hosts
7fec19672a491661b2fe4b29f685bc7f4efa64d4nd<section id="setenv"><title>Environment Variable Testing</title>