Apache Module mod_rewrite

Available Languages: en

+ + + + +

Description:	Provides a rule-based rewriting engine to rewrite requested +URLs on the fly
Status:	Extension
Module Identifier:	rewrite_module
Source File:	mod_rewrite.c
Compatibility:	Available in Apache 1.3 and later

Summary

+ +

This module uses a rule-based rewriting engine (based on a + regular-expression parser) to rewrite requested URLs on the + fly. It supports an unlimited number of rules and an + unlimited number of attached rule conditions for each rule, to + provide a really flexible and powerful URL manipulation + mechanism. The URL manipulations can depend on various tests, + of server variables, environment variables, HTTP + headers, or time stamps. Even external database lookups in + various formats can be used to achieve highly granular URL + matching.

+ +

This module operates on the full URLs (including the + path-info part) both in per-server context + (httpd.conf) and per-directory context + (.htaccess) and can generate query-string + parts on result. The rewritten result can lead to internal + sub-processing, external request redirection or even to an + internal proxy throughput.

+ +

Further details, discussion, and examples, are provided in the + detailed mod_rewrite documentation.

Topics

API Phases
Ruleset Processing
Regex Back-Reference Availability
Quoting Special Characters
Environment Variables
Practical Solutions

API Phases

+ +

Apache processes a HTTP request in several phases. + A hook for each of these + phases is provided by the Apache API. mod_rewrite uses two of + these hooks: the URL-to-filename translation hook + (used after the HTTP request has been read, but before any + authorization starts) and the Fixup hook (triggered + after the authorization phases, and after the per-directory + config files (.htaccess) have been read, but + before the content handler is activated).

+ +

Once a request comes in, and Apache has determined the + appropriate server (or virtual server), the rewrite engine + starts the URL-to-filename translation, + processing the mod_rewrite directives from the + per-server configuration. A few + steps later, when the final data directories are found, the + per-directory configuration directives of mod_rewrite are + triggered in the Fixup phase.

+ +

Ruleset Processing

+ +

When mod_rewrite is triggered during these two API phases, it + reads the relevant rulesets from its configuration + structure (which was either created on startup, for + per-server context, or during the directory traversal + for per-directory context). The URL rewriting + engine is started with the appropriate ruleset (one or more + rules together with their conditions), and its operation + is exactly the same for both + configuration contexts. Only the final result processing is + different.

+ +

The order of rules in the ruleset is important because the + rewrite engine processes them in a particular (not always + obvious) order, as follows: The rewrite engine loops + through the rulesets (each ruleset being made up of RewriteRule directives, with or without + RewriteConds), rule by rule. + When a particular rule is matched, mod_rewrite + also checks the corresponding conditions (RewriteCond + directives). For historical reasons the conditions are given + first, making the control flow a little bit long-winded. See + Figure 1 for more details.

+ [Needs graphics capability to display]
+ Figure 1:The control flow of the rewrite engine through a + rewrite ruleset +

As above, first the URL is matched against the + Pattern of a rule. If it does not match, mod_rewrite immediately stops processing that rule, + and goes on to the next rule. If the Pattern matches, + mod_rewrite checks for rule conditions. + If none are present, the URL will be replaced with a new string, + constructed from the Substitution string, and mod_rewrite goes on to the next rule.

If RewriteConds exist, an + inner loop is started, processing them in the order that they are + listed. Conditions are not matched against the current URL directly. + A TestString is constructed by expanding variables, + back-references, map lookups, etc., against which the + CondPattern is matched. If the pattern fails to match one + of the conditions, the complete set of rule and associated conditions + fails. If the pattern matches a given condition, then matching continues + to the next condition, until no more conditions are + available. If all conditions match, processing is continued + with the substitution of the Substitution string for the URL.

+ +

Regex Back-Reference Availability

+ +

Using parentheses in Pattern or in one of the + CondPatterns causes back-references to be internally + created. + These can later be referenced using the strings $N and + %N (see below), for creating + the Substitution and TestString strings. + Figure 2 attempts to show how the back-references are + transferred through the process for later expansion.

+ +

+ [Needs graphics capability to display]
+ Figure 2: The back-reference flow through a rule. +

Quoting Special Characters

+ +

