About this Module

Summary of Functionality

The Apache webserver API (application programmers interface) has a hook (an entry point) for URL-to-filename translation which is primarily used by this module to link itself into the server. For every request, this module is called with the requested URL (or even with an URI in a proxy-context) and has the chance to re-write this request just before the Apache server continues with all following processing steps, like running the hooks of the other modules, etc.

It's rewriting engine is rule-based where a rule primarily consists of a rewriting pattern and a rewriting substitution. The patterns are full regular expressions, as commonly known in the Unix community. They are applied to the current value of the URL.

The substitutions replace the current URL value of the pattern matched and are either:

Additionally these substitutions can have in-lined mapping-function expressions to lookup external databases (either plain text, DBM hashfile or even programs which act like a map) and hence can include strings from external sources.

Finally the rule flags can control the behaviour after a rewriting rule has been matched. There is support for rewriting loops, rewriting breaks, chained rules, pseudo if-then-else constructs, forced redirects, forced MIME-types, forced proxy-module throughput etc.

When a URL expands to a non-self-referencing URI by means of a substitution, it will automatically lead to an external request redirection at the end of the rewriting process. If the generated URI is self-referencing (i.e. http://thishost[:thisport]), then this automatically gets stripped down to a URL. This provides support for so-called webclusters with homogeneous URL trees.

Optionally, any rewriting rule can be preceded by any number of additional rewriting conditions. These are pairs of condition strings (which can be constructed out of a rich set of variables) and condition patterns. The condition patterns are again regular expressions and get matched against the runtime-evaluated condition string. Preceding a rule with such conditions mean that the rule is only fully applied if the rule pattern matches and all of the preceding rule conditions do so as well. This gives you a flexible way to adjust the situation in which your rules are applied.

This functionality can be used in four contexts:

  1. Used by the administrator inside the server config file (httpd.conf) for global per-server context outside of any VirtualHost blocks.
    Here the rules are applied to all URLs, i.e. to all URLs of the main server and all URLs of the virtual servers.

  2. Used by the administrator inside the server config file (httpd.conf) for global per-server context inside of any VirtualHost blocks.
    Here the rules are applied only to URLs of a specific virtual server.

  3. Used by the administrator inside the server config file (httpd.conf) for local per-directory context inside of any Directory blocks.
    Here the rules are applied only to URLs for the specific directory.

  4. Used by the users inside their directory config files (.htaccess) for local per-directory context.
    Here the rules are applied only to URLs for the specific directory.
This consistent usage is provided for maximum flexibility. But there is a slight difference between situations 1 & 2 and 3 & 4: This difference is subtle but very important, because only this way it is possibly to do a lot of special rewriting tricks in the per-directory context!

New Features

The URL rewriting module adds a lot of new features to the Apache server which are not possible with the aliasing and rewriting mechanism provided by the standard functionality inherited from the NCSA webserver. These are listed where:

Side Effects

You can safely compile mod_rewrite into the Apache server, because this module is only triggered with its server configuration directives.

Only the RewriteRule directive is a runtime one and causes URL rewriting actions to really happen, and then only if the RewriteEngine on directive is used too. In other words: Unless you set "RewriteEngine on" there are no side effects!

Tested Apache Versions

Although this module's history starts with the Apache 1.0 API in February 1996, it was moved to the Apache 1.1 API very early. This means it will NOT run with any Apache server prior to 1.1b0!

It runs fine with any beta release of Apache 1.1 and (of course) with the current official release: Apache 1.1.1. If you want to use this module but still have an older version of the Apache server running, please upgrade first!

From version 2.1 mod_rewrite has support for Apache version 1.2-dev which already has its own POSIX library included.