mod_rewrite.html.en revision e884f58207082fa2136d5fc86635c31252338948
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<?xml version="1.0" encoding="ISO-8859-1"?>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher This file is generated from xml source: DO NOT EDIT
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<title>mod_rewrite - Apache HTTP Server</title>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<link href="/images/favicon.ico" rel="shortcut icon" /></head>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<p class="apache">Apache HTTP Server Version 2.1</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<img alt="" src="/images/feather.gif" /></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs-project/">Documentation</a> > <a href="../">Version 2.1</a> > <a href="./">Modules</a></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<div id="preamble"><h1>Apache Module mod_rewrite</h1>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>rewrite_module</td></tr>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_rewrite.c</td></tr>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 1.3 and later</td></tr></table>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>``The great thing about mod_rewrite is it gives you
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher all the configurability and flexibility of Sendmail.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher The downside to mod_rewrite is that it gives you all
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher the configurability and flexibility of Sendmail.''</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p class="cite">-- <cite>Brian Behlendorf</cite><br />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher Apache Group</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>`` Despite the tons of examples and docs,
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher mod_rewrite is voodoo. Damned cool voodoo, but still
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher voodoo. ''</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p class="cite">-- <cite>Brian Moore</cite><br />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher bem@news.cmc.net</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>Welcome to mod_rewrite, the Swiss Army Knife of URL
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher manipulation!</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>This module uses a rule-based rewriting engine (based on a
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher regular-expression parser) to rewrite requested URLs on the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher fly. It supports an unlimited number of rules and an
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher unlimited number of attached rule conditions for each rule to
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher provide a really flexible and powerful URL manipulation
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher mechanism. The URL manipulations can depend on various tests,
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher for instance server variables, environment variables, HTTP
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher headers, time stamps and even external database lookups in
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher various formats can be used to achieve a really granular URL
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher <p>This module operates on the full URLs (including the
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher path-info part) both in per-server context
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher (<code>httpd.conf</code>) and per-directory context
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher (<code>.htaccess</code>) and can even generate query-string
c7a4383b3b5549d0627c21bb02bd5f0bd46a3531Jakub Hrozek parts on result. The rewritten result can lead to internal
c7a4383b3b5549d0627c21bb02bd5f0bd46a3531Jakub Hrozek sub-processing, external request redirection or even to an
c7a4383b3b5549d0627c21bb02bd5f0bd46a3531Jakub Hrozek internal proxy throughput.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>But all this functionality and flexibility has its
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher drawback: complexity. So don't expect to understand this
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher entire module in just one day.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>This module was invented and originally written in April
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher 1996 and gifted exclusively to the The Apache Group in July 1997
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <a href="http://www.engelschall.com/"><code>Ralf S.
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <a href="mailto:rse@engelschall.com"><code>rse@engelschall.com</code></a><br />
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <a href="http://www.engelschall.com/"><code>www.engelschall.com</code></a>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<div id="quickview"><h3 class="directives">Directives</h3>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewritelock">RewriteLock</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewritelog">RewriteLog</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#rewriteloglevel">RewriteLogLevel</a></li>
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose<li><img alt="" src="/images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose<li><img alt="" src="/images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
4cdaf239d4504966bed8ecd5e3fa07def74c7302Sumit Bose<li><img alt="" src="/images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#Internal">Internal Processing</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<li><img alt="" src="/images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
294e9a5521d327c5cdc49beeb9cb9e703b3134f1Jan Zeleny<li><img alt="" src="/images/down.gif" /> <a href="#Solutions">Practical Solutions</a></li>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<h2><a name="Internal" id="Internal">Internal Processing</a></h2>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>The internal processing of this module is very complex but
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher needs to be explained once even to the average user to avoid
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher common mistakes and to let you exploit its full
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher functionality.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<h3><a name="InternalAPI" id="InternalAPI">API Phases</a></h3>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>First you have to understand that when Apache processes a
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher HTTP request it does this in phases. A hook for each of these
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher phases is provided by the Apache API. Mod_rewrite uses two of
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher these hooks: the URL-to-filename translation hook which is
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher used after the HTTP request has been read but before any
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher authorization starts and the Fixup hook which is triggered
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher after the authorization phases and after the per-directory
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher config files (<code>.htaccess</code>) have been read, but
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher before the content handler is activated.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>So, after a request comes in and Apache has determined the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher corresponding server (or virtual server) the rewriting engine
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher starts processing of all mod_rewrite directives from the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher per-server configuration in the URL-to-filename phase. A few
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher steps later when the final data directories are found, the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher per-directory configuration directives of mod_rewrite are
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher triggered in the Fixup phase. In both situations mod_rewrite
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher rewrites URLs either to new URLs or to filenames, although
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher there is no obvious distinction between them. This is a usage
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina of the API which was not intended to be this way when the API
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina was designed, but as of Apache 1.x this is the only way
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina mod_rewrite can operate. To make this point more clear
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina remember the following two points:</p>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina <li>Although mod_rewrite rewrites URLs to URLs, URLs to
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina filenames and even filenames to filenames, the API
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina currently provides only a URL-to-filename hook. In Apache
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina 2.0 the two missing hooks will be added to make the
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina processing more clear. But this point has no drawbacks for
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina the user, it is just a fact which should be remembered:
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina Apache does more in the URL-to-filename hook than the API
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina intends for it.</li>
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina Unbelievably mod_rewrite provides URL manipulations in
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina <code>.htaccess</code> files, although these are reached
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina a very long time after the URLs have been translated to
a679f0167b646cffdae86546ed77e105576991b0Pavel Březina filenames. It has to be this way because
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <code>.htaccess</code> files live in the filesystem, so
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek processing has already reached this stage. In other
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek words: According to the API phases at this time it is too
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek late for any URL manipulations. To overcome this chicken
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek and egg problem mod_rewrite uses a trick: When you
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek manipulate a URL/filename in per-directory context
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek mod_rewrite first rewrites the filename back to its
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek corresponding URL (which is usually impossible, but see
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek the <code>RewriteBase</code> directive below for the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek trick to achieve this) and then initiates a new internal
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek sub-request with the new URL. This restarts processing of
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek the API phases.
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>Again mod_rewrite tries hard to make this complicated
ad1be6fd04234f61f108773ff39aa7485abda47cJakub Hrozek step totally transparent to the user, but you should
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek remember here: While URL manipulations in per-server
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek context are really fast and efficient, per-directory
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek rewrites are slow and inefficient due to this chicken and
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek egg problem. But on the other hand this is the only way
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek mod_rewrite can provide (locally restricted) URL
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek manipulations to the average user.</p>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek<h3><a name="InternalRuleset" id="InternalRuleset">Ruleset Processing</a></h3>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>Now when mod_rewrite is triggered in these two API phases, it
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek reads the configured rulesets from its configuration
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek structure (which itself was either created on startup for
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek per-server context or during the directory walk of the Apache
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek kernel for per-directory context). Then the URL rewriting
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek engine is started with the contained ruleset (one or more
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek rules together with their conditions). The operation of the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek URL rewriting engine itself is exactly the same for both
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek configuration contexts. Only the final result processing is
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek different. </p>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>The order of rules in the ruleset is important because the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek rewriting engine processes them in a special (and not very
65e454c64dbeb4b74e0cc4ad952a54861dc0c3e4Jakub Hrozek obvious) order. The rule is this: The rewriting engine loops
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek through the ruleset rule by rule (<code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives) and
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek when a particular rule matches it optionally loops through
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek existing corresponding conditions (<code>RewriteCond</code>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek directives). For historical reasons the conditions are given
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek first, and so the control flow is a little bit long-winded. See
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek Figure 1 for more details.</p>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <img src="/images/mod_rewrite_fig1.gif" width="428" height="385" alt="[Needs graphics capability to display]" /><br />
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <dfn>Figure 1:</dfn>The control flow through the rewriting ruleset
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>As you can see, first the URL is matched against the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>Pattern</em> of each rule. When it fails mod_rewrite
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek immediately stops processing this rule and continues with the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek next rule. If the <em>Pattern</em> matches, mod_rewrite looks
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek for corresponding rule conditions. If none are present, it
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek just substitutes the URL with a new value which is
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek constructed from the string <em>Substitution</em> and goes on
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek with its rule-looping. But if conditions exist, it starts an
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek inner loop for processing them in the order that they are
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek listed. For conditions the logic is different: we don't match
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek a pattern against the current URL. Instead we first create a
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek string <em>TestString</em> by expanding variables,
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek back-references, map lookups, <em>etc.</em> and then we try
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek to match <em>CondPattern</em> against it. If the pattern
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek doesn't match, the complete set of conditions and the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek corresponding rule fails. If the pattern matches, then the
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek next condition is processed until no more conditions are
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek available. If all conditions match, processing is continued
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek with the substitution of the URL with
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek<h3><a name="quoting" id="quoting">Quoting Special Characters</a></h3>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <p>As of Apache 1.3.20, special characters in
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek <em>TestString</em> and <em>Substitution</em> strings can be
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek escaped (that is, treated as normal characters without their
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek usual special meaning) by prefixing them with a slosh ('\')
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek character. In other words, you can include an actual
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek dollar-sign character in a <em>Substitution</em> string by
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek using '<code>\$</code>'; this keeps mod_rewrite from trying
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek to treat it as a backreference.</p>
74e95cfd9d3939dfe9417d79d2f6fc79b361405fJakub Hrozek<h3><a name="InternalBackRefs" id="InternalBackRefs">Regex Back-Reference Availability</a></h3>
591b0325f5d6f70ae71e61a8c563b437acfb1884Jakub Hrozek <p>One important thing here has to be remembered: Whenever you
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose use parentheses in <em>Pattern</em> or in one of the
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose <em>CondPattern</em>, back-references are internally created
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose which can be used with the strings <code>$N</code> and
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose <code>%N</code> (see below). These are available for creating
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose the strings <em>Substitution</em> and <em>TestString</em>.
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose Figure 2 shows to which locations the back-references are
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose transfered for expansion.</p>
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose <img src="/images/mod_rewrite_fig2.gif" width="381" height="179" alt="[Needs graphics capability to display]" /><br />
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose <dfn>Figure 2:</dfn> The back-reference flow through a rule.
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose <p>We know this was a crash course on mod_rewrite's internal
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose processing. But you will benefit from this knowledge when
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose reading the following documentation of the available
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose directives.</p>
edaa983d094c239c3e1ba667bcd20ed3934be3b8Sumit Bose</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>This module keeps track of two additional (non-standard)
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher CGI/SSI environment variables named <code>SCRIPT_URL</code>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher and <code>SCRIPT_URI</code>. These contain the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <em>logical</em> Web-view to the current resource, while the
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher standard CGI/SSI variables <code>SCRIPT_NAME</code> and
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
5f879ab8b6c1cefbc63e1c2303f79b09b6246ca3Stephen Gallagher System-view. </p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>Notice: These variables hold the URI/URL <em>as they were
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher initially requested</em>, <em>i.e.</em>, <em>before</em> any
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher rewriting. This is important because the rewriting process is
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher primarily used to rewrite logical URLs to physical
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher pathnames.</p>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherSCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen GallagherSCRIPT_URI=http://en1.engelschall.com/u/rse/
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<h2><a name="Solutions" id="Solutions">Practical Solutions</a></h2>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>We also have an <a href="/misc/rewriteguide.html">URL
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek Rewriting Guide</a> available, which provides a collection of
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek practical solutions for URL-based problems. There you can
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek find real-life rulesets and additional information about
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek mod_rewrite.</p>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>See usage for information.</code></td></tr>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
d231e95b0a5e1bd377f67e041e8b502a79fdc605Jakub Hrozek<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <p>The <code class="directive">RewriteBase</code> directive explicitly
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher sets the base URL for per-directory rewrites. As you will see
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher below, <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher can be used in per-directory config files
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher (<code>.htaccess</code>). There it will act locally,
03532fb1cbb7e8c1d5cf2e93aa3719f926631cabStephen Gallagher <em>i.e.</em>, the local directory prefix is stripped at this
path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
files where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.
RewriteRule ^oldstuff\.html$ newstuff.html
<div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
rule condition. Precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directive with one
RewriteRule ...some special stuff for any of these hosts...
RewriteRule ^/$ /homepage.max.html [L]
RewriteRule ^/$ /homepage.min.html [L]
RewriteRule ^/$ /homepage.std.html [L]
<div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
<div class="directive-section"><h2><a name="RewriteLock" id="RewriteLock">RewriteLock</a> <a name="rewritelock" id="rewritelock">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the lock file used for RewriteMap
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLock <em>file-path</em></code></td></tr>
lockfile which mod_rewrite needs to communicate with <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
<div class="directive-section"><h2><a name="RewriteLog" id="RewriteLog">RewriteLog</a> <a name="rewritelog" id="rewritelog">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the file used for logging rewrite engine
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLog <em>file-path</em></code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<div class="directive-section"><h2><a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel" id="rewriteloglevel">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the verbosity of the log file used by the rewrite
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLogLevel <em>Level</em></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteLogLevel 0</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
## map.txt -- rewriting map
Ralf.S.Engelschall rse # Bastard Operator From Hell
Mr.Joe.Average joe # Mr. Average
## map.txt -- rewriting map
# ...put here any transformations or lookups...
<div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteOptions MaxRedirects=10</code></td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is available in Apache 2.0.45 and
issued by per-directory <code class="directive"><a href="#rewriterule">RewriteRule</a></code>s, <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> aborts
<div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The cookie-flag is available in Apache 2.0.40 and later.</td></tr>
perl regular expression manpage ("<a href="http://www.perldoc.com/perl5.6.1/pod/perlre.html">perldoc
[=<em>code</em>]</strong>' (force <a id="redirect" name="redirect"><strong>r</strong>edirect</a>)<br />
rewriting rule processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You have to make
'<strong><code>cookie|CO=</code></strong><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>]]'
^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
^/somepath(.*) http://thishost/otherpath$1 [P] not supported, because silly!
^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!
<p class="apache">Maintained by the <a href="http://httpd.apache.org/docs-project/">Apache HTTP Server Documentation Project</a></p>
<p class="menu"><a href="/mod/">Modules</a> | <a href="/mod/directives.html">Directives</a> | <a href="/faq/">FAQ</a> | <a href="/glossary.html">Glossary</a> | <a href="/sitemap.html">Sitemap</a></p></div>