As of Apache 1.3.20, special characters in + TestString and Substitution strings can be + escaped (that is, treated as normal characters without their + usual special meaning) by prefixing them with a backslash ('\') + character. In other words, you can include an actual + dollar-sign character in a Substitution string by + using '\$'; this keeps mod_rewrite from trying + to treat it as a backreference.

Environment Variables

+ +

This module keeps track of two additional (non-standard) + CGI/SSI environment variables named SCRIPT_URL + and SCRIPT_URI. These contain the + logical Web-view to the current resource, while the + standard CGI/SSI variables SCRIPT_NAME and + SCRIPT_FILENAME contain the physical + System-view.

+ +

Notice: These variables hold the URI/URL as they were + initially requested, that is, before any + rewriting. This is important to note because the rewriting process is + primarily used to rewrite logical URLs to physical + pathnames.

+ +

Example

+SCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
+SCRIPT_FILENAME=/u/rse/.www/index.html
+SCRIPT_URL=/u/rse/
+SCRIPT_URI=http://en1.engelschall.com/u/rse/
+

+ +

Practical Solutions

+ +

For numerous examples of common, and not-so-common, uses for + mod_rewrite, see the Rewrite + Guide, and the Advanced Rewrite + Guide documents.

+ +

RewriteBase Directive

+ + + + + + + + +

Description:	Sets the base URL for per-directory rewrites
Syntax:	`RewriteBase URL-path`
Default:	`See usage for information.`
Context:	directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_rewrite

The RewriteBase directive explicitly + sets the base URL for per-directory rewrites. As you will see + below, RewriteRule + can be used in per-directory config files + (.htaccess). In such a case, it will act locally, + stripping the local directory prefix before processing, and applying + rewrite rules only to the remainder. When processing is complete, the + prefix is automatically added back to the + path. The default setting is; RewriteBase physical-directory-path

+ +

When a substitution occurs for a new URL, this module has + to re-inject the URL into the server processing. To be able + to do this it needs to know what the corresponding URL-prefix + or URL-base is. By default this prefix is the corresponding + filepath itself. However, for most websites, URLs are NOT + directly related to physical filename paths, so this + assumption will often be wrong! Therefore, you can + use the RewriteBase directive to specify the + correct URL-prefix.

+ +

If your webserver's URLs are not directly +related to physical file paths, you will need to use +RewriteBase in every .htaccess +file where you want to use RewriteRule directives. +

+ +

For example, assume the following per-directory config file:

+ +

+#
+#  /abc/def/.htaccess -- per-dir config file for directory /abc/def
+#  Remember: /abc/def is the physical path of /xyz, i.e., the server
+#            has a 'Alias /xyz /abc/def' directive e.g.
+#
+
+RewriteEngine On
+
+#  let the server know that we were reached via /xyz and not
+#  via the physical path prefix /abc/def
+RewriteBase   /xyz
+
+#  now the rewriting rules
+RewriteRule   ^oldstuff\.html$  newstuff.html
+

+ +

In the above example, a request to + /xyz/oldstuff.html gets correctly rewritten to + the physical file /abc/def/newstuff.html.

+ +

For Apache Hackers

The following list gives detailed information about + the internal processing steps:

+Request:
+  /xyz/oldstuff.html
+
+Internal Processing:
+  /xyz/oldstuff.html     -> /abc/def/oldstuff.html  (per-server Alias)
+  /abc/def/oldstuff.html -> /abc/def/newstuff.html  (per-dir    RewriteRule)
+  /abc/def/newstuff.html -> /xyz/newstuff.html      (per-dir    RewriteBase)
+  /xyz/newstuff.html     -> /abc/def/newstuff.html  (per-server Alias)
+
+Result:
+  /abc/def/newstuff.html
+

This seems very complicated, but is in fact + correct Apache internal processing. Because the + per-directory rewriting comes late in the + process, the rewritten request + has to be re-injected into the Apache kernel, as if it + were a new request. (See mod_rewrite technical + details.) + This is not the serious overhead it may seem to be - + this re-injection is completely internal to the + Apache server (and the same procedure is used by + many other operations within Apache).

+ + +

RewriteCond Directive

+ + + + + + + +

Description:	Defines a condition under which rewriting will take place +
Syntax:	`RewriteCond + TestString CondPattern`
Context:	server config, virtual host, directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_rewrite

The RewriteCond directive defines a + rule condition. One or more RewriteCond + can precede a RewriteRule + directive. The following rule is then only used if both + the current state of the URI matches its pattern, and if these conditions are met.

+ +

TestString is a string which can contain the + following expanded constructs in addition to plain text:

+ +

+ RewriteRule backreferences: These are + backreferences of the form $N + (0 <= N <= 9), which provide access to the grouped + parts (in parentheses) of the pattern, from the + RewriteRule which is subject to the current + set of RewriteCond conditions.. +
+ RewriteCond backreferences: These are + backreferences of the form %N + (1 <= N <= 9), which provide access to the grouped + parts (again, in parentheses) of the pattern, from the last matched + RewriteCond in the current set + of conditions. +
+ RewriteMap expansions: These are + expansions of the form ${mapname:key|default}. + See the documentation for + RewriteMap for more details. +

+ Server-Variables: These are variables of + the form + %{ NAME_OF_VARIABLE + } + where NAME_OF_VARIABLE can be a string taken + from the following list: + + + + + + + + + + + + + + + + + + + + + + + + +

HTTP headers:	connection & request:	+
+ HTTP_USER_AGENT + HTTP_REFERER + HTTP_COOKIE + HTTP_FORWARDED + HTTP_HOST + HTTP_PROXY_CONNECTION + HTTP_ACCEPT +	+ REMOTE_ADDR + REMOTE_HOST + REMOTE_PORT + REMOTE_USER + REMOTE_IDENT + REQUEST_METHOD + SCRIPT_FILENAME + PATH_INFO + QUERY_STRING + AUTH_TYPE +	+
server internals:	system stuff:	specials:
+ DOCUMENT_ROOT + SERVER_ADMIN + SERVER_NAME + SERVER_ADDR + SERVER_PORT + SERVER_PROTOCOL + SERVER_SOFTWARE +	+ TIME_YEAR + TIME_MON + TIME_DAY + TIME_HOUR + TIME_MIN + TIME_SEC + TIME_WDAY + TIME +	+ API_VERSION + THE_REQUEST + REQUEST_URI + REQUEST_FILENAME + IS_SUBREQ + HTTPS +

+ +

These variables all + correspond to the similarly named HTTP + MIME-headers, C variables of the Apache server or + struct tm fields of the Unix system. + Most are documented elsewhere in the Manual or in + the CGI specification. Those that are special to + mod_rewrite include those below.

IS_SUBREQ: Will contain the text "true" if the request + currently being processed is a sub-request, + "false" otherwise. Sub-requests may be generated + by modules that need to resolve additional files + or URIs in order to complete their tasks.
API_VERSION: This is the version of the Apache module API + (the internal interface between server and + module) in the current httpd build, as defined in + include/ap_mmn.h. The module API version + corresponds to the version of Apache in use (in + the release version of Apache 1.3.14, for + instance, it is 19990320:10), but is mainly of + interest to module authors.
THE_REQUEST: The full HTTP request line sent by the + browser to the server (e.g., "GET + /index.html HTTP/1.1"). This does not + include any additional headers sent by the + browser.
REQUEST_URI: The resource requested in the HTTP request + line. (In the example above, this would be + "/index.html".)
REQUEST_FILENAME: The full local filesystem path to the file or + script matching the request.
HTTPS: Will contain the text "on" if the connection is + using SSL/TLS, or "off" otherwise. (This variable + can be safely used regardless of whether or not + mod_ssl is loaded).

+ +

Other things you should be aware of:

+ +

The variables SCRIPT_FILENAME and REQUEST_FILENAME + contain the same value - the value of the + filename field of the internal + request_rec structure of the Apache server. + The first name is the commonly known CGI variable name + while the second is the appropriate counterpart of + REQUEST_URI (which contains the value of the + uri field of request_rec).
+ %{ENV:variable}, where variable can be + any environment variable, is also available. + This is looked-up via internal + Apache structures and (if not found there) via + getenv() from the Apache server process.
+ %{SSL:variable}, where variable is the + name of an SSL environment + variable, can be used whether or not + mod_ssl is loaded, but will always expand to + the empty string if it is not. Example: + %{SSL:SSL_CIPHER_USEKEYSIZE} may expand to + 128.
+ %{HTTP:header}, where header can be + any HTTP MIME-header name, can always be used to obtain the + value of a header sent in the HTTP request. + Example: %{HTTP:Proxy-Connection} is + the value of the HTTP header + ``Proxy-Connection:''.
+ %{LA-U:variable} can be used for look-aheads which perform + an internal (URL-based) sub-request to determine the final + value of variable. This can be used to access + variable for rewriting which is not available at the current + stage, but will be set in a later phase. +
For instance, to rewrite according to the + REMOTE_USER variable from within the + per-server context (httpd.conf file) you must + use %{LA-U:REMOTE_USER} - this + variable is set by the authorization phases, which come + after the URL translation phase (during which mod_rewrite + operates).
+
On the other hand, because mod_rewrite implements + its per-directory context (.htaccess file) via + the Fixup phase of the API and because the authorization + phases come before this phase, you just can use + %{REMOTE_USER} in that context.
+ %{LA-F:variable} can be used to perform an internal + (filename-based) sub-request, to determine the final value + of variable. Most of the time, this is the same as + LA-U above.

+ +

CondPattern is the condition pattern, + a regular expression which is applied to the + current instance of the TestString. + TestString is first evaluated, before being matched against + CondPattern.

+ +

Remember: CondPattern is a + perl compatible regular expression with some + additions:

+ +

You can prefix the pattern string with a + '!' character (exclamation mark) to specify a + non-matching pattern.
+ There are some special variants of CondPatterns. + Instead of real regular expression strings you can also + use one of the following: + +
- '<CondPattern' (lexicographically + precedes)
  + Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString lexicographically precedes + CondPattern.
- '>CondPattern' (lexicographically + follows)
  + Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString lexicographically follows + CondPattern.
- '=CondPattern' (lexicographically + equal)
  + Treats the CondPattern as a plain string and + compares it lexicographically to TestString. True if + TestString is lexicographically equal to + CondPattern (the two strings are exactly + equal, character for character). If CondPattern + is "" (two quotation marks) this + compares TestString to the empty string.
- '-d' (is + directory)
  + Treats the TestString as a pathname and tests + whether or not it exists, and is a directory.
- '-f' (is regular + file)
  + Treats the TestString as a pathname and tests + whether or not it exists, and is a regular file.
- '-s' (is regular file, with + size)
  + Treats the TestString as a pathname and tests + whether or not it exists, and is a regular file with size greater + than zero.
- '-l' (is symbolic + link)
  + Treats the TestString as a pathname and tests + whether or not it exists, and is a symbolic link.
- '-F' (is existing file, via + subrequest)
  + Checks whether or not TestString is a valid file, + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to do the check, so use it with care - + it can impact your server's performance!
- '-U' (is existing URL, via + subrequest)
  + Checks whether or not TestString is a valid URL, + accessible via all the server's currently-configured + access controls for that path. This uses an internal + subrequest to do the check, so use it with care - + it can impact your server's performance!
+ +
Note
+ All of these tests can + also be prefixed by an exclamation mark ('!') to + negate their meaning. +
+
You can also set special flags for + CondPattern by appending + [flags] + as the third argument to the RewriteCond + directive, where flags is a comma-separated list of any of the + following flags: + +
- 'nocase|NC' + (no case)
  + This makes the test case-insensitive - differences + between 'A-Z' and 'a-z' are ignored, both in the + expanded TestString and the CondPattern. + This flag is effective only for comparisons between + TestString and CondPattern. It has no + effect on filesystem and subrequest checks.
- + 'ornext|OR' + (or next condition)
  + Use this to combine rule conditions with a local OR + instead of the implicit AND. Typical example: + +
```
+RewriteCond %{REMOTE_HOST}  ^host1.*  [OR]
+RewriteCond %{REMOTE_HOST}  ^host2.*  [OR]
+RewriteCond %{REMOTE_HOST}  ^host3.*
+RewriteRule ...some special stuff for any of these hosts...
+
```
  + + Without this flag you would have to write the condition/rule + pair three times. +
+

+ +

Example:

+ +

To rewrite the Homepage of a site according to the + ``User-Agent:'' header of the request, you can + use the following:

+ +

+RewriteCond  %{HTTP_USER_AGENT}  ^Mozilla.*
+RewriteRule  ^/$                 /homepage.max.html  [L]
+
+RewriteCond  %{HTTP_USER_AGENT}  ^Lynx.*
+RewriteRule  ^/$                 /homepage.min.html  [L]
+
+RewriteRule  ^/$                 /homepage.std.html  [L]
+

+ +

Explanation: If you use a browser which identifies itself + as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you + get the max homepage (which could include frames, or other special + features). + If you use the Lynx browser (which is terminal-based), then + you get the min homepage (which could be a version designed for + easy, text-only browsing). + If neither of these conditions apply (you use any other browser, + or your browser identifies itself as something non-standard), you get + the std (standard) homepage.

+ + +

RewriteEngine Directive

+ + + + + + + + +

Description:	Enables or disables runtime rewriting engine
Syntax:	`RewriteEngine on\|off`
Default:	`RewriteEngine off`
Context:	server config, virtual host, directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_rewrite

+ +

The RewriteEngine directive enables or + disables the runtime rewriting engine. If it is set to + off this module does no runtime processing at + all. It does not even update the SCRIPT_URx + environment variables.

+ +

Use this directive to disable the module instead of + commenting out all the RewriteRule directives!

+ +

Note that, by default, rewrite configurations are not + inherited. This means that you need to have a + RewriteEngine on directive for each virtual host + in which you wish to use it.

+ +

RewriteMap directives of the type prg + are not started during server initialization if they're defined in a + context that does not have RewriteEngine set to + on

+ + +

RewriteLock Directive

+ + + + + + +

Description:	Sets the name of the lock file used for `RewriteMap` +synchronization
Syntax:	`RewriteLock file-path`
Context:	server config
Status:	Extension
Module:	mod_rewrite

This directive sets the filename for a synchronization + lockfile which mod_rewrite needs to communicate with RewriteMap + programs. Set this lockfile to a local path (not on a + NFS-mounted device) when you want to use a rewriting + map-program. It is not required for other types of rewriting + maps.

+ +

RewriteLog Directive

+ + + + + + +

Description:	Sets the name of the file used for logging rewrite engine +processing
Syntax:	`RewriteLog file-path`
Context:	server config, virtual host
Status:	Extension
Module:	mod_rewrite

The RewriteLog directive sets the name + of the file to which the server logs any rewriting actions it + performs. If the name does not begin with a slash + ('/') then it is assumed to be relative to the + Server Root. The directive should occur only once per + server config.

+ +

To disable the logging of + rewriting actions it is not recommended to set + Filename to /dev/null, because + although the rewriting engine does not then output to a + logfile it still creates the logfile output internally. + This will slow down the server with no advantage + to the administrator! To disable logging either + remove or comment out the RewriteLog + directive or use RewriteLogLevel 0! +

+ +

Security

+ +See the Apache Security Tips +document for details on how your security could be compromised if the +directory where logfiles are stored is writable by anyone other than +the user that starts the server. +

+ +

Example

+RewriteLog "/usr/local/var/apache/logs/rewrite.log" +

+ + +

RewriteLogLevel Directive

+ + + + + + + +

Description:	Sets the verbosity of the log file used by the rewrite +engine
Syntax:	`RewriteLogLevel Level`
Default:	`RewriteLogLevel 0`
Context:	server config, virtual host
Status:	Extension
Module:	mod_rewrite

The RewriteLogLevel directive sets the + verbosity level of the rewriting logfile. The default level 0 + means no logging, while 9 or more means that practically all + actions are logged.

+ +

To disable the logging of rewriting actions simply set + Level to 0. This disables all rewrite action + logs.

+ +

Using a high value for + Level will slow down your Apache server + dramatically! Use the rewriting logfile at a + Level greater than 2 only for debugging! +

+ +

Example

+RewriteLogLevel 3 +

+ + +

RewriteMap Directive

+ + + + + + + +

Description:	Defines a mapping function for key-lookup
Syntax:	`RewriteMap MapName MapType:MapSource +`
Context:	server config, virtual host
Status:	Extension
Module:	mod_rewrite
Compatibility:	The choice of different dbm types is available in +Apache 2.0.41 and later

The RewriteMap directive defines a + Rewriting Map which can be used inside rule + substitution strings by the mapping-functions to + insert/substitute fields through a key lookup. The source of + this lookup can be of various types.

+ +

The MapName is + the name of the map and will be used to specify a + mapping-function for the substitution strings of a rewriting + rule via one of the following constructs:

+ +

+ ${ MapName : + LookupKey }
+ ${ MapName : + LookupKey | DefaultValue + } +

+ +

When such a construct occurs, the map MapName is + consulted and the key LookupKey is looked-up. If the + key is found, the map-function construct is substituted by + SubstValue. If the key is not found then it is + substituted by DefaultValue or by the empty string + if no DefaultValue was specified.

+ +

For example, you might define a + RewriteMap as:

+ +

+ RewriteMap examplemap txt:/path/to/file/map.txt +

+ +

You would then be able to use this map in a + RewriteRule as follows:

+ +

+ RewriteRule ^/ex/(.*) ${examplemap:$1} +

+ +

The following combinations for MapType and + MapSource can be used:

+ +

+ Standard Plain Text
+ MapType: txt, MapSource: Unix filesystem + path to valid regular file + +
This is the standard rewriting map feature where the + MapSource is a plain ASCII file containing + either blank lines, comment lines (starting with a '#' + character) or pairs like the following - one per + line.
+ +
+ MatchingKey + SubstValue +
+ +
Example
```
+##
+##  map.txt -- rewriting map
+##
+
+Ralf.S.Engelschall    rse   # Bastard Operator From Hell
+Mr.Joe.Average        joe   # Mr. Average
+
```
+ +
+RewriteMap real-to-user txt:/path/to/file/map.txt +
+
+ Randomized Plain Text
+ MapType: rnd, MapSource: Unix filesystem + path to valid regular file + +
This is identical to the Standard Plain Text variant + above but with a special post-processing feature: After + looking up a value it is parsed according to contained + ``|'' characters which have the meaning of + ``or''. In other words they indicate a set of + alternatives from which the actual returned value is + chosen randomly. For example, you might use the following map + file and directives to provide a random load balancing between + several back-end server, via a reverse-proxy. Images are sent + to one of the servers in the 'static' pool, while everything + else is sent to one of the 'dynamic' pool.
+
Example:
+ +
Rewrite map file
```
+##
+##  map.txt -- rewriting map
+##
+
+static   www1|www2|www3|www4
+dynamic  www5|www6
+
```
+ +
Configuration directives
+RewriteMap servers rnd:/path/to/file/map.txt + +RewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1 +[NC,P,L] +RewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L] +
+
+ Hash File
MapType: + dbm[=type], MapSource: Unix filesystem + path to valid regular file + +
Here the source is a binary format DBM file containing + the same contents as a Plain Text format file, but + in a special representation which is optimized for really + fast lookups. The type can be sdbm, gdbm, ndbm, or + db depending on compile-time + settings. If the type is ommitted, the + compile-time default will be chosen. You can create such a + file with any DBM tool or with the following Perl + script. Be sure to adjust it to create the appropriate + type of DBM. The example creates an NDBM file.
+ +
```
+#!/path/to/bin/perl
+##
+##  txt2dbm -- convert txt map to dbm format
+##
+
+use NDBM_File;
+use Fcntl;
+
+($txtmap, $dbmmap) = @ARGV;
+
+open(TXT, "<$txtmap") or die "Couldn't open $txtmap!\n";
+tie (%DB, 'NDBM_File', $dbmmap,O_RDWR|O_TRUNC|O_CREAT, 0644)
+  or die "Couldn't create $dbmmap!\n";
+
+while (<TXT>) {
+  next if (/^\s*#/ or /^\s*$/);
+  $DB{$1} = $2 if (/^\s*(\S+)\s+(\S+)/);
+}
+
+untie %DB;
+close(TXT);
+
```
+ +
+$ txt2dbm map.txt map.db +
+
+ Internal Function
+ MapType: int, MapSource: Internal Apache + function + +
Here, the source is an internal Apache function. + Currently you cannot create your own, but the following + functions already exist:
+ +
- toupper:
  + Converts the key to all upper case.
