remapping.xml revision 1a1f0f42c4b3840641897888fec7792af8ba384f
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<?xml-stylesheet type="text/xsl" href="/style/manual.en.xsl"?>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<!-- $LastChangedRevision: 832069 $ -->
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<title>Redirecting and Remapping with mod_rewrite</title>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<p>This document supplements the <module>mod_rewrite</module>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<a href="/mod_rewrite.html">reference documentation</a>. It describes
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenhow you can use <module>mod_rewrite</module> to redirect and remap
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenrequest. This includes many examples of common uses of mod_rewrite,
4a1711ab536d965e63d7be80e29f912287fe70b2rbowenincluding detailed descriptions of how each works.</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen<note type="warning">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
1a1f0f42c4b3840641897888fec7792af8ba384frbowenconfiguration.</note>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<seealso><a href="/mod/mod_rewrite.html">Module documentation</a></seealso>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen<seealso><a href="intro.html">mod_rewrite introduction</a></seealso>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>Assume we have recently renamed the page
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <code>foo.html</code> to <code>bar.html</code> and now want
1a1f0f42c4b3840641897888fec7792af8ba384frbowen to provide the old URL for backward compatibility. However,
1a1f0f42c4b3840641897888fec7792af8ba384frbowen we want that users of the old URL even not recognize that
1a1f0f42c4b3840641897888fec7792af8ba384frbowen the pages was renamed - that is, we don't want the address to
1a1f0f42c4b3840641897888fec7792af8ba384frbowen change in their browser.</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>We rewrite the old URL to the new one internally via the
1a1f0f42c4b3840641897888fec7792af8ba384frbowen following rule:</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteEngine on
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^<strong>/old</strong>\.html$ <strong>/new</strong>.html [PT]
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>Assume again that we have recently renamed the page
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <code>foo.html</code> to <code>bar.html</code> and now want
1a1f0f42c4b3840641897888fec7792af8ba384frbowen to provide the old URL for backward compatibility. But this
1a1f0f42c4b3840641897888fec7792af8ba384frbowen time we want that the users of the old URL get hinted to
1a1f0f42c4b3840641897888fec7792af8ba384frbowen the new one, i.e. their browsers Location field should
1a1f0f42c4b3840641897888fec7792af8ba384frbowen change, too.</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>We force a HTTP redirect to the new URL which leads to a
1a1f0f42c4b3840641897888fec7792af8ba384frbowen change of the browsers and thus the users view:</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteEngine on
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>]
1a1f0f42c4b3840641897888fec7792af8ba384frbowen href="#old-to-new-intern">internal</a> example above, we can simply
1a1f0f42c4b3840641897888fec7792af8ba384frbowen use the Redirect directive. mod_rewrite was used in that earlier
1a1f0f42c4b3840641897888fec7792af8ba384frbowen example in order to hide the redirect from the client:</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>How can we transform a static page
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <code>foo.cgi</code> in a seamless way, i.e. without notice
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>We just rewrite the URL to the CGI-script and force the
1a1f0f42c4b3840641897888fec7792af8ba384frbowen handler to be <strong>cgi-script</strong> so that it is
1a1f0f42c4b3840641897888fec7792af8ba384frbowen executed as a CGI program.
1a1f0f42c4b3840641897888fec7792af8ba384frbowen internally leads to the invocation of
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteEngine on
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteBase /~quux/
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>]
1a1f0f42c4b3840641897888fec7792af8ba384frbowen<section id="canonicalhost"><title>Canonical Hostnames</title>
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <dd>The goal of this rule is to force the use of a particular
1a1f0f42c4b3840641897888fec7792af8ba384frbowen hostname, in preference to other hostnames which may be used to
1a1f0f42c4b3840641897888fec7792af8ba384frbowen reach the same site. For example, if you wish to force the use
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <strong>example.com</strong>, you might use a variant of the
1a1f0f42c4b3840641897888fec7792af8ba384frbowen following recipe.</dd>
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^$
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{SERVER_PORT} !^80$
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE]
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^www\.example\.com [NC]
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^$
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE]
1a1f0f42c4b3840641897888fec7792af8ba384frbowen If you wanted to do this generically for all domain names - that
1a1f0f42c4b3840641897888fec7792af8ba384frbowen is, if you want to redirect <strong>example.com</strong> to
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <strong>www.example.com</strong> for all possible values of
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <strong>example.com</strong>, you could use the following
1a1f0f42c4b3840641897888fec7792af8ba384frbowen recipe:</p>
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^www\. [NC]
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteCond %{HTTP_HOST} !^$
1a1f0f42c4b3840641897888fec7792af8ba384frbowenRewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE]
1a1f0f42c4b3840641897888fec7792af8ba384frbowen <p>These rulesets will work either in your main server configuration
1a1f0f42c4b3840641897888fec7792af8ba384frbowen file, or in a <code>.htaccess</code> file placed in the <directive
1a1f0f42c4b3840641897888fec7792af8ba384frbowen module="core">DocumentRoot</directive> of the server.</p>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen</manualpage>