granicus.if.org Git - apache/blob - docs/manual/rewrite/remapping.xml

   1 <?xml version="1.0" encoding="UTF-8" ?>
   2 <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd">
   3 <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?>
   4 <!-- $LastChangedRevision: 832069 $ -->
   5
   6 <!--
   7  Licensed to the Apache Software Foundation (ASF) under one or more
   8  contributor license agreements.  See the NOTICE file distributed with
   9  this work for additional information regarding copyright ownership.
  10  The ASF licenses this file to You under the Apache License, Version 2.0
  11  (the "License"); you may not use this file except in compliance with
  12  the License.  You may obtain a copy of the License at
  13
  14      http://www.apache.org/licenses/LICENSE-2.0
  15
  16  Unless required by applicable law or agreed to in writing, software
  17  distributed under the License is distributed on an "AS IS" BASIS,
  18  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  19  See the License for the specific language governing permissions and
  20  limitations under the License.
  21 -->
  22
  23 <manualpage metafile="remapping.xml.meta">
  24   <parentdocument href="./">Rewrite</parentdocument>
  25
  26 <title>Redirecting and Remapping with mod_rewrite</title>
  27
  28 <summary>
  29
  30 <p>This document supplements the <module>mod_rewrite</module>
  31 <a href="../mod_rewrite.html">reference documentation</a>. It describes
  32 how you can use <module>mod_rewrite</module> to redirect and remap
  33 request. This includes many examples of common uses of mod_rewrite,
  34 including detailed descriptions of how each works.</p>
  35
  36 <note type="warning">Note that many of these examples won't work unchanged in your
  37 particular server configuration, so it's important that you understand
  38 them, rather than merely cutting and pasting the examples into your
  39 configuration.</note>
  40
  41 </summary>
  42 <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso>
  43 <seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
  44
  45 <section id="old-to-new">
  46
  47   <title>From Old to New (internal)</title>
  48
  49   <dl>
  50     <dt>Description:</dt>
  51
  52     <dd>
  53       <p>Assume we have recently renamed the page
  54       <code>foo.html</code> to <code>bar.html</code> and now want
  55       to provide the old URL for backward compatibility. However,
  56       we want that users of the old URL even not recognize that
  57       the pages was renamed - that is, we don't want the address to
  58       change in their browser.</p>
  59     </dd>
  60
  61     <dt>Solution:</dt>
  62
  63     <dd>
  64       <p>We rewrite the old URL to the new one internally via the
  65       following rule:</p>
  66
  67 <example><pre>
  68 RewriteEngine  on
  69 RewriteRule    ^<strong>/old</strong>\.html$  <strong>/new</strong>.html [PT]
  70 </pre></example>
  71     </dd>
  72   </dl>
  73
  74 </section>
  75
  76 <section id="old-to-new-extern">
  77
  78   <title>Rewriting From Old to New (external)</title>
  79
  80   <dl>
  81     <dt>Description:</dt>
  82
  83     <dd>
  84       <p>Assume again that we have recently renamed the page
  85       <code>foo.html</code> to <code>bar.html</code> and now want
  86       to provide the old URL for backward compatibility. But this
  87       time we want that the users of the old URL get hinted to
  88       the new one, i.e. their browsers Location field should
  89       change, too.</p>
  90     </dd>
  91
  92     <dt>Solution:</dt>
  93
  94     <dd>
  95       <p>We force a HTTP redirect to the new URL which leads to a
  96       change of the browsers and thus the users view:</p>
  97
  98 <example><pre>
  99 RewriteEngine  on
 100 RewriteRule    ^<strong>/foo</strong>\.html$  <strong>bar</strong>.html  [<strong>R</strong>]
 101 </pre></example>
 102 </dd>
 103
 104 <dt>Discussion</dt>
 105
 106     <dd>
 107     <p>In this example, as contrasted to the <a
 108     href="#old-to-new-intern">internal</a> example above, we can simply
 109     use the Redirect directive. mod_rewrite was used in that earlier
 110     example in order to hide the redirect from the client:</p>
 111
 112     <example>
 113     Redirect /foo.html /bar.html
 114     </example>
 115
 116     </dd>
 117   </dl>
 118
 119 </section>
 120
 121 <section id="static-to-dynamic">
 122
 123   <title>From Static to Dynamic</title>
 124
 125   <dl>
 126     <dt>Description:</dt>
 127
 128     <dd>
 129       <p>How can we transform a static page
 130       <code>foo.html</code> into a dynamic variant
 131       <code>foo.cgi</code> in a seamless way, i.e. without notice
 132       by the browser/user.</p>
 133     </dd>
 134
 135     <dt>Solution:</dt>
 136
 137     <dd>
 138       <p>We just rewrite the URL to the CGI-script and force the
 139       handler to be <strong>cgi-script</strong> so that it is
 140       executed as a CGI program.
 141       This way a request to <code>/~quux/foo.html</code>
 142       internally leads to the invocation of
 143       <code>/~quux/foo.cgi</code>.</p>
 144
 145 <example><pre>
 146 RewriteEngine  on
 147 RewriteBase    /~quux/
 148 RewriteRule    ^foo\.<strong>html</strong>$  foo.<strong>cgi</strong>  [H=<strong>cgi-script</strong>]
 149 </pre></example>
 150     </dd>
 151   </dl>
 152
 153 </section>
 154
 155 <section id="canonicalhost"><title>Canonical Hostnames</title>
 156
 157       <dl>
 158         <dt>Description:</dt>
 159
 160         <dd>The goal of this rule is to force the use of a particular
 161         hostname, in preference to other hostnames which may be used to
 162         reach the same site. For example, if you wish to force the use
 163         of <strong>www.example.com</strong> instead of
 164         <strong>example.com</strong>, you might use a variant of the
 165         following recipe.</dd>
 166
 167         <dt>Solution:</dt>
 168
 169         <dd>
 170 <p>For sites running on a port other than 80:</p>
 171 <example><pre>
 172 RewriteCond %{HTTP_HOST}   !^www\.example\.com [NC]
 173 RewriteCond %{HTTP_HOST}   !^$
 174 RewriteCond %{SERVER_PORT} !^80$
 175 RewriteRule ^/?(.*)         http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
 176 </pre></example>
 177
 178 <p>And for a site running on port 80</p>
 179 <example><pre>
 180 RewriteCond %{HTTP_HOST}   !^www\.example\.com [NC]
 181 RewriteCond %{HTTP_HOST}   !^$
 182 RewriteRule ^/?(.*)         http://www.example.com/$1 [L,R,NE]
 183 </pre></example>
 184
 185         <p>
 186         If you wanted to do this generically for all domain names - that
 187         is, if you want to redirect <strong>example.com</strong> to
 188         <strong>www.example.com</strong> for all possible values of
 189         <strong>example.com</strong>, you could use the following
 190         recipe:</p>
 191
 192 <example><pre>
 193 RewriteCond %{HTTP_HOST} !^www\. [NC]
 194 RewriteCond %{HTTP_HOST} !^$
 195 RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
 196 </pre></example>
 197
 198     <p>These rulesets will work either in your main server configuration
 199     file, or in a <code>.htaccess</code> file placed in the <directive
 200     module="core">DocumentRoot</directive> of the server.</p>
 201         </dd>
 202       </dl>
 203
 204     </section>
 205
 206 </manualpage>