- tolower:
  + Converts the key to all lower case.
- escape:
  + Translates special characters in the key to + hex-encodings.
- unescape:
  + Translates hex-encodings in the key back to + special characters.
+
+ External Rewriting Program
+ MapType: prg, MapSource: Unix filesystem + path to valid regular file + +
Here the source is a program, not a map file. To + create it you can use a language of your choice, but + the result has to be an executable program (either + object-code or a script with the magic cookie trick + '#!/path/to/interpreter' as the first + line).
+ +
This program is started once, when the Apache server + is started, and then communicates with the rewriting engine + via its stdin and stdout + file-handles. For each map-function lookup it will + receive the key to lookup as a newline-terminated string + on stdin. It then has to give back the + looked-up value as a newline-terminated string on + stdout or the four-character string + ``NULL'' if it fails (i.e., there + is no corresponding value for the given key). A trivial + program which will implement a 1:1 map (i.e., + key == value) could be:
+ +
External rewriting programs are not started if they're defined in a + context that does not have RewriteEngine set to + on
. + +
```
+#!/usr/bin/perl
+$| = 1;
+while (<STDIN>) {
+    # ...put here any transformations or lookups...
+    print $_;
+}
+
```
+ +
But be very careful:
+ +
1. ``Keep it simple, stupid'' (KISS). + If this program hangs, it will cause Apache to hang + when trying to use the relevant rewrite rule.
2. A common mistake is to use buffered I/O on + stdout. Avoid this, as it will cause a deadloop! + ``$|=1'' is used above, to prevent this.
3. The RewriteLock directive can + be used to define a lockfile which mod_rewrite can use to synchronize + communication with the mapping program. By default no such + synchronization takes place.
+

