About this Module
Summary of FunctionalityThe 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.
- fully-qualified URIs
- new URLs
- filepaths, which can contain so-called QUERY_STRING parts.
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:
This consistent usage is provided for maximum flexibility. But there is a slight difference between situations 1 & 2 and 3 & 4:
- 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.
- 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.
- 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.
- 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 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!
- In situation 1 & 2 the context is global hence the rule patterns get applied to the full URLs and the substitutions have to create full URLs.
- In situation 3 & 3 the context is local hence the rule patterns get applied only to the remainder of the URL. This remainder is just the URL with the per-directory prefix stripped off. The same thing applies to the substitutions: they should (but they have not) create remainders which automatically will completed to full URLs by adding the previously stripped prefix.
New FeaturesThe 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:
- URLs can be re-written in any number of steps instead of just translated once to the final result.
- URLs can be changed in any way instead of just substituted through a simple prefix match.
- The full power of regular expressions can be used for rewriting instead of simple substring substitution
- The substitutions of a rewriting rule can contain a
QUERY_STRINGpart, i.e. "
?key=value&key=value&...". If such a part occurs, the module automatically splits it away from the URL and injects it into the current Apache-internal request information, just as it was coming from the original request.
- You can use rule conditions not only to rewrite according to a pattern which has to match the current URI/URL. You can additionally match (also via regular expression patterns) a lot of server-variables which include most of the HTTP headers. With this you can rewrite according to the browser type or identified user and host, etc.
- URIs (i.e. URLs plus protocol, host and port) can be generated instead of just URLs. Additionally when those occur the module automatically forces a request redirection, so you do not have to differentiate between pure rewritings and rewriting with redirection as in the old Alias and Redirect directives.
- You can force a URI to be put through the proxy module internally. This is a sort of an super-enhanced ProxyPass directive, because it enables some special tricks. For instance, to proxy away only some files of a directory, etc.
- Mapping-functions can be used inside the substitution strings to insert looked-up values by means of external databases. These external databases can be either plain text files, DBM hashfiles or even programs which act like dynamic maps.
- Server-variables (the same as in the condition strings of the rule conditions) can be used to insert values into the rule substitution by means of the current internal Apache state of these variables.
- Exhaustive logging is provided for all rewriting actions. This is very useful for the webmaster to see how the rewriting rules are applied and what result is generated by these rules. You can set the amount of verbosity for this logging.
- The rewriting rules can be used both globally inside the server configuration (httpd.conf) and locally in per-directory configuration files (.htaccess).
- Through the use of rewrite rule flags many special URL rewriting features can be configured. There is support for rewriting loops, rewriting breaks, pseudo-if-then-else constructs, chained rules, forced MIME-types, forced proxy-throughputs, etc.
- Two additional new CGI/SSI environment variables named SCRIPT_URL and SCRIPT_URI are provided which contain the original (i.e. previous to any rewritings!) Web-view to the current resource.
Side EffectsYou 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 VersionsAlthough 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.