diff options
Diffstat (limited to 'docs/manual/mod/mod_rewrite.html')
| -rw-r--r-- | docs/manual/mod/mod_rewrite.html | 1928 |
1 files changed, 0 insertions, 1928 deletions
diff --git a/docs/manual/mod/mod_rewrite.html b/docs/manual/mod/mod_rewrite.html deleted file mode 100644 index 812e755ccc..0000000000 --- a/docs/manual/mod/mod_rewrite.html +++ /dev/null @@ -1,1928 +0,0 @@ -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN"> -<!--%hypertext --> -<!-- mod_rewrite.html --> -<!-- Documentation for the mod_rewrite Apache module --> -<HTML> -<HEAD> -<TITLE>Apache module mod_rewrite</TITLE> -</HEAD> - -<!-- Background white, links blue (unvisited), navy (visited), red (active) --> -<BODY - BGCOLOR="#FFFFFF" - TEXT="#000000" - LINK="#0000FF" - VLINK="#000080" - ALINK="#FF0000" -> -<BLOCKQUOTE><!-- page indentation --> -<!--#include virtual="header.html" --> - -<BR> -<H1 ALIGN="CENTER">Module mod_rewrite<BR>URL Rewriting Engine</H1> - -<p>This module provides a rule-based rewriting engine to rewrite requested -URLs on the fly.</p> - -<P><A -HREF="module-dict.html#Status" -REL="Help" -><STRONG>Status:</STRONG></A> Extension -<BR> -<A -HREF="module-dict.html#SourceFile" -REL="Help" -><STRONG>Source File:</STRONG></A> mod_rewrite.c -<BR> -<A -HREF="module-dict.html#ModuleIdentifier" -REL="Help" -><STRONG>Module Identifier:</STRONG></A> rewrite_module -<BR> -<A -HREF="module-dict.html#Compatibility" -REL="Help" -><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later. -</P> - - -<P> -<HR NOSHADE SIZE=1> - -<BR> -<H2>Summary</H2> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>``The great thing about mod_rewrite is it gives you all the -configurability and flexibility of Sendmail. The downside to -mod_rewrite is that it gives you all the configurability and -flexibility of Sendmail.''</EM> -<DIV ALIGN=RIGHT> --- Brian Behlendorf<BR> -Apache Group -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -<BLOCKQUOTE> -<BLOCKQUOTE> -<BLOCKQUOTE> -<EM>`` -Despite the tons of examples and docs, mod_rewrite -is voodoo. Damned cool voodoo, but still voodoo. -''</EM> -<DIV ALIGN=RIGHT> --- Brian Moore<BR> -bem@news.cmc.net -</DIV> -</BLOCKQUOTE> -</BLOCKQUOTE> -</BLOCKQUOTE> - -Welcome to mod_rewrite, the Swiss Army Knife of URL manipulation! - -<P> -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, for instance server variables, -environment variables, HTTP headers, time stamps and even external database -lookups in various formats can be used to achieve a really granular URL -matching. - -<P> -This module operates on the full URLs (including the path-info part) both in -per-server context (<CODE>httpd.conf</CODE>) and per-directory context -(<CODE>.htaccess</CODE>) and can even 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. - -<P> -But all this functionality and flexibility has its drawback: complexity. So -don't expect to understand this entire module in just one day. - -<P> -This module was invented and originally written in April 1996<BR> -and gifted exclusively to the The Apache Group in July 1997 by - -<P> -<BLOCKQUOTE> -<A HREF="http://www.engelschall.com/"><CODE>Ralf S. Engelschall</CODE></A><BR> -<A HREF="mailto:rse@engelschall.com"><CODE>rse@engelschall.com</CODE></A><BR> -<A HREF="http://www.engelschall.com/"><CODE>www.engelschall.com</CODE></A> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2>Table Of Contents</H2> - -<P> -<STRONG>Internal Processing</STRONG> -<UL> - <LI><A HREF="#InternalAPI">API Phases</A> - <LI><A HREF="#InternalRuleset">Ruleset Processing</A> - <LI><A HREF="#InternalBackRefs">Regex Back-Reference Availability</A> -</UL> -<P> -<STRONG>Configuration Directives</STRONG> -<UL> - <LI><A HREF="#RewriteEngine">RewriteEngine</A> - <LI><A HREF="#RewriteOptions">RewriteOptions</A> - <LI><A HREF="#RewriteLog">RewriteLog</A> - <LI><A HREF="#RewriteLogLevel">RewriteLogLevel</A> - <LI><A HREF="#RewriteLock">RewriteLock</A> - <LI><A HREF="#RewriteMap">RewriteMap</A> - <LI><A HREF="#RewriteBase">RewriteBase</A> - <LI><A HREF="#RewriteCond">RewriteCond</A> - <LI><A HREF="#RewriteRule">RewriteRule</A> -</UL> -<STRONG>Miscellaneous</STRONG> -<UL> - <LI><A HREF="#EnvVar">Environment Variables</A> - <LI><A HREF="#Solutions">Practical Solutions</A> -</UL> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Internal">Internal Processing</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<P> -The internal processing of this module is very complex but needs to be -explained once even to the average user to avoid common mistakes and to let -you exploit its full functionality. - -<H2><A NAME="InternalAPI">API Phases</A></H2> - -<P> -First you have to understand that when Apache processes a HTTP request it does -this in 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 -which is used after the HTTP request has been read but before any authorization -starts and the Fixup hook which is triggered after the authorization phases -and after the per-directory config files (<CODE>.htaccess</CODE>) have been -read, but before the content handler is activated. - -<P> -So, after a request comes in and Apache has determined the corresponding -server (or virtual server) the rewriting engine starts processing of all -mod_rewrite directives from the per-server configuration in the -URL-to-filename phase. 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. In both situations mod_rewrite rewrites URLs either to new -URLs or to filenames, although there is no obvious distinction between them. -This is a usage of the API which was not intended to be this way when the API -was designed, but as of Apache 1.x this is the only way mod_rewrite can -operate. To make this point more clear remember the following two points: - -<OL> -<LI>Although mod_rewrite rewrites URLs to URLs, URLs to filenames and - even filenames to filenames, the API currently provides only a - URL-to-filename hook. In Apache 2.0 the two missing hooks will be - added to make the processing more clear. But this point has no - drawbacks for the user, it is just a fact which should be - remembered: Apache does more in the URL-to-filename hook than the - API intends for it. -<P> -<LI>Unbelievably mod_rewrite provides URL manipulations in per-directory - context, <EM>i.e.</EM>, within <CODE>.htaccess</CODE> files, - although these are reached a very long time after the URLs have - been translated to filenames. It has to be this way because - <CODE>.htaccess</CODE> files live in the filesystem, so processing - has already reached this stage. In other words: According to the - API phases at this time it is too late for any URL manipulations. - To overcome this chicken and egg problem mod_rewrite uses a trick: - When you manipulate a URL/filename in per-directory context - mod_rewrite first rewrites the filename back to its corresponding - URL (which is usually impossible, but see the <CODE>RewriteBase</CODE> - directive below for the trick to achieve this) and then initiates - a new internal sub-request with the new URL. This restarts - processing of the API phases. - <P> - Again mod_rewrite tries hard to make this complicated step totally - transparent to the user, but you should remember here: While URL - manipulations in per-server context are really fast and efficient, - per-directory rewrites are slow and inefficient due to this chicken and - egg problem. But on the other hand this is the only way mod_rewrite can - provide (locally restricted) URL manipulations to the average user. -</OL> - -<P> -Don't forget these two points! - -<H2><A NAME="InternalRuleset">Ruleset Processing</A></H2> - -Now when mod_rewrite is triggered in these two API phases, it reads the -configured rulesets from its configuration structure (which itself was either -created on startup for per-server context or during the directory walk of the -Apache kernel for per-directory context). Then the URL rewriting engine is -started with the contained ruleset (one or more rules together with their -conditions). The operation of the URL rewriting engine itself is exactly the -same for both configuration contexts. Only the final result processing is -different. - -<P> -The order of rules in the ruleset is important because the rewriting engine -processes them in a special (and not very obvious) order. The -rule is this: The rewriting engine loops through the ruleset rule by rule -(<CODE>RewriteRule</CODE> directives) and when a particular rule matches it -optionally loops through existing corresponding conditions -(<CODE>RewriteCond</CODE> directives). For historical reasons the conditions -are given first, and so the control flow is a little bit long-winded. See -Figure 1 for more details. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig1.gif" - WIDTH="428" HEIGHT="385" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 1:</STRONG> The control flow through the rewriting ruleset -</TD> -</TR> -</TABLE> -</DIV> - -<P> -As you can see, first the URL is matched against the <EM>Pattern</EM> of each -rule. When it fails mod_rewrite immediately stops processing this rule and -continues with the next rule. If the <EM>Pattern</EM> matches, mod_rewrite -looks for corresponding rule conditions. If none are present, it just -substitutes the URL with a new value which is constructed from the string -<EM>Substitution</EM> and goes on with its rule-looping. But if conditions -exist, it starts an inner loop for processing them in the order that -they are listed. For conditions the logic is different: we don't match a -pattern against the current URL. Instead we first create a string -<EM>TestString</EM> by expanding variables, back-references, map lookups, -<EM>etc.</EM> and then we try to match <EM>CondPattern</EM> against it. If the -pattern doesn't match, the complete set of conditions and the corresponding -rule fails. If the pattern matches, then the next condition is processed -until no more conditions are available. If all conditions match, processing -is continued with the substitution of the URL with <EM>Substitution</EM>. - -<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2> - -One important thing here has to be remembered: Whenever you -use parentheses in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM>, -back-references are internally created which can be used with the -strings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). These -are available for creating the strings <EM>Substitution</EM> and -<EM>TestString</EM>. Figure 2 shows to which locations the back-references are -transfered for expansion. - -<P> -<DIV ALIGN=CENTER> -<TABLE CELLSPACING=0 CELLPADDING=2 BORDER=0> -<TR> -<TD BGCOLOR="#CCCCCC"><IMG - SRC="../images/mod_rewrite_fig2.gif" - WIDTH="381" HEIGHT="179" - ALT="[Needs graphics capability to display]"></TD> -</TR> -<TR> -<TD ALIGN=CENTER> -<STRONG>Figure 2:</STRONG> The back-reference flow through a rule -</TD> -</TR> -</TABLE> -</DIV> - -<P> -We know this was a crash course on mod_rewrite's internal processing. But -you will benefit from this knowledge when reading the following documentation -of the available directives. - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Configuration">Configuration Directives</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H3><A NAME="RewriteEngine">RewriteEngine</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> - RewriteEngine on|off<BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> - <CODE>RewriteEngine off</CODE><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> - server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteEngine</CODE> directive enables or disables the runtime -rewriting engine. If it is set to <CODE>off</CODE> this module does no runtime -processing at all. It does not even update the <CODE>SCRIPT_URx</CODE> -environment variables. - -<P> -Use this directive to disable the module instead of commenting out -all the <CODE>RewriteRule</CODE> directives! - -<P> -Note that, by default, rewrite configurations are not inherited. -This means that you need to have a <CODE>RewriteEngine on</CODE> -directive for each virtual host in which you wish to use it. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteOptions">RewriteOptions</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteOptions <EM>Option</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> FileInfo<BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteOptions</CODE> directive sets some special options for the -current per-server or per-directory configuration. The <EM>Option</EM> -strings can be one of the following: - -<UL> -<LI>'<STRONG><CODE>inherit</CODE></STRONG>'<BR> - 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 - <CODE>.htaccess</CODE> configuration are inherited. -</UL> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLog">RewriteLog</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLog <EM>Filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLog</CODE> 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 ('<CODE>/</CODE>') then it is assumed to be relative to the -<EM>Server Root</EM>. The directive should occur only once per server -config. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note</STRONG>: To disable the logging of rewriting actions it is -not recommended to set <EM>Filename</EM> -to <CODE>/dev/null</CODE>, because although the rewriting engine does -not then output to a logfile it still creates the logfile -output internally. <STRONG>This will slow down the server with no advantage -to the administrator!</STRONG> -To disable logging either remove or comment out the -<CODE>RewriteLog</CODE> directive or use <CODE>RewriteLogLevel 0</CODE>! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Security</STRONG>: See the <A -HREF="../misc/security_tips.html">Apache Security -Tips</A> document for details on why your security could be compromised if the -directory where logfiles are stored is writable by anyone other than the user -that starts the server. -</TD></TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> -RewriteLog "/usr/local/var/apache/logs/rewrite.log" -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLogLevel">RewriteLogLevel</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLogLevel <EM>Level</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <CODE>RewriteLogLevel 0</CODE> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteLogLevel</CODE> 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. - -<P> -To disable the logging of rewriting actions simply set <EM>Level</EM> to 0. -This disables all rewrite action logs. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> Using a high value for <EM>Level</EM> will slow down -your Apache server dramatically! Use the rewriting logfile at -a <EM>Level</EM> greater than 2 only for debugging! -</TD></TR> -</TABLE> - - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> -<PRE> -RewriteLogLevel 3 -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteLock">RewriteLock</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteLock <EM>Filename</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.3<BR> - -<P> -This directive sets the filename for a synchronization lockfile which -mod_rewrite needs to communicate with <SAMP>RewriteMap</SAMP> -<EM>programs</EM>. 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. - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteMap">RewriteMap</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteMap <EM>MapName </EM> - <EM>MapType</EM>:<EM>MapSource</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> not used per default<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteMap</CODE> directive defines a <EM>Rewriting Map</EM> -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. -<P> - -The <A NAME="mapfunc"><EM>MapName</EM></A> 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: - -<BLOCKQUOTE><STRONG> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>}</CODE><BR> -<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM> -<CODE>|</CODE> <EM>DefaultValue</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -When such a construct occurs the map <EM>MapName</EM> -is consulted and the key <EM>LookupKey</EM> is looked-up. If the key is -found, the map-function construct is substituted by <EM>SubstValue</EM>. If -the key is not found then it is substituted by <EM>DefaultValue</EM> or -by the empty string if no <EM>DefaultValue</EM> was specified. - -<P> -The following combinations for <EM>MapType</EM> and <EM>MapSource</EM> -can be used: - -<UL> -<LI><STRONG>Standard Plain Text</STRONG><BR> - MapType: <CODE>txt</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - This is the standard rewriting map feature where the <EM>MapSource</EM> is - a plain ASCII file containing either blank lines, comment lines (starting - with a '#' character) or pairs like the following - one per line. - - <BLOCKQUOTE><STRONG> - <EM>MatchingKey</EM> <EM>SubstValue</EM> - </STRONG></BLOCKQUOTE> - - <P> - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -## -## map.txt -- rewriting map -## - -Ralf.S.Engelschall rse # Bastard Operator From Hell -Mr.Joe.Average joe # Mr. Average -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -RewriteMap real-to-user txt:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Randomized Plain Text</STRONG><BR> - MapType: <CODE>rnd</CODE>, MapSource: Unix filesystem path to valid regular - file - <P> - 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 ``<CODE>|</CODE>'' 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. Although this sounds crazy and useless, - it - was actually designed for load balancing in a reverse proxy situation where - the looked up values are server names. - Example: -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -## -## map.txt -- rewriting map -## - -static www1|www2|www3|www4 -dynamic www5|www6 -</PRE></TD></TR> -</TABLE> - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -RewriteMap servers rnd:/path/to/file/map.txt -</PRE></TD></TR> -</TABLE> - -<P> -<LI><STRONG>Hash File</STRONG><BR> - MapType: <CODE>dbm</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a binary NDBM format file containing the same contents - as a <EM>Plain Text</EM> format file, but in a special representation - which is optimized for really fast lookups. You can create such a file with - any NDBM tool or with the following Perl script: - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE> -#!/path/to/bin/perl -## -## txt2dbm -- convert txt map to dbm format -## - -($txtmap, $dbmmap) = @ARGV; -open(TXT, "<$txtmap"); -dbmopen(%DB, $dbmmap, 0644); -while (<TXT>) { - next if (m|^s*#.*| or m|^s*$|); - $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|); -} -dbmclose(%DB); -close(TXT)</PRE></TD></TR> - </TABLE> - <P> - <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> - <TR><TD><PRE>$ txt2dbm map.txt map.db </PRE></TD></TR> - </TABLE> -<P> -<LI><STRONG>Internal Function</STRONG><BR> - MapType: <CODE>int</CODE>, MapSource: Internal Apache function - <P> - Here the source is an internal Apache function. Currently you cannot - create your own, but the following functions already exists: - <UL> - <LI><STRONG>toupper</STRONG>:<BR> - Converts the looked up key to all upper case. - <LI><STRONG>tolower</STRONG>:<BR> - Converts the looked up key to all lower case. - <LI><STRONG>escape</STRONG>:<BR> - Translates special characters in the looked up key to hex-encodings. - <LI><STRONG>unescape</STRONG>:<BR> - Translates hex-encodings in the looked up key back to special characters. - </UL> -<P> -<LI><STRONG>External Rewriting Program</STRONG><BR> - MapType: <CODE>prg</CODE>, MapSource: Unix filesystem path to valid - regular file - <P> - Here the source is a program, not a map file. To create it you - can use the language of your choice, but the result has to be a - executable (<EM>i.e.</EM>, either object-code or a script with the - magic cookie trick '<CODE>#!/path/to/interpreter</CODE>' as the - first line). - <P> - This program is started once at startup of the Apache servers and then - communicates with the rewriting engine over its <CODE>stdin</CODE> and - <CODE>stdout</CODE> file-handles. For each map-function lookup it will - receive the key to lookup as a newline-terminated string on - <CODE>stdin</CODE>. It then has to give back the looked-up value as a - newline-terminated string on <CODE>stdout</CODE> or the four-character - string ``<CODE>NULL</CODE>'' if it fails (<EM>i.e.</EM>, there is no - corresponding value - for the given key). A trivial program which will implement a 1:1 map - (<EM>i.e.</EM>, key == value) could be: - <P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -#!/usr/bin/perl -$| = 1; -while (<STDIN>) { - # ...put here any transformations or lookups... - print $_; -} -</PRE></TD></TR> -</TABLE> - <P> - But be very careful:<BR> - <OL> - <LI>``<EM>Keep it simple, stupid</EM>'' (KISS), because - if this program hangs it will hang the Apache server - when the rule occurs. - <LI>Avoid one common mistake: never do buffered I/O on <CODE>stdout</CODE>! - This will cause a deadloop! Hence the ``<CODE>$|=1</CODE>'' in the - above example... - <LI>Use the <SAMP>RewriteLock</SAMP> directive to define a lockfile - mod_rewrite can use to synchronize the communication to the program. - By default no such synchronization takes place. - </OL> -</UL> - -The <CODE>RewriteMap</CODE> directive can occur more than once. For each -mapping-function use one <CODE>RewriteMap</CODE> directive to declare its -rewriting mapfile. While you cannot <STRONG>declare</STRONG> a map in -per-directory context it is of course possible to <STRONG>use</STRONG> -this map in per-directory context. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> For plain text and DBM format files the looked-up -keys are cached in-core -until the <CODE>mtime</CODE> of the mapfile changes or the server does a -restart. This way you can have map-functions in rules which are used -for <STRONG>every</STRONG> request. This is no problem, because the -external lookup only happens once! -</TD></TR> -</TABLE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteBase">RewriteBase</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteBase <EM>BaseURL</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>default is the physical directory path</EM> -<BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2<BR> - -<P> -The <CODE>RewriteBase</CODE> directive explicitly sets the base URL for -per-directory rewrites. As you will see below, <CODE>RewriteRule</CODE> can be -used in per-directory config files (<CODE>.htaccess</CODE>). There it will act -locally, <EM>i.e.</EM>, the local directory prefix is stripped at this stage of -processing and your rewriting rules act only on the remainder. At the end -it is automatically added back to the path. - -<P> -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. <STRONG>But at most websites URLs are -NOT directly related to physical filename paths, so this -assumption will usually be wrong!</STRONG> There you have to use the -<CODE>RewriteBase</CODE> directive to specify the correct URL-prefix. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> If your webserver's URLs are <STRONG>not</STRONG> -directly related to physical file paths, you have to use -<CODE>RewriteBase</CODE> in every -<CODE>.htaccess</CODE> files where you want to use <CODE>RewriteRule</CODE> -directives. -</TD></TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> - Assume the following per-directory config file: - -<P> -<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0"> -<TR><TD><PRE> -# -# /abc/def/.htaccess -- per-dir config file for directory /abc/def -# Remember: /abc/def is the physical path of /xyz, <EM>i.e.</EM>, the server -# has a 'Alias /xyz /abc/def' directive <EM>e.g.</EM> -# - -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 -</PRE></TD></TR> -</TABLE> - -<P> -In the above example, a request to <CODE>/xyz/oldstuff.html</CODE> -gets correctly -rewritten to the physical file <CODE>/abc/def/newstuff.html</CODE>. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<FONT SIZE=-1> -<STRONG>Note - For Apache hackers:</STRONG><BR> -The following list gives detailed information about the internal -processing steps: - -<P> -<PRE> -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 -</PRE> - -This seems very complicated but is the correct Apache internal processing, -because the per-directory rewriting comes too late in the process. So, -when it occurs the (rewritten) request has to be re-injected into the Apache -kernel! BUT: While this seems like a serious overhead, it really isn't, because -this re-injection happens fully internally to the Apache server and the same -procedure is used by many other operations inside Apache. So, you can be -sure the design and implementation is correct. -</FONT> -</TD></TR> -</TABLE> - -</BLOCKQUOTE> - - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteCond">RewriteCond</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteCond <EM>TestString</EM> - <EM>CondPattern</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, - .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteCond</CODE> directive defines a rule condition. Precede a -<CODE>RewriteRule</CODE> directive with one or more <CODE>RewriteCond</CODE> -directives. - -The following rewriting rule is only used if its pattern matches the current -state of the URI <STRONG>and</STRONG> if these additional conditions apply -too. - -<P> -<EM>TestString</EM> is a string which can contains the following -expanded constructs in addition to plain text: - -<UL> -<LI><STRONG>RewriteRule backreferences</STRONG>: These are backreferences of - the form - -<BLOCKQUOTE><STRONG> -<CODE>$N</CODE> -</STRONG></BLOCKQUOTE> - -(0 <= N <= 9) which provide access to the grouped parts (parenthesis!) -of the pattern from the corresponding <CODE>RewriteRule</CODE> directive (the -one following the current bunch of <CODE>RewriteCond</CODE> directives). - -<P> -<LI><STRONG>RewriteCond backreferences</STRONG>: These are backreferences of -the form - -<BLOCKQUOTE><STRONG> -<CODE>%N</CODE> -</STRONG></BLOCKQUOTE> - -(1 <= N <= 9) which provide access to the grouped parts (parentheses!) of -the pattern from the last matched <CODE>RewriteCond</CODE> directive in the -current bunch of conditions. - -<P> -<LI><STRONG>RewriteMap expansions</STRONG>: These are expansions of the form - -<BLOCKQUOTE><STRONG> -<CODE>${mapname:key|default}</CODE> -</STRONG></BLOCKQUOTE> - -See <A HREF="#mapfunc">the documentation for RewriteMap</A> for more details. - -<P> -<LI><STRONG>Server-Variables</STRONG>: These are variables - of the form - -<BLOCKQUOTE><STRONG> -<CODE>%{</CODE> <EM>NAME_OF_VARIABLE</EM> <CODE>}</CODE> -</STRONG></BLOCKQUOTE> - -where <EM>NAME_OF_VARIABLE</EM> can be a string -taken from the following list: - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD VALIGN=TOP> -<STRONG>HTTP headers:</STRONG><P> -<FONT SIZE=-1> -HTTP_USER_AGENT<BR> -HTTP_REFERER<BR> -HTTP_COOKIE<BR> -HTTP_FORWARDED<BR> -HTTP_HOST<BR> -HTTP_PROXY_CONNECTION<BR> -HTTP_ACCEPT<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>connection & request:</STRONG><P> -<FONT SIZE=-1> -REMOTE_ADDR<BR> -REMOTE_HOST<BR> -REMOTE_USER<BR> -REMOTE_IDENT<BR> -REQUEST_METHOD<BR> -SCRIPT_FILENAME<BR> -PATH_INFO<BR> -QUERY_STRING<BR> -AUTH_TYPE<BR> -</FONT> -</TD> - -</TR> -<TR> - -<TD VALIGN=TOP> -<STRONG>server internals:</STRONG><P> -<FONT SIZE=-1> -DOCUMENT_ROOT<BR> -SERVER_ADMIN<BR> -SERVER_NAME<BR> -SERVER_ADDR<BR> -SERVER_PORT<BR> -SERVER_PROTOCOL<BR> -SERVER_SOFTWARE<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>system stuff:</STRONG><P> -<FONT SIZE=-1> -TIME_YEAR<BR> -TIME_MON<BR> -TIME_DAY<BR> -TIME_HOUR<BR> -TIME_MIN<BR> -TIME_SEC<BR> -TIME_WDAY<BR> -TIME<BR> -</FONT> -</TD> - -<TD VALIGN=TOP> -<STRONG>specials:</STRONG><P> -<FONT SIZE=-1> -API_VERSION<BR> -THE_REQUEST<BR> -REQUEST_URI<BR> -REQUEST_FILENAME<BR> -IS_SUBREQ<BR> -</FONT> -</TD> -</TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> - -<p><STRONG>Notice:</STRONG> These variables all correspond to -the similarly named HTTP MIME-headers, C variables of the Apache -server or <CODE>struct tm</CODE> 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:</p> - -<dl> -<dt><code>IS_SUBREQ</code></dt> -<dd>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.</dd> - -<dt><code>API_VERSION</code></dt> -<dd>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.</dd> - -<dt><code>THE_REQUEST</code></dt> -<dd>The full HTTP request line sent by the browser to the server -(e.g., "<code>GET /index.html HTTP/1.1</code>"). This does not include -any additional headers sent by the browser.</dd> - -<dt><code>REQUEST_URI</code></dt> -<dd>The resource requested in the HTTP request line. (In the -example above, this would be "/index.html".)</dd> - -<dt><code>REQUEST_FILENAME</code></dt> -<dd>The full local filesystem path to the file or script -matching the request.</dd> -</dl> - -</TD></TR> -</TABLE> - -</UL> - -<P> -Special Notes: - -<OL> -<LI>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same -value, <EM>i.e.</EM>, the value of the <CODE>filename</CODE> field of -the internal -<CODE>request_rec</CODE> structure of the Apache server. The first name is -just the -commonly known CGI variable name while the second is the consistent -counterpart to REQUEST_URI (which contains the value of the <CODE>uri</CODE> -field of <CODE>request_rec</CODE>). - -<P> -<LI>There is the special format: <CODE>%{ENV:variable}</CODE> where -<EM>variable</EM> can be any environment variable. This is looked-up via -internal Apache structures and (if not found there) via <CODE>getenv()</CODE> -from the Apache server process. - -<P> -<LI>There is the special format: <CODE>%{HTTP:header}</CODE> where -<EM>header</EM> can be any HTTP MIME-header name. This is looked-up -from the HTTP request. Example: <CODE>%{HTTP:Proxy-Connection}</CODE> -is the value of the HTTP header ``<CODE>Proxy-Connection:</CODE>''. - -<P> -<LI>There is the special format <CODE>%{LA-U:variable}</CODE> for look-aheads -which perform an internal (URL-based) sub-request to determine the final value -of <EM>variable</EM>. Use this when you want to use a variable for rewriting -which is actually set later in an API phase and thus is not available at the -current stage. For instance when you want to rewrite according to the -<CODE>REMOTE_USER</CODE> variable from within the per-server context -(<CODE>httpd.conf</CODE> file) you have to use <CODE>%{LA-U:REMOTE_USER}</CODE> -because this variable is set by the authorization phases which come -<EM>after</EM> the URL translation phase where mod_rewrite operates. On the -other hand, because mod_rewrite implements its per-directory context -(<CODE>.htaccess</CODE> file) via the Fixup phase of the API and because the -authorization phases come <EM>before</EM> this phase, you just can use -<CODE>%{REMOTE_USER}</CODE> there. - -<P> -<LI>There is the special format: <CODE>%{LA-F:variable}</CODE> which performs an -internal (filename-based) sub-request to determine the final value of -<EM>variable</EM>. Most of the time this is the same as LA-U above. -</OL> - -<P> -<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular -expression -which is applied to the current instance of the <EM>TestString</EM>, -<EM>i.e.</EM>, <EM>TestString</EM> is evaluated and then matched against -<EM>CondPattern</EM>. - -<P> -<STRONG>Remember:</STRONG> <EM>CondPattern</EM> is a standard -<EM>Extended Regular Expression</EM> with some additions: - -<OL> -<LI>You can prefix the pattern string with a '<CODE>!</CODE>' character -(exclamation mark) to specify a <STRONG>non</STRONG>-matching pattern. - -<P> -<LI> -There are some special variants of <EM>CondPatterns</EM>. Instead of real -regular expression strings you can also use one of the following: -<P> -<UL> -<LI>'<STRONG><CondPattern</STRONG>' (is lexically lower)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically lower than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>>CondPattern</STRONG>' (is lexically greater)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically greater than <EM>CondPattern</EM>. -<P> -<LI>'<STRONG>=CondPattern</STRONG>' (is lexically equal)<BR> -Treats the <EM>CondPattern</EM> as a plain string and compares it -lexically to <EM>TestString</EM>. True if -<EM>TestString</EM> is lexically equal to <EM>CondPattern</EM>, i.e the -two strings are exactly equal (character by character). -If <EM>CondPattern</EM> is just <SAMP>""</SAMP> (two quotation marks) this -compares <EM>TestString</EM> to the empty string. -<P> -<LI>'<STRONG>-d</STRONG>' (is <STRONG>d</STRONG>irectory)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a directory. -<P> -<LI>'<STRONG>-f</STRONG>' (is regular <STRONG>f</STRONG>ile)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file. -<P> -<LI>'<STRONG>-s</STRONG>' (is regular file with <STRONG>s</STRONG>ize)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a regular file with size greater than zero. -<P> -<LI>'<STRONG>-l</STRONG>' (is symbolic <STRONG>l</STRONG>ink)<BR> -Treats the <EM>TestString</EM> as a pathname and -tests if it exists and is a symbolic link. -<P> -<LI>'<STRONG>-F</STRONG>' (is existing file via subrequest)<BR> -Checks if <EM>TestString</EM> is a valid file and accessible via all the -server's currently-configured access controls for that path. This uses an -internal subrequest to determine the check, so use it with care because it -decreases your servers performance! -<P> -<LI>'<STRONG>-U</STRONG>' (is existing URL via subrequest)<BR> -Checks if <EM>TestString</EM> is a valid URL and accessible via all the -server's -currently-configured access controls for that path. This uses an internal -subrequest to determine the check, so use it with care because it decreases -your server's performance! -</UL> -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> -All of these tests can also be prefixed by an exclamation mark ('!') -to negate their meaning. -</TD></TR> -</TABLE> -</OL> - -<P> -Additionally you can set special flags for <EM>CondPattern</EM> by appending - -<BLOCKQUOTE><STRONG> -<CODE>[</CODE><EM>flags</EM><CODE>]</CODE> -</STRONG></BLOCKQUOTE> - -as the third argument to the <CODE>RewriteCond</CODE> directive. <EM>Flags</EM> -is a comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the test case-insensitive, <EM>i.e.</EM>, there is - no difference between 'A-Z' and 'a-z' both in the expanded - <EM>TestString</EM> and the <EM>CondPattern</EM>. - This flag is effective only for comparisons between - <EM>TestString</EM> and <EM>CondPattern</EM>. It has no - effect on filesystem and subrequest checks. -<P> -<LI>'<STRONG><CODE>ornext|OR</CODE></STRONG>' (<STRONG>or</STRONG> next condition)<BR> - Use this to combine rule conditions with a local OR instead of the - implicit AND. Typical example: - <P> -<BLOCKQUOTE><PRE> -RewriteCond %{REMOTE_HOST} ^host1.* [OR] -RewriteCond %{REMOTE_HOST} ^host2.* [OR] -RewriteCond %{REMOTE_HOST} ^host3.* -RewriteRule ...some special stuff for any of these hosts... -</PRE></BLOCKQUOTE> - Without this flag you would have to write the cond/rule three times. -</UL> - -<P> -<STRONG>Example:</STRONG> -<BLOCKQUOTE> - -To rewrite the Homepage of a site according to the ``<CODE>User-Agent:</CODE>'' -header of the request, you can use the following: - -<BLOCKQUOTE><PRE> -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] -</PRE></BLOCKQUOTE> - -Interpretation: If you use Netscape Navigator as your browser (which identifies -itself as 'Mozilla'), then you get the max homepage, which includes -Frames, <EM>etc.</EM> If you use the Lynx browser (which is Terminal-based), then you -get the min homepage, which contains no images, no tables, <EM>etc.</EM> If you -use any other browser you get the standard homepage. -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> -<P> - -<H3><A NAME="RewriteRule">RewriteRule</A></H3> -<A - HREF="directive-dict.html#Syntax" - REL="Help" -><STRONG>Syntax:</STRONG></A> RewriteRule <EM>Pattern</EM> <EM>Substitution</EM><BR> -<A - HREF="directive-dict.html#Default" - REL="Help" -><STRONG>Default:</STRONG></A> <EM>None</EM><BR> -<A - HREF="directive-dict.html#Context" - REL="Help" -><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR> -<A - HREF="directive-dict.html#Override" - REL="Help" -><STRONG>Override:</STRONG></A> <EM>FileInfo</EM><BR> -<A - HREF="directive-dict.html#Status" - REL="Help" -><STRONG>Status:</STRONG></A> Extension<BR> -<A - HREF="directive-dict.html#Module" - REL="Help" -><STRONG>Module:</STRONG></A> mod_rewrite.c<BR> -<A - HREF="directive-dict.html#Compatibility" - REL="Help" -><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR> - -<P> -The <CODE>RewriteRule</CODE> directive is the real rewriting workhorse. The -directive can occur more than once. Each directive then defines one single -rewriting rule. The <STRONG>definition order</STRONG> of these rules is -<STRONG>important</STRONG>, because this order is used when applying the rules at -run-time. - -<P> -<A NAME="patterns"><EM>Pattern</EM></A> can be (for Apache -1.1.x a System V8 and for Apache 1.2.x and later a POSIX) <A -NAME="regexp">regular expression</A> which gets applied to the current -URL. Here ``current'' means the value of the URL when this rule gets -applied. This may not be the originally requested URL, because no -longer existingany number of rules may already have matched and made -alterations to it. - -<P> -Some hints about the syntax of regular expressions: - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD VALIGN=TOP> -<PRE> -<STRONG>Text:</STRONG> - <STRONG><CODE>.</CODE></STRONG> Any single character - <STRONG><CODE>[</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: One of chars - <STRONG><CODE>[^</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: None of chars - text1<STRONG><CODE>|</CODE></STRONG>text2 Alternative: text1 or text2 - -<STRONG>Quantifiers:</STRONG> - <STRONG><CODE>?</CODE></STRONG> 0 or 1 of the preceding text - <STRONG><CODE>*</CODE></STRONG> 0 or N of the preceding text (N > 0) - <STRONG><CODE>+</CODE></STRONG> 1 or N of the preceding text (N > 1) - -<STRONG>Grouping:</STRONG> - <STRONG><CODE>(</CODE></STRONG>text<STRONG><CODE>)</CODE></STRONG> Grouping of text - (either to set the borders of an alternative or - for making backreferences where the <STRONG>N</STRONG>th group can - be used on the RHS of a RewriteRule with <CODE>$</CODE><STRONG>N</STRONG>) - -<STRONG>Anchors:</STRONG> - <STRONG><CODE>^</CODE></STRONG> Start of line anchor - <STRONG><CODE>$</CODE></STRONG> End of line anchor - -<STRONG>Escaping:</STRONG> - <STRONG><CODE>\</CODE></STRONG>char escape that particular char - (for instance to specify the chars "<CODE>.[]()</CODE>" <EM>etc.</EM>) -</PRE> -</TD> -</TR> -</TABLE> - -<P> -For more information about regular expressions either have a look at your -local regex(3) manpage or its <CODE>src/regex/regex.3</CODE> copy in the -Apache 1.3 distribution. If you are interested in more detailed -information about regular expressions and their variants (POSIX regex, Perl -regex, <EM>etc.</EM>) have a look at the following dedicated book on this topic: - -<BLOCKQUOTE> -<EM>Mastering Regular Expressions</EM><BR> -Jeffrey E.F. Friedl<BR> -Nutshell Handbook Series<BR> -O'Reilly & Associates, Inc. 1997<BR> -ISBN 1-56592-257-3<BR> -</BLOCKQUOTE> - -<P> -Additionally in mod_rewrite the NOT character ('<CODE>!</CODE>') is a possible -pattern prefix. This gives you the ability to negate a pattern; to say, for -instance: ``<EM>if the current URL does <STRONG>NOT</STRONG> match this -pattern</EM>''. This can be used for exceptional cases, where it is easier to -match the negative pattern, or as a last default rule. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Notice:</STRONG> When using the NOT character to negate a pattern you cannot -have grouped wildcard parts in the pattern. This is impossible because when -the pattern does NOT match, there are no contents for the groups. In -consequence, if negated patterns are used, you cannot use <CODE>$N</CODE> in the -substitution string! -</TD></TR> -</TABLE> - -<P> -<A NAME="rhs"><EM>Substitution</EM></A> of a rewriting rule is the string -which is substituted for (or replaces) the original URL for which -<EM>Pattern</EM> matched. Beside plain text you can use - -<OL> -<LI>back-references <CODE>$N</CODE> to the RewriteRule pattern -<LI>back-references <CODE>%N</CODE> to the last matched RewriteCond pattern -<LI>server-variables as in rule condition test-strings (<CODE>%{VARNAME}</CODE>) -<LI><A HREF="#mapfunc">mapping-function</A> calls (<CODE>${mapname:key|default}</CODE>) -</OL> - -Back-references are <CODE>$</CODE><STRONG>N</STRONG> (<STRONG>N</STRONG>=0..9) identifiers which -will be replaced by the contents of the <STRONG>N</STRONG>th group of the matched -<EM>Pattern</EM>. The server-variables are the same as for the -<EM>TestString</EM> of a <CODE>RewriteCond</CODE> directive. The -mapping-functions come from the <CODE>RewriteMap</CODE> directive and are -explained there. These three types of variables are expanded in the order of -the above list. - -<P> -As already mentioned above, all the rewriting rules are applied to the -<EM>Substitution</EM> (in the order of definition in the config file). The -URL is <STRONG>completely replaced</STRONG> by the <EM>Substitution</EM> and the -rewriting process goes on until there are no more rules unless explicitly -terminated by a <CODE><STRONG>L</STRONG></CODE> flag - see below. - -<P> -There is a special substitution string named '<CODE>-</CODE>' which means: -<STRONG>NO substitution</STRONG>! Sounds silly? No, it is useful to provide rewriting -rules which <STRONG>only</STRONG> match some URLs but do no substitution, <EM>e.g.</EM>, in -conjunction with the <STRONG>C</STRONG> (chain) flag to be able to have more than one -pattern to be applied before a substitution occurs. - -<P> -One more note: You can even create URLs in the substitution string containing -a query string part. Just use a question mark inside the substitution string -to indicate that the following stuff should be re-injected into the -QUERY_STRING. When you want to erase an existing query string, end the -substitution string with just the question mark. - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note</STRONG>: There is a special feature: When you prefix a substitution -field with <CODE>http://</CODE><EM>thishost</EM>[<EM>:thisport</EM>] then -<STRONG>mod_rewrite</STRONG> automatically strips it out. This auto-reduction on -implicit external redirect URLs is a useful and important feature when -used in combination with a mapping-function which generates the hostname -part. Have a look at the first example in the example section below to -understand this. -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Remember:</STRONG> An unconditional external redirect to your own server will -not work with the prefix <CODE>http://thishost</CODE> because of this feature. -To achieve such a self-redirect, you have to use the <STRONG>R</STRONG>-flag (see -below). -</TD></TR> -</TABLE> - -<P> -Additionally you can set special flags for <EM>Substitution</EM> by appending - -<BLOCKQUOTE><STRONG> -<CODE>[</CODE><EM>flags</EM><CODE>]</CODE> -</STRONG></BLOCKQUOTE> - -as the third argument to the <CODE>RewriteRule</CODE> directive. <EM>Flags</EM> is a -comma-separated list of the following flags: - -<UL> -<LI>'<STRONG><CODE>redirect|R</CODE> [=<EM>code</EM>]</STRONG>' (force <A NAME="redirect"><STRONG>r</STRONG>edirect</A>)<BR> - Prefix <EM>Substitution</EM> - with <CODE>http://thishost[:thisport]/</CODE> (which makes the new URL a URI) to - force a external redirection. If no <EM>code</EM> is given a HTTP response - of 302 (MOVED TEMPORARILY) is used. If you want to use other response - codes in the range 300-400 just specify them as a number or use - one of the following symbolic names: <CODE>temp</CODE> (default), <CODE>permanent</CODE>, - <CODE>seeother</CODE>. - Use it for rules which should - canonicalize the URL and give it back to the client, <EM>e.g.</EM>, translate - ``<CODE>/~</CODE>'' into ``<CODE>/u/</CODE>'' or always append a slash to - <CODE>/u/</CODE><EM>user</EM>, etc.<BR> - <P> - <STRONG>Note:</STRONG> When you use this flag, make sure that the - substitution field is a valid URL! If not, you are redirecting to an - invalid location! And remember that this flag itself only prefixes the - URL with <CODE>http://thishost[:thisport]/</CODE>, rewriting continues. - Usually you also want to stop and do the redirection immediately. To stop - the rewriting you also have to provide the 'L' flag. -<P> -<LI>'<STRONG><CODE>forbidden|F</CODE></STRONG>' (force URL to be <STRONG>f</STRONG>orbidden)<BR> - This forces the current URL to be forbidden, <EM>i.e.</EM>, it immediately sends - back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with - appropriate RewriteConds to conditionally block some URLs. -<P> -<LI>'<STRONG><CODE>gone|G</CODE></STRONG>' (force URL to be <STRONG>g</STRONG>one)<BR> - This forces the current URL to be gone, <EM>i.e.</EM>, it immediately sends back a - HTTP response of 410 (GONE). Use this flag to mark pages which no longer - exist as gone. -<P> -<LI>'<STRONG><CODE>proxy|P</CODE></STRONG>' (force <STRONG>p</STRONG>roxy)<BR> - This flag forces the substitution part to be internally forced as a proxy - request and immediately (<EM>i.e.</EM>, rewriting rule processing stops here) put - through the <A HREF="mod_proxy.html">proxy module</A>. You have to make - sure that the substitution string is a valid URI (<EM>e.g.</EM>, typically starting - with <CODE>http://</CODE><EM>hostname</EM>) which can be handled by the - Apache proxy module. If not you get an error from the proxy module. Use - this flag to achieve a more powerful implementation of the <A - HREF="mod_proxy.html#proxypass">ProxyPass</A> directive, to map some - remote stuff into the namespace of the local server. - <P> - Notice: To use this functionality make sure you have the proxy module - compiled into your Apache server program. If you don't know please check - whether <CODE>mod_proxy.c</CODE> is part of the ``<CODE>httpd -l</CODE>'' - output. If yes, this functionality is available to mod_rewrite. If not, - then you first have to rebuild the ``<CODE>httpd</CODE>'' program with - mod_proxy enabled. -<P> -<LI>'<STRONG><CODE>last|L</CODE></STRONG>' (<STRONG>l</STRONG>ast rule)<BR> - Stop the rewriting process here and - don't apply any more rewriting rules. This corresponds to the Perl - <CODE>last</CODE> command or the <CODE>break</CODE> command from the C - language. 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 ('<CODE>/</CODE>') to a real - one, <EM>e.g.</EM>, '<CODE>/e/www/</CODE>'. -<P> -<LI>'<STRONG><CODE>next|N</CODE></STRONG>' (<STRONG>n</STRONG>ext round)<BR> - Re-run the rewriting process (starting again with the first rewriting - rule). Here the URL to match is again not the original URL but the URL - from the last rewriting rule. This corresponds to the Perl - <CODE>next</CODE> command or the <CODE>continue</CODE> command from the C - language. Use this flag to restart the rewriting process, <EM>i.e.</EM>, to - immediately go to the top of the loop. <BR> - <STRONG>But be careful not to create an infinite loop!</STRONG> -<P> -<LI>'<STRONG><CODE>chain|C</CODE></STRONG>' (<STRONG>c</STRONG>hained with next rule)<BR> - This flag chains the current rule with the next rule (which itself can - be chained with the following rule, <EM>etc.</EM>). This has the following - effect: if a rule matches, then processing continues as usual, <EM>i.e.</EM>, the - flag has no effect. If the rule does <STRONG>not</STRONG> match, then all following - chained rules are skipped. For instance, use it to remove the - ``<CODE>.www</CODE>'' part inside a per-directory rule set when you let an - external redirect happen (where the ``<CODE>.www</CODE>'' part should not to - occur!). -<P> -<LI>'<STRONG><CODE>type|T</CODE></STRONG>=<EM>MIME-type</EM>' (force MIME <STRONG>t</STRONG>ype)<BR> - Force the MIME-type of the target file to be <EM>MIME-type</EM>. For - instance, this can be used to simulate the <CODE>mod_alias</CODE> - directive <CODE>ScriptAlias</CODE> which internally forces all files inside - the mapped directory to have a MIME type of - ``<CODE>application/x-httpd-cgi</CODE>''. -<P> -<LI>'<STRONG><CODE>nosubreq|NS</CODE></STRONG>' (used only if <STRONG>n</STRONG>o internal <STRONG>s</STRONG>ub-request)<BR> - This flag forces the rewriting engine to skip a rewriting rule if the - current request is an internal sub-request. For instance, sub-requests - occur internally in Apache when <CODE>mod_include</CODE> tries to find out - information about possible directory default files (<CODE>index.xxx</CODE>). - On sub-requests it is not always useful and even sometimes causes a failure to - if the complete set of rules are applied. Use this flag to exclude some rules.<BR> - <P> - Use the following rule for your decision: whenever you prefix some URLs - with CGI-scripts to force them to be processed by the CGI-script, the - chance is high that you will run into problems (or even overhead) on sub-requests. - In these cases, use this flag. -<P> -<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR> - This makes the <EM>Pattern</EM> case-insensitive, <EM>i.e.</EM>, there is - no difference between 'A-Z' and 'a-z' when <EM>Pattern</EM> is matched - against the current URL. -<P> -<LI>'<STRONG><CODE>qsappend|QSA</CODE></STRONG>' (<STRONG>q</STRONG>uery <STRONG>s</STRONG>tring - <STRONG>a</STRONG>ppend)<BR> - This flag forces the rewriting engine to append a query - string part in the substitution string to the existing one instead of - replacing it. Use this when you want to add more data to the query string - via a rewrite rule. -<P> -<LI>'<STRONG><CODE>passthrough|PT</CODE></STRONG>' (<STRONG>p</STRONG>ass <STRONG>t</STRONG>hrough to next handler)<BR> - This flag forces the rewriting engine to set the <CODE>uri</CODE> field - of the internal <CODE>request_rec</CODE> structure to the value - of the <CODE>filename</CODE> field. This flag is just a hack to be able - to post-process the output of <CODE>RewriteRule</CODE> directives by - <CODE>Alias</CODE>, <CODE>ScriptAlias</CODE>, <CODE>Redirect</CODE>, <EM>etc.</EM> directives - from other URI-to-filename translators. A trivial example to show the - semantics: - If you want to rewrite <CODE>/abc</CODE> to <CODE>/def</CODE> via the rewriting - engine of <CODE>mod_rewrite</CODE> and then <CODE>/def</CODE> to <CODE>/ghi</CODE> - with <CODE>mod_alias</CODE>: - <PRE> - RewriteRule ^/abc(.*) /def$1 [PT] - Alias /def /ghi - </PRE> - If you omit the <CODE>PT</CODE> flag then <CODE>mod_rewrite</CODE> - will do its job fine, <EM>i.e.</EM>, it rewrites <CODE>uri=/abc/...</CODE> to - <CODE>filename=/def/...</CODE> as a full API-compliant URI-to-filename - translator should do. Then <CODE>mod_alias</CODE> comes and tries to do a - URI-to-filename transition which will not work. - <P> - Note: <STRONG>You have to use this flag if you want to intermix directives - of different modules which contain URL-to-filename translators</STRONG>. The - typical example is the use of <CODE>mod_alias</CODE> and - <CODE>mod_rewrite</CODE>.. -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<font size=-1> - <STRONG>Note - For Apache hackers:</STRONG><BR> - If the current Apache API had a - filename-to-filename hook additionally to the URI-to-filename hook then - we wouldn't need this flag! But without such a hook this flag is the - only solution. The Apache Group has discussed this problem and will - add such a hook in Apache version 2.0. -</FONT> -</TD></TR> -</TABLE> -<P> -<LI>'<STRONG><CODE>skip|S</CODE></STRONG>=<EM>num</EM>' (<STRONG>s</STRONG>kip next rule(s))<BR> - This flag forces the rewriting engine to skip the next <EM>num</EM> rules - in sequence when the current rule matches. Use this to make pseudo - if-then-else constructs: The last rule of the then-clause becomes - <CODE>skip=N</CODE> where N is the number of rules in the else-clause. - (This is <STRONG>not</STRONG> the same as the 'chain|C' flag!) -<P> -<LI>'<STRONG><CODE>env|E=</CODE></STRONG><EM>VAR</EM>:<EM>VAL</EM>' (set <STRONG>e</STRONG>nvironment variable)<BR> - This forces an environment variable named <EM>VAR</EM> to be set to the - value <EM>VAL</EM>, where <EM>VAL</EM> can contain regexp backreferences - <CODE>$N</CODE> and <CODE>%N</CODE> which will be expanded. You can use this flag - more than once to set more than one variable. The variables can be later - dereferenced in many situations, but usually from - within XSSI (via <CODE><!--#echo var="VAR"--></CODE>) or CGI (<EM>e.g.</EM> - <CODE>$ENV{'VAR'}</CODE>). Additionally you can dereference it in a - following RewriteCond pattern via <CODE>%{ENV:VAR}</CODE>. Use this to strip - but remember information from URLs. -</UL> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> Never forget that <EM>Pattern</EM> is applied to a complete URL -in per-server configuration files. <STRONG>But in per-directory configuration -files, the per-directory prefix (which always is the same for a specific -directory!) is automatically <EM>removed</EM> for the pattern matching and -automatically <EM>added</EM> after the substitution has been done.</STRONG> This feature is -essential for many sorts of rewriting, because without this prefix stripping -you have to match the parent directory which is not always possible. -<P> -There is one exception: If a substitution string starts with -``<CODE>http://</CODE>'' then the directory prefix will <STRONG>not</STRONG> be added and an -external redirect or proxy throughput (if flag <STRONG>P</STRONG> is used!) is forced! -</TD></TR> -</TABLE> - -<P> -<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10> -<TR><TD> -<STRONG>Note:</STRONG> To enable the rewriting engine for per-directory configuration files -you need to set ``<CODE>RewriteEngine On</CODE>'' in these files <STRONG>and</STRONG> -``<CODE>Options FollowSymLinks</CODE>'' must be enabled. If your administrator has -disabled override of <CODE>FollowSymLinks</CODE> for a user's directory, then -you cannot use the rewriting engine. This restriction is needed for -security reasons. -</TD></TR> -</TABLE> - -<P> -Here are all possible substitution combinations and their meanings: - -<P> -<STRONG>Inside per-server configuration (<CODE>httpd.conf</CODE>)<BR> -for request ``<CODE>GET /somepath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ----------------------------------------------- ---------------------------------- -^/somepath(.*) otherpath$1 not supported, because invalid! - -^/somepath(.*) otherpath$1 [R] not supported, because invalid! - -^/somepath(.*) otherpath$1 [P] not supported, because invalid! ----------------------------------------------- ---------------------------------- -^/somepath(.*) /otherpath$1 /otherpath/pathinfo - -^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^/somepath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/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] not supported, because silly! ----------------------------------------------- ---------------------------------- -^/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 -</PRE> -</TD> -</TR> -</TABLE> - -<P> -<STRONG>Inside per-directory configuration for <CODE>/somepath</CODE><BR> -(<EM>i.e.</EM>, file <CODE>.htaccess</CODE> in dir <CODE>/physical/path/to/somepath</CODE> containing -<CODE>RewriteBase /somepath</CODE>)<BR> for -request ``<CODE>GET /somepath/localpath/pathinfo</CODE>'':</STRONG><BR> - -<P> -<TABLE BGCOLOR="#F0F0F0" CELLSPACING=0 CELLPADDING=5> -<TR> -<TD> -<PRE> -<STRONG>Given Rule</STRONG> <STRONG>Resulting Substitution</STRONG> ----------------------------------------------- ---------------------------------- -^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo - -^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo - via external redirection - -^localpath(.*) otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^localpath(.*) /otherpath$1 /otherpath/pathinfo - -^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo - via external redirection - -^localpath(.*) /otherpath$1 [P] not supported, because silly! ----------------------------------------------- ---------------------------------- -^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] not supported, because silly! ----------------------------------------------- ---------------------------------- -^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 -</PRE> -</TD> -</TR> -</TABLE> - -<P> -<STRONG>Example:</STRONG> -<P> -<BLOCKQUOTE> -We want to rewrite URLs of the form -<BLOCKQUOTE> -<CODE>/</CODE> <EM>Language</EM> -<CODE>/~</CODE> <EM>Realname</EM> -<CODE>/.../</CODE> <EM>File</EM> -</BLOCKQUOTE> -into -<BLOCKQUOTE> -<CODE>/u/</CODE> <EM>Username</EM> -<CODE>/.../</CODE> <EM>File</EM> -<CODE>.</CODE> <EM>Language</EM> -</BLOCKQUOTE> -<P> -We take the rewrite mapfile from above and save it under -<CODE>/path/to/file/map.txt</CODE>. Then we only have to add the -following lines to the Apache server configuration file: - -<BLOCKQUOTE> -<PRE> -RewriteLog /path/to/file/rewrite.log -RewriteMap real-to-user txt:/path/to/file/map.txt -RewriteRule ^/([^/]+)/~([^/]+)/(.*)$ /u/${real-to-user:$2|nobody}/$3.$1 -</PRE> -</BLOCKQUOTE> - -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<CENTER> -<H1><A NAME="Miscelleneous">Miscellaneous</A></H1> -</CENTER> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="EnvVar">Environment Variables</A></H2> - -This module keeps track of two additional (non-standard) CGI/SSI environment -variables named <CODE>SCRIPT_URL</CODE> and <CODE>SCRIPT_URI</CODE>. These contain -the <EM>logical</EM> Web-view to the current resource, while the standard CGI/SSI -variables <CODE>SCRIPT_NAME</CODE> and <CODE>SCRIPT_FILENAME</CODE> contain the -<EM>physical</EM> System-view. - -<P> -Notice: These variables hold the URI/URL <EM>as they were initially -requested</EM>, <EM>i.e.</EM>, <EM>before</EM> any rewriting. This is -important because the rewriting process is primarily used to rewrite logical -URLs to physical pathnames. - -<P> -<STRONG>Example:</STRONG> - -<BLOCKQUOTE> -<PRE> -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/ -</PRE> -</BLOCKQUOTE> - -<P> -<HR NOSHADE SIZE=1> - -<H2><A NAME="Solutions">Practical Solutions</A></H2> - -We also have an <a href="../misc/rewriteguide.html">URL Rewriting -Guide</a> available, which provides a collection of practical solutions -for URL-based problems. There you can find real-life rulesets and -additional information about mod_rewrite. - -<!--#include virtual="footer.html" --> -</BLOCKQUOTE><!-- page indentation --> -</BODY> -</HTML> -<!--/%hypertext --> |