The RewriteMap directive can occur more than + once. For each mapping-function use one + RewriteMap directive to declare its rewriting + mapfile. While you cannot declare a map in + per-directory context it is of course possible to + use this map in per-directory context.

+ +

Note

For plain text and DBM format files the +looked-up keys are cached in-core until the mtime of the +mapfile changes or the server does a restart. This way you can have +map-functions in rules which are used for every +request. This is no problem, because the external lookup only happens +once! +

+ + +

RewriteOptions Directive

+ + + + + + + + + +

Description:	Sets some special options for the rewrite engine
Syntax:	`RewriteOptions Options`
Default:	`RewriteOptions MaxRedirects=10`
Context:	server config, virtual host, directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_rewrite
Compatibility:	`MaxRedirects` is available in Apache 2.0.45 and +later

+ +

The RewriteOptions directive sets some + special options for the current per-server or per-directory + configuration. The Option strings can be one of the + following:

+ +

inherit: This forces the current configuration to inherit the + configuration of the parent. In per-virtual-server context + this means that the maps, conditions and rules of the main + server are inherited. In per-directory context this means + that conditions and rules of the parent directory's + .htaccess configuration are inherited.
MaxRedirects=number: In order to prevent endless loops of internal redirects + issued by per-directory RewriteRules, mod_rewrite aborts + the request after reaching a maximum number of such redirects and + responds with an 500 Internal Server Error. If you really need + more internal redirects than 10 per request, you may increase + the default to the desired value.

