| <?xml version="1.0" encoding="UTF-8" ?> |
| <!DOCTYPE manualpage SYSTEM "../style/manualpage.dtd"> |
| <?xml-stylesheet type="text/xsl" href="../style/manual.en.xsl"?> |
| <!-- $LastChangedRevision$ --> |
| |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to You under the Apache License, Version 2.0 |
| (the "License"); you may not use this file except in compliance with |
| the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <manualpage metafile="remapping.xml.meta"> |
| <parentdocument href="./">Rewrite</parentdocument> |
| |
| <title>Redirecting and Remapping with mod_rewrite</title> |
| |
| <summary> |
| |
| <p>This document supplements the <module>mod_rewrite</module> |
| <a href="../mod/mod_rewrite.html">reference documentation</a>. It describes |
| how you can use <module>mod_rewrite</module> to redirect and remap |
| request. This includes many examples of common uses of mod_rewrite, |
| including detailed descriptions of how each works.</p> |
| |
| <note type="warning">Note that many of these examples won't work unchanged in your |
| particular server configuration, so it's important that you understand |
| them, rather than merely cutting and pasting the examples into your |
| configuration.</note> |
| |
| </summary> |
| <seealso><a href="../mod/mod_rewrite.html">Module documentation</a></seealso> |
| <seealso><a href="intro.html">mod_rewrite introduction</a></seealso> |
| <!--<seealso><a href="remapping.html">Redirection and remapping</a></seealso>--> |
| <seealso><a href="access.html">Controlling access</a></seealso> |
| <seealso><a href="vhosts.html">Virtual hosts</a></seealso> |
| <seealso><a href="proxy.html">Proxying</a></seealso> |
| <seealso><a href="rewritemap.html">Using RewriteMap</a></seealso> |
| <seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso> |
| <seealso><a href="avoid.html">When not to use mod_rewrite</a></seealso> |
| |
| <section id="old-to-new"> |
| |
| <title>From Old to New (internal)</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>Assume we have recently renamed the page |
| <code>foo.html</code> to <code>bar.html</code> and now want |
| to provide the old URL for backward compatibility. However, |
| we want that users of the old URL even not recognize that |
| the pages was renamed - that is, we don't want the address to |
| change in their browser.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We rewrite the old URL to the new one internally via the |
| following rule:</p> |
| |
| <example> |
| RewriteEngine on<br /> |
| RewriteRule ^<strong>/foo</strong>\.html$ <strong>/bar</strong>.html [PT] |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="old-to-new-extern"> |
| |
| <title>Rewriting From Old to New (external)</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>Assume again that we have recently renamed the page |
| <code>foo.html</code> to <code>bar.html</code> and now want |
| to provide the old URL for backward compatibility. But this |
| time we want that the users of the old URL get hinted to |
| the new one, i.e. their browsers Location field should |
| change, too.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We force a HTTP redirect to the new URL which leads to a |
| change of the browsers and thus the users view:</p> |
| |
| <example> |
| RewriteEngine on<br /> |
| RewriteRule ^<strong>/foo</strong>\.html$ <strong>bar</strong>.html [<strong>R</strong>] |
| </example> |
| </dd> |
| |
| <dt>Discussion</dt> |
| |
| <dd> |
| <p>In this example, as contrasted to the <a |
| href="#old-to-new-intern">internal</a> example above, we can simply |
| use the Redirect directive. mod_rewrite was used in that earlier |
| example in order to hide the redirect from the client:</p> |
| |
| <example> |
| Redirect /foo.html /bar.html |
| </example> |
| |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="movehomedirs"> |
| |
| <title>Resource Moved to Another Server</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>If a resource has moved to another server, you may wish to have |
| URLs continue to work for a time on the old server while people |
| update their bookmarks.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>You can use <module>mod_rewrite</module> to redirect these URLs |
| to the new server, but you might also consider using the Redirect |
| or RedirectMatch directive.</p> |
| |
| <example><title>With mod_rewrite</title> |
| RewriteEngine on<br /> |
| RewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L] |
| </example> |
| |
| <example><title>With RedirectMatch</title> |
| RedirectMatch ^/docs/(.*) http://new.example.com/docs/$1 |
| </example> |
| |
| <example><title>With Redirect</title> |
| Redirect /docs/ http://new.example.com/docs/ |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="static-to-dynamic"> |
| |
| <title>From Static to Dynamic</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>How can we transform a static page |
| <code>foo.html</code> into a dynamic variant |
| <code>foo.cgi</code> in a seamless way, i.e. without notice |
| by the browser/user.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We just rewrite the URL to the CGI-script and force the |
| handler to be <strong>cgi-script</strong> so that it is |
| executed as a CGI program. |
| This way a request to <code>/~quux/foo.html</code> |
| internally leads to the invocation of |
| <code>/~quux/foo.cgi</code>.</p> |
| |
| <example> |
| RewriteEngine on<br /> |
| RewriteBase /~quux/<br /> |
| RewriteRule ^foo\.<strong>html</strong>$ foo.<strong>cgi</strong> [H=<strong>cgi-script</strong>] |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="backward-compatibility"> |
| |
| <title>Backward Compatibility for file extension change</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>How can we make URLs backward compatible (still |
| existing virtually) after migrating <code>document.YYYY</code> |
| to <code>document.XXXX</code>, e.g. after translating a |
| bunch of <code>.html</code> files to <code>.php</code>?</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We rewrite the name to its basename and test for |
| existence of the new extension. If it exists, we take |
| that name, else we rewrite the URL to its original state.</p> |
| |
| <example> |
| # backward compatibility ruleset for<br /> |
| # rewriting document.html to document.php<br /> |
| # when and only when document.php exists<br /> |
| <Directory /var/www/htdocs><br /> |
| <indent> |
| RewriteEngine on<br /> |
| RewriteBase /var/www/htdocs<br /> |
| <br /> |
| RewriteCond $1.php -f<br /> |
| RewriteCond $1.html !-f<br /> |
| RewriteRule ^(.*).html$ $1.php<br /> |
| </indent> |
| </Directory> |
| </example> |
| </dd> |
| |
| <dt>Discussion</dt> |
| <dd> |
| <p>This example uses an often-overlooked feature of mod_rewrite, |
| by taking advantage of the order of execution of the ruleset. In |
| particular, mod_rewrite evaluates the left-hand-side of the |
| RewriteRule before it evaluates the RewriteCond directives. |
| Consequently, $1 is already defined by the time the RewriteCond |
| directives are evaluated. This allows us to test for the existence |
| of the original (<code>document.html</code>) and target |
| (<code>document.php</code>) files using the same base filename.</p> |
| |
| <p>This ruleset is designed to use in a per-directory context (In a |
| <Directory> block or in a .htaccess file), so that the |
| <code>-f</code> checks are looking at the correct directory path. |
| You may need to set a <directive |
| module="mod_rewrite">RewriteBase</directive> directive to specify the |
| directory base that you're working in.</p> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="canonicalhost"> |
| |
| <title>Canonical Hostnames</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd>The goal of this rule is to force the use of a particular |
| hostname, in preference to other hostnames which may be used to |
| reach the same site. For example, if you wish to force the use |
| of <strong>www.example.com</strong> instead of |
| <strong>example.com</strong>, you might use a variant of the |
| following recipe.</dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| |
| <p>The very best way to solve this doesn't involve mod_rewrite at all, |
| but rather uses the <directive module="mod_alias">Redirect</directive> |
| directive placed in a virtual host for the non-canonical |
| hostname(s).</p> |
| |
| <example> |
| <VirtualHost *:80><br /> |
| <indent> |
| ServerName undesired.example.com<br /> |
| ServerAlias example.com notthis.example.com<br /> |
| <br /> |
| Redirect / http://www.example.com/<br /> |
| </indent> |
| </VirtualHost><br /> |
| <br /> |
| <VirtualHost *:80><br /> |
| <indent> |
| ServerName www.example.com<br /> |
| </indent> |
| </VirtualHost> |
| </example> |
| |
| <p>If, for whatever reason, you still want to use <code>mod_rewrite</code> |
| - if, for example, you need this to work with a larger set of RewriteRules - |
| you might use one of the recipes below.</p> |
| |
| <p>For sites running on a port other than 80:</p> |
| <example> |
| RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br /> |
| RewriteCond %{HTTP_HOST} !^$<br /> |
| RewriteCond %{SERVER_PORT} !^80$<br /> |
| RewriteRule ^/?(.*) http://www.example.com:%{SERVER_PORT}/$1 [L,R,NE] |
| </example> |
| |
| <p>And for a site running on port 80</p> |
| <example> |
| RewriteCond %{HTTP_HOST} !^www\.example\.com [NC]<br /> |
| RewriteCond %{HTTP_HOST} !^$<br /> |
| RewriteRule ^/?(.*) http://www.example.com/$1 [L,R,NE] |
| </example> |
| |
| <p> |
| If you wanted to do this generically for all domain names - that |
| is, if you want to redirect <strong>example.com</strong> to |
| <strong>www.example.com</strong> for all possible values of |
| <strong>example.com</strong>, you could use the following |
| recipe:</p> |
| |
| <example> |
| RewriteCond %{HTTP_HOST} !^www\. [NC]<br /> |
| RewriteCond %{HTTP_HOST} !^$<br /> |
| RewriteRule ^/?(.*) http://www.%{HTTP_HOST}/$1 [L,R,NE] |
| </example> |
| |
| <p>These rulesets will work either in your main server configuration |
| file, or in a <code>.htaccess</code> file placed in the <directive |
| module="core">DocumentRoot</directive> of the server.</p> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="multipledirs"> |
| |
| <title>Search for pages in more than one directory</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>A particular resource might exist in one of several places, and |
| we want to look in those places for the resource when it is |
| requested. Perhaps we've recently rearranged our directory |
| structure, dividing content into several locations.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>The following ruleset searches in two directories to find the |
| resource, and, if not finding it in either place, will attempt to |
| just serve it out of the location requested.</p> |
| |
| <example> |
| RewriteEngine on<br /> |
| <br /> |
| # first try to find it in dir1/...<br /> |
| # ...and if found stop and be happy:<br /> |
| RewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f<br /> |
| RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]<br /> |
| <br /> |
| # second try to find it in dir2/...<br /> |
| # ...and if found stop and be happy:<br /> |
| RewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f<br /> |
| RewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]<br /> |
| <br /> |
| # else go on for other Alias or ScriptAlias directives,<br /> |
| # etc.<br /> |
| RewriteRule ^ - [PT] |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="archive-access-multiplexer"> |
| |
| <title>Redirecting to Geographically Distributed Servers</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>We have numerous mirrors of our website, and want to redirect |
| people to the one that is located in the country where they are |
| located.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>Looking at the hostname of the requesting client, we determine |
| which country they are coming from. If we can't do a lookup on their |
| IP address, we fall back to a default server.</p> |
| <p>We'll use a <directive module="mod_rewrite">RewriteMap</directive> |
| directive to build a list of servers that we wish to use.</p> |
| |
| <example> |
| HostnameLookups on<br /> |
| RewriteEngine on<br /> |
| RewriteMap multiplex txt:/path/to/map.mirrors<br /> |
| RewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]<br /> |
| RewriteRule ^/(.*)$ ${multiplex:<strong>%1</strong>|http://www.example.com/}$1 [R,L] |
| </example> |
| |
| <example> |
| ## map.mirrors -- Multiplexing Map<br /> |
| <br /> |
| de http://www.example.de/<br /> |
| uk http://www.example.uk/<br /> |
| com http://www.example.com/<br /> |
| ##EOF## |
| </example> |
| </dd> |
| |
| <dt>Discussion</dt> |
| <dd> |
| <note type="warning">This ruleset relies on |
| <directive module="core">HostNameLookups</directive> |
| being set <code>on</code>, which can be |
| a significant performance hit.</note> |
| |
| <p>The <directive module="mod_rewrite">RewriteCond</directive> |
| directive captures the last portion of the hostname of the |
| requesting client - the country code - and the following RewriteRule |
| uses that value to look up the appropriate mirror host in the map |
| file.</p> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="browser-dependent-content"> |
| |
| <title>Browser Dependent Content</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>We wish to provide different content based on the browser, or |
| user-agent, which is requesting the content.</p> |
| </dd> |
| |
| <!-- It would be nice to bring this example into the 21st century. --> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We have to decide, based on the HTTP header "User-Agent", |
| which content to serve. The following config |
| does the following: If the HTTP header "User-Agent" |
| contains "Mozilla/3", the page <code>foo.html</code> |
| is rewritten to <code>foo.NS.html</code> and the |
| rewriting stops. If the browser is "Lynx" or "Mozilla" of |
| version 1 or 2, the URL becomes <code>foo.20.html</code>. |
| All other browsers receive page <code>foo.32.html</code>. |
| This is done with the following ruleset:</p> |
| |
| <example> |
| RewriteCond %{HTTP_USER_AGENT} <strong>^Mozilla/3</strong>.*<br /> |
| RewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]<br /> |
| <br /> |
| RewriteCond %{HTTP_USER_AGENT} <strong>^Lynx/</strong> [OR]<br /> |
| RewriteCond %{HTTP_USER_AGENT} <strong>^Mozilla/[12]</strong><br /> |
| RewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]<br /> |
| <br /> |
| RewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>] |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="canonicalurl"> |
| |
| <title>Canonical URLs</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>On some webservers there is more than one URL for a |
| resource. Usually there are canonical URLs (which are be |
| actually used and distributed) and those which are just |
| shortcuts, internal ones, and so on. Independent of which URL the |
| user supplied with the request, they should finally see the |
| canonical one in their browser address bar.</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We do an external HTTP redirect for all non-canonical |
| URLs to fix them in the location view of the Browser and |
| for all subsequent requests. In the example ruleset below |
| we replace <code>/puppies</code> and <code>/canines</code> |
| by the canonical <code>/dogs</code>.</p> |
| |
| <example> |
| RewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R] |
| </example> |
| </dd> |
| |
| <dt>Discussion:</dt> |
| <dd> |
| This should really be accomplished with Redirect or RedirectMatch |
| directives: |
| |
| <example> |
| RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2 |
| </example> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="moveddocroot"> |
| |
| <title>Moved <code>DocumentRoot</code></title> |
| |
| <dl> |
| <dt>Description:</dt> |
| |
| <dd> |
| <p>Usually the <directive module="core">DocumentRoot</directive> |
| of the webserver directly relates to the URL "<code>/</code>". |
| But often this data is not really of top-level priority. For example, |
| you may wish for visitors, on first entering a site, to go to a |
| particular subdirectory <code>/about/</code>. This may be accomplished |
| using the following ruleset:</p> |
| </dd> |
| |
| <dt>Solution:</dt> |
| |
| <dd> |
| <p>We redirect the URL <code>/</code> to |
| <code>/about/</code>: |
| </p> |
| |
| <example> |
| RewriteEngine on<br /> |
| RewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>] |
| </example> |
| |
| <p>Note that this can also be handled using the <directive |
| module="mod_alias">RedirectMatch</directive> directive:</p> |
| |
| <example> |
| RedirectMatch ^/$ http://example.com/about/ |
| </example> |
| |
| <p>Note also that the example rewrites only the root URL. That is, it |
| rewrites a request for <code>http://example.com/</code>, but not a |
| request for <code>http://example.com/page.html</code>. If you have in |
| fact changed your document root - that is, if <strong>all</strong> of |
| your content is in fact in that subdirectory, it is greatly preferable |
| to simply change your <directive module="core">DocumentRoot</directive> |
| directive, or move all of the content up one directory, |
| rather than rewriting URLs.</p> |
| </dd> |
| </dl> |
| |
| </section> |
| |
| <section id="fallback-resource"> |
| <title>Fallback Resource</title> |
| |
| <dl> |
| <dt>Description:</dt> |
| <dd>You want a single resource (say, a certain file, like index.php) to |
| handle all requests that come to a particular directory, except those |
| that should go to an existing resource such as an image, or a css file.</dd> |
| |
| <dt>Solution:</dt> |
| <dd> |
| <p>As of version 2.2.16, you should use the <directive |
| module="mod_dir">FallbackResource</directive> directive for this:</p> |
| |
| <example> |
| <Directory /var/www/my_blog><br /> |
| <indent> |
| FallbackResource index.php<br /> |
| </indent> |
| </Directory> |
| </example> |
| |
| <p>However, in earlier versions of Apache, or if your needs are more |
| complicated than this, you can use a variation of the following rewrite |
| set to accomplish the same thing:</p> |
| |
| <example> |
| <Directory /var/www/my_blog><br /> |
| <indent> |
| RewriteBase /my_blog<br /> |
| <br /> |
| RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-f<br /> |
| RewriteCond /var/www/my_blog/%{REQUEST_FILENAME} !-d<br /> |
| RewriteRule ^ index.php [PT]<br /> |
| </indent> |
| </Directory> |
| </example> |
| |
| <p>If, on the other hand, you wish to pass the requested URI as a query |
| string argument to index.php, you can replace that RewriteRule with:</p> |
| |
| <example> |
| RewriteRule (.*) index.php?$1 [PT,QSA] |
| </example> |
| |
| <p>Note that these rulesets can be uses in a <code>.htaccess</code> |
| file, as well as in a <Directory> block.</p> |
| |
| </dd> |
| |
| </dl> |
| |
| </section> |
| |
| </manualpage> |