Apache HTTP Server Version 2.4
This document supplements the
reference documentation. It describes
perhaps one of the most important concepts about
mod_rewrite - namely,
when to avoid using it.
mod_rewrite should be considered a last resort, when other
alternatives are found wanting. Using it when there are simpler
alternatives leads to configurations which are confusing, fragile, and
hard to maintain. Understanding what other alternatives are available is
a very important step towards
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.
The most common situation in which
the right tool is when the very best solution requires access to the
server configuration files, and you don't have that access. Some
configuration directives are only available in the server configuration
file. So if you are in a hosting situation where you only have .htaccess
files to work with, you may need to resort to
mod_alias provides the
RedirectMatch directives, which provide a
means to redirect one URL to another. This kind of simple redirection of
one URL, or a class of URLs, to somewhere else, should be accomplished
using these directives rather than
allows you to include a regular expression in your redirection criteria,
providing many of the benefits of using
A common use for
RewriteRule is to redirect an entire
class of URLs. For example, all URLs in the
must be redirected to
http://one.example.com/, or perhaps
http requests must be redirected to
These situations are better handled by the
directive. Remember that
Redirect preserves path
information. That is to say, a redirect for a URL
also redirect all URLs under that, such as
To redirect URLs under
http://one.example.com, do the following:
Redirect "/one/" "http://one.example.com/"
To redirect one hostname to another, for example
www.example.com, see the
http URLs to
https, do the
<VirtualHost *:80> ServerName www.example.com Redirect "/" "https://www.example.com/" </VirtualHost> <VirtualHost *:443> ServerName www.example.com # ... SSL configuration goes here </VirtualHost>
The use of
RewriteRule to perform this task may be
appropriate if there are other
RewriteRule directives in
the same scope. This is because, when there are
RewriteRule directives in the same scope, the
RewriteRule directives will run first, regardless of the
order of appearance in the configuration file.
In the case of the http-to-https redirection, the use of
RewriteRule would be appropriate if you don't have access
to the main server configuration file, and are obliged to perform this
task in a
.htaccess file instead.
provides mapping from a URI to a directory - usually a directory outside
DocumentRoot. Although it
is possible to perform this mapping with
Alias is the preferred method, for
reasons of simplicity and performance.
Alias "/cats" "/var/www/virtualhosts/felines/htdocs"
The use of
mod_rewrite to perform this mapping may be
appropriate when you do not have access to the server configuration
files. Alias may only be used in server or virtualhost context, and not
Symbolic links would be another way to accomplish the same thing, if
Options FollowSymLinks enabled on your
Although it is possible to handle virtual hosts
with mod_rewrite, it is seldom the right way. Creating individual
<VirtualHost> blocks is
almost always the right way to go. In the
event that you have an enormous number of virtual hosts, consider using
mod_vhost_alias to create these hosts automatically.
Modules such as
also useful for creating a large number of virtual hosts dynamically.
mod_rewrite for vitualhost creation may be
appropriate if you are using a hosting service that does not provide
you access to the server configuration files, and you are therefore
restricted to configuration using
See the virtual hosts with mod_rewrite document for more details on how you might accomplish this if it still seems like the right approach.
RewriteRule provides the [P] flag to pass rewritten URIs through
RewriteRule "^/?images(.*)" "http://imageserver.local/images$1" [P]
However, in many cases, when there is no actual pattern matching
needed, as in the example shown above, the
ProxyPass directive is a better choice.
The example here could be rendered as:
ProxyPass "/images/" "http://imageserver.local/images/"
Note that whether you use
ProxyPass, you'll still need to use the
ProxyPassReverse directive to
catch redirects issued from the back-end server:
ProxyPassReverse "/images/" "http://imageserver.local/images/"
You may need to use
RewriteRule instead when there are
RewriteRules in effect in the same scope, as a
RewriteRule will usually take effect before a
ProxyPass, and so may preempt what you're trying to
mod_rewrite is frequently used to take a particular
action based on the presence or absence of a particular environment
variable or request header. This can be done more efficiently using the
Consider, for example, the common scenario where
RewriteRule is used to enforce a canonical
hostname, such as
www.example.com instead of
example.com. This can be done using the
<If> directive, as shown here:
<If "req('Host') != 'www.example.com'"> Redirect "/" "http://www.example.com/" </If>
This technique can be used to take actions based on any request
header, response header, or environment variable, replacing
mod_rewrite in many common scenarios.
See especially the expression evaluation
documentation for a overview of what types of expressions you can
and in certain other directives.