remapping.xml revision 10705fbc225dcf590c9ba24a4f04de221358060a
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>
2bb0656f94af82b1ff5e3e77a99b4427c52e4953rbowen<a href="/mod/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>
10705fbc225dcf590c9ba24a4f04de221358060arbowen<!--<seealso><a href="remapping.html">Redirection and remapping</a></seealso>-->
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="access.html">Controlling access</a></seealso>
10705fbc225dcf590c9ba24a4f04de221358060arbowen<seealso><a href="vhosts.html">Virtual hosts</a></seealso>
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="advanced.html">Advanced techniques and tricks</a></seealso>
8b79a240383bcecf28b75d4803683a7d101d2713rbowen<seealso><a href="avoid.html">When not to use mod_rewrite</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>
67398034ea8b919da6274d4e178661559e1eb1e2rbowen <p>If a resource has moved to another server, you may wish to have
67398034ea8b919da6274d4e178661559e1eb1e2rbowen URLs continue to work for a time on the old server while people
67398034ea8b919da6274d4e178661559e1eb1e2rbowen update their bookmarks.</p>
67398034ea8b919da6274d4e178661559e1eb1e2rbowen <p>You can use <module>mod_rewrite</module> to redirect these URLs
67398034ea8b919da6274d4e178661559e1eb1e2rbowen to the new server, but you might also consider using the Redirect
67398034ea8b919da6274d4e178661559e1eb1e2rbowen or RedirectMatch directive.</p>
67398034ea8b919da6274d4e178661559e1eb1e2rbowenRewriteEngine on
67398034ea8b919da6274d4e178661559e1eb1e2rbowenRewriteRule ^/docs/(.+) http://new.example.com/docs/$1 [R,L]
67398034ea8b919da6274d4e178661559e1eb1e2rbowenRedirectMatch ^/docs/(.*) http://new.example.com/docs/$1
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>]
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <title>Backward Compatibility for file extension change</title>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>How can we make URLs backward compatible (still
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen existing virtually) after migrating <code>document.YYYY</code>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen to <code>document.XXXX</code>, e.g. after translating a
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen bunch of <code>.html</code> files to <code>.php</code>?</p>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>We rewrite the name to its basename and test for
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen existence of the new extension. If it exists, we take
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen that name, else we rewrite the URL to its original state.</p>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# backward compatibility ruleset for
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# when and only when document.php exists
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteEngine on
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteCond $1.php -f
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteCond $1.html !-f
67398034ea8b919da6274d4e178661559e1eb1e2rbowenRewriteRule ^(.*).html$ $1.php
67398034ea8b919da6274d4e178661559e1eb1e2rbowen</Directory>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>This example uses an often-overlooked feature of mod_rewrite,
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen by taking advantage of the order of execution of the ruleset. In
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen particular, mod_rewrite evaluates the left-hand-side of the
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen RewriteRule before it evaluates the RewriteCond directives.
0464ea692a2abb32bccd571ee98ddbd43dad4ffbrbowen Consequently, $1 is already defined by the time the RewriteCond
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen directives are evaluated. This allows us to test for the existence
48193e92704a478a74d9065fc32874505847bfd9lgentis of the original (<code>document.html</code>) and target
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen (<code>document.php</code>) files using the same base filename.</p>
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen <p>This ruleset is designed to use in a per-directory context (In a
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen <Directory> block or in a .htaccess file), so that the
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen <code>-f</code> checks are looking at the correct directory path.
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen You may need to set a <directive
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen module="mod_rewite">RewriteBase</directive> directive to specify the
73036acae345bfcd48167c09e7ee2f0f0a19df8arbowen directory base that you're working in.</p>
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>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <title>Search for pages in more than one directory</title>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>A particular resource might exist in one of several places, and
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen we want to look in those places for the resource when it is
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen requested. Perhaps we've recently rearranged our directory
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen structure, dividing content into several locations.</p>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen <p>The following ruleset searches in two directories to find the
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen resource, and, if not finding it in either place, will attempt to
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen just serve it out of the location requested.</p>
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteEngine on
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# first try to find it in dir1/...
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# ...and if found stop and be happy:
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteCond %{DOCUMENT_ROOT}/<strong>dir1</strong>/%{REQUEST_URI} -f
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir1</strong>/$1 [L]
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# second try to find it in dir2/...
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# ...and if found stop and be happy:
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteCond %{DOCUMENT_ROOT}/<strong>dir2</strong>/%{REQUEST_URI} -f
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteRule ^(.+) %{DOCUMENT_ROOT}/<strong>dir2</strong>/$1 [L]
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowen# else go on for other Alias or ScriptAlias directives,
13e125c14cbafff43783b7f3aed11de6d4cb5b14rbowenRewriteRule ^(.+) - [PT]
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen <title>Redirecting to Geographically Distributed Servers</title>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen <p>We have numerous mirrors of our website, and want to redirect
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen people to the one that is located in the country where they are
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen located.</p>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen <p>Looking at the hostname of the requesting client, we determine
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen which country they are coming from. If we can't do a lookup on their
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen IP address, we fall back to a default server.</p>
48193e92704a478a74d9065fc32874505847bfd9lgentis <p>We'll use a <directive module="mod_rewrite">RewriteMap</directive>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen directive to build a list of servers that we wish to use.</p>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowenHostnameLookups on
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowenRewriteEngine on
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowenRewriteCond %{REMOTE_HOST} ([a-z]+)$ [NC]
4634fe331f9689ad14057c5ca77d285b50ce08c4rbowenRewriteRule ^/(.*)$ ${multiplex:<strong>%1</strong>|http://www.example.com/}$1 [R,L]
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen## map.mirrors -- Multiplexing Map
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen a significant performance hit.</note>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen <p>The <directive module="mod_rewrite">RewriteCond</directive>
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen directive captures the last portion of the hostname of the
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen requesting client - the country code - and the following RewriteRule
aa3ddf73a3cb180f88a18742f363f2cb9a0c5cderbowen uses that value to look up the appropriate mirror host in the map
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen <p>We wish to provide different content based on the browser, or
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen user-agent, which is requesting the content.</p>
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen <p>We have to decide, based on the HTTP header "User-Agent",
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen which content to serve. The following config
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen does the following: If the HTTP header "User-Agent"
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen rewriting stops. If the browser is "Lynx" or "Mozilla" of
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen version 1 or 2, the URL becomes <code>foo.20.html</code>.
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen All other browsers receive page <code>foo.32.html</code>.
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowen This is done with the following ruleset:</p>
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/3</strong>.*
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteRule ^foo\.html$ foo.<strong>NS</strong>.html [<strong>L</strong>]
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteCond %{HTTP_USER_AGENT} ^<strong>Lynx/</strong>.* [OR]
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteCond %{HTTP_USER_AGENT} ^<strong>Mozilla/[12]</strong>.*
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteRule ^foo\.html$ foo.<strong>20</strong>.html [<strong>L</strong>]
32e1018ca3ab0e0bd089fd38ce8d97bb7a607639rbowenRewriteRule ^foo\.html$ foo.<strong>32</strong>.html [<strong>L</strong>]
856d8f134df3b2d23a76717121e042877f85ae3brbowen <p>On some webservers there is more than one URL for a
856d8f134df3b2d23a76717121e042877f85ae3brbowen resource. Usually there are canonical URLs (which are be
856d8f134df3b2d23a76717121e042877f85ae3brbowen actually used and distributed) and those which are just
856d8f134df3b2d23a76717121e042877f85ae3brbowen shortcuts, internal ones, and so on. Independent of which URL the
856d8f134df3b2d23a76717121e042877f85ae3brbowen user supplied with the request, they should finally see the
856d8f134df3b2d23a76717121e042877f85ae3brbowen canonical one in their browser address bar.</p>
856d8f134df3b2d23a76717121e042877f85ae3brbowen <p>We do an external HTTP redirect for all non-canonical
856d8f134df3b2d23a76717121e042877f85ae3brbowen URLs to fix them in the location view of the Browser and
856d8f134df3b2d23a76717121e042877f85ae3brbowen for all subsequent requests. In the example ruleset below
856d8f134df3b2d23a76717121e042877f85ae3brbowen we replace <code>/puppies</code> and <code>/canines</code>
856d8f134df3b2d23a76717121e042877f85ae3brbowenRewriteRule ^/(puppies|canines)/(.*) /dogs/$2 [R]
856d8f134df3b2d23a76717121e042877f85ae3brbowen This should really be accomplished with Redirect or RedirectMatch
856d8f134df3b2d23a76717121e042877f85ae3brbowen directives:
856d8f134df3b2d23a76717121e042877f85ae3brbowen RedirectMatch ^/(puppies|canines)/(.*) /dogs/$2
331e7d505cac0db96920e7177d6f476bc4986341rbowen <p>We want to automatically create a virtual host for every user who
331e7d505cac0db96920e7177d6f476bc4986341rbowen has an account on our web server system, without having to create
331e7d505cac0db96920e7177d6f476bc4986341rbowen new VirtualHost sections.</p>
331e7d505cac0db96920e7177d6f476bc4986341rbowen <p>In this recipe, we assume that we'll be using the hostname
331e7d505cac0db96920e7177d6f476bc4986341rbowen <code>www.<strong>username</strong>.example.com</code> for each
331e7d505cac0db96920e7177d6f476bc4986341rbowen user, and serve their content out of
331e7d505cac0db96920e7177d6f476bc4986341rbowen <code>/home/<strong>username</strong>/www</code>.</p>
331e7d505cac0db96920e7177d6f476bc4986341rbowenRewriteEngine on
331e7d505cac0db96920e7177d6f476bc4986341rbowenRewriteCond %{<strong>HTTP_HOST</strong>} ^www\.<strong>([^.]+)</strong>\.example\.com$
331e7d505cac0db96920e7177d6f476bc4986341rbowen <note type="warning">You will need to take care of the DNS
331e7d505cac0db96920e7177d6f476bc4986341rbowen resolution - Apache does
331e7d505cac0db96920e7177d6f476bc4986341rbowen not handle name resolution. You'll need either to create CNAME
331e7d505cac0db96920e7177d6f476bc4986341rbowen records for each hostname, or a DNS wildcard record. Creating DNS
331e7d505cac0db96920e7177d6f476bc4986341rbowen records is beyond the scope of this document.</note>
331e7d505cac0db96920e7177d6f476bc4986341rbowenmodule="mod_rewrite">RewriteCond</directive> are captured into the
331e7d505cac0db96920e7177d6f476bc4986341rbowenbackreferences <code>%1</code>, <code>%2</code>, etc, while parentheses
331e7d505cac0db96920e7177d6f476bc4986341rbowenused in <directive module="mod_rewrite">RewriteRule</directive> are
331e7d505cac0db96920e7177d6f476bc4986341rbowencaptured into the backreferences <code>$1</code>, <code>$2</code>,
331e7d505cac0db96920e7177d6f476bc4986341rbowenAs with many techniques discussed in this document, mod_rewrite really
331e7d505cac0db96920e7177d6f476bc4986341rbowenisn't the best way to accomplish this task. You should, instead,
331e7d505cac0db96920e7177d6f476bc4986341rbowenconsider using <module>mod_vhost_alias</module> instead, as it will much
331e7d505cac0db96920e7177d6f476bc4986341rbowenmore gracefully handle anything beyond serving static files, such as any
331e7d505cac0db96920e7177d6f476bc4986341rbowendynamic content, and Alias resolution.
9e4b928f0fa926f7d86413e5043993547df97753rbowen<p>Usually the <directive module="core">DocumentRoot</directive>
9e4b928f0fa926f7d86413e5043993547df97753rbowenof the webserver directly relates to the URL "<code>/</code>".
9e4b928f0fa926f7d86413e5043993547df97753rbowenBut often this data is not really of top-level priority. For example,
9e4b928f0fa926f7d86413e5043993547df97753rbowenyou may wish for visitors, on first entering a site, to go to a
9e4b928f0fa926f7d86413e5043993547df97753rbowenparticular subdirectory <code>/about/</code>. This may be accomplished
9e4b928f0fa926f7d86413e5043993547df97753rbowenusing the following ruleset:</p>
9e4b928f0fa926f7d86413e5043993547df97753rbowenRewriteEngine on
9e4b928f0fa926f7d86413e5043993547df97753rbowenRewriteRule <strong>^/$</strong> /about/ [<strong>R</strong>]
9e4b928f0fa926f7d86413e5043993547df97753rbowen<p>Note that this can also be handled using the <directive
9e4b928f0fa926f7d86413e5043993547df97753rbowenmodule="mod_alias">RedirectMatch</directive> directive:</p>
9e4b928f0fa926f7d86413e5043993547df97753rbowenRedirectMatch ^/$ http://example.com/about/
9e4b928f0fa926f7d86413e5043993547df97753rbowen<p>Note also that the example rewrites only the root URL. That is, it
9e4b928f0fa926f7d86413e5043993547df97753rbowenrewrites a request for <code>http://example.com/</code>, but not a
9e4b928f0fa926f7d86413e5043993547df97753rbowenrequest for <code>http://example.com/page.html</code>. If you have in
9e4b928f0fa926f7d86413e5043993547df97753rbowenfact changed your document root - that is, if <strong>all</strong> of
9e4b928f0fa926f7d86413e5043993547df97753rbowenyour content is in fact in that subdirectory, it is greatly preferable
9e4b928f0fa926f7d86413e5043993547df97753rbowento simply change your <directive module="core">DocumentRoot</directive>
9e4b928f0fa926f7d86413e5043993547df97753rbowendirective, or move all of the content up one directory,
9e4b928f0fa926f7d86413e5043993547df97753rbowenrather than rewriting URLs.</p>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen<dd>You want a single resource (say, a certain file, like index.php) to
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenhandle all requests that come to a particular directory, except those
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenthat should go to an existing resource such as an image, or a css file.</dd>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenmodule="mod_dir">FallbackResource</directive> directive for this:</p>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen FallbackResource index.php
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen</Directory>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen<p>However, in earlier versions of Apache, or if your needs are more
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowencomplicated than this, you can use a variation of the following rewrite
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenset to accomplish the same thing:</p>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen RewriteBase /my_blog
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen RewriteRule ^ index.php [PT]
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen</Directory>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen<p>If, on the other hand, you wish to pass the requested URI as a query
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenstring argument to index.php, you can replace that RewriteRule with:</p>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen RewriteRule (.*) index.php?$1 [PT,QSA]
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowen<p>Note that these rulesets can be uses in a <code>.htaccess</code>
8ecfbb3fce5da653749fdc9d97dc6561d4c32ef4rbowenfile, as well as in a <Directory> block.</p>
43289eb78809cbdec92c7d90433a8852233f0b2brbowen <p>Mass virtual hosting is one of the more common uses of
43289eb78809cbdec92c7d90433a8852233f0b2brbowen mod_rewrite. However, it is seldom the best way to handle mass
43289eb78809cbdec92c7d90433a8852233f0b2brbowen virtual hosting. This topic is discussed at great length in the <a
43289eb78809cbdec92c7d90433a8852233f0b2brbowen href="/vhosts/mass.html">virtual host documentation</a>.</p>
4a1711ab536d965e63d7be80e29f912287fe70b2rbowen</manualpage>