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