+ +

RewriteRule Directive

+ + + + + + + + +

Description:	Defines rules for the rewriting engine
Syntax:	`RewriteRule + Pattern Substitution`
Context:	server config, virtual host, directory, .htaccess
Override:	FileInfo
Status:	Extension
Module:	mod_rewrite
Compatibility:	The cookie-flag is available in Apache 2.0.40 and later.

The RewriteRule directive is the real + rewriting workhorse. The directive can occur more than once, with + each instance defining a single rewrite rule. The + order in which these rules are defined is important - this is the order + in which they will be applied at run-time.

+ +

Pattern is + a perl compatible regular + expression, which is applied to the current URL. + ``Current'' means the value of the URL when this rule is + applied. This may not be the originally requested URL, + which may already have matched a previous rule, and have + been altered.

+ +

Some hints on the syntax of regular expressions:

+ +

+Text:
+  .           Any single character
+  [chars]     Character class: Any character of the class ``chars''
+  [^chars]    Character class: Not a character of the class ``chars''
+  text1|text2 Alternative: text1 or text2
+
+Quantifiers:
+  ?           0 or 1 occurrences of the preceding text
+  *           0 or N occurrences of the preceding text (N > 0)
+  +           1 or N occurrences of the preceding text (N > 1)
+
+Grouping:
+  (text)      Grouping of text
+              (used either to set the borders of an alternative as above, or
+              to make backreferences, where the Nth group can
+              be referred to on the RHS of a RewriteRule as $N)
+
+Anchors:
+  ^           Start-of-line anchor
+  $           End-of-line anchor
+
+Escaping:
+  \char       escape the given char
+              (for instance, to specify the chars ".[]()" etc.)
+

