granicus.if.org Git - apache/blob - docs/manual/rewrite/avoid.html.en

   1 <?xml version="1.0" encoding="ISO-8859-1"?>
   2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
   3 <html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
   4         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   5               This file is generated from xml source: DO NOT EDIT
   6         XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
   7       -->
   8 <title>When not to use mod_rewrite - Apache HTTP Server</title>
   9 <link href="../style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
  10 <link href="../style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
  11 <link href="../style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" /><link rel="stylesheet" type="text/css" href="../style/css/prettify.css" />
  12 <script src="../style/scripts/prettify.js" type="text/javascript">
  13 </script>
  14
  15 <link href="../images/favicon.ico" rel="shortcut icon" /></head>
  16 <body id="manual-page"><div id="page-header">
  17 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p>
  18 <p class="apache">Apache HTTP Server Version 2.5</p>
  19 <img alt="" src="../images/feather.gif" /></div>
  20 <div class="up"><a href="./"><img title="&lt;-" alt="&lt;-" src="../images/left.gif" /></a></div>
  21 <div id="path">
  22 <a href="http://www.apache.org/">Apache</a> &gt; <a href="http://httpd.apache.org/">HTTP Server</a> &gt; <a href="http://httpd.apache.org/docs/">Documentation</a> &gt; <a href="../">Version 2.5</a> &gt; <a href="./">Rewrite</a></div><div id="page-content"><div id="preamble"><h1>When not to use mod_rewrite</h1>
  23 <div class="toplang">
  24 <p><span>Available Languages: </span><a href="../en/rewrite/avoid.html" title="English">&nbsp;en&nbsp;</a></p>
  25 </div>
  26
  27
  28 <p>This document supplements the <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>
  29 <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes
  30 perhaps one of the most important concepts about mod_rewrite - namely,
  31 when to avoid using it.</p>
  32
  33 <p>mod_rewrite should be considered a last resort, when other
  34 alternatives are found wanting. Using it when there are simpler
  35 alternatives leads to configurations which are confusing, fragile, and
  36 hard to maintain. Understanding what other alternatives are available is
  37 a very important step towards mod_rewrite mastery.</p>
  38
  39 <p>Note that many of these examples won't work unchanged in your
  40 particular server configuration, so it's important that you understand
  41 them, rather than merely cutting and pasting the examples into your
  42 configuration.</p>
  43
  44 <p>The most common situation in which <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is
  45 the right tool is when the very best solution requires access to the
  46 server configuration files, and you don't have that access. Some
  47 configuration directives are only available in the server configuration
  48 file. So if you are in a hosting situation where you only have .htaccess
  49 files to work with, you may need to resort to
  50 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
  51
  52 </div>
  53 <div id="quickview"><ul id="toc"><li><img alt="" src="../images/down.gif" /> <a href="#redirect">Simple Redirection</a></li>
  54 <li><img alt="" src="../images/down.gif" /> <a href="#alias">URL Aliasing</a></li>
  55 <li><img alt="" src="../images/down.gif" /> <a href="#vhosts">Virtual Hosting</a></li>
  56 <li><img alt="" src="../images/down.gif" /> <a href="#proxy">Simple Proxying</a></li>
  57 <li><img alt="" src="../images/down.gif" /> <a href="#setenv">Environment Variable Testing</a></li>
  58 </ul><h3>See also</h3><ul class="seealso"><li><a href="../mod/mod_rewrite.html">Module documentation</a></li><li><a href="intro.html">mod_rewrite introduction</a></li><li><a href="remapping.html">Redirection and remapping</a></li><li><a href="access.html">Controlling access</a></li><li><a href="vhosts.html">Virtual hosts</a></li><li><a href="proxy.html">Proxying</a></li><li><a href="rewritemap.html">Using RewriteMap</a></li><li><a href="advanced.html">Advanced techniques</a></li></ul><ul class="seealso"><li><a href="#comments_section">Comments</a></li></ul></div>
  59 <div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
  60 <div class="section">
  61 <h2><a name="redirect" id="redirect">Simple Redirection</a></h2>
  62
  63
  64 <p><code class="module"><a href="../mod/mod_alias.html">mod_alias</a></code> provides the <code class="directive"><a href="../mod/mod_alias.html#redirect">Redirect</a></code> and <code class="directive"><a href="../mod/mod_alias.html#redirectmatch">RedirectMatch</a></code> directives, which provide a
  65 means to redirect one URL to another. This kind of simple redirection of
  66 one URL, or a class of URLs, to somewhere else, should be accomplished
  67 using these directives rather than <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code>. <code>RedirectMatch</code>
  68 allows you to include a regular expression in your redirection criteria,
  69 providing many of the benefits of using <code>RewriteRule</code>.</p>
  70
  71 <p>A common use for <code>RewriteRule</code> is to redirect an entire
  72 class of URLs. For example, all URLs in the <code>/one</code> directory
  73 must be redirected to <code>http://one.example.com/</code>, or perhaps
  74 all <code>http</code> requests must be redirected to
  75 <code>https</code>.</p>
  76
  77 <p>These situations are better handled by the <code>Redirect</code>
  78 directive. Remember that <code>Redirect</code> preserves path
  79 information. That is to say, a redirect for a URL <code>/one</code> will
  80 also redirect all URLs under that, such as <code>/one/two.html</code>
  81 and <code>/one/three/four.html</code>.</p>
  82
  83 <p>To redirect URLs under <code>/one</code> to
  84 <code>http://one.example.com</code>, do the following:</p>
  85
  86 <pre class="prettyprint lang-config">Redirect /one/ http://one.example.com/</pre>
  87
  88
  89 <p>To redirect <code>http</code> URLs to <code>https</code>, do the
  90 following:</p>
  91
  92 <pre class="prettyprint lang-config">
  93 &lt;VirtualHost *:80&gt;
  94     ServerName www.example.com
  95     Redirect / https://www.example.com/
  96 &lt;/VirtualHost &gt;
  97
  98 &lt;VirtualHost *:443&gt;
  99     ServerName www.example.com
 100     # ... SSL configuration goes here
 101 &lt;/VirtualHost &gt;
 102 </pre>
 103
 104
 105 <p>The use of <code>RewriteRule</code> to perform this task may be
 106 appropriate if there are other <code>RewriteRule</code> directives in
 107 the same scope. This is because, when there are <code>Redirect</code>
 108 and <code>RewriteRule</code> directives in the same scope, the
 109 <code>RewriteRule</code> directives will run first, regardless of the
 110 order of appearance in the configuration file.</p>
 111
 112 <p>In the case of the <em>http-to-https</em> redirection, the use of
 113 <code>RewriteRule</code> would be appropriate if you don't have access
 114 to the main server configuration file, and are obliged to perform this
 115 task in a <code>.htaccess</code> file instead.</p>
 116
 117 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 118 <div class="section">
 119 <h2><a name="alias" id="alias">URL Aliasing</a></h2>
 120 <p>The <code class="directive"><a href="../mod/mod_alias.html#alias">Alias</a></code> directive
 121 provides mapping from a URI to a directory - usually a directory outside
 122 of your <code class="directive"><a href="../mod/core.html#documentroot">DocumentRoot</a></code>. Although it
 123 is possible to perform this mapping with <code>mod_rewrite</code>,
 124 <code>Alias</code> is the preferred method, for reasons of simplicity
 125 and performance.</p>
 126
 127 <div class="example"><h3>Using Alias</h3><pre class="prettyprint lang-config">Alias /cats /var/www/virtualhosts/felines/htdocs</pre>
 128 </div>
 129
 130 <p>
 131 The use of <code>mod_rewrite</code> to perform this mapping may be
 132 appropriate when you do not have access to the server configuration
 133 files. Alias may only be used in server or virtualhost context, and not
 134 in a <code>.htaccess</code> file.
 135 </p>
 136
 137 <p>Symbolic links would be another way to accomplish the same thing, if
 138 you have <code>Options FollowSymLinks</code> enabled on your
 139 server.</p>
 140 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 141 <div class="section">
 142 <h2><a name="vhosts" id="vhosts">Virtual Hosting</a></h2>
 143 <p>Although it is possible to handle <a href="vhosts.html">virtual hosts
 144 with mod_rewrite</a>, it is seldom the right way. Creating individual
 145 &lt;VirtualHost&gt; blocks is almost always the right way to go. In the
 146 event that you have an enormous number of virtual hosts, consider using
 147 <code class="module"><a href="../mod/mod_vhost_alias.html">mod_vhost_alias</a></code> to create these hosts automatically.</p>
 148
 149 <p>Third-party modules such as <a href="http://www.cri.ensmp.fr/~coelho/mod_macro/">mod_macro</a> are
 150 also useful for creating a large number of virtual hosts dynamically.</p>
 151
 152 <p>Using <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> for vitualhost creation may be
 153 appropriate if you are using a hosting service that does not provide
 154 you access to the server configuration files, and you are therefore
 155 restricted to configuration using <code>.htaccess</code> files.</p>
 156
 157 <p>See the <a href="vhosts.html">virtual hosts with mod_rewrite</a>
 158 document for more details on how you might accomplish this if it still
 159 seems like the right approach.</p>
 160
 161 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 162 <div class="section">
 163 <h2><a name="proxy" id="proxy">Simple Proxying</a></h2>
 164
 165 <p><code>RewriteRule</code> provides the <a href="flags.html#flag_p">[P]</a> flag to pass rewritten URIs through
 166 <code class="module"><a href="../mod/mod_proxy.html">mod_proxy</a></code>.</p>
 167
 168 <pre class="prettyprint lang-config">
 169 RewriteRule ^/?images(.*) http://imageserver.local/images$1 [P]
 170 </pre>
 171
 172
 173 <p>However, in many cases, when there is no actual pattern matching
 174 needed, as in the example shown above, the <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code> directive is a better choice.
 175 The example here could be rendered as:</p>
 176
 177 <pre class="prettyprint lang-config">
 178 ProxyPass /images/ http://imageserver.local/images/
 179 </pre>
 180
 181
 182 <p>Note that whether you use <code class="directive"><a href="../mod/mod_rewrite.html#rewriterule">RewriteRule</a></code> or <code class="directive"><a href="../mod/mod_proxy.html#proxypass">ProxyPass</a></code>, you'll still need to use the
 183 <code class="directive"><a href="../mod/mod_proxy.html#proxypassreverse">ProxyPassReverse</a></code> directive to
 184 catch redirects issued from the back-end server:</p>
 185
 186 <pre class="prettyprint lang-config">
 187 ProxyPassReverse /images/ http://imageserver.local/images/
 188 </pre>
 189
 190
 191 <p>You may need to use <code>RewriteRule</code> instead when there are
 192 other <code>RewriteRule</code>s in effect in the same scope, as a
 193 <code>RewriteRule</code> will usually take effect before a
 194 <code>ProxyPass</code>, and so may preempt what you're trying to
 195 accomplish.</p>
 196
 197 </div><div class="top"><a href="#page-header"><img alt="top" src="../images/up.gif" /></a></div>
 198 <div class="section">
 199 <h2><a name="setenv" id="setenv">Environment Variable Testing</a></h2>
 200
 201 <p><code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> is frequently used to take a particular
 202 action based on the presence or absence of a particular environment
 203 variable or request header. This can be done more efficiently using the
 204 <code class="directive"><a href="../mod/core.html#if">&lt;If&gt;</a></code>.</p>
 205
 206 <p>Consider, for example, the common scenario where
 207 <code class="directive">RewriteRule</code> is used to enforce a canonical
 208 hostname, such as <code>www.example.com</code> instead of
 209 <code>example.com</code>. This can be done using the <code class="directive"><a href="../mod/core.html#if">&lt;If&gt;</a></code> directive, as shown here:</p>
 210
 211 <pre class="prettyprint lang-config">
 212 &lt;If "req('Host') != 'www.example.com'"&gt;
 213     Redirect / http://www.example.com/
 214 &lt;/If&gt;
 215 </pre>
 216
 217
 218 <p>This technique can be used to take actions based on any request
 219 header, response header, or environment variable, replacing
 220 <code class="module"><a href="../mod/mod_rewrite.html">mod_rewrite</a></code> in many common scenarios.</p>
 221
 222 <p>See especially the <a href="../expr.html">expression evaluation
 223 documentation</a> for a overview of what types of expressions you can
 224 use in &lt;If&gt; sections, and in certain other directives.</p>
 225
 226 </div></div>
 227 <div class="bottomlang">
 228 <p><span>Available Languages: </span><a href="../en/rewrite/avoid.html" title="English">&nbsp;en&nbsp;</a></p>
 229 </div><div class="top"><a href="#page-header"><img src="../images/up.gif" alt="top" /></a></div><div class="section"><h2><a id="comments_section" name="comments_section">Comments</a></h2><div class="warning"><strong>This section is experimental!</strong><br />Comments placed here should not be expected
 230 to last beyond the testing phase of this system, nor do we in any way guarantee that we'll read them.</div><div id="disqus_thread" /><script type="text/javascript"><!--//--><![CDATA[//><!--
 231 var lang = 'en';
 232 var disqus_shortname = 'httpd';
 233 var disqus_identifier = window.location.href.replace(/(current|trunk)/, "2.4").replace(/\/[a-z]{2}\//, "/").replace(window.location.protocol, "http:") + '.' + lang;
 234 if (disqus_identifier.indexOf("httpd.apache.org") != -1) {
 235     (function() {
 236                 var dsq = document.createElement('script'); dsq.type = 'text/javascript'; dsq.async = true;
 237                 dsq.src = window.location.protocol + '//' + disqus_shortname + '.disqus.com/embed.js';
 238             (document.getElementsByTagName('head')[0] || document.getElementsByTagName('body')[0]).appendChild(dsq);
 239         })();
 240 } else {
 241     var text = document.createTextNode("Comments have been disabled for offline viewing.");
 242     document.getElementById('disqus_thread').appendChild(text);
 243 }
 244 //--><!]]></script></div><div id="footer">
 245 <p class="apache">Copyright 2012 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</a>.</p>
 246 <p class="menu"><a href="../mod/">Modules</a> | <a href="../mod/directives.html">Directives</a> | <a href="http://wiki.apache.org/httpd/FAQ">FAQ</a> | <a href="../glossary.html">Glossary</a> | <a href="../sitemap.html">Sitemap</a></p></div><script type="text/javascript"><!--//--><![CDATA[//><!--
 247 if (typeof(prettyPrint) !== undefined) {
 248     prettyPrint();
 249 }
 250 //--><!]]></script>
 251 </body></html>