mod_rewrite.html revision dff77f20d3ca0296e740d4369989e57949a06e92
f072359f493a5209335799da85ac16d6a273303bgryzor<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">
f072359f493a5209335799da85ac16d6a273303bgryzor<!--%hypertext -->
f072359f493a5209335799da85ac16d6a273303bgryzor<!-- Documentation for the mod_rewrite Apache module -->
f072359f493a5209335799da85ac16d6a273303bgryzor<!-- Background white, links blue (unvisited), navy (visited), red (active) -->
f072359f493a5209335799da85ac16d6a273303bgryzor BGCOLOR="#FFFFFF"
f072359f493a5209335799da85ac16d6a273303bgryzor TEXT="#000000"
f072359f493a5209335799da85ac16d6a273303bgryzor LINK="#0000FF"
f072359f493a5209335799da85ac16d6a273303bgryzor VLINK="#000080"
f072359f493a5209335799da85ac16d6a273303bgryzor ALINK="#FF0000"
f072359f493a5209335799da85ac16d6a273303bgryzor<!--#include virtual="header.html" -->
f072359f493a5209335799da85ac16d6a273303bgryzor<H1 ALIGN="CENTER">Module mod_rewrite<BR>URL Rewriting Engine</H1>
f072359f493a5209335799da85ac16d6a273303bgryzor<p>This module provides a rule-based rewriting engine to rewrite requested
f072359f493a5209335799da85ac16d6a273303bgryzorURLs on the fly.</p>
f072359f493a5209335799da85ac16d6a273303bgryzorHREF="module-dict.html#SourceFile"
f072359f493a5209335799da85ac16d6a273303bgryzorHREF="module-dict.html#ModuleIdentifier"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Module Identifier:</STRONG></A> rewrite_module
f072359f493a5209335799da85ac16d6a273303bgryzorHREF="module-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Compatibility:</STRONG></A> Available in Apache 1.2 and later.
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>``The great thing about mod_rewrite is it gives you all the
f072359f493a5209335799da85ac16d6a273303bgryzorconfigurability and flexibility of Sendmail. The downside to
f072359f493a5209335799da85ac16d6a273303bgryzormod_rewrite is that it gives you all the configurability and
f072359f493a5209335799da85ac16d6a273303bgryzorflexibility of Sendmail.''</EM>
f072359f493a5209335799da85ac16d6a273303bgryzor-- Brian Behlendorf<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorApache Group
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorDespite the tons of examples and docs, mod_rewrite
f072359f493a5209335799da85ac16d6a273303bgryzoris voodoo. Damned cool voodoo, but still voodoo.
f072359f493a5209335799da85ac16d6a273303bgryzor-- Brian Moore<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorbem@news.cmc.net
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorWelcome to mod_rewrite, the Swiss Army Knife of URL manipulation!
f072359f493a5209335799da85ac16d6a273303bgryzorThis module uses a rule-based rewriting engine (based on a regular-expression
f072359f493a5209335799da85ac16d6a273303bgryzorparser) to rewrite requested URLs on the fly. It supports an unlimited number
f072359f493a5209335799da85ac16d6a273303bgryzorof rules and an unlimited number of attached rule conditions for each rule to
f072359f493a5209335799da85ac16d6a273303bgryzorprovide a really flexible and powerful URL manipulation mechanism. The URL
f072359f493a5209335799da85ac16d6a273303bgryzormanipulations can depend on various tests, for instance server variables,
f072359f493a5209335799da85ac16d6a273303bgryzorenvironment variables, HTTP headers, time stamps and even external database
f072359f493a5209335799da85ac16d6a273303bgryzorlookups in various formats can be used to achieve a really granular URL
f072359f493a5209335799da85ac16d6a273303bgryzorThis module operates on the full URLs (including the path-info part) both in
f072359f493a5209335799da85ac16d6a273303bgryzorper-server context (<CODE>httpd.conf</CODE>) and per-directory context
f072359f493a5209335799da85ac16d6a273303bgryzor(<CODE>.htaccess</CODE>) and can even generate query-string parts on result.
f072359f493a5209335799da85ac16d6a273303bgryzorThe rewritten result can lead to internal sub-processing, external request
f072359f493a5209335799da85ac16d6a273303bgryzorredirection or even to an internal proxy throughput.
f072359f493a5209335799da85ac16d6a273303bgryzorBut all this functionality and flexibility has its drawback: complexity. So
f072359f493a5209335799da85ac16d6a273303bgryzordon't expect to understand this entire module in just one day.
f072359f493a5209335799da85ac16d6a273303bgryzorThis module was invented and originally written in April 1996<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorand gifted exclusively to the The Apache Group in July 1997 by
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<A HREF="http://www.engelschall.com/"><CODE>Ralf S. Engelschall</CODE></A><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor<A HREF="mailto:rse@engelschall.com"><CODE>rse@engelschall.com</CODE></A><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor<A HREF="http://www.engelschall.com/"><CODE>www.engelschall.com</CODE></A>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor <LI><A HREF="#InternalRuleset">Ruleset Processing</A>
f072359f493a5209335799da85ac16d6a273303bgryzor <LI><A HREF="#InternalBackRefs">Regex Back-Reference Availability</A>
f072359f493a5209335799da85ac16d6a273303bgryzorThe internal processing of this module is very complex but needs to be
f072359f493a5209335799da85ac16d6a273303bgryzorexplained once even to the average user to avoid common mistakes and to let
f072359f493a5209335799da85ac16d6a273303bgryzoryou exploit its full functionality.
f072359f493a5209335799da85ac16d6a273303bgryzorFirst you have to understand that when Apache processes a HTTP request it does
f072359f493a5209335799da85ac16d6a273303bgryzorthis in phases. A hook for each of these phases is provided by the Apache API.
f072359f493a5209335799da85ac16d6a273303bgryzorMod_rewrite uses two of these hooks: the URL-to-filename translation hook
f072359f493a5209335799da85ac16d6a273303bgryzorwhich is used after the HTTP request has been read but before any authorization
f072359f493a5209335799da85ac16d6a273303bgryzorstarts and the Fixup hook which is triggered after the authorization phases
f072359f493a5209335799da85ac16d6a273303bgryzorand after the per-directory config files (<CODE>.htaccess</CODE>) have been
f072359f493a5209335799da85ac16d6a273303bgryzorread, but before the content handler is activated.
f072359f493a5209335799da85ac16d6a273303bgryzorSo, after a request comes in and Apache has determined the corresponding
f072359f493a5209335799da85ac16d6a273303bgryzorserver (or virtual server) the rewriting engine starts processing of all
f072359f493a5209335799da85ac16d6a273303bgryzormod_rewrite directives from the per-server configuration in the
f072359f493a5209335799da85ac16d6a273303bgryzorURL-to-filename phase. A few steps later when the final data directories are
f072359f493a5209335799da85ac16d6a273303bgryzorfound, the per-directory configuration directives of mod_rewrite are triggered
f072359f493a5209335799da85ac16d6a273303bgryzorin the Fixup phase. In both situations mod_rewrite rewrites URLs either to new
f072359f493a5209335799da85ac16d6a273303bgryzorURLs or to filenames, although there is no obvious distinction between them.
f072359f493a5209335799da85ac16d6a273303bgryzorThis is a usage of the API which was not intended to be this way when the API
f072359f493a5209335799da85ac16d6a273303bgryzorwas designed, but as of Apache 1.x this is the only way mod_rewrite can
f072359f493a5209335799da85ac16d6a273303bgryzoroperate. To make this point more clear remember the following two points:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>Although mod_rewrite rewrites URLs to URLs, URLs to filenames and
f072359f493a5209335799da85ac16d6a273303bgryzor even filenames to filenames, the API currently provides only a
f072359f493a5209335799da85ac16d6a273303bgryzor URL-to-filename hook. In Apache 2.0 the two missing hooks will be
f072359f493a5209335799da85ac16d6a273303bgryzor added to make the processing more clear. But this point has no
f072359f493a5209335799da85ac16d6a273303bgryzor drawbacks for the user, it is just a fact which should be
eef716e54c415709ca9d53aad4678bf9d96186e6nd remembered: Apache does more in the URL-to-filename hook than the
f072359f493a5209335799da85ac16d6a273303bgryzor API intends for it.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>Unbelievably mod_rewrite provides URL manipulations in per-directory
f072359f493a5209335799da85ac16d6a273303bgryzor context, <EM>i.e.</EM>, within <CODE>.htaccess</CODE> files,
f072359f493a5209335799da85ac16d6a273303bgryzor although these are reached a very long time after the URLs have
f072359f493a5209335799da85ac16d6a273303bgryzor been translated to filenames. It has to be this way because
f072359f493a5209335799da85ac16d6a273303bgryzor <CODE>.htaccess</CODE> files live in the filesystem, so processing
f072359f493a5209335799da85ac16d6a273303bgryzor has already reached this stage. In other words: According to the
f072359f493a5209335799da85ac16d6a273303bgryzor API phases at this time it is too late for any URL manipulations.
f072359f493a5209335799da85ac16d6a273303bgryzor To overcome this chicken and egg problem mod_rewrite uses a trick:
f072359f493a5209335799da85ac16d6a273303bgryzor When you manipulate a URL/filename in per-directory context
f072359f493a5209335799da85ac16d6a273303bgryzor mod_rewrite first rewrites the filename back to its corresponding
f072359f493a5209335799da85ac16d6a273303bgryzor URL (which is usually impossible, but see the <CODE>RewriteBase</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzor directive below for the trick to achieve this) and then initiates
eef716e54c415709ca9d53aad4678bf9d96186e6nd a new internal sub-request with the new URL. This restarts
eef716e54c415709ca9d53aad4678bf9d96186e6nd processing of the API phases.
f072359f493a5209335799da85ac16d6a273303bgryzor Again mod_rewrite tries hard to make this complicated step totally
f072359f493a5209335799da85ac16d6a273303bgryzor transparent to the user, but you should remember here: While URL
f072359f493a5209335799da85ac16d6a273303bgryzor manipulations in per-server context are really fast and efficient,
f072359f493a5209335799da85ac16d6a273303bgryzor per-directory rewrites are slow and inefficient due to this chicken and
f072359f493a5209335799da85ac16d6a273303bgryzor egg problem. But on the other hand this is the only way mod_rewrite can
f072359f493a5209335799da85ac16d6a273303bgryzor provide (locally restricted) URL manipulations to the average user.
f072359f493a5209335799da85ac16d6a273303bgryzorDon't forget these two points!
f072359f493a5209335799da85ac16d6a273303bgryzor<H2><A NAME="InternalRuleset">Ruleset Processing</A></H2>
f072359f493a5209335799da85ac16d6a273303bgryzorNow when mod_rewrite is triggered in these two API phases, it reads the
f072359f493a5209335799da85ac16d6a273303bgryzorconfigured rulesets from its configuration structure (which itself was either
f072359f493a5209335799da85ac16d6a273303bgryzorcreated on startup for per-server context or during the directory walk of the
f072359f493a5209335799da85ac16d6a273303bgryzorApache kernel for per-directory context). Then the URL rewriting engine is
f072359f493a5209335799da85ac16d6a273303bgryzorstarted with the contained ruleset (one or more rules together with their
f072359f493a5209335799da85ac16d6a273303bgryzorconditions). The operation of the URL rewriting engine itself is exactly the
f072359f493a5209335799da85ac16d6a273303bgryzorsame for both configuration contexts. Only the final result processing is
f072359f493a5209335799da85ac16d6a273303bgryzorThe order of rules in the ruleset is important because the rewriting engine
f072359f493a5209335799da85ac16d6a273303bgryzorprocesses them in a special (and not very obvious) order. The
f072359f493a5209335799da85ac16d6a273303bgryzorrule is this: The rewriting engine loops through the ruleset rule by rule
f072359f493a5209335799da85ac16d6a273303bgryzor(<CODE>RewriteRule</CODE> directives) and when a particular rule matches it
f072359f493a5209335799da85ac16d6a273303bgryzoroptionally loops through existing corresponding conditions
f072359f493a5209335799da85ac16d6a273303bgryzor(<CODE>RewriteCond</CODE> directives). For historical reasons the conditions
f072359f493a5209335799da85ac16d6a273303bgryzorare given first, and so the control flow is a little bit long-winded. See
f072359f493a5209335799da85ac16d6a273303bgryzorFigure 1 for more details.
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Figure 1:</STRONG> The control flow through the rewriting ruleset
f072359f493a5209335799da85ac16d6a273303bgryzorAs you can see, first the URL is matched against the <EM>Pattern</EM> of each
f072359f493a5209335799da85ac16d6a273303bgryzorrule. When it fails mod_rewrite immediately stops processing this rule and
f072359f493a5209335799da85ac16d6a273303bgryzorcontinues with the next rule. If the <EM>Pattern</EM> matches, mod_rewrite
f072359f493a5209335799da85ac16d6a273303bgryzorlooks for corresponding rule conditions. If none are present, it just
f072359f493a5209335799da85ac16d6a273303bgryzorsubstitutes the URL with a new value which is constructed from the string
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Substitution</EM> and goes on with its rule-looping. But if conditions
f072359f493a5209335799da85ac16d6a273303bgryzorexist, it starts an inner loop for processing them in the order that
f072359f493a5209335799da85ac16d6a273303bgryzorthey are listed. For conditions the logic is different: we don't match a
f072359f493a5209335799da85ac16d6a273303bgryzorpattern against the current URL. Instead we first create a string
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> by expanding variables, back-references, map lookups,
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>etc.</EM> and then we try to match <EM>CondPattern</EM> against it. If the
f072359f493a5209335799da85ac16d6a273303bgryzorpattern doesn't match, the complete set of conditions and the corresponding
eef716e54c415709ca9d53aad4678bf9d96186e6ndrule fails. If the pattern matches, then the next condition is processed
f072359f493a5209335799da85ac16d6a273303bgryzoruntil no more conditions are available. If all conditions match, processing
f072359f493a5209335799da85ac16d6a273303bgryzoris continued with the substitution of the URL with <EM>Substitution</EM>.
f072359f493a5209335799da85ac16d6a273303bgryzor<h2><a name="quoting">Quoting Special Characters</a></h2>
f072359f493a5209335799da85ac16d6a273303bgryzorAs of Apache 1.3.20, special characters in <i>TestString</i> and
f072359f493a5209335799da85ac16d6a273303bgryzor<i>Substitution</i> strings can be escaped (that is, treated as
f072359f493a5209335799da85ac16d6a273303bgryzornormal characters without their usual special meaning) by prefixing them
f072359f493a5209335799da85ac16d6a273303bgryzorwith a slosh ('\') character. In other words, you can include an
f072359f493a5209335799da85ac16d6a273303bgryzoractual dollar-sign character in a <i>Substitution</i> string
f072359f493a5209335799da85ac16d6a273303bgryzorby using '<code>\$</code>'; this keeps mod_rewrite from trying
f072359f493a5209335799da85ac16d6a273303bgryzorto treat it as a backreference.
f072359f493a5209335799da85ac16d6a273303bgryzor<H2><A NAME="InternalBackRefs">Regex Back-Reference Availability</A></H2>
f072359f493a5209335799da85ac16d6a273303bgryzorOne important thing here has to be remembered: Whenever you
f072359f493a5209335799da85ac16d6a273303bgryzoruse parentheses in <EM>Pattern</EM> or in one of the <EM>CondPattern</EM>,
f072359f493a5209335799da85ac16d6a273303bgryzorback-references are internally created which can be used with the
f072359f493a5209335799da85ac16d6a273303bgryzorstrings <CODE>$N</CODE> and <CODE>%N</CODE> (see below). These
f072359f493a5209335799da85ac16d6a273303bgryzorare available for creating the strings <EM>Substitution</EM> and
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM>. Figure 2 shows to which locations the back-references are
f072359f493a5209335799da85ac16d6a273303bgryzortransfered for expansion.
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Figure 2:</STRONG> The back-reference flow through a rule
f072359f493a5209335799da85ac16d6a273303bgryzorWe know this was a crash course on mod_rewrite's internal processing. But
f072359f493a5209335799da85ac16d6a273303bgryzoryou will benefit from this knowledge when reading the following documentation
f072359f493a5209335799da85ac16d6a273303bgryzorof the available directives.
f072359f493a5209335799da85ac16d6a273303bgryzor<H1><A NAME="Configuration">Configuration Directives</A></H1>
f072359f493a5209335799da85ac16d6a273303bgryzor RewriteEngine on|off<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor server config, virtual host, directory, .htaccess<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteEngine</CODE> directive enables or disables the runtime
f072359f493a5209335799da85ac16d6a273303bgryzorrewriting engine. If it is set to <CODE>off</CODE> this module does no runtime
f072359f493a5209335799da85ac16d6a273303bgryzorprocessing at all. It does not even update the <CODE>SCRIPT_URx</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzorenvironment variables.
f072359f493a5209335799da85ac16d6a273303bgryzorUse this directive to disable the module instead of commenting out
f072359f493a5209335799da85ac16d6a273303bgryzorNote that, by default, rewrite configurations are not inherited.
f072359f493a5209335799da85ac16d6a273303bgryzorThis means that you need to have a <CODE>RewriteEngine on</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzordirective for each virtual host in which you wish to use it.
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteOptions <EM>Option</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host, directory,
f072359f493a5209335799da85ac16d6a273303bgryzor .htaccess<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
eef716e54c415709ca9d53aad4678bf9d96186e6nd HREF="directive-dict.html#Compatibility"
eef716e54c415709ca9d53aad4678bf9d96186e6nd REL="Help"
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteOptions</CODE> directive sets some special options for the
f072359f493a5209335799da85ac16d6a273303bgryzorcurrent per-server or per-directory configuration. The <EM>Option</EM>
f072359f493a5209335799da85ac16d6a273303bgryzorstrings can be one of the following:
f072359f493a5209335799da85ac16d6a273303bgryzor This forces the current configuration to inherit the configuration of the
f072359f493a5209335799da85ac16d6a273303bgryzor parent. In per-virtual-server context this means that the maps,
f072359f493a5209335799da85ac16d6a273303bgryzor conditions and rules of the main server are inherited. In per-directory
f072359f493a5209335799da85ac16d6a273303bgryzor context this means that conditions and rules of the parent directory's
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteLog <EM>file-path</EM><BR>
eef716e54c415709ca9d53aad4678bf9d96186e6nd REL="Help"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteLog</CODE> directive sets the name of the file to which the
f072359f493a5209335799da85ac16d6a273303bgryzorserver logs any rewriting actions it performs. If the name does not begin
f072359f493a5209335799da85ac16d6a273303bgryzorwith a slash ('<CODE>/</CODE>') then it is assumed to be relative to the
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Server Root</EM>. The directive should occur only once per server
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Note</STRONG>: To disable the logging of rewriting actions it is
f072359f493a5209335799da85ac16d6a273303bgryzorto <CODE>/dev/null</CODE>, because although the rewriting engine does
f072359f493a5209335799da85ac16d6a273303bgryzornot then output to a logfile it still creates the logfile
f072359f493a5209335799da85ac16d6a273303bgryzoroutput internally. <STRONG>This will slow down the server with no advantage
f072359f493a5209335799da85ac16d6a273303bgryzorto the administrator!</STRONG>
f072359f493a5209335799da85ac16d6a273303bgryzorTo disable logging either remove or comment out the
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>RewriteLog</CODE> directive or use <CODE>RewriteLogLevel 0</CODE>!
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzorHREF="/misc/security_tips.html">Apache Security
f072359f493a5209335799da85ac16d6a273303bgryzorTips</A> document for details on why your security could be compromised if the
f072359f493a5209335799da85ac16d6a273303bgryzordirectory where logfiles are stored is writable by anyone other than the user
f072359f493a5209335799da85ac16d6a273303bgryzorthat starts the server.
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor<H3><A NAME="RewriteLogLevel">RewriteLogLevel</A></H3>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteLogLevel <EM>Level</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Default:</STRONG></A> <CODE>RewriteLogLevel 0</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
e797af4d7b0cada1278d72d6c8ac77210ef78632minfrin><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteLogLevel</CODE> directive sets the verbosity level of the
f072359f493a5209335799da85ac16d6a273303bgryzorlogfile. The default level 0 means no logging, while 9 or more means
f072359f493a5209335799da85ac16d6a273303bgryzorthat practically all actions are logged.
f072359f493a5209335799da85ac16d6a273303bgryzorTo disable the logging of rewriting actions simply set <EM>Level</EM> to 0.
f072359f493a5209335799da85ac16d6a273303bgryzorThis disables all rewrite action logs.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Notice:</STRONG> Using a high value for <EM>Level</EM> will slow down
f072359f493a5209335799da85ac16d6a273303bgryzoryour Apache server dramatically! Use the rewriting logfile at
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteLogLevel 3
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteLock <EM>file-path</EM><BR>
7cc5e8f14e6ab2d8b60bb0eaba4b68b00d320b29nd HREF="directive-dict.html#Default"
7cc5e8f14e6ab2d8b60bb0eaba4b68b00d320b29nd REL="Help"
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzorThis directive sets the filename for a synchronization lockfile which
f072359f493a5209335799da85ac16d6a273303bgryzormod_rewrite needs to communicate with <SAMP>RewriteMap</SAMP>
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>programs</EM>. Set this lockfile to a local path (not on a NFS-mounted
f072359f493a5209335799da85ac16d6a273303bgryzordevice) when you want to use a rewriting map-program. It is not required for
f072359f493a5209335799da85ac16d6a273303bgryzorother types of rewriting maps.
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteMap <EM>MapName </EM>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Default:</STRONG></A> not used per default<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Override:</STRONG></A> <EM>Not applicable</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteMap</CODE> directive defines a <EM>Rewriting Map</EM>
f072359f493a5209335799da85ac16d6a273303bgryzorwhich can be used inside rule substitution strings by the mapping-functions
f072359f493a5209335799da85ac16d6a273303bgryzorto insert/substitute fields through a key lookup. The source of this
f072359f493a5209335799da85ac16d6a273303bgryzorlookup can be of various types.
f072359f493a5209335799da85ac16d6a273303bgryzorThe <A NAME="mapfunc"><EM>MapName</EM></A> is the name of the map and will
f072359f493a5209335799da85ac16d6a273303bgryzorbe used to specify a mapping-function for the substitution strings of a
f072359f493a5209335799da85ac16d6a273303bgryzorrewriting rule via one of the following constructs:
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM>
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>${</CODE> <EM>MapName</EM> <CODE>:</CODE> <EM>LookupKey</EM>
f072359f493a5209335799da85ac16d6a273303bgryzoris consulted and the key <EM>LookupKey</EM> is looked-up. If the key is
f072359f493a5209335799da85ac16d6a273303bgryzorfound, the map-function construct is substituted by <EM>SubstValue</EM>. If
f072359f493a5209335799da85ac16d6a273303bgryzorthe key is not found then it is substituted by <EM>DefaultValue</EM> or
f072359f493a5209335799da85ac16d6a273303bgryzorby the empty string if no <EM>DefaultValue</EM> was specified.
f072359f493a5209335799da85ac16d6a273303bgryzorThe following combinations for <EM>MapType</EM> and <EM>MapSource</EM>
f072359f493a5209335799da85ac16d6a273303bgryzorcan be used:
f072359f493a5209335799da85ac16d6a273303bgryzor MapType: <CODE>txt</CODE>, MapSource: Unix filesystem path to valid regular
f072359f493a5209335799da85ac16d6a273303bgryzor This is the standard rewriting map feature where the <EM>MapSource</EM> is
f072359f493a5209335799da85ac16d6a273303bgryzor a plain ASCII file containing either blank lines, comment lines (starting
f072359f493a5209335799da85ac16d6a273303bgryzor with a '#' character) or pairs like the following - one per line.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor## map.txt -- rewriting map
f072359f493a5209335799da85ac16d6a273303bgryzorRalf.S.Engelschall rse # Bastard Operator From Hell
f072359f493a5209335799da85ac16d6a273303bgryzorMr.Joe.Average joe # Mr. Average
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor MapType: <CODE>rnd</CODE>, MapSource: Unix filesystem path to valid regular
f072359f493a5209335799da85ac16d6a273303bgryzor This is identical to the Standard Plain Text variant above but with a
f072359f493a5209335799da85ac16d6a273303bgryzor post-processing feature: After looking up a value it is parsed according
f072359f493a5209335799da85ac16d6a273303bgryzor to contained ``<CODE>|</CODE>'' characters which have the meaning of
f072359f493a5209335799da85ac16d6a273303bgryzor In other words they indicate a set of alternatives from which the actual
f072359f493a5209335799da85ac16d6a273303bgryzor returned value is chosen randomly. Although this sounds crazy and useless,
f072359f493a5209335799da85ac16d6a273303bgryzor was actually designed for load balancing in a reverse proxy situation where
f072359f493a5209335799da85ac16d6a273303bgryzor the looked up values are server names.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor## map.txt -- rewriting map
f072359f493a5209335799da85ac16d6a273303bgryzorstatic www1|www2|www3|www4
f072359f493a5209335799da85ac16d6a273303bgryzordynamic www5|www6
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor MapType: <CODE>dbm</CODE>, MapSource: Unix filesystem path to valid
f072359f493a5209335799da85ac16d6a273303bgryzor regular file
f072359f493a5209335799da85ac16d6a273303bgryzor Here the source is a binary NDBM format file containing the same contents
f072359f493a5209335799da85ac16d6a273303bgryzor as a <EM>Plain Text</EM> format file, but in a special representation
f072359f493a5209335799da85ac16d6a273303bgryzor which is optimized for really fast lookups. You can create such a file with
f072359f493a5209335799da85ac16d6a273303bgryzor any NDBM tool or with the following Perl script:
f072359f493a5209335799da85ac16d6a273303bgryzor <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor## txt2dbm -- convert txt map to dbm format
7cc5e8f14e6ab2d8b60bb0eaba4b68b00d320b29nd($txtmap, $dbmmap) = @ARGV;
7cc5e8f14e6ab2d8b60bb0eaba4b68b00d320b29ndopen(TXT, "<$txtmap");
f072359f493a5209335799da85ac16d6a273303bgryzordbmopen(%DB, $dbmmap, 0644);
f072359f493a5209335799da85ac16d6a273303bgryzorwhile (<TXT>) {
f072359f493a5209335799da85ac16d6a273303bgryzor next if (m|^s*#.*| or m|^s*$|);
f072359f493a5209335799da85ac16d6a273303bgryzor $DB{$1} = $2 if (m|^\s*(\S+)\s+(\S+)$|);
f072359f493a5209335799da85ac16d6a273303bgryzordbmclose(%DB);
f072359f493a5209335799da85ac16d6a273303bgryzor <TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor <TR><TD><PRE>$ txt2dbm map.txt map.db </PRE></TD></TR>
f072359f493a5209335799da85ac16d6a273303bgryzor MapType: <CODE>int</CODE>, MapSource: Internal Apache function
f072359f493a5209335799da85ac16d6a273303bgryzor Here the source is an internal Apache function. Currently you cannot
f072359f493a5209335799da85ac16d6a273303bgryzor create your own, but the following functions already exists:
f072359f493a5209335799da85ac16d6a273303bgryzor Converts the looked up key to all upper case.
f072359f493a5209335799da85ac16d6a273303bgryzor Converts the looked up key to all lower case.
f072359f493a5209335799da85ac16d6a273303bgryzor Translates special characters in the looked up key to hex-encodings.
f072359f493a5209335799da85ac16d6a273303bgryzor Translates hex-encodings in the looked up key back to special characters.
f072359f493a5209335799da85ac16d6a273303bgryzor MapType: <CODE>prg</CODE>, MapSource: Unix filesystem path to valid
f072359f493a5209335799da85ac16d6a273303bgryzor regular file
f072359f493a5209335799da85ac16d6a273303bgryzor Here the source is a program, not a map file. To create it you
f072359f493a5209335799da85ac16d6a273303bgryzor can use the language of your choice, but the result has to be a
f072359f493a5209335799da85ac16d6a273303bgryzor executable (<EM>i.e.</EM>, either object-code or a script with the
f072359f493a5209335799da85ac16d6a273303bgryzor magic cookie trick '<CODE>#!/path/to/interpreter</CODE>' as the
f072359f493a5209335799da85ac16d6a273303bgryzor first line).
f072359f493a5209335799da85ac16d6a273303bgryzor This program is started once at startup of the Apache servers and then
f072359f493a5209335799da85ac16d6a273303bgryzor communicates with the rewriting engine over its <CODE>stdin</CODE> and
f072359f493a5209335799da85ac16d6a273303bgryzor <CODE>stdout</CODE> file-handles. For each map-function lookup it will
f072359f493a5209335799da85ac16d6a273303bgryzor receive the key to lookup as a newline-terminated string on
f072359f493a5209335799da85ac16d6a273303bgryzor <CODE>stdin</CODE>. It then has to give back the looked-up value as a
f072359f493a5209335799da85ac16d6a273303bgryzor newline-terminated string on <CODE>stdout</CODE> or the four-character
f072359f493a5209335799da85ac16d6a273303bgryzor string ``<CODE>NULL</CODE>'' if it fails (<EM>i.e.</EM>, there is no
f072359f493a5209335799da85ac16d6a273303bgryzor corresponding value
f072359f493a5209335799da85ac16d6a273303bgryzor for the given key). A trivial program which will implement a 1:1 map
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzorwhile (<STDIN>) {
f072359f493a5209335799da85ac16d6a273303bgryzor # ...put here any transformations or lookups...
eef716e54c415709ca9d53aad4678bf9d96186e6nd But be very careful:<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor <LI>``<EM>Keep it simple, stupid</EM>'' (KISS), because
eef716e54c415709ca9d53aad4678bf9d96186e6nd if this program hangs it will hang the Apache server
f072359f493a5209335799da85ac16d6a273303bgryzor when the rule occurs.
f072359f493a5209335799da85ac16d6a273303bgryzor <LI>Avoid one common mistake: never do buffered I/O on <CODE>stdout</CODE>!
f072359f493a5209335799da85ac16d6a273303bgryzor This will cause a deadloop! Hence the ``<CODE>$|=1</CODE>'' in the
eef716e54c415709ca9d53aad4678bf9d96186e6nd above example...
eef716e54c415709ca9d53aad4678bf9d96186e6nd <LI>Use the <SAMP>RewriteLock</SAMP> directive to define a lockfile
f072359f493a5209335799da85ac16d6a273303bgryzor mod_rewrite can use to synchronize the communication to the program.
f072359f493a5209335799da85ac16d6a273303bgryzor By default no such synchronization takes place.
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteMap</CODE> directive can occur more than once. For each
f072359f493a5209335799da85ac16d6a273303bgryzormapping-function use one <CODE>RewriteMap</CODE> directive to declare its
f072359f493a5209335799da85ac16d6a273303bgryzorrewriting mapfile. While you cannot <STRONG>declare</STRONG> a map in
f072359f493a5209335799da85ac16d6a273303bgryzorper-directory context it is of course possible to <STRONG>use</STRONG>
f072359f493a5209335799da85ac16d6a273303bgryzorthis map in per-directory context.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Note:</STRONG> For plain text and DBM format files the looked-up
eef716e54c415709ca9d53aad4678bf9d96186e6ndkeys are cached in-core
f072359f493a5209335799da85ac16d6a273303bgryzoruntil the <CODE>mtime</CODE> of the mapfile changes or the server does a
f072359f493a5209335799da85ac16d6a273303bgryzorrestart. This way you can have map-functions in rules which are used
f072359f493a5209335799da85ac16d6a273303bgryzorfor <STRONG>every</STRONG> request. This is no problem, because the
eef716e54c415709ca9d53aad4678bf9d96186e6ndexternal lookup only happens once!
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteBase <EM>URL-path</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Default:</STRONG></A> <EM>default is the physical directory path</EM>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> directory, .htaccess<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
eef716e54c415709ca9d53aad4678bf9d96186e6nd REL="Help"
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteBase</CODE> directive explicitly sets the base URL for
f072359f493a5209335799da85ac16d6a273303bgryzorper-directory rewrites. As you will see below, <CODE>RewriteRule</CODE> can be
f072359f493a5209335799da85ac16d6a273303bgryzorused in per-directory config files (<CODE>.htaccess</CODE>). There it will act
f072359f493a5209335799da85ac16d6a273303bgryzorlocally, <EM>i.e.</EM>, the local directory prefix is stripped at this stage of
f072359f493a5209335799da85ac16d6a273303bgryzorprocessing and your rewriting rules act only on the remainder. At the end
f072359f493a5209335799da85ac16d6a273303bgryzorit is automatically added back to the path.
f072359f493a5209335799da85ac16d6a273303bgryzorWhen a substitution occurs for a new URL, this module has to re-inject the URL
f072359f493a5209335799da85ac16d6a273303bgryzorinto the server processing. To be able to do this it needs to know what the
f072359f493a5209335799da85ac16d6a273303bgryzorcorresponding URL-prefix or URL-base is. By default this prefix is the
f072359f493a5209335799da85ac16d6a273303bgryzorcorresponding filepath itself. <STRONG>But at most websites URLs are
f072359f493a5209335799da85ac16d6a273303bgryzorNOT directly related to physical filename paths, so this
f072359f493a5209335799da85ac16d6a273303bgryzorassumption will usually be wrong!</STRONG> There you have to use the
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>RewriteBase</CODE> directive to specify the correct URL-prefix.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Notice:</STRONG> If your webserver's URLs are <STRONG>not</STRONG>
f072359f493a5209335799da85ac16d6a273303bgryzordirectly related to physical file paths, you have to use
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>.htaccess</CODE> files where you want to use <CODE>RewriteRule</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor Assume the following per-directory config file:
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE BORDER=0 CELLSPACING=1 CELLPADDING=5 BGCOLOR="#F0F0F0">
f072359f493a5209335799da85ac16d6a273303bgryzor# /abc/def/.htaccess -- per-dir config file for directory /abc/def
f072359f493a5209335799da85ac16d6a273303bgryzor# Remember: /abc/def is the physical path of /xyz, <EM>i.e.</EM>, the server
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteEngine On
f072359f493a5209335799da85ac16d6a273303bgryzor# let the server know that we were reached via /xyz and not
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteBase /xyz
f072359f493a5209335799da85ac16d6a273303bgryzor# now the rewriting rules
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteRule ^oldstuff\.html$ newstuff.html
f072359f493a5209335799da85ac16d6a273303bgryzorIn the above example, a request to <CODE>/xyz/oldstuff.html</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzorgets correctly
f072359f493a5209335799da85ac16d6a273303bgryzorrewritten to the physical file <CODE>/abc/def/newstuff.html</CODE>.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzorThe following list gives detailed information about the internal
f072359f493a5209335799da85ac16d6a273303bgryzorprocessing steps:
f072359f493a5209335799da85ac16d6a273303bgryzorInternal Processing:
f072359f493a5209335799da85ac16d6a273303bgryzor /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
f072359f493a5209335799da85ac16d6a273303bgryzor /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
f072359f493a5209335799da85ac16d6a273303bgryzor /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
f072359f493a5209335799da85ac16d6a273303bgryzor /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
f072359f493a5209335799da85ac16d6a273303bgryzorThis seems very complicated but is the correct Apache internal processing,
f072359f493a5209335799da85ac16d6a273303bgryzorbecause the per-directory rewriting comes too late in the process. So,
f072359f493a5209335799da85ac16d6a273303bgryzorwhen it occurs the (rewritten) request has to be re-injected into the Apache
f072359f493a5209335799da85ac16d6a273303bgryzorkernel! BUT: While this seems like a serious overhead, it really isn't, because
f072359f493a5209335799da85ac16d6a273303bgryzorthis re-injection happens fully internally to the Apache server and the same
f072359f493a5209335799da85ac16d6a273303bgryzorprocedure is used by many other operations inside Apache. So, you can be
f072359f493a5209335799da85ac16d6a273303bgryzorsure the design and implementation is correct.
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteCond <EM>TestString</EM>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host, directory,
f072359f493a5209335799da85ac16d6a273303bgryzor .htaccess<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteCond</CODE> directive defines a rule condition. Precede a
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>RewriteRule</CODE> directive with one or more <CODE>RewriteCond</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzorThe following rewriting rule is only used if its pattern matches the current
f072359f493a5209335799da85ac16d6a273303bgryzorstate of the URI <STRONG>and</STRONG> if these additional conditions apply
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> is a string which can contains the following
f072359f493a5209335799da85ac16d6a273303bgryzorexpanded constructs in addition to plain text:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI><STRONG>RewriteRule backreferences</STRONG>: These are backreferences of
f072359f493a5209335799da85ac16d6a273303bgryzor(0 <= N <= 9) which provide access to the grouped parts (parenthesis!)
f072359f493a5209335799da85ac16d6a273303bgryzorof the pattern from the corresponding <CODE>RewriteRule</CODE> directive (the
f072359f493a5209335799da85ac16d6a273303bgryzorone following the current bunch of <CODE>RewriteCond</CODE> directives).
f072359f493a5209335799da85ac16d6a273303bgryzor<LI><STRONG>RewriteCond backreferences</STRONG>: These are backreferences of
f072359f493a5209335799da85ac16d6a273303bgryzor(1 <= N <= 9) which provide access to the grouped parts (parentheses!) of
f072359f493a5209335799da85ac16d6a273303bgryzorthe pattern from the last matched <CODE>RewriteCond</CODE> directive in the
f072359f493a5209335799da85ac16d6a273303bgryzorcurrent bunch of conditions.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI><STRONG>RewriteMap expansions</STRONG>: These are expansions of the form
f072359f493a5209335799da85ac16d6a273303bgryzorSee <A HREF="#mapfunc">the documentation for RewriteMap</A> for more details.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI><STRONG>Server-Variables</STRONG>: These are variables
f072359f493a5209335799da85ac16d6a273303bgryzor of the form
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>%{</CODE> <EM>NAME_OF_VARIABLE</EM> <CODE>}</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzortaken from the following list:
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_USER_AGENT<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_REFERER<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_COOKIE<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_FORWARDED<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_HOST<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_PROXY_CONNECTION<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorHTTP_ACCEPT<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREMOTE_ADDR<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREMOTE_HOST<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREMOTE_USER<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREMOTE_IDENT<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREQUEST_METHOD<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSCRIPT_FILENAME<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorPATH_INFO<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorQUERY_STRING<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorAUTH_TYPE<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorDOCUMENT_ROOT<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSERVER_ADMIN<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSERVER_NAME<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSERVER_ADDR<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSERVER_PORT<BR>
5479b5fa65d8ec88ea9c4389fd1b2c2728585571ndSERVER_PROTOCOL<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorSERVER_SOFTWARE<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_YEAR<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_MON<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_DAY<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_HOUR<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_MIN<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_SEC<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTIME_WDAY<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorAPI_VERSION<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTHE_REQUEST<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREQUEST_URI<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorREQUEST_FILENAME<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorIS_SUBREQ<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<p><STRONG>Notice:</STRONG> These variables all correspond to
f072359f493a5209335799da85ac16d6a273303bgryzorthe similarly named HTTP MIME-headers, C variables of the Apache
f072359f493a5209335799da85ac16d6a273303bgryzorserver or <CODE>struct tm</CODE> fields of the Unix system. Most
f072359f493a5209335799da85ac16d6a273303bgryzorare documented elsewhere in the Manual or in the CGI specification.
f072359f493a5209335799da85ac16d6a273303bgryzorThose that are special to mod_rewrite include:</p>
f072359f493a5209335799da85ac16d6a273303bgryzor<dd>Will contain the text "true" if the request currently
f072359f493a5209335799da85ac16d6a273303bgryzorbeing processed is a sub-request, "false" otherwise. Sub-requests may
f072359f493a5209335799da85ac16d6a273303bgryzorbe generated by modules that need to resolve additional files or URIs
f072359f493a5209335799da85ac16d6a273303bgryzorin order to complete their tasks.</dd>
f072359f493a5209335799da85ac16d6a273303bgryzor<dd>This is the version of the Apache module API (the internal
f072359f493a5209335799da85ac16d6a273303bgryzorinterface between server and module) in the current httpd build, as
f072359f493a5209335799da85ac16d6a273303bgryzordefined in include/ap_mmn.h. The module API version corresponds to the
f072359f493a5209335799da85ac16d6a273303bgryzorversion of Apache in use (in the release version of Apache 1.3.14, for
f072359f493a5209335799da85ac16d6a273303bgryzorinstance, it is 19990320:10), but is mainly of interest to module
f072359f493a5209335799da85ac16d6a273303bgryzorauthors.</dd>
f072359f493a5209335799da85ac16d6a273303bgryzor<dd>The full HTTP request line sent by the browser to the server
f072359f493a5209335799da85ac16d6a273303bgryzor(e.g., "<code>GET /index.html HTTP/1.1</code>"). This does not include
f072359f493a5209335799da85ac16d6a273303bgryzorany additional headers sent by the browser.</dd>
f072359f493a5209335799da85ac16d6a273303bgryzor<dd>The resource requested in the HTTP request line. (In the
f072359f493a5209335799da85ac16d6a273303bgryzor<dd>The full local filesystem path to the file or script
f072359f493a5209335799da85ac16d6a273303bgryzormatching the request.</dd>
f072359f493a5209335799da85ac16d6a273303bgryzorSpecial Notes:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>The variables SCRIPT_FILENAME and REQUEST_FILENAME contain the same
f072359f493a5209335799da85ac16d6a273303bgryzorvalue, <EM>i.e.</EM>, the value of the <CODE>filename</CODE> field of
f072359f493a5209335799da85ac16d6a273303bgryzorthe internal
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>request_rec</CODE> structure of the Apache server. The first name is
f072359f493a5209335799da85ac16d6a273303bgryzorcommonly known CGI variable name while the second is the consistent
f072359f493a5209335799da85ac16d6a273303bgryzorcounterpart to REQUEST_URI (which contains the value of the <CODE>uri</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>There is the special format: <CODE>%{ENV:variable}</CODE> where
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>variable</EM> can be any environment variable. This is looked-up via
f072359f493a5209335799da85ac16d6a273303bgryzorinternal Apache structures and (if not found there) via <CODE>getenv()</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzorfrom the Apache server process.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>There is the special format: <CODE>%{HTTP:header}</CODE> where
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>header</EM> can be any HTTP MIME-header name. This is looked-up
f072359f493a5209335799da85ac16d6a273303bgryzorfrom the HTTP request. Example: <CODE>%{HTTP:Proxy-Connection}</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzoris the value of the HTTP header ``<CODE>Proxy-Connection:</CODE>''.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>There is the special format <CODE>%{LA-U:variable}</CODE> for look-aheads
f072359f493a5209335799da85ac16d6a273303bgryzorwhich perform an internal (URL-based) sub-request to determine the final value
f072359f493a5209335799da85ac16d6a273303bgryzorof <EM>variable</EM>. Use this when you want to use a variable for rewriting
f072359f493a5209335799da85ac16d6a273303bgryzorwhich is actually set later in an API phase and thus is not available at the
f072359f493a5209335799da85ac16d6a273303bgryzorcurrent stage. For instance when you want to rewrite according to the
f072359f493a5209335799da85ac16d6a273303bgryzor<CODE>REMOTE_USER</CODE> variable from within the per-server context
f072359f493a5209335799da85ac16d6a273303bgryzor(<CODE>httpd.conf</CODE> file) you have to use <CODE>%{LA-U:REMOTE_USER}</CODE>
eef716e54c415709ca9d53aad4678bf9d96186e6ndbecause this variable is set by the authorization phases which come
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>after</EM> the URL translation phase where mod_rewrite operates. On the
f072359f493a5209335799da85ac16d6a273303bgryzorother hand, because mod_rewrite implements its per-directory context
eef716e54c415709ca9d53aad4678bf9d96186e6nd(<CODE>.htaccess</CODE> file) via the Fixup phase of the API and because the
f072359f493a5209335799da85ac16d6a273303bgryzorauthorization phases come <EM>before</EM> this phase, you just can use
eef716e54c415709ca9d53aad4678bf9d96186e6nd<LI>There is the special format: <CODE>%{LA-F:variable}</CODE> which performs an
f072359f493a5209335799da85ac16d6a273303bgryzorinternal (filename-based) sub-request to determine the final value of
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>variable</EM>. Most of the time this is the same as LA-U above.
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>CondPattern</EM> is the condition pattern, <EM>i.e.</EM>, a regular
eef716e54c415709ca9d53aad4678bf9d96186e6ndwhich is applied to the current instance of the <EM>TestString</EM>,
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>i.e.</EM>, <EM>TestString</EM> is evaluated and then matched against
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Remember:</STRONG> <EM>CondPattern</EM> is a standard
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Extended Regular Expression</EM> with some additions:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>You can prefix the pattern string with a '<CODE>!</CODE>' character
f072359f493a5209335799da85ac16d6a273303bgryzor(exclamation mark) to specify a <STRONG>non</STRONG>-matching pattern.
f072359f493a5209335799da85ac16d6a273303bgryzorThere are some special variants of <EM>CondPatterns</EM>. Instead of real
f072359f493a5209335799da85ac16d6a273303bgryzorregular expression strings you can also use one of the following:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CondPattern</STRONG>' (is lexically lower)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTreats the <EM>CondPattern</EM> as a plain string and compares it
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> is lexically lower than <EM>CondPattern</EM>.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>>CondPattern</STRONG>' (is lexically greater)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTreats the <EM>CondPattern</EM> as a plain string and compares it
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> is lexically greater than <EM>CondPattern</EM>.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>=CondPattern</STRONG>' (is lexically equal)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorTreats the <EM>CondPattern</EM> as a plain string and compares it
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> is lexically equal to <EM>CondPattern</EM>, i.e the
f072359f493a5209335799da85ac16d6a273303bgryzortwo strings are exactly equal (character by character).
f072359f493a5209335799da85ac16d6a273303bgryzorIf <EM>CondPattern</EM> is just <SAMP>""</SAMP> (two quotation marks) this
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>-d</STRONG>' (is <STRONG>d</STRONG>irectory)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzortests if it exists and is a directory.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>-f</STRONG>' (is regular <STRONG>f</STRONG>ile)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzortests if it exists and is a regular file.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>-s</STRONG>' (is regular file with <STRONG>s</STRONG>ize)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzortests if it exists and is a regular file with size greater than zero.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>-l</STRONG>' (is symbolic <STRONG>l</STRONG>ink)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzortests if it exists and is a symbolic link.
eef716e54c415709ca9d53aad4678bf9d96186e6nd<LI>'<STRONG>-F</STRONG>' (is existing file via subrequest)<BR>
eef716e54c415709ca9d53aad4678bf9d96186e6ndChecks if <EM>TestString</EM> is a valid file and accessible via all the
eef716e54c415709ca9d53aad4678bf9d96186e6ndserver's currently-configured access controls for that path. This uses an
f072359f493a5209335799da85ac16d6a273303bgryzorinternal subrequest to determine the check, so use it with care because it
f072359f493a5209335799da85ac16d6a273303bgryzordecreases your servers performance!
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG>-U</STRONG>' (is existing URL via subrequest)<BR>
eef716e54c415709ca9d53aad4678bf9d96186e6ndChecks if <EM>TestString</EM> is a valid URL and accessible via all the
f072359f493a5209335799da85ac16d6a273303bgryzorcurrently-configured access controls for that path. This uses an internal
f072359f493a5209335799da85ac16d6a273303bgryzorsubrequest to determine the check, so use it with care because it decreases
eef716e54c415709ca9d53aad4678bf9d96186e6ndyour server's performance!
eef716e54c415709ca9d53aad4678bf9d96186e6nd<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzorAll of these tests can also be prefixed by an exclamation mark ('!')
f072359f493a5209335799da85ac16d6a273303bgryzorto negate their meaning.
f072359f493a5209335799da85ac16d6a273303bgryzorAdditionally you can set special flags for <EM>CondPattern</EM> by appending
f072359f493a5209335799da85ac16d6a273303bgryzoras the third argument to the <CODE>RewriteCond</CODE> directive. <EM>Flags</EM>
f072359f493a5209335799da85ac16d6a273303bgryzoris a comma-separated list of the following flags:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>nocase|NC</CODE></STRONG>' (<STRONG>n</STRONG>o <STRONG>c</STRONG>ase)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This makes the test case-insensitive, <EM>i.e.</EM>, there is
f072359f493a5209335799da85ac16d6a273303bgryzor no difference between 'A-Z' and 'a-z' both in the expanded
f072359f493a5209335799da85ac16d6a273303bgryzor This flag is effective only for comparisons between
f072359f493a5209335799da85ac16d6a273303bgryzor <EM>TestString</EM> and <EM>CondPattern</EM>. It has no
f072359f493a5209335799da85ac16d6a273303bgryzor effect on filesystem and subrequest checks.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>ornext|OR</CODE></STRONG>' (<STRONG>or</STRONG> next condition)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor Use this to combine rule conditions with a local OR instead of the
f072359f493a5209335799da85ac16d6a273303bgryzor implicit AND. Typical example:
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteCond %{REMOTE_HOST} ^host1.* [OR]
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteCond %{REMOTE_HOST} ^host2.* [OR]
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteCond %{REMOTE_HOST} ^host3.*
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteRule ...some special stuff for any of these hosts...
f072359f493a5209335799da85ac16d6a273303bgryzor Without this flag you would have to write the cond/rule three times.
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorTo rewrite the Homepage of a site according to the ``<CODE>User-Agent:</CODE>''
f072359f493a5209335799da85ac16d6a273303bgryzorheader of the request, you can use the following:
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteRule ^/$ /homepage.max.html [L]
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteCond %{HTTP_USER_AGENT} ^Lynx.*
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteRule ^/$ /homepage.min.html [L]
f072359f493a5209335799da85ac16d6a273303bgryzorRewriteRule ^/$ /homepage.std.html [L]
f072359f493a5209335799da85ac16d6a273303bgryzorInterpretation: If you use Netscape Navigator as your browser (which identifies
f072359f493a5209335799da85ac16d6a273303bgryzoritself as 'Mozilla'), then you get the max homepage, which includes
f072359f493a5209335799da85ac16d6a273303bgryzorFrames, <EM>etc.</EM> If you use the Lynx browser (which is Terminal-based), then you
f072359f493a5209335799da85ac16d6a273303bgryzorget the min homepage, which contains no images, no tables, <EM>etc.</EM> If you
f072359f493a5209335799da85ac16d6a273303bgryzoruse any other browser you get the standard homepage.
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Syntax:</STRONG></A> RewriteRule <EM>Pattern</EM> <EM>Substitution</EM><BR>
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Context:</STRONG></A> server config, virtual host, directory, .htaccess<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Override"
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="directive-dict.html#Compatibility"
f072359f493a5209335799da85ac16d6a273303bgryzor><STRONG>Compatibility:</STRONG></A> Apache 1.2 (partially), Apache 1.3<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorThe <CODE>RewriteRule</CODE> directive is the real rewriting workhorse. The
f072359f493a5209335799da85ac16d6a273303bgryzordirective can occur more than once. Each directive then defines one single
f072359f493a5209335799da85ac16d6a273303bgryzorrewriting rule. The <STRONG>definition order</STRONG> of these rules is
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>important</STRONG>, because this order is used when applying the rules at
f072359f493a5209335799da85ac16d6a273303bgryzor<A NAME="patterns"><EM>Pattern</EM></A> can be (for Apache
f072359f493a5209335799da85ac16d6a273303bgryzor1.1.x a System V8 and for Apache 1.2.x and later a POSIX) <A
f072359f493a5209335799da85ac16d6a273303bgryzorNAME="regexp">regular expression</A> which gets applied to the current
f072359f493a5209335799da85ac16d6a273303bgryzorURL. Here ``current'' means the value of the URL when this rule gets
f072359f493a5209335799da85ac16d6a273303bgryzorapplied. This may not be the originally requested URL, because
f072359f493a5209335799da85ac16d6a273303bgryzorany number of rules may already have matched and made
f072359f493a5209335799da85ac16d6a273303bgryzoralterations to it.
f072359f493a5209335799da85ac16d6a273303bgryzorSome hints about the syntax of regular expressions:
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>[</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: One of chars
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>[^</CODE></STRONG>chars<STRONG><CODE>]</CODE></STRONG> Character class: None of chars
f072359f493a5209335799da85ac16d6a273303bgryzor text1<STRONG><CODE>|</CODE></STRONG>text2 Alternative: text1 or text2
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>?</CODE></STRONG> 0 or 1 of the preceding text
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>*</CODE></STRONG> 0 or N of the preceding text (N > 0)
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>+</CODE></STRONG> 1 or N of the preceding text (N > 1)
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>(</CODE></STRONG>text<STRONG><CODE>)</CODE></STRONG> Grouping of text
f072359f493a5209335799da85ac16d6a273303bgryzor (either to set the borders of an alternative or
f072359f493a5209335799da85ac16d6a273303bgryzor for making backreferences where the <STRONG>N</STRONG>th group can
f072359f493a5209335799da85ac16d6a273303bgryzor be used on the RHS of a RewriteRule with <CODE>$</CODE><STRONG>N</STRONG>)
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG><CODE>\</CODE></STRONG>char escape that particular char
f072359f493a5209335799da85ac16d6a273303bgryzor (for instance to specify the chars "<CODE>.[]()</CODE>" <EM>etc.</EM>)
f072359f493a5209335799da85ac16d6a273303bgryzorFor more information about regular expressions either have a look at your
f072359f493a5209335799da85ac16d6a273303bgryzorlocal regex(3) manpage or its <CODE>src/regex/regex.3</CODE> copy in the
f072359f493a5209335799da85ac16d6a273303bgryzorApache 1.3 distribution. If you are interested in more detailed
f072359f493a5209335799da85ac16d6a273303bgryzorinformation about regular expressions and their variants (POSIX regex, Perl
f072359f493a5209335799da85ac16d6a273303bgryzorregex, <EM>etc.</EM>) have a look at the following dedicated book on this topic:
f072359f493a5209335799da85ac16d6a273303bgryzor<BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorNutshell Handbook Series<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorO'Reilly & Associates, Inc. 1997<BR>
f072359f493a5209335799da85ac16d6a273303bgryzorISBN 1-56592-257-3<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor</BLOCKQUOTE>
f072359f493a5209335799da85ac16d6a273303bgryzorAdditionally in mod_rewrite the NOT character ('<CODE>!</CODE>') is a possible
f072359f493a5209335799da85ac16d6a273303bgryzorpattern prefix. This gives you the ability to negate a pattern; to say, for
f072359f493a5209335799da85ac16d6a273303bgryzorinstance: ``<EM>if the current URL does <STRONG>NOT</STRONG> match this
f072359f493a5209335799da85ac16d6a273303bgryzorpattern</EM>''. This can be used for exceptional cases, where it is easier to
f072359f493a5209335799da85ac16d6a273303bgryzormatch the negative pattern, or as a last default rule.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Notice:</STRONG> When using the NOT character to negate a pattern you cannot
f072359f493a5209335799da85ac16d6a273303bgryzorhave grouped wildcard parts in the pattern. This is impossible because when
f072359f493a5209335799da85ac16d6a273303bgryzorthe pattern does NOT match, there are no contents for the groups. In
f072359f493a5209335799da85ac16d6a273303bgryzorconsequence, if negated patterns are used, you cannot use <CODE>$N</CODE> in the
f072359f493a5209335799da85ac16d6a273303bgryzorsubstitution string!
f072359f493a5209335799da85ac16d6a273303bgryzor<A NAME="rhs"><EM>Substitution</EM></A> of a rewriting rule is the string
f072359f493a5209335799da85ac16d6a273303bgryzorwhich is substituted for (or replaces) the original URL for which
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Pattern</EM> matched. Beside plain text you can use
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>back-references <CODE>$N</CODE> to the RewriteRule pattern
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>back-references <CODE>%N</CODE> to the last matched RewriteCond pattern
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>server-variables as in rule condition test-strings (<CODE>%{VARNAME}</CODE>)
f072359f493a5209335799da85ac16d6a273303bgryzor<LI><A HREF="#mapfunc">mapping-function</A> calls (<CODE>${mapname:key|default}</CODE>)
f072359f493a5209335799da85ac16d6a273303bgryzorBack-references are <CODE>$</CODE><STRONG>N</STRONG> (<STRONG>N</STRONG>=0..9) identifiers which
f072359f493a5209335799da85ac16d6a273303bgryzorwill be replaced by the contents of the <STRONG>N</STRONG>th group of the matched
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Pattern</EM>. The server-variables are the same as for the
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>TestString</EM> of a <CODE>RewriteCond</CODE> directive. The
f072359f493a5209335799da85ac16d6a273303bgryzormapping-functions come from the <CODE>RewriteMap</CODE> directive and are
f072359f493a5209335799da85ac16d6a273303bgryzorexplained there. These three types of variables are expanded in the order of
f072359f493a5209335799da85ac16d6a273303bgryzorthe above list.
f072359f493a5209335799da85ac16d6a273303bgryzorAs already mentioned above, all the rewriting rules are applied to the
f072359f493a5209335799da85ac16d6a273303bgryzor<EM>Substitution</EM> (in the order of definition in the config file). The
f072359f493a5209335799da85ac16d6a273303bgryzorURL is <STRONG>completely replaced</STRONG> by the <EM>Substitution</EM> and the
f072359f493a5209335799da85ac16d6a273303bgryzorrewriting process goes on until there are no more rules unless explicitly
f072359f493a5209335799da85ac16d6a273303bgryzorterminated by a <CODE><STRONG>L</STRONG></CODE> flag - see below.
f072359f493a5209335799da85ac16d6a273303bgryzorThere is a special substitution string named '<CODE>-</CODE>' which means:
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>NO substitution</STRONG>! Sounds silly? No, it is useful to provide rewriting
f072359f493a5209335799da85ac16d6a273303bgryzorrules which <STRONG>only</STRONG> match some URLs but do no substitution, <EM>e.g.</EM>, in
f072359f493a5209335799da85ac16d6a273303bgryzorconjunction with the <STRONG>C</STRONG> (chain) flag to be able to have more than one
f072359f493a5209335799da85ac16d6a273303bgryzorpattern to be applied before a substitution occurs.
f072359f493a5209335799da85ac16d6a273303bgryzorOne more note: You can even create URLs in the substitution string containing
f072359f493a5209335799da85ac16d6a273303bgryzora query string part. Just use a question mark inside the substitution string
f072359f493a5209335799da85ac16d6a273303bgryzorto indicate that the following stuff should be re-injected into the
f072359f493a5209335799da85ac16d6a273303bgryzorQUERY_STRING. When you want to erase an existing query string, end the
f072359f493a5209335799da85ac16d6a273303bgryzorsubstitution string with just the question mark.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Note</STRONG>: There is a special feature: When you prefix a substitution
eef716e54c415709ca9d53aad4678bf9d96186e6ndfield with <CODE>http://</CODE><EM>thishost</EM>[<EM>:thisport</EM>] then
eef716e54c415709ca9d53aad4678bf9d96186e6nd<STRONG>mod_rewrite</STRONG> automatically strips it out. This auto-reduction on
f072359f493a5209335799da85ac16d6a273303bgryzorimplicit external redirect URLs is a useful and important feature when
f072359f493a5209335799da85ac16d6a273303bgryzorused in combination with a mapping-function which generates the hostname
f072359f493a5209335799da85ac16d6a273303bgryzorpart. Have a look at the first example in the example section below to
f072359f493a5209335799da85ac16d6a273303bgryzorunderstand this.
f072359f493a5209335799da85ac16d6a273303bgryzor<TABLE WIDTH="70%" BORDER=0 BGCOLOR="#E0E0F0" CELLSPACING=0 CELLPADDING=10>
f072359f493a5209335799da85ac16d6a273303bgryzor<STRONG>Remember:</STRONG> An unconditional external redirect to your own server will
f072359f493a5209335799da85ac16d6a273303bgryzornot work with the prefix <CODE>http://thishost</CODE> because of this feature.
f072359f493a5209335799da85ac16d6a273303bgryzorTo achieve such a self-redirect, you have to use the <STRONG>R</STRONG>-flag (see
f072359f493a5209335799da85ac16d6a273303bgryzorAdditionally you can set special flags for <EM>Substitution</EM> by appending
f072359f493a5209335799da85ac16d6a273303bgryzoras the third argument to the <CODE>RewriteRule</CODE> directive. <EM>Flags</EM> is a
f072359f493a5209335799da85ac16d6a273303bgryzorcomma-separated list of the following flags:
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>redirect|R</CODE> [=<EM>code</EM>]</STRONG>' (force <A NAME="redirect"><STRONG>r</STRONG>edirect</A>)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor with <CODE>http://thishost[:thisport]/</CODE> (which makes the new URL a URI) to
f072359f493a5209335799da85ac16d6a273303bgryzor force a external redirection. If no <EM>code</EM> is given a HTTP response
f072359f493a5209335799da85ac16d6a273303bgryzor of 302 (MOVED TEMPORARILY) is used. If you want to use other response
f072359f493a5209335799da85ac16d6a273303bgryzor codes in the range 300-400 just specify them as a number or use
f072359f493a5209335799da85ac16d6a273303bgryzor one of the following symbolic names: <CODE>temp</CODE> (default), <CODE>permanent</CODE>,
f072359f493a5209335799da85ac16d6a273303bgryzor Use it for rules which should
f072359f493a5209335799da85ac16d6a273303bgryzor canonicalize the URL and give it back to the client, <EM>e.g.</EM>, translate
f072359f493a5209335799da85ac16d6a273303bgryzor ``<CODE>/~</CODE>'' into ``<CODE>/u/</CODE>'' or always append a slash to
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG>Note:</STRONG> When you use this flag, make sure that the
f072359f493a5209335799da85ac16d6a273303bgryzor substitution field is a valid URL! If not, you are redirecting to an
f072359f493a5209335799da85ac16d6a273303bgryzor invalid location! And remember that this flag itself only prefixes the
f072359f493a5209335799da85ac16d6a273303bgryzor URL with <CODE>http://thishost[:thisport]/</CODE>, rewriting continues.
f072359f493a5209335799da85ac16d6a273303bgryzor Usually you also want to stop and do the redirection immediately. To stop
f072359f493a5209335799da85ac16d6a273303bgryzor the rewriting you also have to provide the 'L' flag.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>forbidden|F</CODE></STRONG>' (force URL to be <STRONG>f</STRONG>orbidden)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This forces the current URL to be forbidden, <EM>i.e.</EM>, it immediately sends
f072359f493a5209335799da85ac16d6a273303bgryzor back a HTTP response of 403 (FORBIDDEN). Use this flag in conjunction with
f072359f493a5209335799da85ac16d6a273303bgryzor appropriate RewriteConds to conditionally block some URLs.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>gone|G</CODE></STRONG>' (force URL to be <STRONG>g</STRONG>one)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This forces the current URL to be gone, <EM>i.e.</EM>, it immediately sends back a
f072359f493a5209335799da85ac16d6a273303bgryzor HTTP response of 410 (GONE). Use this flag to mark pages which no longer
f072359f493a5209335799da85ac16d6a273303bgryzor exist as gone.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>proxy|P</CODE></STRONG>' (force <STRONG>p</STRONG>roxy)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This flag forces the substitution part to be internally forced as a proxy
f072359f493a5209335799da85ac16d6a273303bgryzor request and immediately (<EM>i.e.</EM>, rewriting rule processing stops here) put
f072359f493a5209335799da85ac16d6a273303bgryzor through the <A HREF="mod_proxy.html">proxy module</A>. You have to make
f072359f493a5209335799da85ac16d6a273303bgryzor sure that the substitution string is a valid URI (<EM>e.g.</EM>, typically starting
f072359f493a5209335799da85ac16d6a273303bgryzor with <CODE>http://</CODE><EM>hostname</EM>) which can be handled by the
f072359f493a5209335799da85ac16d6a273303bgryzor Apache proxy module. If not you get an error from the proxy module. Use
f072359f493a5209335799da85ac16d6a273303bgryzor this flag to achieve a more powerful implementation of the <A
f072359f493a5209335799da85ac16d6a273303bgryzor HREF="mod_proxy.html#proxypass">ProxyPass</A> directive, to map some
f072359f493a5209335799da85ac16d6a273303bgryzor remote stuff into the namespace of the local server.
f072359f493a5209335799da85ac16d6a273303bgryzor Notice: To use this functionality make sure you have the proxy module
f072359f493a5209335799da85ac16d6a273303bgryzor compiled into your Apache server program. If you don't know please check
f072359f493a5209335799da85ac16d6a273303bgryzor whether <CODE>mod_proxy.c</CODE> is part of the ``<CODE>httpd -l</CODE>''
f072359f493a5209335799da85ac16d6a273303bgryzor output. If yes, this functionality is available to mod_rewrite. If not,
f072359f493a5209335799da85ac16d6a273303bgryzor then you first have to rebuild the ``<CODE>httpd</CODE>'' program with
f072359f493a5209335799da85ac16d6a273303bgryzor mod_proxy enabled.
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>last|L</CODE></STRONG>' (<STRONG>l</STRONG>ast rule)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor Stop the rewriting process here and
f072359f493a5209335799da85ac16d6a273303bgryzor don't apply any more rewriting rules. This corresponds to the Perl
f072359f493a5209335799da85ac16d6a273303bgryzor <CODE>last</CODE> command or the <CODE>break</CODE> command from the C
f072359f493a5209335799da85ac16d6a273303bgryzor language. Use this flag to prevent the currently rewritten URL from being
f072359f493a5209335799da85ac16d6a273303bgryzor rewritten further by following rules. For
f072359f493a5209335799da85ac16d6a273303bgryzor example, use it to rewrite the root-path URL ('<CODE>/</CODE>') to a real
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>next|N</CODE></STRONG>' (<STRONG>n</STRONG>ext round)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor Re-run the rewriting process (starting again with the first rewriting
f072359f493a5209335799da85ac16d6a273303bgryzor rule). Here the URL to match is again not the original URL but the URL
f072359f493a5209335799da85ac16d6a273303bgryzor from the last rewriting rule. This corresponds to the Perl
f072359f493a5209335799da85ac16d6a273303bgryzor <CODE>next</CODE> command or the <CODE>continue</CODE> command from the C
f072359f493a5209335799da85ac16d6a273303bgryzor language. Use this flag to restart the rewriting process, <EM>i.e.</EM>, to
f072359f493a5209335799da85ac16d6a273303bgryzor immediately go to the top of the loop. <BR>
f072359f493a5209335799da85ac16d6a273303bgryzor <STRONG>But be careful not to create an infinite loop!</STRONG>
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>chain|C</CODE></STRONG>' (<STRONG>c</STRONG>hained with next rule)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This flag chains the current rule with the next rule (which itself can
f072359f493a5209335799da85ac16d6a273303bgryzor be chained with the following rule, <EM>etc.</EM>). This has the following
f072359f493a5209335799da85ac16d6a273303bgryzor effect: if a rule matches, then processing continues as usual, <EM>i.e.</EM>, the
f072359f493a5209335799da85ac16d6a273303bgryzor flag has no effect. If the rule does <STRONG>not</STRONG> match, then all following
f072359f493a5209335799da85ac16d6a273303bgryzor chained rules are skipped. For instance, use it to remove the
f072359f493a5209335799da85ac16d6a273303bgryzor ``<CODE>.www</CODE>'' part inside a per-directory rule set when you let an
f072359f493a5209335799da85ac16d6a273303bgryzor external redirect happen (where the ``<CODE>.www</CODE>'' part should not to
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>type|T</CODE></STRONG>=<EM>MIME-type</EM>' (force MIME <STRONG>t</STRONG>ype)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor Force the MIME-type of the target file to be <EM>MIME-type</EM>. For
f072359f493a5209335799da85ac16d6a273303bgryzor instance, this can be used to simulate the <CODE>mod_alias</CODE>
f072359f493a5209335799da85ac16d6a273303bgryzor directive <CODE>ScriptAlias</CODE> which internally forces all files inside
f072359f493a5209335799da85ac16d6a273303bgryzor the mapped directory to have a MIME type of
f072359f493a5209335799da85ac16d6a273303bgryzor<LI>'<STRONG><CODE>nosubreq|NS</CODE></STRONG>' (used only if <STRONG>n</STRONG>o internal <STRONG>s</STRONG>ub-request)<BR>
f072359f493a5209335799da85ac16d6a273303bgryzor This flag forces the rewriting engine to skip a rewriting rule if the
f072359f493a5209335799da85ac16d6a273303bgryzor current request is an internal sub-request. For instance, sub-requests
f072359f493a5209335799da85ac16d6a273303bgryzor occur internally in Apache when <CODE>mod_include</CODE> tries to find out
f072359f493a5209335799da85ac16d6a273303bgryzor information about possible directory default files (<CODE>index.xxx</CODE>).
50039065d571fe01fd458a3f031c995a1fd53c22rbowen On sub-requests it is not always useful and even sometimes causes a failure to
f072359f493a5209335799da85ac16d6a273303bgryzor if the complete set of rules are applied. Use this flag to exclude some rules.<BR>
<LI>'<STRONG><CODE>noescape|NE</CODE></STRONG>' (<STRONG>n</STRONG>o URI <STRONG>e</STRONG>scaping of output)<BR>
<LI>'<STRONG><CODE>passthrough|PT</CODE></STRONG>' (<STRONG>p</STRONG>ass <STRONG>t</STRONG>hrough to next handler)<BR>
<LI>'<STRONG><CODE>env|E=</CODE></STRONG><EM>VAR</EM>:<EM>VAL</EM>' (set <STRONG>e</STRONG>nvironment variable)<BR>
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
(<EM>i.e.</EM>, file <CODE>.htaccess</CODE> in dir <CODE>/physical/path/to/somepath</CODE> containing
^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^localpath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
SCRIPT_URI=http://en1.engelschall.com/u/rse/
<!--#include virtual="footer.html" -->