+ +

For more information about regular expressions, have a look at the + perl regular expression manpage ("perldoc + perlre"). If you are interested in more detailed + information about regular expressions and their variants + (POSIX regex etc.) the following book is dedicated to this topic:

+ +

+ Mastering Regular Expressions, 2nd Edition
+ Jeffrey E.F. Friedl
+ O'Reilly & Associates, Inc. 2002
+ ISBN 0-596-00289-0
+

+ +

In mod_rewrite, the NOT character + ('!') is also available as a possible pattern + prefix. This enables you to negate a pattern; to say, for instance: + ``if the current URL does NOT match this + pattern''. This can be used for exceptional cases, where + it is easier to match the negative pattern, or as a last + default rule.

+ +

Note

+When using the NOT character to negate a pattern, you cannot include +grouped wildcard parts in that pattern. This is because, when the +pattern does NOT match (ie, the negation matches), there are no +contents for the groups. Thus, if negated patterns are used, you +cannot use $N in the substitution string! +

+ +

The substitution of a + rewrite rule is the string which is substituted for (or + replaces) the original URL which Pattern + matched. In addition to plain text, it can include

+ +

back-references ($N) to the RewriteRule + pattern
back-references (%N) to the last matched + RewriteCond pattern
server-variables as in rule condition test-strings + (%{VARNAME})
mapping-function calls + (${mapname:key|default})

+ +

Back-references are identifiers of the form + $N + (N=0..9), which will be replaced + by the contents of the Nth group of the + matched Pattern. The server-variables are the same + as for the TestString of a RewriteCond + directive. The mapping-functions come from the + RewriteMap directive and are explained there. + These three types of variables are expanded in the order above.

+ +

As already mentioned, all rewrite rules are + applied to the Substitution (in the order in which + they are defined + in the config file). The URL is completely + replaced by the Substitution and the + rewriting process continues until all rules have been applied, + or it is explicitly terminated by a + L flag - see below.

+ +

There is a special substitution string named + '-' which means: NO + substitution! This is useful in providing + rewriting rules which only match + URLs but do not substitute anything for them. It is commonly used + in conjunction with the C (chain) flag, in order + to apply more than one pattern before substitution occurs.

+ +

Additionally you can set special flags for Substitution by + appending [flags] + as the third argument to the RewriteRule + directive. Flags is a comma-separated list of any of the + following flags:

+ +

