Getting started with mod-rewrite

Remarks#

mod_rewrite is a module for Apache. This module is used for internal rewrites (external requests that should load a different resource) and external redirects (external requests that should make the client request a different url).

mod_rewrite provides a finer control over internal rewrites than mod_alias, as the latter can only map requests to filenames. mod_rewrite provides some means of access control, but this is usually better done with mod_authz_core and mod_authz_host. mod_rewrite provides some integration with mod_proxy, but for performance reasons this integration should not be used and instead ProxyPass and ProxyPassMatch of the latter module should be used.

mod_rewrite can be set up in a way that allows for directives to be placed in the dynamic (.htaccess) configuration files. For performance reasons, one should always use the static (httpd.conf) configuration file whenever possible.

Versions#

Installation

mod_rewrite must be enabled before being used on an Apache server.

Debian/Ubuntu

Run a2enmod rewrite

Then restart Apache with service apache2 restart

General case

Add or uncomment the following line in the static configuration file (such as httpd.conf):

LoadModule rewrite_module modules/mod_rewrite.so

Then restart Apache.

Using mod_rewrite in the static configuration file

Add the following directive before using any other mod_rewrite directive (RewriteRule, RewriteCond, RewriteBase or RewriteMap).

RewriteEngine on

By default the engine is turned off. mod_rewrite directives found while the engine is turned off are ignored. Enable it from within the virtual host context when using virtual hosts, or from specific directory contexts when applicable.

Using mod_rewrite from the dynamic configuration files

Important: Using the dynamic configuration files (.htaccess) is a big performance hit. When you have access to the static configuration file (httpd.conf or something similar) you should use that instead.

In the static configuration file, allow dynamic configuration files to override “Fileinfo” using AllowOverride. This directive must be placed in directory context:

AllowOverride FileInfo

The filename used for dynamic configuration files is governed by the AccessFileName directive. By default, the dynamic configuration files are hidden files called .htaccess.

At the top of each dynamic configuration file containing mod_rewrite directives, add the following directive:

RewriteEngine on