mod_rewrite.html.en revision f2f7bfe0e3e57940b386bdbcb266eea78a86aa24
97a9a944b5887e91042b019776c41d5dd74557aferikabele<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
97a9a944b5887e91042b019776c41d5dd74557aferikabele<html xmlns="http://www.w3.org/1999/xhtml" lang="en" xml:lang="en"><head><!--
b1ced323143ade589985456a78f3f64d6a6580c5yoshiki XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
b1ced323143ade589985456a78f3f64d6a6580c5yoshiki This file is generated from xml source: DO NOT EDIT
b1ced323143ade589985456a78f3f64d6a6580c5yoshiki XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<link href="/style/css/manual.css" rel="stylesheet" media="all" type="text/css" title="Main stylesheet" />
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<link href="/style/css/manual-loose-100pc.css" rel="alternate stylesheet" media="all" type="text/css" title="No Sidebar - Default font size" />
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<link href="/style/css/manual-print.css" rel="stylesheet" media="print" type="text/css" />
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<link href="/images/favicon.ico" rel="shortcut icon" /></head>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<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>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<div class="up"><a href="./"><img title="<-" alt="<-" src="/images/left.gif" /></a></div>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<a href="http://www.apache.org/">Apache</a> > <a href="http://httpd.apache.org/">HTTP Server</a> > <a href="http://httpd.apache.org/docs/">Documentation</a> > <a href="../">Version 2.3</a> > <a href="./">Modules</a></div>
ad74a0524a06bfe11b7de9e3b4ce7233ab3bd3f7nd<p><span>Available Languages: </span><a href="/en/mod/mod_rewrite.html" title="English"> en </a></p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<table class="module"><tr><th><a href="module-dict.html#Description">Description:</a></th><td>Provides a rule-based rewriting engine to rewrite requested
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="module-dict.html#Status">Status:</a></th><td>Extension</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="module-dict.html#ModuleIdentifier">Module�Identifier:</a></th><td>rewrite_module</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="module-dict.html#SourceFile">Source�File:</a></th><td>mod_rewrite.c</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="module-dict.html#Compatibility">Compatibility:</a></th><td>Available in Apache 1.3 and later</td></tr></table>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This module uses a rule-based rewriting engine (based on a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive regular-expression parser) to rewrite requested URLs on the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive fly. It supports an unlimited number of rules and an
06ba4a61654b3763ad65f52283832ebf058fdf1cslive unlimited number of attached rule conditions for each rule, to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive provide a really flexible and powerful URL manipulation
06ba4a61654b3763ad65f52283832ebf058fdf1cslive mechanism. The URL manipulations can depend on various tests,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive of server variables, environment variables, HTTP
06ba4a61654b3763ad65f52283832ebf058fdf1cslive headers, or time stamps. Even external database lookups in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive various formats can be used to achieve highly granular URL
06ba4a61654b3763ad65f52283832ebf058fdf1cslive matching.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This module operates on the full URLs (including the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path-info part) both in per-server context
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (<code>.htaccess</code>) and can generate query-string
06ba4a61654b3763ad65f52283832ebf058fdf1cslive parts on result. The rewritten result can lead to internal
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sub-processing, external request redirection or even to an
06ba4a61654b3763ad65f52283832ebf058fdf1cslive internal proxy throughput.</p>
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen <p>Further details, discussion, and examples, are provided in the
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen <a href="/rewrite/">detailed mod_rewrite documentation</a>.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<div id="quickview"><h3 class="directives">Directives</h3>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<li><img alt="" src="/images/down.gif" /> <a href="#rewritebase">RewriteBase</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewritecond">RewriteCond</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewriteengine">RewriteEngine</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewritelock">RewriteLock</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewritelog">RewriteLog</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewriteloglevel">RewriteLogLevel</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewritemap">RewriteMap</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewriteoptions">RewriteOptions</a></li>
117c1f888a14e73cdd821dc6c23eb0411144a41cnd<li><img alt="" src="/images/down.gif" /> <a href="#rewriterule">RewriteRule</a></li>
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen<li><img alt="" src="/images/down.gif" /> <a href="#quoting">Quoting Special Characters</a></li>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<li><img alt="" src="/images/down.gif" /> <a href="#EnvVar">Environment Variables</a></li>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<li><img alt="" src="/images/down.gif" /> <a href="#vhosts">Rewriting in Virtual Hosts</a></li>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<li><img alt="" src="/images/down.gif" /> <a href="#Solutions">Practical Solutions</a></li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<h2><a name="quoting" id="quoting">Quoting Special Characters</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>As of Apache 1.3.20, special characters in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>TestString</em> and <em>Substitution</em> strings can be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive escaped (that is, treated as normal characters without their
06ba4a61654b3763ad65f52283832ebf058fdf1cslive usual special meaning) by prefixing them with a slash ('\')
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen character. In other words, you can include an actual
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen dollar-sign character in a <em>Substitution</em> string by
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd using '<code>\$</code>'; this keeps mod_rewrite from trying
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to treat it as a backreference.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<h2><a name="EnvVar" id="EnvVar">Environment Variables</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This module keeps track of two additional (non-standard)
06ba4a61654b3763ad65f52283832ebf058fdf1cslive CGI/SSI environment variables named <code>SCRIPT_URL</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>logical</em> Web-view to the current resource, while the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive standard CGI/SSI variables <code>SCRIPT_NAME</code> and
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>SCRIPT_FILENAME</code> contain the <em>physical</em>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive System-view. </p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Notice: These variables hold the URI/URL <em>as they were
06ba4a61654b3763ad65f52283832ebf058fdf1cslive initially requested</em>, that is, <em>before</em> any
97a9a944b5887e91042b019776c41d5dd74557aferikabele rewriting. This is important to note because the rewriting process is
06ba4a61654b3763ad65f52283832ebf058fdf1cslive primarily used to rewrite logical URLs to physical
06ba4a61654b3763ad65f52283832ebf058fdf1cslive pathnames.</p>
97a9a944b5887e91042b019776c41d5dd74557aferikabeleSCRIPT_NAME=/sw/lib/w3s/tree/global/u/rse/.www/index.html
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen<h2><a name="vhosts" id="vhosts">Rewriting in Virtual Hosts</a></h2>
f0a393c5c2d7de58f447855369ad2fbfa254e544rbowen <p>By default, <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> configuration
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd settings from the main server context are not inherited by
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd virtual hosts. To make the main server settings apply to virtual
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd hosts, you must place the following directives in each <code class="directive"><a href="/mod/core.html#virtualhost"><VirtualHost></a></code> section:</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd RewriteEngine On<br />
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd RewriteOptions Inherit
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd</div><div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<h2><a name="Solutions" id="Solutions">Practical Solutions</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>For numerous examples of common, and not-so-common, uses for
06ba4a61654b3763ad65f52283832ebf058fdf1cslive mod_rewrite, see the <a href="/rewrite/rewrite_guide.html">Rewrite
97a9a944b5887e91042b019776c41d5dd74557aferikabele Guide</a>, and the <a href="/rewrite/rewrite_guide_advanced.html">Advanced Rewrite
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="directive-section"><h2><a name="RewriteBase" id="RewriteBase">RewriteBase</a> <a name="rewritebase" id="rewritebase">Directive</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the base URL for per-directory rewrites</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteBase <em>URL-path</em></code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>See usage for information.</code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>directory, .htaccess</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <code class="directive">RewriteBase</code> directive explicitly
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sets the base URL for per-directory rewrites. As you will see
06ba4a61654b3763ad65f52283832ebf058fdf1cslive below, <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
97a9a944b5887e91042b019776c41d5dd74557aferikabele can be used in per-directory config files
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (<code>.htaccess</code>). In such a case, it will act locally,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive stripping the local directory prefix before processing, and applying
97a9a944b5887e91042b019776c41d5dd74557aferikabele rewrite rules only to the remainder. When processing is complete, the
97a9a944b5887e91042b019776c41d5dd74557aferikabele prefix is automatically added back to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path. The default setting is; <code class="directive">RewriteBase</code> <em>physical-directory-path</em></p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>When a substitution occurs for a new URL, this module has
97a9a944b5887e91042b019776c41d5dd74557aferikabele to re-inject the URL into the server processing. To be able
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to do this it needs to know what the corresponding URL-prefix
06ba4a61654b3763ad65f52283832ebf058fdf1cslive or URL-base is. By default this prefix is the corresponding
06ba4a61654b3763ad65f52283832ebf058fdf1cslive filepath itself. <strong>However, for most websites, URLs are NOT
06ba4a61654b3763ad65f52283832ebf058fdf1cslive directly related to physical filename paths, so this
06ba4a61654b3763ad65f52283832ebf058fdf1cslive assumption will often be wrong!</strong> Therefore, you can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive use the <code>RewriteBase</code> directive to specify the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive correct URL-prefix.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="note"> If your webserver's URLs are <strong>not</strong> directly
06ba4a61654b3763ad65f52283832ebf058fdf1csliverelated to physical file paths, you will need to use
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<code class="directive">RewriteBase</code> in every <code>.htaccess</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslivefile where you want to use <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives.
97a9a944b5887e91042b019776c41d5dd74557aferikabele <p> For example, assume the following per-directory config file:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive# /abc/def/.htaccess -- per-dir config file for directory /abc/def
06ba4a61654b3763ad65f52283832ebf058fdf1cslive# Remember: /abc/def is the physical path of /xyz, <em>i.e.</em>, the server
97a9a944b5887e91042b019776c41d5dd74557aferikabele# has a 'Alias /xyz /abc/def' directive <em>e.g.</em>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteEngine On
06ba4a61654b3763ad65f52283832ebf058fdf1cslive# let the server know that we were reached via /xyz and not
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteBase /xyz
06ba4a61654b3763ad65f52283832ebf058fdf1cslive# now the rewriting rules
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteRule ^oldstuff\.html$ newstuff.html
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>In the above example, a request to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>/xyz/oldstuff.html</code> gets correctly rewritten to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the physical file <code>/abc/def/newstuff.html</code>.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>The following list gives detailed information about
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the internal processing steps:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveInternal Processing:
06ba4a61654b3763ad65f52283832ebf058fdf1cslive /xyz/oldstuff.html -> /abc/def/oldstuff.html (per-server Alias)
06ba4a61654b3763ad65f52283832ebf058fdf1cslive /abc/def/oldstuff.html -> /abc/def/newstuff.html (per-dir RewriteRule)
97a9a944b5887e91042b019776c41d5dd74557aferikabele /abc/def/newstuff.html -> /xyz/newstuff.html (per-dir RewriteBase)
97a9a944b5887e91042b019776c41d5dd74557aferikabele /xyz/newstuff.html -> /abc/def/newstuff.html (per-server Alias)
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>This seems very complicated, but is in fact
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd correct Apache internal processing. Because the
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd per-directory rewriting comes late in the
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd process, the rewritten request
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd has to be re-injected into the Apache kernel, as if it
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd were a new request. (See <a href="/rewrite/rewrite_tech.html">mod_rewrite technical
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd details</a>.)
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd This is not the serious overhead it may seem to be -
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd this re-injection is completely internal to the
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd Apache server (and the same procedure is used by
06ba4a61654b3763ad65f52283832ebf058fdf1cslive many other operations within Apache).</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="directive-section"><h2><a name="RewriteCond" id="RewriteCond">RewriteCond</a> <a name="rewritecond" id="rewritecond">Directive</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a condition under which rewriting will take place
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code> RewriteCond
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>TestString</em> <em>CondPattern</em></code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
97a9a944b5887e91042b019776c41d5dd74557aferikabele <p>The <code class="directive">RewriteCond</code> directive defines a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive rule condition. One or more <code class="directive">RewriteCond</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive can precede a <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive directive. The following rule is then only used if both
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the current state of the URI matches its pattern, <strong>and</strong> if these conditions are met.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p><em>TestString</em> is a string which can contain the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive following expanded constructs in addition to plain text:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <strong>RewriteRule backreferences</strong>: These are
97a9a944b5887e91042b019776c41d5dd74557aferikabele backreferences of the form <strong><code>$N</code></strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (0 <= N <= 9), which provide access to the grouped
97a9a944b5887e91042b019776c41d5dd74557aferikabele parts (in parentheses) of the pattern, from the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>RewriteRule</code> which is subject to the current
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <strong>RewriteCond backreferences</strong>: These are
06ba4a61654b3763ad65f52283832ebf058fdf1cslive backreferences of the form <strong><code>%N</code></strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (1 <= N <= 9), which provide access to the grouped
06ba4a61654b3763ad65f52283832ebf058fdf1cslive parts (again, in parentheses) of the pattern, from the last matched
06ba4a61654b3763ad65f52283832ebf058fdf1cslive of conditions.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive expansions of the form <strong><code>${mapname:key|default}</code></strong>.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive RewriteMap</a> for more details.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <strong>Server-Variables</strong>: These are variables of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive from the following list:
97a9a944b5887e91042b019776c41d5dd74557aferikabele <th>HTTP headers:</th> <th>connection & request:</th> <th />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_USER_AGENT<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_REFERER<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_COOKIE<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_FORWARDED<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_HOST<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_PROXY_CONNECTION<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele HTTP_ACCEPT<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive REMOTE_ADDR<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive REMOTE_HOST<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive REMOTE_PORT<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele REMOTE_USER<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele REMOTE_IDENT<br />
74a6de79356cd15d2e47065087785e36dd65aa41nd REQUEST_METHOD<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SCRIPT_FILENAME<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele PATH_INFO<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele QUERY_STRING<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele AUTH_TYPE<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <th>server internals:</th> <th>date and time:</th> <th>specials:</th>
97a9a944b5887e91042b019776c41d5dd74557aferikabele DOCUMENT_ROOT<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_ADMIN<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_NAME<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_ADDR<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_PORT<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_PROTOCOL<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele SERVER_SOFTWARE<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive TIME_YEAR<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive TIME_MON<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive TIME_DAY<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele TIME_HOUR<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele TIME_MIN<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele TIME_SEC<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele TIME_WDAY<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive API_VERSION<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive THE_REQUEST<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive REQUEST_URI<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele REQUEST_FILENAME<br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele IS_SUBREQ<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>These variables all
06ba4a61654b3763ad65f52283832ebf058fdf1cslive correspond to the similarly named HTTP
06ba4a61654b3763ad65f52283832ebf058fdf1cslive MIME-headers, C variables of the Apache server or
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Most are documented elsewhere in the Manual or in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the CGI specification. Those that are special to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive mod_rewrite include those below.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>Will contain the text "true" if the request
06ba4a61654b3763ad65f52283832ebf058fdf1cslive currently being processed is a sub-request,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive "false" otherwise. Sub-requests may be generated
06ba4a61654b3763ad65f52283832ebf058fdf1cslive by modules that need to resolve additional files
06ba4a61654b3763ad65f52283832ebf058fdf1cslive or URIs in order to complete their tasks.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>This is the version of the Apache module API
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (the internal interface between server and
06ba4a61654b3763ad65f52283832ebf058fdf1cslive module) in the current httpd build, as defined in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive corresponds to the version of Apache in use (in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the release version of Apache 1.3.14, for
06ba4a61654b3763ad65f52283832ebf058fdf1cslive instance, it is 19990320:10), but is mainly of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive interest to module authors.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>The full HTTP request line sent by the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive include any additional headers sent by the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive browser.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>The resource requested in the HTTP request
06ba4a61654b3763ad65f52283832ebf058fdf1cslive line. (In the example above, this would be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>The full local filesystem path to the file or
06ba4a61654b3763ad65f52283832ebf058fdf1cslive script matching the request.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>Will contain the text "on" if the connection is
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd can be safely used regardless of whether or not
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is loaded).</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>The variables SCRIPT_FILENAME and REQUEST_FILENAME
06ba4a61654b3763ad65f52283832ebf058fdf1cslive contain the same value - the value of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>request_rec</code> structure of the Apache server.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive The first name is the commonly known CGI variable name
06ba4a61654b3763ad65f52283832ebf058fdf1cslive while the second is the appropriate counterpart of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive REQUEST_URI (which contains the value of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>uri</code> field of <code>request_rec</code>).</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{ENV:variable}</code>, where <em>variable</em> can be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive any environment variable, is also available.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This is looked-up via internal
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Apache structures and (if not found there) via
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>getenv()</code> from the Apache server process.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{SSL:variable}</code>, where <em>variable</em> is the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive name of an <a href="mod_ssl.html#envvars">SSL environment
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd variable</a>, can be used whether or not
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd <code class="module"><a href="/mod/mod_ssl.html">mod_ssl</a></code> is loaded, but will always expand to
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd the empty string if it is not. Example:
eaaa852423e42d6d86bcada80ed781a205fc3e5fnd <code>%{HTTP:header}</code>, where <em>header</em> can be
fb82af0f0cd7b58eef19c54b086131b7e1e1e749madhum any HTTP MIME-header name, can always be used to obtain the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive value of a header sent in the HTTP request.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the value of the HTTP header
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>If a HTTP header is used in a condition this header is added to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the Vary header of the response in case the condition evaluates to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to true for the request. It is <strong>not</strong> added if the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive condition evaluates to false for the request. Adding the HTTP header
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to the Vary header of the response is needed for proper caching.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>It has to be kept in mind that conditions follow a short circuit
06ba4a61654b3763ad65f52283832ebf058fdf1cslive logic in the case of the '<strong><code>ornext|OR</code></strong>' flag
06ba4a61654b3763ad65f52283832ebf058fdf1cslive so that certain conditions might not be evaluated at all.</p></li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{LA-U:variable}</code> can be used for look-aheads which perform
06ba4a61654b3763ad65f52283832ebf058fdf1cslive an internal (URL-based) sub-request to determine the final
06ba4a61654b3763ad65f52283832ebf058fdf1cslive value of <em>variable</em>. This can be used to access
06ba4a61654b3763ad65f52283832ebf058fdf1cslive variable for rewriting which is not available at the current
06ba4a61654b3763ad65f52283832ebf058fdf1cslive stage, but will be set in a later phase.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>For instance, to rewrite according to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive per-server context (<code>httpd.conf</code> file) you must
06ba4a61654b3763ad65f52283832ebf058fdf1cslive variable is set by the authorization phases, which come
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>after</em> the URL translation phase (during which mod_rewrite
06ba4a61654b3763ad65f52283832ebf058fdf1cslive operates).</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>On the other hand, because mod_rewrite implements
06ba4a61654b3763ad65f52283832ebf058fdf1cslive its per-directory context (<code>.htaccess</code> file) via
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the Fixup phase of the API and because the authorization
06ba4a61654b3763ad65f52283832ebf058fdf1cslive phases come <em>before</em> this phase, you just can use
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{LA-F:variable}</code> can be used to perform an internal
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (filename-based) sub-request, to determine the final value
06ba4a61654b3763ad65f52283832ebf058fdf1cslive of <em>variable</em>. Most of the time, this is the same as
06ba4a61654b3763ad65f52283832ebf058fdf1cslive LA-U above.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive a regular expression which is applied to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>TestString</em> is first evaluated, before being matched against
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p><strong>Remember:</strong> <em>CondPattern</em> is a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive additions:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>You can prefix the pattern string with a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive '<code>!</code>' character (exclamation mark) to specify a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive There are some special variants of <em>CondPatterns</em>.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Instead of real regular expression strings you can also
06ba4a61654b3763ad65f52283832ebf058fdf1cslive use one of the following:
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>'<strong><CondPattern</strong>' (lexicographically
97a9a944b5887e91042b019776c41d5dd74557aferikabele precedes)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive compares it lexicographically to <em>TestString</em>. True if
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>'<strong>>CondPattern</strong>' (lexicographically
97a9a944b5887e91042b019776c41d5dd74557aferikabele follows)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive compares it lexicographically to <em>TestString</em>. True if
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>'<strong>=CondPattern</strong>' (lexicographically
06ba4a61654b3763ad65f52283832ebf058fdf1cslive equal)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive compares it lexicographically to <em>TestString</em>. True if
06ba4a61654b3763ad65f52283832ebf058fdf1cslive equal, character for character). If <em>CondPattern</em>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive compares <em>TestString</em> to the empty string.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Treats the <em>TestString</em> as a pathname and tests
06ba4a61654b3763ad65f52283832ebf058fdf1cslive whether or not it exists, and is a directory.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Treats the <em>TestString</em> as a pathname and tests
06ba4a61654b3763ad65f52283832ebf058fdf1cslive whether or not it exists, and is a regular file.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Treats the <em>TestString</em> as a pathname and tests
06ba4a61654b3763ad65f52283832ebf058fdf1cslive whether or not it exists, and is a regular file with size greater
4e3cdb85620921a8a120fe22edbccae708f4f34end than zero.</li>
4e3cdb85620921a8a120fe22edbccae708f4f34end whether or not it exists, and is a symbolic link.</li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele <li>'<strong>-x</strong>' (has e<strong>x</strong>ecutable
06ba4a61654b3763ad65f52283832ebf058fdf1cslive permissions)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Treats the <em>TestString</em> as a pathname and tests
06ba4a61654b3763ad65f52283832ebf058fdf1cslive whether or not it exists, and has executable permissions.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive These permissions are determined according to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the underlying OS.</li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele subrequest)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Checks whether or not <em>TestString</em> is a valid file,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive accessible via all the server's currently-configured
06ba4a61654b3763ad65f52283832ebf058fdf1cslive access controls for that path. This uses an internal
06ba4a61654b3763ad65f52283832ebf058fdf1cslive subrequest to do the check, so use it with care -
06ba4a61654b3763ad65f52283832ebf058fdf1cslive it can impact your server's performance!</li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele subrequest)<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Checks whether or not <em>TestString</em> is a valid URL,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive accessible via all the server's currently-configured
06ba4a61654b3763ad65f52283832ebf058fdf1cslive access controls for that path. This uses an internal
97a9a944b5887e91042b019776c41d5dd74557aferikabele subrequest to do the check, so use it with care -
06ba4a61654b3763ad65f52283832ebf058fdf1cslive it can impact your server's performance!</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive All of these tests can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive also be prefixed by an exclamation mark ('!') to
97a9a944b5887e91042b019776c41d5dd74557aferikabele negate their meaning.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>You can also set special flags for
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <strong><code>[</code><em>flags</em><code>]</code></strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive directive, where <em>flags</em> is a comma-separated list of any of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive following flags:
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This makes the test case-insensitive - differences
06ba4a61654b3763ad65f52283832ebf058fdf1cslive between 'A-Z' and 'a-z' are ignored, both in the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive expanded <em>TestString</em> and the <em>CondPattern</em>.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This flag is effective only for comparisons between
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>TestString</em> and <em>CondPattern</em>. It has no
06ba4a61654b3763ad65f52283832ebf058fdf1cslive effect on filesystem and subrequest checks.</li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele Use this to combine rule conditions with a local OR
06ba4a61654b3763ad65f52283832ebf058fdf1cslive instead of the implicit AND. Typical example:
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteCond %{REMOTE_HOST} ^host1.* [OR]
97a9a944b5887e91042b019776c41d5dd74557aferikabeleRewriteCond %{REMOTE_HOST} ^host2.* [OR]
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteCond %{REMOTE_HOST} ^host3.*
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteRule ...some special stuff for any of these hosts...
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Without this flag you would have to write the condition/rule
06ba4a61654b3763ad65f52283832ebf058fdf1cslive pair three times.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive If a HTTP header is used in the condition, this flag prevents
06ba4a61654b3763ad65f52283832ebf058fdf1cslive this header from being added to the Vary header of the response. <br />
97a9a944b5887e91042b019776c41d5dd74557aferikabele Using this flag might break proper caching of the response if
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the representation of this response varies on the value of this header.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive So this flag should be only used if the meaning of the Vary header
06ba4a61654b3763ad65f52283832ebf058fdf1cslive is well understood.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>To rewrite the Homepage of a site according to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive ``<code>User-Agent:</code>'' header of the request, you can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive use the following: </p>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteCond %{HTTP_USER_AGENT} ^Mozilla.*
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteRule ^/$ /homepage.max.html [L]
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4ndRewriteCond %{HTTP_USER_AGENT} ^Lynx.*
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4ndRewriteRule ^/$ /homepage.min.html [L]
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4ndRewriteRule ^/$ /homepage.std.html [L]
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>Explanation: If you use a browser which identifies itself
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd as 'Mozilla' (including Netscape Navigator, Mozilla etc), then you
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd get the max homepage (which could include frames, or other special
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd features).
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd If you use the Lynx browser (which is terminal-based), then
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd you get the min homepage (which could be a version designed for
06ba4a61654b3763ad65f52283832ebf058fdf1cslive easy, text-only browsing).
06ba4a61654b3763ad65f52283832ebf058fdf1cslive If neither of these conditions apply (you use any other browser,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive or your browser identifies itself as something non-standard), you get
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the std (standard) homepage.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<div class="directive-section"><h2><a name="RewriteEngine" id="RewriteEngine">RewriteEngine</a> <a name="rewriteengine" id="rewriteengine">Directive</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Enables or disables runtime rewriting engine</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteEngine on|off</code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteEngine off</code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
627c978514c54179736d152923478be7c8707f9bnd <p>The <code class="directive">RewriteEngine</code> directive enables or
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd disables the runtime rewriting engine. If it is set to
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <code>off</code> this module does no runtime processing at
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd environment variables.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>Use this directive to disable the module instead of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive commenting out all the <code class="directive"><a href="#rewriterule">RewriteRule</a></code> directives!</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Note that rewrite configurations are not
06ba4a61654b3763ad65f52283832ebf058fdf1cslive inherited by virtual hosts. This means that you need to have a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>RewriteEngine on</code> directive for each virtual host
06ba4a61654b3763ad65f52283832ebf058fdf1cslive in which you wish to use rewrite rules.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p><code class="directive">RewriteMap</code> directives of the type <code>prg</code>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd are not started during server initialization if they're defined in a
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd context that does not have <code class="directive">RewriteEngine</code> set to
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<div class="directive-section"><h2><a name="RewriteLock" id="RewriteLock">RewriteLock</a> <a name="rewritelock" id="rewritelock">Directive</a></h2>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the lock file used for <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLock <em>file-path</em></code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This directive sets the filename for a synchronization
06ba4a61654b3763ad65f52283832ebf058fdf1cslive lockfile which mod_rewrite needs to communicate with <code class="directive"><a href="#rewritemap">RewriteMap</a></code>
97a9a944b5887e91042b019776c41d5dd74557aferikabele <em>programs</em>. Set this lockfile to a local path (not on a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive NFS-mounted device) when you want to use a rewriting
06ba4a61654b3763ad65f52283832ebf058fdf1cslive map-program. It is not required for other types of rewriting
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="directive-section"><h2><a name="RewriteLog" id="RewriteLog">RewriteLog</a> <a name="rewritelog" id="rewritelog">Directive</a></h2>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the name of the file used for logging rewrite engine
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLog <em>file-path</em></code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <code class="directive">RewriteLog</code> directive sets the name
97a9a944b5887e91042b019776c41d5dd74557aferikabele of the file to which the server logs any rewriting actions it
06ba4a61654b3763ad65f52283832ebf058fdf1cslive performs. If the name does not begin with a slash
97a9a944b5887e91042b019776c41d5dd74557aferikabele ('<code>/</code>') then it is assumed to be relative to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>Server Root</em>. The directive should occur only once per
97a9a944b5887e91042b019776c41d5dd74557aferikabele server config.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd rewriting actions it is not recommended to set
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd although the rewriting engine does not then output to a
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd logfile it still creates the logfile output internally.
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <strong>This will slow down the server with no advantage
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd to the administrator!</strong> To disable logging either
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd remove or comment out the <code class="directive">RewriteLog</code>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveSee the <a href="/misc/security_tips.html">Apache Security Tips</a>
06ba4a61654b3763ad65f52283832ebf058fdf1cslivedocument for details on how your security could be compromised if the
06ba4a61654b3763ad65f52283832ebf058fdf1cslivedirectory where logfiles are stored is writable by anyone other than
06ba4a61654b3763ad65f52283832ebf058fdf1cslivethe user that starts the server.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<div class="directive-section"><h2><a name="RewriteLogLevel" id="RewriteLogLevel">RewriteLogLevel</a> <a name="rewriteloglevel" id="rewriteloglevel">Directive</a></h2>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets the verbosity of the log file used by the rewrite
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteLogLevel <em>Level</em></code></td></tr>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Default">Default:</a></th><td><code>RewriteLogLevel 0</code></td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>The <code class="directive">RewriteLogLevel</code> directive sets the
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd verbosity level of the rewriting logfile. The default level 0
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd means no logging, while 9 or more means that practically all
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd actions are logged.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>To disable the logging of rewriting actions simply set
06ba4a61654b3763ad65f52283832ebf058fdf1cslive dramatically! Use the rewriting logfile at a
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteLogLevel 3
97a9a944b5887e91042b019776c41d5dd74557aferikabele<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="directive-section"><h2><a name="RewriteMap" id="RewriteMap">RewriteMap</a> <a name="rewritemap" id="rewritemap">Directive</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines a mapping function for key-lookup</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteMap <em>MapName</em> <em>MapType</em>:<em>MapSource</em>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td>The choice of different dbm types is available in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <code class="directive">RewriteMap</code> directive defines a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive substitution strings by the mapping-functions to
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen insert/substitute fields through a key lookup. The source of
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen this lookup can be of various types.</p>
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen <p>The <a id="mapfunc" name="mapfunc"><em>MapName</em></a> is
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen the name of the map and will be used to specify a
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen mapping-function for the substitution strings of a rewriting
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen rule via one of the following constructs:</p>
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen <strong><code>${</code> <em>MapName</em> <code>:</code>
0ccb6ee166750359937ae35d59c0beb54f8fd228rbowen <em>LookupKey</em> <code>|</code> <em>DefaultValue</em>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>When such a construct occurs, the map <em>MapName</em> is
06ba4a61654b3763ad65f52283832ebf058fdf1cslive consulted and the key <em>LookupKey</em> is looked-up. If the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive key is found, the map-function construct is substituted by
97a9a944b5887e91042b019776c41d5dd74557aferikabele <em>SubstValue</em>. If the key is not found then it is
06ba4a61654b3763ad65f52283832ebf058fdf1cslive substituted by <em>DefaultValue</em> or by the empty string
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>For example, you might define a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>You would then be able to use this map in a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="directive">RewriteRule</code> as follows:</p>
97a9a944b5887e91042b019776c41d5dd74557aferikabele RewriteRule ^/ex/(.*) ${examplemap:$1}
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The following combinations for <em>MapType</em> and
97a9a944b5887e91042b019776c41d5dd74557aferikabele MapType: <code>txt</code>, MapSource: Unix filesystem
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path to valid regular file
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This is the standard rewriting map feature where the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive either blank lines, comment lines (starting with a '#'
97a9a944b5887e91042b019776c41d5dd74557aferikabele character) or pairs like the following - one per
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen## map.txt -- rewriting map
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowenRalf.S.Engelschall rse # Bastard Operator From Hell
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowenMr.Joe.Average joe # Mr. Average
97a9a944b5887e91042b019776c41d5dd74557aferikabele MapType: <code>rnd</code>, MapSource: Unix filesystem
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path to valid regular file
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen <p>This is identical to the Standard Plain Text variant
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen above but with a special post-processing feature: After
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen looking up a value it is parsed according to contained
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen ``<code>|</code>'' characters which have the meaning of
36088d24dae5b2cc8124264fc6a9ba349ba81adcrbowen ``or''. In other words they indicate a set of
97a9a944b5887e91042b019776c41d5dd74557aferikabele alternatives from which the actual returned value is
06ba4a61654b3763ad65f52283832ebf058fdf1cslive chosen randomly. For example, you might use the following map
06ba4a61654b3763ad65f52283832ebf058fdf1cslive file and directives to provide a random load balancing between
06ba4a61654b3763ad65f52283832ebf058fdf1cslive several back-end server, via a reverse-proxy. Images are sent
97a9a944b5887e91042b019776c41d5dd74557aferikabele to one of the servers in the 'static' pool, while everything
1578daeec017d3bb20cecdcdc3b0261c999730d5slive else is sent to one of the 'dynamic' pool.</p>
1578daeec017d3bb20cecdcdc3b0261c999730d5slive## map.txt -- rewriting map
ab6f5669a4cb16dbff7d791d434ba1b9c9b50928ndstatic www1|www2|www3|www4
1578daeec017d3bb20cecdcdc3b0261c999730d5slivedynamic www5|www6
1578daeec017d3bb20cecdcdc3b0261c999730d5slive<div class="example"><h3>Configuration directives</h3><p><code>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteRule ^/(.*\.(png|gif|jpg)) http://${servers:static}/$1
06ba4a61654b3763ad65f52283832ebf058fdf1cslive[NC,P,L]<br />
06ba4a61654b3763ad65f52283832ebf058fdf1csliveRewriteRule ^/(.*) http://${servers:dynamic}/$1 [P,L]
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>dbm[=<em>type</em>]</code>, MapSource: Unix filesystem
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path to valid regular file
97a9a944b5887e91042b019776c41d5dd74557aferikabele <p>Here the source is a binary format DBM file containing
97a9a944b5887e91042b019776c41d5dd74557aferikabele the same contents as a <em>Plain Text</em> format file, but
06ba4a61654b3763ad65f52283832ebf058fdf1cslive in a special representation which is optimized for really
06ba4a61654b3763ad65f52283832ebf058fdf1cslive fast lookups. The <em>type</em> can be sdbm, gdbm, ndbm, or
06ba4a61654b3763ad65f52283832ebf058fdf1cslive db depending on <a href="/install.html#dbm">compile-time
06ba4a61654b3763ad65f52283832ebf058fdf1cslive compile-time default will be chosen.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>To create a dbm file from a source text file, use the <a href="/programs/httxt2dbm.html">httxt2dbm</a> utility.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Here, the source is an internal Apache function.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Currently you cannot create your own, but the following
06ba4a61654b3763ad65f52283832ebf058fdf1cslive functions already exist:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Converts the key to all upper case.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Converts the key to all lower case.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Translates special characters in the key to
97a9a944b5887e91042b019776c41d5dd74557aferikabele hex-encodings.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Translates hex-encodings in the key back to
97a9a944b5887e91042b019776c41d5dd74557aferikabele special characters.</li>
97a9a944b5887e91042b019776c41d5dd74557aferikabele path to valid regular file
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Here the source is a program, not a map file. To
06ba4a61654b3763ad65f52283832ebf058fdf1cslive create it you can use a language of your choice, but
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the result has to be an executable program (either
06ba4a61654b3763ad65f52283832ebf058fdf1cslive object-code or a script with the magic cookie trick
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This program is started once, when the Apache server
06ba4a61654b3763ad65f52283832ebf058fdf1cslive is started, and then communicates with the rewriting engine
06ba4a61654b3763ad65f52283832ebf058fdf1cslive file-handles. For each map-function lookup it will
06ba4a61654b3763ad65f52283832ebf058fdf1cslive receive the key to lookup as a newline-terminated string
06ba4a61654b3763ad65f52283832ebf058fdf1cslive looked-up value as a newline-terminated string on
06ba4a61654b3763ad65f52283832ebf058fdf1cslive ``<code>NULL</code>'' if it fails (<em>i.e.</em>, there
06ba4a61654b3763ad65f52283832ebf058fdf1cslive is no corresponding value for the given key). A trivial
06ba4a61654b3763ad65f52283832ebf058fdf1cslive program which will implement a 1:1 map (<em>i.e.</em>,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive key == value) could be:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>External rewriting programs are not started if they're defined in a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive context that does not have <code class="directive">RewriteEngine</code> set to
06ba4a61654b3763ad65f52283832ebf058fdf1cslivewhile (<STDIN>) {
06ba4a61654b3763ad65f52283832ebf058fdf1cslive # ...put here any transformations or lookups...
06ba4a61654b3763ad65f52283832ebf058fdf1cslive If this program hangs, it will cause Apache to hang
06ba4a61654b3763ad65f52283832ebf058fdf1cslive when trying to use the relevant rewrite rule.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>A common mistake is to use buffered I/O on
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>stdout</code>. Avoid this, as it will cause a deadloop!
97a9a944b5887e91042b019776c41d5dd74557aferikabele ``<code>$|=1</code>'' is used above, to prevent this.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>The <code class="directive"><a href="#rewritelock">RewriteLock</a></code> directive can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive be used to define a lockfile which mod_rewrite can use to synchronize
06ba4a61654b3763ad65f52283832ebf058fdf1cslive communication with the mapping program. By default no such
06ba4a61654b3763ad65f52283832ebf058fdf1cslive synchronization takes place.</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive MapSource: An SQL SELECT statement that takes a single
06ba4a61654b3763ad65f52283832ebf058fdf1cslive argument and returns a single value.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This uses <code class="module"><a href="/mod/mod_dbd.html">mod_dbd</a></code> to implement a rewritemap
97a9a944b5887e91042b019776c41d5dd74557aferikabele by lookup in an SQL database. There are two forms:
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>fastdbd</code> caches database lookups internally,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>dbd</code> doesn't. So <code>dbd</code> incurs a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive performance penalty but responds immediately if the database
06ba4a61654b3763ad65f52283832ebf058fdf1cslive contents are updated, while <code>fastdbd</code> is more
06ba4a61654b3763ad65f52283832ebf058fdf1cslive efficient but won't re-read database contents until server
97a9a944b5887e91042b019776c41d5dd74557aferikabele restart.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>If a query returns more than one row, a random row from
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd the result set is used.</p>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4ndRewriteMap myquery "fastdbd:SELECT destination FROM rewrite WHERE source = %s"
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>The <code class="directive">RewriteMap</code> directive can occur more than
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd once. For each mapping-function use one
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <code class="directive">RewriteMap</code> directive to declare its rewriting
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd mapfile. While you cannot <strong>declare</strong> a map in
844def494f17cb1ab0983427d5c3939e1a03ff8cnd per-directory context it is of course possible to
0203b896e484dfb877111aceffb812401d0f216and <strong>use</strong> this map in per-directory context. </p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="note"><h3>Note</h3> For plain text and DBM format files the
06ba4a61654b3763ad65f52283832ebf058fdf1cslivelooked-up keys are cached in-core until the <code>mtime</code> of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslivemapfile changes or the server does a restart. This way you can have
844def494f17cb1ab0983427d5c3939e1a03ff8cndmap-functions in rules which are used for <strong>every</strong>
06ba4a61654b3763ad65f52283832ebf058fdf1csliverequest. This is no problem, because the external lookup only happens
0203b896e484dfb877111aceffb812401d0f216and<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
0203b896e484dfb877111aceffb812401d0f216and<div class="directive-section"><h2><a name="RewriteOptions" id="RewriteOptions">RewriteOptions</a> <a name="rewriteoptions" id="rewriteoptions">Directive</a></h2>
0203b896e484dfb877111aceffb812401d0f216and<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Sets some special options for the rewrite engine</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteOptions <var>Options</var></code></td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd<tr><th><a href="directive-dict.html#Compatibility">Compatibility:</a></th><td><code>MaxRedirects</code> is no longer available in version 2.1 and
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd <p>The <code class="directive">RewriteOptions</code> directive sets some
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd special options for the current per-server or per-directory
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd only be one of the following:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>This forces the current configuration to inherit the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive configuration of the parent. In per-virtual-server context,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive this means that the maps, conditions and rules of the main
06ba4a61654b3763ad65f52283832ebf058fdf1cslive server are inherited. In per-directory context this means
06ba4a61654b3763ad65f52283832ebf058fdf1cslive that conditions and rules of the parent directory's
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="top"><a href="#page-header"><img alt="top" src="/images/up.gif" /></a></div>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<div class="directive-section"><h2><a name="RewriteRule" id="RewriteRule">RewriteRule</a> <a name="rewriterule" id="rewriterule">Directive</a></h2>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Description">Description:</a></th><td>Defines rules for the rewriting engine</td></tr>
d1348237b33bc1755b9f1165eea52317465a7671nd<tr><th><a href="directive-dict.html#Syntax">Syntax:</a></th><td><code>RewriteRule
d1348237b33bc1755b9f1165eea52317465a7671nd <em>Pattern</em> <em>Substitution</em> [<em>flags</em>]</code></td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Context">Context:</a></th><td>server config, virtual host, directory, .htaccess</td></tr>
97a9a944b5887e91042b019776c41d5dd74557aferikabele<tr><th><a href="directive-dict.html#Override">Override:</a></th><td>FileInfo</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Status">Status:</a></th><td>Extension</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<tr><th><a href="directive-dict.html#Module">Module:</a></th><td>mod_rewrite</td></tr>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <code class="directive">RewriteRule</code> directive is the real
06ba4a61654b3763ad65f52283832ebf058fdf1cslive rewriting workhorse. The directive can occur more than once,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive with each instance defining a single rewrite rule. The
06ba4a61654b3763ad65f52283832ebf058fdf1cslive order in which these rules are defined is important - this is the order
06ba4a61654b3763ad65f52283832ebf058fdf1cslive in which they will be applied at run-time.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p><a id="patterns" name="patterns"><em>Pattern</em></a> is
06ba4a61654b3763ad65f52283832ebf058fdf1cslive a perl compatible <a id="regexp" name="regexp">regular
06ba4a61654b3763ad65f52283832ebf058fdf1cslive expression</a>. On the first RewriteRule it is applied to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <a href="/directive-dict.html#Syntax">URL-path</a> of the request;
06ba4a61654b3763ad65f52283832ebf058fdf1cslive subsequent patterns are applied to the output of the last matched
06ba4a61654b3763ad65f52283832ebf058fdf1cslive RewriteRule.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <em>Pattern</em> will initially be matched against the part of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive URL after the hostname and port, and before the query string. If you wish
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to match against the hostname, port, or query string, use a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="directive"><a href="#rewritecond">RewriteCond</a></code> with the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{HTTP_HOST}</code>, <code>%{SERVER_PORT}</code>, or
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%{QUERY_STRING}</code> variables respectively.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>For some hints on <a class="glossarylink" href="/glossary.html#regex" title="see glossary">regular
630c456b6461158be6cc5c5483735e27b13b4ad5nd expressions</a>, see
630c456b6461158be6cc5c5483735e27b13b4ad5nd the <a href="/rewrite/rewrite_intro.html#regex">mod_rewrite
630c456b6461158be6cc5c5483735e27b13b4ad5nd <p>In mod_rewrite, the NOT character
06ba4a61654b3763ad65f52283832ebf058fdf1cslive ('<code>!</code>') is also available as a possible pattern
06ba4a61654b3763ad65f52283832ebf058fdf1cslive prefix. This enables you to negate a pattern; to say, for instance:
97a9a944b5887e91042b019776c41d5dd74557aferikabele ``<em>if the current URL does <strong>NOT</strong> match this
edc8d9e0cce625a77afd1ff87a8f955694a973e2rbowen pattern</em>''. This can be used for exceptional cases, where
97a9a944b5887e91042b019776c41d5dd74557aferikabele it is easier to match the negative pattern, or as a last
edc8d9e0cce625a77afd1ff87a8f955694a973e2rbowen default rule.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveWhen using the NOT character to negate a pattern, you cannot include
06ba4a61654b3763ad65f52283832ebf058fdf1cslivegrouped wildcard parts in that pattern. This is because, when the
06ba4a61654b3763ad65f52283832ebf058fdf1cslivepattern does NOT match (ie, the negation matches), there are no
06ba4a61654b3763ad65f52283832ebf058fdf1cslivecontents for the groups. Thus, if negated patterns are used, you
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>The <a id="rhs" name="rhs"><em>Substitution</em></a> of a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive rewrite rule is the string that replaces the original URL-path that
97a9a944b5887e91042b019776c41d5dd74557aferikabele was matched by <em>Pattern</em>. The <em>Substitution</em> may
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>Designates the location on the file-system of the resource
97a9a944b5887e91042b019776c41d5dd74557aferikabele to be delivered to the client.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>A <code class="directive"><a href="/mod/core.html#documentroot">DocumentRoot</a></code>-relative path to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive resource to be served. Note that <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive tries to guess whether you have specified a file-system path
06ba4a61654b3763ad65f52283832ebf058fdf1cslive or a URL-path by checking to see if the first segment of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive path exists at the root of the file-system. For example, if
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>/www/file.html</code>, then this will be treated as a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive URL-path <em>unless</em> a directory named <code>www</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive exists at the root or your file-system, in which case it will
06ba4a61654b3763ad65f52283832ebf058fdf1cslive be treated as a file-system path. If you wish other
06ba4a61654b3763ad65f52283832ebf058fdf1cslive URL-mapping directives (such as <code class="directive"><a href="/mod/mod_alias.html#alias">Alias</a></code>) to be applied to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive described below.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>If an absolute URL is specified,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code> checks to see whether the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive hostname matches the current host. If it does, the scheme and
06ba4a61654b3763ad65f52283832ebf058fdf1cslive hostname are stripped out and the resulting path is treated as
06ba4a61654b3763ad65f52283832ebf058fdf1cslive a URL-path. Otherwise, an external redirect is performed for
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the given URL. To force an external redirect back to the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive current host, see the <code>[R]</code> flag below.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <dd>A dash indicates that no substitution should be performed
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (the existing path is passed through untouched). This is used
06ba4a61654b3763ad65f52283832ebf058fdf1cslive when a flag (see below) needs to be applied without changing
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the path.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>In addition to plain text, the <em>Substition</em> string can include</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>back-references (<code>$N</code>) to the RewriteRule
06ba4a61654b3763ad65f52283832ebf058fdf1cslive pattern</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>back-references (<code>%N</code>) to the last matched
06ba4a61654b3763ad65f52283832ebf058fdf1cslive RewriteCond pattern</li>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <li>server-variables as in rule condition test-strings
70373b9ee042e7b3be82eee14b17f510fffdacc9slive <p>Back-references are identifiers of the form
70373b9ee042e7b3be82eee14b17f510fffdacc9slive by the contents of the <strong>N</strong>th group of the
70373b9ee042e7b3be82eee14b17f510fffdacc9slive matched <em>Pattern</em>. The server-variables are the same
70373b9ee042e7b3be82eee14b17f510fffdacc9slive as for the <em>TestString</em> of a <code>RewriteCond</code>
70373b9ee042e7b3be82eee14b17f510fffdacc9slive directive. The mapping-functions come from the
70373b9ee042e7b3be82eee14b17f510fffdacc9slive <code>RewriteMap</code> directive and are explained there.
70373b9ee042e7b3be82eee14b17f510fffdacc9slive These three types of variables are expanded in the order above.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>As already mentioned, all rewrite rules are
06ba4a61654b3763ad65f52283832ebf058fdf1cslive applied to the <em>Substitution</em> (in the order in which
06ba4a61654b3763ad65f52283832ebf058fdf1cslive they are defined
06ba4a61654b3763ad65f52283832ebf058fdf1cslive in the config file). The URL is <strong>completely
06ba4a61654b3763ad65f52283832ebf058fdf1cslive replaced</strong> by the <em>Substitution</em> and the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive rewriting process continues until all rules have been applied,
70373b9ee042e7b3be82eee14b17f510fffdacc9slive or it is explicitly terminated by a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>By default, the query string is passed through unchanged. You
06ba4a61654b3763ad65f52283832ebf058fdf1cslive can, however, create URLs in the substitution string containing
70373b9ee042e7b3be82eee14b17f510fffdacc9slive a query string part. Simply use a question mark inside the
97a9a944b5887e91042b019776c41d5dd74557aferikabele substitution string to indicate that the following text should
06ba4a61654b3763ad65f52283832ebf058fdf1cslive be re-injected into the query string. When you want to erase an
21f4ac5ab80abe4cbe90ae0f340c29053556c52drbowen existing query string, end the substitution string with just a
21f4ac5ab80abe4cbe90ae0f340c29053556c52drbowen question mark. To combine new and old query strings, use the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Additionally you can set special <a name="rewriteflags" id="rewriteflags">actions</a> to be performed by
06ba4a61654b3763ad65f52283832ebf058fdf1cslive appending <strong><code>[</code><em>flags</em><code>]</code></strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive directive. <em>Flags</em> is a comma-separated list, surround by square
06ba4a61654b3763ad65f52283832ebf058fdf1cslive brackets, of any of the following flags: </p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <dd><p>Apache has to unescape URLs before mapping them,
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen so backreferences will be unescaped at the time they are applied.
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen Using the B flag, non-alphanumeric characters in backreferences
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen will be escaped. For example, consider the rule:</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <pre><code> RewriteRule ^(.*)$ index.php?show=$1 </code></pre>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>This will map <code>/C++</code> to <code>index.php?show=/C++</code>.
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code>index.php?show=/C++</code>, because the <code>%2b</code>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen has been unescaped. With the B flag, it will instead map to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>This escaping is particularly necessary in a proxy situation,
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen when the backend may break if presented with an unescaped URL.</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen This flag chains the current rule with the next rule
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen (which itself can be chained with the following rule,
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen and so on). This has the following effect: if a rule
06ba4a61654b3763ad65f52283832ebf058fdf1cslive matches, then processing continues as usual -
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen the flag has no effect. If the rule does
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <strong>not</strong> match, then all following chained
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rules are skipped. For instance, it can be used to remove the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen ``<code>.www</code>'' part, inside a per-directory rule set,
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen when you let an external redirect happen (where the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <dt>'<code>cookie|CO=</code><em>NAME</em>:<em>VAL</em>:<em>domain</em>[:<em>lifetime</em>[:<em>path</em>[:<em>secure</em>[:<em>httponly</em>]]]]'
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen This sets a cookie in the client's browser. The cookie's name
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <em>VAL</em>. The <em>domain</em> field is the domain of the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen cookie, such as '.apache.org', the optional <em>lifetime</em>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen is the lifetime of the cookie in minutes (0 means expires at end
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen of session), and the optional
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>path</em> is the path of the cookie. If <em>secure</em>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive is set to 'secure', 'true' or '1', the cookie is only transmitted via secured
97a9a944b5887e91042b019776c41d5dd74557aferikabele connections. If <em>httponly</em> is set to 'HttpOnly', 'true' or '1', the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>HttpOnly</code> flag is used, making the cookie inaccessible
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to JavaScript code on browsers that support this feature.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This forces an environment variable named <em>VAR</em> to
97a9a944b5887e91042b019776c41d5dd74557aferikabele be set to the value <em>VAL</em>, where <em>VAL</em> can
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>%N</code>) which will be expanded. You can use this
06ba4a61654b3763ad65f52283832ebf058fdf1cslive flag more than once, to set more than one variable. The
06ba4a61654b3763ad65f52283832ebf058fdf1cslive variables can later be dereferenced in many situations, most commonly
06ba4a61654b3763ad65f52283832ebf058fdf1cslive from within XSSI (via <code><!--#echo
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen var="VAR"--></code>) or CGI (<code>$ENV{'VAR'}</code>).
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen You can also dereference the variable in a later RewriteCond pattern, using
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen information from URLs, while maintaining a record of that information.</dd>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen This forces the current URL to be forbidden - it immediately
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sends back a HTTP response of 403 (FORBIDDEN).
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Use this flag in conjunction with
97a9a944b5887e91042b019776c41d5dd74557aferikabele appropriate RewriteConds to conditionally block some
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This forces the current URL to be gone - it
06ba4a61654b3763ad65f52283832ebf058fdf1cslive immediately sends back a HTTP response of 410 (GONE). Use
06ba4a61654b3763ad65f52283832ebf058fdf1cslive this flag to mark pages which no longer exist as gone.</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Force the Content-handler of the target file to be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <em>Content-handler</em>. For instance, this can be used to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive simulate the <code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code> directive
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="directive"><a href="/mod/mod_alias.html#scriptalias">ScriptAlias</a></code>,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive which internally forces all files
06ba4a61654b3763ad65f52283832ebf058fdf1cslive inside the mapped directory to have a handler of
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen here and don't apply any more rewrite rules. This corresponds
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code>break</code> command in C. Use this flag to prevent the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen currently rewritten URL from being rewritten further by
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen following rules. Remember, however, that if the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code class="directive">RewriteRule</code> generates an internal
06ba4a61654b3763ad65f52283832ebf058fdf1cslive redirect (which frequently occurs when rewriting in a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive per-directory context), this will reinject the request and
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen will cause processing to be repeated starting from the first
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen Re-run the rewriting process (starting again with the
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen first rewriting rule). This time, the URL to match is no longer
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen the original URL, but rather the URL returned by the last rewriting rule.
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen This corresponds to the Perl <code>next</code> command or
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen this flag to restart the rewriting process -
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen to immediately go to the top of the loop.
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <strong>Be careful not to create an infinite
06ba4a61654b3763ad65f52283832ebf058fdf1cslive ignoring difference between 'A-Z' and
06ba4a61654b3763ad65f52283832ebf058fdf1cslive 'a-z' when <em>Pattern</em> is matched against the current
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (no URI escaping of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This flag prevents mod_rewrite from applying the usual URI
06ba4a61654b3763ad65f52283832ebf058fdf1cslive escaping rules to the result of a rewrite. Ordinarily,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive special characters (such as '%', '$', ';', and so on)
06ba4a61654b3763ad65f52283832ebf058fdf1cslive will be escaped into their hexcode equivalents ('%25',
97a9a944b5887e91042b019776c41d5dd74557aferikabele '%24', and '%3B', respectively); this flag prevents this
06ba4a61654b3763ad65f52283832ebf058fdf1cslive from happening. This allows percent symbols to appear in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the output, as in
06ba4a61654b3763ad65f52283832ebf058fdf1cslive RewriteRule /foo/(.*) /bar?arg=P1\%3d$1 [R,NE]
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen (not for internal
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>This flag forces the rewriting engine to skip a
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rewriting rule if the current request is an internal
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen sub-request. For instance, sub-requests occur internally
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen in Apache when <code class="module"><a href="/mod/mod_include.html">mod_include</a></code> tries to find out
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen information about possible directory default files
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen (<code>index.xxx</code> files). On sub-requests it is not
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen always useful, and can even cause errors, if
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen the complete set of rules are applied. Use this flag to
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen exclude some rules.</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>To decide whether or not to use this rule: if you
06ba4a61654b3763ad65f52283832ebf058fdf1cslive prefix URLs with CGI-scripts, to force them to be
9b82bd7c7f2083318e7856831dede324534308bcrbowen processed by the CGI-script, it's likely that you
9b82bd7c7f2083318e7856831dede324534308bcrbowen will run into problems (or significant overhead) on
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sub-requests. In these cases, use this flag.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This flag forces the substitution part to be internally
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sent as a proxy request and immediately (rewrite
06ba4a61654b3763ad65f52283832ebf058fdf1cslive processing stops here) put through the <a href="mod_proxy.html">proxy module</a>. You must make
06ba4a61654b3763ad65f52283832ebf058fdf1cslive sure that the substitution string is a valid URI
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (typically starting with
06ba4a61654b3763ad65f52283832ebf058fdf1cslive handled by the Apache proxy module. If not, you will get an
06ba4a61654b3763ad65f52283832ebf058fdf1cslive error from the proxy module. Use this flag to achieve a
06ba4a61654b3763ad65f52283832ebf058fdf1cslive more powerful implementation of the <a href="mod_proxy.html#proxypass">ProxyPass</a> directive,
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to map remote content into the namespace of the local
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Note: <code class="module"><a href="/mod/mod_proxy.html">mod_proxy</a></code> must be enabled in order
06ba4a61654b3763ad65f52283832ebf058fdf1cslive to use this flag.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (pass through to next
06ba4a61654b3763ad65f52283832ebf058fdf1cslive This flag forces the rewrite engine to set the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>request_rec</code> structure to the value of the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>filename</code> field. This flag is just a hack to
06ba4a61654b3763ad65f52283832ebf058fdf1cslive enable post-processing of the output of
06ba4a61654b3763ad65f52283832ebf058fdf1cslive various URI-to-filename translators. For example, to rewrite
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>, and then
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code>:
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen RewriteRule ^/abc(.*) /def$1 [PT]<br />
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen Alias /def /ghi
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code>filename=/def/...</code> as a full API-compliant
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen URI-to-filename translator should do. Then
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen URI-to-filename transition, which will fail.
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>Note: <strong>You must use this flag if you want to
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen mix directives from different modules which allow
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen URL-to-filename translators</strong>. The typical example
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen is the use of <code class="module"><a href="/mod/mod_alias.html">mod_alias</a></code> and
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code class="module"><a href="/mod/mod_rewrite.html">mod_rewrite</a></code>.</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>The <code>PT</code> flag implies the <code>L</code> flag:
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rewriting will be stopped in order to pass the request to
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen the next phase of processing.</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen (query string
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen This flag forces the rewrite engine to append a query
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen string part of the substitution string to the existing string,
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen instead of replacing it. Use this when you want to add more
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen data to the query string via a rewrite rule.</dd>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen [=<em>code</em>]' (force <a id="redirect" name="redirect">redirect</a>)</dt><dd>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code>http://thishost[:thisport]/</code> (which makes the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive new URL a URI) to force a external redirection. If no
97a9a944b5887e91042b019776c41d5dd74557aferikabele <em>code</em> is given, a HTTP response of 302 (MOVED
06ba4a61654b3763ad65f52283832ebf058fdf1cslive TEMPORARILY) will be returned. If you want to use other
06ba4a61654b3763ad65f52283832ebf058fdf1cslive response codes, simply specify the appropriate number or use
06ba4a61654b3763ad65f52283832ebf058fdf1cslive one of the following symbolic names: <code>temp</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>seeother</code>. Use this for rules to canonicalize
06ba4a61654b3763ad65f52283832ebf058fdf1cslive the URL and return it to the client - to translate
06ba4a61654b3763ad65f52283832ebf058fdf1cslive ``<code>/~</code>'' into ``<code>/u/</code>'', or to always
06ba4a61654b3763ad65f52283832ebf058fdf1cslive append a slash to <code>/u/</code><em>user</em>, etc.<br />
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <strong>Note:</strong> When you use this flag, make sure
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen that the substitution field is a valid URL! Otherwise, you
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen will be redirecting to an invalid location. Remember that
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen this flag on its own will only prepend
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <code>http://thishost[:thisport]/</code> to the URL, and
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rewriting will continue. Usually, you will want to stop
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rewriting at this point, and redirect immediately. To stop
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen rewriting, you should add the 'L' flag.</p>
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen <p>While this is typically used for redirects, any valid status
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen code can be given here. If the status code is outside the redirect
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen range (300-399), then the <em>Substitution</em> string is dropped
173a6aaf8f8d2c818ab71d3781400e521051a565rbowen and rewriting is stopped as if the <code>L</code> flag was
97a9a944b5887e91042b019776c41d5dd74557aferikabele This flag forces the rewriting engine to skip the next
06ba4a61654b3763ad65f52283832ebf058fdf1cslive matches. Use this to make pseudo if-then-else constructs:
06ba4a61654b3763ad65f52283832ebf058fdf1cslive The last rule of the then-clause becomes
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <code>skip=N</code>, where N is the number of rules in the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive else-clause. (This is <strong>not</strong> the same as the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive 'chain|C' flag!)</dd>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive Force the <a class="glossarylink" href="/glossary.html#mime-type" title="see glossary">MIME-type</a> of the target file to be
06ba4a61654b3763ad65f52283832ebf058fdf1cslive set up the content-type based on some conditions.
06ba4a61654b3763ad65f52283832ebf058fdf1cslive For example, the following snippet allows <code>.php</code> files to
97a9a944b5887e91042b019776c41d5dd74557aferikabele be <em>displayed</em> by <code>mod_php</code> if they are called with
06ba4a61654b3763ad65f52283832ebf058fdf1cslive RewriteRule ^(.+\.php)s$ $1 [T=application/x-httpd-php-source]
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p> When the substitution string begins with a string
06ba4a61654b3763ad65f52283832ebf058fdf1csliveresembling "/~user" (via explicit text or backreferences), mod_rewrite performs
97a9a944b5887e91042b019776c41d5dd74557aferikabelehome directory expansion independent of the presence or configuration
06ba4a61654b3763ad65f52283832ebf058fdf1csliveof <code class="module"><a href="/mod/mod_userdir.html">mod_userdir</a></code>.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1csliveflag is used on the <code class="directive"><a href="#rewriterule">RewriteRule</a></code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslivedirective.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>The rewrite engine may be used in <a href="/howto/htaccess.html">.htaccess</a> files. To enable the
97a9a944b5887e91042b019776c41d5dd74557aferikabelerewrite engine for these files you need to set
06ba4a61654b3763ad65f52283832ebf058fdf1cslive"<code>Options FollowSymLinks</code>" must be enabled. If your
06ba4a61654b3763ad65f52283832ebf058fdf1csliveadministrator has disabled override of <code>FollowSymLinks</code> for
06ba4a61654b3763ad65f52283832ebf058fdf1cslivea user's directory, then you cannot use the rewrite engine. This
06ba4a61654b3763ad65f52283832ebf058fdf1csliverestriction is required for security reasons.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>When using the rewrite engine in <code>.htaccess</code> files the
06ba4a61654b3763ad65f52283832ebf058fdf1csliveper-directory prefix (which always is the same for a specific
06ba4a61654b3763ad65f52283832ebf058fdf1cslivedirectory) is automatically <em>removed</em> for the pattern matching
06ba4a61654b3763ad65f52283832ebf058fdf1csliveand automatically <em>added</em> after the substitution has been
06ba4a61654b3763ad65f52283832ebf058fdf1cslivedone. This feature is essential for many sorts of rewriting; without
06ba4a61654b3763ad65f52283832ebf058fdf1cslivethis, you would always have to match the parent directory, which is
06ba4a61654b3763ad65f52283832ebf058fdf1cslivenot always possible. There is one exception: If a substitution string
06ba4a61654b3763ad65f52283832ebf058fdf1cslivestarts with <code>http://</code>, then the directory prefix will
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<strong>not</strong> be added, and an external redirect (or proxy
06ba4a61654b3763ad65f52283832ebf058fdf1cslivethroughput, if using flag <strong>P</strong>) is forced. See the
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<code class="directive"><a href="#rewritebase">RewriteBase</a></code> directive for
06ba4a61654b3763ad65f52283832ebf058fdf1cslivemore information.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>The rewrite engine may also be used in <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> sections with the same
06ba4a61654b3763ad65f52283832ebf058fdf1csliveprefix-matching rules as would be applied to <code>.htaccess</code>
06ba4a61654b3763ad65f52283832ebf058fdf1cslivefiles. It is usually simpler, however, to avoid the prefix substitution
06ba4a61654b3763ad65f52283832ebf058fdf1cslivecomplication by putting the rewrite rules in the main server or
06ba4a61654b3763ad65f52283832ebf058fdf1cslivevirtual host context, rather than in a <code class="directive"><a href="/mod/core.html#directory"><Directory></a></code> section.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<p>Although rewrite rules are syntactically permitted in <code class="directive"><a href="/mod/core.html#location"><Location></a></code> sections, this
06ba4a61654b3763ad65f52283832ebf058fdf1csliveshould never be necessary and is unsupported.</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive <p>Here are all possible substitution combinations and their
97a9a944b5887e91042b019776c41d5dd74557aferikabele meanings:</p>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive for request ``<code>GET
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<strong>Given Rule</strong> <strong>Resulting Substitution</strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
97a9a944b5887e91042b019776c41d5dd74557aferikabele^/somepath(.*) otherpath$1 invalid, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) otherpath$1 [R] invalid, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) otherpath$1 [P] invalid, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) /otherpath$1 [P] doesn't make sense, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive (the [R] flag is redundant)
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^/somepath(.*) http://otherhost/otherpath$1 [P] http://otherhost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via internal proxy
97a9a944b5887e91042b019776c41d5dd74557aferikabele (<code>/physical/path/to/somepath/.htacccess</code>, with
06ba4a61654b3763ad65f52283832ebf058fdf1cslive for request ``<code>GET
06ba4a61654b3763ad65f52283832ebf058fdf1cslive<strong>Given Rule</strong> <strong>Resulting Substitution</strong>
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
97a9a944b5887e91042b019776c41d5dd74557aferikabele^localpath(.*) otherpath$1 /somepath/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^localpath(.*) otherpath$1 [R] http://thishost/somepath/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^localpath(.*) otherpath$1 [P] doesn't make sense, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^localpath(.*) /otherpath$1 [R] http://thishost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^localpath(.*) /otherpath$1 [P] doesn't make sense, not supported
06ba4a61654b3763ad65f52283832ebf058fdf1cslive---------------------------------------------- ----------------------------------
97a9a944b5887e91042b019776c41d5dd74557aferikabele^localpath(.*) http://thishost/otherpath$1 /otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive^localpath(.*) http://thishost/otherpath$1 [R] http://thishost/otherpath/pathinfo
06ba4a61654b3763ad65f52283832ebf058fdf1cslive via external redirection
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd^localpath(.*) http://thishost/otherpath$1 [P] doesn't make sense, not supported
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd---------------------------------------------- ----------------------------------
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd^localpath(.*) http://otherhost/otherpath$1 http://otherhost/otherpath/pathinfo
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd via external redirection
3b3b7fc78d1f5bfc2769903375050048ff41ff26nd^localpath(.*) http://otherhost/otherpath$1 [R] http://otherhost/otherpath/pathinfo
b95ae799514ad86a15610ad75808d7065e9847c9kess via external redirection
0c4abc32c00611fe1d52c9661f5cc79a3f74c6d4nd (the [R] flag is redundant)
<p><span>Available Languages: </span><a href="/en/mod/mod_rewrite.html" title="English"> en </a></p>
<p class="apache">Copyright 2008 The Apache Software Foundation.<br />Licensed under the <a href="http://www.apache.org/licenses/LICENSE-2.0">Apache License, Version 2.0</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>