'chain|C' + (chained with next rule)
+ This flag chains the current rule with the next rule + (which itself can be chained with the following rule, + and so on). This has the following effect: if a rule + matches, then processing continues as usual - + the flag has no effect. If the rule does + not match, then all following chained + rules are skipped. For instance, it can be used to remove the + ``.www'' part, inside a per-directory rule set, + when you let an external redirect happen (where the + ``.www'' part should not occur!).
+ 'cookie|CO=NAME:VAL:domain[:lifetime[:path]]' + (set cookie)
+ This sets a cookie in the client's browser. The cookie's name + is specified by NAME and the value is + VAL. The domain field is the domain of the + cookie, such as '.apache.org', the optional lifetime + is the lifetime of the cookie in minutes, and the optional + path is the path of the cookie
+ 'env|E=VAR:VAL' + (set environment variable)
+ This forces an environment variable named VAR to + be set to the value VAL, where VAL can + contain regexp backreferences ($N and + %N) which will be expanded. You can use this + flag more than once, to set more than one variable. The + variables can later be dereferenced in many situations, most commonly + from within XSSI (via ) or CGI ($ENV{'VAR'}). + You can also dereference the variable in a later RewriteCond pattern, using + %{ENV:VAR}. Use this to strip + information from URLs, while maintaining a record of that information.
'forbidden|F' (force URL + to be forbidden)
+ This forces the current URL to be forbidden - it immediately + sends back a HTTP response of 403 (FORBIDDEN). + Use this flag in conjunction with + appropriate RewriteConds to conditionally block some + URLs.
'gone|G' (force URL to be + gone)
+ This forces the current URL to be gone - it + immediately sends back a HTTP response of 410 (GONE). Use + this flag to mark pages which no longer exist as gone.
'last|L' + (last rule)
+ Stop the rewriting process here and don't apply any more + rewrite rules. This corresponds to the Perl + last command or the break command + in C. Use this flag to prevent the currently + rewritten URL from being rewritten further by following + rules. For example, use it to rewrite the root-path URL + ('/') to a real one, e.g., + '/e/www/'.
'next|N' + (next round)
+ Re-run the rewriting process (starting again with the + first rewriting rule). This time, the URL to match is no longer + the original URL, but rather the URL returned by the last rewriting rule. + This corresponds to the Perl next command or + the continue command in C. Use + this flag to restart the rewriting process - + to immediately go to the top of the loop.
+ Be careful not to create an infinite + loop!
'nocase|NC' + (no case)
+ This makes the Pattern case-insensitive, + ignoring difference between 'A-Z' and + 'a-z' when Pattern is matched against the current + URL.
+ 'noescape|NE' + (no URI escaping of + output)
+ This flag prevents mod_rewrite from applying the usual URI + escaping rules to the result of a rewrite. Ordinarily, + special characters (such as '%', '$', ';', and so on) + will be escaped into their hexcode equivalents ('%25', + '%24', and '%3B', respectively); this flag prevents this + from happening. This allows percent symbols to appear in + the output, as in +
+ RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE] +
+ + which would turn '/foo/zed' into a safe + request for '/bar?arg=P1=zed'. +
+ 'nosubreq|NS' ( + not for internal + sub-requests)
+ This flag forces the rewrite engine to skip a + rewrite rule if the current request is an internal + sub-request. For instance, sub-requests occur internally + in Apache when mod_include tries to find out + information about possible directory default files + (index.xxx). On sub-requests it is not + always useful, and can even cause errors, if + the complete set of rules are applied. Use this flag to + exclude some rules.
+ To decide whether or not to use this rule: if you + prefix URLs with CGI-scripts, to force them to be + processed by the CGI-script, it's likely that you + will run into problems (or significant overhead) on + sub-requests. In these cases, use this flag. +
+ 'proxy|P' (force + proxy)
+ This flag forces the substitution part to be internally + sent as a proxy request and immediately (rewrite + processing stops here) put through the proxy module. You must make + sure that the substitution string is a valid URI + (typically starting with + http://hostname) which can be + handled by the Apache proxy module. If not, you will get an + error from the proxy module. Use this flag to achieve a + more powerful implementation of the ProxyPass directive, + to map remote content into the namespace of the local + server. + +
Note: mod_proxy must be enabled in order + to use this flag.
+
+ 'passthrough|PT' + (pass through to next + handler)
+ This flag forces the rewrite engine to set the + uri field of the internal + request_rec structure to the value of the + filename field. This flag is just a hack to + enable post-processing of the output of + RewriteRule directives, using + Alias, ScriptAlias, + Redirect, and other directives from + various URI-to-filename translators. For example, to rewrite + /abc to /def using + mod_rewrite, and then + /def to /ghi using + mod_alias: +
+ RewriteRule ^/abc(.*) /def$1 [PT] + Alias /def /ghi +
+ If you omit the PT flag, + mod_rewrite will rewrite + uri=/abc/... to + filename=/def/... as a full API-compliant + URI-to-filename translator should do. Then + mod_alias will try to do a + URI-to-filename transition, which will fail. + +
Note: You must use this flag if you want to + mix directives from different modules which allow + URL-to-filename translators. The typical example + is the use of mod_alias and + mod_rewrite.
+
'qsappend|QSA' + (query string + append)
+ This flag forces the rewrite engine to append a query + string part of the substitution string to the existing string, + instead of replacing it. Use this when you want to add more + data to the query string via a rewrite rule.
'redirect|R + [=code]' (force redirect)
+ Prefix Substitution with + http://thishost[:thisport]/ (which makes the + new URL a URI) to force a external redirection. If no + code is given, a HTTP response of 302 (MOVED + TEMPORARILY) will be returned. If you want to use other response + codes in the range 300-400, simply specify the appropriate number + or use one of the following symbolic names: + temp (default), permanent, + seeother. Use this for rules to + canonicalize the URL and return it to the client - to + translate ``/~'' into + ``/u/'', or to always append a slash to + /u/user, etc.
+ Note: When you use this flag, make + sure that the substitution field is a valid URL! Otherwise, + you will be redirecting to an invalid location. Remember + that this flag on its own will only prepend + http://thishost[:thisport]/ to the URL, and rewriting + will continue. Usually, you will want to stop rewriting at this point, + and redirect immediately. To stop rewriting, you should add + the 'L' flag. +
'skip|S=num' + (skip next rule(s))
+ This flag forces the rewriting engine to skip the next + num rules in sequence, if the current rule + matches. Use this to make pseudo if-then-else constructs: + The last rule of the then-clause becomes + skip=N, where N is the number of rules in the + else-clause. (This is not the same as the + 'chain|C' flag!)
+ 'type|T=MIME-type' + (force MIME type)
+ Force the MIME-type of the target file to be + MIME-type. This can be used to + set up the content-type based on some conditions. + For example, the following snippet allows .php files to + be displayed by mod_php if they are called with + the .phps extension: +
+ RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source] +
+

+ +

Home directory expansion

When the substitution string begins with a string +resembling "/~user" (via explicit text or backreferences), mod_rewrite performs +home directory expansion independent of the presence or configuration +of mod_userdir.

+ +

This expansion does not occur when the PT +flag is used on the RewriteRule +directive.

+ +

Note: Enabling rewrites in per-directory context

+ To enable the rewriting engine + for per-directory configuration files, you need to set + ``RewriteEngine On'' in these files + and ``

Options
+          FollowSymLinks

'' must be enabled. If your + administrator has disabled override of + FollowSymLinks for a user's directory, then + you cannot use the rewriting engine. This restriction is + needed for security reasons. +

+ +

Note: Pattern matching in per-directory context

+ Never forget that Pattern is +applied to a complete URL in per-server configuration +files. However, in per-directory configuration files, the +per-directory prefix (which always is the same for a specific +directory) is automatically removed for the pattern matching +and automatically added after the substitution has been +done. This feature is essential for many sorts of rewriting - +without this, you would always have to match the parent +directory which is not always possible. + +

There is one exception: If a substitution string + starts with ``http://'', then the directory + prefix will not be added, and an + external redirect or proxy throughput (if flag + P is used) is forced!

+ + +

Note: Substitution of Absolute URLs

When you prefix a substitution field with + http://thishost[:thisport], + mod_rewrite will automatically strip that + out. This auto-reduction on URLs with an implicit external redirect + is most useful in combination with + a mapping-function which generates the + hostname part.

+ +

Remember: An unconditional external + redirect to your own server will not work with the prefix + http://thishost because of this feature. To + achieve such a self-redirect, you have to use the + R-flag.

+ +

Note: Query String

The Pattern will not be matched against the query string. + Instead, you must use a RewriteCond with the + %{QUERY_STRING} variable. You can, however, create + URLs in the substitution string, containing a query string + part. Simply use a question mark inside the substitution string, to + indicate that the following text should be re-injected into the + query string. When you want to erase an existing query string, + end the substitution string with just a question mark. To + combine a new query string with an old one, use the + [QSA] flag.

+ +

Here are all possible substitution combinations and their + meanings:

+ +

Inside per-server configuration + (httpd.conf)
+ for request ``GET + /somepath/pathinfo'':
+

+ +

+Given Rule                                      Resulting Substitution
+----------------------------------------------  ----------------------------------
+^/somepath(.*) otherpath$1                      invalid, not supported
+
+^/somepath(.*) otherpath$1  [R]                 invalid, not supported
+
+^/somepath(.*) otherpath$1  [P]                 invalid, not supported
+----------------------------------------------  ----------------------------------
+^/somepath(.*) /otherpath$1                     /otherpath/pathinfo
+
+^/somepath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
+----------------------------------------------  ----------------------------------
+^/somepath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
+
+^/somepath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) http://thishost/otherpath$1 [P]  doesn't make sense, not supported
+----------------------------------------------  ----------------------------------
+^/somepath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
+                                                via external redirection
+
+^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
+                                                via external redirection
+                                                (the [R] flag is redundant)
+
+^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
+                                                via internal proxy
+

+ +

Inside per-directory configuration for + /somepath
+ (/physical/path/to/somepath/.htacccess, with + RewriteBase /somepath)
+ for request ``GET + /somepath/localpath/pathinfo'':
+

+ +

+Given Rule                                      Resulting Substitution
+----------------------------------------------  ----------------------------------
+^localpath(.*) otherpath$1                      /somepath/otherpath/pathinfo
+
+^localpath(.*) otherpath$1  [R]                 http://thishost/somepath/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) otherpath$1  [P]                 doesn't make sense, not supported
+----------------------------------------------  ----------------------------------
+^localpath(.*) /otherpath$1                     /otherpath/pathinfo
+
+^localpath(.*) /otherpath$1 [R]                 http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) /otherpath$1 [P]                 doesn't make sense, not supported
+----------------------------------------------  ----------------------------------
+^localpath(.*) http://thishost/otherpath$1      /otherpath/pathinfo
+
+^localpath(.*) http://thishost/otherpath$1 [R]  http://thishost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) http://thishost/otherpath$1 [P]  doesn't make sense, not supported
+----------------------------------------------  ----------------------------------
+^localpath(.*) http://otherhost/otherpath$1     http://otherhost/otherpath/pathinfo
+                                                via external redirection
+
+^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
+                                                via external redirection
+                                                (the [R] flag is redundant)
+
+^localpath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
+                                                via internal proxy
+

+ +

Apache Module mod_rewrite

Summary

Directives

Topics

See also

Example

For Apache Hackers

Note

Security

Example

Example

Example

Rewrite map file

Configuration directives

Note

Note

Home directory expansion

Note: Enabling rewrites in per-directory context

Note: Pattern matching in per-directory context

Note: Substitution of Absolute URLs

Note: Query String